facetpy 2.0.0__tar.gz

facetpy-2.0.0/PKG-INFO

@@ -0,0 +1,376 @@
+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
+

facetpy-2.0.0/README.md

@@ -0,0 +1,326 @@
+# 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