msqms.quality_reference.quality_reference module

msqms.quality_reference.quality_reference module#

Module for calculating the quality reference range for given datasets, including BIDS or RAW datasets.

Summary#

Functions:#

calculate_quality_metrics

Calculate quality metrics for the given MEG file.

convert_to_yaml

Convert the quality bounds DataFrame to a dictionary format suitable for YAML.

is_bids_dataset

Check if the given dataset path is a BIDS dataset.

list_existing_quality_references

List all existing quality reference YAML files in the installed msqms library.

obtain_quality_ranges

Calculate quality bounds (sigma and IQR) based on the dataset metrics.

process_meg_quality

Process the quality metrics for a list of MEG files, compute the quality reference bounds, and save them to a YAML file.

save_quality_reference_to_yaml

Save the quality reference bounds to a YAML file.

update_quality_reference_file

Updates the existing quality reference file for a given device name in the msqms library.

Reference#

msqms.quality_reference.quality_reference.calculate_quality_metrics(meg_filename, data_type=~DATA_TYPE, n_jobs=-1)[source]#

Calculate quality metrics for the given MEG file.

Parameters:

  • meg_filename (str) – Path to the MEG file.

  • data_type (DATA_TYPE) – The data type, either “mag”

  • n_jobs (int) – Number of parallel jobs for computation.

Returns:

A DataFrame containing the computed quality metrics.

Return type:

pd.DataFrame

msqms.quality_reference.quality_reference.obtain_quality_ranges(dataset_metrics_df, sigma=1, k=0.5)[source]#

Calculate quality bounds (sigma and IQR) based on the dataset metrics.

Parameters:

  • dataset_metrics_df (pd.DataFrame) – DataFrame containing the quality metrics.

  • sigma (float, optional) – Number of standard deviations for sigma bounds. Default is 1.

  • k (float, optional) – Scaling factor for IQR bounds. Default is 0.5.

Returns:

The updated dataset metrics DataFrame with calculated quality bounds.

Return type:

pd.DataFrame

msqms.quality_reference.quality_reference.convert_to_yaml(quality_bounds_df)[source]#

Convert the quality bounds DataFrame to a dictionary format suitable for YAML.

This function processes a pandas DataFrame containing various quality metrics for each feature (e.g., sigma_lower_bound, sigma_upper_bound, avg, std, iqr_lower_bound, etc.) and converts it into a dictionary structure that can be serialized into YAML format.

Parameters:

quality_bounds_df (pandas.DataFrame) – A DataFrame containing quality metrics, with columns for each metric (e.g., ‘sigma_lower_bound’, ‘sigma_upper_bound’, ‘avg’, ‘std’, ‘iqr_lower_bound’, ‘iqr_upper_bound’, etc.). The index of the DataFrame represents the features (e.g., channels or other metrics).

Returns:

A dictionary where each key is a column from the DataFrame, and each value is another dictionary containing the following keys: - ‘sigma_range’: A list containing the sigma_lower_bound and sigma_upper_bound values. - ‘mean’: The avg value. - ‘std’: The std value. - ‘iqr_range’: A list containing the iqr_lower_bound and iqr_upper_bound values. - ‘q1’: The first quartile value (q1). - ‘q3’: The third quartile value (q3). - ‘median’: The median value.

Return type:

dict

msqms.quality_reference.quality_reference.save_quality_reference_to_yaml(quality_bounds_df, output_dir, filename='quality_reference.yaml', overwrite=False)[source]#

Save the quality reference bounds to a YAML file.

Parameters:

  • quality_bounds_df (pd.DataFrame) – DataFrame containing the quality bounds for each metric.

  • output_dir (str or Path) – Directory where the quality reference YAML file will be saved.

  • filename (str, optional) – The name of the YAML file. Default is “quality_reference.yaml”.

  • overwrite (bool, optional) – Whether to overwrite the existing file. Default is False, which will not overwrite existing files.

Returns:

The full path to the saved YAML file.

Return type:

str

msqms.quality_reference.quality_reference.is_bids_dataset(dataset_path, file_suffix='.fif')[source]#

Check if the given dataset path is a BIDS dataset.

A BIDS dataset typically includes: - A ‘sub-’ subject folder. - Optionally, a ‘ses-’ session folder. :rtype: bool

  • A ‘meg’ folder containing the actual MEG data files.

  • Required BIDS metadata files: - ‘participants.tsv’ file. - ‘dataset_description.json’ file.

Parameters:

  • dataset_path (Path or str) – The path to the dataset directory to check.

  • file_suffix (str, optional) – The file extension to look for in the data files (default is ‘.fif’).

Returns:

True if the dataset follows BIDS structure, False otherwise.

Return type:

bool

msqms.quality_reference.quality_reference.process_meg_quality(dataset_paths, data_type, file_suffix='.fif', n_jobs=-1, output_dir='quality_ref', update_reference=False, device_name='new_device', overwrite=False)[source]#

Process the quality metrics for a list of MEG files, compute the quality reference bounds, and save them to a YAML file.

Parameters:

  • dataset_paths (list of str) – List of paths to the MEG datasets (either BIDS or Raw format).

  • file_suffix (str) – The suffix of the file to read (e.g., ‘.fif’). Default is ‘.fif’.

  • data_type (DATA_TYPE) – The data type for the quality metrics, e.g., ‘opm’ or ‘squid’.

  • n_jobs (int, optional) – Number of parallel jobs to use for metric computation. Default is -1 (use all available CPUs).

  • output_dir (str, optional) – Directory where the quality reference YAML file will be saved. Default is “quality_ref”.

  • update_reference (bool, optional) – If True, update the reference YAML file in the msqms library. Default is False.

  • device_name (str, optional) – The device name for the reference YAML file. Default is “new_device”.

  • overwrite (bool, optional) – Whether to overwrite the existing file. Default is False, which will not overwrite existing files.

Returns:

Path to the generated quality reference YAML file.

Return type:

str

msqms.quality_reference.quality_reference.update_quality_reference_file(quality_reference_df, device_name, overwrite=False)[source]#

Updates the existing quality reference file for a given device name in the msqms library.

Automatically determines the msqms installation directory.

Parameters:

  • quality_reference_df (pd.DataFrame) – The DataFrame containing the calculated quality reference bounds.

  • device_name (str) – The name of the device, which will be used to name the YAML file (e.g., ‘opm’, ‘squid’).

  • overwrite (bool, optional) – Whether to overwrite the existing file. Default is False, which will not overwrite existing files.

Returns:

The path to the updated quality reference YAML file.

Return type:

str

msqms.quality_reference.quality_reference.list_existing_quality_references()[source]#

List all existing quality reference YAML files in the installed msqms library.

This function searches the ‘quality_reference’ directory within the msqms installation for YAML files following the ‘<device_name>_quality_reference.yaml’ naming pattern.

Returns:

A list where each tuple contains the device name and the corresponding YAML file path.

Return type:

list of tuple

Raises:

ImportError – If the msqms library is not installed or cannot be found.