mne_denoise.viz.plot_endpoint_metrics_summary#

mne_denoise.viz.plot_endpoint_metrics_summary(data, metric_col, group_col='group', subject_col='subject', group_order=None, group_colors=None, group_labels=None, reference_value=None, reference_label='Reference', null_distribution=None, observed_value=None, title='Endpoint Metrics Summary', show=True, fname=None)[source]#

Plot a generic endpoint-metric storyboard.

Parameters:

  • data (mapping[str, array-like]) – Columnar mapping with at least metric_col, group_col, and subject_col.

  • metric_col (str) – Metric column to summarize.

  • group_col (str) – Group identifier column.

  • subject_col (str) – Subject identifier column.

  • group_order (sequence of str | None) – Optional group order. Defaults to first-seen order.

  • group_colors (mapping | None) – Optional color/label overrides keyed by group.

  • group_labels (mapping | None) – Optional color/label overrides keyed by group.

  • reference_value (float | None) – Optional horizontal reference line for metric panels.

  • reference_label (str) – Label for reference_value.

  • null_distribution (array-like | None) – Optional null distribution for the null panel.

  • observed_value (float | None) – Observed statistic for the null panel.

  • title (str) – Figure title.

  • show (bool) – Whether to show the figure.

  • fname (path-like | None) – Optional output path.

Returns:

fig – Figure handle.

Return type:

matplotlib.figure.Figure

Raises:

  • KeyError – If required columns are missing from data.

  • ValueError – If numeric conversion or plotting operations receive incompatible shapes.

Notes

The output is a 2x2 storyboard combining grouped means, paired subject trajectories, per-group distributions, and optional null-distribution diagnostics.

Examples

>>> import numpy as np
>>> from mne_denoise.viz import plot_endpoint_metrics_summary
>>> data = {
...     "subject": np.array(["s1", "s1", "s2", "s2"]),
...     "group": np.array(["A", "B", "A", "B"]),
...     "score": np.array([1.2, 0.9, 1.1, 0.8]),
... }
>>> fig = plot_endpoint_metrics_summary(
...     data,
...     metric_col="score",
...     show=False,
... )