coco_pipe.dim_reduction.reducers.manifold ========================================= .. py:module:: coco_pipe.dim_reduction.reducers.manifold .. autoapi-nested-parse:: Nonlinear manifold-learning reducers. This module provides wrappers around scikit-learn manifold-learning estimators. These reducers follow the shared `BaseReducer` contract so they can be used with `DimReduction`, reporting, and visualization utilities while preserving a consistent reducer API. Classes ------- IsomapReducer Nonlinear geodesic-distance embedding based on Isomap. LLEReducer Nonlinear neighborhood-preserving embedding based on Locally Linear Embedding. MDSReducer Distance-preserving embedding based on multidimensional scaling. SpectralEmbeddingReducer Graph Laplacian embedding based on spectral decomposition. .. rubric:: References .. [1] Tenenbaum, J. B., de Silva, V., and Langford, J. C. (2000). "A global geometric framework for nonlinear dimensionality reduction". Science, 290(5500), 2319-2323. .. [2] Roweis, S. T., and Saul, L. K. (2000). "Nonlinear dimensionality reduction by locally linear embedding". Science, 290(5500), 2323-2326. .. [3] Borg, I., and Groenen, P. J. F. (2005). Modern multidimensional scaling: Theory and applications. Springer. .. [4] Belkin, M., and Niyogi, P. (2003). "Laplacian eigenmaps for dimensionality reduction and data representation". Neural Computation, 15(6), 1373-1396. Author: Hamza Abdelhedi (hamza.abdelhedi@umontreal.ca) Classes ------- .. autoapisummary:: coco_pipe.dim_reduction.reducers.manifold.IsomapReducer coco_pipe.dim_reduction.reducers.manifold.LLEReducer coco_pipe.dim_reduction.reducers.manifold.MDSReducer coco_pipe.dim_reduction.reducers.manifold.SpectralEmbeddingReducer Module Contents --------------- .. py:class:: IsomapReducer(n_components: int = 2, **kwargs) Bases: :py:obj:`coco_pipe.dim_reduction.reducers.base.BaseReducer` Isometric Mapping reducer. Isomap estimates geodesic distances on a nearest-neighbor graph and then computes a low-dimensional embedding consistent with those distances. :param n_components: Number of coordinates for the manifold. :type n_components: int, default=2 :param \*\*kwargs: Additional keyword arguments forwarded to `sklearn.manifold.Isomap` after signature filtering. Common options include `n_neighbors`, `metric`, `p`, and `eigen_solver`. :type \*\*kwargs: dict .. attribute:: model Fitted Isomap estimator after `fit`. :type: sklearn.manifold.Isomap or None .. seealso:: :obj:`LLEReducer` Nonlinear local-neighborhood manifold embedding. :obj:`MDSReducer` Distance-preserving manifold embedding. :obj:`SpectralEmbeddingReducer` Nonlinear graph Laplacian embedding. :obj:`PCAReducer` Linear baseline for global variance preservation. :obj:`UMAPReducer` Nonlinear graph-based embedding for local and global structure. :obj:`TSNEReducer` Nonlinear neighborhood-preserving visualization method. .. rubric:: Examples >>> import numpy as np >>> from coco_pipe.dim_reduction import IsomapReducer >>> X = np.random.rand(100, 10) >>> reducer = IsomapReducer(n_components=2, n_neighbors=5) >>> _ = reducer.fit(X) >>> reducer.transform(X[:8]).shape (8, 2) >>> reducer.n_features_in_ 10 >>> embedding = reducer.fit_transform(X) >>> embedding.shape (100, 2) .. py:property:: capabilities :type: dict Return capability metadata for Isomap. :returns: Capability mapping describing Isomap as a nonlinear reducer with out-of-sample transform support. :rtype: dict .. py:method:: fit(X: coco_pipe.dim_reduction.reducers.base.ArrayLike, y: Optional[coco_pipe.dim_reduction.reducers.base.ArrayLike] = None) -> IsomapReducer Fit Isomap 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: IsomapReducer .. rubric:: Examples >>> import numpy as np >>> from coco_pipe.dim_reduction import IsomapReducer >>> X = np.random.rand(30, 6) >>> reducer = IsomapReducer(n_components=2, n_neighbors=4) >>> _ = 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 Isomap embedding space. :param X: Data to project. :type X: ArrayLike of shape (n_samples, n_features) :returns: Low-dimensional embedding coordinates. :rtype: np.ndarray of shape (n_samples, n_components) :raises RuntimeError: If the reducer has not been fitted. .. py:property:: reconstruction_error_ :type: Optional[float] Return the Isomap reconstruction error. :returns: Reconstruction error returned by the fitted estimator. :rtype: float :raises RuntimeError: If the reducer has not been fitted. .. py:class:: LLEReducer(n_components: int = 2, **kwargs) Bases: :py:obj:`coco_pipe.dim_reduction.reducers.base.BaseReducer` Locally Linear Embedding reducer. LLE learns a nonlinear embedding by reconstructing each point from its local neighborhood in the input space and preserving those reconstruction weights in the low-dimensional space. :param n_components: Number of coordinates for the manifold. :type n_components: int, default=2 :param \*\*kwargs: Additional keyword arguments forwarded to `sklearn.manifold.LocallyLinearEmbedding` after signature filtering. Common options include `n_neighbors`, `method`, `eigen_solver`, and `random_state`. :type \*\*kwargs: dict .. attribute:: model Fitted LLE estimator after `fit`. :type: sklearn.manifold.LocallyLinearEmbedding or None .. seealso:: :obj:`IsomapReducer` Nonlinear geodesic-distance embedding. :obj:`MDSReducer` Distance-preserving manifold embedding. :obj:`SpectralEmbeddingReducer` Nonlinear graph Laplacian embedding. :obj:`PCAReducer` Linear baseline for global variance preservation. :obj:`UMAPReducer` Nonlinear graph-based embedding for local and global structure. :obj:`TSNEReducer` Nonlinear neighborhood-preserving visualization method. .. rubric:: Examples >>> import numpy as np >>> from coco_pipe.dim_reduction import LLEReducer >>> X = np.random.rand(100, 10) >>> reducer = LLEReducer(n_components=2, n_neighbors=10, eigen_solver="dense") >>> _ = reducer.fit(X) >>> reducer.transform(X[:6]).shape (6, 2) >>> embedding = reducer.fit_transform(X) >>> embedding.shape (100, 2) .. py:property:: capabilities :type: dict Return capability metadata for LLE. :returns: Capability mapping describing LLE as a nonlinear reducer with out-of-sample transform support. :rtype: dict .. py:method:: fit(X: coco_pipe.dim_reduction.reducers.base.ArrayLike, y: Optional[coco_pipe.dim_reduction.reducers.base.ArrayLike] = None) -> LLEReducer Fit LLE 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: LLEReducer .. rubric:: Examples >>> import numpy as np >>> from coco_pipe.dim_reduction import LLEReducer >>> X = np.random.rand(30, 6) >>> reducer = LLEReducer(n_components=2, n_neighbors=5, eigen_solver="dense") >>> _ = reducer.fit(X) >>> reducer.model is not None True >>> reducer = LLEReducer(n_components=2, method="modified", n_neighbors=5) >>> _ = 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 LLE embedding space. :param X: Data to project. :type X: ArrayLike of shape (n_samples, n_features) :returns: Low-dimensional embedding coordinates. :rtype: np.ndarray of shape (n_samples, n_components) :raises RuntimeError: If the reducer has not been fitted. .. py:property:: reconstruction_error_ :type: float Return the LLE reconstruction error. :returns: Reconstruction error associated with the embedding. :rtype: float :raises RuntimeError: If the reducer has not been fitted. .. py:class:: MDSReducer(n_components: int = 2, **kwargs) Bases: :py:obj:`coco_pipe.dim_reduction.reducers.base.BaseReducer` Multidimensional Scaling reducer. MDS seeks a low-dimensional representation whose pairwise distances best match the pairwise distances in the original space. :param n_components: Number of coordinates for the manifold. :type n_components: int, default=2 :param \*\*kwargs: Additional keyword arguments forwarded to `sklearn.manifold.MDS` after signature filtering. Common options include `metric`, `n_init`, `max_iter`, `dissimilarity`, and `random_state`. :type \*\*kwargs: dict .. attribute:: model Fitted MDS estimator after `fit` or `fit_transform`. :type: sklearn.manifold.MDS or None .. rubric:: Notes `transform` is not supported because scikit-learn MDS does not provide an out-of-sample projection API. .. seealso:: :obj:`IsomapReducer` Nonlinear geodesic-distance embedding. :obj:`LLEReducer` Nonlinear local-neighborhood embedding. :obj:`SpectralEmbeddingReducer` Nonlinear graph Laplacian embedding. :obj:`PCAReducer` Linear baseline for global variance preservation. :obj:`UMAPReducer` Nonlinear graph-based embedding for local and global structure. :obj:`TSNEReducer` Nonlinear neighborhood-preserving visualization method. .. rubric:: Examples >>> import numpy as np >>> from coco_pipe.dim_reduction import MDSReducer >>> X = np.random.rand(60, 8) >>> reducer = MDSReducer(n_components=2, random_state=42) >>> embedding = reducer.fit_transform(X) >>> embedding.shape (60, 2) >>> reducer.stress_ >= 0 True >>> _ = reducer.fit(X) >>> reducer.model is not None True .. py:property:: capabilities :type: dict Return capability metadata for MDS. :returns: Capability mapping describing MDS as a nonlinear reducer without out-of-sample transform support. :rtype: dict .. py:method:: fit(X: coco_pipe.dim_reduction.reducers.base.ArrayLike, y: Optional[coco_pipe.dim_reduction.reducers.base.ArrayLike] = None) -> MDSReducer Fit MDS 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: MDSReducer .. rubric:: Examples >>> import numpy as np >>> from coco_pipe.dim_reduction import MDSReducer >>> X = np.random.rand(25, 5) >>> reducer = MDSReducer(n_components=2, random_state=0) >>> _ = reducer.fit(X) >>> reducer.model is not None True .. py:method:: transform(X: coco_pipe.dim_reduction.reducers.base.ArrayLike) -> numpy.ndarray :abstractmethod: Raise because scikit-learn MDS does not support out-of-sample transform. :param X: Ignored input included for API compatibility. :type X: ArrayLike :raises NotImplementedError: Always raised because MDS does not support transforming new data. .. py:method:: fit_transform(X: coco_pipe.dim_reduction.reducers.base.ArrayLike, y: Optional[coco_pipe.dim_reduction.reducers.base.ArrayLike] = None) -> numpy.ndarray Fit MDS and return the embedding coordinates. :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: Embedded coordinates produced by MDS. :rtype: np.ndarray of shape (n_samples, n_components) .. rubric:: Examples >>> import numpy as np >>> from coco_pipe.dim_reduction import MDSReducer >>> X = np.random.rand(20, 4) >>> reducer = MDSReducer(n_components=2, random_state=0) >>> reducer.fit_transform(X).shape (20, 2) .. py:property:: stress_ :type: float Return the MDS stress (sum of squared distances mismatch). :returns: Stress value returned by the fitted MDS model. :rtype: float :raises RuntimeError: If the reducer has not been fitted. .. py:class:: SpectralEmbeddingReducer(n_components: int = 2, **kwargs) Bases: :py:obj:`coco_pipe.dim_reduction.reducers.base.BaseReducer` Spectral Embedding reducer. Spectral Embedding computes a nonlinear embedding using eigenvectors of the graph Laplacian built from the data affinity graph. :param n_components: Number of coordinates for the manifold. :type n_components: int, default=2 :param \*\*kwargs: Additional keyword arguments forwarded to `sklearn.manifold.SpectralEmbedding` after signature filtering. Common options include `affinity`, `gamma`, `random_state`, `eigen_solver`, and `n_neighbors`. :type \*\*kwargs: dict .. attribute:: model Fitted spectral embedding estimator after `fit` or `fit_transform`. :type: sklearn.manifold.SpectralEmbedding or None .. rubric:: Notes `transform` is not supported because scikit-learn SpectralEmbedding does not provide an out-of-sample projection API. .. seealso:: :obj:`IsomapReducer` Nonlinear geodesic-distance embedding. :obj:`LLEReducer` Nonlinear local-neighborhood embedding. :obj:`MDSReducer` Distance-preserving manifold embedding. :obj:`PCAReducer` Linear baseline for global variance preservation. :obj:`UMAPReducer` Nonlinear graph-based embedding for local and global structure. :obj:`TSNEReducer` Nonlinear neighborhood-preserving visualization method. .. rubric:: Examples >>> import numpy as np >>> from coco_pipe.dim_reduction import SpectralEmbeddingReducer >>> X = np.random.rand(80, 10) >>> reducer = SpectralEmbeddingReducer(n_components=2, random_state=42) >>> embedding = reducer.fit_transform(X) >>> embedding.shape (80, 2) >>> _ = reducer.fit(X) >>> reducer.model is not None True .. py:property:: capabilities :type: dict Return capability metadata for Spectral Embedding. :returns: Capability mapping describing Spectral Embedding as a nonlinear reducer without out-of-sample transform support. :rtype: dict .. py:method:: fit(X: coco_pipe.dim_reduction.reducers.base.ArrayLike, y: Optional[coco_pipe.dim_reduction.reducers.base.ArrayLike] = None) -> SpectralEmbeddingReducer Fit Spectral Embedding 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: SpectralEmbeddingReducer .. rubric:: Examples >>> import numpy as np >>> from coco_pipe.dim_reduction import SpectralEmbeddingReducer >>> X = np.random.rand(30, 6) >>> reducer = SpectralEmbeddingReducer(n_components=2, random_state=0) >>> _ = reducer.fit(X) >>> reducer.model is not None True .. py:method:: transform(X: coco_pipe.dim_reduction.reducers.base.ArrayLike) -> numpy.ndarray :abstractmethod: Raise because scikit-learn Spectral Embedding lacks out-of-sample transform. :param X: Ignored input included for API compatibility. :type X: ArrayLike :raises NotImplementedError: Always raised because Spectral Embedding does not support transforming new data. .. py:method:: fit_transform(X: coco_pipe.dim_reduction.reducers.base.ArrayLike, y: Optional[coco_pipe.dim_reduction.reducers.base.ArrayLike] = None) -> numpy.ndarray Fit Spectral Embedding and return the embedding coordinates. :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: Embedded coordinates produced by Spectral Embedding. :rtype: np.ndarray of shape (n_samples, n_components) .. rubric:: Examples >>> import numpy as np >>> from coco_pipe.dim_reduction import SpectralEmbeddingReducer >>> X = np.random.rand(20, 4) >>> reducer = SpectralEmbeddingReducer(n_components=2, random_state=0) >>> reducer.fit_transform(X).shape (20, 2)