quality_control module

quality_control module#

@author: Théo Lambert

This module regroups all the functions related to data preprocessing.

class quality_control.OutlierFrameRemoval(interp: str = 'linear', verbose: bool = False)#

Bases: object

Object for removing noisy frames from trials. Adapted from Brunner et al., Nature Protocols 2021, code data_stability.m and image_rejection.m /!designed to work with volumetric data in the order DV.AP.LR

Parameters:

  • interp (str) – Interpolation method. Check the argument ‘kind’ of scipy.interpolate interp1d function for further detail.

  • verbose (bool) – If True, info about the amount of frames rejected for each element will be displayed in the terminal.

get_outliers(data: ~numpy.ndarray) -> (<class 'numpy.ndarray'>, <class 'float'>)#

Method for identifying the outlier frames. A frame is considered outlier when the average value of the frame is above the threshold of 3 times the standard deviation of the frames from the recording.

Parameters:

data (ndarray) – Volumetric data in the order DV.AP.LR + time

Returns:

  • outliers (ndarray of bool) – Ndarray of the same size as data without the time dimension, with True as value if the average frame value is above 3 x std of the distribution.

  • N_rejected (float) – Proportion of rejected frames.

replace_outliers(data: ndarray, outliers: ndarray) → ndarray#

Method for replacing the frames identified as outliers with an interpolation of neighbouring frames.

Parameters:

  • data (ndarray) – Input data, 3D volume in time.

  • outliers (ndarray) – Array of outliers as output by the ‘get_outliers’ method.

Returns:

data – The new data where outlier frames were replace by interpolation.

Return type:

ndarray

class quality_control.ReliabilityMaps(atlas: ndarray, regions_info_file: str, atlas_contours: ndarray | None = None, reliability_threshold: float = 0.6, verbose: bool = False)#

Bases: object

Computes reliability maps before trial averaging

The reliability of a voxel is defined as the proportion of samples averaged for obtaining its value. Example: if there are 10 samples to be averaged, a voxel whose value result from the 10 samples will have a reliability of 100%, while only 7 samples (because the rest is NaN) will have 70% reliability. /!Assumes that the input are registered data, otherwise the averaging will not make sense!

Parameters:

  • atlas (ndarray) – Atlas to be used (volume).

  • regions_info_file (str) – Path to the regions info file.

  • atlas_contours (ndarray) – Contours of the atlas (volume) to be used for the visualization. Purely optional.

  • reliability_threshold (float) – Threshold to determine if a voxel is reliable or not.

  • verbose (bool) – If True, results of the reliability check will be displayed in the terminal.

compute_reliability_map(data: ndarray)#

Computes the reliability map from an individual session and stores it in self.maps.

Parameters:

data (ndarray) – 4D data (registered) from a session.

process(output_folder: str, name: str, plot: bool = True) → ndarray#

Main method to be called to compute the maps, extract the regions below the reliability threshold and get the mask to remove unreliable voxels.

Parameters:

  • output_folder (str) – Folder in which the reliability maps will be saved.

  • name (str) – Name of the element from which the reliability map is computed.

  • plot (bool) – If True, the reliability maps will be displayed on the screen. /!The display will stop the data loading while the display window is open.

Returns:

filter – An array with value True where voxels are below the reliability threshold.

Return type:

ndarray of bool

remove_unreliable(data: ndarray) → ndarray#

Convenience method for setting to nan voxels whose reliability is below the threshold. Must be called after process.

Parameters:

data (ndarray) – Data to be processed (4D).

Returns:

data – Same as input data but with nan values where reliability is below the threshold.

Return type:

ndarray