Visualization

Utilities for visualising epoch rejection results.

viz

Visualization utilities for dropped epoch analysis.

droplog_dataframe

droplog_dataframe(epochs)

Build a tidy DataFrame of dropped epochs and their rejection reasons.

Parameters:

Name	Type	Description	Default
epochs	Epochs	Epochs object after rejection (drop_log must be populated).	required

Returns:

Type	Description
DataFrame	DataFrame with columns epoch_ix, event_type, and reason.
DataFrame	One row per (dropped epoch, rejection reason) pair. Empty if no epochs
DataFrame	were dropped.

Source code in src/meegflow/viz.py

def droplog_dataframe(epochs: mne.Epochs) -> pd.DataFrame:
    """Build a tidy DataFrame of dropped epochs and their rejection reasons.

    Args:
        epochs: Epochs object after rejection (``drop_log`` must be populated).

    Returns:
        DataFrame with columns ``epoch_ix``, ``event_type``, and ``reason``.
        One row per (dropped epoch, rejection reason) pair. Empty if no epochs
        were dropped.
    """
    event_type = _epoch_event_labels(epochs)

    rows = []
    for ei, reasons in enumerate(epochs.drop_log):
        # epochs.drop_log[ei] is a tuple/list of ’reasons’; empty means kept
        if not reasons:
            continue
        for r in reasons:
            rows.append({"epoch_ix": ei, "event_type": event_type[ei], "reason": r})
    return pd.DataFrame(rows)

plot_drops_by_reason_and_type

plot_drops_by_reason_and_type(epochs, title='Dropped epochs by reason and event type')

Plot a stacked bar chart of dropped epochs broken down by reason and event type.

Parameters:

Name	Type	Description	Default
epochs	Epochs	Epochs object after rejection (drop_log must be populated).	required
title	str	Title for the figure axes.	'Dropped epochs by reason and event type'

Returns:

Type	Description
Figure	Matplotlib Figure. If no epochs were dropped the figure contains a
Figure	text message instead of a chart.

Source code in src/meegflow/viz.py

def plot_drops_by_reason_and_type(
    epochs: mne.Epochs,
    title: str = "Dropped epochs by reason and event type",
) -> plt.Figure:
    """Plot a stacked bar chart of dropped epochs broken down by reason and event type.

    Args:
        epochs: Epochs object after rejection (``drop_log`` must be populated).
        title: Title for the figure axes.

    Returns:
        Matplotlib Figure. If no epochs were dropped the figure contains a
        text message instead of a chart.
    """
    df = droplog_dataframe(epochs)

    fig, ax = plt.subplots(figsize=(8, 4))
    if df.empty:
        ax.text(0.5, 0.5, "No dropped epochs.", ha="center", va="center")
        ax.axis("off")
        return fig

    # counts(reason, event_type)
    tab = (
        df.groupby(["reason", "event_type"])
          .size()
          .unstack("event_type", fill_value=0)
          .sort_index()
    )

    tab.plot(kind="bar", stacked=True, ax=ax)
    ax.set_title(title)
    ax.set_xlabel("Drop reason")
    ax.set_ylabel("# epochs dropped")
    ax.legend(title="Event type", bbox_to_anchor=(1.02, 1), loc="upper left")
    fig.tight_layout()
    return fig