Tools¶
Every tool BrainO registers, with its parameters. This page is generated from the code: the
parameter tables come from the same JSON schemas the AI agent sees (braino tools schema).
Tools that work on one recording take its subject, and task, session and run when the
subject has several recordings. Decision tools return a proposal that takes effect only once
a person approves it.
dataset.inspect¶
Risk: read
Summarise the dataset: subjects, sessions, tasks, and for each recording its sampling rate, duration, power-line frequency, channels per type, channels marked bad and events per type.
| Parameter | Type | Default | Description |
|---|---|---|---|
max_recordings |
integer | 20 |
How many recordings to list in detail |
eeg.detect_bad_channels¶
Risk: decision (its proposal takes effect only once a person approves it)
Find bad EEG channels (flat, noisy, poorly correlated with the others) and propose marking them bad. Checks the ICA-cleaned recording if there is one, else the preprocessed one. Running eeg.ica_clean first is best: eye activity then no longer makes channels near the eyes look bad, and a broken channel shows up in ICA as a 'channel noise' component. Once approved, bad channels are interpolated when epoching (and left out of an ICA run afterwards).
| Parameter | Type | Default | Description |
|---|---|---|---|
subject |
string | required | Subject label without 'sub-', e.g. '001' |
task |
string or null | null |
Task label, if the subject has several |
session |
string or null | null |
Session label, if any |
run |
string or null | null |
Run number, if any |
method |
pyprep | qc |
"pyprep" |
'pyprep' (PREP noisy-channel detection: deviation, correlation, high-frequency noise, RANSAC) or 'qc' (BrainO's flat/noisy screen) |
ransac |
boolean | true |
pyprep only: also run RANSAC (needs electrode positions) |
correlation_max_bad_time |
number | 0.05 |
pyprep only: share of 1-s windows with low correlation (< 0.4 with every other channel) that makes a channel bad. PREP uses 0.01, too strict for caps with fewer than 64 channels |
leave_out_blinks |
boolean | true |
Leave blinks (from the EOG, or Fp1/Fp2) out of the detection, so channels near the eyes are not marked bad for blinks, which ICA removes |
seed |
integer | 42 |
Random seed for RANSAC |
eeg.epoch¶
Risk: compute
Cut the recording into epochs around events, grouped into named conditions, with baseline correction and rejection of epochs with artifacts (autoreject by default). Reads the ICA-cleaned recording if there is one, else the preprocessed one; bad channels are interpolated first.
| Parameter | Type | Default | Description |
|---|---|---|---|
conditions |
map to list of string | required | Condition name -> event descriptions (annotations) that belong to it, e.g. |
tmin |
number | -0.2 |
Epoch start relative to the event, s |
tmax |
number | 0.8 |
Epoch end relative to the event, s |
baseline |
[number or null, number or null] or null | [null, 0.0] |
Baseline interval in s ([null, 0] = from epoch start to the event); null for no baseline correction |
reject |
autoreject | autoreject_global | peak_to_peak | none |
"autoreject" |
'autoreject' (learned per-channel thresholds, repairs or drops epochs), 'autoreject_global' (one learned threshold), 'peak_to_peak' (fixed threshold) or 'none' |
peak_to_peak_uv |
number | 150.0 |
Threshold for reject='peak_to_peak', µV |
interpolate_bads |
boolean | true |
Interpolate channels marked bad from their neighbours before epoching |
event_delay_s |
number | 0.0 |
Measured delay between the event codes and what the participant saw or heard (e.g. a monitor's delay, measured with a photosensor), s. Events are moved this much later, to the earlier sample. ERP CORE: 0.026 |
seed |
integer | 42 |
Random seed for autoreject |
subject |
string | required | Subject label without 'sub-', e.g. '001' |
task |
string or null | null |
Task label, if the subject has several |
session |
string or null | null |
Session label, if any |
run |
string or null | null |
Run number, if any |
label |
string | "epochs" |
Name for these epochs (letters and digits), used by later steps |
eeg.erp¶
Risk: compute
Average the epochs of each condition into event-related potentials, compute difference waves, and measure amplitudes (mean amplitude or peak and latency in a time window over chosen channels). Run eeg.epoch first. The averages are written for group statistics.
| Parameter | Type | Default | Description |
|---|---|---|---|
subject |
string | required | Subject label without 'sub-', e.g. '001' |
task |
string or null | null |
Task label, if the subject has several |
session |
string or null | null |
Session label, if any |
run |
string or null | null |
Run number, if any |
label |
string | "epochs" |
Label of the epochs to use (as given to eeg.epoch) |
conditions |
list of string or null | null |
Conditions to average; null for all |
contrasts |
list of Contrast | null |
Difference waves to compute, e.g. rare minus frequent |
measures |
list of Measure | null |
Amplitude measures to take from every average and difference wave |
eeg.ica_clean¶
Risk: decision (its proposal takes effect only once a person approves it)
Fit ICA to the preprocessed recording (good channels only), label the components (eye, heart, muscle, brain, ...) and propose removing the artifact components. Run eeg.preprocess (and eeg.detect_bad_channels, if used) first. Once approved, the cleaned recording is what eeg.epoch reads.
| Parameter | Type | Default | Description |
|---|---|---|---|
subject |
string | required | Subject label without 'sub-', e.g. '001' |
task |
string or null | null |
Task label, if the subject has several |
session |
string or null | null |
Session label, if any |
run |
string or null | null |
Run number, if any |
n_components |
integer or number or null | null |
Number of components (>= 2), share of variance to keep (0-1, e.g. 0.99), or null for as many as the data allow |
method |
infomax | fastica | picard |
"picard" |
'picard' (extended infomax, fast), 'infomax' (the same, slower) or 'fastica' |
labeler |
iclabel | eog |
"iclabel" |
'iclabel' (ICLabel classifier) or 'eog' (correlation with EOG channels) |
exclude_labels |
list of string | null |
Component labels proposed for removal; ICLabel labels are brain, muscle artifact, eye blink, heart beat, line noise, channel noise, other |
min_probability |
number | 0.8 |
Least label probability for removal |
seed |
integer | 42 |
Random seed for ICA |
eeg.preprocess¶
Risk: compute
Filter (high-pass, low-pass, optional notch), resample and re-reference one recording. Writes a preprocessed copy to the derivatives; the original is not changed. Bad-channel detection, ICA and epoching all start from this copy, so run this first. Electrode positions are added from a standard layout if the file has none and the names identify one.
| Parameter | Type | Default | Description |
|---|---|---|---|
l_freq |
number or null | 0.1 |
High-pass cut-off in Hz; null for no high-pass |
h_freq |
number or null | 40.0 |
Low-pass cut-off in Hz; null for no low-pass |
filter_method |
fir | iir |
"fir" |
'fir' (zero-phase windowed FIR, MNE's default) or 'iir' (zero-phase 4th-order Butterworth) |
notch_line_noise |
boolean | false |
Notch-filter the power-line frequency and its harmonics below the low-pass |
notch_freqs |
list of number | null |
Further frequencies (Hz) to notch-filter |
resample_hz |
number or null | null |
New sampling rate in Hz; null keeps the original |
reference |
average | average_with_eog | none or list of string |
"average" |
'average' (of the good EEG channels), 'average_with_eog' (of the good EEG and EOG channels, subtracted from both, as ERP CORE does), 'none' to keep the recording's reference, or the channels to reference to, e.g. ['P9', 'P10'] for linked mastoids |
subject |
string | required | Subject label without 'sub-', e.g. '001' |
task |
string or null | null |
Task label, if the subject has several |
session |
string or null | null |
Session label, if any |
run |
string or null | null |
Run number, if any |
eeg.qc_report¶
Risk: compute
Screen one recording for data-quality problems: flat channels, noisy channels, power-line noise and the share of time with large artifacts. Changes nothing; the per-channel table is written to the derivatives.
| Parameter | Type | Default | Description |
|---|---|---|---|
subject |
string | required | Subject label without 'sub-', e.g. '001' |
task |
string or null | null |
Task label, if the subject has several |
session |
string or null | null |
Session label, if any |
run |
string or null | null |
Run number, if any |
eeg.spectral¶
Risk: compute
Estimate power spectra (Welch or multitaper) and band power (delta, theta, alpha, beta, gamma, or chosen bands), per condition from epochs or for the whole continuous recording. Reports absolute (µV²) and relative band power and the peak alpha frequency.
| Parameter | Type | Default | Description |
|---|---|---|---|
subject |
string | required | Subject label without 'sub-', e.g. '001' |
task |
string or null | null |
Task label, if the subject has several |
session |
string or null | null |
Session label, if any |
run |
string or null | null |
Run number, if any |
source |
epochs | continuous |
"epochs" |
'epochs' (per condition, average of the epochs' spectra) or 'continuous' (the whole cleaned recording, e.g. for resting state) |
label |
string | "epochs" |
Label of the epochs to use (as given to eeg.epoch) |
method |
welch | multitaper |
"welch" |
'welch' or 'multitaper' |
fmin |
number | 1.0 |
Lowest frequency, Hz |
fmax |
number | 45.0 |
Highest frequency, Hz |
bands |
map to [number, number] | null |
Frequency bands, name -> [low, high) Hz |
conditions |
list of string or null | null |
Conditions; null for all |
eeg.tfr¶
Risk: compute
Time-frequency power with Morlet wavelets, per condition, baseline-corrected (dB by default). Shows when power in each frequency band rises or falls relative to the event. Run eeg.epoch first; written for group statistics.
| Parameter | Type | Default | Description |
|---|---|---|---|
subject |
string | required | Subject label without 'sub-', e.g. '001' |
task |
string or null | null |
Task label, if the subject has several |
session |
string or null | null |
Session label, if any |
run |
string or null | null |
Run number, if any |
label |
string | "epochs" |
Label of the epochs to use (as given to eeg.epoch) |
fmin |
number | 6.0 |
Lowest frequency, Hz. Low frequencies need long epochs: 6 Hz needs 0.8 s, 4 Hz 1.2 s |
fmax |
number | 40.0 |
Highest frequency, Hz |
n_freqs |
integer | 20 |
Number of log-spaced frequencies |
cycles_divisor |
number | 2.0 |
Wavelet cycles = frequency / this (at least 3) |
baseline |
[number or null, number or null] or null | [null, 0.0] |
Baseline interval in s; null for none |
mode |
logratio | percent | zscore | none |
"logratio" |
Baseline correction: 'logratio' (dB), 'percent', 'zscore' or 'none' (µV²) |
decim |
integer | 1 |
Keep every n-th time point of the result |
conditions |
list of string or null | null |
Conditions; null for all |
bands |
map to [number, number] | null |
Bands in which the summary reports the largest change |
stats.cluster_permutation¶
Risk: compute
Cluster-based permutation test across subjects (one condition against 0, or a paired test of two): finds groups of neighbouring channels and time (or frequency) points with an effect, and gives each cluster a p-value that controls the family-wise error rate. Reads the per-subject results of eeg.erp, eeg.spectral or eeg.tfr.
| Parameter | Type | Default | Description |
|---|---|---|---|
task |
string | required | Task label of the recordings |
session |
string or null | null |
Session label, if any |
run |
string or null | null |
Run number, if subjects have several |
subjects |
list of string or null | null |
Subjects to include; null for every subject with results |
data |
erp | psd | tfr |
"erp" |
Which per-subject results: 'erp' (eeg.erp averages, µV), 'psd' (eeg.spectral spectra, dB), 'tfr' (eeg.tfr power) |
label |
string | "epochs" |
Label of the results (the epochs label; 'continuous' for spectra of continuous data) |
conditions |
list of string | required | One condition or difference wave (tested against 0), two conditions (paired test of the first minus the second), or more (repeated-measures ANOVA, stats.mass_univariate only) |
channels |
list of string or null | null |
Channels; null for all |
tmin |
number or null | null |
Start of the time window, s |
tmax |
number or null | null |
End of the time window, s |
fmin |
number or null | null |
Lowest frequency (psd, tfr), Hz |
fmax |
number or null | null |
Highest frequency (psd, tfr), Hz |
output_label |
string | "group" |
Name for the output files |
p_threshold |
number | 0.05 |
Two-sided p of the t that forms clusters |
alpha |
number | 0.05 |
|
n_permutations |
integer | 1024 |
|
seed |
integer | 42 |
stats.mass_univariate¶
Risk: compute
Test across subjects at every channel and time (or frequency) point: t-test of one condition against 0, paired t-test of two conditions, or repeated-measures ANOVA of more, corrected for multiple comparisons (FDR by default). Reads the per-subject results of eeg.erp, eeg.spectral or eeg.tfr. Restrict channels and windows to planned ones when you can: fewer tests, more power.
| Parameter | Type | Default | Description |
|---|---|---|---|
task |
string | required | Task label of the recordings |
session |
string or null | null |
Session label, if any |
run |
string or null | null |
Run number, if subjects have several |
subjects |
list of string or null | null |
Subjects to include; null for every subject with results |
data |
erp | psd | tfr |
"erp" |
Which per-subject results: 'erp' (eeg.erp averages, µV), 'psd' (eeg.spectral spectra, dB), 'tfr' (eeg.tfr power) |
label |
string | "epochs" |
Label of the results (the epochs label; 'continuous' for spectra of continuous data) |
conditions |
list of string | required | One condition or difference wave (tested against 0), two conditions (paired test of the first minus the second), or more (repeated-measures ANOVA, stats.mass_univariate only) |
channels |
list of string or null | null |
Channels; null for all |
tmin |
number or null | null |
Start of the time window, s |
tmax |
number or null | null |
End of the time window, s |
fmin |
number or null | null |
Lowest frequency (psd, tfr), Hz |
fmax |
number or null | null |
Highest frequency (psd, tfr), Hz |
output_label |
string | "group" |
Name for the output files |
correction |
fdr | bonferroni | max_stat | none |
"fdr" |
Multiple-comparison correction: 'fdr' (false discovery rate), 'bonferroni', 'max_stat' (permutation, family-wise) or 'none' (exploration only) |
alpha |
number | 0.05 |
|
n_permutations |
integer | 1000 |
For max_stat |
seed |
integer | 42 |
system.info¶
Risk: read
Report the BrainO version, Python version and operating system.