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. The information about the trials (timestamps, condition name etc) is stored in an events.mat file. 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". Then the trial size is computed as a period before (preEventTime_sec) and after (postEventTime_sec) the event as:
trial_length = preEventTime_sec + postEventTime_sec; Input
This function accepts only image time series (with dimensions Y,X,T) as input.
Output
The output of this function is a 4D numerical array with dimensions E,Y,X,T. Thus, there is an image time series for each trial in E. The trials are organized in chronological order. The list of trial identifiers (i.e. condition index) and condition names are stored in the meta data .mat file associated with the output data in the variables eventID and eventNameList, respectively.
Parameters
Time (in seconds) before the temporal reference point of the trial (i.e. event).
If set to "auto": the function will use the value stored in the variable preEventTime_sec in the input's meta data file. If this information is missing, the function will then calculate the pre AND post-event times as 20 and 80% of the maximum trial size, respectively. In this case, the maximum trial size is calculated as the average time between two consecutive events.
Note
Note that if the "auto" option is selected for this parameter OR for the parameter postEventTime_sec, both parameters will be set automatically. Thus, if preEventTime_sec is set to "auto" and postEventTime_sec is set to a number, the latter will be ignored.
Time (in seconds) after the temporal reference point of the trial (i.e. event).
For the "auto" option, the function behaves the same was as described in the preEventTime_sec parameter (see text box above for details).
Value for padding the data.
In the eventuality that the calculated length of the last trial is longer than the input data, this function will add frames (i.e. padding) with the value set for this parameter.
If set to mean, the padding values will be the temporal average value for the trial. Alternatively, one can type "NaN" to pad with NaNs or give any number to use as padding.