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.
detransient(eyeris, n = 16, mad_thresh = NULL, call_info = NULL)An eyeris object with a new column in timeseries:
pupil_raw_{...}_detransient
An object of class eyeris derived from load_asc()
A constant used to compute the median absolute deviation (MAD)
threshold. Defaults to 16
Default NULL. This parameter provides
alternative options for handling edge cases where the computed
properties here within detransient() \(mad\_val\)
and \(median\_speed\) are very small. For example, if
$$mad\_val = 0 \quad \text{and} \quad median\_speed = 1,$$
then, with the default multiplier \(n = 16\),
$$mad\_thresh = median\_speed +
(n \times mad\_val) = 1 + (16 \times 0) = 1.$$
In this situation, any speed \(p_i \ge 1\) would be flagged as a
transient, which might be overly sensitive. To reduce this sensitivity,
two possible adjustments are available:
If \(mad\_thresh = 1\), the transient detection criterion is modified from $$p_i \ge mad\_thresh$$ to $$p_i > mad\_thresh .$$
If \(mad\_thresh\) is very small, the user may manually
adjust the sensitivity by supplying an alternative threshold value
here directly via this mad_thresh parameter.
A list of call information and parameters. If not provided,
it will be generated from the function call. Defaults to NULL
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
of x (pupil) with respect to y (time) using finite differences.
Let \(x = (x_1, x_2, \dots, x_n)\) and \(y = (y_1, y_2, \dots, y_n)\) be two numeric vectors with \(n \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 computed pupil_speed:
$$median\_speed = median(p)$$
mad_val: The median absolute deviation (MAD) of pupil_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 multiplier \(n\) (default value: 16):
$$mad\_thresh = median\_speed + (n \times mad\_val)$$
glassbox() for the recommended way to run this step as
part of the full eyeris glassbox preprocessing pipeline.
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)
Run the code above in your browser using DataLab