Learn R Programming

mousetrap (version 1.2.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). 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.
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 on 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. 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:
mt_id
Trial ID (can be used for merging measures data.frame with other trial-level data)
x_max
Maximum x-position
x_min
Minimum x-position
y_max
Maximum y-position
y_min
Minimum y-position
MAD
Maximum absolute deviation from the direct path connecting start and end point of the trajectory (straight line)
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
x_flips
Number of directional changes along x-axis
y_flips
Number of directional changes along y-axis
x_reversals
Number of crossings of the y-axis
y_reversals
Number of crossings of the x-axis
RT
Response time, the total time passed until a response was given
initiation_time
Time passed until first mouse movement was initiated
idle_time
Total time without mouse movement across the entirety of the trial
xy_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 where minimum acceleration occurred first

Details

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. If the deviations from the idealized response trajectory have been calculated using mt_calculate_deviations before running mt_calculate_measures, the corresponding data in the trajectory array will be used. If not, mt_calculate_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_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_deviations(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