coco_pipe.decoding.Experiment#

class coco_pipe.decoding.Experiment(config)#

Bases: object

Main executor for decoding experiments.

Parameters:

config (ExperimentConfig) – The complete configuration for the experiment.

Examples

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

See also

ExperimentResult

Container for experiment outputs.

get_cv_splitter

Factory for cross-validation splitters.

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.

Parameters:

  • X (np.ndarray) – The input data. Can be 2D (samples x features) or 3D temporal (samples x sensors x time).

  • y (Union[pd.Series, np.ndarray]) – The target labels or values.

  • groups (Union[pd.Series, np.ndarray], optional) – Grouping labels for grouped cross-validation (e.g., subject IDs).

  • feature_names (Sequence[str], optional) – Human-readable names for features. Auto-generated if None.

  • sample_ids (Sequence[Any], optional) – Unique identifiers for each sample. Auto-generated if None.

  • sample_metadata (Union[pd.DataFrame, Dict], optional) – Additional scientific context for each sample (BIDS-like).

  • observation_level (str, default='sample') – Level of the input rows (‘sample’ or ‘epoch’).

  • inferential_unit (str, optional) – The level of statistical independence (‘sample’ or ‘subject’).

  • time_axis (Sequence[Any], optional) – Scientific time points for 3D temporal data.

  • sample_weight (np.ndarray | None)

Returns:

A container holding all raw results, metrics, and diagnostics.

Return type:

ExperimentResult

Raises:

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

Examples

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

See also

ExperimentResult.get_predictions

Tidy prediction accessor.

Examples using coco_pipe.decoding.Experiment#

Basic Decoding: Classification and Model Verification

Basic Decoding: Classification and Model Verification