coco_pipe.viz.plotly_utils ========================== .. py:module:: coco_pipe.viz.plotly_utils .. autoapi-nested-parse:: Dim-Reduction Plotly Visualization ================================== Interactive plotting helpers for explicit dim-reduction embeddings, tidy metric records, trajectory tensors, and interpretation payloads. Functions --------- .. autoapisummary:: coco_pipe.viz.plotly_utils.plot_channel_traces_interactive coco_pipe.viz.plotly_utils.plot_embedding_interactive coco_pipe.viz.plotly_utils.plot_loss_history_interactive coco_pipe.viz.plotly_utils.plot_metric_details coco_pipe.viz.plotly_utils.plot_scree_interactive coco_pipe.viz.plotly_utils.plot_radar_comparison coco_pipe.viz.plotly_utils.plot_raw_preview coco_pipe.viz.plotly_utils.plot_shepard_interactive coco_pipe.viz.plotly_utils.plot_feature_importance_interactive coco_pipe.viz.plotly_utils.plot_feature_correlation_heatmap_interactive coco_pipe.viz.plotly_utils.plot_interpretation_interactive coco_pipe.viz.plotly_utils.plot_streamlines_interactive coco_pipe.viz.plotly_utils.plot_trajectory_metric_series_interactive coco_pipe.viz.plotly_utils.plot_trajectory_interactive Module Contents --------------- .. py:function:: plot_channel_traces_interactive(data: numpy.ndarray, times: Optional[numpy.ndarray] = None, group_labels: Optional[numpy.ndarray] = None, channel_names: Optional[collections.abc.Sequence[str] | numpy.ndarray] = None, selected_channels: Optional[collections.abc.Sequence[int] | collections.abc.Sequence[str]] = None, group_name_map: Optional[dict[Any, str]] = None, color_map: Optional[dict[Any, str]] = 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 Plot grouped channel traces as stacked interactive subplots. :param data: Three-dimensional array with shape ``(n_groups, n_channels, n_times)``. :type data: np.ndarray :param times: Explicit time axis aligned with the last dimension of ``data``. :type times: np.ndarray, optional :param group_labels: Labels aligned with the first axis of ``data``. :type group_labels: np.ndarray, optional :param channel_names: Channel names aligned with the channel axis. :type channel_names: sequence of str or np.ndarray, optional :param selected_channels: Channel indices or names to plot. When omitted, all channels are shown. :type selected_channels: sequence of int or sequence of str, optional :param group_name_map: Optional mapping from raw group labels to display names. :type group_name_map: dict, optional :param color_map: Optional mapping from raw group labels to trace colors. :type color_map: dict, optional :param title: Figure title. :type title: str, default="Grouped Channel Time Series" :param xaxis_title: X-axis label for the final row. :type xaxis_title: str, default="Time" :param yaxis_title: Y-axis label per subplot row. :type yaxis_title: str, default="Amplitude" :param template: Plotly layout template. :type template: str, default="plotly_white" :param shared_xaxes: Whether subplot rows share the same x-axis. :type shared_xaxes: bool, default=True :param vertical_spacing: Vertical spacing between subplot rows. :type vertical_spacing: float, default=0.05 :param line_width: Trace line width. :type line_width: float, default=2.0 :param opacity: Trace opacity. :type opacity: float, default=1.0 :param base_height: Base figure height before row scaling. :type base_height: int, default=300 :param row_height: Additional height per plotted row. :type row_height: int, default=220 :param showlegend: Whether to show the legend. :type showlegend: bool, default=True :returns: Interactive multi-row channel trace figure. :rtype: plotly.graph_objects.Figure :raises ValueError: If the input shape or aligned labels/names are invalid. :raises TypeError: If ``selected_channels`` contains unsupported selector types. .. py:function:: plot_embedding_interactive(embedding: numpy.ndarray, labels: Optional[numpy.ndarray] = None, metadata: Optional[dict[str, Any]] = None, title: str = 'Embedding', dimensions: int = 2, cmap: str = 'Viridis', palette: Optional[str | collections.abc.Sequence[str]] = None, random_state: Optional[int] = None) -> plotly.graph_objects.Figure Create an interactive 2D or 3D scatter plot of an embedding. :param embedding: Embedding array with shape ``(n_samples, n_dimensions)``. :type embedding: np.ndarray :param labels: Optional values aligned with the sample axis. :type labels: np.ndarray, optional :param metadata: Optional column-oriented metadata aligned with the sample axis. :type metadata: dict, optional :param title: Figure title. :type title: str, default="Embedding" :param dimensions: Number of embedding dimensions to plot. Must be 2 or 3. :type dimensions: int, default=2 :param cmap: Continuous colormap name. :type cmap: str, default="Viridis" :param palette: Discrete color palette used for categorical columns. :type palette: str or sequence of str, optional :param random_state: Reserved for compatibility with data-first static/interactive APIs. :type random_state: int, optional :returns: Interactive embedding scatter plot. :rtype: plotly.graph_objects.Figure .. seealso:: :obj:`prepare_embedding_frame`, :obj:`coco_pipe.viz.dim_reduction.plot_embedding` .. py:function:: plot_loss_history_interactive(loss_history: list, title: str = 'Training Loss') -> plotly.graph_objects.Figure Plot training loss history. .. py:function:: plot_metric_details(metrics_df: Any, title: str = 'Metric Details', plot_type: str = 'auto', metric: Optional[str] = None, scope: Optional[str] = None, method: Optional[str | collections.abc.Sequence[str]] = None) -> plotly.graph_objects.Figure Create an interactive metric plot from tidy metric observations. :param metrics_df: Metric mapping, tidy metric frame, list of records, or object exposing ``to_frame()``. :type metrics_df: Any :param title: Figure title. :type title: str, default="Metric Details" :param plot_type: Plot style to use. ``"auto"`` infers a suitable 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: Interactive metric plot. :rtype: plotly.graph_objects.Figure .. seealso:: :obj:`prepare_metrics_frame`, :obj:`infer_metric_plot_type`, :obj:`coco_pipe.viz.dim_reduction.plot_metrics` .. py:function:: plot_scree_interactive(explained_variance_ratio: numpy.ndarray) -> plotly.graph_objects.Figure Plot explained variance and cumulative variance interactively. :param explained_variance_ratio: One-dimensional array of explained variance ratios. :type explained_variance_ratio: np.ndarray :returns: Interactive scree plot. :rtype: plotly.graph_objects.Figure .. py:function:: plot_radar_comparison(metrics_df: pandas.DataFrame, normalize: bool = True, title: str = 'Method Comparison') -> plotly.graph_objects.Figure Create a radar chart comparing methods across scalar metrics. :param metrics_df: Wide comparison table indexed by method with numeric metric columns. :type metrics_df: pandas.DataFrame :param normalize: Whether to normalize each numeric metric column to ``[0, 1]`` before plotting. :type normalize: bool, default=True :param title: Figure title. :type title: str, default="Method Comparison" :returns: Interactive radar comparison figure. :rtype: plotly.graph_objects.Figure .. rubric:: Notes Radar charts are overview visuals. They are less precise than line plots, tables, or heatmaps for detailed method comparisons. .. py:function:: plot_raw_preview(data: numpy.ndarray, names: Optional[list] = None, title: str = 'Raw Data Preview', max_points: int = 50000) -> plotly.graph_objects.Figure Create a scrollable preview of multichannel raw traces. :param data: Two-dimensional array with shape ``(n_samples, n_channels)``. :type data: np.ndarray :param names: Optional channel names aligned with the channel axis. :type names: list, optional :param title: Figure title. :type title: str, default="Raw Data Preview" :param max_points: Soft limit used to subsample very large inputs for display. :type max_points: int, default=50000 :returns: Interactive raw-trace preview with a range slider. :rtype: plotly.graph_objects.Figure .. py:function:: plot_shepard_interactive(X_orig: numpy.ndarray, X_emb: numpy.ndarray, sample_size: int = 1000, title: str = 'Shepard Diagram', random_state: Optional[int] = None, distances: Optional[dict[str, numpy.ndarray]] = None, clip_quantiles: Optional[tuple[float, float]] = (0.01, 0.99), scatter_max_points: int = 4000, scatter_opacity: float = 0.14) -> plotly.graph_objects.Figure Create an interactive Shepard diagram using Plotly. .. py:function:: plot_feature_importance_interactive(scores: Any, title: str = 'Feature Importance', top_n: int = 20, analysis: Optional[str] = None, method: Optional[str] = None, dimension: Optional[str] = None) -> plotly.graph_objects.Figure Plot feature importance as an interactive 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 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 multiple dimensions are present. :type dimension: str, optional :returns: Interactive feature-importance bar chart. :rtype: plotly.graph_objects.Figure .. seealso:: :obj:`prepare_feature_scores`, :obj:`plot_interpretation_interactive`, :obj:`coco_pipe.viz.dim_reduction.plot_feature_importance` .. py:function:: plot_feature_correlation_heatmap_interactive(correlations: Any, title: str = 'Feature Correlation', top_n: Optional[int] = 25, method: Optional[str] = None) -> plotly.graph_objects.Figure Plot feature-to-dimension correlations as an interactive 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 method: Method name to select when multiple methods are present. :type method: str, optional :returns: Interactive feature-correlation heatmap. :rtype: plotly.graph_objects.Figure .. seealso:: :obj:`prepare_interpretation_frame`, :obj:`plot_interpretation_interactive`, :obj:`coco_pipe.viz.dim_reduction.plot_feature_correlation_heatmap` .. py:function:: plot_interpretation_interactive(interpretation: Any, *, analysis: str, title: Optional[str] = None, method: Optional[str] = None, dimension: Optional[str] = None, top_n: int = 20) -> plotly.graph_objects.Figure Plot one interpretation analysis using an interactive Plotly view. :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 method: Method name to select when multiple methods are present. :type method: str, optional :param dimension: Dimension label to select when multiple dimensions are present. :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: Interactive interpretation figure. :rtype: plotly.graph_objects.Figure .. seealso:: :obj:`plot_feature_importance_interactive`, :obj:`plot_feature_correlation_heatmap_interactive`, :obj:`coco_pipe.viz.dim_reduction.plot_interpretation` .. py:function:: plot_streamlines_interactive(X_emb: numpy.ndarray, V_emb: numpy.ndarray, grid_density: int = 25, title: str = 'Velocity Streamlines', random_state: Optional[int] = None) -> plotly.graph_objects.Figure Plot a velocity vector field using Plotly line segments. .. py:function:: plot_trajectory_metric_series_interactive(series: Any, *, times: Optional[numpy.ndarray] = None, labels: Optional[numpy.ndarray] = None, title: str = 'Trajectory Metric', ylabel: str = 'Value') -> plotly.graph_objects.Figure Plot evaluated trajectory metric time series interactively. :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" :returns: Interactive trajectory metric series figure. :rtype: plotly.graph_objects.Figure .. seealso:: :obj:`coco_pipe.viz.dim_reduction.plot_trajectory_metric_series` .. py:function:: plot_trajectory_interactive(X: numpy.ndarray, times: Optional[numpy.ndarray] = None, labels: Optional[numpy.ndarray] = None, values: Optional[numpy.ndarray] = None, title: str = 'Trajectory Plot', dimensions: int = 2, smooth_window: Optional[int] = None) -> plotly.graph_objects.Figure Plot already-prepared native trajectory tensors interactively. :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 labels: Optional label per trajectory. :type labels: np.ndarray, optional :param values: Optional scalar overlay with shape ``(n_trajectories, n_times)``. :type values: np.ndarray, optional :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 smooth_window: Moving-average window applied independently to each already-valid trajectory when greater than 1. :type smooth_window: int, optional :returns: Interactive trajectory plot. :rtype: 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. .. seealso:: :obj:`plot_trajectory_metric_series_interactive`, :obj:`coco_pipe.viz.dim_reduction.plot_trajectory`