coco_pipe.dim_reduction.reducers.topology¶

Topological dimensionality reduction reducers.

This module provides topology-aware neural reducers that preserve geometric structure through reconstruction and topological regularization. Heavy dependencies such as torch, gudhi, and skorch remain lazy at import time so the base package can be imported without deep-learning backends installed.

Classes¶

TopologicalSignatureDistance: Persistent-homology-inspired loss term used by the topological autoencoder.
TopologicalAEReducer: Topological autoencoder wrapper built on PyTorch and Skorch.

References

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

Classes¶

`TopologicalSignatureDistance`	Topological signature distance used as a regularization loss.
`TopologicalAEReducer`	Topological autoencoder reducer.

Module Contents¶

class coco_pipe.dim_reduction.reducers.topology.TopologicalSignatureDistance(match_edges: str = 'symmetric', p: int = 2)[source]¶

Topological signature distance used as a regularization loss.

Parameters:

match_edges (str, default="symmetric") – Matching strategy placeholder retained for API compatibility.
p (int, default=2) – Norm used when computing pairwise distances with torch.cdist.

Notes

This implementation currently compares active edge lengths derived from persistence pairs in the input and latent spaces.

match_edges = 'symmetric'¶

p = 2¶

_get_active_pairs(dist_matrix: Any, dim: int = 1) → list[tuple[int, int]][source]¶

_compute_distance_matrix(x: Any, p: int = 2) → Any[source]¶

forward(x: Any, z: Any) → Any[source]¶

Compute the topological signature distance.

Parameters:

x (torch.Tensor) – Input-space samples.
z (torch.Tensor) – Latent-space samples.

Returns:

Scalar loss value.

Return type:

torch.Tensor

__call__¶

class coco_pipe.dim_reduction.reducers.topology.TopologicalAEReducer(n_components: int = 2, hidden_dims: list[int] | None = None, lam: float = 0.0, lr: float = 0.001, batch_size: int = 64, epochs: int = 50, device: str = 'auto', verbose: int = 0, **kwargs)[source]¶

Bases: coco_pipe.dim_reduction.reducers.base.BaseReducer

Topological autoencoder reducer.

This reducer trains an autoencoder with an optional topological regularization term. The low-dimensional embedding is obtained from the encoder output and supports out-of-sample transformation after fitting.

Parameters:

n_components (int, default=2) – Latent dimensionality of the embedding.
hidden_dims (list of int, optional) – Hidden layer sizes for the encoder. The decoder mirrors this sequence. If omitted, [128, 64] is used.
lam (float, default=0.0) – Regularization strength applied to the topological loss term.
lr (float, default=1e-3) – Optimizer learning rate.
batch_size (int, default=64) – Training batch size.
epochs (int, default=50) – Number of training epochs.
device (str, default="auto") – Training device. If “auto”, the reducer selects CUDA, then MPS, then CPU depending on availability.
verbose (int, default=0) – Verbosity forwarded to Skorch.
**kwargs (dict) – Additional advanced Skorch parameters. Keys using the name__subparam convention are forwarded, as are a small number of top-level Skorch options such as callbacks and train_split.

model¶

Fitted Skorch wrapper after fit.

Type:: skorch.NeuralNetRegressor or None

See also

IVISReducer: Neural reducer based on triplet loss.
ParametricUMAPReducer: Neural graph-based reducer with transform support.
PHATEReducer: Nonlinear diffusion-based reducer for smooth trajectories.
PCAReducer: Linear baseline for tabular inputs.

Examples

>>> import numpy as np
>>> from coco_pipe.dim_reduction import TopologicalAEReducer
>>> X = np.random.rand(20, 10).astype(np.float32)
>>> reducer = TopologicalAEReducer(
...     n_components=2,
...     epochs=2,
...     batch_size=10,
...     device="cpu",
... )
>>> reducer.fit(X)  
TopologicalAEReducer(...)
>>> reducer.transform(X).shape  
(20, 2)

property capabilities: dict¶

Return capability metadata for the topology autoencoder.

Returns:: Capability mapping describing the reducer as a stochastic nonlinear model with transform support and loss-history diagnostics.
Return type:: dict

hidden_dims¶

lam = 0.0¶

lr = 0.001¶

batch_size = 64¶

epochs = 50¶

requested_device = 'auto'¶

device = 'cpu'¶

verbose = 0¶

input_dim_ = None¶

fit(X: coco_pipe.dim_reduction.reducers.base.ArrayLike, y: coco_pipe.dim_reduction.reducers.base.ArrayLike | None = None) → TopologicalAEReducer[source]¶

Fit the topology autoencoder on the input data.

Parameters:

X (ArrayLike of shape (n_samples, n_features)) – Training data.
y (ArrayLike, optional) – Ignored. Present for API compatibility.

Returns:

Fitted reducer instance.

Return type:

TopologicalAEReducer

Raises:

ValueError – If X is not 2-dimensional.

transform(X: coco_pipe.dim_reduction.reducers.base.ArrayLike) → numpy.ndarray[source]¶

Encode new samples with the fitted topology autoencoder.

Parameters:: X (ArrayLike of shape (n_samples, n_features)) – Samples to encode.
Returns:: Latent embedding produced by the encoder.
Return type:: np.ndarray of shape (n_samples, n_components)

property loss_history_: list[float]¶

Return the recorded training loss history.

Returns:: Training loss values. Returns an empty list if no fitted history is available.
Return type:: list of float

get_pytorch_module() → Any | None[source]¶

Return the fitted underlying PyTorch module.

Returns:: Fitted encoder-decoder module, or None if unavailable.
Return type:: torch.nn.Module or None