coco_pipe.viz.interactive.dim_reduction#

Interactive Plotly visualization helpers for dimensionality reduction outputs.

Functions#

`plot_embedding`(embedding[, labels, metadata, title, ...])	Create an interactive 2D or 3D scatter plot of an embedding.
`plot_loss_history`(loss_history[, title])	Plot training loss history as an interactive Plotly line chart.
`plot_metrics`(metrics_df[, title, plot_type, metric, ...])	Create an interactive metric plot from tidy metric observations.
`plot_scree`(explained_variance_ratio)	Plot explained variance and cumulative variance interactively.
`plot_radar_comparison`(metrics_df[, normalize, title])	Create a radar chart comparing methods across scalar metrics.
`plot_raw_preview`(data[, names, title, max_points])	Create a scrollable preview of multichannel raw traces.
`plot_shepard_diagram`(X_orig, X_emb[, sample_size, ...])	Create an interactive Shepard diagram.
`plot_feature_importance`(scores[, title, top_n, ...])	Plot feature importance as an interactive horizontal bar chart.
`plot_feature_correlation_heatmap`(correlations[, ...])	Plot feature-to-dimension correlations as an interactive heatmap.
`plot_streamlines`(X_emb, V_emb[, grid_density, title, ...])	Plot a velocity vector field using Plotly line segments.
`plot_trajectory_metric_series`(series, *[, times, ...])	Plot evaluated trajectory metric time series interactively.
`plot_trajectory`(X[, times, labels, values, sem, ...])	Plot native trajectory tensors interactively.
`plot_coranking_matrix`(coranking_matrix[, title, max_k])	Plot a co-ranking matrix as an interactive heatmap.
`plot_trajectory_separation`(separation, *[, times, ...])	Plot pairwise label-separation timecourses interactively.
`plot_phase_portrait`(X, times, labels[, component_idx, ...])	Plot a phase portrait (amplitude vs velocity) for condition-mean trajectories.
`plot_component_loadings`(components[, feature_names, ...])	Plot component loadings from linear reducers as an interactive heatmap.

Module Contents#

coco_pipe.viz.interactive.dim_reduction.plot_embedding(embedding, labels=None, metadata=None, title='Embedding', dimensions=2, cmap=SEQUENTIAL, palette=None, color_kind='categorical', random_state=None)#

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=SEQUENTIAL) – Continuous colormap name.
palette (str or sequence of str, optional) – Discrete color palette used for categorical columns.
color_kind ({"categorical", "continuous"}, default="categorical") – How to color the first available label or metadata column.
random_state (int, optional) – Accepted for API compatibility; not used internally.

Returns:

Interactive embedding scatter plot.

Return type:

plotly.graph_objects.Figure

See also

coco_pipe.viz.dim_reduction.plot_embedding: Static Matplotlib version.
plot_shepard_diagram: Validates embedding structure via distance preservation.
plot_metrics: Metric summary for the same embedding.
plot_trajectory: Overlay temporal trajectories on an embedding.

Examples

>>> import numpy as np
>>> from coco_pipe.viz.interactive import dim_reduction as viz
>>> X_emb = np.random.default_rng(42).normal(size=(50, 2))
>>> fig = viz.plot_embedding(X_emb)

coco_pipe.viz.interactive.dim_reduction.plot_loss_history(loss_history, title='Training Loss')#

Plot training loss history as an interactive Plotly line chart.

Parameters:

loss_history (list) – Sequence of per-epoch loss values.
title (str) – Figure title.

Returns:

Interactive loss curve figure.

Return type:

plotly.graph_objects.Figure

See also

coco_pipe.viz.dim_reduction.plot_loss_history: Static Matplotlib version.
plot_scree: Scree plot of explained variance ratios.
plot_metrics: Metric bar chart for post-fit quality evaluation.

Examples

>>> from coco_pipe.viz.interactive import dim_reduction as viz
>>> fig = viz.plot_loss_history([1.0, 0.7, 0.4, 0.25, 0.18])

coco_pipe.viz.interactive.dim_reduction.plot_metrics(metrics_df, title='Metric Details', plot_type='bar', metric=None, scope=None, method=None)#

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="bar") – Explicit plot style to use.
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

coco_pipe.viz.dim_reduction.plot_metrics: Static Matplotlib version.
plot_scree: Scree plot complementing variance-based metrics.
plot_shepard_diagram: Distance-preservation diagnostic.
plot_coranking_matrix: Rank-based quality matrix.

Examples

>>> from coco_pipe.viz.interactive import dim_reduction as viz
>>> fig = viz.plot_metrics({"trustworthiness": 0.9, "continuity": 0.85})

coco_pipe.viz.interactive.dim_reduction.plot_scree(explained_variance_ratio)#

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

See also

coco_pipe.viz.dim_reduction.plot_scree: Static Matplotlib version.
plot_loss_history: Training loss curve for iterative methods.
plot_metrics: Broader metric quality summary.
plot_component_loadings: Component loading heatmap for linear reducers.

Examples

>>> import numpy as np
>>> from coco_pipe.viz.interactive import dim_reduction as viz
>>> fig = viz.plot_scree(np.array([0.5, 0.3, 0.2]))

coco_pipe.viz.interactive.dim_reduction.plot_radar_comparison(metrics_df, normalize=True, title='Method Comparison')#

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

See also

plot_metrics: Tidy metric bar/box/line charts for the same data.
plot_channel_traces: Grouped channel traces for raw exploration.
plot_raw_preview: Scrollable raw data preview.

Examples

>>> import pandas as pd
>>> from coco_pipe.viz.interactive import dim_reduction as viz
>>> df = pd.DataFrame(
...     {"trustworthiness": [0.9, 0.85], "continuity": [0.88, 0.82]},
...     index=["UMAP", "t-SNE"],
... )
>>> fig = viz.plot_radar_comparison(df)

coco_pipe.viz.interactive.dim_reduction.plot_raw_preview(data, names=None, title='Raw Data Preview', max_points=50000)#

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

See also

plot_channel_traces: Grouped channel traces with stacked subplots.
plot_radar_comparison: Radar chart comparing methods across metrics.
plot_embedding: Embedding scatter after dimensionality reduction.

Examples

>>> import numpy as np
>>> from coco_pipe.viz.interactive import dim_reduction as viz
>>> data = np.random.default_rng(42).normal(size=(200, 8))
>>> fig = viz.plot_raw_preview(data)

coco_pipe.viz.interactive.dim_reduction.plot_shepard_diagram(X_orig, X_emb, sample_size=1000, title='Shepard Diagram', random_state=None, distances=None, clip_quantiles=(0.01, 0.99), scatter_max_points=4000, scatter_opacity=0.14)#

Create an interactive Shepard diagram.

Parameters:

X_orig (numpy.ndarray) – Original high-dimensional data. Ignored when distances is given.
X_emb (numpy.ndarray) – Low-dimensional embedding. Ignored when distances is given.
sample_size (int) – Number of point pairs sampled for distance computation.
title (str) – Figure title.
random_state (int | None) – Random seed for reproducible distance sampling.
distances (dict[str, numpy.ndarray] | None) – Pre-computed dict with "original" and "embedded" keys. When both keys are present, X_orig and X_emb are not used.
clip_quantiles (tuple[float, float] | None) – (low, high) quantile pair used to clip axis ranges for display. Set to None to use the full distance range.
scatter_max_points (int) – Maximum number of individual pair points shown as a scatter overlay.
scatter_opacity (float) – Opacity of the scatter overlay points.

Returns:

Interactive Shepard diagram with density contours and scatter overlay.

Return type:

plotly.graph_objects.Figure

See also

coco_pipe.viz.dim_reduction.plot_shepard_diagram: Static Matplotlib version.
plot_embedding: Embedding scatter plot for visual inspection.
plot_coranking_matrix: Rank-order quality matrix complementing Shepard analysis.
plot_metrics: Summary of trustworthiness and continuity metrics.

Examples

>>> import numpy as np
>>> from coco_pipe.viz.interactive import dim_reduction as viz
>>> rng = np.random.default_rng(42)
>>> fig = viz.plot_shepard_diagram(
...     rng.normal(size=(30, 5)), rng.normal(size=(30, 2))
... )

coco_pipe.viz.interactive.dim_reduction.plot_feature_importance(scores, title='Feature Importance', top_n=20, analysis=None, method=None, dimension=None)#

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

See also

coco_pipe.viz.dim_reduction.plot_feature_importance: Static Matplotlib version.
plot_feature_correlation_heatmap: Feature-to-dimension correlation heatmap.
plot_component_loadings: Component loading matrix for linear reducers.

Examples

>>> from coco_pipe.viz.interactive import dim_reduction as viz
>>> fig = viz.plot_feature_importance({"F1": 0.6, "F2": 0.4, "F3": 0.2})

coco_pipe.viz.interactive.dim_reduction.plot_feature_correlation_heatmap(correlations, title='Feature Correlation', top_n=25, method=None)#

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

See also

coco_pipe.viz.dim_reduction.plot_feature_correlation_heatmap: Static Matplotlib version.
plot_feature_importance: Feature importance bar chart.
plot_component_loadings: Linear component loadings heatmap.

Examples

>>> from coco_pipe.viz.interactive import dim_reduction as viz
>>> corr = {
...     "correlation": {"D1": {"F1": 0.3, "F2": -0.1}, "D2": {"F1": 0.5, "F2": 0.2}}
... }
>>> fig = viz.plot_feature_correlation_heatmap(corr)

coco_pipe.viz.interactive.dim_reduction.plot_streamlines(X_emb, V_emb, grid_density=25, title='Velocity Streamlines', random_state=None)#

Plot a velocity vector field using Plotly line segments.

Parameters:

X_emb (numpy.ndarray) – 2D embedding coordinates with shape (n_samples, 2).
V_emb (numpy.ndarray) – Velocity vectors with the same shape as X_emb.
grid_density (int) – Accepted for API parity with the static version; not used internally.
title (str) – Figure title.
random_state (int | None) – Random seed used when subsampling large point clouds.

Returns:

Interactive velocity field figure.

Return type:

plotly.graph_objects.Figure

See also

coco_pipe.viz.dim_reduction.plot_streamlines: Static Matplotlib version.
plot_embedding: Embedding scatter that provides context for the velocity field.
plot_trajectory: Trajectory lines overlaid on an embedding.

Examples

>>> import numpy as np
>>> from coco_pipe.viz.interactive import dim_reduction as viz
>>> rng = np.random.default_rng(42)
>>> fig = viz.plot_streamlines(rng.normal(size=(50, 2)), rng.normal(size=(50, 2)))

coco_pipe.viz.interactive.dim_reduction.plot_trajectory_metric_series(series, *, times=None, labels=None, color_map=None, linestyle_map=None, smooth_window=1, title='Trajectory Metric', ylabel='Value', **layout_kwargs)#

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.
color_map (dict[str, str], optional)
linestyle_map (dict[str, str], optional)
title (str, default="Trajectory Metric") – Figure title.
ylabel (str, default="Value") – Y-axis label.
smooth_window (int)
layout_kwargs (Any)

Returns:

Interactive trajectory metric series figure.

Return type:

plotly.graph_objects.Figure

See also

coco_pipe.viz.dim_reduction.plot_trajectory_metric_series: Static Matplotlib version.
plot_trajectory: Trajectory geometry in 2D or 3D space.
plot_trajectory_separation: Pairwise label-separation timecourses.

Examples

>>> import numpy as np
>>> from coco_pipe.viz.interactive import dim_reduction as viz
>>> series = np.random.default_rng(42).normal(size=(3, 20))
>>> fig = viz.plot_trajectory_metric_series(series)

coco_pipe.viz.interactive.dim_reduction.plot_trajectory(X, times=None, labels=None, values=None, sem=None, color_map=None, linestyle_map=None, title='Trajectory Plot', dimensions=2, smooth_window=None, downsample=1, sem_alpha=0.18, sem_n_steps=8, show_markers=True, add_start_end_markers=False, linewidth=4.0, width=None, height=None, axis_labels=None, layout_kws=None)#

Plot 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).
sem (np.ndarray, optional) – Per-trajectory, per-time, per-dimension uncertainty (typically the across-trial SEM of the trajectory). Shape (n_trajectories, n_times, n_dimensions). When provided, a translucent uncertainty envelope is drawn around each trajectory: in 2D as small ellipses with semi-axes equal to sem along each PC; in 3D as small translucent markers sized by the joint SEM magnitude.
color_map (dict[str, str], optional) – Optional mapping of label to hex color string.
linestyle_map (dict[str, str], optional) – Optional mapping of label to dash style string.
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 to each trajectory when greater than 1.
downsample (int, default=1) – Keep every downsample-th time point after smoothing.
sem_alpha (float, default=0.18) – Opacity of the uncertainty envelope when sem is provided.
sem_n_steps (int, default=8) – Approximate number of timepoints sampled for the uncertainty envelope. Lower values declutter dense trajectories; the line itself is still drawn at full resolution.
show_markers (bool, default=True) – If True, draws markers at each sampled time point.
add_start_end_markers (bool)
linewidth (float)
width (int | None)
height (int | None)
axis_labels (list[str] | None)
layout_kws (dict | None)

Returns:

Interactive trajectory plot.

Return type:

plotly.graph_objects.Figure

See also

coco_pipe.viz.dim_reduction.plot_trajectory: Static Matplotlib version.
plot_trajectory_separation: Pairwise label-separation timecourses.
plot_trajectory_metric_series: Scalar metric timecourses per trajectory.
plot_embedding: Static embedding scatter for context.

Examples

>>> import numpy as np
>>> from coco_pipe.viz.interactive import dim_reduction as viz
>>> X = np.random.default_rng(42).normal(size=(3, 20, 2))
>>> fig = viz.plot_trajectory(X)
>>> sem = np.full_like(X, 0.3)
>>> fig = viz.plot_trajectory(X, sem=sem)

coco_pipe.viz.interactive.dim_reduction.plot_coranking_matrix(coranking_matrix, title='Co-Ranking Matrix', max_k=None)#

Plot a co-ranking matrix as an interactive heatmap.

Parameters:

coranking_matrix (numpy.ndarray) – Square co-ranking matrix with shape (n_samples-1, n_samples-1).
title (str) – Figure title.
max_k (int | None) – Crop the matrix to the top-left max_k x max_k corner. Defaults to min(n, 50).

Returns:

Interactive co-ranking matrix heatmap.

Return type:

plotly.graph_objects.Figure

See also

coco_pipe.viz.dim_reduction.plot_coranking_matrix: Static Matplotlib version.
plot_shepard_diagram: Distance-level quality diagnostic.
plot_metrics: Scalar trustworthiness and continuity summary.
plot_embedding: Embedding scatter for visual inspection.

Examples

>>> import numpy as np
>>> from coco_pipe.viz.interactive import dim_reduction as viz
>>> fig = viz.plot_coranking_matrix(np.eye(8))

coco_pipe.viz.interactive.dim_reduction.plot_trajectory_separation(separation, *, times=None, top_n=None, color_map=None, linestyle_map=None, smooth_window=1, title='Trajectory Separation', **layout_kwargs)#

Plot pairwise label-separation timecourses interactively.

Parameters:

separation (dict) – Mapping of (label_a, label_b) tuples (or any hashable key) to 1D separation timecourses.
times (numpy.ndarray | None) – Explicit time axis aligned with the separation arrays.
top_n (int | None) – Keep only the top_n pairs ranked by peak separation.
color_map (dict[tuple, str], optional)
linestyle_map (dict[tuple, str], optional)
title (str) – Figure title.
smooth_window (int)
layout_kwargs (Any)

Returns:

Interactive trajectory separation figure.

Return type:

plotly.graph_objects.Figure

See also

coco_pipe.viz.dim_reduction.plot_trajectory_separation: Static Matplotlib version.
plot_trajectory: Trajectory geometry in embedding space.
plot_trajectory_metric_series: Scalar metric timecourses per trajectory.

Examples

>>> import numpy as np
>>> from coco_pipe.viz.interactive import dim_reduction as viz
>>> sep = {("A", "B"): np.arange(10, dtype=float)}
>>> fig = viz.plot_trajectory_separation(sep)

coco_pipe.viz.interactive.dim_reduction.plot_phase_portrait(X, times, labels, component_idx=0, title='Phase Portrait')#

Plot a phase portrait (amplitude vs velocity) for condition-mean trajectories.

Parameters:

X (np.ndarray) – Trajectory array with shape (n_conditions, n_times, n_components).
times (np.ndarray) – One-dimensional time axis aligned with the time dimension of X.
labels (sequence of str) – Condition labels, one per trajectory (first axis of X).
component_idx (int, default=0) – Index of the component to extract for the portrait.
title (str, default="Phase Portrait") – Figure title.

Returns:

Interactive phase portrait figure.

Return type:

plotly.graph_objects.Figure

See also

plot_trajectory: Full trajectory geometry in 2D or 3D space.
plot_trajectory_metric_series: Scalar metric timecourses per trajectory.
coco_pipe.viz.dim_reduction.plot_phase_portrait: Static Matplotlib version.

Examples

>>> import numpy as np
>>> from coco_pipe.viz.interactive import dim_reduction as viz
>>> rng = np.random.default_rng(42)
>>> X = rng.normal(size=(3, 20, 5))
>>> times = np.linspace(0, 1, 20)
>>> fig = viz.plot_phase_portrait(X, times, labels=["A", "B", "C"])

coco_pipe.viz.interactive.dim_reduction.plot_component_loadings(components, feature_names=None, n_components=None, title='Component Loadings')#

Plot component loadings from linear reducers as an interactive heatmap.

Parameters:

components (numpy.ndarray) – Loading matrix with shape (n_features, n_components).
feature_names (list[str] | None) – Optional feature names for row labels.
n_components (int | None) – Crop to this many components (columns).
title (str) – Figure title.

Returns:

Interactive component-loadings heatmap.

Return type:

plotly.graph_objects.Figure

See also

coco_pipe.viz.dim_reduction.plot_component_loadings: Static Matplotlib version.
plot_feature_importance: Feature importance bar chart.
plot_feature_correlation_heatmap: Feature-to-dimension correlation heatmap.
plot_scree: Scree plot of explained variance per component.

Examples

>>> import numpy as np
>>> from coco_pipe.viz.interactive import dim_reduction as viz
>>> components = np.random.default_rng(42).normal(size=(10, 3))
>>> fig = viz.plot_component_loadings(components)