Metadata-Version: 2.4
Name: facetpy
Version: 2.0.0
Summary: A flexible artifact correction and evaluation toolbox to correct eeg data
License: GPL-3.0-only
Keywords: eeg,fmri,artifact-correction,mne,neuroscience
Author: Janik Michael Mueller
Author-email: janik.michael.mueller@gmail.com
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Provides-Extra: all
Provides-Extra: deeplearning
Provides-Extra: docs
Provides-Extra: gui
Provides-Extra: notebooks
Requires-Dist: defusedxml (>=0.7.1,<0.8.0)
Requires-Dist: edfio (>=0.4.11,<0.5.0)
Requires-Dist: eeglabio (>=0.1.3,<0.2.0)
Requires-Dist: ipython (>=7.23.1,<9) ; extra == "notebooks"
Requires-Dist: loguru (==0.7.2)
Requires-Dist: matplotlib (>=3.10.3,<4.0.0)
Requires-Dist: mne (==1.10.2)
Requires-Dist: mne-bids (==0.17)
Requires-Dist: myst-parser (>=3.0.1,<4.0.0) ; extra == "docs" or extra == "all"
Requires-Dist: neurokit2 (>=0.2.7,<0.3.0)
Requires-Dist: notebook (>=7.1.2,<8.0.0) ; extra == "notebooks" or extra == "all"
Requires-Dist: numpy (==2.1.3)
Requires-Dist: pandas (>=2.2.3,<3.0.0)
Requires-Dist: pyqt6 (>=6.6.1,<7.0.0) ; extra == "gui" or extra == "all"
Requires-Dist: rich (>=14.2.0,<15.0.0)
Requires-Dist: scikit-learn (>=1.4.2,<2.0.0)
Requires-Dist: scipy (>=1.15.3,<2.0.0)
Requires-Dist: sphinx (>=7.2.6,<8.0.0) ; extra == "docs" or extra == "all"
Requires-Dist: sphinx-rtd-theme (>=2.0.0,<3.0.0) ; extra == "docs" or extra == "all"
Requires-Dist: tensorflow (>=2.19.0,<3.0.0) ; extra == "deeplearning" or extra == "all"
Project-URL: Documentation, https://facetpy.readthedocs.io/
Project-URL: Homepage, https://github.com/H0mire/facetpy
Project-URL: Repository, https://github.com/H0mire/facetpy
Description-Content-Type: text/markdown

# FACETpy — fMRI Artifact Correction and Evaluation Toolbox

<p align="center">
  <picture>
    <source srcset="docs/source/_static/logo_dark_theme.png" media="(prefers-color-scheme: dark)">
    <img src="docs/source/_static/logo_light_theme.png" width="300" alt="FACETpy logo" />
  </picture>
</p>

[![Documentation Status](https://readthedocs.org/projects/facetpy/badge/?version=latest)](https://facetpy.readthedocs.io/en/latest/?badge=latest)

A Python toolbox for correcting fMRI-induced EEG artifacts using Averaged
Artifact Subtraction (AAS) and other advanced methods.  Built on
[MNE-Python](https://mne.tools), it provides a modular pipeline
architecture that lets researchers process, evaluate, and compare correction
results with minimal code.

**Key features**

- Load EEG from EDF, GDF, and BIDS formats
- Artifact correction: AAS, PCA, Adaptive Noise Cancellation (ANC)
- Full evaluation suite: SNR, RMS, Median Artifact, FFT-based metrics
- One-call results: `result.print_metrics()`, `result.print_summary()`
- Batch processing across subjects/sessions with `Pipeline.map()`
- Generate synthetic EEG for algorithm testing
- Rich progress display in the terminal


## Quick start

Quick installation (requires Python 3.11/3.12/3.13):

Unix (macOS/Linux):

```bash
curl -fsSL https://raw.githubusercontent.com/H0mire/facetpy/main/scripts/bootstrap.sh | sh
cd facetpy
```

Windows (PowerShell):

```powershell
git clone https://github.com/H0mire/facetpy.git
Set-Location facetpy
poetry install --no-interaction
```
<p align="center">
  <img src="docs/source/_static/run_example.png" alt="FACETpy example run" width="700" />
</p>


```python
from facet import (
    Pipeline, Loader, EDFExporter,
    TriggerDetector, UpSample, DownSample, AASCorrection,
)

pipeline = Pipeline([
    Loader(path="data.edf", preload=True),
    TriggerDetector(regex=r"\b1\b"),
    UpSample(factor=10),
    AASCorrection(window_size=30),
    DownSample(factor=10),
    EDFExporter(path="corrected.edf", overwrite=True),
], name="Quickstart")

result = pipeline.run()
result.print_summary()   # Done in 4.2s  snr=18.3  rms_ratio=0.14
```


## Installation

Requires **Python 3.11, 3.12, or 3.13** and [Poetry](https://python-poetry.org) >= 1.8.
Conda is optional, not required.

### Option A (PyPI): install from package index

```bash
pip install facetpy
```

The package name on PyPI is `facetpy`; import it in Python as `facet`.

### Option B (Unix recommended): bootstrap script
```bash
curl -fsSL https://raw.githubusercontent.com/H0mire/facetpy/main/scripts/bootstrap.sh | sh
cd facetpy
```

This bootstrap script:
- clones the FACETpy repository into `./facetpy`
- runs `./scripts/install.sh` inside that clone

### Option C (Unix): clone first, then run local installer
```bash
git clone https://github.com/H0mire/facetpy.git
cd facetpy
./scripts/install.sh
```

The script:
- checks for Python 3.11/3.12/3.13
- checks whether Poetry is installed
- asks whether Poetry should be installed if missing
- runs `poetry install --no-interaction`

### Option D (Windows PowerShell): manual install

```powershell
git clone https://github.com/H0mire/facetpy.git
Set-Location facetpy
poetry install --no-interaction
```

Use Option B/C inside WSL or Git Bash if you want to run the `.sh` installer scripts.

### Option E: system Python + Poetry (manual)

Unix (macOS/Linux):
```bash
# 1 — verify Python
python3 --version

# 2 — install Poetry (pick one)
pipx install poetry
# or: python3 -m pip install --user poetry

# 3 — install FACETpy and dependencies
poetry install --no-interaction
```

Windows (PowerShell):

```powershell
# 1 — verify Python
py --version

# 2 — install Poetry (pick one)
pipx install poetry
# or: py -m pip install --user poetry

# 3 — install FACETpy and dependencies
poetry install --no-interaction
```

### Option F (optional): Conda workflow

Unix (macOS/Linux):

```bash
conda create -n facetpy python=3.13 -y
conda activate facetpy
conda install -c conda-forge poetry -y
poetry install --no-interaction
```

Windows (PowerShell):

```powershell
conda create -n facetpy python=3.13 -y
conda activate facetpy
conda install -c conda-forge poetry -y
poetry install --no-interaction
```

Optional extras:
```text
poetry install -E deeplearning   # TensorFlow-based models
poetry install -E notebooks      # Jupyter notebook support
poetry install -E gui            # PyQt6 GUI components
poetry install -E docs           # Sphinx documentation toolchain
poetry install -E all            # everything above
```

Run commands with `poetry run ...` (for example, `poetry run python examples/quickstart.py`).


### Build the C extension (optional)

The fast Adaptive Noise Cancellation (ANC) step uses a compiled C extension.
Build it once after installing:

```bash
poetry run build-fastranc
```

If the extension is absent, ANC is skipped automatically and the rest of the
toolbox works normally.


## Running the examples

All examples are in the `examples/` folder and use the bundled
`NiazyFMRI.edf` dataset.  Run them from the project root:

```bash
# Recommended order for new users:
poetry run python examples/quickstart.py          # minimal pipeline
poetry run python examples/evaluation.py          # metrics & comparison
poetry run python examples/advanced_workflows.py  # conditional, parallel, factory
poetry run python examples/batch_processing.py    # multiple files at once
poetry run python examples/inline_steps.py        # custom steps & pipe operator
poetry run python examples/complete_pipeline_example.py  # full clinical pipeline
poetry run python examples/eeg_generation_visualization_example.py  # synthetic EEG
```


## Testing

```bash
# Run the full test suite
poetry run pytest

# Only fast unit tests (skip slow integration tests)
poetry run pytest -m "not slow"

# A single test file
poetry run pytest tests/test_core_pipeline.py -v

# With coverage report
poetry run pytest --cov=facet --cov-report=html
```

Open the coverage report:

Unix (macOS/Linux):

```bash
open htmlcov/index.html
```

Windows (PowerShell):

```powershell
start htmlcov/index.html
```


## Documentation

```bash
# Install docs dependencies
poetry install -E docs

# Build HTML docs
poetry run sphinx-build -b html docs/source docs/build

```

Open docs locally:

Unix (macOS/Linux):

```bash
open docs/build/index.html
```

Windows (PowerShell):

```powershell
start docs/build/index.html
```

Full online documentation: https://facetpy.readthedocs.io/

For comprehensive build instructions, theme configuration, and contribution guidelines see [`docs/README.md`](docs/README.md).
For PyPI release steps, see [`RELEASING.md`](RELEASING.md).


## Project structure

```
src/facet/
├── core/           Pipeline, Processor, ProcessingContext, BatchResult
├── io/             Loader, BIDSLoader, EDFExporter, BIDSExporter
├── preprocessing/  Filters, Resample, TriggerDetector, Alignment, Transforms
├── correction/     AASCorrection, PCACorrection, ANCCorrection
├── evaluation/     SNRCalculator, RMSCalculator, MetricsReport, RawPlotter
├── misc/           EEGGenerator (synthetic data)
└── pipelines.py    create_standard_pipeline() factory

examples/
├── quickstart.py                         minimal pipeline
├── evaluation.py                         metrics & comparison
├── advanced_workflows.py                 conditional, parallel, factory
├── batch_processing.py                   multiple files
├── inline_steps.py                       custom steps & pipe operator
├── complete_pipeline_example.py          full clinical pipeline
└── eeg_generation_visualization_example.py  synthetic EEG
```


## VS Code Tasks

Tasks are defined in `.vscode/tasks.json` and can be run via **Ctrl+Shift+P** → **Tasks: Run Task**.

| Task | Shortcut | Description |
|---|---|---|
| **Test: Run All** | default test task | Full test suite with coverage report |
| **Test: Run Current File** | | Run pytest on the file open in the editor |
| **Test: Unit Only** | | Only tests marked `@pytest.mark.unit` |
| **Test: Integration Only** | | Only tests marked `@pytest.mark.integration` |
| **Test: Skip Slow** | | All tests except those marked `@pytest.mark.slow` |
| **Test: Show Coverage Report** | | Open `htmlcov/index.html` in the browser |
| **Lint: Check (Ruff)** | | Check `src/` and `tests/` for lint errors |
| **Lint: Fix (Ruff)** | | Auto-fix lint errors in place |
| **Format: Check (Ruff)** | | Verify formatting without changing files |
| **Format: Apply (Ruff)** | | Apply ruff formatting to `src/` and `tests/` |
| **Build: FastRANC C Extension** | | Compile the FastRANC C extension |
| **Build: Install Dependencies** | | `poetry install` |
| **Build: Install All Extras** | | `poetry install -E all` |
| **Build: Update Dependencies** | | `poetry update` |
| **Docs: Build HTML** | | Build Sphinx documentation |
| **Docs: Open in Browser** | | Open the built docs in the browser |
| **Docs: Build & Open** | | Build docs and open immediately |
| **Run: Current Python File** | | Execute the file open in the editor |
| **Review: Uncommitted Changes (Codex)** | | Codex AI review of all local changes |
| **Review: Against Branch (Codex)** | | Codex AI review against a selected base branch (prompts for branch) |
| **QA: Full Check (Lint + Format + Test)** | | Lint + format check + full test suite in sequence |

## License

GPLv3 — see `LICENSE` for details.

Author: Janik Michael Mueller

