coco_pipe.viz.utils =================== .. py:module:: coco_pipe.viz.utils .. autoapi-nested-parse:: Dim-Reduction Visualization Utilities ===================================== Shared normalization helpers for the explicit, data-first dim-reduction plotting API. Functions --------- .. autoapisummary:: coco_pipe.viz.utils.is_categorical coco_pipe.viz.utils.filter_metrics coco_pipe.viz.utils.prepare_embedding_frame coco_pipe.viz.utils.prepare_metrics_frame coco_pipe.viz.utils.prepare_interpretation_frame coco_pipe.viz.utils.prepare_feature_scores coco_pipe.viz.utils.extract_interpretation_matrix coco_pipe.viz.utils.filter_metric_frame coco_pipe.viz.utils.infer_metric_plot_type Module Contents --------------- .. py:function:: is_categorical(labels: collections.abc.Sequence[Any] | numpy.ndarray, max_unique_numeric: int = 20) -> bool Return whether a label array should be treated as categorical. :param labels: Labels or values to inspect. :type labels: array-like :param max_unique_numeric: Maximum number of unique numeric values still treated as categorical. :type max_unique_numeric: int, default=20 :returns: True when the values should be visualized as categories. :rtype: bool .. py:function:: filter_metrics(scores: collections.abc.Mapping[str, Any]) -> dict[str, float] Keep scalar numeric metrics suitable for plotting. :param scores: Metric mapping. :type scores: mapping :returns: Numeric scalar metrics only. :rtype: dict .. py:function:: prepare_embedding_frame(embedding: numpy.ndarray, labels: Optional[collections.abc.Sequence[Any]] = None, metadata: Optional[collections.abc.Mapping[str, Any]] = None, dimensions: int = 2) -> pandas.DataFrame Convert embedding coordinates and aligned metadata into a plotting frame. :param embedding: Embedding array with shape ``(n_samples, n_dimensions)``. :type embedding: np.ndarray :param labels: Optional label array aligned with samples. :type labels: sequence, optional :param metadata: Optional column-oriented metadata aligned with samples. :type metadata: mapping, optional :param dimensions: Number of embedding dimensions to expose in the frame. Must be 2 or 3. :type dimensions: int, default=2 :returns: Frame with columns ``x``, ``y`` and optionally ``z`` plus label and metadata columns. :rtype: pandas.DataFrame :raises ValueError: If the embedding is not 2D, if ``dimensions`` is unsupported, or if aligned arrays do not match the sample axis. .. py:function:: prepare_metrics_frame(metrics: Any, default_method: str = 'Method') -> pandas.DataFrame Normalize metric inputs into a tidy long-form frame. Output columns always include: ``method``, ``metric``, ``value``, ``scope``, and ``scope_value``. .. py:function:: prepare_interpretation_frame(interpretation: Any, default_method: str = 'embedding') -> pandas.DataFrame Normalize interpretation payloads and records into a tidy frame. :param interpretation: One of: - interpretation result with ``records`` or ``analysis`` keys - list of interpretation records - tidy interpretation DataFrame - raw correlation payload - raw feature-importance mapping :type interpretation: Any :param default_method: Method name used when raw payloads do not contain one. :type default_method: str, default="embedding" :returns: Tidy frame with at least ``method``, ``analysis``, ``feature``, and ``value`` columns. Correlation rows also carry ``dimension``. :rtype: pandas.DataFrame .. py:function:: prepare_feature_scores(interpretation: Any, *, analysis: Optional[str] = None, method: Optional[str] = None, dimension: Optional[str] = None) -> pandas.Series Reduce interpretation payloads to one feature-score series. :param interpretation: Raw feature-score mapping or normalized interpretation payload. :type interpretation: Any :param analysis: Interpretation analysis to keep when multiple analyses are present. :type analysis: str, optional :param method: Method name to keep when multiple methods are present. :type method: str, optional :param dimension: Dimension label to keep when the interpretation contains multiple dimensions. :type dimension: str, optional :returns: Feature scores indexed by feature name, sorted descending. :rtype: pandas.Series :raises ValueError: If multiple analyses, methods, or dimensions are present and no explicit selector is provided. .. py:function:: extract_interpretation_matrix(interpretation: Any, *, analysis: str) -> Optional[numpy.ndarray] Extract a matrix-style interpretation payload when one is available. :param interpretation: Interpretation payload or wrapper containing an ``analysis`` mapping. :type interpretation: Any :param analysis: Analysis key to extract. :type analysis: str :returns: Interpretation matrix when present, otherwise ``None``. :rtype: np.ndarray or None .. py:function:: filter_metric_frame(metrics_df: pandas.DataFrame, *, metric: Optional[str] = None, scope: Optional[str] = None, method: Optional[str | collections.abc.Sequence[str]] = None) -> pandas.DataFrame Filter a tidy metric frame by metric, scope, and method. :param metrics_df: Tidy metric frame from :func:`prepare_metrics_frame`. :type metrics_df: pandas.DataFrame :param metric: Metric name to keep. :type metric: str, optional :param scope: Scope name to keep. :type scope: str, optional :param method: Method name or names to keep. :type method: str or sequence of str, optional :returns: Filtered frame. :rtype: pandas.DataFrame .. py:function:: infer_metric_plot_type(metrics_df: pandas.DataFrame, requested: Optional[str] = None) -> str Choose a sensible default plot type from filtered metric observations. :param metrics_df: Already-filtered tidy metric frame. :type metrics_df: pandas.DataFrame :param requested: Explicit requested plot type. :type requested: str, optional :returns: Resolved plot type. :rtype: str