coco_pipe ========= .. py:module:: coco_pipe .. autoapi-nested-parse:: Package initializer for the coco_pipe package. Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/coco_pipe/decoding/index /autoapi/coco_pipe/descriptors/index /autoapi/coco_pipe/dim_reduction/index /autoapi/coco_pipe/fm/index /autoapi/coco_pipe/io/index /autoapi/coco_pipe/report/index /autoapi/coco_pipe/utils/index /autoapi/coco_pipe/viz/index Attributes ---------- .. autoapisummary:: coco_pipe.METHODS Classes ------- .. autoapisummary:: coco_pipe.DescriptorConfig coco_pipe.DescriptorPipeline coco_pipe.BaseReducer coco_pipe.DimReduction coco_pipe.IncrementalPCAReducer coco_pipe.IsomapReducer coco_pipe.LLEReducer coco_pipe.MDSReducer coco_pipe.PCAReducer coco_pipe.SpectralEmbeddingReducer coco_pipe.TSNEReducer Functions --------- .. autoapisummary:: coco_pipe.continuity coco_pipe.interpret_features coco_pipe.lcmc coco_pipe.shepard_diagram_data coco_pipe.trustworthiness Package Contents ---------------- .. py:class:: DescriptorConfig(/, **data: Any) Bases: :py:obj:`_StrictConfigModel` Top-level descriptors configuration object. .. attribute:: input Runtime input requirements for explicit array extraction. :type: DescriptorInputConfig .. attribute:: families Enabled descriptor families and their typed configs. :type: DescriptorFamiliesConfig .. attribute:: precision Output dtype used for the final descriptor matrix. :type: {"float32", "float64"} .. attribute:: runtime Runtime execution and error-handling settings. :type: DescriptorRuntimeConfig .. rubric:: Notes This object is the stable config boundary for :class:`coco_pipe.descriptors.core.DescriptorPipeline`. Parsing this config validates local structure here, then the pipeline applies the remaining cross-family compatibility checks when it builds the execution plan. .. py:attribute:: input :type: DescriptorInputConfig :value: None .. py:attribute:: families :type: DescriptorFamiliesConfig :value: None .. py:attribute:: precision :type: Literal['float32', 'float64'] :value: 'float32' .. py:attribute:: runtime :type: DescriptorRuntimeConfig :value: None .. py:class:: DescriptorPipeline(config: coco_pipe.descriptors.configs.DescriptorConfig | collections.abc.Mapping[str, Any]) Run config-driven descriptor extraction on explicit arrays. :param config: Typed descriptors configuration or a mapping accepted by :class:`DescriptorConfig`. :type config: DescriptorConfig or Mapping[str, Any] .. attribute:: config Parsed descriptors configuration. :type: DescriptorConfig .. attribute:: extractors Enabled family extractors in deterministic family order. :type: list of BaseDescriptorExtractor .. attribute:: signal_extractors Enabled non-PSD extractors that consume raw signal batches directly. :type: list of BaseDescriptorExtractor .. attribute:: psd_groups Planned PSD reuse groups derived once from the enabled extractors. :type: list of _PSDGroup .. attribute:: family_order Deterministic family order used when merging batch-local outputs. :type: list of str .. rubric:: Notes The pipeline is config-bound but runtime-stateless. Construction performs config parsing, corrected-band compatibility checks, and planner setup once. Each call to :meth:`extract` then validates the explicit runtime inputs, executes the planned families, and returns one flat descriptor matrix plus any collected failures. .. py:attribute:: config .. py:attribute:: extractors :type: list[coco_pipe.descriptors.extractors.base.BaseDescriptorExtractor] :value: [] .. py:attribute:: signal_extractors .. py:attribute:: psd_groups :value: [] .. py:attribute:: family_order .. py:method:: extract(X: numpy.ndarray, ids: collections.abc.Sequence[Any] | numpy.ndarray | None = None, sfreq: float | None = None, channel_names: collections.abc.Sequence[str] | numpy.ndarray | None = None) -> dict[str, Any] Extract descriptors from explicit NumPy inputs. :param X: Signal array with shape ``(n_obs, n_channels, n_times)``. :type X: np.ndarray :param ids: Observation identifiers aligned with ``X``. :type ids: sequence or np.ndarray, optional :param sfreq: Sampling frequency in Hertz. Required when enabled families depend on spectral estimates or spectral entropy. :type sfreq: float, optional :param channel_names: Channel labels. Required for channel-resolved outputs. :type channel_names: sequence of str or np.ndarray, optional :returns: Dictionary with keys ``X``, ``descriptor_names``, and ``failures``. :rtype: dict[str, Any] :raises ValueError: If the explicit input contract is not satisfied. :raises ImportError: If an optional backend required by the enabled families is missing. .. rubric:: Notes When ``runtime.on_error="warn"``, extraction still completes and stores failures in ``result["failures"]`` before emitting one aggregate warning at the pipeline level. The returned row order always matches the input observation order. .. py:method:: pool_channels(result: collections.abc.Mapping[str, Any], channel_groups: collections.abc.Mapping[str, collections.abc.Sequence[str]]) -> dict[str, Any] Pool sensor-level descriptor columns into grouped channel outputs. :param result: Standard descriptor result produced by :meth:`extract`. :type result: mapping :param channel_groups: Channel groups used to replace sensor-level descriptor columns with grouped ``"chgrp-..."`` outputs. :type channel_groups: mapping of str to sequence of str :returns: Descriptor result with grouped channel features and unchanged failures. :rtype: dict[str, Any] :raises ValueError: If the provided result is malformed or if any requested group cannot be formed from the sensor-level descriptor columns. .. py:data:: METHODS :value: ('PCA', 'IncrementalPCA', 'DaskPCA', 'DaskTruncatedSVD', 'Isomap', 'LLE', 'MDS',... .. 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:: DimReduction(method: Union[str, coco_pipe.dim_reduction.config.BaseReducerConfig], n_components: int = 2, params: Optional[Dict[str, Any]] = None, **kwargs) Manage one dimensionality reduction workflow. :param method: Canonical public reducer name or a typed configuration object. Method names are exact and must match the registry, for example ``"PCA"``, ``"Isomap"``, ``"Pacmap"``, or ``"TopologicalAE"``. :type method: str or BaseReducerConfig :param n_components: Target dimensionality when ``method`` is a string. :type n_components: int, default=2 :param params: Additional reducer keyword arguments merged into the constructor arguments when ``method`` is a string. :type params: dict, optional :param \*\*kwargs: Runtime reducer keyword overrides. These are merged after ``params``. :type \*\*kwargs: dict .. attribute:: method Canonical reducer name. :type: str .. attribute:: n_components Target dimensionality used for the reducer instance. :type: int .. attribute:: reducer Instantiated reducer backend. :type: BaseReducer .. attribute:: metrics_ Cached scalar evaluation summaries from the latest ``score()`` call. :type: dict .. attribute:: quality_metadata_ Cached scalar reducer metadata exposed through the reducer contract. :type: dict .. attribute:: diagnostics_ Cached non-scalar diagnostic artifacts exposed through the reducer contract or the evaluation layer. :type: dict .. attribute:: metric_records_ Cached tidy metric observations produced by the evaluator. :type: list of dict .. attribute:: interpretation_ Cached feature interpretation payloads from the latest ``interpret()`` call. :type: dict .. attribute:: interpretation_records_ Cached tidy feature-interpretation observations. :type: list of dict .. seealso:: :obj:`coco_pipe.dim_reduction.analysis.interpret_features` Pure interpretation backend used by ``interpret()``. :obj:`coco_pipe.dim_reduction.evaluation.core.evaluate_embedding` Pure evaluator used by ``score()``. :obj:`coco_pipe.dim_reduction.evaluation.core.MethodSelector` Post-hoc comparison and ranking over already-scored reducers. :obj:`coco_pipe.viz.dim_reduction` Plotting utilities for embeddings, metrics, and diagnostics. .. rubric:: Examples >>> reducer = DimReduction("UMAP", n_components=2, n_neighbors=15) >>> embedding = reducer.fit_transform(X) >>> scores = reducer.score(embedding, X=X) >>> "trustworthiness" in scores["metrics"] True >>> interpretation = reducer.interpret( ... X, ... X_emb=embedding, ... analyses=["correlation"], ... feature_names=feature_names, ... ) >>> "correlation" in interpretation["analysis"] True .. py:attribute:: reducer_kwargs .. py:attribute:: reducer :type: coco_pipe.dim_reduction.reducers.base.BaseReducer .. py:attribute:: metrics_ :type: Dict[str, Any] .. py:attribute:: quality_metadata_ :type: Dict[str, Any] .. py:attribute:: diagnostics_ :type: Dict[str, Any] .. py:attribute:: metric_records_ :type: List[Dict[str, Any]] :value: [] .. py:attribute:: interpretation_ :type: Dict[str, Any] .. py:attribute:: interpretation_records_ :type: List[Dict[str, Any]] :value: [] .. py:property:: random_state :type: Optional[int] Return the random seed from parameters if any. .. py:property:: capabilities :type: Dict[str, Any] Return reducer capability metadata through the manager interface. .. py:method:: _reset_cached_outputs() -> None Clear cached evaluation outputs. .. py:method:: _validate_input(X: Any) -> numpy.ndarray Validate reducer input shape and coerce to a NumPy array. :param X: Input data accepted by the reducer. Objects exposing ``get_data()`` are unwrapped before validation. :type X: array-like or MNE object :returns: **X** -- Validated reducer input. :rtype: np.ndarray :raises ValueError: If the input dimensionality does not match the reducer contract. .. py:method:: fit(X: Any, y: Optional[Any] = None) -> DimReduction Fit the reducer on the provided data. :param X: Input data in the reducer's native layout. :type X: array-like or MNE object :param y: Optional supervision forwarded to the reducer. :type y: array-like, optional :returns: **self** -- The fitted reducer. :rtype: DimReduction .. py:method:: transform(X: Any) -> numpy.ndarray Transform new data with a fitted reducer. :param X: Input data in the reducer's native layout. :type X: array-like or MNE object :returns: **X_emb** -- Reduced representation returned by the reducer. :rtype: np.ndarray .. py:method:: fit_transform(X: Any, y: Optional[Any] = None) -> numpy.ndarray Fit the reducer and return the reduced representation. :param X: Input data in the reducer's native layout. :type X: array-like or MNE object :param y: Optional supervision forwarded to the reducer. :type y: array-like, optional :returns: **X_emb** -- Reduced representation returned by the reducer. :rtype: np.ndarray .. py:method:: get_components() -> numpy.ndarray Return reducer-defined component-like outputs. :returns: **components** -- Component-like array exposed by the reducer. :rtype: np.ndarray :raises ValueError: If the reducer does not expose public components. .. py:method:: score(X_emb: numpy.ndarray, X: Any = None, n_neighbors: int = 5, metrics: Optional[List[str]] = None, k_values: Optional[List[int]] = None, labels: Optional[numpy.ndarray] = None, groups: Optional[numpy.ndarray] = None, times: Optional[numpy.ndarray] = None, separation_method: str = 'centroid') -> Dict[str, Dict[str, Any]] Evaluate an explicit embedding against the original data. :param X_emb: Embedded data to evaluate. :type X_emb: array-like :param X: Original high-dimensional data in evaluation-ready layout. This is required for standard 2D metrics and optional for native 3D trajectory metrics. :type X: array-like, optional :param n_neighbors: K-nearest neighbors size for metric computation. :type n_neighbors: int, default=5 :param metrics: Metric selectors to compute. ``None`` evaluates all metric families available for the embedding shape. :type metrics: list of str, optional :param k_values: Neighborhood sizes used for multi-scale standard metric evaluation. :type k_values: list of int, optional :param labels: Optional labels aligned with the embedding. Used for trajectory separation when ``X_emb`` is 3D and for explicit supervised 2D metrics when requested. :type labels: np.ndarray, optional :param groups: Optional grouping variable aligned with the embedding. Required by grouped supervised evaluation metrics such as ``separation_logreg_balanced_accuracy``. :type groups: np.ndarray, optional :param times: Optional trajectory time coordinates aligned with the trajectory length axis. :type times: np.ndarray, optional :param separation_method: Separation definition passed to trajectory evaluation when labels are available for native 3D trajectory embeddings. :type separation_method: str, default="centroid" :returns: **scores** -- Dictionary with keys ``"metrics"``, ``"metadata"``, and ``"diagnostics"``. :rtype: dict .. rubric:: Notes ``score()`` does not infer or cache embeddings. Callers must pass ``X_emb`` explicitly. ``X`` is only required when the requested evaluation path needs the original high-dimensional samples. .. py:method:: interpret(X: numpy.ndarray, *, X_emb: numpy.ndarray, analyses: Optional[List[str]] = None, feature_names: Optional[List[str]] = None, n_repeats: int = 5, random_state: Optional[int] = None) -> Dict[str, Any] Run feature interpretation analyses for an explicit embedding. :param X: Original input data. :type X: np.ndarray :param X_emb: Explicit embedding aligned with ``X``. :type X_emb: np.ndarray :param analyses: Interpretation analyses to compute. ``None`` defaults to ``["correlation"]``. :type analyses: list of {"correlation", "perturbation", "gradient"}, optional :param feature_names: Feature names aligned with the columns of ``X`` when the requested interpretation returns feature-keyed outputs. :type feature_names: list of str, optional :param n_repeats: Number of shuffles per feature for perturbation importance. :type n_repeats: int, default=5 :param random_state: Random seed for perturbation importance. :type random_state: int, optional :returns: Dictionary with keys ``"analysis"`` and ``"records"``. :rtype: dict .. rubric:: Notes ``interpret()`` does not fit the reducer or compute embeddings. Callers must pass both ``X`` and ``X_emb`` explicitly. .. seealso:: :obj:`coco_pipe.dim_reduction.analysis.interpret_features` Pure interpretation backend used by this manager method. :obj:`score` Evaluate structure-preservation metrics for an explicit embedding. .. rubric:: Examples >>> reducer = DimReduction("PCA", n_components=2) >>> embedding = reducer.fit_transform(X) >>> result = reducer.interpret( ... X, ... X_emb=embedding, ... analyses=["correlation"], ... feature_names=feature_names, ... ) >>> sorted(result) ['analysis', 'records'] .. py:method:: get_diagnostics() -> Dict[str, Any] Return cached diagnostics merged with reducer diagnostics. :returns: **diagnostics** -- Diagnostic artifacts declared by the reducer contract and the evaluation layer. :rtype: dict .. py:method:: get_quality_metadata() -> Dict[str, Any] Return cached scalar metadata merged with reducer metadata. :returns: **metadata** -- Scalar metadata declared by the reducer contract and the evaluation layer. :rtype: dict .. py:method:: get_metrics() -> Dict[str, Any] Return cached scalar metrics from the latest ``score()`` call. .. py:method:: get_summary() -> Dict[str, Any] Return a normalized summary payload for report and export paths. :returns: Plain dictionary containing method identity, cached scalar summaries, reducer metadata, diagnostics, tidy metric records, and capability flags, plus cached feature interpretation payloads. :rtype: dict .. rubric:: Notes The summary does not include an embedding payload. Embeddings are handled explicitly outside the manager and must be passed directly to plotting or reporting utilities that need them. .. py:method:: save(path: Union[str, pathlib.Path]) Save the underlying reducer to disk. :param path: Output path for reducer persistence. :type path: str or Path .. rubric:: Notes Only the reducer model is persisted. Cached manager state such as metrics and diagnostics is not included. .. py:method:: load(path: Union[str, pathlib.Path], method: str) -> DimReduction :classmethod: Load a persisted reducer and wrap it in a fresh manager. :param path: Path to a serialized reducer saved with ``save()``. :type path: str or Path :param method: Canonical public reducer name used to reconstruct the manager. :type method: str :returns: Fresh manager wrapping the loaded reducer model. :rtype: DimReduction .. rubric:: Notes This restores the reducer model only. Cached manager state such as scores, diagnostics, and metric records is not persisted. .. 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:: 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:: 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:: 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) .. py:function:: continuity(Q: numpy.ndarray, k: int) -> float Compute continuity from a co-ranking matrix. Continuity penalizes extrusions, i.e. points that are among the ``k`` nearest neighbors in the original space but are pushed farther away in the embedding. :param Q: Co-ranking matrix. :type Q: np.ndarray of shape (n_samples - 1, n_samples - 1) :param k: Neighborhood size. The normalization used by continuity requires ``2 * n_samples - 3 * k - 1 > 0``. :type k: int :returns: Continuity score in ``[0, 1]``. Higher is better. :rtype: float :raises ValueError: If ``Q`` is invalid or if ``k`` falls outside the valid domain. .. seealso:: :obj:`trustworthiness` Complementary intrusion-based metric. :obj:`compute_coranking_matrix` Construct the required co-ranking matrix. .. rubric:: Examples >>> import numpy as np >>> Q = np.diag([1, 1, 1, 1]) >>> continuity(Q, k=1) 1.0 .. py:function:: interpret_features(X: numpy.ndarray, *, X_emb: Optional[numpy.ndarray] = None, model: Optional[Any] = None, analyses: Optional[Sequence[str]] = None, feature_names: Optional[Sequence[str]] = None, method_name: str = 'embedding', n_repeats: int = 5, random_state: Optional[int] = None) -> Dict[str, Any] Run one or more feature interpretation analyses. :param X: Original input data. :type X: np.ndarray :param X_emb: Explicit embedding used by correlation-based analysis. :type X_emb: np.ndarray, optional :param model: Fitted reducer or model used by importance analyses. :type model: Any, optional :param analyses: Analyses to compute. ``None`` defaults to ``("correlation",)``. :type analyses: sequence of {"correlation", "perturbation", "gradient"}, optional :param feature_names: Feature names aligned with ``X`` when the requested analysis returns feature-keyed outputs. :type feature_names: sequence of str, optional :param method_name: Display name written into the returned analysis records. :type method_name: str, default="embedding" :param n_repeats: Number of permutations per feature for perturbation importance. :type n_repeats: int, default=5 :param random_state: Random seed for perturbation importance. :type random_state: int, optional :returns: Dictionary with keys: - ``analysis``: nested analysis payloads - ``records``: tidy analysis records as ``list[dict]`` :rtype: dict :raises ValueError: If a requested analysis is unsupported, missing required inputs, or lacks required feature names. .. rubric:: Notes This function is a pure interpretation backend for manager, report, or visualization workflows. It does not fit models, compute embeddings, or mutate reducer state. .. seealso:: :obj:`correlate_features` Feature-to-dimension interpretation from explicit embeddings. :obj:`perturbation_importance` Model-agnostic importance based on shuffled features. :obj:`gradient_importance` Encoder saliency for supported torch-based reducers. .. rubric:: Examples >>> import numpy as np >>> class MockReducer: ... def transform(self, X): ... return X[:, :2] >>> X = np.array([[0.0, 1.0], [1.0, 0.0], [2.0, 1.0]]) >>> X_emb = X[:, :2] >>> result = interpret_features( ... X, ... X_emb=X_emb, ... model=MockReducer(), ... analyses=["correlation", "perturbation"], ... feature_names=["f1", "f2"], ... n_repeats=1, ... random_state=0, ... ) >>> sorted(result) ['analysis', 'records'] .. py:function:: lcmc(Q: numpy.ndarray, k: int) -> float Compute the local continuity meta-criterion (LCMC). :param Q: Co-ranking matrix. :type Q: np.ndarray of shape (n_samples - 1, n_samples - 1) :param k: Neighborhood size. :type k: int :returns: LCMC score. Higher is better. :rtype: float :raises ValueError: If ``Q`` is invalid or if ``k`` falls outside the valid domain. .. seealso:: :obj:`trustworthiness` Neighbor-preservation metric. :obj:`continuity` Neighbor-consistency metric. .. rubric:: Examples >>> import numpy as np >>> Q = np.diag([1, 1, 1, 1]) >>> isinstance(lcmc(Q, k=1), float) True .. py:function:: shepard_diagram_data(X: numpy.ndarray, X_embedded: numpy.ndarray, sample_size: int = 1000, random_state: Optional[int] = None) -> Tuple[numpy.ndarray, numpy.ndarray] Compute sampled pairwise distances for a Shepard diagram. :param X: Original high-dimensional data. :type X: np.ndarray of shape (n_samples, n_features) :param X_embedded: Low-dimensional embedding of the same samples. :type X_embedded: np.ndarray of shape (n_samples, n_components) :param sample_size: Number of samples to keep before computing pairwise distances. If ``sample_size`` is at least ``n_samples``, all samples are used. :type sample_size: int, default=1000 :param random_state: Random seed used when subsampling. :type random_state: int, optional :returns: Pairwise distances in the original and embedded spaces. :rtype: tuple[np.ndarray, np.ndarray] :raises ValueError: If the inputs are invalid or if ``sample_size <= 1``. .. seealso:: :obj:`compute_coranking_matrix` Rank-based global quality summary. .. rubric:: Examples >>> import numpy as np >>> X = np.random.RandomState(0).rand(10, 3) >>> X_emb = X[:, :2] >>> d_orig, d_emb = shepard_diagram_data(X, X_emb, sample_size=5, random_state=0) >>> len(d_orig) == len(d_emb) True .. py:function:: trustworthiness(Q: numpy.ndarray, k: int) -> float Compute trustworthiness from a co-ranking matrix. Trustworthiness penalizes intrusions, i.e. points that appear among the ``k`` nearest neighbors in the embedding but were farther away in the original space. :param Q: Co-ranking matrix. :type Q: np.ndarray of shape (n_samples - 1, n_samples - 1) :param k: Neighborhood size. The normalization used by trustworthiness requires ``2 * n_samples - 3 * k - 1 > 0``. :type k: int :returns: Trustworthiness score in ``[0, 1]``. Higher is better. :rtype: float :raises ValueError: If ``Q`` is invalid or if ``k`` falls outside the valid domain. .. seealso:: :obj:`continuity` Complementary extrusion-based metric. :obj:`compute_coranking_matrix` Construct the required co-ranking matrix. .. rubric:: Examples >>> import numpy as np >>> Q = np.diag([1, 1, 1, 1]) >>> trustworthiness(Q, k=1) 1.0