- .rst
Contents
@author: Théo Lambert
This module regroups all the utility functions of generic use.
- class utils.Formatter(atlas, regions_acr, regions_nb)#
Bases:
objectObject 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)#
- 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.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.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.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
Contents
