eegproc.plotting.plots module

Plotting for EEG feature tables.

eegproc.plotting.plots.plot_eeg_features(input_data, title='EEG Features', xlabel='Time (s)', seconds=4.0, overlap=0.0, start_row=0, end_row=None, save_path=None, max_width=12.0, max_height_per_channel=0.6, max_subplots=40, channels=None, frequency_bands=None)[source]

Plot stacked EEG feature traces per channel and/or band.

This function creates a vertically stacked line plot showing channel-level features (e.g., entropy or bandpower) across time windows. Each subplot corresponds to one feature column, with time on the x-axis (derived from the row index multiplied by the window duration seconds).

It supports filtering by subsets of channels and/or frequency bands, and automatically arranges figure size and subplot layout.

Parameters:

  • input_data (DataFrame) – DataFrame containing per-window EEG features (e.g., from shannons_entropy(), wavelet_entropy(), etc.).

  • title (str, default: 'EEG Features') – Figure title.

  • xlabel (str, default: 'Time (s)') – X-axis label (typically “Time”).

  • seconds (float, default: 4.0) – Duration represented by each row, in seconds. Used to scale the time axis.

  • start_row (int, default: 0) – Inclusive start row index to plot.

  • end_row (int | None, default: None) – Exclusive end row index (like df.iloc[start:end]). If None, plots until the end of the DataFrame.

  • save_path (str | None, default: None) – If provided, saves the figure to this path (e.g., "entropy_plot.png"). Otherwise, displays it interactively via plt.show().

  • max_width (float, default: 12.0) – Maximum width (in inches) of the entire figure. If None, width is auto-scaled.

  • max_height_per_channel (float, default: 0.6) – Maximum height (in inches) allocated per channel subplot. If None, auto-scaled.

  • channels (list[str] | None, default: None) – Subset of channel names to plot (e.g., ["AF3", "F7"]). If None, includes all.

  • frequency_bands (list[str] | None, default: None) – Subset of frequency bands to include when aggregating (e.g., ["alpha", "theta"]). If None, includes all bands found in column names.

Raises:

ValueError – If input_data is empty or the specified start/end rows yields an empty range.

Return type:

tuple[Figure, list[Axes]]

Notes

  • Each row of input_data corresponds to one analysis window (e.g., 4 seconds).

  • Columns are expected to follow patterns like: AF3_wentropy, F7_wentropy, AF3_alpha_entropy etc.

  • The function automatically infers which columns to plot based on substring matches for the requested channels and frequency_bands.

Examples

Basic synthetic example:

>>> import numpy as np, pandas as pd
>>> from eegproc.plotting import plot_eeg_features
>>>
>>> # Per-window band powers for two channels, as psd_bandpowers emits them
>>> t = np.arange(100)
>>> df = pd.DataFrame({
...     "AF3_alpha": np.sin(0.1 * t),
...     "AF3_betaL": np.cos(0.1 * t),
...     "AF3_theta": np.cos(0.2 * t),
...     "F7_alpha": np.sin(0.1 * t + 1.0),
... })
>>>
>>> # Plot only AF3's alpha and betaL traces, for the first 50 windows
>>> plot_eeg_features(
...     df,
...     title="AF3 Band Power (Synthetic Example)",
...     seconds=4,
...     start_row=0,
...     end_row=50,
...     channels=["AF3"],
...     frequency_bands=["alpha", "betaL"],
... )

Note that band filtering only applies to features whose column names carry a band token. shannons_entropy, wavelet_entropy and imf_entropy emit one column per channel ({channel}_entropy) with no band, so pass channels= alone for those.

Parameters:

  • overlap (float, default: 0.0)

  • max_subplots (int | None, default: 40)