mt_deviations {mousetrap}

Calculate deviations from idealized trajectory.

Description

Calculate the idealized trajectory and the perpendicular deviations of the actual trajectory from it for each logged position.

Usage

mt_deviations(
  data,
  use = "trajectories",
  save_as = use,
  dimensions = c("xpos", "ypos"),
  start_ideal = NULL,
  end_ideal = NULL,
  prefix = "",
  verbose = FALSE
)

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 resulting trajectory data should be stored.

dimensions

a character vector specifying the two dimensions in the trajectory array that contain the mouse positions. By default (c("xpos","ypos")), the x- and y-positions are used.

start_ideal

an optional vector specifying the start position (see Example). If specified, this position will be used as the starting point of the idealized trajectory (instead of the actual starting point).

end_ideal

an optional vector specifying the end position (see Example). If specified, this position will be used as the end point of the idealized trajectory (instead of the actual end point).

prefix

an optional character string that is added as a prefix to the to be created new trajectory dimensions.

verbose

logical indicating whether function should report its progress.

Details

The idealized trajectory is defined as the straight line connecting the start and end point of the actual trajectory (e.g., Freeman & Ambady, 2010). The deviation for each position is calculated as the perpendicular deviation of the actual trajectory from the idealized trajectory.

If a deviation 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 points). In case the movement was from top to bottom, mt_deviations automatically flips the signs. Note that the second dimension specified in dimensions is used for determining all this.

Value

A mousetrap data object (see mt_example) where the positions of the idealized trajectory (by default called xpos_ideal and ypos_ideal) and the perpendicular deviations of the actual trajectory from the idealized trajectory (by default called dev_ideal) have been added as additional variables to the trajectory array. If the trajectory array was provided directly as data, only the trajectory array will be returned.

Author(s)

Pascal J. Kieslich

Felix Henninger

References

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_measures for calculating per-trial mouse-tracking measures.

Examples

# Calculate deviations from idealized trajectory
# (straight line connecting the start and end point of each trial)
mt_example <- mt_deviations(mt_example)
  
# Calculate deviations from idealized trajectory with
# constant start and end points across trials
mt_example <- mt_deviations(mt_example,
  start_ideal=c(0,0), end_ideal=c(-665,974))