detransient {eyeris} | R Documentation |
Remove pupil samples that are physiologically unlikely
Description
The intended use of this method is for removing pupil samples that emerge
more quickly than would be physiologically expected. This is accomplished by
rejecting samples that exceed a "speed"-based threshold (i.e., median
absolute deviation from sample-to-sample). This threshold is computed based
on the constant n
, which defaults to the value 16
.
Usage
detransient(eyeris, n = 16, mad_thresh = NULL, call_info = NULL)
Arguments
eyeris |
An object of class |
n |
A constant used to compute the median absolute deviation (MAD)
threshold. Defaults to |
mad_thresh |
Default
then, with the default multiplier
In this situation, any speed
|
call_info |
A list of call information and parameters. If not provided,
it will be generated from the function call. Defaults to |
Details
This function is automatically called by glassbox()
by default. If needed,
customize the parameters for detransient
by providing a parameter list. Use
glassbox(detransient = FALSE)
to disable this step as needed.
Users should prefer using glassbox()
rather than invoking this function
directly unless they have a specific reason to customize the pipeline
manually.
Computed properties:
-
pupil_speed
: Compute speed of pupil by approximating the derivative ofx
(pupil) with respect toy
(time) using finite differences.Let
x = (x_1, x_2, \dots, x_n)
andy = (y_1, y_2, \dots, y_n)
be two numeric vectors withn \ge 2
; then, the finite differences are computed as:\delta_i = \frac{x_{i+1} - x_i}{y_{i+1} - y_i}, \quad i = 1, 2, \dots, n-1.
This produces an output vector
p = (p_1, p_2, \dots, p_n)
defined by:For the first element:
p_1 = |\delta_1|,
For the last element:
p_n = |\delta_{n-1}|,
For the intermediate elements (
i = 2, 3, \dots, n-1
):p_i = \max\{|\delta_{i-1}|,\,|\delta_i|\}.
-
median_speed
: The median of the computedpupil_speed
:median\_speed = median(p)
-
mad_val
: The median absolute deviation (MAD) ofpupil_speed
from the median:mad\_val = median(|p - median\_speed|)
-
mad_thresh
: A threshold computed from the median speed and the MAD, using a constant multipliern
(default value: 16):mad\_thresh = median\_speed + (n \times mad\_val)
Value
An eyeris
object with a new column in timeseries
:
pupil_raw_{...}_detransient
Note
This function is part of the glassbox()
preprocessing pipeline and is not
intended for direct use in most cases. Provide parameters via
detransient = list(...)
.
Advanced users may call it directly if needed.
See Also
glassbox()
for the recommended way to run this step as
part of the full eyeris glassbox preprocessing pipeline.
Examples
demo_data <- eyelink_asc_demo_dataset()
demo_data |>
eyeris::glassbox(
detransient = list(n = 16) # set to FALSE to skip step (not recommended)
) |>
plot(seed = 0)