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

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: int = 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.

model

Fitted Isomap estimator after fit.

Type:

sklearn.manifold.Isomap or None

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: coco_pipe.dim_reduction.reducers.base.ArrayLike, y: coco_pipe.dim_reduction.reducers.base.ArrayLike | None = None) → IsomapReducer

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: coco_pipe.dim_reduction.reducers.base.ArrayLike) → numpy.ndarray

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_components)

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: int = 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.

model

Fitted LLE estimator after fit.

Type:

sklearn.manifold.LocallyLinearEmbedding or None

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: coco_pipe.dim_reduction.reducers.base.ArrayLike, y: coco_pipe.dim_reduction.reducers.base.ArrayLike | None = None) → LLEReducer

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: coco_pipe.dim_reduction.reducers.base.ArrayLike) → numpy.ndarray

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_components)

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: int = 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.

model

Fitted MDS estimator after fit or fit_transform.

Type:

sklearn.manifold.MDS or None

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: coco_pipe.dim_reduction.reducers.base.ArrayLike, y: coco_pipe.dim_reduction.reducers.base.ArrayLike | None = None) → MDSReducer

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

abstract transform(X: coco_pipe.dim_reduction.reducers.base.ArrayLike) → numpy.ndarray

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.

fit_transform(X: coco_pipe.dim_reduction.reducers.base.ArrayLike, y: coco_pipe.dim_reduction.reducers.base.ArrayLike | None = None) → numpy.ndarray

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_components)

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: int = 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.

model

Fitted spectral embedding estimator after fit or fit_transform.

Type:

sklearn.manifold.SpectralEmbedding or None

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: coco_pipe.dim_reduction.reducers.base.ArrayLike, y: coco_pipe.dim_reduction.reducers.base.ArrayLike | None = None) → SpectralEmbeddingReducer

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

abstract transform(X: coco_pipe.dim_reduction.reducers.base.ArrayLike) → numpy.ndarray

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.

fit_transform(X: coco_pipe.dim_reduction.reducers.base.ArrayLike, y: coco_pipe.dim_reduction.reducers.base.ArrayLike | None = None) → numpy.ndarray

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_components)

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)