coco_pipe.dim_reduction.reducers.neural

Neural-network dimensionality reduction reducers.

This module provides wrappers around neural embedding backends that follow the shared BaseReducer contract. These reducers integrate with DimReduction, reporting, and visualization while keeping optional deep-learning dependencies lazy at import time.

Classes

IVISReducer

Neural triplet-loss embedding based on ivis.Ivis.

References

[1]

Szubert, B., Cole, J. E., Monaco, C., and Drozdov, I. (2019). “Structure-preserving visualization of high dimensional single-cell datasets”. Scientific Reports, 9(1), 8914.

[2]

IVIS documentation: https://github.com/beringresearch/ivis

Author: Hamza Abdelhedi (hamza.abdelhedi@umontreal.ca)

Classes

IVISReducer

IVIS dimensionality reducer.

Module Contents

class coco_pipe.dim_reduction.reducers.neural.IVISReducer(n_components: int = 2, **kwargs)

Bases: coco_pipe.dim_reduction.reducers.base.BaseReducer

IVIS dimensionality reducer.

IVIS learns a low-dimensional representation with a Siamese neural network trained using a triplet-loss objective. The reducer supports out-of-sample transformation and is suitable for large datasets when the optional ivis dependency is installed.

Parameters:

• n_components (int, default=2) – Number of embedding dimensions to learn.

• **kwargs (dict) – Additional keyword arguments forwarded to ivis.Ivis after signature filtering. Common options include k, model, epochs, batch_size, n_epochs_without_progress, and supervise_metric.

model

Fitted IVIS estimator after fit.

Type:

ivis.Ivis or None

Notes

The IVIS backend uses embedding_dims instead of n_components. This wrapper maps the reducer component count to the backend constructor automatically.

See also

ParametricUMAPReducer

Neural graph-based embedding with parametric transform.

UMAPReducer

Nonparametric graph-based nonlinear embedding.

PHATEReducer

Diffusion-based nonlinear embedding for smooth trajectories.

TopologicalAEReducer

Neural autoencoder with topological regularization.

PCAReducer

Linear baseline for global variance preservation.

Examples

>>> import numpy as np
>>> from coco_pipe.dim_reduction import IVISReducer
>>> X = np.random.rand(100, 10).astype(np.float32)
>>> reducer = IVISReducer(n_components=2, k=10, epochs=2, batch_size=16)
>>> _ = reducer.fit(X)
>>> embedding = reducer.transform(X[:8])
>>> embedding.shape
(8, 2)
>>> reducer.get_diagnostics()["loss_history_"]  
[...]
>>> reducer = IVISReducer(n_components=3, epochs=2, batch_size=16)
>>> reducer.fit_transform(X).shape  
(100, 3)

property capabilities: dict

Return capability metadata for IVIS.

Returns:

Capability mapping describing IVIS as a stochastic nonlinear reducer with transform support and loss-history diagnostics.

Return type:

dict

fit(X: coco_pipe.dim_reduction.reducers.base.ArrayLike, y: coco_pipe.dim_reduction.reducers.base.ArrayLike | None = None) → IVISReducer

Fit IVIS on the input data.

Parameters:

• X (ArrayLike of shape (n_samples, n_features)) – Training data.

• y (ArrayLike of shape (n_samples,), optional) – Optional supervision passed to IVIS for supervised training.

Returns:

Fitted reducer instance.

Return type:

IVISReducer

Examples

>>> import numpy as np
>>> from coco_pipe.dim_reduction import IVISReducer
>>> X = np.random.rand(30, 6).astype(np.float32)
>>> reducer = IVISReducer(n_components=2, epochs=2, batch_size=8)
>>> _ = reducer.fit(X)
>>> reducer.model is not None
True

transform(X: coco_pipe.dim_reduction.reducers.base.ArrayLike) → numpy.ndarray

Project data into the fitted IVIS embedding space.

Parameters:

X (ArrayLike of shape (n_samples, n_features)) – New samples to embed.

Returns:

Low-dimensional embedding of X.

Return type:

np.ndarray of shape (n_samples, n_components)