Muscle artifacts

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, raw_orig: Raw, noisy_freqs_global: dict, m_or_g_chosen: list, verbose_plots: bool, interactive_matplot: bool = False, 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.

  • 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’.

  • verbose_plots (bool) – True for showing plot in notebook.

  • interactive_matplot (bool) – Whether to use interactive matplotlib plots or not. Default is False because it cant be extracted into the report. But might just be useful for beter undertanding while maintaining this function.

  • 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 (str) – String with notes about muscle artifacts for report

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.

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, verbose_plots, interactive_matplot, muscle_str_joined)[source]

annotate_muscle_zscore() requires threshold_muscle so define a minimal one here: 5 z-score.

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.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.plot_muscle(m_or_g: str, raw: Raw, scores_muscle: ndarray, threshold_muscle: float, muscle_times: ndarray, high_scores_muscle: ndarray, verbose_plots: bool, annot_muscle: Annotations | None = None, interactive_matplot: bool = False)[source]

Plot the muscle events with the z-scores and the threshold.

Parameters:

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

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

  • scores_muscle (np.ndarray) – The z-scores of the muscle events.

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

  • muscle_times (np.ndarray) – The times of the muscle events.

  • high_scores_muscle (np.ndarray) – The z-scores of the muscle events over the threshold.

  • verbose_plots (bool) – True for showing plot in notebook.

  • annot_muscle (mne.Annotations) – The annotations of the muscle events. Used only for interactive_matplot.

  • interactive_matplot (bool) – Whether to use interactive matplotlib plots or not. Default is False because it cant be extracted into the report.

Returns:

fig_derivs – A list of QC_derivative objects with plotly figures for muscle events.

Return type:

list