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 coco_pipe.dim_reduction.config.DEFAULT_EVAL_GROUP_COL coco_pipe.dim_reduction.config.MISSING_EVAL_VALUES 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 coco_pipe.dim_reduction.config.parse_eval_specs Module Contents --------------- .. py:data:: METHODS :value: ('PCA', 'IncrementalPCA', 'DaskPCA', 'DaskTruncatedSVD', 'Isomap', 'LLE', 'MDS',... .. py:function:: get_reducer_class(method) 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:: :py:obj:`METHODS` Canonical public method names accepted by the registry. :py:obj:`BaseReducerConfig` Base type for typed reducer configuration objects. .. rubric:: Examples >>> cls = get_reducer_class("PCA") >>> cls.__name__ 'PCAReducer' .. py:class:: BaseReducerConfig(/, **data) 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:: :py:obj:`get_reducer_class` Registry lookup for canonical method names. :py:obj:`EvaluationConfig` Post-hoc scoring and ranking configuration. .. py:attribute:: n_components :type: int :value: None .. py:method:: to_reducer_kwargs() Return reducer keyword arguments for this config. .. py:class:: StochasticReducerConfig(/, **data) Bases: :py:obj:`_StrictConfigModel` Mixin for reducers that expose a random seed. .. py:attribute:: random_state :type: int | None :value: None .. py:class:: PCAConfig(/, **data) 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) Bases: :py:obj:`BaseReducerConfig` Configuration for Incremental PCA. .. py:attribute:: method :type: Literal['IncrementalPCA'] :value: 'IncrementalPCA' .. py:attribute:: batch_size :type: int | None :value: None .. py:attribute:: whiten :type: bool :value: None .. py:class:: DaskPCAConfig(/, **data) 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) 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) 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: int | None :value: None .. py:attribute:: spread :type: float :value: None .. py:attribute:: set_op_mix_ratio :type: float :value: None .. py:class:: TSNEConfig(/, **data) 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) 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) 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) 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) 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) 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() Return reducer keyword arguments with sklearn-compatible names. .. py:class:: MDSConfig(/, **data) 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) 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: float | None :value: None .. py:class:: DMDConfig(/, **data) 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) 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: list | None :value: None .. py:class:: TopologicalAEConfig(/, **data) 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) 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) 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: int | None :value: None .. py:attribute:: batch_size :type: int :value: None .. py:attribute:: verbose :type: bool :value: None .. py:class:: EvaluationConfig(/, **data) 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:: :py:obj:`coco_pipe.dim_reduction.evaluation.core.evaluate_embedding` Pure evaluator that consumes these settings. :py: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: str | None :value: None .. py:attribute:: selection_k :type: int | None :value: None .. py:attribute:: tie_breakers :type: list[str] :value: None .. py:attribute:: separation_method :type: str :value: None .. py:method:: to_score_kwargs() Return scoring keyword arguments for ``evaluate_embedding``. Maps the config's evaluation fields onto the keyword arguments consumed by :func:`coco_pipe.dim_reduction.evaluation.core.evaluate_embedding` (and :meth:`coco_pipe.dim_reduction.core.DimReduction.score`). Ranking fields (``selection_metric``, ``selection_k``, ``tie_breakers``) are not included here — they drive :meth:`coco_pipe.dim_reduction.evaluation.core.MethodSelector.rank_methods`. :returns: Mapping with ``metrics``, ``k_values``, and ``separation_method``. :rtype: dict .. py:data:: DEFAULT_EVAL_GROUP_COL :type: str :value: 'patient_group_id' Default grouping column used when building post-hoc eval specs. .. py:data:: MISSING_EVAL_VALUES :type: frozenset[str] Label/group values that are treated as missing during eval alignment. .. py:function:: parse_eval_specs(raw_specs, subject_col) Parse raw eval spec input into a validated list of spec dicts. *raw_specs* may be: - ``None`` — returns an empty list - a ``list`` of spec dicts - a ``dict`` with an ``"evals"`` key whose value is the list Each spec dict must have at least ``"name"`` and ``"target_col"`` keys. Optional keys: ``"group_col"`` (defaults to :data:`DEFAULT_EVAL_GROUP_COL`), ``"filters"`` (list of ``{column, values}`` dicts), ``"label_map"`` (string→string mapping). :param raw_specs: Raw YAML/JSON eval spec input. :param subject_col: Subject identifier column name (reserved for future alignment checks). :returns: Normalised eval spec dicts, ready for use in :func:`coco_pipe.dim_reduction.pipeline.run_eval`. :rtype: list of dict :raises ValueError: On structural violations (wrong type, missing required keys, …).