Import mouse-tracking data saved in wide format.

mt_import_wide receives a data.frame where mouse-tracking data are stored in wide format, i.e., where one row contains the data of one trial and every recorded mouse position and variable is saved in a separate variable (e.g., X_1, X_2, ..., Y_1, Y_2, ...). This is, e.g., the case when collecting data using MouseTracker (Freeman & Ambady, 2010). From this data.frame, mt_import_wide 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_wide(
  raw_data,
  xpos_label = "X",
  ypos_label = "Y",
  zpos_label = NULL,
  timestamps_label = "T",
  add_labels = NULL,
  mt_id_label = NULL,
  pos_sep = "_",
  pos_ids = NULL,
  reset_timestamps = TRUE,
  verbose = TRUE
)

Arguments

raw_data: a data.frame containing the raw data.
xpos_label: a character string specifying the core of the column labels containing the x-positions (e.g., "X" for "X_1", "X_2", ...).
ypos_label: a character string specifying the core of the column labels containing the y-positions (e.g., "Y" for "Y_1", "Y_2", ...).
zpos_label: a character string specifying the core of the column labels containing the z-positions.
timestamps_label: an optional character string specifying the core of the column labels containing the timestamps. If no timestamps are found in the data, a timestamps variable with increasing integers will be created (assuming equidistant time steps).
add_labels: a character vector specifying the core of columns containing additional mouse-tracking variables.
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.
pos_sep: a character string indicating the character that connects the core label and the position, (e.g., "_" for "X_1", "Y_1", ...).
pos_ids: the vector of IDs used for indexing the x-coordinates, y-coordinates etc. (e.g., 1:101 for time-normalized trajectories from MouseTracker). If unspecified (the default), column labels for the respective variable will be extracted using grep (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.
verbose: logical indicating whether function should report its progress.

Value

A mousetrap data object (see mt_example).

Details

mt_import_wide is designed to import mouse-tracking data saved in a wide format. The defaults are set so that usually only the raw_data need to be provided when data have been collecting using MouseTracker (Freeman & Ambady, 2010) and have been read into R using read_mt.

If no pos_ids are provided, column labels for the respective variable (e.g., x-positions) are extracted using grep returning all variables that start with the respective character string (e.g., "X_" if xpos_label="X" and pos_sep="_").

If no timestamps are found in the data, mt_import_wide automatically creates a timestamps variable with increasing integers (starting with 0) assuming equally spaced sampling intervals.

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.

Author

Pascal J. Kieslich

Felix Henninger

Examples

# Create data in wide format for test purposes
mt_data_wide <- mt_export_wide(mt_example,
  use2_variables=c("subject_nr", "Condition"))

# Import the data using mt_import_wide
mt_data <- mt_import_wide(mt_data_wide,
  xpos_label="xpos", ypos_label="ypos",
  timestamps_label="timestamps")
#> No mt_id_label provided. A new trial identifying variable called mt_id was created.
#> No pos_ids provided. The following variables were found using grep:
#> 465 variables found for timestamps.
#> 465 variables found for xpos.
#> 465 variables found for ypos.