Skip to content

Add average_reference option to NoisyChannels - #217

Merged
sappelhoff merged 2 commits into
mainfrom
noisychannels-average-reference
Oct 27, 2026
Merged

sappelhoff merged 2 commits into
mainfrom
noisychannels-average-reference

Conversation

@sappelhoff

@sappelhoff sappelhoff commented Oct 27, 2026 •

Copy link
Copy Markdown
Owner

Adds a keyword-only average_reference=False parameter to NoisyChannels.

Why

Users who want to detect bad channels on average-referenced data currently have to re-reference the Raw before passing it in. That has three problems:

  • Flat and NaN channels become undetectable. After set_eeg_reference("average"), a flat channel c becomes c - mean(all channels) and carries the variance of the mean signal, so find_bad_by_nan_flat (run in __init__) no longer flags it. A single NaN channel spreads into every channel through the average.
  • Dropouts become undetectable. A flat stretch in an otherwise good channel carries -mean(other channels) instead of a flat signal, so bad_by_dropout in find_bad_by_correlation never triggers.
  • Unusable channels contaminate the reference. Manually marked, NaN, and flat channels are averaged into every other channel before detection runs.

What

With average_reference=True, __init__ runs find_bad_by_nan_flat on the data as passed (unchanged), builds EEGData from the usable channels (not bad-by-NaN, bad-by-flat, or manually marked) as before, and then subtracts their mean from EEGData, before EEGFiltered is computed and before any other detector runs. Deviation, HF noise, correlation, SNR, PSD, and RANSAC all read EEGData/EEGFiltered, so they all see the re-referenced data; raw_mne is untouched.

The subtracted reference (one row) is kept. find_bad_by_correlation filters it with the same filter and adds it back per window for the dropout test only. The filter is linear and negation is exact in floating point, so a zeroed stretch is recovered exactly and the existing MAD == 0 criterion still applies. Dropout windows are excluded from the correlation computation, as before.

  • Default False: no change in behaviour.
  • Ignored with a warning when matlab_strict=True (same pattern as reject_by_annotation).
  • With fewer than 2 usable channels, a warning is logged and no reference is applied (a single channel referenced to itself would be all zeros).
  • New entry in the MATLAB differences page under "PyPREP-Only Features"; changelog entry.

Tests

Flat/NaN still detected and EEGData equals the usable channels minus their own mean; a dropout is still detected with average_reference=True (fails without the add-back); results independent of the content of a manually marked channel; default off; matlab_strict; too few usable channels; non-boolean input. Full suite: 68 passed; pre-commit clean; docs build clean with -W.

@codecov

codecov Bot commented Oct 27, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.08%. Comparing base (aec30dc) to head (f9175d2).

Additional details and impacted files
@@            Coverage Diff             @@
##             main     #217      +/-   ##
==========================================
+ Coverage   98.03%   98.08%   +0.04%     
==========================================
  Files           8        8              
  Lines         864      886      +22     
==========================================
+ Hits          847      869      +22     
  Misses         17       17              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@sappelhoff
sappelhoff merged commit 6462354 into main Oct 27, 2026
9 of 10 checks passed
@sappelhoff
sappelhoff deleted the noisychannels-average-reference branch October 27, 2026 20:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant