Skip to content

Reproduce Whiteford paper results with new preproc and analysis - #52

Merged
sitek merged 16 commits into
mainfrom
whiteford-repro
Sep 29, 2026
Merged

Reproduce Whiteford paper results with new preproc and analysis#52
sitek merged 16 commits into
mainfrom
whiteford-repro

Conversation

@sitek

@sitek sitek commented Sep 24, 2026

Copy link
Copy Markdown
Owner

Adds new preprocessing options and analysis outputs to allow for reproduction of the Whiteford et al. musicianship FFR results.

Note 1: this was created by branching the group-level branch, so it cannot be merged until #43 is merged with main.

Note 2: It also uses tools introduced in #46 #47 #48 #49 #50 #51 . It will conflict in preproc.py and test_preproc.py (and CHANGES.rst). To resolve: merge main into whiteford-repro. Keep both sides in _save_one_preproc_epochs (the new RejectionMode fields plus the raw-sources and counts logic). In epoch_data, put the per-condition count call after the --reject-mode abs drop block, so ABS_AMP rejections are counted.

sitek and others added 9 commits September 23, 2026 22:19
@sitek
Merge branch 'fix-plt-show-hang' into whiteford-repro
f023bdf
@sitek
Merge branch 'bids-safe-condition-labels' into whiteford-repro
c02d55c
@sitek
Merge branch 'vectorize-response-consistency' into whiteford-repro
77cd351
@sitek
Merge branch 'no-report-flag' into whiteford-repro
49982fc
@sitek @claude
Add opt-in --filter-method iir and --reject-mode abs preprocessing
e276621 
Some published FFR pipelines band-pass with zero-phase first-order
Butterworth filters (butter + filtfilt) and reject trials on absolute
amplitude (max|x| >= threshold) rather than peak-to-peak. Both are now
opt-in (defaults unchanged), plumbed through the CLI, nipype workflow
nodes and sidecar (RejectionMode). Tests compare the IIR output with
scipy butter+sosfiltfilt and check abs vs ptp on constructed epochs.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@sitek @claude
Add generic FFR harmonic-amplitude and stimulus-to-response metrics
92af1e1 
harmonic_amplitudes computes zero-padded, band-averaged FFT amplitudes at
the harmonics of f0 (fundamental and summed upper harmonics, in uV) and
stim_to_resp_xcorr the max cross-correlation in xcorr 'coeff' form with an
optional lag window and Fisher z. load_wav_mono / resample_signal bring a
stimulus to the EEG rate. Defaults follow Whiteford et al. (2025).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@sitek @claude
Add opt-in FFR metrics and covariates to the group metrics table
deba371 
With --f0 the group table gains rms_snr_polarity_sum, f0_uv and
upper_harmonics_uv computed on the sum of the two per-trial-type averages;
--stimulus adds stimulus-to-response r/z/lag (and a lag-limited variant);
--n-trials-presented adds usable_pct. participants.tsv and --covariates are
joined onto the saved TSV. discover_group_inputs returns per-type evokeds,
and the report section shows histograms instead of an unreadably tall table
for large cohorts. Defaults leave existing group outputs unchanged.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@sitek @claude
Do not lag-restrict the primary stimulus-to-response correlation
78b7440 
The stim2resp_r/z/lag_ms columns must search all lags; --xcorr-lag-range
only defines the separate stim2resp_lim_* variant. The primary columns were
accidentally computed with the restriction whenever a lag range was given.
Validated on real data: max-over-all-lags r = 0.1607 vs 0.1610 published.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@sitek @claude
Grand-average single-channel evokeds with differing channel names
6c10251 
Multi-site cohorts can label the one recorded channel differently (A32 vs
Cz) and mne.grand_average refuses to combine them. Rename single-channel
evokeds to the most common name (with a note); mismatched multi-channel
sets raise an explicit error.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@sitek
sitek requested a review from PeerHerholz September 24, 2026 14:31
@sitek sitek added bug Something isn't working enhancement New feature or request labels Sep 24, 2026
@sitek

sitek commented Sep 24, 2026

Copy link
Copy Markdown
Owner Author

@PeerHerholz in my mind, this PR is the next milestone: using the new group analysis to validate an existing dataset while also using this dataset processing to test out the current FFRPrep implementation and point out required fixes. If the previous PRs look good (referenced above—all relatively simple one-issue fixes), let's merge them so that we can focus on #43 and this current PR.

@PeerHerholz

PeerHerholz commented Sep 24, 2026

Copy link
Copy Markdown
Collaborator

Sounds good! Happy to give this PR a review when you say the word and merge the others respectively.

sitek and others added 5 commits September 24, 2026 16:05
@sitek
Merge remote-tracking branch 'origin/main' into whiteford-repro
14ef01b 
# Conflicts:
#	CHANGES.rst
#	docs/source/pipeline_details.rst
#	ffrprep/preproc.py
#	ffrprep/tests/test_preproc.py
@sitek @claude
Add --skip-existing, --clean-work-dir and --no-keep-epochs
710352d 
Bulk runs over hundreds of subjects were limited by disk space (2.5-4 GB
of Nipype working files per subject) and needed external wrapper scripts
to resume after interruptions.

- --skip-existing skips (task, run) iterations whose JSON sidecars already
  exist; completion is judged from sidecars so it survives --no-keep-epochs.
  A finished subject builds no report and no longer errors when the epochs
  were removed.
- --clean-work-dir removes an iteration's Nipype working files after it
  succeeds (logs are kept; failed iterations keep theirs for debugging).
- --keep-epochs/--no-keep-epochs (default keep) deletes *_epo.fif after the
  analysis stage; ignored with a warning for --stage preprocessing.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@sitek @claude
Add QC flag columns to the group metrics table
88bf7c2 
--min-usable-pct and --min-snr add qc_usable_pct_ok / qc_snr_ok,
qc_include and qc_reason columns to the group metrics TSV. Recordings are
flagged, never dropped: the table and grand averages keep every subject so
downstream analyses choose whether to filter, and the report summary shows
the flagged count. A NaN value fails its check; --min-usable-pct without
--n-trials-presented is a clear error.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@sitek @claude
Write a data dictionary beside the group metrics TSV
7e6024e 
The group step now writes task-<task>[_run-<run>]_metrics.json with a
description and units for every metrics column (BIDS-style), embedding the
windows, harmonic settings and QC thresholds the run used. Covariate columns
take their description/levels/units from the JSON sidecar next to the
covariate TSV when present. merge_covariates gains return_sources and
save_group_metrics a dictionary argument.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@sitek @claude
Avoid an RST emphasis warning in the --keep-epochs help
55365ef 
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@sitek

sitek commented Sep 24, 2026

Copy link
Copy Markdown
Owner Author

A few additional commits:

  • 14ef01b Merge origin/main into whiteford-repro, keeping --reject-mode abs drops counted in the sidecar epoch counts.
  • 710352d Add --skip-existing, --clean-work-dir and --no-keep-epochs so bulk runs can resume and free disk space.
  • 88bf7c2 Add --min-usable-pct / --min-snr QC flag columns to the group metrics table, flagging subjects without dropping them.
  • 7e6024e Write a BIDS-style *_metrics.json data dictionary beside the group metrics TSV.
  • 55365ef Reword the --keep-epochs help text to fix an RST emphasis warning in the docs build.

@sitek @claude
Update docs for the group step, resume/cleanup flags and sidecar fields
de611bc 
pipeline_details.rst: the group section now covers the polarity-sum and
stimulus metrics, covariates, QC flags, the metrics dictionary, channel-name
harmonization and the ffrprep-group output files; the sidecar text lists
RejectionMode and Sources/RawSources and explains the epoch counts; the
workflow section describes --skip-existing, --clean-work-dir and
--no-keep-epochs. The walkthrough, index and README point to the group step.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@sitek

sitek commented Sep 24, 2026

Copy link
Copy Markdown
Owner Author

Updated docs to match this PR's changes (as well as the group-analysis changes upstream of this PR).

  • Group section in pipeline_details.rst: it now covers the F0/harmonic and stimulus-correlation columns, usable_pct, covariates, QC flags, the _metrics.json dictionary and single-channel name harmonization. It also has an output-file tree for ffrprep-group/.
  • Sidecar text in pipeline_details.rst: it now lists RejectionMode and Sources/RawSources. It also explains that epoch counts cover only the trial types being written, and that --reject-mode abs drops count as rejected.
  • Resume and cleanup: the workflow section describes --skip-existing, --clean-work-dir and --no-keep-epochs.
  • Pointers to the group step: one line each in the walkthrough, index.rst and README.rst, plus a CHANGES.rst line.

@sitek
sitek merged commit 626fc0d into main Sep 29, 2026
6 checks passed
github-actions Bot pushed a commit that referenced this pull request Sep 29, 2026
@sitek
Merge pull request #52 from sitek/whiteford-repro
2aac82d 
Reproduce Whiteford paper results with new preproc and analysis 626fc0d
@sitek
sitek deleted the whiteford-repro branch September 29, 2026 18:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@PeerHerholz PeerHerholz Awaiting requested review from PeerHerholz

Assignees

No one assigned

Labels

bug Something isn't working enhancement New feature or request

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@sitek @PeerHerholz