Metadata-Version: 2.4
Name: coco-pipe
Version: 0.0.1
Summary: A modular framework for scalable biosignal analysis with Machine Learning and Deep Learning
Author-email: Hamza Abdelhedi <hamza.abdelhedii@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/BabaSanfour/coco-pipe
Project-URL: Documentation, https://babasanfour.github.io/coco-pipe/
Project-URL: Repository, https://github.com/BabaSanfour/coco-pipe.git
Project-URL: Issues, https://github.com/BabaSanfour/coco-pipe/issues
Project-URL: Changelog, https://github.com/BabaSanfour/coco-pipe/blob/main/CHANGELOG.md
Keywords: EEG,machine learning,deep learning,neuroscience,bio-data
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.0.0
Requires-Dist: pandas
Requires-Dist: scikit-learn>=1.6
Requires-Dist: matplotlib<3.13
Requires-Dist: seaborn
Requires-Dist: scipy>=1.11.0
Requires-Dist: xarray
Requires-Dist: pyriemann>=0.7
Requires-Dist: pyyaml
Requires-Dist: pydantic
Requires-Dist: hydra-core
Requires-Dist: requests
Requires-Dist: openpyxl
Requires-Dist: joblib
Requires-Dist: plotly
Requires-Dist: markdown
Requires-Dist: mne>=1.13
Requires-Dist: mne-bids>=0.20
Requires-Dist: filelock>=3.20.4
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: beautifulsoup4; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: insegel; extra == "docs"
Requires-Dist: pydata-sphinx-theme; extra == "docs"
Requires-Dist: sphinx-design; extra == "docs"
Requires-Dist: sphinx-gallery; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: sphinxcontrib-mermaid; extra == "docs"
Requires-Dist: sphinx-autoapi; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: towncrier; extra == "docs"
Provides-Extra: dev
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: beautifulsoup4; extra == "dev"
Requires-Dist: towncrier; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: release
Requires-Dist: build; extra == "release"
Requires-Dist: twine; extra == "release"
Requires-Dist: towncrier; extra == "release"
Provides-Extra: dask
Requires-Dist: dask[array]; extra == "dask"
Requires-Dist: dask-ml; extra == "dask"
Provides-Extra: neighbor
Requires-Dist: umap-learn[plot]; extra == "neighbor"
Requires-Dist: trimap>=1.2; extra == "neighbor"
Requires-Dist: phate; extra == "neighbor"
Requires-Dist: pacmap; extra == "neighbor"
Requires-Dist: faiss-cpu; extra == "neighbor"
Provides-Extra: parametric-umap
Requires-Dist: umap-learn[plot]; extra == "parametric-umap"
Requires-Dist: tensorflow; extra == "parametric-umap"
Requires-Dist: keras; extra == "parametric-umap"
Provides-Extra: topology
Requires-Dist: torch; extra == "topology"
Requires-Dist: skorch; extra == "topology"
Requires-Dist: gudhi; extra == "topology"
Provides-Extra: torch
Requires-Dist: torch; extra == "torch"
Provides-Extra: braindecode
Requires-Dist: braindecode>=1.8.1; extra == "braindecode"
Provides-Extra: hf
Requires-Dist: transformers; extra == "hf"
Requires-Dist: huggingface-hub; extra == "hf"
Provides-Extra: peft
Requires-Dist: peft; extra == "peft"
Requires-Dist: accelerate; extra == "peft"
Provides-Extra: foundation
Requires-Dist: torch; extra == "foundation"
Requires-Dist: skorch; extra == "foundation"
Requires-Dist: braindecode>=1.8.1; extra == "foundation"
Requires-Dist: transformers; extra == "foundation"
Requires-Dist: huggingface-hub; extra == "foundation"
Requires-Dist: peft; extra == "foundation"
Requires-Dist: accelerate; extra == "foundation"
Provides-Extra: decoding
Requires-Dist: skorch; extra == "decoding"
Provides-Extra: quant
Requires-Dist: bitsandbytes; extra == "quant"
Provides-Extra: moabb
Requires-Dist: moabb; extra == "moabb"
Requires-Dist: mne; extra == "moabb"
Provides-Extra: torcheeg
Requires-Dist: torcheeg; extra == "torcheeg"
Provides-Extra: dev-gpu
Requires-Dist: pytest>=8.0; extra == "dev-gpu"
Requires-Dist: torch; extra == "dev-gpu"
Requires-Dist: accelerate; extra == "dev-gpu"
Provides-Extra: spatiotemporal
Requires-Dist: pydmd; extra == "spatiotemporal"
Requires-Dist: meegkit; extra == "spatiotemporal"
Provides-Extra: eeg
Requires-Dist: meegkit; extra == "eeg"
Provides-Extra: descriptors
Requires-Dist: specparam; extra == "descriptors"
Requires-Dist: antropy; extra == "descriptors"
Requires-Dist: neurokit2; extra == "descriptors"
Provides-Extra: dim-red
Requires-Dist: dask[array]; extra == "dim-red"
Requires-Dist: dask-ml; extra == "dim-red"
Requires-Dist: umap-learn[plot]; extra == "dim-red"
Requires-Dist: trimap>=1.2; extra == "dim-red"
Requires-Dist: phate; extra == "dim-red"
Requires-Dist: pacmap; extra == "dim-red"
Requires-Dist: faiss-cpu; extra == "dim-red"
Requires-Dist: tensorflow; extra == "dim-red"
Requires-Dist: keras; extra == "dim-red"
Requires-Dist: torch; extra == "dim-red"
Requires-Dist: skorch; extra == "dim-red"
Requires-Dist: gudhi; extra == "dim-red"
Requires-Dist: pydmd; extra == "dim-red"
Requires-Dist: meegkit; extra == "dim-red"
Provides-Extra: full
Requires-Dist: dask[array]; extra == "full"
Requires-Dist: dask-ml; extra == "full"
Requires-Dist: umap-learn[plot]; extra == "full"
Requires-Dist: trimap>=1.2; extra == "full"
Requires-Dist: phate; extra == "full"
Requires-Dist: pacmap; extra == "full"
Requires-Dist: faiss-cpu; extra == "full"
Requires-Dist: tensorflow; extra == "full"
Requires-Dist: keras; extra == "full"
Requires-Dist: torch; extra == "full"
Requires-Dist: skorch; extra == "full"
Requires-Dist: gudhi; extra == "full"
Requires-Dist: pydmd; extra == "full"
Requires-Dist: meegkit; extra == "full"
Requires-Dist: specparam; extra == "full"
Requires-Dist: antropy; extra == "full"
Requires-Dist: neurokit2; extra == "full"
Requires-Dist: braindecode>=1.8.1; extra == "full"
Requires-Dist: transformers; extra == "full"
Requires-Dist: huggingface-hub; extra == "full"
Requires-Dist: peft; extra == "full"
Requires-Dist: accelerate; extra == "full"
Provides-Extra: all
Requires-Dist: coco-pipe[dask,descriptors,dim-red,docs,eeg,foundation,moabb,neighbor,parametric-umap,spatiotemporal,test,topology,torcheeg]; extra == "all"
Dynamic: license-file

# coco-pipe

[![CI](https://img.shields.io/github/actions/workflow/status/BabaSanfour/coco-pipe/ci.yml?branch=main\&label=CI)](https://github.com/BabaSanfour/coco-pipe/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/github/actions/workflow/status/BabaSanfour/coco-pipe/docs.yml?branch=main\&label=docs)](https://babasanfour.github.io/coco-pipe/)
[![Codecov](https://img.shields.io/codecov/c/github/BabaSanfour/coco-pipe)](https://codecov.io/gh/BabaSanfour/coco-pipe)
[![PyPI - Version](https://img.shields.io/pypi/v/coco-pipe.svg)](https://pypi.org/project/coco-pipe/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**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

```bash
pip install coco-pipe
```

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

### From source

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

Development installation:

```bash
pip install -e .[dev,test]
```

Full installation (all optional modules):

```bash
pip install -e .[full,test]
```

### With uv

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

uv venv
source .venv/bin/activate

uv pip install -e .
```

Development installation:

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

Full installation:

```bash
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 from mne-bids PR #1679 on. Until that is in a release,
install mne-bids from GitHub:

```bash
pip install "mne-bids @ git+https://github.com/mne-tools/mne-bids.git@main"
```

With mne-bids 0.20, loading saved epochs fails and the tests that need it are
skipped.

---

## 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:

```python
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](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.
