Initial processing

UML diagrams presenting the flow of the analysis for each module are available here: https://github.com/ANCPLabOldenburg/MEG-QC-code/tree/main/diagrams

meg_qc.calculation.initial_meg_qc.Epoch_meg(epoching_params, data: Raw, file_path: str | None = None)

Epoch MEG data based on the parameters provided in the config file.

Event detection priority: 1. BIDS *_events.tsv alongside the MEG file (most reliable). 2. mne.find_events on the best available stim channel

(prefers combined channels like STI101; excludes known-noisy channels).

3. Fixed-length epochs (fallback when use_fixed_length_epochs=True).

Parameters:

• epoching_params (dict) – Dictionary with parameters for epoching.

• data (mne.io.Raw) – MEG data to be epoched.

• file_path (str, optional) – Path to the original MEG file, used to locate the BIDS events TSV.

Returns:

dict_epochs_mg – Keys: ‘mag’, ‘grad’, ‘epoching_mode’, ‘epoch_onset_times_s’, ‘event_summary’

Return type:

dict

meg_qc.calculation.initial_meg_qc.add_3d_ch_locations(raw, channels_objs)

Add channel locations to the MEG channels objects.

Parameters:

• raw (mne.io.Raw) – MEG data.

• channels_objs (dict) – Dictionary with MEG channels.

Returns:

channels_objs – Dictionary with MEG channels with added locations.

Return type:

dict

meg_qc.calculation.initial_meg_qc.add_EEG_lobes(channels_objs)

Assign brain region (lobe) labels to EEG channels based on standard 10-20 / 10-10 / 10-05 naming conventions.

Electrode naming rules: - First 1-3 letters = region prefix (Fp, AF, F, FC, FT, C, CP, T, TP, P, PO, O, I) - Trailing digit: odd = left hemisphere, even = right hemisphere - Trailing ‘z’ or ‘Z’ = midline

Parameters:

channels_objs (dict) – Dictionary with channel objects for each channel type.

Returns:

• channels_objs (dict) – Updated with lobe and lobe_color set on each channel.

• lobes_color_coding_str (str) – Description string.

meg_qc.calculation.initial_meg_qc.apply_eeg_montage(raw, eeg_settings)

Detect and apply a standard EEG montage for topomap plotting.

Parameters:

• raw (mne.io.Raw) – Raw EEG data.

• eeg_settings (dict) – Settings from config: {‘montage’: ‘auto’|’standard_1020’|…, …}

Returns:

• raw (mne.io.Raw) – Data with montage applied (in-place).

• montage_str (str) – Description of montage applied.

meg_qc.calculation.initial_meg_qc.apply_eeg_reference(raw, eeg_settings)

Apply EEG re-referencing.

Parameters:

• raw (mne.io.Raw) – Raw EEG data.

• eeg_settings (dict) – Settings with ‘reference_method’.

Returns:

• raw (mne.io.Raw) – Re-referenced data (in-place).

• ref_str (str) – Description.

meg_qc.calculation.initial_meg_qc.assign_channels_properties(channels_short: dict, meg_system: str)

Assign lobe area to each channel according to the lobe area dictionary + the color for plotting + channel location.

Can later try to make this function a method of the MEG_channels class. At the moment not possible because it needs to know the total number of channels to figure which meg system to use for locations. And MEG_channels class is created for each channel separately.

Parameters:

• channels (dict) – dict with channels names like: {‘mag’: […], ‘grad’: […]}

• meg_system (str) – CTF, Triux, None…

Returns:

• channels_objs (dict) – Dictionary with channel names for each channel type: mag, grad. Each channel has assigned lobe area and color for plotting + channel location.

• lobes_color_coding_str (str) – A string with information about the color coding of the lobes.

meg_qc.calculation.initial_meg_qc.change_ch_type_CTF(raw, channels)

For CTF data channels types and units need to be chnaged from mag to grad.

Parameters:

channels (dict) – dict with ch names separated by mag and grad

Returns:

channels – dict with ch names separated by mag and grad UPDATED

Return type:

dict

meg_qc.calculation.initial_meg_qc.check_chosen_ch_types(m_or_g_chosen: List, channels_objs: dict)

Check if the channels which the user gave in config file to analize actually present in the data set.

IMPORTANT: This function works on a copy of m_or_g_chosen so that the caller’s original list (e.g. the config dict) is never mutated. This is critical when the pipeline processes both MEG and EEG files in the same subject loop — mutating the shared config list would permanently remove channel types discovered absent in one file but present in another.

Parameters:

• m_or_g_chosen (list) – List with channel types to analize: mag, grad, eeg. These are the ones the user chose.

• channels_objs (dict) – Dictionary with channel names for each channel type: mag, grad, eeg. These are the ones present in the data set.

Returns:

• m_or_g_chosen (list) – New list with only those channel types that are both requested and present in the data.

• m_or_g_skipped_str (str) – String with information about which channel types were skipped.

meg_qc.calculation.initial_meg_qc.choose_channels(raw: Raw)

Separate channels by ‘mag’, ‘grad’, and ‘eeg’. Done this way, because pick() or pick_types() sometimes gets wrong results, especialy for CTF data.

Parameters:

raw (mne.io.Raw) – MEG or EEG data

Returns:

channels – dict with ch names separated by mag, grad, and eeg

Return type:

dict

meg_qc.calculation.initial_meg_qc.chs_dict_to_csv(chs_by_lobe: dict, file_name_prefix: str)

Convert dictionary with channels objects to a data frame and save it as a csv file.

Parameters:

• chs_by_lobe (dict) – Dictionary with channel objects for each channel type: mag, grad. And by lobe. Each obj hold info about the channel name, lobe area and color code, locations and (in the future) pther info, like: if it has noise of any sort.

• file_name_prefix (str) – Prefix for the file name. Example: ‘Sensors’ will result in file name ‘Sensors.csv’.

Returns:

df_deriv – List with data frames with sensors info.

Return type:

list

meg_qc.calculation.initial_meg_qc.delete_temp_folder(derivatives_root: str) → str

Remove the temporary working directory used during preprocessing.

Parameters:

derivatives_root (str) – Absolute path to the dataset’s derivatives directory (either inside the BIDS dataset or in an external location).

meg_qc.calculation.initial_meg_qc.get_all_config_params(config_file_path: str)

Parse all the parameters from config and put into a python dictionary divided by sections. Parsing approach can be changed here, which will not affect working of other fucntions.

Parameters:

config_file_path (str) – The path to the config file.

Returns:

all_qc_params – A dictionary with all the parameters from the config file.

Return type:

dict

meg_qc.calculation.initial_meg_qc.get_internal_config_params(config_file_name: str)

Parse all the parameters from config and put into a python dictionary divided by sections. Parsing approach can be changed here, which will not affect working of other fucntions. These are interanl parameters, NOT to be changed by the user.

Parameters:

config_file_name (str) – The name of the config file.

Returns:

internal_qc_params – A dictionary with all the parameters.

Return type:

dict

meg_qc.calculation.initial_meg_qc.initial_processing(default_settings: dict, filtering_settings: dict, epoching_params: dict, file_path: str, derivatives_root: str, eeg_settings: dict | None = None)

Here all the initial actions needed to analyse MEG or EEG data are done:

• read data file,

• separate channel types (mag / grad / eeg),

• apply EEG montage and reference if applicable,

• crop the data if needed,

• filter and downsample the data,

• epoch the data.

Parameters:

• default_settings (dict) – Dictionary with default settings for MEG QC.

• filtering_settings (dict) – Dictionary with parameters for filtering.

• epoching_params (dict) – Dictionary with parameters for epoching.

• file_path (str) – Path to the data file.

• derivatives_root (str) – Path to the derivatives directory.

• eeg_settings (dict, optional) – EEG-specific settings (montage, reference_method). Only used when modality is EEG.

Returns:

(meg_system, dict_epochs_mg, chs_by_lobe, channels,

raw_cropped_filtered_path, raw_cropped_filtered_resampled_path, raw_cropped_path, raw_path, info_derivs, stim_deriv, event_summary_deriv, shielding_str, epoching_str, sensors_derivs, m_or_g_chosen, m_or_g_skipped_str, lobes_color_coding_str, resample_str)

Return type:

tuple

meg_qc.calculation.initial_meg_qc.load_data(file_path)

Load MEG or EEG data from a file.

Parameters:

file_path (str) – Path to the data file (FIF, CTF .ds, EDF, BDF, BrainVision, EEGLAB, EGI, Neuroscan).

Returns:

• raw (mne.io.Raw) – Loaded data.

• shielding_str (str) – String with information about active shielding (empty for EEG).

• meg_system (str) – Identifier: ‘Triux’, ‘CTF’, ‘EEG’, or ‘OTHER’.

• modality (str) – ‘meg’ or ‘eeg’.

meg_qc.calculation.initial_meg_qc.remove_fif_and_splits(path: str) → None

Remove a FIF file and any split parts created by MNE.

MNE may split large FIF saves into multiple pieces using either split-XX or -1.fif style numbering. This function removes the specified file path as well as any adjacent split parts that share the same base name.

meg_qc.calculation.initial_meg_qc.save_meg_with_suffix(file_path: str, derivatives_root: str, raw, final_suffix: str = 'FILTERED') → str

Save an MNE raw object alongside the derivatives with a custom suffix.

The output directory is constructed as <derivatives_root>/.tmp/<subject> where subject is inferred from the first path component starting with sub- in file_path. Using derivatives_root allows callers to place temporary files outside the read-only BIDS directory if needed.

meg_qc.calculation.initial_meg_qc.sort_channels_by_lobe(channels_objs: dict)

Sorts channels by lobes.

Parameters:

channels_objs (dict) – A dictionary of channel objects.

Returns:

chs_by_lobe – A dictionary of channels sorted by ch type and lobe.

Return type:

dict

meg_qc.calculation.initial_meg_qc.stim_data_to_df(raw: Raw, epoching_params: dict | None = None)

Extract stimulus data from MEG data and put it into a pandas DataFrame. Also compute per-channel event counts using mne.find_events for later comparison with BIDS *_events.tsv.

Parameters:

• raw (mne.io.Raw) – MEG data.

• epoching_params (dict, optional) – Epoching parameters dict (used for event_dur). When None, a default minimum duration of 0.002 s is used.

Returns:

• stim_deriv (list) – List with QC_derivative object with stimulus time-series data.

• stim_channel_event_counts (dict) – {channel_name: {event_id: count, ...}, ...} for every stim channel.