Import mouse-tracking data recorded using the mousetrap plug-ins in OpenSesame.

Source: R/import.R

mt_import_mousetrap accepts a data.frame of (merged) raw data from a mouse-tracking experiment implemented in OpenSesame using the mousetrap plugin (Kieslich & Henninger, 2017). From this data.frame, mt_import_mousetrap creates a mousetrap data object containing the trajectories and additional data for further processing within the mousetrap package. Specifically, it returns a list that includes the trajectory data as an array (called trajectories), and all other data as a data.frame (called data). This data structure can then be passed on to other functions within this package (see mousetrap for an overview).

mt_import_mousetrap(
  raw_data,
  xpos_label = "xpos",
  ypos_label = "ypos",
  timestamps_label = "timestamps",
  mt_id_label = NULL,
  split = ",",
  duplicates = "remove_first",
  unordered = "warn",
  reset_timestamps = TRUE,
  digits = NULL,
  verbose = FALSE
)

Arguments

raw_data

a data.frame containing the raw data.

xpos_label

a character string specifying the name of the column(s) in which the x-positions are stored (see Details).

ypos_label

a character string specifying the name of the column(s) in which the y-positions are stored (see Details).

timestamps_label

a character string specifying the name of the column(s) in which the timestamps are stored (see Details).

mt_id_label

an optional character string (or vector) specifying the name of the column that provides a unique ID for every trial (the trial identifier). If unspecified (the default), an ID variable will be generated. If more than one variable name is provided, a new ID variable will be created by combining the values of each variable. The trial identifier will be set as the rownames of the resulting trajectories and trial data, and additionally be stored in the column "mt_id" in the trial data.

split

a character string indicating how the different timestamps and coordinates within a trial are separated.

duplicates

a character string indicating how duplicate timestamps within a trial are handled (see Details).

unordered

a character string indicating how unordered (i.e., non-monotonically increasing) timestamps within a trial are handled (see Details).

reset_timestamps

logical indicating if the first timestamp should be subtracted from all timestamps within a trial. Default is TRUE as it is recommended for all following analyses in mousetrap.

digits

an optional integer. If specified, timestamps will be rounded. Potentially useful if timestamps are recorded with submillisecond precision.

verbose

logical indicating whether function should report its progress.

Value

A mousetrap data object (see mt_example).

If mouse-tracking data were recorded using the mousetrap plug-ins for OpenSesame, the unit of the timestamps is milliseconds.

Details

When working with mouse-tracking data that were recorded using the mousetrap plug-ins for OpenSesame, usually only the raw_data need to be provided. All other arguments have sensible defaults.

If the relevant timestamps, x-positions, and y-positions are each stored in one variable, a character string specifying (parts of) the respective column name needs to be provided. In this case, the column names are extracted using grep to find the column that starts with the respective character string (in OpenSesame these will typically contain the name of the item that was used to record them, such as xpos_get_response). This means that the exact column names do not have to be provided - as long as only one column starts with the respective character string (otherwise, the exact column names have to be provided).

If several variables contain the timestamps, x-positions, and y-positions within a trial (e.g., xpos_part1 and xpos_part2), a vector of the exact column names has to be provided (e.g., xpos_label=c("xpos_part1","xpos_part2")). mt_import_mousetrap will then merge all raw data in the order with which the variable labels have been specified. If one variable contains NAs or an empty string in a trial, these cases will be ignored (this covers the special case that, e.g., xpos_part2 is only relevant for some trials and contains NAs in the other trials).

duplicates allows for different options to handle duplicate timestamps within a trial:

  • remove_first: First timestamp and corresponding x-/y-positions are removed (the default).

  • remove_last: Last timestamp and corresponding x-/y-positions are removed.

  • ignore: Duplicates are kept.

unordered allows for different options to handle unordered, that is, non-monotonically increasing timestamps within a trial:

  • warn: A warning is issued if unordered timestamps are encountered in a trial (the default).

  • remove: Unordered timestamps within a trial are removed. This means that any timestamp that is smaller than its predecessor will be removed along with the corresponding x-/y-position.

  • ignore: Unordered timestamps are kept and no warning is issued.

References

Kieslich, P. J., & Henninger, F. (2017). Mousetrap: An integrated, open-source mouse-tracking package. Behavior Research Methods, 49(5), 1652-1667. doi:10.3758/s13428-017-0900-z

See also

read_opensesame from the readbulk library for reading and combining raw data files that were collected with OpenSesame.

mt_import_wide and mt_import_long for importing mouse-tracking data from other sources.

Author

Pascal J. Kieslich

Felix Henninger

Examples

mt_data <- mt_import_mousetrap(mt_example_raw)