coco_pipe.viz.utils

Shared normalization helpers for the explicit, data-first dim-reduction plotting API.

Functions

is_categorical(→ bool)	Return whether a label array should be treated as categorical.
filter_metrics(→ dict[str, float])	Keep scalar numeric metrics suitable for plotting.
prepare_embedding_frame(→ pandas.DataFrame)	Convert embedding coordinates and aligned metadata into a plotting frame.
prepare_metrics_frame(→ pandas.DataFrame)	Normalize metric inputs into a tidy long-form frame.
prepare_interpretation_frame(→ pandas.DataFrame)	Normalize interpretation payloads and records into a tidy frame.
prepare_feature_scores(→ pandas.Series)	Reduce interpretation payloads to one feature-score series.
extract_interpretation_matrix(→ Optional[numpy.ndarray])	Extract a matrix-style interpretation payload when one is available.
filter_metric_frame(→ pandas.DataFrame)	Filter a tidy metric frame by metric, scope, and method.
infer_metric_plot_type(→ str)	Choose a sensible default plot type from filtered metric observations.

Module Contents

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

Parameters:

• labels (array-like) – Labels or values to inspect.

• max_unique_numeric (int, default=20) – Maximum number of unique numeric values still treated as categorical.

Returns:

True when the values should be visualized as categories.

Return type:

bool

coco_pipe.viz.utils.filter_metrics(scores: collections.abc.Mapping[str, Any]) → dict[str, float]

Keep scalar numeric metrics suitable for plotting.

Parameters:

scores (mapping) – Metric mapping.

Returns:

Numeric scalar metrics only.

Return type:

dict

coco_pipe.viz.utils.prepare_embedding_frame(embedding: numpy.ndarray, labels: collections.abc.Sequence[Any] | None = None, metadata: collections.abc.Mapping[str, Any] | None = None, dimensions: int = 2) → pandas.DataFrame

Convert embedding coordinates and aligned metadata into a plotting frame.

Parameters:

• embedding (np.ndarray) – Embedding array with shape (n_samples, n_dimensions).

• labels (sequence, optional) – Optional label array aligned with samples.

• metadata (mapping, optional) – Optional column-oriented metadata aligned with samples.

• dimensions (int, default=2) – Number of embedding dimensions to expose in the frame. Must be 2 or 3.

Returns:

Frame with columns x, y and optionally z plus label and metadata columns.

Return type:

pandas.DataFrame

Raises:

ValueError – If the embedding is not 2D, if dimensions is unsupported, or if aligned arrays do not match the sample axis.

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

coco_pipe.viz.utils.prepare_interpretation_frame(interpretation: Any, default_method: str = 'embedding') → pandas.DataFrame

Normalize interpretation payloads and records into a tidy frame.

Parameters:

• interpretation (Any) –

  One of:

  • interpretation result with records or analysis keys

  • list of interpretation records

  • tidy interpretation DataFrame

  • raw correlation payload

  • raw feature-importance mapping

• default_method (str, default="embedding") – Method name used when raw payloads do not contain one.

Returns:

Tidy frame with at least method, analysis, feature, and value columns. Correlation rows also carry dimension.

Return type:

pandas.DataFrame

coco_pipe.viz.utils.prepare_feature_scores(interpretation: Any, *, analysis: str | None = None, method: str | None = None, dimension: str | None = None) → pandas.Series

Reduce interpretation payloads to one feature-score series.

Parameters:

• interpretation (Any) – Raw feature-score mapping or normalized interpretation payload.

• analysis (str, optional) – Interpretation analysis to keep when multiple analyses are present.

• method (str, optional) – Method name to keep when multiple methods are present.

• dimension (str, optional) – Dimension label to keep when the interpretation contains multiple dimensions.

Returns:

Feature scores indexed by feature name, sorted descending.

Return type:

pandas.Series

Raises:

ValueError – If multiple analyses, methods, or dimensions are present and no explicit selector is provided.

coco_pipe.viz.utils.extract_interpretation_matrix(interpretation: Any, *, analysis: str) → numpy.ndarray | None

Extract a matrix-style interpretation payload when one is available.

Parameters:

• interpretation (Any) – Interpretation payload or wrapper containing an analysis mapping.

• analysis (str) – Analysis key to extract.

Returns:

Interpretation matrix when present, otherwise None.

Return type:

np.ndarray or None

coco_pipe.viz.utils.filter_metric_frame(metrics_df: pandas.DataFrame, *, metric: str | None = None, scope: str | None = None, method: str | collections.abc.Sequence[str] | None = None) → pandas.DataFrame

Filter a tidy metric frame by metric, scope, and method.

Parameters:

• metrics_df (pandas.DataFrame) – Tidy metric frame from prepare_metrics_frame().

• metric (str, optional) – Metric name to keep.

• scope (str, optional) – Scope name to keep.

• method (str or sequence of str, optional) – Method name or names to keep.

Returns:

Filtered frame.

Return type:

pandas.DataFrame

coco_pipe.viz.utils.infer_metric_plot_type(metrics_df: pandas.DataFrame, requested: str | None = None) → str

Choose a sensible default plot type from filtered metric observations.

Parameters:

• metrics_df (pandas.DataFrame) – Already-filtered tidy metric frame.

• requested (str, optional) – Explicit requested plot type.

Returns:

Resolved plot type.

Return type:

str