split_data_by_event - Split data by trials
Rearranges an image time series by trials.
Description
This function is used to separate a recording into trials: an E (event instance) axis is appended after the T axis. The information about the trials (timestamps, condition name etc) is stored in an events.mat file, which must exist in the SaveFolder. The creation of the events.mat file is not covered here.
The function uses the onset timestamps (state == 1) of each trial in the events.mat file as a temporal reference of the trial. Here, we refer to this temporal reference as an "event". Each trial starts one baseline period (defined in the events information) before its event, runs until the start of the next trial (the last one runs to the end of the recording), and all trials are then cropped to the length of the shortest one so they stack along E.
Input
This function accepts data with a time (T) axis as its last axis, given as one of:
- a .dat file with a continuous image time series (dimensions Y,X,T);
- a UMT structure, image or non-image, with a single entry that has T as its last axis (for example Y,X,T or ROI,T);
- a .umt file containing such a UMT structure.
Arrays are not supported, and data that are already split by events are rejected. A .dat input is streamed: the continuous recording is never loaded whole and each trial is read and written in slabs (Low-RAM mode is always on).
Output
The output follows the input format.
- .dat input: a .dat file with dimensions Y,X,T,E named dataByEv.dat, written in the SaveFolder. There is an image time series for each trial in E.
- UMT or .umt input: a UMT structure of the same kind, saved as a .umt file, whose entry keeps its name and gets an E axis appended (Y,X,T becomes Y,X,T,E; ROI,T becomes ROI,T,E), together with the event information. Labels of the other axes are kept; T labels are dropped because the trial length differs.
The trials are organized in chronological order, with one slice per event instance of events.mat. The .dat file stores no labels: its E axis is matched to events.mat, which provides the condition of each trial.
For ROI response features, continue with getDataFromROI and then calculateResponseFeatures.
Ignored events
Every event instance of events.mat is saved, including the ones that were removed (ignored), so the E axis maps one to one onto events.mat. Removing an event affects display and processing, not saving: functions that reduce the output over events, such as genAmplitudeMaps, exclude the ignored instances.
Trial length
If trials have unequal lengths, the output is cropped to the shortest trial. UMT inputs are processed in RAM and keep a UMT output.
Parameters
Frame rate (in Hz) of the input data, used to convert the event times into frames. It is provided automatically by the pipeline, by the .dat header or, for UMT inputs, by the entry's meta.FrameRateHz. AcqInfos.mat is not used.