coco_pipe.decoding.experiment
=============================

.. py:module:: coco_pipe.decoding.experiment

.. autoapi-nested-parse::

   Decoding Experiment
   ===================
   Main executor for decoding experiments.



Attributes
----------

.. autoapisummary::

   coco_pipe.decoding.experiment.logger


Classes
-------

.. autoapisummary::

   coco_pipe.decoding.experiment.Experiment


Module Contents
---------------

.. py:data:: logger

.. py:class:: Experiment(config)

   Main executor for decoding experiments.

   :param config: The complete configuration for the experiment.
   :type config: ExperimentConfig

   .. rubric:: Examples

   >>> from coco_pipe.decoding import Experiment, ExperimentConfig
   >>> config = ExperimentConfig(
   ...     task="classification", models={"lr": {"kind": "classical"}}
   ... )
   >>> exp = Experiment(config)

   .. seealso::

      :py:obj:`ExperimentResult`
          Container for experiment outputs.

      :py:obj:`get_cv_splitter`
          Factory for cross-validation splitters.


   .. py:attribute:: config


   .. py:attribute:: results
      :type:  dict[str, Any]


   .. py:attribute:: result_
      :type:  coco_pipe.decoding.result.ExperimentResult | None
      :value: None



   .. py:method:: run(X, y, groups = None, feature_names = None, sample_ids = None, sample_metadata = None, observation_level = 'sample', inferential_unit = None, time_axis = None, sample_weight = None)

      Execute the complete decoding experiment pipeline.

      This method orchestrates the full scientific workflow:
      1. Resolves and validates data hierarchy (metadata, groups, sample IDs).
      2. Aligns temporal dimensions and feature names.
      3. Performs model-by-model evaluation using stratified/grouped cross-validation.
      4. Aggregates results into a unified ExperimentResult object.
      5. Performs statistical assessment (permutations/bootstrapping) if enabled.

      :param X: The input data. Can be 2D (samples x features) or 3D temporal
                (samples x sensors x time).
      :type X: np.ndarray
      :param y: The target labels or values.
      :type y: Union[pd.Series, np.ndarray]
      :param groups: Grouping labels for grouped cross-validation (e.g., subject IDs).
      :type groups: Union[pd.Series, np.ndarray], optional
      :param feature_names: Human-readable names for features. Auto-generated if None.
      :type feature_names: Sequence[str], optional
      :param sample_ids: Unique identifiers for each sample. Auto-generated if None.
      :type sample_ids: Sequence[Any], optional
      :param sample_metadata: Additional scientific context for each sample (BIDS-like).
      :type sample_metadata: Union[pd.DataFrame, Dict], optional
      :param observation_level: Level of the input rows ('sample' or 'epoch').
      :type observation_level: str, default='sample'
      :param inferential_unit: The level of statistical independence ('sample' or 'subject').
      :type inferential_unit: str, optional
      :param time_axis: Scientific time points for 3D temporal data.
      :type time_axis: Sequence[Any], optional

      :returns: A container holding all raw results, metrics, and diagnostics.
      :rtype: ExperimentResult

      :raises ValueError: If input lengths mismatch, data is empty, or configuration
          is scientifically invalid (e.g. regression with stratification).

      .. rubric:: Examples

      >>> from coco_pipe.decoding import Experiment, ExperimentConfig
      >>> config = ExperimentConfig(
      ...     task="classification", models={"lr": {"kind": "classical"}}
      ... )
      >>> result = Experiment(config).run(X, y)

      .. seealso::

         :py:obj:`ExperimentResult.get_predictions`
             Tidy prediction accessor.