Calculate a number of mouse-tracking measures for each trajectory, such as
minima, maxima, and flips for each dimension, and different measures for
AUC). Note that some
measures are only returned if distance, velocity and acceleration are
calculated using mt_derivatives before running
More information on the different measures can be found in the Details and
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 )
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).
a character string specifying which trajectory data should be used.
a character string specifying where the calculated measures should be stored.
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 (
a character string specifying the trajectory dimension containing the timestamps.
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).
an optional numeric value. If specified,
hover_time) will be calculated as the number (and total time)
of periods without movement in a trial (whose duration exceeds the value
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
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).
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.
logical indicating whether function should report its progress.
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
The following measures are computed for each trajectory (the labels
relating to x- and y-positions will be adapted depending on the values
dimensions). Please note that additional information is
provided in the Details section.
Trial ID (can be used for merging measures data.frame with other trial-level data)
Signed Maximum absolute deviation from the direct path
connecting start and end point of the trajectory (straight line).
MAD occurs above the direct path, this is denoted by
a positive value; if it occurs below, by a negative value.
Time at which the maximum absolute deviation was reached first
Maximum deviation above the direct path
Time at which the maximum deviation above was reached first
Maximum deviation below the direct path
Time at which the maximum deviation below was reached first
Average deviation from direct path
Area under curve, the geometric area between the actual trajectory and the direct path where areas below the direct path have been subtracted
Number of directional changes along x-axis (exceeding the
distance specified in
Number of directional changes along y-axis (exceeding the
distance specified in
Number of crossings of the y-axis
Number of crossings of the x-axis
Response time, time at which tracking stopped
Time at which first mouse movement was initiated
Total time without mouse movement across the entirety of the trial
Total time of all periods without movement in a trial
(whose duration exceeds the value specified in
Number of periods without movement in a trial (whose duration
exceeds the value specified in
Total distance covered by the trajectory
Time at which maximum velocity occurred first
Time at which minimum velocity occurred first
Time at which maximum acceleration occurred first
Time at which minimum acceleration occurred first
Note that some measures are only returned if distance, velocity and
acceleration are calculated using mt_derivatives before
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
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
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_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).
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.
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
calculated using the polyarea function from the pracma
Note that all time related measures (except
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
initiation_time is defined as the last timestamp before the
initiation_threshold was crossed.
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.
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.
inner_join for merging data using the