coco_pipe.dim_reduction.reducers ================================ .. py:module:: coco_pipe.dim_reduction.reducers Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/coco_pipe/dim_reduction/reducers/base/index /autoapi/coco_pipe/dim_reduction/reducers/linear/index /autoapi/coco_pipe/dim_reduction/reducers/manifold/index /autoapi/coco_pipe/dim_reduction/reducers/neighbor/index /autoapi/coco_pipe/dim_reduction/reducers/neural/index /autoapi/coco_pipe/dim_reduction/reducers/spatiotemporal/index /autoapi/coco_pipe/dim_reduction/reducers/topology/index Classes ------- .. autoapisummary:: coco_pipe.dim_reduction.reducers.BaseReducer coco_pipe.dim_reduction.reducers.IncrementalPCAReducer coco_pipe.dim_reduction.reducers.PCAReducer coco_pipe.dim_reduction.reducers.IsomapReducer coco_pipe.dim_reduction.reducers.LLEReducer coco_pipe.dim_reduction.reducers.MDSReducer coco_pipe.dim_reduction.reducers.SpectralEmbeddingReducer coco_pipe.dim_reduction.reducers.TSNEReducer Package Contents ---------------- .. py:class:: BaseReducer(n_components: int = 2, **kwargs) Bases: :py:obj:`abc.ABC` Abstract base class for all dimensionality reduction implementations. This class defines the standard interface that all reducers must implement and is safe to subclass for custom reducers. It provides built-in support for model persistence (save/load) using joblib. For custom reducers operating on nonstandard data layouts, override `capabilities` so the manager layer can route validation, scoring, plotting, and reporting correctly. :param n_components: Target dimensionality of the reduced representation. :type n_components: int, default=2 :param \*\*kwargs: Additional keyword arguments stored on `params` and typically forwarded to the wrapped estimator or backend implementation. :type \*\*kwargs: dict .. attribute:: n_components Target dimensionality of the reduced representation. :type: int .. attribute:: params Additional reducer parameters captured at initialization time. :type: dict .. attribute:: model Underlying fitted model object, such as a scikit-learn estimator or a scientific computing backend. This attribute should be populated by `fit`. :type: Any .. rubric:: Notes The `capabilities` property returns a plain dictionary consumed by the manager and evaluation layers. Custom reducers should declare supported diagnostics and scalar metadata explicitly through this mapping. Common keys include: - `input_ndim` : expected dimensionality of the input container - `input_layout` : semantic layout name such as `"standard"` - `has_transform` : whether `transform` is supported - `has_inverse_transform` : whether inverse transforms are available - `has_components` : whether PCA-like components are exposed - `supported_diagnostics` : names returned by `get_diagnostics` - `has_native_plot` : whether the reducer exposes its own plotting path - `is_linear` : whether the reducer is linear - `is_stochastic` : whether repeated runs can vary without a fixed seed .. rubric:: Examples >>> from sklearn.decomposition import PCA >>> from coco_pipe.dim_reduction import BaseReducer >>> >>> class CustomPCAReducer(BaseReducer): ... @property ... def capabilities(self): ... return self._merge_capabilities( ... super().capabilities, ... is_linear=True, ... has_components=True, ... supported_diagnostics=("explained_variance_ratio_",), ... ) ... ... def fit(self, X, y=None): ... self.model = PCA(n_components=self.n_components, **self.params) ... self.model.fit(X) ... return self ... ... def transform(self, X): ... return self.model.transform(X) .. py:attribute:: n_components :value: 2 .. py:attribute:: params .. py:attribute:: model :value: None .. py:attribute:: context_ :type: Dict[str, Any] .. py:property:: name :type: str Return a stable public display name for the reducer. .. py:method:: _filter_params(fn_or_class: Any, params: dict) -> dict Filter parameters to match the signature of a function or class. :param fn_or_class: The function or class to inspect. :type fn_or_class: Any :param params: The parameters to filter. :type params: dict :returns: **filtered_params** -- Parameters present in the signature. If the target accepts ``**kwargs`` or its signature cannot be inspected, the original parameter dictionary is returned unchanged. :rtype: dict .. rubric:: Notes This is a convenience helper for reducer implementations that wrap third-party estimators with partially overlapping constructor signatures. .. py:method:: _build_estimator(estimator_cls: Any, params: Optional[dict] = None, component_param: Optional[str] = 'n_components', **fixed_kwargs: Any) -> Any Instantiate an estimator with filtered reducer parameters. :param estimator_cls: Estimator class to instantiate. :type estimator_cls: Any :param params: Explicit parameter dictionary to filter instead of `self.params`. :type params: dict, optional :param component_param: Name of the constructor argument receiving `self.n_components`. Set to ``None`` to skip injecting the component count. :type component_param: str or None, default="n_components" :param \*\*fixed_kwargs: Keyword arguments always forwarded to the estimator constructor. :type \*\*fixed_kwargs: dict :returns: Instantiated estimator. :rtype: Any .. rubric:: Notes This helper assumes the wrapped backend is constructor-driven and can be configured from keyword arguments. .. py:method:: _require_fitted(method_name: str = 'transform', model: Any = None) -> Any Validate that a reducer backend has been fitted before access. :param method_name: Operation requiring a fitted model. :type method_name: str, default="transform" :param model: Backend model to check. Defaults to `self.model`. :type model: Any, optional :returns: The validated model instance. :rtype: Any :raises RuntimeError: If no fitted model is available. .. py:method:: _merge_capabilities(base_caps: Dict[str, Any], **overrides: Any) -> Dict[str, Any] Return a capability mapping updated with reducer-specific overrides. :param base_caps: Base capability mapping, typically `super().capabilities`. :type base_caps: dict :param \*\*overrides: Reducer-specific capability values to apply. :type \*\*overrides: dict :returns: Capability mapping with overrides applied. :rtype: dict .. py:method:: fit(X: ArrayLike, y: Optional[ArrayLike] = None) -> BaseReducer :abstractmethod: Fit the model to the data. :param X: Training data. Most reducers expect `(n_samples, n_features)`, but reducers with custom `capabilities["input_layout"]` may accept other layouts such as snapshot matrices or grouped trajectory tensors. :type X: ArrayLike :param y: Optional supervision aligned with the sample axis used by the reducer's declared input layout. :type y: ArrayLike, optional :returns: **self** -- The fitted reducer instance. :rtype: BaseReducer .. rubric:: Notes Most reducers expect `X` to have shape `(n_samples, n_features)`. Some reducers operate on alternative layouts and should document those layouts through `capabilities`. .. py:method:: transform(X: ArrayLike) -> numpy.ndarray :abstractmethod: Apply dimensionality reduction to X. :param X: New data to transform. Its layout should match the reducer's declared `capabilities`. :type X: ArrayLike :returns: **X_new** -- Reduced representation. The exact output shape depends on the reducer, but the last dimension usually matches `n_components`. :rtype: np.ndarray :raises RuntimeError: Raised by concrete implementations when `transform` is called before fitting or when the reducer does not support out-of-sample transforms. .. py:method:: fit_transform(X: ArrayLike, y: Optional[ArrayLike] = None) -> numpy.ndarray Fit the model to data and return the transformed data. This method usually calls `fit` and then `transform`, but reducers may override it for efficiency if the underlying algorithm supports a native combined path. :param X: Training data following the reducer's declared layout. :type X: ArrayLike :param y: Optional supervision aligned with the reducer's input layout. :type y: ArrayLike, optional :returns: **X_new** -- Reduced representation returned by `transform`. :rtype: np.ndarray .. py:method:: save(filepath: Union[str, os.PathLike]) -> None Persist the reducer to a file. The default implementation serializes the reducer instance with joblib. Custom reducers should either remain joblib-serializable or override this method and `load()` with a custom persistence strategy. :param filepath: Path to the output file. :type filepath: str or Path .. rubric:: Notes The default implementation serializes the reducer instance with `joblib.dump`. Custom reducers should either remain joblib-serializable or override this method and `load` with a custom persistence strategy. .. py:property:: capabilities :type: Dict[str, Any] Return reducer capability flags consumed by the manager layer. Custom reducers with nonstandard inputs should override at least `input_ndim` and `input_layout`. Reducers exposing diagnostics or scalar quality metadata should declare them explicitly through `supported_diagnostics` and `supported_metadata`. :returns: Mapping of reducer capability flags. :rtype: dict .. rubric:: Notes The default capabilities describe a typical estimator consuming `(samples, features)` input and exposing `transform`. .. py:method:: _attribute_dict(obj: Any, attrs: Iterable[str]) -> Dict[str, Any] Extract requested attributes from a target object into a dictionary. This helper filters missing attributes and swallows common access errors (such as deferred scikit-learn properties) to return only what is currently available on the target. :param obj: Target object to inspect. :type obj: Any :param attrs: Attribute names to attempt to extract. :type attrs: iterable of str :returns: Mapping of available attribute names to their values. :rtype: dict .. py:method:: get_diagnostics() -> Dict[str, Any] Return diagnostic arrays or structured artifacts. Diagnostics are intended for non-scalar outputs such as explained variance curves, eigenvalues, modes, graphs, or training histories. Only names declared in `capabilities["supported_diagnostics"]` are queried. :returns: **diagnostics** -- Dictionary of diagnostic attributes declared in `capabilities["supported_diagnostics"]`. :rtype: dict :raises RuntimeError: If the reducer has not been fitted. .. py:method:: get_quality_metadata() -> Dict[str, Any] Return scalar metadata about the reduction process or quality. Typical examples include iteration counts, optimization stress, final loss values, or backend-specific convergence flags. Only names declared in `capabilities["supported_metadata"]` are queried. :returns: **metadata** -- Dictionary containing only scalar values corresponding to keys declared in `capabilities["supported_metadata"]`. :rtype: dict :raises RuntimeError: If the reducer has not been fitted. .. py:method:: get_components() -> numpy.ndarray Return reducer-defined component-like outputs. :returns: Reducer-defined component array. :rtype: np.ndarray :raises ValueError: If the reducer does not expose public components. .. py:method:: load(filepath: Union[str, os.PathLike]) -> BaseReducer :classmethod: Load a reducer from a file. :param filepath: Path to the file to load. :type filepath: str or Path :returns: **reducer** -- The loaded reducer instance. :rtype: BaseReducer .. rubric:: Notes This method assumes the reducer was serialized with `save` or a compatible `joblib.dump` call. .. py:class:: IncrementalPCAReducer(n_components: int = 2, batch_size: Optional[int] = None, **kwargs) Bases: :py:obj:`coco_pipe.dim_reduction.reducers.base.BaseReducer` Incremental PCA reducer. This reducer wraps `sklearn.decomposition.IncrementalPCA` for batch-wise fitting when the full dataset is too large to process in one pass. :param n_components: Number of principal components to keep. :type n_components: int, default=2 :param batch_size: Number of samples processed per batch. :type batch_size: int, optional :param \*\*kwargs: Additional keyword arguments forwarded to `IncrementalPCA` after signature filtering. :type \*\*kwargs: dict .. attribute:: batch_size Batch size used when fitting the incremental estimator. :type: int or None .. attribute:: model Fitted IncrementalPCA estimator after `fit` or `partial_fit`. :type: sklearn.decomposition.IncrementalPCA or None .. seealso:: :obj:`PCAReducer` Standard in-memory linear PCA reducer. :obj:`DaskPCAReducer` Linear PCA variant for lazy or distributed arrays. :obj:`DaskTruncatedSVDReducer` Linear factorization alternative for lazy arrays. :obj:`IsomapReducer` Nonlinear manifold learner based on geodesic distances. :obj:`TSNEReducer` Nonlinear neighborhood-preserving embedding. :obj:`UMAPReducer` Nonlinear graph-based embedding balancing local and global structure. .. rubric:: Examples >>> import numpy as np >>> from coco_pipe.dim_reduction import IncrementalPCAReducer >>> X = np.random.rand(100, 12) >>> reducer = IncrementalPCAReducer(n_components=3, batch_size=25) >>> _ = reducer.fit(X) >>> reducer.transform(X[:10]).shape (10, 3) >>> stream = IncrementalPCAReducer(n_components=2, batch_size=20) >>> _ = stream.partial_fit(X[:50]) >>> _ = stream.partial_fit(X[50:]) >>> stream.transform(X).shape (100, 2) .. py:property:: capabilities :type: dict Return capability metadata for Incremental PCA. :returns: Capability mapping describing Incremental PCA as a linear component-based reducer. :rtype: dict .. py:attribute:: batch_size :value: None .. py:method:: fit(X: coco_pipe.dim_reduction.reducers.base.ArrayLike, y: Optional[coco_pipe.dim_reduction.reducers.base.ArrayLike] = None) -> IncrementalPCAReducer Fit Incremental PCA in batch mode. :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: IncrementalPCAReducer .. rubric:: Examples >>> import numpy as np >>> from coco_pipe.dim_reduction import IncrementalPCAReducer >>> X = np.random.rand(30, 6) >>> reducer = IncrementalPCAReducer(n_components=2, batch_size=10) >>> _ = reducer.fit(X) >>> reducer.model is not None True .. py:method:: partial_fit(X: coco_pipe.dim_reduction.reducers.base.ArrayLike, y: Optional[coco_pipe.dim_reduction.reducers.base.ArrayLike] = None) -> IncrementalPCAReducer Incrementally fit the estimator on a batch of samples. :param X: Batch of training samples. :type X: ArrayLike of shape (n_samples, n_features) :param y: Ignored. Present for API compatibility. :type y: ArrayLike, optional :returns: Reducer instance after updating the incremental estimator. :rtype: IncrementalPCAReducer .. rubric:: Examples >>> import numpy as np >>> from coco_pipe.dim_reduction import IncrementalPCAReducer >>> X = np.random.rand(40, 6) >>> reducer = IncrementalPCAReducer(n_components=2, batch_size=20) >>> _ = reducer.partial_fit(X[:20]) >>> _ = reducer.partial_fit(X[20:]) >>> reducer.model is not None True .. py:method:: transform(X: coco_pipe.dim_reduction.reducers.base.ArrayLike) -> numpy.ndarray Project data onto the fitted incremental PCA basis. :param X: Data to project. :type X: ArrayLike of shape (n_samples, n_features) :returns: Projected coordinates in component space. :rtype: np.ndarray of shape (n_samples, n_components) :raises RuntimeError: If the reducer has not been fitted. .. py:method:: get_components() -> numpy.ndarray Return the incremental PCA component loading matrix. :returns: Principal component loading matrix. :rtype: np.ndarray :raises RuntimeError: If the reducer has not been fitted. .. py:class:: PCAReducer(n_components: int = 2, **kwargs) Bases: :py:obj:`coco_pipe.dim_reduction.reducers.base.BaseReducer` Principal Component Analysis reducer. This reducer wraps `sklearn.decomposition.PCA` and provides a linear low-dimensional embedding based on singular value decomposition. :param n_components: Number of principal components to keep. :type n_components: int, default=2 :param \*\*kwargs: Additional keyword arguments forwarded to `sklearn.decomposition.PCA` after signature filtering. Common options include `whiten`, `svd_solver`, and `random_state`. :type \*\*kwargs: dict .. attribute:: model Fitted PCA estimator after `fit`. :type: sklearn.decomposition.PCA or None .. rubric:: Notes This is a deterministic linear reducer unless a randomized solver is used. .. seealso:: :obj:`IncrementalPCAReducer` Linear PCA variant for batch-wise fitting. :obj:`DaskPCAReducer` Linear PCA variant for lazy or distributed arrays. :obj:`DaskTruncatedSVDReducer` Linear factorization alternative for lazy arrays. :obj:`IsomapReducer` Nonlinear manifold learner based on geodesic distances. :obj:`TSNEReducer` Nonlinear neighborhood-preserving embedding. :obj:`UMAPReducer` Nonlinear graph-based embedding balancing local and global structure. :obj:`PHATEReducer` Nonlinear diffusion-based embedding for smooth trajectories. .. rubric:: Examples >>> import numpy as np >>> from coco_pipe.dim_reduction import PCAReducer >>> X = np.random.rand(100, 10) >>> reducer = PCAReducer(n_components=2, random_state=42) >>> _ = reducer.fit(X) >>> X_reduced = reducer.transform(X) >>> X_reduced.shape (100, 2) >>> reducer.explained_variance_ratio_.shape (2,) >>> reducer.components_.shape (2, 10) >>> reducer = PCAReducer(n_components=3, whiten=True) >>> reducer.fit_transform(X).shape (100, 3) .. py:property:: capabilities :type: dict Return capability metadata for PCA. :returns: Capability mapping describing PCA as a linear component-based reducer. :rtype: dict .. py:method:: fit(X: coco_pipe.dim_reduction.reducers.base.ArrayLike, y: Optional[coco_pipe.dim_reduction.reducers.base.ArrayLike] = None) -> PCAReducer Fit PCA 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: PCAReducer .. rubric:: Examples >>> import numpy as np >>> from coco_pipe.dim_reduction import PCAReducer >>> X = np.random.rand(20, 5) >>> reducer = PCAReducer(n_components=2) >>> _ = reducer.fit(X) >>> reducer.model is not None True .. py:method:: transform(X: coco_pipe.dim_reduction.reducers.base.ArrayLike) -> numpy.ndarray Project data onto the fitted principal component basis. :param X: Data to project. :type X: ArrayLike of shape (n_samples, n_features) :returns: Projected coordinates in principal component space. :rtype: np.ndarray of shape (n_samples, n_components) :raises RuntimeError: If the reducer has not been fitted. .. py:property:: explained_variance_ratio_ :type: numpy.ndarray Percentage of variance explained by each selected component. :returns: Explained variance ratio for each retained component. :rtype: np.ndarray of shape (n_components,) :raises RuntimeError: If the reducer has not been fitted. .. py:property:: components_ :type: numpy.ndarray Principal axes in feature space. :returns: Principal component loading matrix. :rtype: np.ndarray of shape (n_components, n_features) :raises RuntimeError: If the reducer has not been fitted. .. py:method:: get_components() -> numpy.ndarray Return the principal component loading matrix. :returns: Principal component loading matrix. :rtype: np.ndarray :raises RuntimeError: If the reducer has not been fitted. .. 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) .. py:class:: TSNEReducer(n_components: int = 2, **kwargs) Bases: :py:obj:`coco_pipe.dim_reduction.reducers.base.BaseReducer` t-SNE reducer. t-Distributed Stochastic Neighbor Embedding (t-SNE) is a neighborhood- preserving method designed primarily for visualization. It optimizes a low-dimensional embedding by matching pairwise similarities between the original space and the embedding. :param n_components: Number of embedding dimensions. :type n_components: int, default=2 :param \*\*kwargs: Additional keyword arguments forwarded to `sklearn.manifold.TSNE` after signature filtering. Common options include `perplexity`, `learning_rate`, `max_iter`, `init`, and `random_state`. :type \*\*kwargs: dict .. attribute:: embedding_ Learned training-set embedding after `fit` or `fit_transform`. :type: np.ndarray or None .. attribute:: model Fitted t-SNE estimator after `fit` or `fit_transform`. :type: sklearn.manifold.TSNE or None .. rubric:: Notes `transform` is not supported because scikit-learn t-SNE does not provide an out-of-sample projection API. .. seealso:: :obj:`UMAPReducer` Nonlinear graph-based embedding with transform support. :obj:`PacmapReducer` Nonlinear embedding balancing local and global structure. :obj:`TrimapReducer` Nonlinear triplet-based embedding preserving global layout. :obj:`PHATEReducer` Diffusion-based embedding for continuous trajectories. :obj:`PCAReducer` Linear baseline for global variance preservation. :obj:`IsomapReducer` Nonlinear geodesic-distance manifold embedding. .. rubric:: Examples >>> import numpy as np >>> from coco_pipe.dim_reduction import TSNEReducer >>> X = np.random.rand(100, 10) >>> reducer = TSNEReducer(n_components=2, perplexity=20, random_state=42) >>> embedding = reducer.fit_transform(X) >>> embedding.shape (100, 2) >>> reducer.get_quality_metadata()["kl_divergence_"] >= 0 True >>> _ = reducer.fit(X) >>> reducer.embedding_.shape (100, 2) .. py:property:: capabilities :type: dict Return capability metadata for t-SNE. :returns: Capability mapping describing t-SNE as a nonlinear stochastic reducer without out-of-sample transform support. :rtype: dict .. py:attribute:: embedding_ :value: None .. py:method:: fit(X: coco_pipe.dim_reduction.reducers.base.ArrayLike, y: Optional[coco_pipe.dim_reduction.reducers.base.ArrayLike] = None) -> TSNEReducer Fit t-SNE 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: TSNEReducer .. rubric:: Examples >>> import numpy as np >>> from coco_pipe.dim_reduction import TSNEReducer >>> X = np.random.rand(30, 6) >>> reducer = TSNEReducer(n_components=2, perplexity=5, max_iter=250) >>> _ = 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 t-SNE does not support out-of-sample transformation. :param X: Ignored input included for API compatibility. :type X: ArrayLike :raises NotImplementedError: Always raised because t-SNE 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 t-SNE 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 t-SNE. :rtype: np.ndarray of shape (n_samples, n_components)