mousetrap (version 1.2.0)

mt_import_wide: Import mouse-tracking data saved in wide format.

Description

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 is saved in a separate variable. This is, e.g., the case when exporting trajectories from 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. mt_import_wide returns a list, which includes the trajectory data as an array, and all other data as a data.frame. This data structure can then be passed on to other functions within this package, such as mt_time_normalize or mt_calculate_measures.

Usage

mt_import_wide(raw_data, xpos_label = "X", ypos_label = "Y", timestamps_label = NULL, dist_label = NULL, vel_label = NULL, acc_label = NULL, mt_id_label = NULL, pos_sep = "_", pos_ids = NULL, reset_timestamps = 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", ...).

timestamps_label

an optional character string specifying the core of the column labels containing the timestamps.

dist_label

an optional character string specifying the core of the column labels containing the distance traveled.

vel_label

an optional character string specifying the core of the column labels containing the velocity.

acc_label

an optional character string specifying the core of the column labels containing the acceleration.

mt_id_label

an optional character string specifying the name of the column that provides a unique ID for every trial. If unspecified, an ID variable will be generated.

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, 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.

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 and pos_ids need to be provided when importing trajectory data that stem from a "time normalized analysis" in MouseTracker (Freeman & Ambady, 2010).

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" for x-positions). This is, e.g., useful when importing trajectory data that stem from a "raw time analysis" in MouseTracker (Freeman & Ambady, 2010).

If no timestamps are provided, mt_import_wide automatically assumes equally spaced sampling intervals and creates a timestamp variable with increasing integers (starting with 0).

If labels for distance, velocity, and acceleration are provided, these are included in the trajectory array.

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

read_mousetracker for reading data into R that were exported from MouseTracker (Freeman & Ambady, 2010).

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

Examples

## Not run: 
# 
# # Data from "time normalized analysis" in MouseTracker
# raw_data <- read_mousetracker("tn_data_exported.csv")
# data <- mt_import_wide(raw_data, pos_ids=1:101)
# 
# # Data from "raw time analysis" in MouseTracker
# raw_data <- read_mousetracker("raw_data_exported.csv", last_lines_to_rm=2*8)
# data <- mt_import_wide(raw_data)
# 
# ## End(Not run)