mt_import_long: Import mouse-tracking data saved in long format.

Description

mt_import_long receives a data.frame in which mouse-tracking data are stored in long format, i.e., where one row contains the logging data (timestamp, x- and y-position etc.) at one specific point in the trial. This is, for example, the case when exporting the trajectory data from the mousetrap package using mt_export_long. From this data.frame, mt_import_long 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).

Usage

mt_import_long(
  raw_data,
  xpos_label = "xpos",
  ypos_label = "ypos",
  zpos_label = NULL,
  timestamps_label = "timestamps",
  add_labels = NULL,
  mt_id_label = "mt_id",
  mt_seq_label = "mt_seq",
  reset_timestamps = TRUE,
  verbose = TRUE
)

Arguments

raw_data

a data.frame in long format, containing the raw data.

xpos_label

a character string specifying the column containing the x-positions.

ypos_label

a character string specifying the column containing the y-positions.

zpos_label

an optional character string specifying the column containing the z-positions.

timestamps_label

a character string specifying the column 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 columns containing additional mouse-tracking variables.

mt_id_label

a character string (or vector) specifying the name of the column that provides a unique ID for every trial (the trial identifier). 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.

mt_seq_label

a character string specifying the column that indicates the order of the logged coordinates within a trial. If no column of the specified name is found in the data.frame, the coordinates will be imported in the order in which they were stored in raw_data.

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

The default arguments are set so that no adjustments have to be made when importing a data.frame that was created using mt_export_long.

The coordinates are ordered according to the values in the column provided in the mt_seq_label parameter (mt_seq by default). If the corresponding column does not exist, the coordinates will be imported in the order in which they were stored in the raw_data.

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

Examples

Run this code

# NOT RUN {
# Create data in long format for test purposes
mt_data_long <- mt_export_long(mt_example,
  use2_variables=c("subject_nr","Condition"))

# Import the data using mt_import_long
mt_data <- mt_import_long(mt_data_long)


# }
# NOT RUN {
# Import a hypothetical dataset that contains the
# custom mouse-tracking variables angle and velocity
mt_data <- mt_import_long(exp_data,
  add_labels= c("angle", "velocity"))
# }
# NOT RUN {
# }