coco_pipe.dim_reduction.reducers.topology ========================================= .. py:module:: coco_pipe.dim_reduction.reducers.topology .. autoapi-nested-parse:: 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. .. rubric:: References .. [1] Moor, M., Horn, M., Rieck, B., and Borgwardt, K. (2020). "Topological Autoencoders". Proceedings of the 37th International Conference on Machine Learning. .. [2] Gudhi documentation: https://gudhi.inria.fr/python/latest/ Author: Hamza Abdelhedi (hamza.abdelhedi@umontreal.ca) Classes ------- .. autoapisummary:: coco_pipe.dim_reduction.reducers.topology.TopologicalSignatureDistance coco_pipe.dim_reduction.reducers.topology.TopologicalAEReducer Module Contents --------------- .. py:class:: TopologicalSignatureDistance(match_edges: str = 'symmetric', p: int = 2) Topological signature distance used as a regularization loss. :param match_edges: Matching strategy placeholder retained for API compatibility. :type match_edges: str, default="symmetric" :param p: Norm used when computing pairwise distances with `torch.cdist`. :type p: int, default=2 .. rubric:: Notes This implementation currently compares active edge lengths derived from persistence pairs in the input and latent spaces. .. py:attribute:: match_edges :value: 'symmetric' .. py:attribute:: p :value: 2 .. py:method:: _get_active_pairs(dist_matrix: Any, dim: int = 1) -> list[tuple[int, int]] .. py:method:: _compute_distance_matrix(x: Any, p: int = 2) -> Any .. py:method:: forward(x: Any, z: Any) -> Any Compute the topological signature distance. :param x: Input-space samples. :type x: torch.Tensor :param z: Latent-space samples. :type z: torch.Tensor :returns: Scalar loss value. :rtype: torch.Tensor .. py:attribute:: __call__ .. py:class:: TopologicalAEReducer(n_components: int = 2, hidden_dims: Optional[list[int]] = None, lam: float = 0.0, lr: float = 0.001, batch_size: int = 64, epochs: int = 50, device: str = 'auto', verbose: int = 0, **kwargs) Bases: :py:obj:`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. :param n_components: Latent dimensionality of the embedding. :type n_components: int, default=2 :param hidden_dims: Hidden layer sizes for the encoder. The decoder mirrors this sequence. If omitted, `[128, 64]` is used. :type hidden_dims: list of int, optional :param lam: Regularization strength applied to the topological loss term. :type lam: float, default=0.0 :param lr: Optimizer learning rate. :type lr: float, default=1e-3 :param batch_size: Training batch size. :type batch_size: int, default=64 :param epochs: Number of training epochs. :type epochs: int, default=50 :param device: Training device. If `"auto"`, the reducer selects CUDA, then MPS, then CPU depending on availability. :type device: str, default="auto" :param verbose: Verbosity forwarded to Skorch. :type verbose: int, default=0 :param \*\*kwargs: 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`. :type \*\*kwargs: dict .. attribute:: model Fitted Skorch wrapper after `fit`. :type: skorch.NeuralNetRegressor or None .. seealso:: :obj:`IVISReducer` Neural reducer based on triplet loss. :obj:`ParametricUMAPReducer` Neural graph-based reducer with transform support. :obj:`PHATEReducer` Nonlinear diffusion-based reducer for smooth trajectories. :obj:`PCAReducer` Linear baseline for tabular inputs. .. rubric:: 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) # doctest: +SKIP TopologicalAEReducer(...) >>> reducer.transform(X).shape # doctest: +SKIP (20, 2) .. py:property:: capabilities :type: 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. :rtype: dict .. py:attribute:: hidden_dims .. py:attribute:: lam :value: 0.0 .. py:attribute:: lr :value: 0.001 .. py:attribute:: batch_size :value: 64 .. py:attribute:: epochs :value: 50 .. py:attribute:: requested_device :value: 'auto' .. py:attribute:: device :value: 'cpu' .. py:attribute:: verbose :value: 0 .. py:attribute:: input_dim_ :value: None .. py:method:: fit(X: coco_pipe.dim_reduction.reducers.base.ArrayLike, y: Optional[coco_pipe.dim_reduction.reducers.base.ArrayLike] = None) -> TopologicalAEReducer Fit the topology autoencoder on the input data. :param X: Training data. :type X: ArrayLike of shape (n_samples, n_features) :param y: Ignored. Present for API compatibility. :type y: ArrayLike, optional :returns: Fitted reducer instance. :rtype: TopologicalAEReducer :raises ValueError: If `X` is not 2-dimensional. .. py:method:: transform(X: coco_pipe.dim_reduction.reducers.base.ArrayLike) -> numpy.ndarray Encode new samples with the fitted topology autoencoder. :param X: Samples to encode. :type X: ArrayLike of shape (n_samples, n_features) :returns: Latent embedding produced by the encoder. :rtype: np.ndarray of shape (n_samples, n_components) .. py:property:: loss_history_ :type: list[float] Return the recorded training loss history. :returns: Training loss values. Returns an empty list if no fitted history is available. :rtype: list of float .. py:method:: get_pytorch_module() -> Optional[Any] Return the fitted underlying PyTorch module. :returns: Fitted encoder-decoder module, or ``None`` if unavailable. :rtype: torch.nn.Module or None