utils module

@author: Théo Lambert

This module regroups all the utility functions of generic use.

class utils.Formatter(atlas, regions_acr, regions_nb)

Bases: object

Object for dynamically displaying the regions of the atlas under the cursor in the plots.

Parameters:

• atlas (ndarray) – The 3D atlas volume.

• regions_acr (array) – Array containing the acronyms of the regions included in the atlas.

• regions_nb (array) – Array containing the regions’ numbers / IDs included in the atlas.

utils.average_files(filelist: List[str]) → ndarray

utils.convert_projections_to_df(projections: ~numpy.ndarray, regions_acr: ~numpy.array, hemispheres: ~numpy.array, start_at: int = 4) -> (<class 'pandas.core.frame.DataFrame'>, <class 'dict'>)

Utility function for converting the projections from the ‘projection’ function into a pandas dataframe. It allows convenient and fancy display.

Parameters:

• projections (ndarray) – First output of the ‘projection’ function, ie a 2D matrix with rows as regions and columns as timepoints.

• regions_acr (array) – Array providing all the regions acronyms.

• hemispheres (array) – Array providing the hemispheres (-1 for left, 1 for right)

• start_at (int) – If some early frames need to be removed because of noise. Standard value is 4.

Returns:

• df (dataframe) – A dataframe structure containing all the data from projections.

• info (dict) – A dictionary with useful information for setting the scaling displays.

utils.convert_to_zscore(d, baseline)

utils.extract_info_from_region_file(regions_info_file: str) -> (<built-in function array>, <built-in function array>, <built-in function array>)

Utility function for extracting region numbrs, acronyms, and anatomical groups from the region info file.

Parameters:

regions_info_file (str) – Path to the regions_info_file.

Returns:

• All output are ordered in the same way.

• regions_nb (array) – 1D array containing the regions’ numbers

• regions_acr (array) – Same but for the acronyms.

• groups_acr (array) – Same but for the anatomical group.

utils.generate_color_coded_atlas_flat(atlas_resolution: int, ext: str, cmap=None)

Function for displaying an atlas color-coded depending on the major anatomical structures.

Parameters:

• atlas_resolution (int) – The resolution of the atlas to be loaded.

• ext (str) – The extension of the atlas to be loaded.

• cmap (None | list of colors) – List of colors for the anatomical structures.

utils.get_atlas_and_info_paths(atlas_resolution, ext)

Utility function to get the path to the atlases and info files from the library.

Parameters:

• atlas_resolution (int) – Resolution of the atlas to use, in µm.

• ext (str) – Extension of the atlas to be used.

utils.get_atlas_mask_from_regions(atlas, regions_nb, regions_acr, acr_list)

Utility function to get a volume matching the atlas size with ones where voxels belong to the selected regions and zeros elesewhere.

Parameters:

• atlas (array) – Resolution of the atlas to use, in µm.

• regions_acr (array) – Array containing the acronyms of the regions included in the atlas.

• regions_nb (array) – Array containing the regions’ numbers / IDs included in the atlas.

• acr_list (list of tuples) – List containing the acronyms and associated hemispheres of the selected regions. Ex: [(‘SCs’, ‘L’), (‘VISp’, ‘R’)].

utils.get_regions_from_groups(group: str, hemisphere: str, regions_acr: array, groups_acr: array)

Utility function for converting an anatomical group into a list of regions included in that group in the format expected by the clustering code.

Parameters:

• group (str) – Acronym of the anatomical group

• hemisphere (str) – ‘L’ or ‘R’ respectively for left and right hemispheres, or ‘LR’ for both.

• regions_acr (array) – 1D array containing the regions’ acronyms.

• groups_acr (array) – 1D array containing the anatomical groups’ acronyms.

Returns:

res – List of tuples in the format (region acronym, hemisphere ‘L’ or ‘R’)

Return type:

list

utils.get_regions_from_hemisphere(hemisphere: str, regions_acr: array, groups_acr: array)

Utility function for converting a hemisphere group into a list of regions included in that group in the format expected by the clustering code.

Parameters:

• group (str) – Acronym of the anatomical group

• hemisphere (str) – ‘L’ or ‘R’ respectively for left and right hemispheres, or ‘LR’ for both.

• regions_acr (array) – 1D array containing the regions’ acronyms.

• groups_acr (array) – 1D array containing the anatomical groups’ acronyms.

Returns:

res – List of tuples in the format (region acronym, hemisphere ‘L’ or ‘R’)

Return type:

list

utils.load_atlas(atlas_path: str) → ndarray

Utility function for loading the atlas from the given path. Left hemisphere will be identified by negative values.

Parameters:

atlas_path (str) – Path to the atlas file.

Returns:

atlas – The atlas volume (3D).

Return type:

ndarray

utils.load_object(path)

Utility function to load an object, for example a clustering object. Rely on pickle.

Parameters:

path (string) – The path where the object is saved.

Returns:

The loaded object.

Return type:

obj

utils.name_from_path(path)

Simple utility function for getting the name from the path of loaded_data.

Parameters:

path (str) – Path from which the name is to be extracted.

Returns:

The extracted name.

Return type:

str

utils.post_data_loading_average(source_dir: str, level_avg: str)

A FINIR CORRECTEMNT, LES FICHIERS GENERES SONT PRIS EN COMPTE LORS DE OS.WALK

utils.post_data_loading_iterator(source_dir: str, expgroup_ID: str | List[str] | None = None, subject_ID: str | List[str] | None = None, session_ID: str | List[str] | None = None, stim_ID: str | List[str] | None = None) → List[str]

Function for selecting data once the data loading has been done.

Parameters:

• source_dir (str) – Path where the data structure was created during the data loading. Usually param <root_folder>/loaded_data/<experiment_ID>. Check parameters from data_loading.py to see what these correspond to.

• expgroup_ID (list of str | str | None) –

  • if string, the specified experimental group will be selected.

  • if list of string, the experimental groups in the list will be selected.

  • if None: all experimental groups available will be selected.

• subjects_ID (list of str | string | None) – Same as expgroup_ID but for subjects IDs.

• session_ID (list of str | string | None) – Same as expgroup_ID but for sessions IDs.

• stim_ID (list of str | string | None) – Same as expgroup_ID but for stimuli IDs.

Returns:

filelist – Lists containing the paths to the selected data.

Return type:

list of str

utils.projection(data: ~numpy.ndarray, atlas: ~numpy.ndarray, regions_nb: ~numpy.array, regions_acr: ~numpy.array, groups_acr: ~numpy.array, regions_to_exclude: list = [], reduction: str = 'median', use_allen: bool = True, start_at: int = 4) -> (<class 'numpy.ndarray'>, <class 'numpy.ndarray'>, <class 'numpy.ndarray'>, <class 'numpy.ndarray'>)

Convert a 4D input data (volume in time) into a 2D matrix in which each line corresponds to the reduced time trace associated with a given region of the atlas.

Parameters:

• data (ndarray) – 4D (volume in time) matrices containing the fus signal variations per voxel.

• atlas (ndarray) – 3D volume of the same size as data (without temporal) where each voxel value correspond to its number in the Allen CCF v3 ontology.

• regions_nb (ndarray) – Array containing all the region numbers in the atlas used.

• regions_acr (ndarray) – Array containing all the region acronyms in the atlas used (same order as in regions_nb).

• groups_acr (ndarray) – Array containing all the anatomical groups acronyms associated with each region acronym (same order as in regions_nb).

• regions_to_exclude (list) – List of regions to be excluded during the projection. Default correspond to voxels only belonging to a major anatomical groups, eg boundaries between cortical areas.

• reduction (str) – Selection of the reduction method to average the data in each region, either ‘mean’ or ‘median’.

• use_allen (bool) – Set to True if you use the Allen brain atlas, otherwise False. If True, some specific regions will be automatically removed.

• use_allen – Set to True if you use the Allen brain atlas, otherwise False. If True, some specific regions will be automatically removed.

• start_at (int) – To remove the first frames of the recording if required. Usually 4 first frames are removed since the acquisition processing pipelines is fully operational after these 4 frames.

Returns:

• All output are ordered the same way.

• proj – Temporal traces resulting from the projection.

• acr – Array containing the regions acronyms associated with the traces.

• groups – Array containing the groups acronyms associated with the traces.

• hemi – Array containing the hemisphere (-1 for left, 1 for right) associated with the traces.

utils.reshape_volume_for_display(volume: ndarray, volume_boundaries: array | None = None, ncols: int = 8, return_for_clustering=False) → ndarray

Utility function for creating flattened 3D volumes towards displaying them as a mosaique of 2D images, where each value is the cluster attribution of the associated voxel.

Parameters:

• volume (ndarray) – The 3D volume to be flattened.

• volume_boundaries (array | None) – For setting custom boundaries, if None the dimensionses of the whole volume will be taken.

• ncols (int) – Number of columns to be used for the flattening.

• return_for_clustering (bool) – If True, returns extra values useful for the colormap display in the clustering object.

Returns:

res – A 2D array with values being either int (cluster ID) or tuple (color associated with cluster ID) depeding on the ‘apply_colormap’ parameter.

Return type:

ndarray

utils.save_object(path, obj)

Utility function to save an object, for example a clustering object. Rely on pickle.

Parameters:

• path (string) – The path where the object should be saved. The extension of the file must be ‘.p’

• obj (object) – The object to be saved.

utils.single_voxels_in_region(data: array, atlas: array, regions_nb: array, regions_acr: array, region: int, show: bool = False)

Utility function for diplaying or returning the temporal traces of all single voxels within a region.

Parameters:

• data (ndarray) – 4D volume (space and time) containing the time traces of each voxel.

• atlas (array) – 3D volume of the atlas, where each value is a number indicating to which region a voxel belongs.

• regions_nb (array) – Array providing all the regions number.

• regions_acr (array) – Array providing all the regions acronyms. Same order as regions_nb.

• region (int) – The region to be displayed.

• show (bool) – If True, plot the single voxel temporal traces, else return them.

Returns:

single_voxels – 2D array whose first dim contains single voxels and second dim the temporal traces

Return type:

ndarray