label_trial: Label Trial Number
In jashu/itrak: Tools for processing eye-tracking data

Description Usage Arguments Details Value

Label individual time series according to trial sequence.

1	label_trial(sample, marker = NULL, event = NULL)

`sample`	Index number for the time series that resets with the start of a new trial.
`marker`	Vector containing markers of trial events.
`event`	Label in `marker` that is uniquely associated with valid trials. If this is a character string, it must be enclosed in quotation marks.

If your time series vector contains a larger time series that represents a sequence of smaller time series (as would occur in a multi-trial experiment), it is often useful to explicitly represent this meta-sequence in statistical models (e.g., as trial effects). However, your time series data may not represent this variable explicitly, in which case you may need to infer the trial number from other variables. At minimum, your data should contain a sample index, i.e., an integer sequence that resets with each trial. label_trial uses this information to construct a trial label.

label_trial detects the start of a new trial using the most generic rule possible–when the sample index decreases instead of increasing, increment the trial number–because sometimes this may be the only reliable indicator of trial number that you have. But note that there are more computationally efficient solutions if you know that all of your trials have an equal number of samples (in which case it will be faster to use rep(1:<number of trials>, each = <samples per trial>) or if trials can be uniquely identified using another variable or combination of variables as a key (in which case it will be faster to label the sequence of keys and then join this value to your time-series data).

Optionally, an event-onset marker can be included that indicates that a time series belongs to a valid trial. If this onset marker is not detected for a time series, then label_trial will not include this series in the trial count and will return a label of NA. This can then be used as a flag for removing extraneous measurements, such as pupil readings taken during a drift check or calibration procedure.

An integer vector of trial numbers reflecting the temporal order of multiple time series.

jashu/itrak documentation built on May 9, 2020, 1:57 p.m.