High frequency (muscle) disturbancies

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.metrics.muscle_meg_qc.MUSCLE_meg_qc(muscle_params: dict, psd_params: dict, psd_params_internal: dict, channels: dict, raw_orig: Raw, noisy_freqs_global: dict, m_or_g_chosen: list, attach_dummy: bool = True, cut_dummy: bool = True)[source]

Detect muscle artifacts in MEG data. Gives the number of muscle artifacts based on the set z score threshold: artifact time + artifact z score. Threshold is set by the user in the config file. Several thresholds can be used on the loop.

Notes

The data has to first be notch filtered at powerline frequencies as suggested by mne.

Parameters:

  • muscle_params (dict) – The parameters for muscle artifact detection originally defined in the config file.

  • psd_params (dict) – The parameters for PSD calculation originally defined in the config file. This in only needed to calculate powerline noise in case PSD was not calculated before.

  • psd_params_internal (dict) – The parameters for PSD calculation originally defined in the internal config file.

  • channels (dict) – Dictionary with channels names separated by mag/grad

  • raw_orig (mne.io.Raw) – The raw data.

  • noisy_freqs_global (List) – The powerline frequencies found in the data by previously running PSD_meg_qc.

  • m_or_g_chosen (List) – The channel types chosen for the analysis: ‘mag’ or ‘grad’.

  • attach_dummy (bool) – Whether to attach dummy data to the start and end of the recording to avoid filtering artifacts. Default is True.

  • cut_dummy (bool) – Whether to cut the dummy data after filtering. Default is True.

Returns:

  • muscle_derivs (List) – A list of QC_derivative objects for muscle events containing figures.

  • simple_metric (dict) – A simple metric dict for muscle events.

  • muscle_str_joined (str) – String with notes about muscle artifacts for report

  • scores_muscle (np.ndarray) – The muscle scores.

  • raw (mne.io.Raw) – The raw data with filtered noise or not filtered if no noise was found.

meg_qc.calculation.metrics.muscle_meg_qc.attach_dummy_data(raw: Raw, attach_seconds: int = 5)[source]

Attach a dummy start and end to the data to avoid filtering artifacts at the beginning/end of the recording. Dummy data is mirrored data: take beginning of real data, mirror it and attach to the start of the recording. Same for the end of the recording. It will be cut off after filtering.

Parameters:

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

  • attach_seconds (int) – The number of seconds to attach to the start and end of the recording.

Returns:

raw – The raw data with dummy start attached.

Return type:

mne.io.Raw

meg_qc.calculation.metrics.muscle_meg_qc.calculate_muscle_NO_threshold(raw, m_or_g_decided, muscle_params, threshold_muscle, muscle_freqs, cut_dummy, attach_sec, min_distance_between_different_muscle_events, muscle_str_joined)[source]

Calculate muscle artifacts without thresholding by user.

We still have to use threshold_muscle here, even if we do not want to use it: annotate_muscle_zscore() requires threshold_muscle so define a minimal one here: 5 z-score.

Parameters:

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

  • m_or_g_decided (List) – The channel types chosen for the analysis: ‘mag’ or ‘grad’.

  • muscle_params (dict) – The parameters for muscle artifact detection originally defined in the config file.

  • threshold_muscle (float) – The z-score threshold for muscle detection.

  • muscle_freqs (List) – The frequencies of muscle artifacts, usually 110 and 140 Hz.

  • cut_dummy (bool) – Whether to cut the dummy data after filtering. Dummy data is attached to the start and end of the recording to avoid filtering artifacts. Default is True.

  • attach_sec (int) – The number of seconds to attach to the start and end of the recording.

  • min_distance_between_different_muscle_events (int) – The minimum distance between different muscle events in seconds.

  • muscle_str_joined (str) – Notes about muscle detection to use as description.

Returns:

  • simple_metric (dict) – A simple metric dict for muscle events.

  • scores_muscle (np.ndarray) – The muscle scores.

  • df_deriv (List) – A list of QC_derivative objects for muscle events containing figures.

meg_qc.calculation.metrics.muscle_meg_qc.filter_noise_before_muscle_detection(raw: Raw, noisy_freqs_global: dict, muscle_freqs: List = [110, 140])[source]

Filter out power line noise and other noisy freqs in range of muscle artifacts before muscle artifact detection. MNE advices to filter power line noise. We also filter here noisy frequencies in range of muscle artifacts. List of noisy frequencies for filtering come from PSD artifact detection function. If any noise peaks were found there for mags or grads they will all be passed here and checked if they are in range of muscle artifacts.

Parameters:

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

  • noisy_freqs_global (dict) – The noisy frequencies found in PSD artifact detection function.

  • muscle_freqs (List) – The frequencies of muscle artifacts, usually 110 and 140 Hz.

Returns:

raw – The raw data with filtered noise or not filtered if no noise was found.

Return type:

mne.io.Raw

meg_qc.calculation.metrics.muscle_meg_qc.find_powerline_noise_short(raw, psd_params, psd_params_internal, m_or_g_chosen, channels)[source]

Find powerline noise in the data.

Parameters:

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

  • psd_params (dict) – The parameters for PSD calculation originally defined in the config file.

  • psd_params_internal (dict) – The parameters for PSD calculation originally defined in the internal config file.

  • m_or_g_chosen (List) – The channel types chosen for the analysis: ‘mag’ or ‘grad’.

Returns:

noisy_freqs – The noisy frequencies found in the data separated by channel type.

Return type:

dict

meg_qc.calculation.metrics.muscle_meg_qc.make_simple_metric_muscle(m_or_g_decided: str, z_scores_dict: dict, muscle_str_joined: str)[source]

Make a simple metric dict for muscle events.

Parameters:

  • m_or_g_decided (str) – The channel type used for muscle detection: ‘mag’ or ‘grad’.

  • z_scores_dict (dict) – The z-score thresholds used for muscle detection.

  • muscle_str_joined (str) – Notes about muscle detection to use as description.

Returns:

simple_metric – A simple metric dict for muscle events.

Return type:

dict

meg_qc.calculation.metrics.muscle_meg_qc.save_muscle_to_csv(file_name_prefix: str, raw: Raw, scores_muscle: ndarray, high_scores_muscle_times: ndarray, high_scores_muscle: ndarray, m_or_g: str)[source]

Save muscle artifacts to a CSV file.

Parameters:

  • file_name_prefix (str) – The prefix for the file name. Example: ‘Muscle’.

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

  • scores_muscle (np.ndarray) – The muscle scores.

  • high_scores_muscle_times (np.ndarray) – The times of the high muscle scores.

  • high_scores_muscle (np.ndarray) – The high muscle scores.

  • m_or_g (str) – The channel type chosen for the analysis: ‘mag’ or ‘grad’.

Returns:

df_deriv – A list of QC_derivative objects for muscle events containing figures.

Return type:

List