quantification module

@author: Théo Lambert

This module regroups all the functions related to spatial and temporal quantification.

class quantification.SpatialQuantification(data_dict: Dict[str, ndarray], atlas_path: str, regions_info_path: str)

Bases: object

Object for performing basic spatial quantification from the output of the correlation and single voxel clustering analyses based on the atlas. Assumes that the data are registered. Example of input include the Z-maps and the cluster maps. Each unique value in the input will be considered as the identifier of a set.

Parameters:

• data_dict (dict of ndarray) – Dictionary containing 3D volumes with int-like values.

• atlas_path (str) – Path to the atlas volume.

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

print_quantification_per_hemisphere(data_name: None | str = None)

Method for printing the proportion of voxels per set in each hemisphere.

Parameters:

data_name (str | None) – Either the name of the specific data to be displayed or None. If None, all available data will be printed.

print_quantification_per_set(data_name: None | str = None, set_id: int | None = None, normalization: str = 'brainwide')

Method for printing the proportion of voxels per set in each anatomical structure.

Parameters:

• data_name (str | None) – Either the name of the specific data to be displayed or None. If None, all available data will be printed.

• set_id (int | None) – Either the id of the set to be displayed or None. If None, quantification for all sets will be printed.

• normalization (str) – Either ‘hemisphere’ or ‘brainwide’

print_quantification_region(region_acr: str, hemisphere: str, data_name: None | str = None, set_id: int | None = None)

Method for printing the quantification associated with a specific region.

Parameters:

• region_acr (str) – Acronym of the region to be printed.

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

• data_name (str | None) – Either the name of the specific data to be displayed. If None, all available data will be printed.

• set_id (int | None) – Either the value defining a specific set, e.g. 1 for cluster 1. If None, all the sets will be printed.

print_quantification_structure(acr: str, hemisphere: str, data_name: None | str = None, ignore_non_selected: bool = False)

Method for printing the quantification associated with a specific anatomical structure.

Parameters:

• acr (str) – Acronym of the group to be printed.

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

• data_name (str | None) – Either the name of the specific data to be displayed or None. If None, all available data will be printed.

• ignore_non_selected (bool) – To set to True if used with clustering, to remove voxels that were not included in the clustering process if a subset of regions was selected.

quantification_per_region()

Fill and store in the object two dataframes containing for each region all the available info and quantification for each set. Called during initialization.

class quantification.SpatialTransitionAnalysis(maps, mode, mode_params, atlas_path, regions_info_path, n_clusters, cmap=None)

Bases: object

Object for spatial transition analysis, ie investigating how voxels behave in terms of clusters changes between conditions, at different spatial scales. Also works with the Z-maps.

Parameters:

• maps (dict of array) – Dictionary containing 3D volumes with int-like values.

• mode (str) –

  Either ‘multiregion’, ‘structure’, ‘hemisphere’. Determines which voxels are included in the process:

  • hemisphere: all voxels in a given or both hemispheres

  • structure: all voxels belonging to a list of structures

  • multiregion: all voxels belonging to a list of regions

• mode_params (tuple | list | str) –

  Parameters associated with the selected mode:

  • if ‘hemisphere’: ‘L’ or ‘R’ respectively for left and right hemispheres, or ‘LR’ for both.

  • if ‘structure’: a tuple or list of tuples with format (<structure>, <hemisphere>).

  • if ‘multiregion’: a tuple or list of tuples with format (<region acronym>, <hemisphere>).

• atlas_path (str) – Path to the file containing the atlas volume.

• regions_info_path (str) – Text file listing all the regions included in the atlas.

• n_clusters (int) – Number of clusters present in the maps.

• cmap (None | str | list) – Either a list of RGBA values or the name of a colormap available in pyplot.

get_cluster_transitions(cluster_maps, cluster_switches, mask_map=True, show=True)

Method for highlighting the voxels following a specific transition pattern. For example, voxels switching from cluster 1 in condition A to cluster 2 in condition B and from cluster 1 in condition C to cluster 3 in condition D.

Parameters:

• cluster_maps (list of tuples) – List of tuples containing the pairs of cluster maps, for example (condition A, condition B).

• cluster_switches (list of tuples) – List of tuples containing the associated cluster transitions, for example (1, 2). Must be the same length as cluster_maps.

• mask_map (bool) – Whether or not to mask voxels outside of the area defined by self.mode.

• show (bool) – Whether or not to display the resulting transitions map.

Returns:

map_diff – The resulting transition map, with 1s indicating the voxels following the switching pattern.

Return type:

ndarray

get_quantif_regions_from_transitions(transition_map, threshold, plot=True, title='', prop='region')

Method for getting proportions of voxels in anatomical regions out of a transition map.

Parameters:

• transition_map (ndarray) – Transition map as output by the method ‘get_cluster_transitions’ .

• threshold (float) – Threshold on the proportion (either with normalization ‘region’ or ‘total’, see ‘prop’) to determine which regions are included. Should be between 0 and 1.

• plot (bool) – Whether or not to plot the quantification as a bar plot. If False, quantifications will be displayed in the terminal. First and second values corresponds to the ‘region’ and ‘total’ normalizations, respectively. See argument ‘prop’ for further detail.

• title (string) – The title of the plot.

• prop (str) – Either ‘region’ or ‘total’. If ‘region’, the number of voxels in the region will be normalized with respect to the size of the region. If ‘total’, the total number of voxels with value 1 in the transition map will be used for normalization.

merge_transition_maps(maps, legends, cmap=None)

Function for merging multiple transition maps and displaying the outcome. Each map will have a separate color.

Parameters:

• maps (list of array) – A list of maps, where each map is an output of the function ‘get_cluster_transitions’.

• legends (list of string) – The label associated with each map.

• cmap (None | list) – Either None or a list of RGB values. If None, a default colormap will be used.

sankey_from_maps(reduce=True)

Method for generating a Sankey plot allowing for the visualization of cluster transitions across cluster maps.

Parameters:

reduce (bool) – If True, reduces the flows in the Sankey plot, ie voxels switching from same source to same target will be grouped as a single flow.

class quantification.TemporalQuantification(data_dict: Dict[str, array], sampling_rate: float)

Bases: object

Object for performing basic temporal quantification from the output of the region averaging and single voxel clustering analyses. Example of input include the temporal traces of individual regions of the atlas or clusters.

Parameters:

• data_dict (dict of array) – Dictionary of 1D temporal signals.

• sampling_rate (float) – Temporal sampling rate of the signals.

compute_metrics()

Method for computing the metrics from each signal and storing them in a dataframe. Called during initialization. Element refers to a mouse, session, etc. Key refers to a region, a cluster ID, etc.

plot_metric(metric: str, scale: None | Tuple[float, float] = None, colors=None)

Convenience method for plotting a given metric.

Parameters:

• metric (str) – Name of the metric to be plotted. Available metrics are ‘Peak amplitude’, ‘AUC’, ‘Time to peak (s)’, ‘FWHM (s)’, ‘Time to half max (s)’

• scale (tuple of float | None) – Min and max scales for the display (arguments vmin / vmax from plt.imshow). If None, auto scale will be used.

print_metric(metric)

Convenience method for printing a given metric.

Parameters:

metric (str) – Name of the metric to be printed.

quantification.compute_amplitude(signal: array, time_stim: None | Iterable)

Utility function for computing the amplitude of an input signal.

Parameters:

• signal (array) – 1D array, temporal signal.

• time_stim (None | iterable)

Returns:

amp – Computed amplitude of the input signal.

Return type:

float

quantification.compute_auc(signal: array, sr: float = 5)

Utility function for computing the area under the curve (AUC) of an input signal.

Parameters:

• signal (array) – 1D array, temporal signal.

• sr (float) – Temporal sampling rate of the signal.

Returns:

auc – Computed AUC of the input signal.

Return type:

float

quantification.compute_full_width_half_max(signal: array, sr: float = 5)

Utility function for computing the full width at half maximum (FWHM) and time to half maximum (THM) of an input signal.

Parameters:

• signal (array) – 1D array, temporal signal.

• sr (float) – Temporal sampling rate of the signal.

Returns:

• fwhm (float) – Computed FWHM of the input signal.

• thm (float) – Computed THM of the input signal.

quantification.compute_time_to_peak(signal: array, sr: float = 5)

Utility function for computing the time to peak (TTP) of an input signal.

Parameters:

• signal (array) – 1D array, temporal signal.

• sr (float) – Temporal sampling rate of the signal.

Returns:

ttp – Computed TTP of the input signal.

Return type:

float