ffrprep is a preprocessing and analysis pipeline for frequency-following
response (FFR) EEG data, packaged as a
BIDS-App.
A typical run loads each subject's raw recordings from a
BIDS dataset, applies
referencing and band-pass filtering, epochs around stimulus events,
and averages epochs into per-trial-type, combined, and (for 2-type
datasets) difference evoked responses. Each evoked carries
FFR-specific metrics: RMS SNR, autocorrelation, pitch tracking,
and stim ↔ response cross-correlation (peak r + lag, plus envelope
correlation on the combined evoked). Per (task, run) groups also
get a trial-to-trial response-consistency row and a phase-
consistency time–frequency plot across polarities. Outputs land in
a BIDS-derivatives layout with JSON sidecars and a single-file
HTML report per subject and stage. The CLI parallelizes
per-(task, run) iterations within a subject via --n_procs N;
multi-node / cluster scaling is one ffrprep invocation per subject
under your scheduler of choice.
Running the group analysis level against an output_dir that
already holds participant-level derivatives aggregates them across
subjects: a grand-average evoked response, a per-subject metrics
table, and a group HTML report per (task, run). The table can also
hold F0 and harmonic amplitudes, stimulus-to-response correlation,
covariates from participants.tsv and QC flag columns, and comes
with a _metrics.json data dictionary. This is aggregation
only, in the spirit of a "prep" tool — no group-level statistics are
computed; see the Usage guide for details.
See the installation guide for the
Docker image, Singularity image, and local Python install via
uv.
Process two subjects, both preprocessing and analysis stages, with four parallel workers per subject:
docker run --rm \
-v /path/to/your/bids_dataset:/data:rw \
sitek/ffrprep:latest \
/data /data/derivatives participant \
--participant_label 01 02 \
--stage both \
--n_procs 4Outputs land in /path/to/your/bids_dataset/derivatives/ under
ffrprep-preprocessing/ and ffrprep-analysis/, each containing
a sub-XX_<stage>_report.html per subject.
For cluster runs: one ffrprep invocation per subject (slurm job
array, GNU parallel, etc.) composes with --n_procs for
intra-subject parallelism. The
usage docs
include slurm and GNU parallel examples.
Full documentation — pipeline walkthrough, CLI reference, API reference — at https://sitek.github.io/ffrprep.