aperion
Resting-state EEG analysis for neurodevelopmental disorder research. The goal is a simple, honest pipeline that predicts Parkinson's disease (PD) vs healthy control (HC) from resting-state EEG — and, crucially, that keeps working when tested on a hospital it has never seen.
Status: chunks one–three complete.
- Plumbing + honesty gate — one dataset (ds002778), band-power features, logistic regression, shuffled-label leakage control.
- Aperiodic method — separate the 1/f background (offset, exponent) from the periodic peaks (FOOOF), scored with a nested SelectKBest + shrinkage-LDA harness.
- Cross-hospital — three hospitals (ds002778, ds003490, ds004584), leave-one-dataset-out evaluation, and a harmonizer to remove site effects.
Headline result (honest)
Trained on two hospitals, tested on an entirely unseen third (leave-one-dataset-out):
| Features | cross-hospital AUC (no harmonizer) | with harmonizer |
|---|---|---|
| band-power | 0.711 | 0.703 |
| aperiodic | 0.660 | 0.716 |
The harmonizer rescues the aperiodic method from behind to a tie with band-power (not a decisive win). The strongest evidence is the hospital-probe control: after harmonizing, the ability to predict which hospital a recording came from collapses (aperiodic 0.72 → 0.24, below chance) while disease AUC rises — i.e. it removed hospital effects, not disease signal. Benefit was heterogeneous (large on ds002778 / ds004584, flat on ds003490).
Project layout
NDDProject_EEG/
├── pyproject.toml # build (hatchling) + deps + optional [app]/[dev] extras
├── src/aperion/ # the importable package (LEAN: core deps only)
│ ├── datasets/ # dataset loaders (+ multi-cohort loader)
│ ├── preprocessing/ # one identical cleaning pipeline -> epochs
│ ├── features/ # band-power + aperiodic (FOOOF) features
│ ├── harmonize/ # PerHospitalStandardizer (site harmonizer)
│ ├── evaluate/ # subject-grouped CV, LODO, honesty/probe controls
│ ├── utils/ # structural harmonization (channels, sample rate)
│ ├── viz/ # PSD / group-comparison plots
│ ├── pipeline_api.py # raw -> subject-level features (single source of truth)
│ ├── model.py # trainable/saveable AperionModel (aperiodic + harmonizer)
│ └── inference.py # single-recording scoring for the app
├── app/ # SEPARATE demo web app (Streamlit) — imports aperion only
│ ├── streamlit_app.py
│ └── assets/ # saved results.json, figures, demo recordings
├── benchmarks/ # build_phase_b_artifacts.py (trains model, saves results)
├── models/ # saved model file (generated; gitignored)
├── examples/ · tests/ · docs/
Install
A virtual environment (.venv) is expected in the project root.
python -m venv .venv
source .venv/bin/activate # Windows: .\.venv\Scripts\Activate.ps1
pip install -e ".[dev]" # core + dev tools (pytest/ruff/black)
Core install pulls only mne, scikit-learn, numpy, scipy, pandas, matplotlib, fooof.
It does not install streamlit — the web app is an opt-in extra (see below).
Verify:
python -c "import aperion; print(aperion.__version__)" # -> 0.1.0
pytest
Quickstart
The feature extractors and the harmonizer are standard scikit-learn transformers, so they drop straight into a pipeline. This snippet is self-contained (toy spectra) and runs as-is:
import numpy as np
from aperion import AperiodicPeriodicExtractor, BandPowerExtractor, PerHospitalStandardizer
freqs = np.arange(2.0, 40.0, 0.5)
ch_names = ["Fz", "Cz", "Pz", "Oz"]
# power spectra shaped (n_recordings, n_channels, n_freqs) -- here a toy 1/f example
base = (10.0 ** 1.0) / (freqs ** 1.3)
spectra = np.tile(base, (6, len(ch_names), 1))
# 1) two interchangeable feature families
# (n_jobs=1 keeps FOOOF single-process — safest on Windows / inside scripts)
ap = AperiodicPeriodicExtractor(freqs, ch_names, n_jobs=1).fit_transform(spectra) # 1/f + peaks
bp = BandPowerExtractor(freqs, ch_names).fit_transform(spectra) # relative band power
# 2) remove per-hospital effects (fit on training sites; held-out site uses its own stats)
cohorts = np.array(["H1"] * 3 + ["H2"] * 3)
harm = PerHospitalStandardizer().fit(ap, cohorts=cohorts)
ap_harmonized = harm.transform(ap, cohorts=cohorts)
print(ap.shape, bp.shape, ap_harmonized.shape)
Score a real recording with the saved model (after running the build step below):
from aperion import load_model, load_recording, analyze_raw
model = load_model("models/aperion_model_v0.1.0.joblib")
raw = load_recording("data/raw/ds002778/sub-pd3/ses-off/eeg/sub-pd3_ses-off_task-rest_eeg.bdf")
result = analyze_raw(raw, model, cohort="ds002778")
print(f"P(Parkinson's) = {result['probability']:.2f} ± {result['uncertainty']:.2f}")
Reproduce the benchmark
Verify the headline cross-hospital result from the raw data (fixed seeds; requires the three
datasets in data/raw/):
python benchmarks/reproduce_cross_hospital.py
It rebuilds features, runs leave-one-dataset-out ± harmonizer for both feature types and the
hospital-probe control, and checks the two headline effects (harmonizer rescue + probe
collapse) against expected values — printing HEADLINE REPRODUCED on success.
Demo web app
The app is a research demonstration — not a medical device and not a diagnosis. It
lives in app/ and only imports/calls aperion (no data or modelling logic of its own);
it loads a pre-trained model and pre-computed result files rather than recomputing science.
1. Install the optional app dependencies (adds streamlit):
pip install -e ".[app]"
2. Build the model + result files once (the app loads these; requires the datasets in
data/raw/):
python benchmarks/build_phase_b_artifacts.py
3. Run the app locally:
streamlit run app/streamlit_app.py
# open http://localhost:8501
- Analyze page: pick a bundled demo recording (or upload one); see its spectrum split into the 1/f background and the peaks, plus the model's Parkinson's probability with an uncertainty band and a medical disclaimer.
- Results page: the honest cross-hospital story (harmonizer rescue, hospital-probe control, matched-size domain shift, and limitations), loaded from saved files.
Sharing it online (optional, not deployed here)
The simplest free option is Streamlit Community Cloud:
push this repo to GitHub, then on Community Cloud point a new app at
app/streamlit_app.py and set the dependencies to .[app]. You would need to include (or
regenerate) the models/ file and app/assets/ since large data is gitignored. This repo
does not deploy anything automatically.
Dependencies
- Core:
mne,scikit-learn,numpy,scipy,pandas,matplotlib,fooof [app]:streamlit·[dev]:pytest,ruff,black
License
MIT — see LICENSE.
Metadata
Release files for aperion 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aperion-0.1.0.tar.gz | 47.3 kB | Without provenance | Details for aperion-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aperion-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for aperion-0.1.0-py3-none-any.whl |
Total release size: 83.9 kB
Release files / aperion-0.1.0.tar.gz
| Download URL | aperion-0.1.0.tar.gz |
|---|---|
| Size | 47.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
964aac1b55b56408b8f3ee8af185b31a5912e1916eedfad9f8f44fa06a0954a2
|
|
BLAKE2b-256 checksum How to use checksums |
64c9776ff34e635503001c3be05cad9961feb0eee7eaa21a6c3969f1f932e0b5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Release files / aperion-0.1.0-py3-none-any.whl
| Download URL | aperion-0.1.0-py3-none-any.whl |
|---|---|
| Size | 36.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
55ae13b1bd1a2ecd7a2173474a083f33937e0f0adb3a57466b7b1899f92d4066
|
|
BLAKE2b-256 checksum How to use checksums |
638dcc84e3d9f6f28e3236bf8440482144f9b09fb39e55041bc2fe2be9f81602
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Security for aperion 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.