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.

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

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

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

hover_threshold | an optional numeric value. If specified, |

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

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

Maximum x-position

Minimum x-position

Maximum y-position

Minimum y-position

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.

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 `flip_threshold`

)

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

)

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 `hover_threshold`

)

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

)

Total distance covered by the trajectory

Maximum velocity

Time at which maximum velocity occurred first

Minimum velocity

Time at which minimum velocity occurred first

Maximum acceleration

Time at which maximum acceleration occurred first

Minimum acceleration

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

Kieslich, P. J., Henninger, F., Wulff, D. U., Haslbeck, J. M. B.,
& Schulte-Mecklenbeck, M. (in press). Mouse-tracking: A practical guide to
implementation and analysis. In M. Schulte-Mecklenbeck, A. Kuehberger, & J.
G. Johnson (Eds.), *A Handbook of Process Tracing Methods*. New York:
Taylor & Francis.

Kieslich, P. J., Wulff, D. U., Henninger, F., Haslbeck, J. M. B., &
Schulte-Mecklenbeck, M. (2018). *Mouse- and hand-tracking as a window
to cognition: A tutorial on implementation, analysis, and visualization*.
Manuscript in preparation.

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.

mt_aggregate and mt_aggregate_per_subject for aggregating the measures.

inner_join for merging data using the `dplyr`

package.

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