coco_pipe.dim_reduction.config ============================== .. py:module:: coco_pipe.dim_reduction.config .. autoapi-nested-parse:: Dimensionality Reduction Configuration ====================================== Strict configuration models and reducer registry for the dim-reduction module. This module defines: - canonical reducer names and lazy registry lookup - strict pydantic configs for each supported reducer - evaluation configuration with early validation for metric and ranking choices The config layer follows the same explicit design as the rest of the module: exact method names, no aliasing, no compatibility wrappers, and no permissive extra fields. Author: Hamza Abdelhedi (hamza.abdelhedi@umontreal.ca) Attributes ---------- .. autoapisummary:: coco_pipe.dim_reduction.config.METHODS Classes ------- .. autoapisummary:: coco_pipe.dim_reduction.config.BaseReducerConfig coco_pipe.dim_reduction.config.StochasticReducerConfig coco_pipe.dim_reduction.config.PCAConfig coco_pipe.dim_reduction.config.IncrementalPCAConfig coco_pipe.dim_reduction.config.DaskPCAConfig coco_pipe.dim_reduction.config.DaskTruncatedSVDConfig coco_pipe.dim_reduction.config.UMAPConfig coco_pipe.dim_reduction.config.TSNEConfig coco_pipe.dim_reduction.config.PacmapConfig coco_pipe.dim_reduction.config.TrimapConfig coco_pipe.dim_reduction.config.PHATEConfig coco_pipe.dim_reduction.config.IsomapConfig coco_pipe.dim_reduction.config.LLEConfig coco_pipe.dim_reduction.config.MDSConfig coco_pipe.dim_reduction.config.SpectralEmbeddingConfig coco_pipe.dim_reduction.config.DMDConfig coco_pipe.dim_reduction.config.TRCAConfig coco_pipe.dim_reduction.config.TopologicalAEConfig coco_pipe.dim_reduction.config.IVISConfig coco_pipe.dim_reduction.config.ParametricUMAPConfig coco_pipe.dim_reduction.config.EvaluationConfig Functions --------- .. autoapisummary:: coco_pipe.dim_reduction.config.get_reducer_class Module Contents --------------- .. py:data:: METHODS :value: ('PCA', 'IncrementalPCA', 'DaskPCA', 'DaskTruncatedSVD', 'Isomap', 'LLE', 'MDS',... .. py:function:: get_reducer_class(method: str) Return the reducer class registered for one canonical method name. :param method: Canonical public name of the reduction method. :type method: str :returns: The reducer class (subclass of BaseReducer). :rtype: class :raises ValueError: If ``method`` is not one of the canonical names in ``METHODS``. :raises ImportError: If the reducer backend cannot be imported. .. rubric:: Notes Registry lookup is exact and case-sensitive. The dim-reduction module does not support aliasing or case normalization. .. seealso:: :obj:`METHODS` Canonical public method names accepted by the registry. :obj:`BaseReducerConfig` Base type for typed reducer configuration objects. .. rubric:: Examples >>> cls = get_reducer_class("PCA") >>> cls.__name__ 'PCAReducer' .. py:class:: BaseReducerConfig(/, **data: Any) Bases: :py:obj:`_StrictConfigModel` Base configuration shared by all reducer configs. .. rubric:: Notes All reducer configs are strict. Unknown fields are rejected at parse time. Subclasses must expose a canonical ``method`` literal and may override ``to_reducer_kwargs()`` when the reducer constructor needs renamed fields. .. seealso:: :obj:`get_reducer_class` Registry lookup for canonical method names. :obj:`EvaluationConfig` Post-hoc scoring and ranking configuration. .. py:attribute:: n_components :type: int :value: None .. py:method:: to_reducer_kwargs() -> dict[str, Any] Return reducer keyword arguments for this config. .. py:class:: StochasticReducerConfig(/, **data: Any) Bases: :py:obj:`_StrictConfigModel` Mixin for reducers that expose a random seed. .. py:attribute:: random_state :type: Optional[int] :value: None .. py:class:: PCAConfig(/, **data: Any) Bases: :py:obj:`BaseReducerConfig`, :py:obj:`StochasticReducerConfig` Configuration for PCA. .. py:attribute:: method :type: Literal['PCA'] :value: 'PCA' .. py:attribute:: whiten :type: bool :value: None .. py:attribute:: svd_solver :type: str :value: None .. py:class:: IncrementalPCAConfig(/, **data: Any) Bases: :py:obj:`BaseReducerConfig` Configuration for Incremental PCA. .. py:attribute:: method :type: Literal['IncrementalPCA'] :value: 'IncrementalPCA' .. py:attribute:: batch_size :type: Optional[int] :value: None .. py:attribute:: whiten :type: bool :value: None .. py:class:: DaskPCAConfig(/, **data: Any) Bases: :py:obj:`BaseReducerConfig`, :py:obj:`StochasticReducerConfig` Configuration for Dask PCA. .. py:attribute:: method :type: Literal['DaskPCA'] :value: 'DaskPCA' .. py:attribute:: svd_solver :type: str :value: None .. py:class:: DaskTruncatedSVDConfig(/, **data: Any) Bases: :py:obj:`BaseReducerConfig`, :py:obj:`StochasticReducerConfig` Configuration for Dask TruncatedSVD. .. py:attribute:: method :type: Literal['DaskTruncatedSVD'] :value: 'DaskTruncatedSVD' .. py:attribute:: algorithm :type: str :value: None .. py:class:: UMAPConfig(/, **data: Any) Bases: :py:obj:`BaseReducerConfig`, :py:obj:`StochasticReducerConfig` Configuration for UMAP. .. py:attribute:: method :type: Literal['UMAP'] :value: 'UMAP' .. py:attribute:: n_neighbors :type: int :value: None .. py:attribute:: min_dist :type: float :value: None .. py:attribute:: metric :type: str :value: None .. py:attribute:: n_epochs :type: Optional[int] :value: None .. py:attribute:: spread :type: float :value: None .. py:attribute:: set_op_mix_ratio :type: float :value: None .. py:class:: TSNEConfig(/, **data: Any) Bases: :py:obj:`BaseReducerConfig`, :py:obj:`StochasticReducerConfig` Configuration for TSNE. .. py:attribute:: method :type: Literal['TSNE'] :value: 'TSNE' .. py:attribute:: perplexity :type: float :value: None .. py:attribute:: early_exaggeration :type: float :value: None .. py:attribute:: learning_rate :type: float | str :value: None .. py:attribute:: max_iter :type: int :value: None .. py:attribute:: init :type: str :value: None .. py:class:: PacmapConfig(/, **data: Any) Bases: :py:obj:`BaseReducerConfig`, :py:obj:`StochasticReducerConfig` Configuration for Pacmap. .. py:attribute:: method :type: Literal['Pacmap'] :value: 'Pacmap' .. py:attribute:: n_neighbors :type: int :value: None .. py:attribute:: MN_ratio :type: float :value: None .. py:attribute:: FP_ratio :type: float :value: None .. py:attribute:: nn_backend :type: str :value: None .. py:attribute:: init :type: str :value: None .. py:class:: TrimapConfig(/, **data: Any) Bases: :py:obj:`BaseReducerConfig`, :py:obj:`StochasticReducerConfig` Configuration for Trimap. .. py:attribute:: method :type: Literal['Trimap'] :value: 'Trimap' .. py:attribute:: n_inliers :type: int :value: None .. py:attribute:: n_outliers :type: int :value: None .. py:attribute:: n_random :type: int :value: None .. py:class:: PHATEConfig(/, **data: Any) Bases: :py:obj:`BaseReducerConfig`, :py:obj:`StochasticReducerConfig` Configuration for PHATE. .. py:attribute:: method :type: Literal['PHATE'] :value: 'PHATE' .. py:attribute:: knn :type: int :value: None .. py:attribute:: decay :type: int :value: None .. py:attribute:: t :type: int | str :value: None .. py:class:: IsomapConfig(/, **data: Any) Bases: :py:obj:`BaseReducerConfig` Configuration for Isomap. .. py:attribute:: method :type: Literal['Isomap'] :value: 'Isomap' .. py:attribute:: n_neighbors :type: int :value: None .. py:attribute:: metric :type: str :value: None .. py:attribute:: p :type: int :value: None .. py:class:: LLEConfig(/, **data: Any) Bases: :py:obj:`BaseReducerConfig`, :py:obj:`StochasticReducerConfig` Configuration for LLE. .. py:attribute:: method :type: Literal['LLE'] :value: 'LLE' .. py:attribute:: n_neighbors :type: int :value: None .. py:attribute:: lle_method :type: str :value: None .. py:method:: to_reducer_kwargs() -> dict[str, Any] Return reducer keyword arguments with sklearn-compatible names. .. py:class:: MDSConfig(/, **data: Any) Bases: :py:obj:`BaseReducerConfig`, :py:obj:`StochasticReducerConfig` Configuration for MDS. .. py:attribute:: method :type: Literal['MDS'] :value: 'MDS' .. py:attribute:: metric :type: bool :value: None .. py:attribute:: n_init :type: int :value: None .. py:attribute:: max_iter :type: int :value: None .. py:attribute:: dissimilarity :type: str :value: None .. py:class:: SpectralEmbeddingConfig(/, **data: Any) Bases: :py:obj:`BaseReducerConfig`, :py:obj:`StochasticReducerConfig` Configuration for Spectral Embedding. .. py:attribute:: method :type: Literal['SpectralEmbedding'] :value: 'SpectralEmbedding' .. py:attribute:: affinity :type: str :value: None .. py:attribute:: gamma :type: Optional[float] :value: None .. py:class:: DMDConfig(/, **data: Any) Bases: :py:obj:`BaseReducerConfig` Configuration for DMD. .. py:attribute:: method :type: Literal['DMD'] :value: 'DMD' .. py:attribute:: force_transpose :type: bool :value: None .. py:attribute:: tlsq_rank :type: int :value: None .. py:attribute:: exact :type: bool :value: None .. py:attribute:: opt :type: bool :value: None .. py:class:: TRCAConfig(/, **data: Any) Bases: :py:obj:`BaseReducerConfig` Configuration for TRCA. .. py:attribute:: method :type: Literal['TRCA'] :value: 'TRCA' .. py:attribute:: sfreq :type: float :value: None .. py:attribute:: filterbank :type: Optional[list] :value: None .. py:class:: TopologicalAEConfig(/, **data: Any) Bases: :py:obj:`BaseReducerConfig`, :py:obj:`StochasticReducerConfig` Configuration for Topological Autoencoder. .. py:attribute:: method :type: Literal['TopologicalAE'] :value: 'TopologicalAE' .. py:attribute:: hidden_dims :type: list[int] :value: None .. py:attribute:: lam :type: float :value: None .. py:attribute:: lr :type: float :value: None .. py:attribute:: batch_size :type: int :value: None .. py:attribute:: epochs :type: int :value: None .. py:attribute:: device :type: str :value: None .. py:attribute:: verbose :type: int :value: None .. py:class:: IVISConfig(/, **data: Any) Bases: :py:obj:`BaseReducerConfig`, :py:obj:`StochasticReducerConfig` Configuration for IVIS. .. py:attribute:: method :type: Literal['IVIS'] :value: 'IVIS' .. py:attribute:: k :type: int :value: None .. py:attribute:: model :type: str :value: None .. py:attribute:: n_epochs_without_progress :type: int :value: None .. py:attribute:: supervise_metric :type: str :value: None .. py:class:: ParametricUMAPConfig(/, **data: Any) Bases: :py:obj:`BaseReducerConfig`, :py:obj:`StochasticReducerConfig` Configuration for Parametric UMAP. .. py:attribute:: method :type: Literal['ParametricUMAP'] :value: 'ParametricUMAP' .. py:attribute:: n_neighbors :type: int :value: None .. py:attribute:: min_dist :type: float :value: None .. py:attribute:: metric :type: str :value: None .. py:attribute:: n_epochs :type: Optional[int] :value: None .. py:attribute:: batch_size :type: int :value: None .. py:attribute:: verbose :type: bool :value: None .. py:class:: EvaluationConfig(/, **data: Any) Bases: :py:obj:`_StrictConfigModel` Configuration for post-hoc evaluation and method comparison. :param metrics: Metric families to compute. Must use canonical evaluator metric names. :type metrics: list of str, optional :param k_range: Neighborhood sizes used for standard structure-preservation metrics. :type k_range: list of int, optional :param selection_metric: Primary ranking metric. Must be one of the supported ranking metrics and also appear in ``metrics``. :type selection_metric: str, optional :param selection_k: Neighborhood size used when ranking a k-scoped metric. :type selection_k: int, optional :param tie_breakers: Additional ranking metrics applied in order. Each value must also be present in ``metrics``. :type tie_breakers: list of str, optional :param separation_method: Separation definition used for trajectory separation scoring. :type separation_method: str, default="centroid" .. rubric:: Notes ``EvaluationConfig`` validates semantic consistency at parse time. Invalid metric names, duplicate entries, invalid separation methods, and ranking metrics that are not part of ``metrics`` all fail early. .. seealso:: :obj:`coco_pipe.dim_reduction.evaluation.core.evaluate_embedding` Pure evaluator that consumes these settings. :obj:`coco_pipe.dim_reduction.evaluation.core.MethodSelector` Post-hoc collector and ranker for scored reducers. .. rubric:: Examples >>> config = EvaluationConfig( ... metrics=["trustworthiness", "continuity"], ... k_range=[5, 10], ... selection_metric="trustworthiness", ... selection_k=10, ... tie_breakers=["continuity"], ... ) >>> config.selection_metric 'trustworthiness' .. py:attribute:: metrics :type: list[str] :value: None .. py:attribute:: k_range :type: list[int] :value: None .. py:attribute:: selection_metric :type: Optional[str] :value: None .. py:attribute:: selection_k :type: Optional[int] :value: None .. py:attribute:: tie_breakers :type: list[str] :value: None .. py:attribute:: separation_method :type: str :value: None .. py:method:: _validate_metrics(value: list[str]) -> list[str] :classmethod: .. py:method:: _validate_k_range(value: list[int]) -> list[int] :classmethod: .. py:method:: _validate_selection_metric(value: Optional[str]) -> Optional[str] :classmethod: .. py:method:: _validate_selection_k(value: Optional[int]) -> Optional[int] :classmethod: .. py:method:: _validate_tie_breakers(value: list[str]) -> list[str] :classmethod: .. py:method:: _validate_separation_method(value: str) -> str :classmethod: .. py:method:: _validate_metric_dependencies() -> EvaluationConfig