mt_measures {mousetrap}

Calculate mouse-tracking measures.

Description

Calculate a number of mouse-tracking measures for each trajectory, such as minima, maxima, and flips for each dimension, and different measures for curvature (e.g., MAD, AD, and AUC). Note that some measures are only returned if distance, velocity and acceleration are calculated using mt_derivatives before running mt_measures. More information on the different measures can be found in the Details and Values sections.

Usage

mt_measures(
  data,
  use = "trajectories",
  save_as = "measures",
  dimensions = c("xpos", "ypos"),
  timestamps = "timestamps",
  flip_threshold = 0,
  hover_threshold = NULL,
  hover_incl_initial = TRUE,
  initiation_threshold = 0,
  verbose = FALSE
)

Arguments

data

a mousetrap data object created using one of the mt_import functions (see mt_example for details). Alternatively, a trajectory array can be provided directly (in this case use will be ignored).

use

a character string specifying which trajectory data should be used.

save_as

a character string specifying where the calculated measures should be stored.

dimensions

a character vector specifying the two dimensions in the trajectory array that contain the mouse positions. Usually (and by default), the first value in the vector corresponds to the x-positions (xpos) and the second to the y-positions (ypos).

timestamps

a character string specifying the trajectory dimension containing the timestamps.

flip_threshold

a numeric value specifying the distance that needs to be exceeded in one direction so that a change in direction counts as a flip. If several thresholds are specified, flips will be returned in separate variables for each threshold value (the variable name will be suffixed with the threshold value).

hover_threshold

an optional numeric value. If specified, hovers (and hover_time) will be calculated as the number (and total time) of periods without movement in a trial (whose duration exceeds the value specified in hover_threshold). If several thresholds are specified, hovers and hover_time will be returned in separate variables for each threshold value (the variable name will be suffixed with the threshold value).

hover_incl_initial

logical indicating if the calculation of hovers should include a potential initial phase in the trial without mouse movements (this initial phase is included by default).

initiation_threshold

a numeric value specifying the distance from the start point of the trajectory that needs to be exceeded for calculating the initiation time. By default, it is 0, meaning that any movement counts as movement initiation.

verbose

logical indicating whether function should report its progress.

Details

Note that some measures are only returned if distance, velocity and acceleration are calculated using mt_derivatives before running mt_measures. Besides, the meaning of these measures depends on the values of the arguments in mt_derivatives.

If the deviations from the idealized response trajectory have been calculated using mt_deviations before running mt_measures, the corresponding data in the trajectory array will be used. If not, mt_measures will calculate these deviations automatically.

The calculation of most measures can be deduced directly from their definition (see Value). For several more complex measures, a few details are provided in the following.

The signed maximum absolute deviation (MAD) is the maximum perpendicular deviation from the straight path connecting start and end point of the trajectory (e.g., Freeman & Ambady, 2010). If the MAD occurs above the direct path, this is denoted by a positive value. If it occurs below the direct path, this is denoted by a negative value. This assumes that the complete movement in the trial was from bottom to top (i.e., the end point has a higher y-position than the start point). In case the movement was from top to bottom, mt_measures automatically flips the signs. Both MD_above and MD_below are also reported separately.

The average deviation (AD) is the average of all deviations across the trial. Note that AD ignores the timestamps when calculating this average. This implicitly assumes that the time passed between each recording of the mouse is the same within each individual trajectory. If the AD is calculated using raw data that were obtained with an approximately constant logging resolution (sampling rate), this assumption is usually justified (mt_check_resolution can be used to check this). Alternatively, the AD can be calculated based on time-normalized trajectories; these can be computed using mt_time_normalize which creates equidistant time steps within each trajectory.

The AUC represents the area under curve, i.e., the geometric area between the actual trajectory and the direct path. Areas above the direct path are added and areas below are subtracted. The AUC is calculated using the polyarea function from the pracma package.

Note that all time related measures (except idle_time and hover_time) are reported using the timestamp metric as present in the data. To interpret the timestamp values as time since tracking start, the assumption has to be made that for each trajectory the tracking started at timestamp 0 and that all timestamps indicate the time passed since tracking start. Therefore, all timestamps should be reset during data import by subtracting the value of the first timestamp from all timestamps within a trial (assuming that the first timestamp corresponds to the time when tracking started). Timestamps are reset by default when importing the data using one of the mt_import functions (e.g., mt_import_mousetrap). Note that initiation_time is defined as the last timestamp before the initiation_threshold was crossed.

Value

A mousetrap data object (see mt_example) where an additional data.frame has been added (by default called "measures") containing the per-trial mouse-tracking measures. Each row in the data.frame corresponds to one trajectory (the corresponding trajectory is identified via the rownames and, additionally, in the column "mt_id"). Each column in the data.frame corresponds to one of the measures. If a trajectory array was provided directly as data, only the measures data.frame will be returned.

The following measures are computed for each trajectory (the labels relating to x- and y-positions will be adapted depending on the values specified in dimensions). Please note that additional information is provided in the Details section.

mt_id

Trial ID (can be used for merging measures data.frame with other trial-level data)

xpos_max

Maximum x-position

xpos_min

Minimum x-position

ypos_max

Maximum y-position

ypos_min

Minimum y-position

MAD

Signed Maximum absolute deviation from the direct path connecting start and end point of the trajectory (straight line). If the MAD occurs above the direct path, this is denoted by a positive value; if it occurs below, by a negative value.

MAD_time

Time at which the maximum absolute deviation was reached first

MD_above

Maximum deviation above the direct path

MD_above_time

Time at which the maximum deviation above was reached first

MD_below

Maximum deviation below the direct path

MD_below_time

Time at which the maximum deviation below was reached first

AD

Average deviation from direct path

AUC

Area under curve, the geometric area between the actual trajectory and the direct path where areas below the direct path have been subtracted

xpos_flips

Number of directional changes along x-axis (exceeding the distance specified in flip_threshold)

ypos_flips

Number of directional changes along y-axis (exceeding the distance specified in flip_threshold)

xpos_reversals

Number of crossings of the y-axis

ypos_reversals

Number of crossings of the x-axis

RT

Response time, time at which tracking stopped

initiation_time

Time at which first mouse movement was initiated

idle_time

Total time without mouse movement across the entirety of the trial

hover_time

Total time of all periods without movement in a trial (whose duration exceeds the value specified in hover_threshold)

hovers

Number of periods without movement in a trial (whose duration exceeds the value specified in hover_threshold)

total_dist

Total distance covered by the trajectory

vel_max

Maximum velocity

vel_max_time

Time at which maximum velocity occurred first

vel_min

Minimum velocity

vel_min_time

Time at which minimum velocity occurred first

acc_max

Maximum acceleration

acc_max_time

Time at which maximum acceleration occurred first

acc_min

Minimum acceleration

acc_min_time

Time at which minimum acceleration occurred first

Author(s)

Pascal J. Kieslich

Felix Henninger

References

Kieslich, P. J., Henninger, F., Wulff, D. U., Haslbeck, J. M. B., & Schulte-Mecklenbeck, M. (2019). Mouse-tracking: A practical guide to implementation and analysis. In M. Schulte-Mecklenbeck, A. Kühberger, & J. G. Johnson (Eds.), A Handbook of Process Tracing Methods (pp. 111-130). New York, NY: Routledge.

Freeman, J. B., & Ambady, N. (2010). MouseTracker: Software for studying real-time mental processing using a computer mouse-tracking method. Behavior Research Methods, 42(1), 226-241.

See Also

mt_sample_entropy for calculating sample entropy.

mt_standardize for standardizing the measures per subject.

mt_check_bimodality for checking bimodality of the measures using different methods.

mt_aggregate and mt_aggregate_per_subject for aggregating the measures.

inner_join for merging data using the dplyr package.

Examples

mt_example <- mt_derivatives(mt_example)
mt_example <- mt_deviations(mt_example)
mt_example <- mt_measures(mt_example)

# Merge measures with trial data
mt_example_results <- dplyr::inner_join(
  mt_example$data, mt_example$measures,
  by="mt_id")