apply_aggregate_function
Applies an aggregate function ('mean', 'max', 'min', 'median', 'sum', 'std') to the T or E dimension of the data.
Description
This function applies one of the following aggregate functions to a selected dimension of the imaging data:
- mean (average)
- median
- max
- min
- sum
- std (standard deviation)
Generally, this function is used as an intermediate step of the data processing in order to reduce the data's dimension (i.e. aggregation). For instance, you can use the apply_aggregate_function to apply the "mean" to the Events dimension of a data containing the response amplitude maps to a stimulus which creates the average event-triggered cortical maps.
Input
This function accepts a .dat file with axes Y,X,T, Y,X,T,E or Y,X,E, a single-entry image UMT struct, or a .umt file containing one single-entry image UMT struct. Arrays are not supported.
A .dat input is streamed in X slabs and its output is written slab by slab (Low-RAM mode is always on), so neither the recording nor the result is ever loaded whole. A .umt file is loaded fully into RAM.
The algorithm
When applying an aggregation function over the Time dimension, the resulting data will lack this dimension. This occurs because the aggregation of the data creates a singleton dimension which is automatically eliminated. For instance, if you apply the "mean" across the Time dimension of an image series (Y,X,T) the resulting dataset will have dimensions Y and X. For event-split data (Y,X,T,E), each trial is reduced on its own, giving Y,X,E.
When the function is applied to the Events dimension, the aggregation function is applied across the repetitions of each condition, giving one E slice per condition. For event-split data (Y,X,T,E or Y,X,E) the axes of the output remain the same. A continuous image series (Y,X,T) can also be aggregated along E: the instances listed in events.mat are split out of the recording (with the same trial length as split_data_by_event) and reduced per condition, resulting in Y,X,T,E.
In E aggregation, ignored event instances are excluded and conditions are ordered by first appearance. A condition whose instances are all ignored gives a NaN slice. The .dat output stores no condition labels: its E axis is matched to events.mat, with one slice per condition. An event-split .dat that is already aggregated is refused.
For a UMT input, E aggregation uses the event information frozen in the UMT, and the output carries the aggregated event information.
Output
The output has the same representation as the input. A .dat input gives the aggregated .dat file (aggFcn_applied.dat, saved in the save folder). A UMT input (including one loaded from a .umt file) gives a UMT struct. No separate meta data output is returned.
Parameters
The parameters of this function are the following:
Select the aggregation function to be applied over a dimension of the input data.
This parameter sets the dimension to perform the aggregation function (aggregateFcn) on. The data must contain that axis. In case of the dimension E, the aggregation function will be applied over the repetitions of each event.
Frame rate (in Hertz) of the data, needed only to convert the event times of events.mat into frames when a continuous Y,X,T .dat file is aggregated along E. When the function runs in a pipeline, the value is taken from the data flowing into the step; otherwise it is read from the .dat header.