Cycle-by-cycle respiration waveforms are coupled with the shape of neural oscillations

This repository contains all the necessary code to reproduce the analysis and figures of the following manuscript (currently a preprint):

E. L. Kosik-Rose, G. Zhou, A. Sherif, J. M. Rosenow, S. U. Schuele, C. O. Oluigbo, S. A. Teti, M. Koubeissi, M. R. Mowla, A. E. Rhone, S. Kumar, B. J. Dlouhy, C. Zelano, & B. Voytek. (2026). Cycle-by-cycle respiration waveforms are coupled with the shape of neural oscillations. bioRxiv, 2026.04.13.718339.

Datasets

The results are based on invasive stereoelectroencephalography (sEEG) recordings from 16 participants with medically intractable epilepsy, collected across three hospital sites:

1. Northwestern Memorial Hospital (n = 10)
2. Children's National Medical Center (n = 3)
3. University of Iowa Stead Family Children's Hospital (n = 3)

Note: Raw and preprocessed sEEG recordings contain protected health information (PHI) and cannot be publicly shared. Data access may be requested through the respective institutions subject to IRB approval and data use agreements. Per-dataset configuration files describing file paths, channel types, and respiration modalities are in metadata/.

Requirements

The provided Python 3 scripts require the following packages:

• numpy, scipy, and pandas for numerical computation and data handling
• mne for reading and storing sEEG data
• neurodsp for signal filtering
• specparam for parameterizing neural power spectra
• mat73 for reading MATLAB v7.3 files
• joblib for parallelizing the coherence analysis
• matplotlib and seaborn for generating figures
• PyYAML for reading dataset configuration files
• scienceplots for figure styling

To install all packages: pip install -r requirements.txt

The R scripts require brms, tidybayes, bayesplot, patchwork, and here (R 4.5+, with Stan via CmdStanR or RStan).

Processing Pipeline

Note: Steps 1–4 require access to the restricted sEEG recordings described above and cannot be run without institutional data access. Final analysis outputs needed to reproduce figures are provided in saved_files/ (see Figures below).

The processing pipeline can be run from start to finish by running the scripts/0* files in order:

1. 01_preproc.py — downsample to 500 Hz, bipolar re-reference sEEG, low-pass filter and detrend respiration signals
2. 02_save_chan_regions.py — build a unified electrode anatomical label table from per-site atlas files
3. 03_coherence.py — screen neural channels for significant spectral coherence with respiration using phase-randomized surrogates (parallelized across channels)
4. 04_waveform_shape.py — identify respiration-coupled channels via cross-correlation and phase monotonicity index, then compute paired waveform shape features (rise time, decay time, sharpness, AUC) on a cycle-by-cycle basis
5. 05_bayes_lmms.R — fit Bayesian multilevel models relating respiratory and neural waveform shape features using a within-between decomposition

The remaining .py files in scripts/ (coupling.py, data_io.py, electrode.py, events.py, features.py, matching.py, signal_utils.py, utils.py) are utility modules imported by the pipeline scripts and are not run directly.

Figures

The waveform shape feature outputs from 04_waveform_shape.py (saved_files/waveform_shape/all_feats_airflow.csv and all_feats_belt.csv) are provided in this repository so that figures can be reproduced without access to the raw data.

Notebook	Reproducible without raw data?
fig1.ipynb	No — requires preprocessed respiration signals
fig2.ipynb	No — requires preprocessed sEEG and respiration signals
fig3.ipynb	No — requires elec_df.csv (electrode localization, cannot be shared)
fig4.ipynb	Yes — requires all_feats_*.csv and Bayesian model outputs
fig5.ipynb	Yes — requires all_feats_*.csv only
figS1.ipynb	No — requires preprocessed respiration signals

To run a notebook:

cd figs/
jupyter notebook fig5.ipynb

Figures are saved as SVGs to fig_files/ on each run.