coco_pipe.viz¶

Curated plotting helpers for coco_pipe.

Submodules¶

Functions¶

`plot_eigenvalues`(, ax, interactive, Any])	Plot Scree plot of eigenvalues or explained variance.
`plot_embedding`(, title, figsize, int] =, cmap, ...)	Plot an explicit embedding with optional labels and metadata.
`plot_feature_correlation_heatmap`(, ax, interactive, ...)	Plot feature-to-dimension correlations as a heatmap.
`plot_feature_importance`(, ax, interactive, analysis, ...)	Plot feature-importance scores as a horizontal bar chart.
`plot_interpretation`(, ax, interactive, method, ...)	Plot one interpretation analysis using an appropriate visualization.
`plot_local_metrics`(→ matplotlib.pyplot.Figure)	Plot the embedding colored by local quality (e.g. point-wise trustworthiness).
`plot_loss_history`(, ax, interactive, Any])	Plot training loss over epochs.
`plot_metrics`(, ax, interactive, plot_type, metric, ...)	Plot tidy metric observations using one shared entrypoint.
`plot_shepard_diagram`(→ Union[matplotlib.pyplot.Figure, ...)	Plot Shepard Diagram (Original vs Embedded Distances).
`plot_streamlines`(→ Union[matplotlib.pyplot.Figure, Any])	Plot streamlines of a vector field on the embedding.
`plot_trajectory`(, ax, interactive, cmap, Any])	Plot already-prepared native trajectory tensors.
`plot_trajectory_metric_series`(, ax, interactive, Any])	Plot evaluated trajectory metric time series.
`plot_channel_traces_interactive`(...)	Plot grouped channel traces as stacked interactive subplots.
`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.
`plot_topomap`(, ax, save, matplotlib.pyplot.Axes])	Plot a topographic map for arbitrary sensor values using MNE.

Package Contents¶

coco_pipe.viz.plot_eigenvalues(values: numpy.ndarray, title: str = 'Scree Plot', ylabel: str = 'Explained Variance', figsize: Tuple[int, int] = (8, 5), ax: matplotlib.pyplot.Axes | None = None, interactive: bool = False) → matplotlib.pyplot.Figure | Any[source]¶

Plot Scree plot of eigenvalues or explained variance.

Parameters:

values (np.ndarray) – Array of eigenvalues or variance ratios.
title (str, optional) – Plot title, by default “Scree Plot”.
ylabel (str, optional) – Label for y-axis, by default “Explained Variance”.
figsize (tuple, optional) – Figure size, by default (8, 5).
ax (plt.Axes, optional) – Existing axes to plot on.
interactive (bool, optional) – If True, returns a Plotly figure.

Returns:

Matplotlib figure for static plots or the Plotly figure returned by the interactive backend.

Return type:

matplotlib.figure.Figure or Any

See also

plotly_utils.plot_scree_interactive

coco_pipe.viz.plot_embedding(X_emb: numpy.ndarray, labels: numpy.ndarray | None = None, metadata: Dict[str, Any] | None = None, dims: Tuple[int, int] | Tuple[int, int, int] = (0, 1), title: str = 'Embedding', figsize: Tuple[int, int] = (10, 8), cmap: str = 'viridis', palette: str = 'deep', s: int = 40, alpha: float = 0.8, metrics: Dict[str, Any] | None = None, ax: matplotlib.pyplot.Axes | None = None, save_path: str | None = None, interactive: bool = False, random_state: int | None = None) → matplotlib.pyplot.Figure | Any[source]¶

Plot an explicit embedding with optional labels and metadata.

Parameters:

X_emb (np.ndarray) – Embedding array with shape (n_samples, n_dimensions).
labels (np.ndarray, optional) – Optional values aligned with the sample axis. Categorical values are shown with a legend and continuous values with a colorbar.
metadata (dict, optional) – Optional column-oriented metadata aligned with the sample axis.
dims (tuple of int, default=(0, 1)) – Embedding dimensions to visualize. Length must be 2 or 3.
title (str, default="Embedding") – Figure title.
figsize (tuple of int, default=(10, 8)) – Matplotlib figure size for static plots.
cmap (str, default="viridis") – Colormap for continuous labels or value overlays.
palette (str, default="deep") – Seaborn categorical palette name.
s (int, default=40) – Marker size.
alpha (float, default=0.8) – Marker opacity.
metrics (dict, optional) – Optional scalar metrics to annotate on the figure.
ax (matplotlib.axes.Axes, optional) – Existing axes to draw on.
save_path (str, optional) – Optional file path for saving the static figure.
interactive (bool, default=False) – If True, return the Plotly equivalent.
random_state (int, optional) – Random seed used by the interactive path when sampling is needed.

Returns:

Matplotlib figure for static plots or the Plotly figure returned by the interactive backend.

Return type:

matplotlib.figure.Figure or Any

Raises:

ValueError – If the embedding is not 2D or the requested dimensions are invalid.

See also

plotly_utils.plot_embedding_interactive, prepare_embedding_frame, plot_metrics

coco_pipe.viz.plot_feature_correlation_heatmap(correlations: Any, title: str = 'Feature Correlation', top_n: int | None = 25, figsize: Tuple[int, int] = (10, 8), ax: matplotlib.pyplot.Axes | None = None, interactive: bool = False, method: str | None = None) → matplotlib.pyplot.Figure | Any[source]¶

Plot feature-to-dimension correlations as a heatmap.

Parameters:

correlations (Any) – Correlation interpretation payload or records.
title (str, default="Feature Correlation") – Figure title.
top_n (int, optional) – Maximum number of features to show. Features are ranked by the maximum absolute correlation across dimensions.
figsize (tuple of int, default=(10, 8)) – Matplotlib figure size for static plots.
ax (matplotlib.axes.Axes, optional) – Existing axes to draw on.
interactive (bool, default=False) – If True, return the Plotly equivalent.
method (str, optional) – Method name to select when multiple methods are present.

Returns:

Matplotlib figure for static plots or the Plotly figure returned by the interactive backend.

Return type:

matplotlib.figure.Figure or Any

coco_pipe.viz.plot_feature_importance(scores: Any, title: str = 'Feature Importance', top_n: int = 20, figsize: Tuple[int, int] = (8, 6), ax: matplotlib.pyplot.Axes | None = None, interactive: bool = False, analysis: str | None = None, method: str | None = None, dimension: str | None = None) → matplotlib.pyplot.Figure | Any[source]¶

Plot feature-importance scores as a horizontal bar chart.

Parameters:

scores (Any) – Raw feature -> score mapping, interpretation payload, or interpretation record table.
title (str, default="Feature Importance") – Figure title.
top_n (int, default=20) – Maximum number of features to show.
figsize (tuple of int, default=(8, 6)) – Matplotlib figure size for static plots.
ax (matplotlib.axes.Axes, optional) – Existing axes to draw on.
interactive (bool, default=False) – If True, return the Plotly equivalent.
analysis (str, optional) – Interpretation analysis to select when multiple analyses are present.
method (str, optional) – Method name to select when multiple methods are present.
dimension (str, optional) – Dimension label to select when the interpretation contains multiple dimensions.

Returns:

Matplotlib figure for static plots or the Plotly figure returned by the interactive backend.

Return type:

matplotlib.figure.Figure or Any

coco_pipe.viz.plot_interpretation(interpretation: Any, *, analysis: str, title: str | None = None, figsize: Tuple[int, int] = (10, 8), ax: matplotlib.pyplot.Axes | None = None, interactive: bool = False, method: str | None = None, dimension: str | None = None, top_n: int = 20) → matplotlib.pyplot.Figure | Any[source]¶

Plot one interpretation analysis using an appropriate visualization.

Parameters:

interpretation (Any) – Interpretation payload or interpretation records.
analysis (str) – Interpretation analysis to plot.
title (str, optional) – Figure title. Defaults to a title derived from analysis.
figsize (tuple of int, default=(10, 8)) – Matplotlib figure size for static plots.
ax (matplotlib.axes.Axes, optional) – Existing axes to draw on.
interactive (bool, default=False) – If True, return the Plotly equivalent.
method (str, optional) – Method name to select when multiple methods are present.
dimension (str, optional) – Dimension label to select when the interpretation contains multiple dimensions.
top_n (int, default=20) – Maximum number of features to show in bar or heatmap views.

Returns:

Matplotlib figure for static plots or the Plotly figure returned by the interactive backend.

Return type:

matplotlib.figure.Figure or Any

coco_pipe.viz.plot_local_metrics(X_emb: numpy.ndarray, local_scores: numpy.ndarray, title: str = 'Local Quality Map', cmap: str = 'RdYlGn', ax: matplotlib.pyplot.Axes | None = None) → matplotlib.pyplot.Figure[source]¶

Plot the embedding colored by local quality (e.g. point-wise trustworthiness).

Parameters:

X_emb (np.ndarray) – Embedding coordinates (2D).
local_scores (np.ndarray) – Score per sample.
title (str) – Plot title.
cmap (str) – Colormap (Green=Good, Red=Bad).

Returns:

Static figure colored by the provided local scores.

Return type:

matplotlib.figure.Figure

See also

plot_embedding

coco_pipe.viz.plot_loss_history(loss_history: list, title: str = 'Training Loss', figsize: Tuple[int, int] = (8, 5), ax: matplotlib.pyplot.Axes | None = None, interactive: bool = False) → matplotlib.pyplot.Figure | Any[source]¶

Plot training loss over epochs.

Parameters:

loss_history (list) – List of loss values.
title (str, optional) – Plot title, by default “Training Loss”.
figsize (tuple, optional) – Figure size, by default (8, 5).
ax (plt.Axes, optional) – Existing axes to plot on.
interactive (bool, optional) – If True, returns a Plotly figure.

Returns:

Matplotlib figure for static plots or the Plotly figure returned by the interactive backend.

Return type:

matplotlib.figure.Figure or Any

coco_pipe.viz.plot_metrics(scores: Any, title: str = 'Quality Metrics', figsize: Tuple[int, int] = (8, 6), ax: matplotlib.pyplot.Axes | None = None, interactive: bool = False, plot_type: str = 'auto', metric: str | None = None, scope: str | None = None, method: str | Sequence[str] | None = None) → matplotlib.pyplot.Figure | Any[source]¶

Plot tidy metric observations using one shared entrypoint.

Parameters:

scores (Any) – Metric mapping, tidy metric frame, list of records, or object exposing to_frame().
title (str, default="Quality Metrics") – Figure title.
figsize (tuple of int, default=(8, 6)) – Matplotlib figure size for static plots.
ax (matplotlib.axes.Axes, optional) – Existing axes to draw on.
interactive (bool, default=False) – If True, return the Plotly equivalent.
plot_type (str, default="auto") – Plot style to use. "auto" infers an appropriate view from the filtered metric records.
metric (str, optional) – Restrict plotting to one metric.
scope (str, optional) – Restrict plotting to one scope.
method (str or sequence of str, optional) – Restrict plotting to one or more methods.

Returns:

Matplotlib figure for static plots or the Plotly figure returned by the interactive backend.

Return type:

matplotlib.figure.Figure or Any

Raises:

ValueError – If no metrics remain after filtering.

See also

plotly_utils.plot_metric_details, prepare_metrics_frame, infer_metric_plot_type

coco_pipe.viz.plot_shepard_diagram(X_orig: numpy.ndarray, X_emb: numpy.ndarray, sample_size: int = 1000, title: str = 'Shepard Diagram', ax: matplotlib.pyplot.Axes | None = None, interactive: bool = False, random_state: int | None = None, distances: Dict[str, numpy.ndarray] | None = None) → matplotlib.pyplot.Figure | Any[source]¶

Plot Shepard Diagram (Original vs Embedded Distances).

Parameters:

X_orig (np.ndarray) – Original high-dimensional data.
X_emb (np.ndarray) – Embedded low-dimensional data.
sample_size (int, optional) – Number of points to sample for distance calculation (to speed up), by default 1000.
title (str, optional) – Plot title, by default “Shepard Diagram”.
ax (plt.Axes, optional) – Existing axes to plot on.
interactive (bool, optional) – If True, returns a Plotly figure.

Returns:

Matplotlib figure for static plots or the Plotly figure returned by the interactive backend.

Return type:

matplotlib.figure.Figure or Any

See also

plotly_utils.plot_shepard_interactive

coco_pipe.viz.plot_streamlines(X_emb: numpy.ndarray, V_emb: numpy.ndarray, grid_density: int = 25, title: str = 'Velocity Streamlines', ax: matplotlib.pyplot.Axes | None = None, interactive: bool = False, random_state: int | None = None) → matplotlib.pyplot.Figure | Any[source]¶

Plot streamlines of a vector field on the embedding.

Parameters:

X_emb (np.ndarray) – Coordinates of the embedding (2D only).
V_emb (np.ndarray) – Velocity vectors in the embedding space.
grid_density (int, optional) – Density of the grid for interpolation, by default 25.
title (str, optional) – Plot title, by default “Velocity Streamlines”.
ax (plt.Axes, optional) – Existing axes to plot on.
interactive (bool, optional) – If True, returns a Plotly figure.

Returns:

Matplotlib figure for static plots or the Plotly figure returned by the interactive backend.

Return type:

matplotlib.figure.Figure or Any

Raises:

ValueError – If X_emb is not 2D.

coco_pipe.viz.plot_trajectory(X: numpy.ndarray, times: numpy.ndarray | None = None, values: numpy.ndarray | None = None, labels: numpy.ndarray | None = None, smooth_window: int = 1, title: str = 'Trajectory Plot', dimensions: int = 2, figsize: Tuple[int, int] = (10, 8), ax: matplotlib.pyplot.Axes | None = None, interactive: bool = False, cmap: str = 'viridis') → matplotlib.pyplot.Figure | Any[source]¶

Plot already-prepared native trajectory tensors.

Parameters:

X (np.ndarray) – Trajectory tensor with shape (n_trajectories, n_times, n_dimensions).
times (np.ndarray, optional) – Explicit time axis aligned with the time dimension.
values (np.ndarray, optional) – Optional scalar overlay with shape (n_trajectories, n_times).
labels (np.ndarray, optional) – Optional label per trajectory.
smooth_window (int, default=1) – Moving-average window applied independently to each already-valid trajectory when greater than 1.
title (str, default="Trajectory Plot") – Figure title.
dimensions (int, default=2) – Number of embedding dimensions to display. Must be 2 or 3.
figsize (tuple of int, default=(10, 8)) – Matplotlib figure size for static plots.
ax (matplotlib.axes.Axes, optional) – Existing axes to draw on.
interactive (bool, default=False) – If True, return the Plotly equivalent.
cmap (str, default="viridis") – Colormap used for scalar overlays.

Returns:

Matplotlib figure for static plots or the Plotly figure returned by the interactive backend.

Return type:

matplotlib.figure.Figure or Any

Raises:

ValueError – If the input is not a native 3D trajectory tensor or if aligned arrays do not match the trajectory/time axes.

coco_pipe.viz.plot_trajectory_metric_series(series: Any, *, times: numpy.ndarray | None = None, labels: numpy.ndarray | None = None, title: str = 'Trajectory Metric', ylabel: str = 'Value', figsize: Tuple[int, int] = (10, 6), ax: matplotlib.pyplot.Axes | None = None, interactive: bool = False) → matplotlib.pyplot.Figure | Any[source]¶

Plot evaluated trajectory metric time series.

Parameters:

series (Any) – One-dimensional series, two-dimensional (trajectory, time) array, or mapping of name -> timecourse.
times (np.ndarray, optional) – Explicit time axis aligned with the time dimension.
labels (np.ndarray, optional) – Optional trajectory labels aligned with the first axis of 2D inputs.
title (str, default="Trajectory Metric") – Figure title.
ylabel (str, default="Value") – Y-axis label.
figsize (tuple of int, default=(10, 6)) – Matplotlib figure size for static plots.
ax (matplotlib.axes.Axes, optional) – Existing axes to draw on.
interactive (bool, default=False) – If True, return the Plotly equivalent.

Returns:

Matplotlib figure for static plots or the Plotly figure returned by the interactive backend.

Return type:

matplotlib.figure.Figure or Any

coco_pipe.viz.plot_channel_traces_interactive(data: numpy.ndarray, times: numpy.ndarray | None = None, group_labels: numpy.ndarray | None = None, channel_names: collections.abc.Sequence[str] | numpy.ndarray | None = None, selected_channels: collections.abc.Sequence[int] | collections.abc.Sequence[str] | None = None, group_name_map: dict[Any, str] | None = None, color_map: dict[Any, str] | None = None, title: str = 'Grouped Channel Time Series', xaxis_title: str = 'Time', yaxis_title: str = 'Amplitude', template: str = 'plotly_white', shared_xaxes: bool = True, vertical_spacing: float = 0.05, line_width: float = 2.0, opacity: float = 1.0, base_height: int = 300, row_height: int = 220, showlegend: bool = True) → plotly.graph_objects.Figure[source]¶

Plot grouped channel traces as stacked interactive subplots.

Parameters:

data (np.ndarray) – Three-dimensional array with shape (n_groups, n_channels, n_times).
times (np.ndarray, optional) – Explicit time axis aligned with the last dimension of data.
group_labels (np.ndarray, optional) – Labels aligned with the first axis of data.
channel_names (sequence of str or np.ndarray, optional) – Channel names aligned with the channel axis.
selected_channels (sequence of int or sequence of str, optional) – Channel indices or names to plot. When omitted, all channels are shown.
group_name_map (dict, optional) – Optional mapping from raw group labels to display names.
color_map (dict, optional) – Optional mapping from raw group labels to trace colors.
title (str, default="Grouped Channel Time Series") – Figure title.
xaxis_title (str, default="Time") – X-axis label for the final row.
yaxis_title (str, default="Amplitude") – Y-axis label per subplot row.
template (str, default="plotly_white") – Plotly layout template.
shared_xaxes (bool, default=True) – Whether subplot rows share the same x-axis.
vertical_spacing (float, default=0.05) – Vertical spacing between subplot rows.
line_width (float, default=2.0) – Trace line width.
opacity (float, default=1.0) – Trace opacity.
base_height (int, default=300) – Base figure height before row scaling.
row_height (int, default=220) – Additional height per plotted row.
showlegend (bool, default=True) – Whether to show the legend.

Returns:

Interactive multi-row channel trace figure.

Return type:

plotly.graph_objects.Figure

Raises:

ValueError – If the input shape or aligned labels/names are invalid.
TypeError – If selected_channels contains unsupported selector types.

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.

coco_pipe.viz.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’.