coco_pipe.viz.dim_reduction =========================== .. py:module:: coco_pipe.viz.dim_reduction .. autoapi-nested-parse:: Dim-Reduction Matplotlib Visualization ====================================== 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 --------- .. autoapisummary:: coco_pipe.viz.dim_reduction.plot_embedding coco_pipe.viz.dim_reduction.plot_metrics coco_pipe.viz.dim_reduction.plot_loss_history coco_pipe.viz.dim_reduction.plot_eigenvalues coco_pipe.viz.dim_reduction.plot_shepard_diagram coco_pipe.viz.dim_reduction.plot_streamlines coco_pipe.viz.dim_reduction.plot_feature_importance coco_pipe.viz.dim_reduction.plot_feature_correlation_heatmap coco_pipe.viz.dim_reduction.plot_interpretation coco_pipe.viz.dim_reduction.plot_trajectory_metric_series coco_pipe.viz.dim_reduction.plot_trajectory coco_pipe.viz.dim_reduction.plot_local_metrics Module Contents --------------- .. py:function:: plot_embedding(X_emb: numpy.ndarray, labels: Optional[numpy.ndarray] = None, metadata: Optional[Dict[str, Any]] = None, dims: Union[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: Optional[Dict[str, Any]] = None, ax: Optional[matplotlib.pyplot.Axes] = None, save_path: Optional[str] = None, interactive: bool = False, random_state: Optional[int] = None) -> Union[matplotlib.pyplot.Figure, Any] Plot an explicit embedding with optional labels and metadata. :param X_emb: Embedding array with shape ``(n_samples, n_dimensions)``. :type X_emb: np.ndarray :param labels: Optional values aligned with the sample axis. Categorical values are shown with a legend and continuous values with a colorbar. :type labels: np.ndarray, optional :param metadata: Optional column-oriented metadata aligned with the sample axis. :type metadata: dict, optional :param dims: Embedding dimensions to visualize. Length must be 2 or 3. :type dims: tuple of int, default=(0, 1) :param title: Figure title. :type title: str, default="Embedding" :param figsize: Matplotlib figure size for static plots. :type figsize: tuple of int, default=(10, 8) :param cmap: Colormap for continuous labels or value overlays. :type cmap: str, default="viridis" :param palette: Seaborn categorical palette name. :type palette: str, default="deep" :param s: Marker size. :type s: int, default=40 :param alpha: Marker opacity. :type alpha: float, default=0.8 :param metrics: Optional scalar metrics to annotate on the figure. :type metrics: dict, optional :param ax: Existing axes to draw on. :type ax: matplotlib.axes.Axes, optional :param save_path: Optional file path for saving the static figure. :type save_path: str, optional :param interactive: If ``True``, return the Plotly equivalent. :type interactive: bool, default=False :param random_state: Random seed used by the interactive path when sampling is needed. :type random_state: int, optional :returns: Matplotlib figure for static plots or the Plotly figure returned by the interactive backend. :rtype: matplotlib.figure.Figure or Any :raises ValueError: If the embedding is not 2D or the requested dimensions are invalid. .. seealso:: :obj:`plotly_utils.plot_embedding_interactive`, :obj:`prepare_embedding_frame`, :obj:`plot_metrics` .. py:function:: plot_metrics(scores: Any, title: str = 'Quality Metrics', figsize: Tuple[int, int] = (8, 6), ax: Optional[matplotlib.pyplot.Axes] = None, interactive: bool = False, plot_type: str = 'auto', metric: Optional[str] = None, scope: Optional[str] = None, method: Optional[Union[str, Sequence[str]]] = None) -> Union[matplotlib.pyplot.Figure, Any] Plot tidy metric observations using one shared entrypoint. :param scores: Metric mapping, tidy metric frame, list of records, or object exposing ``to_frame()``. :type scores: Any :param title: Figure title. :type title: str, default="Quality Metrics" :param figsize: Matplotlib figure size for static plots. :type figsize: tuple of int, default=(8, 6) :param ax: Existing axes to draw on. :type ax: matplotlib.axes.Axes, optional :param interactive: If ``True``, return the Plotly equivalent. :type interactive: bool, default=False :param plot_type: Plot style to use. ``"auto"`` infers an appropriate view from the filtered metric records. :type plot_type: str, default="auto" :param metric: Restrict plotting to one metric. :type metric: str, optional :param scope: Restrict plotting to one scope. :type scope: str, optional :param method: Restrict plotting to one or more methods. :type method: str or sequence of str, optional :returns: Matplotlib figure for static plots or the Plotly figure returned by the interactive backend. :rtype: matplotlib.figure.Figure or Any :raises ValueError: If no metrics remain after filtering. .. seealso:: :obj:`plotly_utils.plot_metric_details`, :obj:`prepare_metrics_frame`, :obj:`infer_metric_plot_type` .. py:function:: plot_loss_history(loss_history: list, title: str = 'Training Loss', figsize: Tuple[int, int] = (8, 5), ax: Optional[matplotlib.pyplot.Axes] = None, interactive: bool = False) -> Union[matplotlib.pyplot.Figure, Any] Plot training loss over epochs. :param loss_history: List of loss values. :type loss_history: list :param title: Plot title, by default "Training Loss". :type title: str, optional :param figsize: Figure size, by default (8, 5). :type figsize: tuple, optional :param ax: Existing axes to plot on. :type ax: plt.Axes, optional :param interactive: If True, returns a Plotly figure. :type interactive: bool, optional :returns: Matplotlib figure for static plots or the Plotly figure returned by the interactive backend. :rtype: matplotlib.figure.Figure or Any .. seealso:: :obj:`plotly_utils.plot_loss_history_interactive` .. py:function:: plot_eigenvalues(values: numpy.ndarray, title: str = 'Scree Plot', ylabel: str = 'Explained Variance', figsize: Tuple[int, int] = (8, 5), ax: Optional[matplotlib.pyplot.Axes] = None, interactive: bool = False) -> Union[matplotlib.pyplot.Figure, Any] Plot Scree plot of eigenvalues or explained variance. :param values: Array of eigenvalues or variance ratios. :type values: np.ndarray :param title: Plot title, by default "Scree Plot". :type title: str, optional :param ylabel: Label for y-axis, by default "Explained Variance". :type ylabel: str, optional :param figsize: Figure size, by default (8, 5). :type figsize: tuple, optional :param ax: Existing axes to plot on. :type ax: plt.Axes, optional :param interactive: If True, returns a Plotly figure. :type interactive: bool, optional :returns: Matplotlib figure for static plots or the Plotly figure returned by the interactive backend. :rtype: matplotlib.figure.Figure or Any .. seealso:: :obj:`plotly_utils.plot_scree_interactive` .. py:function:: plot_shepard_diagram(X_orig: numpy.ndarray, X_emb: numpy.ndarray, sample_size: int = 1000, title: str = 'Shepard Diagram', ax: Optional[matplotlib.pyplot.Axes] = None, interactive: bool = False, random_state: Optional[int] = None, distances: Optional[Dict[str, numpy.ndarray]] = None) -> Union[matplotlib.pyplot.Figure, Any] Plot Shepard Diagram (Original vs Embedded Distances). :param X_orig: Original high-dimensional data. :type X_orig: np.ndarray :param X_emb: Embedded low-dimensional data. :type X_emb: np.ndarray :param sample_size: Number of points to sample for distance calculation (to speed up), by default 1000. :type sample_size: int, optional :param title: Plot title, by default "Shepard Diagram". :type title: str, optional :param ax: Existing axes to plot on. :type ax: plt.Axes, optional :param interactive: If True, returns a Plotly figure. :type interactive: bool, optional :returns: Matplotlib figure for static plots or the Plotly figure returned by the interactive backend. :rtype: matplotlib.figure.Figure or Any .. seealso:: :obj:`plotly_utils.plot_shepard_interactive` .. py:function:: plot_streamlines(X_emb: numpy.ndarray, V_emb: numpy.ndarray, grid_density: int = 25, title: str = 'Velocity Streamlines', ax: Optional[matplotlib.pyplot.Axes] = None, interactive: bool = False, random_state: Optional[int] = None) -> Union[matplotlib.pyplot.Figure, Any] Plot streamlines of a vector field on the embedding. :param X_emb: Coordinates of the embedding (2D only). :type X_emb: np.ndarray :param V_emb: Velocity vectors in the embedding space. :type V_emb: np.ndarray :param grid_density: Density of the grid for interpolation, by default 25. :type grid_density: int, optional :param title: Plot title, by default "Velocity Streamlines". :type title: str, optional :param ax: Existing axes to plot on. :type ax: plt.Axes, optional :param interactive: If True, returns a Plotly figure. :type interactive: bool, optional :returns: Matplotlib figure for static plots or the Plotly figure returned by the interactive backend. :rtype: matplotlib.figure.Figure or Any :raises ValueError: If X_emb is not 2D. .. seealso:: :obj:`plotly_utils.plot_streamlines_interactive` .. py:function:: plot_feature_importance(scores: Any, title: str = 'Feature Importance', top_n: int = 20, figsize: Tuple[int, int] = (8, 6), ax: Optional[matplotlib.pyplot.Axes] = None, interactive: bool = False, analysis: Optional[str] = None, method: Optional[str] = None, dimension: Optional[str] = None) -> Union[matplotlib.pyplot.Figure, Any] Plot feature-importance scores as a horizontal bar chart. :param scores: Raw ``feature -> score`` mapping, interpretation payload, or interpretation record table. :type scores: Any :param title: Figure title. :type title: str, default="Feature Importance" :param top_n: Maximum number of features to show. :type top_n: int, default=20 :param figsize: Matplotlib figure size for static plots. :type figsize: tuple of int, default=(8, 6) :param ax: Existing axes to draw on. :type ax: matplotlib.axes.Axes, optional :param interactive: If ``True``, return the Plotly equivalent. :type interactive: bool, default=False :param analysis: Interpretation analysis to select when multiple analyses are present. :type analysis: str, optional :param method: Method name to select when multiple methods are present. :type method: str, optional :param dimension: Dimension label to select when the interpretation contains multiple dimensions. :type dimension: str, optional :returns: Matplotlib figure for static plots or the Plotly figure returned by the interactive backend. :rtype: matplotlib.figure.Figure or Any .. seealso:: :obj:`prepare_feature_scores`, :obj:`plot_interpretation`, :obj:`plotly_utils.plot_feature_importance_interactive` .. py:function:: plot_feature_correlation_heatmap(correlations: Any, title: str = 'Feature Correlation', top_n: Optional[int] = 25, figsize: Tuple[int, int] = (10, 8), ax: Optional[matplotlib.pyplot.Axes] = None, interactive: bool = False, method: Optional[str] = None) -> Union[matplotlib.pyplot.Figure, Any] Plot feature-to-dimension correlations as a heatmap. :param correlations: Correlation interpretation payload or records. :type correlations: Any :param title: Figure title. :type title: str, default="Feature Correlation" :param top_n: Maximum number of features to show. Features are ranked by the maximum absolute correlation across dimensions. :type top_n: int, optional :param figsize: Matplotlib figure size for static plots. :type figsize: tuple of int, default=(10, 8) :param ax: Existing axes to draw on. :type ax: matplotlib.axes.Axes, optional :param interactive: If ``True``, return the Plotly equivalent. :type interactive: bool, default=False :param method: Method name to select when multiple methods are present. :type method: str, optional :returns: Matplotlib figure for static plots or the Plotly figure returned by the interactive backend. :rtype: matplotlib.figure.Figure or Any .. seealso:: :obj:`plot_interpretation`, :obj:`plotly_utils.plot_feature_correlation_heatmap_interactive` .. py:function:: plot_interpretation(interpretation: Any, *, analysis: str, title: Optional[str] = None, figsize: Tuple[int, int] = (10, 8), ax: Optional[matplotlib.pyplot.Axes] = None, interactive: bool = False, method: Optional[str] = None, dimension: Optional[str] = None, top_n: int = 20) -> Union[matplotlib.pyplot.Figure, Any] Plot one interpretation analysis using an appropriate visualization. :param interpretation: Interpretation payload or interpretation records. :type interpretation: Any :param analysis: Interpretation analysis to plot. :type analysis: str :param title: Figure title. Defaults to a title derived from ``analysis``. :type title: str, optional :param figsize: Matplotlib figure size for static plots. :type figsize: tuple of int, default=(10, 8) :param ax: Existing axes to draw on. :type ax: matplotlib.axes.Axes, optional :param interactive: If ``True``, return the Plotly equivalent. :type interactive: bool, default=False :param method: Method name to select when multiple methods are present. :type method: str, optional :param dimension: Dimension label to select when the interpretation contains multiple dimensions. :type dimension: str, optional :param top_n: Maximum number of features to show in bar or heatmap views. :type top_n: int, default=20 :returns: Matplotlib figure for static plots or the Plotly figure returned by the interactive backend. :rtype: matplotlib.figure.Figure or Any .. seealso:: :obj:`plot_feature_importance`, :obj:`plot_feature_correlation_heatmap`, :obj:`plotly_utils.plot_interpretation_interactive` .. py:function:: plot_trajectory_metric_series(series: Any, *, times: Optional[numpy.ndarray] = None, labels: Optional[numpy.ndarray] = None, title: str = 'Trajectory Metric', ylabel: str = 'Value', figsize: Tuple[int, int] = (10, 6), ax: Optional[matplotlib.pyplot.Axes] = None, interactive: bool = False) -> Union[matplotlib.pyplot.Figure, Any] Plot evaluated trajectory metric time series. :param series: One-dimensional series, two-dimensional ``(trajectory, time)`` array, or mapping of ``name -> timecourse``. :type series: Any :param times: Explicit time axis aligned with the time dimension. :type times: np.ndarray, optional :param labels: Optional trajectory labels aligned with the first axis of 2D inputs. :type labels: np.ndarray, optional :param title: Figure title. :type title: str, default="Trajectory Metric" :param ylabel: Y-axis label. :type ylabel: str, default="Value" :param figsize: Matplotlib figure size for static plots. :type figsize: tuple of int, default=(10, 6) :param ax: Existing axes to draw on. :type ax: matplotlib.axes.Axes, optional :param interactive: If ``True``, return the Plotly equivalent. :type interactive: bool, default=False :returns: Matplotlib figure for static plots or the Plotly figure returned by the interactive backend. :rtype: matplotlib.figure.Figure or Any .. seealso:: :obj:`plot_trajectory`, :obj:`plotly_utils.plot_trajectory_metric_series_interactive` .. py:function:: plot_trajectory(X: numpy.ndarray, times: Optional[numpy.ndarray] = None, values: Optional[numpy.ndarray] = None, labels: Optional[numpy.ndarray] = None, smooth_window: int = 1, title: str = 'Trajectory Plot', dimensions: int = 2, figsize: Tuple[int, int] = (10, 8), ax: Optional[matplotlib.pyplot.Axes] = None, interactive: bool = False, cmap: str = 'viridis') -> Union[matplotlib.pyplot.Figure, Any] Plot already-prepared native trajectory tensors. :param X: Trajectory tensor with shape ``(n_trajectories, n_times, n_dimensions)``. :type X: np.ndarray :param times: Explicit time axis aligned with the time dimension. :type times: np.ndarray, optional :param values: Optional scalar overlay with shape ``(n_trajectories, n_times)``. :type values: np.ndarray, optional :param labels: Optional label per trajectory. :type labels: np.ndarray, optional :param smooth_window: Moving-average window applied independently to each already-valid trajectory when greater than 1. :type smooth_window: int, default=1 :param title: Figure title. :type title: str, default="Trajectory Plot" :param dimensions: Number of embedding dimensions to display. Must be 2 or 3. :type dimensions: int, default=2 :param figsize: Matplotlib figure size for static plots. :type figsize: tuple of int, default=(10, 8) :param ax: Existing axes to draw on. :type ax: matplotlib.axes.Axes, optional :param interactive: If ``True``, return the Plotly equivalent. :type interactive: bool, default=False :param cmap: Colormap used for scalar overlays. :type cmap: str, default="viridis" :returns: Matplotlib figure for static plots or the Plotly figure returned by the interactive backend. :rtype: 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. .. seealso:: :obj:`plot_trajectory_metric_series`, :obj:`plotly_utils.plot_trajectory_interactive` .. py:function:: plot_local_metrics(X_emb: numpy.ndarray, local_scores: numpy.ndarray, title: str = 'Local Quality Map', cmap: str = 'RdYlGn', ax: Optional[matplotlib.pyplot.Axes] = None) -> matplotlib.pyplot.Figure Plot the embedding colored by local quality (e.g. point-wise trustworthiness). :param X_emb: Embedding coordinates (2D). :type X_emb: np.ndarray :param local_scores: Score per sample. :type local_scores: np.ndarray :param title: Plot title. :type title: str :param cmap: Colormap (Green=Good, Red=Bad). :type cmap: str :returns: Static figure colored by the provided local scores. :rtype: matplotlib.figure.Figure .. seealso:: :obj:`plot_embedding`