mousetrap (version 1.0.0)

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

Description

mt_import_mousetrap accepts a data.frame of (merged) raw data from a mouse-tracking experiment implemented in OpenSesame using one of the https://github.com/pascalkieslich/mousetrap-os{mousetrap plug-ins}. 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. mt_import_mousetrap 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_mousetrap(raw_data, xpos_label = "xpos", ypos_label = "ypos",
  timestamps_label = "timestamps", mt_id_label = NULL, split = ", ",
  duplicates = "remove_first", reset_timestamps = TRUE,
  show_progress = TRUE)

Arguments

raw_data

a data.frame containing the raw data.

xpos_label

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

ypos_label

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

timestamps_label

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

mt_id_label

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

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

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.

show_progress

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. The column names for the timestamps, x- and y-positions are extracted using grep to find the column that starts with the respective character string (these will typically also contain the name of the item that was used to record them, such as xpos_track_mouse). This means that the exact column names do not have to be provided - as long as mouse-tracking data was collected only by a single item throughout the experiment (i.e., if only one column contains timestamps, xpos, and ypos respectively). Otherwise, the exact column names have to be specified. 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.

References

Mousetrap plug-ins for OpenSesame (https://github.com/pascalkieslich/mousetrap-os)

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.

Examples

mt_example <- mt_import_mousetrap(mt_example_raw)