comnum.Results#

class comnum.Results(items: Iterable[Mapping[str, Any]] = (), spec: Mapping[str, Any] | None = None)#

The results of a campaign: one dict per condition with condition, status, trials, wall_s and metrics ({name: {value, lo, hi, kind, count, total}}).

It is a list; spec keeps the specification of the campaign when it is known (comnum.run_spec() and comnum.Chain.run() return one).

Parameters:

  • items (list[dict]) – the conditions.

  • spec (dict | None) – the specification.

classmethod load(path: str | Path) → Results#

Read results written by save() (or the JSON report of a specification).

Parameters:

path (str | os.PathLike) – the file.

Returns:

the results and their specification.

Return type:

Results

plot(x: str, metric: str, *, by: str | None = None, ax: Axes | None = None, theory: Callable[..., Any] | None = None, **kwargs: Any) → Axes#

Plot a metric against a variable, one curve per value of by.

Parameters:

  • x (str) – the variable of the abscissa.

  • metric (str) – the metric.

  • by (str | None) – one curve per value of this variable.

  • ax (matplotlib.axes.Axes | None) – the axes (new ones by default).

  • theory (callable | None) – a closed form of x, drawn as a line.

  • **kwargs – passed to comnum.plot.curves().

Returns:

the axes.

Return type:

matplotlib.axes.Axes

profile(**condition: Any) → list[dict[str, Any]]#

Where the time goes, for a campaign run with profile=True.

Parameters:

**condition – average over the conditions with these values only.

Returns:

one row per block of the link, in order, with block, time_ms (the mean time per trial, averaged over the conditions) and share (of the time of the whole link, the last row, link); empty when the campaign was not profiled.

Return type:

list[dict]

Example

>>> import comnum
>>> from comnum import blocks as B
>>> link = comnum.Chain(tx=B.Source(n_symbols=256), ch=B.Awgn(snr_db=10.0))
>>> rows = link.run(stop={"max_trials": 2}, profile=True).profile()
>>> [r["block"] for r in rows], rows[-1]["share"]
(['tx', 'ch', 'link'], 1.0)
rows() → list[dict[str, Any]]#

One flat row per condition, with the columns of the CSV report.

Returns:

index, the variables, status, trials, wall_s, and for every metric m: m, m_lo, m_hi, m_count, m_total (the names of ConditionResult.row).

Return type:

list[dict]

save(path: str | Path) → Path#

Write the results, the specification and the version of comnum to a JSON file.

Parameters:

path (str | os.PathLike) – the file.

Returns:

the path written.

Return type:

pathlib.Path

series(x: str, metric: str, *, interval: bool = False, min_count: int = 0, **condition: Any) → tuple[ndarray, ...]#

A metric against a variable, for the conditions that match condition.

Parameters:

  • x (str) – the variable of the abscissa.

  • metric (str) – the metric.

  • interval (bool) – also return the bounds of the confidence intervals.

  • min_count (int) – values of fewer errors (or values) are NaN.

  • **condition – the values of the other variables.

Returns:

(x, value), or (x, value, lo, hi) with interval.

Return type:

tuple[numpy.ndarray, …]

Raises:

  • KeyError – for a variable or a metric that no condition has.

  • ValueError – when a value of x repeats: the selection holds several curves (fix the other variables with condition).

Example

>>> import comnum
>>> res = comnum.Results([
...     {"condition": {"snr_db": 0.0}, "metrics": {"ser": {"value": 0.1, "lo": 0.09, "hi": 0.11, "count": 10}}},
...     {"condition": {"snr_db": 5.0}, "metrics": {"ser": {"value": 0.01, "lo": 0.008, "hi": 0.012, "count": 1}}},
... ])
>>> x, ser = res.series("snr_db", "ser", min_count=5)
>>> x.tolist(), ser.tolist()
([0.0, 5.0], [0.1, nan])
to_frame() → pd.DataFrame#

The rows as a table (pandas is needed).

Returns:

rows().

Return type:

pandas.DataFrame

values(variable: str) → list[Any]#

The distinct values of a variable, in order.

Parameters:

variable (str) – the variable.

Returns:

its values.

Return type:

list

where(**condition: Any) → Results#

The conditions whose variables have the given values.

Parameters:

**condition – the values (reals compared to a relative tolerance of 1e-9, zero to an absolute tolerance of 1e-12).

Returns:

the selection, with the specification.

Return type:

Results

Raises:

KeyError – for a variable that no condition has (a misspelt name).

property metrics: list[str]#

The metrics reported, sorted (the probes as <label>.<metric>).

Type:

list[str]

property variables: list[str]#

The variables of the conditions, in order.

Type:

list[str]