coco_pipe.viz.plotly_utils¶

Interactive plotting helpers for explicit dim-reduction embeddings, tidy metric records, trajectory tensors, and interpretation payloads.

Functions¶

`plot_channel_traces_interactive`(...)	Plot grouped channel traces as stacked interactive subplots.
`plot_embedding_interactive`(→ plotly.graph_objects.Figure)	Create an interactive 2D or 3D scatter plot of an embedding.
`plot_loss_history_interactive`(...)	Plot training loss history.
`plot_metric_details`(→ plotly.graph_objects.Figure)	Create an interactive metric plot from tidy metric observations.
`plot_scree_interactive`(→ plotly.graph_objects.Figure)	Plot explained variance and cumulative variance interactively.
`plot_radar_comparison`(→ plotly.graph_objects.Figure)	Create a radar chart comparing methods across scalar metrics.
`plot_raw_preview`(→ plotly.graph_objects.Figure)	Create a scrollable preview of multichannel raw traces.
`plot_shepard_interactive`(, scatter_max_points, ...)	Create an interactive Shepard diagram using Plotly.
`plot_feature_importance_interactive`(...)	Plot feature importance as an interactive horizontal bar chart.
`plot_feature_correlation_heatmap_interactive`(...)	Plot feature-to-dimension correlations as an interactive heatmap.
`plot_interpretation_interactive`(...)	Plot one interpretation analysis using an interactive Plotly view.
`plot_streamlines_interactive`(→ plotly.graph_objects.Figure)	Plot a velocity vector field using Plotly line segments.
`plot_trajectory_metric_series_interactive`(...)	Plot evaluated trajectory metric time series interactively.
`plot_trajectory_interactive`(→ plotly.graph_objects.Figure)	Plot already-prepared native trajectory tensors interactively.

Module Contents¶

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

coco_pipe.viz.plotly_utils.plot_embedding_interactive(embedding: numpy.ndarray, labels: numpy.ndarray | None = None, metadata: dict[str, Any] | None = None, title: str = 'Embedding', dimensions: int = 2, cmap: str = 'Viridis', palette: str | collections.abc.Sequence[str] | None = None, random_state: int | None = None) → plotly.graph_objects.Figure[source]¶

Create an interactive 2D or 3D scatter plot of an embedding.

Parameters:

embedding (np.ndarray) – Embedding array with shape (n_samples, n_dimensions).
labels (np.ndarray, optional) – Optional values aligned with the sample axis.
metadata (dict, optional) – Optional column-oriented metadata aligned with the sample axis.
title (str, default="Embedding") – Figure title.
dimensions (int, default=2) – Number of embedding dimensions to plot. Must be 2 or 3.
cmap (str, default="Viridis") – Continuous colormap name.
palette (str or sequence of str, optional) – Discrete color palette used for categorical columns.
random_state (int, optional) – Reserved for compatibility with data-first static/interactive APIs.

Returns:

Interactive embedding scatter plot.

Return type:

plotly.graph_objects.Figure

See also

prepare_embedding_frame, coco_pipe.viz.dim_reduction.plot_embedding

coco_pipe.viz.plotly_utils.plot_loss_history_interactive(loss_history: list, title: str = 'Training Loss') → plotly.graph_objects.Figure[source]¶: Plot training loss history.

coco_pipe.viz.plotly_utils.plot_metric_details(metrics_df: Any, title: str = 'Metric Details', plot_type: str = 'auto', metric: str | None = None, scope: str | None = None, method: str | collections.abc.Sequence[str] | None = None) → plotly.graph_objects.Figure[source]¶

Create an interactive metric plot from tidy metric observations.

Parameters:

metrics_df (Any) – Metric mapping, tidy metric frame, list of records, or object exposing to_frame().
title (str, default="Metric Details") – Figure title.
plot_type (str, default="auto") – Plot style to use. "auto" infers a suitable 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:

Interactive metric plot.

Return type:

plotly.graph_objects.Figure

See also

prepare_metrics_frame, infer_metric_plot_type, coco_pipe.viz.dim_reduction.plot_metrics

coco_pipe.viz.plotly_utils.plot_scree_interactive(explained_variance_ratio: numpy.ndarray) → plotly.graph_objects.Figure[source]¶

Plot explained variance and cumulative variance interactively.

Parameters:: explained_variance_ratio (np.ndarray) – One-dimensional array of explained variance ratios.
Returns:: Interactive scree plot.
Return type:: plotly.graph_objects.Figure

coco_pipe.viz.plotly_utils.plot_radar_comparison(metrics_df: pandas.DataFrame, normalize: bool = True, title: str = 'Method Comparison') → plotly.graph_objects.Figure[source]¶

Create a radar chart comparing methods across scalar metrics.

Parameters:

metrics_df (pandas.DataFrame) – Wide comparison table indexed by method with numeric metric columns.
normalize (bool, default=True) – Whether to normalize each numeric metric column to [0, 1] before plotting.
title (str, default="Method Comparison") – Figure title.

Returns:

Interactive radar comparison figure.

Return type:

plotly.graph_objects.Figure

Notes

Radar charts are overview visuals. They are less precise than line plots, tables, or heatmaps for detailed method comparisons.

coco_pipe.viz.plotly_utils.plot_raw_preview(data: numpy.ndarray, names: list | None = None, title: str = 'Raw Data Preview', max_points: int = 50000) → plotly.graph_objects.Figure[source]¶

Create a scrollable preview of multichannel raw traces.

Parameters:

data (np.ndarray) – Two-dimensional array with shape (n_samples, n_channels).
names (list, optional) – Optional channel names aligned with the channel axis.
title (str, default="Raw Data Preview") – Figure title.
max_points (int, default=50000) – Soft limit used to subsample very large inputs for display.

Returns:

Interactive raw-trace preview with a range slider.

Return type:

plotly.graph_objects.Figure

coco_pipe.viz.plotly_utils.plot_shepard_interactive(X_orig: numpy.ndarray, X_emb: numpy.ndarray, sample_size: int = 1000, title: str = 'Shepard Diagram', random_state: int | None = None, distances: dict[str, numpy.ndarray] | None = None, clip_quantiles: tuple[float, float] | None = (0.01, 0.99), scatter_max_points: int = 4000, scatter_opacity: float = 0.14) → plotly.graph_objects.Figure[source]¶: Create an interactive Shepard diagram using Plotly.

coco_pipe.viz.plotly_utils.plot_feature_importance_interactive(scores: Any, title: str = 'Feature Importance', top_n: int = 20, analysis: str | None = None, method: str | None = None, dimension: str | None = None) → plotly.graph_objects.Figure[source]¶

Plot feature importance as an interactive 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.
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 multiple dimensions are present.

Returns:

Interactive feature-importance bar chart.

Return type:

plotly.graph_objects.Figure

coco_pipe.viz.plotly_utils.plot_feature_correlation_heatmap_interactive(correlations: Any, title: str = 'Feature Correlation', top_n: int | None = 25, method: str | None = None) → plotly.graph_objects.Figure[source]¶

Plot feature-to-dimension correlations as an interactive 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.
method (str, optional) – Method name to select when multiple methods are present.

Returns:

Interactive feature-correlation heatmap.

Return type:

plotly.graph_objects.Figure

coco_pipe.viz.plotly_utils.plot_interpretation_interactive(interpretation: Any, *, analysis: str, title: str | None = None, method: str | None = None, dimension: str | None = None, top_n: int = 20) → plotly.graph_objects.Figure[source]¶

Plot one interpretation analysis using an interactive Plotly view.

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.
method (str, optional) – Method name to select when multiple methods are present.
dimension (str, optional) – Dimension label to select when multiple dimensions are present.
top_n (int, default=20) – Maximum number of features to show in bar or heatmap views.

Returns:

Interactive interpretation figure.

Return type:

plotly.graph_objects.Figure

coco_pipe.viz.plotly_utils.plot_streamlines_interactive(X_emb: numpy.ndarray, V_emb: numpy.ndarray, grid_density: int = 25, title: str = 'Velocity Streamlines', random_state: int | None = None) → plotly.graph_objects.Figure[source]¶: Plot a velocity vector field using Plotly line segments.

coco_pipe.viz.plotly_utils.plot_trajectory_metric_series_interactive(series: Any, *, times: numpy.ndarray | None = None, labels: numpy.ndarray | None = None, title: str = 'Trajectory Metric', ylabel: str = 'Value') → plotly.graph_objects.Figure[source]¶

Plot evaluated trajectory metric time series interactively.

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.

Returns:

Interactive trajectory metric series figure.

Return type:

plotly.graph_objects.Figure

coco_pipe.viz.plotly_utils.plot_trajectory_interactive(X: numpy.ndarray, times: numpy.ndarray | None = None, labels: numpy.ndarray | None = None, values: numpy.ndarray | None = None, title: str = 'Trajectory Plot', dimensions: int = 2, smooth_window: int | None = None) → plotly.graph_objects.Figure[source]¶

Plot already-prepared native trajectory tensors interactively.

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.
labels (np.ndarray, optional) – Optional label per trajectory.
values (np.ndarray, optional) – Optional scalar overlay with shape (n_trajectories, n_times).
title (str, default="Trajectory Plot") – Figure title.
dimensions (int, default=2) – Number of embedding dimensions to display. Must be 2 or 3.
smooth_window (int, optional) – Moving-average window applied independently to each already-valid trajectory when greater than 1.

Returns:

Interactive trajectory plot.

Return type:

plotly.graph_objects.Figure

Raises:

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