genCorrelationMatrix

Generate correlation matrix from image time series.

Description

This function creates a Pearson's correlation matrix from ROIs of image time series data. Here, one can create the correlation matrix using either the centroid pixels and/or all the pixels from the ROIs (see parameters for details).

The .dat file is streamed in blocks of image columns, so the recording is never loaded whole into memory. When centroid_vs_centroid is used, only the seed pixels are read.

Input

This function accepts only a .dat file containing a continuous image time series with dimensions Y, X and T. Numeric arrays, .umt files and UMT structs are not supported, and neither are event-split data (Y, X, T and E). The image size must match the image size of the ROI file.

Output

The output of this function is a .umt file (default name corrMatrix.umt) of kind roi containing the entry CorrMatrix with dimensions {'ROI','ROI'}, i.e., an N x N correlation matrix where N is the number of ROIs. The ROI names are stored as labels of both dimensions.

If b_genSPCMaps is set to True, a second file, corrMatrix_SPCMaps.umt, is saved in the Save Folder (see the parameters).

For more information on the data structure of the output files, click here. To load and use them in MATLAB, see Reading and using .umt files in MATLAB.

Note
ROIs whose traces are entirely NaN (e.g., fully masked pixels) are reported as NaN and do not affect the coefficients of the other ROIs. Partially masked traces use a pairwise-complete estimator, which requires the Statistics and Machine Learning Toolbox.

Parameters

This parameter contains the name of the .roi file with the ROIs that will be used by this function to extract the ROI data. A bare file name is resolved inside the Save Folder; a full path can also be given. The file is created in the ROI manager and its image size must match the image size of the input data. See ROI files organization for the file format.

This parameter sets the correlation algorithm to be used by the function. There are three options:

centroid_vs_centroid: calculates the Pearson's correlation between the centroid pixels of all ROIs
centroid_vs_agg: calculates the Pearson's correlation between the centroid pixel of the source ROI and the aggregated value (calculated using the function set in the SpatialAggFcn parameter) of the target ROI
avg_vs_avg: calculates the Pearson's correlation between the spatial pixel average of both the source and the target ROIs

This parameter states the function that will be used to aggregate the ROI data. The selected function will be applied to all pixels inside the ROI.

Note
This parameter is used only when the parameter CorrAlgorithm is set to centroid_vs_agg. Otherwise, it will be ignored.

Set this parameter to True to apply a (truncated) Fisher Z transformation of the Pearson's correlation values. The transformation is also applied to the SPC maps when they are created.

Set this parameter to True to create a file containing the Seed Pixel Correlation Maps for each ROI. The maps are created using the centroid pixel of the source ROI as seed. The maps are stored in an image .umt file named corrMatrix_SPCMaps.umt in the Save Folder, with one Y-X entry per ROI.

The SPC maps (4 × Y × X × number of ROIs bytes) are kept in memory until they are saved.

Note
This parameter is taken into account only when the correlation algorithm is set to centroid_vs_centroid or centroid_vs_agg. Thus, the SPCMaps are not create when the algorithm avg_vs_avg is used.