coco_pipe.dim_reduction.reducers.neural
=======================================

.. py:module:: coco_pipe.dim_reduction.reducers.neural

.. autoapi-nested-parse::

   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`.

   .. rubric:: 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
-------

.. autoapisummary::

   coco_pipe.dim_reduction.reducers.neural.IVISReducer


Module Contents
---------------

.. py:class:: IVISReducer(n_components: int = 2, **kwargs)

   Bases: :py:obj:`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.

   :param n_components: Number of embedding dimensions to learn.
   :type n_components: int, default=2
   :param \*\*kwargs: 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`.
   :type \*\*kwargs: dict

   .. attribute:: model

      Fitted IVIS estimator after `fit`.

      :type: ivis.Ivis or None

   .. rubric:: Notes

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

   .. seealso::

      :obj:`ParametricUMAPReducer`
          Neural graph-based embedding with parametric transform.

      :obj:`UMAPReducer`
          Nonparametric graph-based nonlinear embedding.

      :obj:`PHATEReducer`
          Diffusion-based nonlinear embedding for smooth trajectories.

      :obj:`TopologicalAEReducer`
          Neural autoencoder with topological regularization.

      :obj:`PCAReducer`
          Linear baseline for global variance preservation.

   .. rubric:: 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_"]  # doctest: +SKIP
   [...]
   >>> reducer = IVISReducer(n_components=3, epochs=2, batch_size=16)
   >>> reducer.fit_transform(X).shape  # doctest: +SKIP
   (100, 3)


   .. py:property:: capabilities
      :type: dict


      Return capability metadata for IVIS.

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


   .. py:method:: fit(X: coco_pipe.dim_reduction.reducers.base.ArrayLike, y: Optional[coco_pipe.dim_reduction.reducers.base.ArrayLike] = None) -> IVISReducer

      Fit IVIS on the input data.

      :param X: Training data.
      :type X: ArrayLike of shape (n_samples, n_features)
      :param y: Optional supervision passed to IVIS for supervised training.
      :type y: ArrayLike of shape (n_samples,), optional

      :returns: Fitted reducer instance.
      :rtype: IVISReducer

      .. rubric:: 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



   .. py:method:: transform(X: coco_pipe.dim_reduction.reducers.base.ArrayLike) -> numpy.ndarray

      Project data into the fitted IVIS embedding space.

      :param X: New samples to embed.
      :type X: ArrayLike of shape (n_samples, n_features)

      :returns: Low-dimensional embedding of `X`.
      :rtype: np.ndarray of shape (n_samples, n_components)