lunapi.viz

Visualization helpers for notebook workflows.

Exports plotting utilities for hypnograms, spectra, topographic maps, and the interactive scope viewer built on ipywidgets and Plotly.

Functions

default_xy()

Return default 2-D scalp electrode locations for a standard 64-channel EEG montage.

stgcol(ss)

Map a sequence of sleep stage labels to their canonical hex display colours.

stgn(ss)

Map a sequence of sleep stage labels to their canonical numeric codes.

hypno(ss[, e, xsize, ysize, title])

Plot a colour-coded hypnogram from a sequence of sleep stage labels.

hypno_density(probs[, e, xsize, ysize, title])

Plot a stacked-probability hypno-density chart from POPS/SOAP output.

psd(df, ch[, var, minf, maxf, minp, maxp, xlines, ...])

Plot power spectral density from a Luna PSD or MTM CH_F table.

spec(df[, ch, var, mine, maxe, minf, maxf, w])

Plot an epoch-by-frequency spectrogram from a Luna CH_E_F result table.

spec0(x, y, z, mine, maxe, minf, maxf)

Render a 2-D spectrogram heatmap from raw epoch/frequency/value vectors.

topo_heat(chs, z[, ths, th, topo, lmts, sz, colormap, ...])

Plot a channel-wise topographic heat map on a scalp electrode layout.

scope(p[, chs, bsigs, hsigs, anns, stgs, stgcols, ...])

Create the interactive notebook scope viewer for one instance.

Module Contents

lunapi.viz.default_xy()[source]

Return default 2-D scalp electrode locations for a standard 64-channel EEG montage.

Returns:

DataFrame with columns ['CH', 'X', 'Y'] giving the normalised Cartesian coordinates of each electrode (top-down view, nose pointing up).

Return type:

pandas.DataFrame

lunapi.viz.stgcol(ss)[source]

Map a sequence of sleep stage labels to their canonical hex display colours.

Parameters:

ss (list of str) – Sleep stage labels (e.g. ['W', 'N1', 'N2', 'R', '?']).

Returns:

Hex colour string for each label (e.g. '#0050C8FF' for N2). Unknown labels are returned unchanged.

Return type:

list of str

lunapi.viz.stgn(ss)[source]

Map a sequence of sleep stage labels to their canonical numeric codes.

Codes: N1 → −1, N2 → −2, N3 → −3, R → 0, W → 1, L/? → 2.

Parameters:

ss (list of str) – Sleep stage labels.

Returns:

Numeric stage code for each label. Unknown labels are returned unchanged.

Return type:

list of int

lunapi.viz.hypno(ss, e=None, xsize=20, ysize=2, title=None)[source]

Plot a colour-coded hypnogram from a sequence of sleep stage labels.

Parameters:

  • ss (array-like of str) – Per-epoch sleep stage labels (e.g. from stages()).

  • e (array-like of int, optional) – Epoch indices. If omitted, epochs are numbered 0, 1, 2, …. Values are divided by 120 before plotting to convert to hours (assuming 30-second epochs).

  • xsize (float, optional) – Figure width in inches. Default 20.

  • ysize (float, optional) – Figure height in inches. Default 2.

  • title (str, optional) – Optional plot title.

Returns:

The hypnogram is rendered inline via Matplotlib.

Return type:

None

lunapi.viz.hypno_density(probs, e=None, xsize=20, ysize=2, title=None)[source]

Plot a stacked-probability hypno-density chart from POPS/SOAP output.

Displays per-epoch posterior stage probabilities as a stacked area plot, giving an at-a-glance picture of staging confidence across the night.

Parameters:

  • probs (pandas.DataFrame) – DataFrame containing columns PP_N1, PP_N2, PP_N3, PP_R, and PP_W (as returned by the POPS command).

  • e (ignored, optional) – Reserved for future use; currently unused.

  • xsize (float, optional) – Figure width in inches. Default 20.

  • ysize (float, optional) – Figure height in inches. Default 2.

  • title (str, optional) – Optional plot title.

Returns:

The chart is rendered inline via Matplotlib.

Return type:

None

lunapi.viz.psd(df, ch, var='PSD', minf=None, maxf=None, minp=None, maxp=None, xlines=None, ylines=None, dB=False)[source]

Plot power spectral density from a Luna PSD or MTM CH_F table.

Parameters:

  • df (pandas.DataFrame) – Result table with at least columns 'CH', 'F', and the power variable named by var. Typically the 'PSD: CH_F' or 'MTM: CH_F' table returned by proc().

  • ch (str or list of str) – Channel label(s) to plot.

  • var (str, optional) – Column name containing the power values ('PSD' or 'MTM'). Default 'PSD'.

  • minf (float, optional) – Minimum frequency (Hz) for the x-axis. Default: data minimum.

  • maxf (float, optional) – Maximum frequency (Hz) for the x-axis. Default: data maximum.

  • minp (float, optional) – Minimum power for the y-axis. Default: data minimum.

  • maxp (float, optional) – Maximum power for the y-axis. Default: data maximum.

  • xlines (float or list of float, optional) – Vertical reference lines at these frequencies.

  • ylines (float or list of float, optional) – Horizontal reference lines at these power values.

  • dB (bool, optional) – If True, convert power values to dB (10·log₁₀) before plotting. Default False.

Returns:

The plot is rendered inline via Matplotlib.

Return type:

None

lunapi.viz.spec(df, ch=None, var='PSD', mine=None, maxe=None, minf=None, maxf=None, w=0.025)[source]

Plot an epoch-by-frequency spectrogram from a Luna CH_E_F result table.

Parameters:

  • df (pandas.DataFrame) – Result table with columns 'E' (epoch), 'F' (frequency), 'CH' (channel), and the power variable named by var. Typically the 'PSD: CH_E_F' or 'MTM: CH_E_F' table.

  • ch (str, optional) – Channel to plot. If None, all channels in df are included.

  • var (str, optional) – Column name for power values. Default 'PSD'.

  • mine (int, optional) – First epoch to display. Default: first epoch in the data.

  • maxe (int, optional) – Last epoch to display. Default: last epoch in the data.

  • minf (float, optional) – Minimum frequency (Hz). Default: data minimum.

  • maxf (float, optional) – Maximum frequency (Hz). Default: data maximum.

  • w (float, optional) – Winsorisation proportion applied to power values before colour mapping. Default 0.025.

Returns:

The spectrogram is rendered inline via Matplotlib.

Return type:

None

lunapi.viz.spec0(x, y, z, mine, maxe, minf, maxf)[source]

Render a 2-D spectrogram heatmap from raw epoch/frequency/value vectors.

Low-level helper called by spec(). Bins z values into an epoch × frequency grid and displays the result as a pcolormesh plot.

Parameters:

  • x (array-like of int) – Epoch index for each observation.

  • y (array-like of float) – Frequency (Hz) for each observation.

  • z (array-like of float) – Power value for each observation.

  • mine (int) – Minimum epoch index for the x-axis.

  • maxe (int) – Maximum epoch index for the x-axis.

  • minf (float) – Minimum frequency (Hz) for the y-axis.

  • maxf (float) – Maximum frequency (Hz) for the y-axis.

Returns:

The heatmap is rendered inline via Matplotlib.

Return type:

None

lunapi.viz.topo_heat(chs, z, ths=None, th=0.05, topo=None, lmts=None, sz=70, colormap='bwr', title='', rimcolor='black', lab='dB')[source]

Plot a channel-wise topographic heat map on a scalp electrode layout.

Renders a scatter plot in electrode space where each dot is coloured by the scalar value z for that channel. Channels with an associated p-value below th are drawn with a thicker rim.

Parameters:

  • chs (array-like of str) – Channel labels corresponding to each value in z.

  • z (array-like of float) – Scalar values to colour-map (one per channel in chs).

  • ths (array-like of float, optional) – P-values (or thresholding values) for each channel. Channels with ths < th receive a highlighted rim. Default None (no thresholding).

  • th (float, optional) – Significance threshold applied to ths. Default 0.05.

  • topo (pandas.DataFrame, optional) – Electrode coordinate table with columns ['CH', 'X', 'Y']. Defaults to the 64-channel layout from default_xy().

  • lmts (list of two float, optional) – [vmin, vmax] colour-map limits. Default: [min(z), max(z)].

  • sz (float, optional) – Marker size (points²) for each electrode dot. Default 70.

  • colormap (str, optional) – Matplotlib colour map name. Default 'bwr'.

  • title (str, optional) – Text label placed in the upper-left of the figure. Default ''.

  • rimcolor (str, optional) – Edge colour for all electrode markers. Default 'black'.

  • lab (str, optional) – Colour-bar label. Default 'dB'.

Returns:

The topoplot is rendered inline via Matplotlib.

Return type:

None

lunapi.viz.scope(p, chs=None, bsigs=None, hsigs=None, anns=None, stgs=['N1', 'N2', 'N3', 'R', 'W', '?', 'L'], stgcols={'N1': 'blue', 'N2': 'blue', 'N3': 'navy', 'R': 'red', 'W': 'green', '?': 'gray', 'L': 'yellow'}, stgns={'N1': -1, 'N2': -2, 'N3': -3, 'R': 0, 'W': 1, '?': 2, 'L': 2}, sigcols=None, anncols=None, throttle1_sr=100, throttle2_np=5 * 30 * 100, summary_mins=30, height=600, annot_height=0.15, header_height=0.04, footer_height=0.01)[source]

Create the interactive notebook scope viewer for one instance.

Parameters:

  • p (inst) – Target Luna instance.

  • chs (list of str, optional) – Signal channel selections for traces/bands/Hjorth summaries.

  • bsigs (list of str, optional) – Signal channel selections for traces/bands/Hjorth summaries.

  • hsigs (list of str, optional) – Signal channel selections for traces/bands/Hjorth summaries.

  • anns (list of str, optional) – Annotation classes to include.

  • stgs (list of str, optional) – Sleep-stage labels used by hypnogram rendering.

  • stgcols (dict, optional) – Stage-to-color and stage-to-numeric maps.

  • stgns (dict, optional) – Stage-to-color and stage-to-numeric maps.

  • sigcols (dict, optional) – Optional explicit color overrides.

  • anncols (dict, optional) – Optional explicit color overrides.

  • throttle1_sr (int, optional) – Input sample-rate throttle.

  • throttle2_np (int, optional) – Output point-count throttle.

  • summary_mins (int or float, optional) – Threshold (minutes) for summary behavior in backend.

  • height (int, optional) – Main scope plot height.

  • annot_height (float, optional) – Relative layout proportions.

  • header_height (float, optional) – Relative layout proportions.

  • footer_height (float, optional) – Relative layout proportions.

Returns:

Widget application, or None when no valid channels/annots exist.

Return type:

ipywidgets.AppLayout or None