getDataFromROI
Extracts data from ROIs.
Description
This function extracts and aggregates data from ROIs. The function uses the ROIs stored in a .roi file to extract the data from imaging datasets created in umIT and returns the result as an ROI-kind UMT. Additionally, this function applies an aggregation function (i.e., mean, max, min, median, mode, sum or standard deviation) to summarize the pixel values from an ROI.
A .dat file is streamed: only the image columns that contain ROI pixels are read, in blocks of consecutive frames, and each block is aggregated as soon as it is read. The recording is never loaded whole into memory.
To calculate event response features, use the workflow split_data_by_event → getDataFromROI with SpatialAggFcn other than 'none' → calculateResponseFeatures.
Input
This function accepts imaging data containing the dimensions Y and X, in one of the following forms:
- a .dat file with dimensions Y-X, Y-X-T, Y-X-E, Y-X-F or Y-X-T-E;
- an image-kind UMT whose entry uses one of those layouts, or a .umt file containing such a UMT.
Numeric arrays are not supported.
Event-split .dat files
An event-split .dat file (e.g., the output of split_data_by_event) stores no event labels. The event information is taken from the events.mat file of the Save Folder: one slice per event instance or one slice per condition. If the E dimension matches neither, the slices are treated as a single condition and a warning is issued.
Output
The output of this function is a .umt file (default name ROI_data.umt) of kind roi containing the data separated by ROI. The output dimensions depend on SpatialAggFcn:
- with aggregation: ROI x ..., e.g., {'ROI','T'} for a Y-X-T input;
- with none: ROI x Pixel x ..., e.g., {'ROI','Pixel','T'}.
where "..." stands for the non-spatial dimensions of the input (T, E and/or F). Labels of the preserved dimensions of a UMT input (e.g., F) are carried to the output. Event information and the frame rate of a UMT input are carried to the output unchanged; continuous inputs produce no event information.
For more information on the data structure of the output file, click here. To load and use it in MATLAB, see Reading and using .umt files in MATLAB.
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. See ROI files organization for the file format.
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. Thus, this operation will replace the Y and X dimensions by an ROI dimension. For instance, if the input data has dimensions Y, X and T, the output data will have dimensions ROI x T.
Note
Select none to extract the ROI data without aggregation. Here, the output data will have dimensions ROI x Pixel x T, where the Pixel dimension is as long as the largest ROI; ROIs with fewer pixels are padded with NaN. The option none is not available for inputs with an F dimension (e.g., Y-X-F maps).
Note
A Y-X-F input aggregated with any function other than none produces {'ROI','F'}: one value per ROI and per F entry (e.g., amplitude and phase of a retinotopy map).
Frame rate of the input data in Hz, recorded in the metadata of the output entry. When the function runs in a pipeline, the value is taken from the data automatically; otherwise it is read from the .dat header.