osl_dynamics.meeg.preproc#

Preprocessing functions.

Functions#

`detect_bad_segments`(raw, picks[, mode, metric, ...])	Bad segment detection using the G-ESD algorithm.
`detect_bad_channels`(raw, picks[, ref_meg, ...])	Detect bad channels using the G-ESD algorithm based on standard deviation.
`ica_label`(raw[, picks, n_components, method, ...])	Automatic ICA artefact rejection using mne-icalabel.
`ica_ecg_eog_correlation`(raw[, picks, n_components, ...])	ICA artefact rejection using ECG/EOG correlation.
`plot_ica_components`(ica, ic_labels)	Plot excluded ICA component topographies with labels.
`decimate_headshape_points`(raw[, decimate_amount, ...])	Decimate headshape points.
`save_qc_plots`(raw, output_dir[, show, ica, ic_labels])	Save preprocessing QC plots and summary.
`plot_sum_square_time_series`(raw[, exclude_bads])	Plot sum-square time series.
`plot_channel_stds`(raw[, exclude_bad_segments])	Plot distribution of standard deviations across channels.

Module Contents#

osl_dynamics.meeg.preproc.detect_bad_segments(raw, picks, mode=None, metric='std', window_length=None, significance_level=0.05, maximum_fraction=0.1, ref_meg='auto')[source]#

Bad segment detection using the G-ESD algorithm.

Parameters:

raw (mne.io.Raw) – MNE Raw object.
picks (str or list of str) – Channel type to pick.
mode (str, optional) – None or ‘diff’ to take the difference fo the time series before detecting bad segments.
metric (str, optional) – Either ‘std’ (for standard deivation) or ‘kurtosis’.
window_length (int, optional) – Window length to used to calculate statistics. Defaults to twice the sampling frequency.
significance_level (float, optional) – Significance level (p-value) to consider as an outlier.
maximum_fraction (float, optional) – Maximum fraction of time series to mark as bad.
ref_meg (str, optional) – ref_meg argument to pass to mne.pick_types.

Returns:

raw – MNE Raw object.

Return type:

mne.io.Raw

osl_dynamics.meeg.preproc.detect_bad_channels(raw, picks, ref_meg='auto', significance_level=0.05, log10=True)[source]#

Detect bad channels using the G-ESD algorithm based on standard deviation.

Parameters:

raw (mne.io.Raw) – MNE raw object.
picks (str) – Channel types to pick. See Notes for recommendations.
ref_meg (str, optional) – ref_meg argument to pass with mne.pick_types.
significance_level (float, optional) – Significance level for detecting outliers. Must be between 0-1.
log10 (bool, optional) – Should we apply a log10 transform to the standard deviations? This is normally a good idea to make sure the standard deviations are normally distributed.

Returns:

raw – MNE Raw object with bad channels marked.

Return type:

mne.io.Raw

Notes

For Elekta/MEGIN data, we recommend using picks=’mag’ or picks=’grad’ separately (in no particular order).

Note that with CTF data, mne.pick_types will return:: ~274 axial grads (as magnetometers) if picks=’mag’, ref_meg=False ~28 reference axial grads if picks=’grad’.

Thus, it is recommended to use picks=’mag’ in combination with ref_mag=False, and picks=’grad’ separately (in no particular order).

osl_dynamics.meeg.preproc.ica_label(raw, picks='mag', n_components=20, method='megnet', threshold=0.5, random_state=42)[source]#

Automatic ICA artefact rejection using mne-icalabel.

Fits ICA on a bandpass-filtered copy of the data, labels components using a pre-trained classifier, and removes artefact components from the original data.

For MEG data, uses the MEGNet classifier. For EEG data, uses ICLabel.

Parameters:

raw (mne.io.Raw) – MNE Raw object.
picks (str, optional) – Channel type to use for ICA. For Elekta MEG data, use "mag" (MEGNet was trained on magnetometer topographies).
n_components (int, optional) – Number of ICA components. Should not exceed the data rank. For MaxFiltered Elekta data (rank ~60), 20 is a safe default.
method (str, optional) – Labelling method: "megnet" for MEG or "iclabel" for EEG.
threshold (float, optional) – Probability threshold (0–1) for excluding a component. Components labelled as artefact with probability above this threshold are removed.
random_state (int, optional) – Random seed for ICA reproducibility.

Returns:

raw (mne.io.Raw) – Cleaned MNE Raw object.
ica (mne.preprocessing.ICA) – Fitted ICA object with exclude set.
ic_labels (dict) – Dictionary with keys "labels" (list of str) and "y_pred_proba" (array of float).

Return type:

tuple[mne.io.Raw, Any, dict]

Notes

For EEG data, use picks="eeg" and method="iclabel":

raw, ica, ic_labels = preproc.ica_label(
    raw, picks="eeg", method="iclabel", n_components=30,
)

osl_dynamics.meeg.preproc.ica_ecg_eog_correlation(raw, picks='meg', n_components=40, l_freq=1.0, h_freq=None, ecg_method='ctps', ecg_threshold='auto', eog_measure='correlation', eog_threshold=0.35, random_state=42)[source]#

ICA artefact rejection using ECG/EOG correlation.

Fits ICA on a high-pass filtered copy of the data, identifies artefact components by correlating with ECG and EOG signals, and removes them from the original data. Follows the approach used in osl-ephys.

Uses picks="meg" by default so both magnetometers and gradiometers are denoised. Does not require mne-icalabel.

Parameters:

raw (mne.io.Raw) – MNE Raw object.
picks (str, optional) – Channel type to use for ICA. "meg" fits on both mags and grads.
n_components (int, optional) – Number of ICA components. Should not exceed the data rank. For MaxFiltered Elekta data (rank ~60), 40 is a safe default.
l_freq (float, optional) – High-pass filter frequency for the ICA fitting copy.
h_freq (float, optional) – Low-pass filter frequency for the ICA fitting copy.
ecg_method (str, optional) – Method for ECG detection: "ctps" (cross-trial phase statistics) or "correlation". Set to None to skip ECG detection.
ecg_threshold (str or float, optional) – Threshold for ECG component detection.
eog_measure (str, optional) – Measure for EOG detection: "correlation" or "zscore".
eog_threshold (float, optional) – Threshold for EOG component detection. When eog_measure="correlation", this is an absolute correlation threshold (e.g. 0.35). When eog_measure="zscore", this is a z-score threshold (e.g. 3.0).
random_state (int, optional) – Random seed for ICA reproducibility.

Returns:

raw (mne.io.Raw) – Cleaned MNE Raw object.
ica (mne.preprocessing.ICA) – Fitted ICA object with exclude set.
ic_labels (dict) – Dictionary with keys "labels" (list of str) and "y_pred_proba" (array of float), compatible with plot_ica_components().

Return type:

tuple[mne.io.Raw, Any, dict]

Notes

For EEG data, use picks="eeg". Note that synthetic ECG detection only works with MEG magnetometers — for EEG data a dedicated ECG channel must be present, otherwise set ecg_method=None:

raw, ica, ic_labels = preproc.ica_ecg_eog_correlation(
    raw, picks="eeg", n_components=30, ecg_method=None,
)

osl_dynamics.meeg.preproc.plot_ica_components(ica, ic_labels)[source]#

Plot excluded ICA component topographies with labels.

Creates a composite figure showing only the excluded ICA components with their classification labels and probabilities.

Parameters:

ica (mne.preprocessing.ICA) – Fitted ICA object.
ic_labels (dict) – Dictionary with keys "labels" and "y_pred_proba".

Returns:

fig – The composite figure, or None if no components were excluded.

Return type:

matplotlib.figure.Figure or None

osl_dynamics.meeg.preproc.decimate_headshape_points(raw, decimate_amount=0.01, include_facial_info=True, remove_zlim=-0.02, angle=0, method='gridaverage', face_Z=None, face_Y=None, face_X=None, decimate_facial_info=True, decimate_facial_info_amount=0.01)[source]#

Decimate headshape points.

Useful for reducing the number of headshape points collected using an EinScan for OPM recordings.

Parameters:

raw (mne.io.Raw) – MNE Raw object.
decimate_amount (float, optional) – Bin width in metres to decimate.
include_facial_info (bool, optional) – Should we keep facial headshape points?
remove_zlim (float, optional) – Remove headshape points below this z-value (in metres).
angle (float, optional) – How much should we rotate the headshape points?
method (str, optional) – What method should we use for decimation?
face_Z (list, optional) – Keep headshape points within these z-values (in metres).
face_Y (list, optional) – Keep headshape points within these y-values (in metres).
face_X (list, optional) – Keep headshape points within these x-values (in metres).
decimate_facial_info (bool, optional) – Should we decimate facial headshape points?
decimate_facial_info_amount (float, optional) – Bin width in metres to decimate.

Returns:

raw – MNE Raw object.

Return type:

mne.io.Raw

osl_dynamics.meeg.preproc.save_qc_plots(raw, output_dir, show=False, ica=None, ic_labels=None)[source]#

Save preprocessing QC plots and summary.

Saves the following files to output_dir:

1_summary.json: preprocessing summary stats
1_psd.png: sensor-level PSD
1_sum_square.png: sum-square time series
1_sum_square_exclude_bads.png: sum-square excluding bad segments/channels
1_channel_stds.png: channel standard deviation distributions
1_ica_components.png: ICA component topographies (if ica and ic_labels are provided)

Parameters:

raw (mne.io.Raw) – Preprocessed MNE Raw object.
output_dir (str or Path) – Directory to save plots to.
show (bool, optional) – Whether to display the plots interactively. Default is False.
ica (mne.preprocessing.ICA, optional) – Fitted ICA object. If provided along with ic_labels, saves ICA component topography plot.
ic_labels (dict, optional) – ICA label dictionary from ica_label.

Return type:

None

osl_dynamics.meeg.preproc.plot_sum_square_time_series(raw, exclude_bads=False)[source]#

Plot sum-square time series.

Parameters:

raw (mne.io.Raw) – MNE Raw object.
exclude_bads (bool, optional) – Whether to exclude bad channels and bad segments.

Return type:

None

osl_dynamics.meeg.preproc.plot_channel_stds(raw, exclude_bad_segments=True)[source]#

Plot distribution of standard deviations across channels.

Parameters:

raw (mne.io.Raw) – MNE Raw object.
exclude_bad_segments (bool) – Whether to exclude bad segments.

Return type:

None