Plotting functions

All the plots produced by MEQqc are interactive, they can be scrolled through and enlarged.

meg_qc.plotting.universal_plots.Plot_psd_csv(m_or_g: str, f_path: str, method: str)

Plotting Power Spectral Density for all channels based on dtaa from tsv file.

Parameters:

• m_or_g (str) – ‘mag’ or ‘grad’

• f_path (str) – Path to the tsv file with PSD data.

• method (str) – ‘welch’ or ‘multitaper’ or other method

Returns:

QC_derivative object with plotly figure as content

Return type:

QC_derivative

meg_qc.plotting.universal_plots.add_log_buttons(fig: Figure)

Add buttons to switch scale between log and linear. For some reason only swithcing the Y scale works so far.

Parameters:

fig (go.Figure) – The figure to be modified withot buttons

Returns:

fig – The modified figure with the buttons

Return type:

go.Figure

meg_qc.plotting.universal_plots.assign_epoched_std_ptp_to_channels(what_data, chs_by_lobe, df_std_ptp)

Assign std or ptp values of each epoch as list to each channel. This is done for easier plotting when need to plot epochs per channel and also color coded by lobes.

Parameters:

• what_data (str) – ‘peaks’ for peak-to-peak amplitudes or ‘stds’

• chs_by_lobe (dict) – dictionary with channel objects sorted by lobe.

• df_std_ptp (pd.DataFrame) – Data Frame containing std or ptp value for each chnnel and each epoch

Returns:

chs_by_lobe – updated dictionary with channel objects sorted by lobe - with info about std or ptp of epochs.

Return type:

dict

meg_qc.plotting.universal_plots.boxplot_all_time_csv(std_csv_path: str, ch_type: str, what_data: str)

Create representation of calculated std data as a boxplot over the whoe time series, not epoched. (box contains magnetometers or gradiomneters, not together): each dot represents 1 channel (std value over whole data of this channel). Too high/low stds are outliers.

On base of the data from tsv file.

Parameters:

• std_csv_path (str) – Path to the tsv file with std data.

• ch_type (str) – ‘mag’ or ‘grad’

• what_data (str) – ‘peaks’ for peak-to-peak amplitudes or ‘stds’

Returns:

QC_derivative object with plotly figure as content

Return type:

QC_derivative

meg_qc.plotting.universal_plots.boxplot_epoched_xaxis_channels_csv(std_csv_path: str, ch_type: str, what_data: str)

Creates representation of calculated data as multiple boxplots. Used in STD and PtP_manual measurements. Color tagged channels by lobes. One box is one channel, boxes are on x axis. Epoch are inside as dots. Y axis shows the STD/PtP value.

On base of the data from tsv file.

Parameters:

• std_csv_path (str) – Path to the tsv file with std data

• ch_type (str) – Type of the channel: ‘mag’, ‘grad’

• what_data (str) – Type of the data: ‘peaks’ or ‘stds’

Returns:

fig_deriv – derivative containing plotly figure

Return type:

QC_derivative

meg_qc.plotting.universal_plots.boxplot_epoched_xaxis_epochs_csv(std_csv_path: str, ch_type: str, what_data: str)

Represent std of epochs for each channel as box plots, where each box on x axis is 1 epoch. Dots inside the box are channels. On base of the data from tsv file

Process: Each box need to be plotted as a separate trace first. Each channels inside each box has to be plottted as separate trace to allow diffrenet color coding

For each box_representing_epoch:

box trace For each color coded lobe:

For each dot_representing_channel in lobe:

dot trace

Add all traces to plotly figure

Parameters:

• std_csv_path (str) – Path to the tsv file with std data

• ch_type (str) – ‘mag’ or ‘grad’

• what_data (str) – ‘peaks’ for peak-to-peak amplitudes or ‘stds’

Returns:

QC_derivative object with plotly figure as content

Return type:

QC_derivative

meg_qc.plotting.universal_plots.boxplot_epochs(df_mg: DataFrame, ch_type: str, what_data: str, x_axis_boxes: str)

Creates representation of calculated data as multiple boxplots. Used in STD and PtP_manual measurements.

• If x_axis_boxes is ‘channels’, each box represents 1 epoch, each dot is std of 1 channel for this epoch

• If x_axis_boxes is ‘epochs’, each box represents 1 channel, each dot is std of 1 epoch for this channel

Parameters:

• df_mg (pd.DataFrame) – Data frame with std or peak-to-peak values for each channel and epoch. Columns are epochs, rows are channels.

• ch_type (str) – Type of the channel: ‘mag’, ‘grad’

• what_data (str) – Type of the data: ‘peaks’ or ‘stds’

• x_axis_boxes (str) – What to plot as boxplot on x axis: ‘channels’ or ‘epochs’

Returns:

fig_deriv – derivative containing plotly figure

Return type:

QC_derivative

meg_qc.plotting.universal_plots.edit_legend_pie_SNR(noisy_freqs: List, noise_ampl: List, total_amplitude: float, noise_ampl_relative_to_signal: List)

Edit the legend for pie chart of signal to noise ratio.

Parameters:

• noisy_freqs (List) – list of noisy frequencies

• noise_ampl (List) – list of their amplitudes

• total_amplitude (float) – Total amplitude of all frequencies

• noise_ampl_relative_to_signal (List) – list of relative (to entire signal) values of noise freq’s amplitude

Returns:

• noise_and_signal_ampl – list of amplitudes of noise freqs + total signal amplitude

• noise_ampl_relative_to_signal – list of relative noise freqs + amplitude of clean signal

• bands_names – names of freq bands

meg_qc.plotting.universal_plots.figure_x_axis(df, metric)

‘ Get the x axis for the plot based on the metric.

Parameters:

• df (pd.DataFrame) – Data frame with the data.

• metric (str) – The metric for which the x axis is needed. Can be ‘PSD’, ‘ECG’, ‘EOG’, ‘Muscle’, ‘Head’.

Returns:

• freqs (np.ndarray) – Frequencies for the PSD plot.

• time_vec (np.ndarray) – Time vector for the ECG, EOG, Muscle, Head plots.

meg_qc.plotting.universal_plots.get_meg_system(sensors_df)

Get which meg system we work with from the df. Make sure there is only 1 system.

meg_qc.plotting.universal_plots.get_tit_and_unit(m_or_g: str, psd: bool = False)

Return title and unit for a given type of data (magnetometers or gradiometers) and type of plot (psd or not)

Parameters:

• m_or_g (str) – ‘mag’ or ‘grad’

• psd (bool, optional) – True if psd plot, False if not, by default False

Returns:

• m_or_g_tit (str) – ‘Magnetometers’ or ‘Gradiometers’

• unit (str) – ‘T’ or ‘T/m’ or ‘T/Hz’ or ‘T/m / Hz’

meg_qc.plotting.universal_plots.keep_unique_locs(ch_list: List)

Combines channel names that have the same location and returns the unique locations and combined channel names for 3D plotting.

Parameters:

ch_list (List) – A list of channel objects.

Returns:

• new_locations (List) – A list of unique locations.

• new_names (List) – A list of combined channel names.

• new_colors (List) – A list of colors for each unique location.

• new_lobes (List) – A list of lobes for each unique location.

meg_qc.plotting.universal_plots.make_3d_sensors_trace(d3_locs: List, names: List, color: str, textsize: int, legend_category: str = 'channels', symbol: str = 'circle', textposition: str = 'top right')

Makes traces for sensors in 1 lobe, one color. Names and locations are combined if the sonsors have same coordinates. This func already gets them combined from keep_unique_locs function. (Since grads have 2 sensors located in the same spot - need to put their names together to make pretty plot label. Mags are located aproxximately in the same place).

Parameters:

• d3_locs (List) – A list of 3D locations of the sensors.

• names (List) – A list of names of the sensors.

• color (str) – A color of the sensors.

• textsize (int) – A size of the text.

• ch_type (str) – A type of the channels.

• symbol (str) – A symbol of the sensors.

• textposition (str) – A position of the text.

Returns:

trace – A trace of the sensors.

Return type:

plotly.graph_objs._scatter3d.Scatter3d

meg_qc.plotting.universal_plots.make_head_annots_plot(raw: Raw, head_pos: ndarray)

Plot raw data with annotated head movement. Currently not used.

Parameters:

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

• head_pos (np.ndarray) – Head positions and rotations.

Returns:

head_derivs – List of QC derivatives with annotated figures.

Return type:

List

meg_qc.plotting.universal_plots.make_head_pos_plot_mne(raw: Raw, head_pos: ndarray)

Currently not used if we wanna plot solely from csv. This function requires also raw as input and cant be only from csv.

TODO: but we can calculate these inputs earlier and add them to csv as well.

meg_qc.plotting.universal_plots.plot_3d_topomap_std_ptp_csv(sensors_csv_path: str, ch_type: str, what_data: str)

Plot the topomap of STP/PtP values (values take over all time, not epoched). One dot reperesnt 1 channel. Dots are colored from blue (lowest std/ptp) to red (highest). Plots is intereactive 3d with hovering labels. If we got gradiometers - 2 channels usually have same locations - values will be combined. See comemnts in the code below for this case.

Parameters:

• sensors_csv_path (str) – Path to the tsv file with the sensors locations.

• ch_type (str) – Type of the channels: mag or grad

• what_data (str) – ‘peaks’ or ‘stds’

Returns:

qc_derivative – A list of QC_derivative objects containing the plotly figures with the sensor locations.

Return type:

List

meg_qc.plotting.universal_plots.plot_ECG_EOG_channel_csv(f_path)

Plot the ECG channel data and detected peaks

Parameters:

f_path (str) – Path to the tsv file with the derivs to plot

Returns:

ch_deriv – List of QC_derivative objects with plotly figures of the ECG/EOG channels

Return type:

List

meg_qc.plotting.universal_plots.plot_affected_channels_csv(df, artifact_lvl: float, t: ndarray, m_or_g: str, ecg_or_eog: str, title: str, flip_data: bool = 'flip', smoothed: bool = False)

Plot the mean artifact amplitude for all affected (not affected) channels in 1 plot together with the artifact_lvl. Based on the data from tsv file.

Parameters:

• df (pd.DataFrame) – Data frame with the data.

• artifact_lvl (float) – The threshold for the artifact amplitude.

• t (np.ndarray) – Time vector.

• m_or_g (str) – Either ‘mag’ or ‘grad’.

• ecg_or_eog (str) – Either ‘ECG’ or ‘EOG’.

• title (str) – The title of the figure.

• flip_data (bool) – If True, the absolute value of the data will be used for the calculation of the mean artifact amplitude. Default to ‘flip’. ‘flip’ means that the data will be flipped if the peak of the artifact is negative. This is donr to get the same sign of the artifact for all channels, then to get the mean artifact amplitude over all channels and the threshold for the artifact amplitude onbase of this mean And also for the reasons of visualization: the artifact amplitude is always positive.

• smoothed (bool) – Plot smoothed data (true) or nonrmal (false)

Returns:

fig – The plotly figure with the mean artifact amplitude for all affected (not affected) channels in 1 plot together with the artifact_lvl.

Return type:

plotly.graph_objects.Figure

meg_qc.plotting.universal_plots.plot_artif_per_ch_3_groups(f_path: str, m_or_g: str, ecg_or_eog: str, flip_data: bool)

This is the final function. Plot average artifact for each channel, colored by lobe, channels are split into 3 separate plots, based on their correlation with mean_rwave: equal number of channels in each group. Based on the data from tsv file.

Parameters:

• f_path (str) – Path to the tsv file with data.

• m_or_g (str) – Type of the channel: mag or grad

• ecg_or_eog (str) – Type of the artifact: ECG or EOG

• flip_data (bool) – Use True or False, doesnt matter here. It is only passed into the plotting function and influences the threshold presentation. But since treshold is not used in correlation method, this is not used.

Returns:

• artif_per_ch (List) – List of objects of class Avg_artif

• affected_derivs (List) – List of objects of class QC_derivative (plots)

meg_qc.plotting.universal_plots.plot_ch_df_as_lines_by_lobe_csv(f_path: str, metric: str, x_values, m_or_g, df=None)

Plots data from a data frame as lines, each lobe has own color. Data is taken from previously saved tsv file.

Parameters:

• f_path (str) – Path to the csv file with the data to plot.

• metric (str) – The metric of the data to plot: ‘psd’, ‘ecg’, ‘eog’, ‘smoothed_ecg’, ‘smoothed_eog’.

• x_values (List) – List of x values for the plot.

• m_or_g (str) – ‘mag’ or ‘grad’.

Returns:

fig – Plotly figure.

Return type:

plotly.graph_objects.Figure

meg_qc.plotting.universal_plots.plot_correlation_csv(f_path: str, ecg_or_eog: str, m_or_g: str)

Plot correlation coefficient and p-value between mean R wave and each channel in artif_per_ch. Based on the data from tsv file.

Parameters:

• f_path (str) – Path to the tsv file with data.

• ecg_or_eog (str) – Either ‘ECG’ or ‘EOG’.

• m_or_g (str) – Either ‘mag’ or ‘grad’.

Returns:

corr_derivs – List with 1 QC_derivative instance: Figure with correlation coefficient and p-value between mean R wave and each channel in artif_per_ch.

Return type:

List

meg_qc.plotting.universal_plots.plot_ecg_eog_mne(channels: dict, ecg_epochs: Epochs, m_or_g: str, tmin: float, tmax: float)

Plot ECG/EOG artifact with topomap and average over epochs (MNE plots based on matplotlib)

NOT USED NOW

Parameters:

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

• ecg_epochs (mne.Epochs) – ECG/EOG epochs.

• m_or_g (str) – String ‘mag’ or ‘grad’ depending on the channel type.

• tmin (float) – Start time of the epoch.

• tmax (float) – End time of the epoch.

Returns:

mne_ecg_derivs – List of QC_derivative objects with MNE plots.

Return type:

List

meg_qc.plotting.universal_plots.plot_head_pos_csv(f_path: str)

Plot positions and rotations of the head. On base of data from tsv file.

Parameters:

f_path (str) – Path to a file with data.

Returns:

• head_derivs (List) – List of QC_derivative objects containing figures with head positions and rotations.

• head_pos_baselined (np.ndarray) – Head positions and rotations starting from 0 instead of the mne detected starting point. Can be used for plotting.

meg_qc.plotting.universal_plots.plot_mean_rwave_csv(f_path: str, ecg_or_eog: str)

Plon mean rwave(ECG) or mean blink (EOG) from data in CSV file.

Parameters:

• f_path (str) – Path to csv file

• ecg_or_eog (str) – plot ECG or EOG data

Returns:

fig_derivs – list with one QC_derivative object, which contains the plot.

Return type:

List

meg_qc.plotting.universal_plots.plot_mean_rwave_shifted(mean_rwave_shifted: ndarray, mean_rwave: ndarray, ecg_or_eog: str, tmin: float, tmax: float)

Only for demonstartion while running the pipeline. Dpesnt go into final report.

Plots the mean ECG wave and the mean ECG wave shifted to align with the ECG artifacts found on meg channels. Probably will not be included into the report. Just for algorythm demosntration. The already shifted mean ECG wave is plotted in the report.

Parameters:

• mean_rwave_shifted (np.ndarray) – The mean ECG wave shifted to align with the ECG artifacts found on meg channels.

• mean_rwave (np.ndarray) – The mean ECG wave, not shifted, original.

• ecg_or_eog (str) – ‘ECG’ or ‘EOG’

• tmin (float) – The start time of the epoch.

• tmax (float) – The end time of the epoch.

Returns:

fig_derivs – list with one QC_derivative object, which contains the plot. (in case want to input intot he report)

Return type:

List

meg_qc.plotting.universal_plots.plot_muscle_annotations_mne(raw: Raw, m_or_g: str, annot_muscle: Annotations | None = None, interactive_matplot: bool = False)

Currently not used since cant be added into HTML report

meg_qc.plotting.universal_plots.plot_muscle_csv(f_path: str)

Plot the muscle events with the z-scores and the threshold. On base of the data from tsv file.

Parameters:

f_path (str) – Path to tsv file with data.

Returns:

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

Return type:

List

meg_qc.plotting.universal_plots.plot_pie_chart_freq_csv(tsv_pie_path: str, m_or_g: str, noise_or_waves: str)

Plot pie chart representation of relative amplitude of each frequency band over the entire times series of mags or grads, not separated by individual channels.

Parameters:

• tsv_pie_path (str) – Path to the tsv file with pie chart data

• m_or_g (str) – ‘mag’ or ‘grad’

• noise_or_waves (str) – do we plot SNR or brain waves percentage (alpha, beta, etc)

Returns:

QC_derivative object with plotly figure as content

Return type:

QC_derivative

meg_qc.plotting.universal_plots.plot_sensors_3d_csv(sensors_csv_path: str)

Plots the 3D locations of the sensors in the raw file. Plot both mags and grads (if both present) in 1 figure. Can turn mags/grads visialisation on and off. Separete channels into brain areas by color coding.

Plot is made on base of the tsv file with sensors locations.

Parameters:

sensors_csv_path (str) – Path to the tsv file with the sensors locations.

Returns:

qc_derivative – A list of QC_derivative objects containing the plotly figures with the sensor locations.

Return type:

List

meg_qc.plotting.universal_plots.plot_stim_csv(f_path: str) → List[QC_derivative]

Plot stimulus channels.

Parameters:

f_path (str) – Path to the tsv file with PSD data.

Returns:

List of QC_derivative objects with plotly figures as content

Return type:

List[QC_derivative]

meg_qc.plotting.universal_plots.plot_stim_csv_colored_leveled(f_path: str) → List[QC_derivative]

Plot stimulus channels.

Parameters:

f_path (str) – Path to the tsv file with PSD data.

Returns:

List of QC_derivative objects with plotly figures as content

Return type:

List[QC_derivative]

meg_qc.plotting.universal_plots.plot_stim_csv_simple(f_path: str) → List[QC_derivative]

Plot stimulus channels.

Parameters:

f_path (str) – Path to the tsv file with PSD data.

Returns:

List of QC_derivative objects with plotly figures as content

Return type:

List[QC_derivative]

meg_qc.plotting.universal_plots.plot_topomap_std_ptp_csv(std_csv_path: str, ch_type: str, what_data: str)

Plot STD using mne.viz.plot_topomap(data, pos, *, ch_type=’mag’, sensors=True, names=None)

For every channel we take STD/PtP value and plot as topomap

meg_qc.plotting.universal_plots.split_affected_into_3_groups_csv(df: DataFrame, metric: str, split_by: str = 'similarity_score')

Collect artif_per_ch into 3 lists - for plotting: - a third of all channels that are the most correlated with mean_rwave - a third of all channels that are the least correlated with mean_rwave - a third of all channels that are in the middle of the correlation with mean_rwave

Parameters:

• df (pd.DataFrame) – Data frame with the data.

• metric (str) – The metric for which the x axis is needed. Can be ‘ECG’ or ‘EOG’.

• split_by (str) – The metric by which the channels will be split. Can be ‘corr_coeff’ or ‘similarity_score’.

Returns:

• artif_per_ch (List) – List of objects of class Avg_artif, ranked by correlation coefficient

• most_correlated (List) – List of objects of class Avg_artif that are the most correlated with mean_rwave

• least_correlated (List) – List of objects of class Avg_artif that are the least correlated with mean_rwave

• middle_correlated (List) – List of objects of class Avg_artif that are in the middle of the correlation with mean_rwave

• corr_val_of_last_least_correlated (float) – Correlation value of the last channel in the list of the least correlated channels

• corr_val_of_last_middle_correlated (float) – Correlation value of the last channel in the list of the middle correlated channels

• corr_val_of_last_most_correlated (float) – Correlation value of the last channel in the list of the most correlated channels

meg_qc.plotting.universal_plots.switch_names_on_off(fig: Figure)

Switches between showing channel names when hovering and always showing channel names.

Parameters:

fig (go.Figure) – The figure to be modified.

Returns:

fig – The modified figure.

Return type:

go.Figure