mousetrap (version 2.0.0)

mt_measures: 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). 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, verbose = FALSE, show_progress = NULL)
mt_calculate_measures(data, use = "trajectories", save_as = "measures", dimensions = c("xpos", "ypos"), timestamps = "timestamps", flip_threshold = 0, verbose = FALSE, show_progress = NULL)

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.

verbose

logical indicating whether function should report its progress.

show_progress

Deprecated. Please use verbose instead.

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):

Functions

• mt_measures: Calculate mouse-tracking measures
• mt_calculate_measures: Deprecated

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 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.

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.

References

Mousetrap 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_movement_angle for calculating the initial movement angle.

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")