pspm_pupil_pp
Description
pspm_pupil_pp preprocesses pupil diameter signals given in any unit of measurement, with a possibility of combining left/right pupil.
It performs the steps described in [1]. This function uses a modified version of [2]. The modified version with a list of changes from the original is shipped with PsPM under pupil-size directory.
Pupil preprocessing is performed in three main steps: 1. In the first step, the “valid” samples are determined. Samples that are not valid are not used in the second step. Determining valid samples is done by the following procedures: (a) Range filtering: Pupil size values outside a predefined range are considered invalid. This range is configurable.
(b) Speed filtering: Speed is computed as the 1st difference of pupil size array normalized by the temporal separation. Samples with speed higher than a threshold are considered invalid. The threshold is configurable.
(c) Edge filtering: Samples at both sides of temporal gaps in the data are considered invalid. Both the duration of gaps and the invalid sample duration before/after the gaps are configurable.
(d) Trendline filtering: A data trend is generated by smoothing and interpolating the data. Then, samples that are too far away from this trend are considered invalid. These two steps are performed multiple times in an iterative fashion. Note that the generated trend is not the final result of this function. The smoothing, invalid threshold and the number of passes are configurable.
(e) Isolated sample filtering: Isolated and small sample islands are considered invalid. The size of the islands and the temporal separation are configurable.
-
In the second step, output smooth signal is generated using the valid samples found in the previous step. This is done by performing filtering, upsampling and interpolation. The parameters of the filtering and upsampling are configurable. Once the pupil data is preprocessed, according to the option ‘channel_action’, it will either replace an existing preprocessed pupil channel or add it as new channel to the provided file.
-
If combining is requested, then a new channel with combined signal will be created. Information about the underlying left and right pupil channels will be written into the data structure (field ‘header.valid_samples’).
Format
[sts, channel_index] = pspm_pupil_pp(fn) or
[sts, channel_index] = pspm_pupil_pp(fn, options)
Arguments
| Variable | Definition |
|---|---|
| fn | [string] Path to the PsPM file which contains the pupil data. |
| options | See following fields. |
| options.channel | [optional][numeric/string] [Default: ‘pupil’] Channel ID to be preprocessed. To process a specific eye, use ‘pupil_l’ or ‘pupil_r’. To process the combined left and right eye, use ‘pupil_c’. To combine both eyes, specify one eye here and the other under option ‘channel_combine’. The identifier ‘pupil’ will use the first existing option out of the following: (1) L-R-combined pupil, (2) non-lateralised pupil, (3) best eye pupil, (4) any pupil channel. If there are multiple channels of the specified type, only last one will be processed. You can also specify the number of a channel. |
| options.channel_combine | [optional][numeric/string][Default: ‘none’] Channel to be used for computing the mean pupil signal. The input format is exactly the same as the .channel field. However, the eye specified in this channel must be different from the one specified in .channel field. The output channel will then be of type ‘pupil_c’. |
| options.channel_action | [optional][string][Accepts: ‘add’/’replace’][Default: ‘add’] Defines whether corrected data should be added or the corresponding preprocessed channel should be replaced. |
| options.custom_settings | [optional][Default: See pspm_pupil_pp_options] Settings structure to modify the preprocessing steps. If not specified, the default settings structure obtained from pspm_pupil_pp_options will be used. To modify certain fields of this structure, you only need to specify those fields in custom_settings. For example, to modify settings.raw.PupilMin, you need to create a struct with a field .raw.PupilMin. |
| options.segments | [cell array of structures] Statistics about user defined segments can be calculated. When specified, segments will be stored in .header.segments field. Each structure must have the the following fields. |
| options.start | [decimal][Unit: second] Starting time of the segment. |
| options.end | [decimal][Unit: second] Ending time of the segment. |
| options.name | [string] Name of the segment. Segment will be stored by this name. |
| options.plot_data | [Boolean][Default: false or 0] Plot the preprocessing steps. |
| options.chan_valid_cutoff | [optional][Default: 0.01] A cut-off value for checking whether there are too many missing values in a data channel for combination. If the difference in missing data percentage between the two channels exceeds this cutoff, then combining will be skipped, and both channels will be processed separately. |
| options.out_chan | Channel ID of the preprocessed output. |
Outputs
| Variable | Definition |
|---|---|
| channel_index | index of channel containing the processed data. |
References
[1] Kret, Mariska E., and Elio E. Sjak-Shie. “Preprocessing pupil size data: Guidelines and code.” Behavior research methods (2018): 1-7.