coco-pipe

A modular framework for biosignal analytics, machine learning, deep learning, and foundation-model workflows.

coco-pipe was originally developed for M/EEG research and provides reusable components for data loading, feature extraction, dimensionality reduction, decoding, visualization, and automated reporting. The framework is designed to support reproducible machine-learning and foundation-model workflows across neuroimaging and biosignal modalities, with planned support for fMRI, fNIRS, and related data types.

---

Highlights

• Biosignal-first design for M/EEG, tabular, and biomedical datasets.
• Modular architecture for building reusable analysis pipelines.
• Machine-learning workflows for classification, regression, feature selection, and hyperparameter optimization.
• Foundation-model workflows for embedding extraction, linear probing, full fine-tuning, parameter-efficient fine-tuning (LoRA/PEFT), and downstream decoding.
• Dimensionality-reduction tools for exploratory analysis, embedding comparison, visualization, clustering, and trajectory analysis.
• Automated reporting for reproducible experiment summaries and analysis outputs.

---

Built On

coco-pipe integrates with many widely used scientific Python libraries, including:

• MNE-Python
• Braindecode
• MOABB
• scikit-learn
• PyTorch
• Hugging Face Transformers
• PEFT
• UMAP
• PHATE
• PaCMAP
• Dask

---

Installation

With pip

pip install coco-pipe

Optional modules come as extras, for example pip install "coco-pipe[full]" for all of them.

From source

git clone https://github.com/BabaSanfour/coco-pipe.git
cd coco-pipe
pip install -e .

Development installation:

pip install -e .[dev,test]

Full installation (all optional modules):

pip install -e .[full,test]

With uv

git clone https://github.com/BabaSanfour/coco-pipe.git
cd coco-pipe

uv venv
source .venv/bin/activate

uv pip install -e .

Development installation:

uv pip install -e ".[dev,test]"

Full installation:

uv pip install -e ".[full,test]"

Saved epochs and mne-bids

BIDSDataset reads saved epochs (*_epo.fif) with mne_bids.read_epochs_bids, which reads FIF epochs only with mne-bids PR #1679. It is not merged yet, so neither a release nor mne-bids main has it; install the PR:

pip install "mne-bids @ git+https://github.com/mne-tools/mne-bids.git@refs/pull/1679/head"

With mne-bids 0.20, loading saved epochs fails and the tests that need it are skipped. CI runs them in a separate job with the PR installed.

---

Modules

Module	Role
io	Dataset loading, validation, and organization.
descriptors	Signal feature extraction and representation building.
dim_reduction	Representation learning and dimensionality reduction.
decoding	Classification, regression, and model evaluation workflows.
viz	Exploratory analysis and publication-quality visualizations.
report	Automated experiment summaries and reporting.

---

Quick Start

The decoding API centers around the Experiment class:

from coco_pipe.decoding import Experiment, ExperimentConfig
from coco_pipe.decoding.configs import (
    CVConfig,
    LogisticRegressionConfig,
)

config = ExperimentConfig(
    task="classification",
    models={
        "logreg": LogisticRegressionConfig(max_iter=500)
    },
    metrics=["accuracy"],
    cv=CVConfig(
        strategy="stratified",
        n_splits=5,
        shuffle=True,
        random_state=42,
    ),
)

result = Experiment(config).run(X, y)

print(result.summary())

More advanced workflows, including feature selection, temporal decoding, dimensionality reduction, foundation-model integration, and automated reporting, are covered in the documentation.

---

Documentation

Documentation, tutorials, examples, and API references are available at:

https://babasanfour.github.io/coco-pipe/

---

Contributing

Contributions are welcome, including:

• Bug reports
• Documentation improvements
• Examples and tutorials
• New analysis modules
• Tests and infrastructure improvements
• Performance optimizations

Please read CONTRIBUTING.md before opening a pull request.

---

Citation

If you use coco-pipe in academic work, please cite the associated publication(s) when available.

Citation information will be added here as the project matures.

---

License

coco-pipe is distributed under the terms of the MIT License.