correlation_analysis module

correlation_analysis module#

@author: Théo Lambert

This module regroups all the functions related to correlation analysis.

class correlation_analysis.CorrelationAnalysis(data_paths: str | List[str], correlation_pattern: List[tuple] | array | Dict[str, array], n_samples: None | int | Dict[str, int] = None, significance_threshold: float = 0.05)#

Bases: object

Object handling the generation and display of correlation maps and Z-maps.

Parameters:

  • data_paths (str | list of str) – Paths to the data to be analyzed.

  • correlation_pattern (list of tuple | array | dict of array) –

    • if list of tuple, first and second elements of each tuple are respectively beginning and end of a square pulse.

    • if np.array, this array should be the same size as the temporal dimension of data. This array will be correlated with each data. Options 1 and 2 assume that all data have same number of frames.

    • if dict containing np.arrays, keys should match the data names (check the info file, key are before ‘n_samples’) and arrays should have the same length as their associated data.

  • n_samples (None | int | dict of int) –

    Number of samples used for computing the data reduction, if applicable (if not, set to None).

    • if None, no Z-map will be computed.

    • if int, assumes that all data have the same number of samples

    • if dict, keys should match the data names

  • significance_threshold (float) – The statistical significance threshold used for the computation of the Z-maps. Either 0.05, 0.01 or 0.001.

compute_corr_map(data_path: str, corr_pattern: array, n_samples: int, plot: bool = True, registered: bool = False, atlas_path: None | str = None, regions_info_path: None | str = None)#

Function for computing the correlation map for a given data. The loading is handled in the function, as well as the display of the maps if requested.

Parameters:

  • data_path (str) – Path to the data to be loaded.

  • corr_pattern (array) – Correlation pattern to be correlated with the data.

  • n_samples (int | None) – Number of samples used for the reduction of data (e.g., number of trials x number of sessions). Used to compute the Z-map. Note: if None, no Z-map will be computed.

  • plot (bool) – If True, correlation and Z-maps (if applicable) will be displayed on a window.

  • registered (bool) – Whether or not the data was registered. Only required to display the atlas overlay.

  • atlas_path (str) – Path to the atlas the data has been registered to. Only necessary if registered is True.

  • regions_info_path (str) – Path to the region info path. Only necessary if registered is True.

Returns:

  • corr_map (ndarray) – Ndarray containing the correlation map.

  • z_map (ndarray) – Ndarray containing the Z-map computed using the number of samples and the significance threshold.

init_pattern(correlation_pattern: List[tuple] | array | Dict[str, array])#

Function for creating the correlation pattern based on the selected mode and parameters. Automatically called during initialization of the object.

Parameters:

correlation_pattern (list of tuple | array | dict of array) – See description in the init function.

process(plot: bool = True, return_map: str = 'zmap', registered: bool = False, atlas_path: None | str = None, regions_info_path: None | str = None)#

Main function computing the correlation maps for each of the selected data.

Parameters:

  • plot (bool) – If True, all the computed correlation maps and Z-maps (if computed) will be displayed in separate windows.

  • return_map (str) – Either ‘both’, ‘zmap’ or ‘cmap’. Determine what will be output by the function.

  • DOC (MISSING)

Returns:

res – A dictionary with keys being the names of the selected data, and values a tuple whose 1st element is the correlation map and the 2nd the Z-map.

Return type:

dict