coco_pipe.dim_reduction.DimReduction#

class coco_pipe.dim_reduction.DimReduction(method, n_components=2, params=None, **kwargs)#

Bases: object

Manage one dimensionality reduction workflow.

Parameters:

  • method (str or BaseReducerConfig) – Canonical public reducer name or a typed configuration object. Method names are exact and must match the registry, for example "PCA", "Isomap", "Pacmap", or "TopologicalAE".

  • n_components (int, default=2) – Target dimensionality when method is a string.

  • params (dict, optional) – Additional reducer keyword arguments merged into the constructor arguments when method is a string.

  • **kwargs (dict) – Runtime reducer keyword overrides. These are merged after params.

Variables:

  • method (str) – Canonical reducer name.

  • n_components (int) – Target dimensionality used for the reducer instance.

  • reducer (BaseReducer) – Instantiated reducer backend.

  • metrics (dict) – Cached scalar evaluation summaries from the latest score() call.

  • quality_metadata (dict) – Cached scalar reducer metadata exposed through the reducer contract.

  • diagnostics (dict) – Cached non-scalar diagnostic artifacts exposed through the reducer contract or the evaluation layer.

  • metric_records (list of dict) – Cached tidy metric observations produced by the evaluator.

  • interpretation (dict) – Cached feature interpretation payloads from the latest interpret() call.

  • interpretation_records (list of dict) – Cached tidy feature-interpretation observations.

See also

coco_pipe.dim_reduction.analysis.interpret_features

Pure interpretation backend used by interpret().

coco_pipe.dim_reduction.evaluation.core.evaluate_embedding

Pure evaluator used by score().

coco_pipe.dim_reduction.evaluation.core.MethodSelector

Post-hoc comparison and ranking over already-scored reducers.

coco_pipe.viz.dim_reduction

Plotting utilities for embeddings, metrics, and diagnostics.

Examples

>>> reducer = DimReduction("UMAP", n_components=2, n_neighbors=15)
>>> embedding = reducer.fit_transform(X)
>>> scores = reducer.score(embedding, X=X)
>>> "trustworthiness" in scores["metrics"]
True
>>> interpretation = reducer.interpret(
...     X,
...     X_emb=embedding,
...     analyses=["correlation"],
...     feature_names=feature_names,
... )
>>> "correlation" in interpretation["analysis"]
True
property random_state: int | None#

Return the random seed from parameters if any.

Return type:

int | None

property capabilities: dict[str, Any]#

Return reducer capability metadata through the manager interface.

Return type:

dict[str, Any]

fit(X, y=None)#

Fit the reducer on the provided data.

Parameters:

  • X (DataContainer, array-like, or MNE object) – Input data in the reducer’s native layout.

  • y (array-like, optional) – Optional supervision forwarded to the reducer.

Returns:

self – The fitted reducer.

Return type:

DimReduction

transform(X)#

Transform new data with a fitted reducer.

Parameters:

X (DataContainer, array-like, or MNE object) – Input data in the reducer’s native layout.

Returns:

X_emb – Reduced representation. A ~coco_pipe.io.DataContainer input yields an embedding ~coco_pipe.io.DataContainer (component axis, ids/coords/meta preserved) for standard 2-D embeddings; array input yields an array.

Return type:

DataContainer or np.ndarray

fit_transform(X, y=None)#

Fit the reducer and return the reduced representation.

Parameters:

  • X (DataContainer, array-like, or MNE object) – Input data in the reducer’s native layout.

  • y (array-like, optional) – Optional supervision forwarded to the reducer.

Returns:

X_emb – Reduced representation. A ~coco_pipe.io.DataContainer input yields an embedding ~coco_pipe.io.DataContainer (component axis, ids/coords/meta preserved) for standard 2-D embeddings; array input yields an array.

Return type:

DataContainer or np.ndarray

get_components()#

Return reducer-defined component-like outputs.

Returns:

components – Component-like array exposed by the reducer.

Return type:

np.ndarray

Raises:

ValueError – If the reducer does not expose public components.

score(X_emb, X=None, n_neighbors=5, metrics=None, k_values=None, labels=None, groups=None, times=None, separation_method=None, config=None)#

Evaluate an explicit embedding against the original data.

Parameters:

  • X_emb (DataContainer or array-like) – Embedded data to evaluate. A ~coco_pipe.io.DataContainer is unwrapped to its X array.

  • X (DataContainer or array-like, optional) – Original high-dimensional data in evaluation-ready layout. This is required for standard 2D metrics and optional for native 3D trajectory metrics. A ~coco_pipe.io.DataContainer is unwrapped to its X array.

  • n_neighbors (int, default=5) – K-nearest neighbors size for metric computation.

  • metrics (list of str, optional) – Metric selectors to compute. None evaluates all metric families available for the embedding shape. Explicit values take precedence over config.

  • k_values (list of int, optional) – Neighborhood sizes used for multi-scale standard metric evaluation. Explicit values take precedence over config.

  • labels (np.ndarray, optional) – Optional labels aligned with the embedding. Used for trajectory separation when X_emb is 3D and for explicit supervised 2D metrics when requested.

  • groups (np.ndarray, optional) – Optional grouping variable aligned with the embedding. Required by grouped supervised evaluation metrics such as separation_logreg_balanced_accuracy.

  • times (np.ndarray, optional) – Optional trajectory time coordinates aligned with the trajectory length axis.

  • separation_method (str, optional) – Separation definition passed to trajectory evaluation when labels are available for native 3D trajectory embeddings. None defers to config and otherwise falls back to "centroid".

  • config (EvaluationConfig, optional) – Typed evaluation configuration. Supplies metrics, k_values (from config.k_range), and separation_method when those are not passed explicitly. Mirrors how DimReduction.__init__ accepts a BaseReducerConfig.

Returns:

scores – Dictionary with keys "metrics", "metadata", and "diagnostics".

Return type:

dict

Notes

score() does not infer or cache embeddings. Callers must pass X_emb explicitly. X is only required when the requested evaluation path needs the original high-dimensional samples.

interpret(X, *, X_emb, analyses=None, feature_names=None, n_repeats=5, random_state=None)#

Run feature interpretation analyses for an explicit embedding.

Parameters:

  • X (np.ndarray) – Original input data.

  • X_emb (np.ndarray) – Explicit embedding aligned with X.

  • analyses (list of {"correlation", "perturbation", "gradient"}, optional) – Interpretation analyses to compute. None defaults to ["correlation"].

  • feature_names (list of str, optional) – Feature names aligned with the columns of X when the requested interpretation returns feature-keyed outputs.

  • n_repeats (int, default=5) – Number of shuffles per feature for perturbation importance.

  • random_state (int, optional) – Random seed for perturbation importance.

Returns:

Dictionary with keys "analysis" and "records".

Return type:

dict

Notes

interpret() does not fit the reducer or compute embeddings. Callers must pass both X and X_emb explicitly.

See also

coco_pipe.dim_reduction.analysis.interpret_features

Pure interpretation backend used by this manager method.

score

Evaluate structure-preservation metrics for an explicit embedding.

Examples

>>> reducer = DimReduction("PCA", n_components=2)
>>> embedding = reducer.fit_transform(X)
>>> result = reducer.interpret(
...     X,
...     X_emb=embedding,
...     analyses=["correlation"],
...     feature_names=feature_names,
... )
>>> sorted(result)
['analysis', 'records']
get_diagnostics()#

Return cached diagnostics merged with reducer diagnostics.

Returns:

diagnostics – Diagnostic artifacts declared by the reducer contract and the evaluation layer.

Return type:

dict

get_quality_metadata()#

Return cached scalar metadata merged with reducer metadata.

Returns:

metadata – Scalar metadata declared by the reducer contract and the evaluation layer.

Return type:

dict

get_metrics()#

Return cached scalar metrics from the latest score() call.

Return type:

dict[str, Any]

get_summary()#

Return a normalized summary payload for report and export paths.

Returns:

Plain dictionary containing method identity, cached scalar summaries, reducer metadata, diagnostics, tidy metric records, and capability flags, plus cached feature interpretation payloads.

Return type:

dict

Notes

The summary does not include an embedding payload. Embeddings are handled explicitly outside the manager and must be passed directly to plotting or reporting utilities that need them.

save(path)#

Save the underlying reducer to disk.

Parameters:

path (str or Path) – Output path for reducer persistence.

Notes

Only the reducer model is persisted. Cached manager state such as metrics and diagnostics is not included.

classmethod load(path, method)#

Load a persisted reducer and wrap it in a fresh manager.

Parameters:

  • path (str or Path) – Path to a serialized reducer saved with save().

  • method (str) – Canonical public reducer name used to reconstruct the manager.

Returns:

Fresh manager wrapping the loaded reducer model.

Return type:

DimReduction

Notes

This restores the reducer model only. Cached manager state such as scores, diagnostics, and metric records is not persisted.