Learn R Programming

mousetrap (version 1.0.0)

mt_calculate_measures: Calculate mouse-tracking measures.

Description

Calculate a number of mouse-tracking measures for each trajectory.

Usage

mt_calculate_measures(data, use = "trajectories", save_as = "measures",
  flip_threshold = 0, show_progress = TRUE)

Arguments

data
a mousetrap data object created using one of the mt_import functions (see mt_example for details).
use
a character string specifying which trajectory data should be used.
save_as
a character string specifying where the calculated measures should be stored.
flip_threshold
a numeric value specifying the distance that needs to be exceeded in one direction so that a change in direction counts as an x- or y-flip.
show_progress
logical indicating whether function should report its progress.

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 by default identified in the column mt_id). Each column in the data.frame corresponds to one of the measures. Note that some measures are only returned if distance, velocity and acceleration are calculated using mt_calculate_derivatives before running mt_calculate_measures. Besides, the meaning of these measures depends on the values of the arguments in mt_calculate_derivatives. The following measures are computed for each trajectory:
  • mt_idTrial ID (can be used for merging measures data.frame with other trial-level data)
  • x_maxMaximum x-position
  • x_minMinimum x-position
  • y_maxMaximum y-position
  • y_minMinimum y-position
  • MADMaximum absolute deviation from the direct path connecting start and end point of the trajectory (straight line)
  • MAD_timeTime at which the maximum absolute deviation was reached first
  • MD_aboveMaximum deviation above the direct path
  • MD_above_timeTime at which the maximum deviation above was reached first
  • MD_belowMaximum deviation below the direct path
  • MD_below_timeTime at which the maximum deviation below was reached first
  • ADAverage deviation from direct path
  • AUCArea under curve, the geometric area between the actual trajectory and the direct path where areas below the direct path have been subtracted
  • x_flipsNumber of directional changes along x-axis
  • y_flipsNumber of directional changes along y-axis
  • x_reversalsNumber of crossings of the y-axis
  • y_reversalsNumber of crossings of the y-axis
  • RTResponse time, the total time passed until a response was given
  • initiation_timeTime passed until first mouse movement was initiated
  • idle_timeTotal time without mouse movement across the entirety of the trial
  • xy_distTotal distance covered by the trajectory
  • vel_maxMaximum velocity
  • vel_max_timeTime at which maximum velocity occurred first
  • vel_minMinimum velocity
  • vel_min_timeTime at which minimum velocity occurred first
  • acc_maxMaximum acceleration
  • acc_max_timeTime at which maximum acceleration occurred first
  • acc_minMinimum acceleration
  • acc_min_timeTime where minimum acceleration occurred first

Details

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_calculate_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. merge for merging data.

Examples

Run this code
mt_example <- mt_calculate_derivatives(mt_example)
mt_example <- mt_calculate_measures(mt_example)

# Merge measures with trial data (adding "_raw"
# to columns already existing in the trial data)
mt_example_results <- merge(
  mt_example$data, mt_example$measures,
  by="mt_id",suffixes=c("_raw",""))

Run the code above in your browser using DataLab