coco_pipe.dim_reduction.reducers.manifold#

Nonlinear manifold-learning reducers.

This module provides wrappers around scikit-learn manifold-learning estimators. These reducers follow the shared ~coco_pipe.dim_reduction.reducers.base.BaseReducer contract so they can be used with ~coco_pipe.dim_reduction.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.

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#

`IsomapReducer`	Isometric Mapping reducer.
`LLEReducer`	Locally Linear Embedding reducer.
`MDSReducer`	Multidimensional Scaling reducer.
`SpectralEmbeddingReducer`	Spectral Embedding reducer.

Module Contents#

class coco_pipe.dim_reduction.reducers.manifold.IsomapReducer(n_components=2, **kwargs)#

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

Parameters:

n_components (int, default=2) – Number of coordinates for the manifold.
**kwargs (dict) – Additional keyword arguments forwarded to sklearn.manifold.Isomap after signature filtering. Common options include n_neighbors, metric, p, and eigen_solver.

Variables:

model (sklearn.manifold.Isomap or None) – Fitted Isomap estimator after fit.

See also

LLEReducer: Nonlinear local-neighborhood manifold embedding.
MDSReducer: Distance-preserving manifold embedding.
SpectralEmbeddingReducer: Nonlinear graph Laplacian embedding.
PCAReducer: Linear baseline for global variance preservation.
UMAPReducer: Nonlinear graph-based embedding for local and global structure.
TSNEReducer: Nonlinear neighborhood-preserving visualization method.

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)

property capabilities: dict#

Return capability metadata for Isomap.

Returns:: Capability mapping describing Isomap as a nonlinear reducer with out-of-sample transform support.
Return type:: dict

fit(X, y=None)#

Fit Isomap 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:

IsomapReducer

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

transform(X)#

Project data into the fitted Isomap embedding space.

Parameters:: X (ArrayLike of shape (n_samples, n_features)) – Data to project.
Returns:: Low-dimensional embedding coordinates.
Return type:: np.ndarray of shape (n_samples, n_dims)
Raises:: RuntimeError – If the reducer has not been fitted.

property reconstruction_error_: float | None#

Return the Isomap reconstruction error.

Returns:: Reconstruction error returned by the fitted estimator.
Return type:: float
Raises:: RuntimeError – If the reducer has not been fitted.

class coco_pipe.dim_reduction.reducers.manifold.LLEReducer(n_components=2, **kwargs)#

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

Parameters:

n_components (int, default=2) – Number of coordinates for the manifold.
**kwargs (dict) – Additional keyword arguments forwarded to sklearn.manifold.LocallyLinearEmbedding after signature filtering. Common options include n_neighbors, method, eigen_solver, and random_state.

Variables:

model (sklearn.manifold.LocallyLinearEmbedding or None) – Fitted LLE estimator after fit.

See also

IsomapReducer: Nonlinear geodesic-distance embedding.
MDSReducer: Distance-preserving manifold embedding.
SpectralEmbeddingReducer: Nonlinear graph Laplacian embedding.
PCAReducer: Linear baseline for global variance preservation.
UMAPReducer: Nonlinear graph-based embedding for local and global structure.
TSNEReducer: Nonlinear neighborhood-preserving visualization method.

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)

property capabilities: dict#

Return capability metadata for LLE.

Returns:: Capability mapping describing LLE as a nonlinear reducer with out-of-sample transform support.
Return type:: dict

fit(X, y=None)#

Fit LLE 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:

LLEReducer

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

transform(X)#

Project data into the fitted LLE embedding space.

Parameters:: X (ArrayLike of shape (n_samples, n_features)) – Data to project.
Returns:: Low-dimensional embedding coordinates.
Return type:: np.ndarray of shape (n_samples, n_dims)
Raises:: RuntimeError – If the reducer has not been fitted.

property reconstruction_error_: float#

Return the LLE reconstruction error.

Returns:: Reconstruction error associated with the embedding.
Return type:: float
Raises:: RuntimeError – If the reducer has not been fitted.

class coco_pipe.dim_reduction.reducers.manifold.MDSReducer(n_components=2, **kwargs)#

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

Parameters:

n_components (int, default=2) – Number of coordinates for the manifold.
**kwargs (dict) – Additional keyword arguments forwarded to sklearn.manifold.MDS after signature filtering. Common options include metric, n_init, max_iter, dissimilarity, and random_state.

Variables:

model (sklearn.manifold.MDS or None) – Fitted MDS estimator after fit or fit_transform.

Notes

transform is not supported because scikit-learn MDS does not provide an out-of-sample projection API.

See also

IsomapReducer: Nonlinear geodesic-distance embedding.
LLEReducer: Nonlinear local-neighborhood embedding.
SpectralEmbeddingReducer: Nonlinear graph Laplacian embedding.
PCAReducer: Linear baseline for global variance preservation.
UMAPReducer: Nonlinear graph-based embedding for local and global structure.
TSNEReducer: Nonlinear neighborhood-preserving visualization method.

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

property capabilities: dict#

Return capability metadata for MDS.

Returns:: Capability mapping describing MDS as a nonlinear reducer without out-of-sample transform support.
Return type:: dict

fit(X, y=None)#

Fit MDS 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:

MDSReducer

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

abstractmethod transform(X)#

Raise because scikit-learn MDS does not support out-of-sample transform.

Parameters:: X (ArrayLike) – Ignored input included for API compatibility.
Raises:: NotImplementedError – Always raised because MDS does not support transforming new data.
Return type:: numpy.ndarray

fit_transform(X, y=None)#

Fit MDS and return the embedding coordinates.

Parameters:

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

Returns:

Embedded coordinates produced by MDS.

Return type:

np.ndarray of shape (n_samples, n_dims)

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)

property stress_: float#

Return the MDS stress (sum of squared distances mismatch).

Returns:: Stress value returned by the fitted MDS model.
Return type:: float
Raises:: RuntimeError – If the reducer has not been fitted.

class coco_pipe.dim_reduction.reducers.manifold.SpectralEmbeddingReducer(n_components=2, **kwargs)#

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

Parameters:

n_components (int, default=2) – Number of coordinates for the manifold.
**kwargs (dict) – Additional keyword arguments forwarded to sklearn.manifold.SpectralEmbedding after signature filtering. Common options include affinity, gamma, random_state, eigen_solver, and n_neighbors.

Variables:

model (sklearn.manifold.SpectralEmbedding or None) – Fitted spectral embedding estimator after fit or fit_transform.

Notes

transform is not supported because scikit-learn SpectralEmbedding does not provide an out-of-sample projection API.

See also

IsomapReducer: Nonlinear geodesic-distance embedding.
LLEReducer: Nonlinear local-neighborhood embedding.
MDSReducer: Distance-preserving manifold embedding.
PCAReducer: Linear baseline for global variance preservation.
UMAPReducer: Nonlinear graph-based embedding for local and global structure.
TSNEReducer: Nonlinear neighborhood-preserving visualization method.

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

property capabilities: dict#

Return capability metadata for Spectral Embedding.

Returns:: Capability mapping describing Spectral Embedding as a nonlinear reducer without out-of-sample transform support.
Return type:: dict

fit(X, y=None)#

Fit Spectral Embedding 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:

SpectralEmbeddingReducer

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

abstractmethod transform(X)#

Raise because scikit-learn Spectral Embedding lacks out-of-sample transform.

Parameters:: X (ArrayLike) – Ignored input included for API compatibility.
Raises:: NotImplementedError – Always raised because Spectral Embedding does not support transforming new data.
Return type:: numpy.ndarray

fit_transform(X, y=None)#

Fit Spectral Embedding and return the embedding coordinates.

Parameters:

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

Returns:

Embedded coordinates produced by Spectral Embedding.

Return type:

np.ndarray of shape (n_samples, n_dims)

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)