coco_pipe.viz.plots¶

Minimal plotting helpers:

plot_topomap: 2D topographic map using MNE’s plot_topomap for EEG layouts.
plot_bar: Generic ranked bar plots with optional error bars.

Both functions are data-agnostic: pass any metric (e.g., accuracy, importance) for any analysis unit (sensors, features, regions).

Functions¶

`_coerce_series`(→ pandas.Series)
`_coerce_coords`(→ pandas.DataFrame)
`plot_topomap`(, ax, save, matplotlib.pyplot.Axes])	Plot a topographic map for arbitrary sensor values using MNE.
`plot_bar`(, ax, save, matplotlib.pyplot.Axes])	Plot a ranked bar chart of scores with optional error bars.
`plot_scatter2d`(, ax, save, matplotlib.pyplot.Axes])	Scatter plot with class-based coloring.

Module Contents¶

coco_pipe.viz.plots._coerce_series(data: pandas.Series | Mapping[str, float] | Sequence[float], index: Sequence[str] | None = None) → pandas.Series[source]¶

coco_pipe.viz.plots._coerce_coords(coords: pandas.DataFrame | Mapping[str, Tuple[float, float]] | Sequence[Tuple[float, float]], index: Sequence[str] | None = None) → pandas.DataFrame[source]¶

coco_pipe.viz.plots.plot_topomap(values: pandas.Series | Mapping[str, float] | Sequence[float], coords: pandas.DataFrame | Mapping[str, Tuple[float, float]] | Sequence[Tuple[float, float]], *, index: Sequence[str] | None = None, vmin: float | None = None, vmax: float | None = None, cmap: str = 'RdBu_r', head_radius: float = 0.5, levels: int = 64, fill: bool = True, sensors: str = 'markers', sensor_size: float = 30.0, outlines: bool = True, contours: int = 0, symmetric: bool = True, title: str | None = None, cbar: bool = True, cbar_label: str | None = None, text_size: float | None = None, title_size: float | None = None, title_loc: str | None = None, tick_size: float | None = None, cbar_size: float | None = None, figsize: Tuple[float, float] = (5, 5), ax: matplotlib.pyplot.Axes | None = None, save: str | None = None) → Tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes][source]¶

Plot a topographic map for arbitrary sensor values using MNE.

Parameters:

values (Series | Mapping | Sequence) – Sensor values. If Series or Mapping, keys should match coords names.
coords (DataFrame | Mapping | Sequence) – Sensor coordinates. Accepts: - DataFrame with columns [‘x’,’y’] and index = sensor names - Mapping[name] -> (x,y) - Sequence[(x,y)], plus index to name them
index (sequence, optional) – Names for values/coords when passing sequences.
sensors (str) – One of {“markers”, “labels”, “none”} to show sensor markers/labels.
contours (int) – Number of contour lines to draw on top (0 disables).
symmetric (bool, default=True) – If True, use symmetric color limits around 0 (vlim = [-a, +a]) where a is a rounded-up amplitude from the data range. Set False to use asymmetric nice-rounded limits.

Notes

Requires the optional dependency ‘mne’. Install with pip install mne.
Uses mne.viz.plot_topomap for robust EEG topographies.
vmin/vmax are rounded to “nice” values: we floor vmin and ceil vmax to the nearest power-of-10 step (e.g., 0.87 -> 0.9, 0.012 -> 0.02).
Use text_size to scale all text; override with title_size, tick_size, or cbar_size for finer control.
Use title_loc to set title alignment: ‘left’, ‘center’, or ‘right’.

Plot a ranked bar chart of scores with optional error bars.

Parameters:

scores (Series | Mapping | Sequence) – Values to plot. If Sequence, provide labels.
errors (Series | Mapping | Sequence, optional) – Error bars (std/sem). Keys or order must match scores.
label_map (Mapping[str, str], optional) – Mapping from original item names (index of scores) to custom display labels for tick names. Unmapped labels fall back to their original names.
top_n (int, optional) – Show only the top-N items after sorting by value.
ascending (bool) – Sort ascending (False for descending/top highest).
orientation (str) – “vertical” or “horizontal”.
axis_lim (tuple(float, float), optional) – Limits for the numeric axis (y for vertical, x for horizontal). If provided, applies via ax.set_ylim(axis_lim) (vertical) or ax.set_xlim(axis_lim) (horizontal).
color (str | list, optional) – Single color or list per bar. If not provided and cmap is set, colors are mapped from values.
cmap (str, optional) – Colormap name to map bar colors by value.
abs_values (bool, default=False) – If True, plot absolute values of scores and also sort/select top_n by absolute magnitude.
nice_axis_limits (bool, default=False) – If True and axis_lim is not provided, set the numeric axis limits to “nice-rounded” floor(min(values)) and ceil(max(values)). Applies to the y-axis for vertical orientation and x-axis for horizontal orientation.
remove_spines (str | sequence, optional) – Remove axis spines by name. Accepts any of {“left”,”right”,”top”,”bottom”}, or the shortcut “right_top” to remove both right and top. You can also pass a list like [“right”, “bottom”].
remove_ticks (str | sequence, optional) – Hide tick marks (not labels) on the x and/or y axes. Accepts “x”, “y”, or “both”. You can combine as a space/comma-separated string (e.g., “x y” or “x,y”) or pass a list like [“x”, “y”].
text_size (float, optional) – Base font size for all text in the plot (title, axis labels, ticks).
title_size (float, optional) – Overrides title font size; falls back to text_size.
axis_label_size (float, optional) – Overrides axis label font size; falls back to text_size.
tick_size (float, optional) – Overrides tick label font size; falls back to text_size.
title_loc (str, optional) – Title alignment: one of {“left”, “center”, “right”}. Defaults to matplotlib’s default (center) if not provided.
grid_axis (str | None, default="y") – Which axis to draw grid lines on: one of {“x”, “y”, “both”, “auto”}. Use “none” or None to disable the grid. “auto” chooses ‘y’ for vertical bars and ‘x’ for horizontal bars.
axis_break_orders (float, optional) – If provided, automatically create a broken numeric axis (y for vertical, x for horizontal) when the largest value is at least 10**axis_break_orders times the second largest. Only applied when values are non-negative and axis_lim is not set. Keeps API compatible by returning the primary axis (bottom/left) of the broken pair.
axis_break_pad (float, default=0.05) – Fractional padding around the split limits for the broken axes.

Scatter plot with class-based coloring.

Parameters:

x (array-like) – Coordinates for points.
y (array-like) – Coordinates for points.
labels (array-like, optional) – Class labels for coloring. If None, a single color is used.
label_map (mapping, optional) – Mapping from raw labels to display names in legend.
palette (sequence of colors, optional) – Colors to cycle over classes (defaults to matplotlib tab10).
legend (bool) – Whether to show legend for classes.