mt_import_mousetrap accepts a data.frame of (merged) raw data from a
mouse-tracking experiment implemented in
OpenSesame using the
(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
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 )
a data.frame containing the raw data.
a character string specifying the name of the column(s) in which the x-positions are stored (see Details).
a character string specifying the name of the column(s) in which the y-positions are stored (see Details).
a character string specifying the name of the column(s) in which the timestamps are stored (see Details).
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.
a character string indicating how the different timestamps and coordinates within a trial are separated.
a character string indicating how duplicate timestamps within a trial are handled (see Details).
a character string indicating how unordered (i.e., non-monotonically increasing) timestamps within a trial are handled (see Details).
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.
an optional integer. If specified, timestamps will be rounded. Potentially useful if timestamps are recorded with submillisecond precision.
logical indicating whether function should report its progress.
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.
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_part2), a vector of
the exact column names has to be provided (e.g.,
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
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
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.
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
mt_data <- mt_import_mousetrap(mt_example_raw)