comnum.plot#

The classical views of a signal and of the results of a campaign (matplotlib).

Every function draws on ax (a new figure if None) and returns it. A signal is a NumPy array, or a comnum.Frame from comnum.Chain.trace(): the functions then take its samples per symbol, its sampling rate and its constellation, and draw every antenna or polarisation.

Function	View
`constellation()`	the samples in the complex plane, over the reference points
`eye()`	the eye diagram, traces of `n_symbols` symbols
`time()`	I and Q, the envelope, the power or the phase against time
`psd()`	the power spectral density (Welch)
`curves()`	a metric of `comnum.Results` against a variable, with confidence intervals and an optional closed form

The colours are named constants of this module (comnum.plot.BLUE, GREY, the categorical cycle SERIES…), shared by the gallery and the documentation; style() sets the figure style of the documentation (comnum.plot.style() before plotting, in a script run outside the gallery).

matplotlib is needed (pip install matplotlib); it is imported when a function is called.

Example

>>> import comnum
>>> from comnum import blocks as B
>>> link = comnum.Chain(tx=B.Source(constellation="16-QAM", n_symbols=2000),
...                    ch=B.Awgn(snr_db=18.0))
>>> frames = link.trace({}, comnum.Rng(1))
>>> ax = comnum.plot.constellation(frames["ch"])
>>> fig = frames.plot("constellation")

Module Attributes

STREAM_COLORS

Colours of the antennas or polarisations, in order.

Functions

`constellation`(x, *[, ax, stream, skip, ...])	The samples in the complex plane.
`curves`(results, x, metric, *[, by, ax, ...])	A metric of `comnum.Results` against the variable `x`, one curve per value of `by`, for the conditions that match `condition`.
`eye`(x, *[, ax, sps, n_symbols, traces, ...])	The eye diagram: `traces` segments of `n_symbols` symbols overlaid.
`psd`(x, *[, ax, fs, nfft, names])	The power spectral density (Welch, Hann window, 50 % overlap) of every stream, in dB, against the frequency: in GHz, MHz, kHz or Hz for a sampling rate in hertz (`fs`, or that of a frame), relative to the symbol rate for a frame on a normalised time axis, to the sampling rate for an array without `fs`.
`style`()	Set the figure style of the documentation and of the gallery in the matplotlib settings (`rcParams`): recessive axes, thin marks, the colours of this module and the categorical cycle `SERIES`.
`time`(x, *[, ax, part, fs, start, n, stream])	The signal against time.

comnum.plot.constellation(x: Any, *, ax: Axes | None = None, stream: int | None = None, skip: int = 0, max_points: int = 20000, density: bool = False, reference: Any = True, size: float = 2.0, alpha: float = 0.35, names: tuple[str, ...] = ('x', 'y')) → Axes#

The samples in the complex plane.

Parameters:

x (Frame | array_like) – a frame or a complex array (rows: streams).
ax (matplotlib.axes.Axes | None) – the axes (a new figure by default).
stream (int | None) – draw this stream only (all by default, one colour each).
skip (int) – samples left out at the start of every stream (filter transients).
max_points (int) – largest number of points drawn per stream (evenly spaced).
density (bool) – a 2D histogram (log scale) instead of points.
reference (bool | array_like | Constellation) – the reference points: True for the constellation of the frame, an array or a constellation, False for none.
size (float) – the size of the markers.
alpha (float) – the opacity of the markers.
names (tuple[str, ...]) – the labels of the streams (the polarisations by default).

Returns:

the axes.

Return type:

matplotlib.axes.Axes

comnum.plot.curves(results: Any, x: str, metric: str, *, by: str | None = None, ax: Axes | None = None, theory: Callable[..., Any] | None = None, errorbars: bool = True, logy: bool | None = None, min_count: int = 0, **condition: Any) → Axes#

A metric of comnum.Results against the variable x, one curve per value of by, for the conditions that match condition.

Parameters:

results (Results | list[dict]) – the results of a campaign.
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 (a new figure by default).
theory (callable | None) – a closed form drawn as a dotted line: theory(x), or theory(x, value) with by, on a fine grid of x (an array: the theory_* functions of the package take one).
errorbars (bool) – draw the confidence intervals.
logy (bool | None) – a logarithmic axis (by default for error rates).
min_count (int) – points with fewer errors are left out.
**condition – the values of the other variables.

Returns:

the axes.

Return type:

matplotlib.axes.Axes

Raises:

KeyError – for a variable or a metric that the results do not have.

comnum.plot.eye(x: Any, *, ax: Axes | None = None, sps: int | None = None, n_symbols: int = 2, traces: int = 300, skip: int = 0, part: str = 'real', stream: int = 0) → Axes#

The eye diagram: traces segments of n_symbols symbols overlaid.

Parameters:

x (Frame | array_like) – a frame or a complex array.
ax (matplotlib.axes.Axes | None) – the axes (a new figure by default).
sps (int | None) – samples per symbol (that of the frame by default; at least 2).
n_symbols (int) – symbols per trace.
traces (int) – number of traces.
skip (int) – samples left out at the start.
part (str) – "real" (I), "imag" (Q) or "abs".
stream (int) – the stream drawn.

Returns:

the axes.

Return type:

matplotlib.axes.Axes

Raises:

ValueError – below 2 samples per symbol.

comnum.plot.psd(x: Any, *, ax: Axes | None = None, fs: float | None = None, nfft: int = 1024, names: tuple[str, ...] = ('x', 'y')) → Axes#

The power spectral density (Welch, Hann window, 50 % overlap) of every stream, in dB, against the frequency: in GHz, MHz, kHz or Hz for a sampling rate in hertz (fs, or that of a frame), relative to the symbol rate for a frame on a normalised time axis, to the sampling rate for an array without fs.

Parameters:

x (Frame | array_like) – a frame or a complex array (rows: streams).
ax (matplotlib.axes.Axes | None) – the axes (a new figure by default).
fs (float | None) – sampling rate (Hz; that of the frame by default).
nfft (int) – length of the segments.
names (tuple[str, ...]) – the labels of the streams.

Returns:

the axes.

Return type:

matplotlib.axes.Axes

comnum.plot.style() → None#

Set the figure style of the documentation and of the gallery in the matplotlib settings (rcParams): recessive axes, thin marks, the colours of this module and the categorical cycle SERIES.

Example

>>> import comnum
>>> comnum.plot.style()

comnum.plot.time(x: Any, *, ax: Axes | None = None, part: str = 'iq', fs: float | None = None, start: int = 0, n: int | None = 400, stream: int = 0) → Axes#

The signal against time.

Parameters:

x (Frame | array_like) – a frame or a complex array.
ax (matplotlib.axes.Axes | None) – the axes (a new figure by default).
part (str) – "iq" (I and Q), "abs" (envelope), "power" or "phase" (unwrapped).
fs (float | None) – sampling rate (Hz); the time axis is in samples without it (that of the frame by default).
start (int) – the first sample drawn.
n (int | None) – the number of samples drawn (all with None).
stream (int) – the stream drawn.

Returns:

the axes.

Return type:

matplotlib.axes.Axes