eegproc.plotting package

eegproc.plotting.plot_per_channel(input_data, title='Entropy Plot', xlabel='Time', seconds=4.0, start_row=0, end_row=1, save_path=None, max_width=None, max_height_per_channel=None, 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 (pandas.DataFrame) – DataFrame containing per-window EEG features (e.g., from shannons_entropy(), wavelet_entropy(), etc.).

  • title (str, default="Entropy Plot") – Figure title.

  • xlabel (str, default="Time") – 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, default=1) – Exclusive end row index (like df.iloc[start:end]). If None, plots until the end of the DataFrame.

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

  • max_width (int or None, optional) – Maximum width (in inches) of the entire figure. If None, width is auto-scaled.

  • max_height_per_channel (int or None, optional) – Maximum height (in inches) allocated per channel subplot. If None, auto-scaled.

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

  • frequency_bands (list[str] or None, optional) – 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:

None

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 matplotlib import pyplot as plt
>>> from eegproc.plotting import plot_per_channel
>>>
>>> # Simulate 3 channels and 2 bands over 100 windows
>>> t = np.arange(100)
>>> df = pd.DataFrame({
...     "AF3_alpha_entropy": np.sin(0.1 * t) + 0.1*np.random.randn(100),
...     "AF3_beta_entropy":  np.cos(0.1 * t) + 0.1*np.random.randn(100),
...     "AF3_theta_entropy":  np.cos(0.1 * t) + 0.1*np.random.randn(100),
...     "F7_alpha_entropy":  np.sin(0.1 * t + 1.0),
... })
>>>
>>> # Plot only AF3 alpha and beta band entropies, for the first 50 windows
>>> plot_per_channel(
...     df,
...     title="AF3 Entropy (Synthetic Example)",
...     seconds=4,
...     start_row=0,
...     end_row=50,
...     channels=["AF3"],
...     frequency_bands=["alpha", "beta"]
... )
>>>
>>> # To save instead of showing:
>>> # plot_per_channel(df, save_path="entropy_AF3.png", channels=["AF3"])

Submodules