Tinnorm

Normative modelling and machine learning pipeline for multi-site resting-state EEG in chronic tinnitus.

Built on data from the TIDE consortium (7 sites, ~544 subjects: 276 controls, 268 tinnitus patients) spanning Austin, Dublin, Ghent, Illinois, Regensburg, Tübingen, and Zürich.

What this repo does

1. Preprocessing — BIDS conversion, ICA-based artefact rejection, source reconstruction to Desikan–Killiany parcellation
2. Feature extraction — spectral power and phase-lag index (PLI) per ROI × frequency band
3. Harmonisation — ComBat site-effect removal preserving biological covariates (age, sex, PTA)
4. Normative modelling — Bayesian linear regression fitted to controls only (leave-one-site-out); Z-score deviations computed per subject × feature
5. Classification — multi-modal ensemble (power + regional PLI + global PLI) with LOSO cross-validation; SHAP-based feature attribution
6. Paper figures — reproduction scripts for all manuscript figures

Repository layout

src/
  00–02   Data preparation, demographics, quality checks
  03–05   BIDS conversion, preprocessing, feature extraction
  06–08   Harmonisation, graph metrics, normative models
  09–18   Classification, explanation, modality comparison
  19–29   Paper analyses and figure generation
material/
  master_clean.csv        Subject-level metadata (not shared publicly)
  audiograms/, questionnaires/

Setup

conda env create -f environment.yaml
conda activate tinnorm
# or
pip install -r requirements.txt

Python 3.10. Key dependencies: mne, pcntoolkit, shap, scikit-learn, statsmodels, seaborn.

All analysis scripts are run from src/:

cd src
python 08_create_norm_models.py
python 13_compare_clfs.py
python 25_paper_neuro_figures.py

Data availability

Raw EEG and clinical data are governed by TIDE consortium data-sharing agreements and cannot be redistributed. Researchers may contact the corresponding author to enquire about access. All analysis code is released under the MIT License.

Reference

Sadeghi P. et al. — Normative EEG deviation modelling reveals right-lateralised prefrontal theta hyperconnectivity as a cross-site tinnitus biomarker (in preparation)