coco_pipe.viz.dim_reduction

Matplotlib plotting helpers for explicit embeddings, tidy evaluation records, trajectory diagnostics, and interpretation payloads.

The functions in this module accept arrays, mappings, or tidy tables directly. They do not depend on manager-owned embedding or context state.

Functions

plot_embedding(, title, figsize, int] =, cmap, ...)	Plot an explicit embedding with optional labels and metadata.
plot_metrics(, ax, interactive, plot_type, metric, ...)	Plot tidy metric observations using one shared entrypoint.
plot_loss_history(, ax, interactive, Any])	Plot training loss over epochs.
plot_eigenvalues(, ax, interactive, Any])	Plot Scree plot of eigenvalues or explained variance.
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_feature_importance(, ax, interactive, analysis, ...)	Plot feature-importance scores as a horizontal bar chart.
plot_feature_correlation_heatmap(, ax, interactive, ...)	Plot feature-to-dimension correlations as a heatmap.
plot_interpretation(, ax, interactive, method, ...)	Plot one interpretation analysis using an appropriate visualization.
plot_trajectory_metric_series(, ax, interactive, Any])	Plot evaluated trajectory metric time series.
plot_trajectory(, ax, interactive, cmap, Any])	Plot already-prepared native trajectory tensors.
plot_local_metrics(→ matplotlib.pyplot.Figure)	Plot the embedding colored by local quality (e.g. point-wise trustworthiness).

Module Contents

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

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.dim_reduction.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

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.dim_reduction.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

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

See also

plotly_utils.plot_loss_history_interactive

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

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.dim_reduction.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

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.dim_reduction.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

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.

See also

plotly_utils.plot_streamlines_interactive

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

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

See also

prepare_feature_scores, plot_interpretation, plotly_utils.plot_feature_importance_interactive

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

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

See also

plot_interpretation, plotly_utils.plot_feature_correlation_heatmap_interactive

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

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

See also

plot_feature_importance, plot_feature_correlation_heatmap, plotly_utils.plot_interpretation_interactive

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

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

See also

plot_trajectory, plotly_utils.plot_trajectory_metric_series_interactive

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

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.

See also

plot_trajectory_metric_series, plotly_utils.plot_trajectory_interactive

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

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