mousetrap: Process and Analyze Mouse-Tracking Data

Description

The mousetrap package provides functions for importing, preprocessing, analyzing, aggregating, and visualizing mouse-tracking data. In the following, a brief overview of the functions in this package is given.

Import functions

The first step is to create a mousetrap data object. Depending on the input format, one of the following functions can be used. A detailed description (and example) of the resulting mousetrap data object can be found in mt_example.

mt_import_mousetrap imports mouse-tracking data that were recorded using the mousetrap plug-ins for OpenSesame.

mt_import_wide imports mouse-tracking data saved in a wide format (e.g., data exported from MouseTracker).

mt_import_long imports mouse-tracking data saved in a long format. (e.g., trajectories exported using the mt_reshape function from this package).

Preprocessing functions

A number of functions are available that perform preprocessing operations typically used before analyzing mouse-tracking data.

mt_remap_symmetric remaps mouse trajectories to one side (or one quadrant) of the coordinate system.

mt_exclude_initiation excludes the initial phase of a trial without mouse movement.

mt_align_start aligns the start position of trajectories.

mt_space_normalize performs space-normalization by remapping all trajectories so that they share a common initial and final coordinate.

mt_time_normalize performs time-normalization, resulting in an identical number of samples for all trajectories.

mt_resample resamples trajectories such that samples occur at constant intervals of a specified length.

mt_average averages trajectory coordinates for time bins of constant duration.

mt_subset filters mouse-tracking data by trials, such that are only those meeting defined criteria are included.

mt_add_variables adds new, self created variables to a trajectory array.

Analysis functions

A number of different analysis procedures and summary statistics for mouse trajectories have been established in the existing literature. The following functions implement many of these approaches.

mt_derivatives calculates distance, velocity, and acceleration for trajectories.

mt_deviations calculates the deviations from an idealized trajectory (straight line).

mt_measures calculates a set of mouse-tracking measures.

mt_sample_entropy calculates sample entropy.

mt_movement_angle calculates the initial movement angle.

mt_standardize standardizes mouse-tracking measures onto a common scale (individually for subsets of the data, e.g. z-scaled data per participant).

mt_check_bimodality assesses the bimodality of mouse-tracking measure distributions.

mt_check_resolution checks the (temporal) logging resolution of raw trajectories.

Reshaping, aggregation, and export functions

A number of helper functions are provided for aggregating, plotting, and exporting the multi-dimensional mouse trajectory arrays.

mt_reshape is a general purpose reshaping and aggregation function for mousetrap data.

mt_aggregate aggregates mouse-tracking data per condition.

mt_aggregate_per_subject aggregates mouse-tracking data per (within subjects-) condition separately for each subject.

mt_export_long exports mouse-tracking data in long format.

mt_export_wide exports mouse-tracking data in wide format.

Visualization functions

The following functions can be used for plotting trajectory data, e.g., individual and aggregated trajectories or velocity profiles.

mt_plot plots individual trajectory data.

mt_plot_aggregate plots aggregated trajectory data.

mt_plot_per_trajectory creates a pdf with separate plots per trajectory.

mt_plot_add_rect adds rectangles to a trajectory plot.

mt_plot_riverbed plots the relative frequency of a selected variable across time.

Helper functions

bimodality_coefficient calculates the bimodality coefficient.

scale_within scales and centers variables within the levels of another variable.

read_mousetracker reads data that was exported from MouseTracker.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
mt_example <- mt_import_mousetrap(mt_example_raw)
mt_example <- mt_remap_symmetric(mt_example)
mt_example <- mt_align_start(mt_example)
mt_example <- mt_time_normalize(mt_example)
mt_example <- mt_derivatives(mt_example)
mt_example <- mt_deviations(mt_example)
mt_example <- mt_measures(mt_example)

average_measures <- mt_aggregate(
  mt_example, use="measures",
  use_variables=c("MAD", "AD"),
  use2_variables="Condition"
)

mt_plot(mt_example,
  use="tn_trajectories",
  x="xpos", y="ypos", color="Condition"
)
        
mt_plot_aggregate(mt_example,
  use="tn_trajectories",
  x="xpos", y="ypos", color="Condition"
)

Want to suggest features or report bugs for rdrr.io? Use the GitHub issue tracker.