Mouse-tracking, the analysis of mouse movements in computerized experiments, is a method that is becoming increasingly popular in the cognitive sciences. The mousetrap package offers functions for importing, preprocessing, analyzing, aggregating, and visualizing mouse-tracking data.
Mouse-tracking, the analysis of mouse movements in computerized
experiments, is a method that is becoming increasingly popular in the
cognitive sciences. The
mousetrap package offers functions for
importing, preprocessing, analyzing, aggregating, and visualizing
mousetrap package is developed by Pascal Kieslich, Dirk Wulff,
Felix Henninger, and Jonas Haslbeck. It is published under the GNU
General Public License (version 3).
An overview of the functions in this package can be found
It can also be accessed from within R using
package?mousetrap once the
package has been installed. Please see
news for a summary of
changes in the package. Questions about using
mousetrap can be asked
mousetrap package offers functions for importing mouse-tracking
data in different formats and from various sources. One option to
collect mouse-tracking data is by using the open-source graphical
experiment builder OpenSesame in combination
with the mousetrap-os
The current stable version is available on CRAN and can be installed via
To install the latest development version from GitHub, you need the
devtools package . The development version can be installed via
If you use the
mousetrap package in your published research, we kindly
ask that you cite it as follows:
Kieslich, P. J., Henninger, F., Wulff, D. U., Haslbeck, J. M. B., & Schulte-Mecklenbeck, M. (in press). Mouse-tracking: A practical guide to implementation and analysis. In M. Schulte-Mecklenbeck, A. Kühberger, & J. G. Johnson (Eds.), A Handbook of Process Tracing Methods. New York, NY: Routledge.
Besides, if you use functions for clustering and mapping trajectories, please also include the following reference:
Wulff, D. U., Haslbeck, J. M. B., Kieslich, P. J., Henninger, F., & Schulte-Mecklenbeck, M. (in press). Mouse-tracking: Detecting types in movement trajectories. In M. Schulte-Mecklenbeck, A. Kühberger, & J. G. Johnson (Eds.), A Handbook of Process Tracing Methods. New York, NY: Routledge.
We thank Johanna Hepp for helpful comments on the documentation of this package and Monika Wiegelmann for testing a development version. This work was supported by the University of Mannheim’s Graduate School of Economic and Social Sciences, which is funded by the German Research Foundation.
citation("mousetrap")now returns the correct citation for the
mt_import_long: internal change (prefix
row_number()function with dplyr) to accomodate changes in dplyr 0.8.0.
mt_map: now allows for mapping trajectories onto prototypes separately for different groups of trajectories (the prototypes will be rescaled separately to match the coordinate system of each group).
mt_heatmap_ggplot: now allows for faceting using the
conditioncan now simply be specified by providing the corresponding variable name (and the condition values can now be any type, provided that they only contain two levels).
mt_plot_aggregate: transparency and line width can now be varied via the
grid_colorsargument for setting the grid colors (use
grid_colors = NAto omit grid lines).
mt_reshape: internal changes reflecting changes in
startis computed internally, it is now ensured that it is a named vector.
mt_plot_add_rect: it is now ensured that this function does not influence the legend (previously, this could happen if the
linetypeargument was used in
mt_derivatives: now always reports acceleration as difference in absolute velocity (the argument
acc_on_abs_velhas been removed). Besides, the argument
absolutehas been introduced that indicates if absolute values for distances and velocities should be reported (by default, this is not the case). All of this is only relevant if a single dimension is specified in
mt_sample_entropy: the default values reported have changed (cf. bug fix below).
mt_sample_entropynow only uses a custom function for computing sample entropy (which is faster and produces virtually identical results as
pracma::sample_entropyif the same parameters are used). Therefore, the
methodargument has been removed. Besides, the
lagargument has been renamed to
mt_map: now provide the option to remove trajectory points containing missing values (by setting the
TRUE). Removal is done column-wise. That is, if any trajectory has a missing value at, e.g., the 10th recorded position, the 10th position is removed for all trajectories.
mt_map: now allow for specifying the relative importance of each trajectory dimension via the
weightsargument. Technically, each variable is rescaled so that the standard deviation matches the corresponding value in
weights. By default,
weightsis a vector of 1s implying equal importance of each dimension (i.e., all dimensions are standardized to a standard deviation of 1). This changes the default behavior of the functions compared to the previous release where the original variables were used without standardization. To use the original variables, set
weights = NULL.
mousetrap::mt_prototypesas default for
prototypesif no prototypes are provided.
mt_average: now internally replaces NaNs with NAs. NaNs only occur if a specific dimension contains only NAs for an interval (which in practice only happens for acc values if the trial stops at the interval boundary).
mt_standardize: now by default standardizes mouse-tracking measures across all trials if no
withinvariable is specified.
mt_sample_entropy: Bug fixed for
method="pracma"(the default method): The window size argument (which used to be specified using the
lagargument - now this has been renamed to
m) was incorrectly passed on to the
pracma::sample_entropy. It should have beend passed on to the
edimargument. After fixing this, both methods in
mt_sample_entropyprovided virtually identical results (which is why the
methodargument has been dropped, see above).
bezier: create Bezier-curves using the Bernstein approximation.
mt_scale_trajectories: standardize variables in a mouse trajectory array.
mt_heatmap_raw: create high-resolution heatmap of trajectory data.
mt_heatmap: plot trajectory heatmap using base plots.
mt_heatmap_ggplot: plot trajectory heatmap using ggplot.
mt_diffmap: create a difference-heatmap of two trajectory heatmap images.
mt_animate: create a gif trajectory animation.
KH2017_raw: Raw mouse-tracking dataset from Kieslich & Henninger (in press).
KH2017: Mouse-tracking dataset from Kieslich & Henninger (in press).
mousetrapteam! They are contributing a number of new functions, particularly for clustering and visualization.
mousetrappackage can now also be found online at http://pascalkieslich.github.io/mousetrap/
mousetrapfor mousetrap data objects (such as
mt_example). This facilitates, among other things, checking of the data class.
show_progresswas replaced with
verbose) have been removed.
mt_align_start: function is now vectorized and allows for optionally aligning to mean start position across trials; default for
save_asargument is set to
mt_space_normalize: function is deprecated and replaced with
mt_align_start_end. It offers similar functionality but is vectorized and allows for optionally aligning to mean start/end position across trials.
mt_resample: now provides option to perform partial constant interpolation. Thanks to @sbrockhaus for the suggestion (cf. #7, #9).
mt_derivatives: now provides option to additionally return timestamp differences.
mt_measures: now optionally determines the number and duration of hovers (cf. #9), improved documentation and report of time measures (cf. #6).
facet_colarguments for faceting.
mt_plot_add_rect: internal change to avoid warning message (due to changes in
mt_plot_riverbed: explicitly remove zero frequencies instead of relying on the alpha parameter.
read_mt: read MouseTracker raw data (.mt files).
mt_align: general purpose function for aligning and rescaling trajectories. For specific operations, you can rely on the specialized functions
mt_spatialize: re-represent each trajectory spatially so that adjacent points become equidistant to each other.
mt_add_trajectory: add a new trajectory to a trajectory array.
mt_bind: join two trajectory arrays.
mt_count: count the number of observations for each trajectory.
mt_angles: calculate movement angles for trajectories.
mt_distmat: compute the distance matrix for each pair of trajectories.
mt_cluster: perform trajectory clustering with a specified number of clusters.
mt_cluster_k: estimate the optimal number of clusters using various methods.
mt_map: map trajectories onto a predefined set of prototype trajectories (a core set is provided in
mt_measures: make checks for timestamps > 0 and < 0 independent. Thanks to Regina Köhler for pointing this out.
mt_plot_per_trajectory: fix bug that all trajectories were plotted on each page (introduced through previous change in
mt_reshape). Thanks to Bence Palfi for discovering this.
create_results(internal function): Explicitly select mt_id column (instead of assuming that it is the first column - which is, e.g., often not the case in
data[["data"]]); ensure for case
overwrite=FALSEthat function also works when multiple columns are merged and when all columns except mt_id are dropped beforehand.
read_mousetracker: removed as it is recommended to directly import the MouseTracker raw data using the new function
mt_movement_angle: removed as it is replaced with new and more general function
mt_calculate_measures: removed as they were previously deprecated and replaced with
verbose(+ set default to
dimensionsargument to explicitly specify the names of the columns in the trajectory array that contain the mouse positions. In most cases, the default is
c("xpos","ypos")as the x- and y-positions should be used. Note that in some functions (as specified in the documentation) the order of the labels matters, the first value will be taken as the label of the x-positions, the second as the label of the y-positions.
timestampsargument to explicitly specify the dimension in the trajectory array containing the timestamps.
mt_reshape) based on the
rownames. Therefore, the
mt_idcolumn in data.frames is not needed anymore - but is kept for the convenience of the user. The column is called
"mt_id"in import and measures functions.
mt_reshapeallows the user to specify the label of the
calculatefrom all mt_calculate functions:
mt_calculate_deviationsare now called
create_results(that simplifies including the newly created trajectories or measures in the existing mousetrap data object).
reshape2functions are replaced with functions from the
dplyrpackages (and custom functions). Package dependencies were adjusted accordingly. As the
dplyrfunctions may introduce additional classes for the reshaped data (such as
tbl_df), a new argument (
convert_df) is introduced that converts the reshaped data to pure data.frames by default (thereby dropping additional classes).
mt_import_wide: Allow specifying several variables for the trial identifier in
mt_id_label. A new ID variable will be created by combining the values of each variable.
mt_import_mousetrap: Make import more robust against variables with empty logs (warning message is returned in the end) (closes #5, thanks to @sbrockhaus).
mt_import_wide: Import any number of additional variables using
mt_import_long: Timestamps are no longer used for ordering if
mt_seq_labelis not provided. Instead, data will be imported in the order in which they were stored in
mt_import_long: Improved speed by relying on functions from the
mt_align_start: Introduction of
dimensionsargument and the corresponding arguments
ypos_end). This also fixes the internal bug that in
xpos_startwas passed on as
dimensions, enable function to work with an arbitrary number of dimensions.
mt_deviations: Vectorized function
point_to_linefor time speed up (closes #2, thanks to @sbrockhaus).
mt_measures: Allow for flexible dimension labels and rename all measures columns relating only to x- or y-positions depending on the values in dimensions (e.g.,
xpos_flips). Change column label
mt_measures: Simplify AUC calculation using the actual x- and y-positions . New AUC values correlate to 1.00 with old values in
mt_example, but in some cases extremely small differences are possible (maximum difference of 2.328e-10 in mt_example).
.funs, which is passed on to the aggregation function(
.funsalso allows for specifying several aggregation functions.
mt_plot_per_trajectory: New arguments
ylimfor specifying the axes limits explicitly and
axes_exactfor plotting exact axes.
mt_plot_per_trajectory: New arguments
fillfor plotting rectangles (usually representing the response buttons).
mt_plot(and related functions): New argument
pointsallows for plotting points.
mt_add_variables: add new variables to trajectory array.
mt_export_long: export mouse-tracking data in long format (wrapper for
mt_export_wide: export mouse-tracking data in wide format (wrapper for
mt_align_start: Fixed bug that
ypos_start) was passed on as
mt_average: Fixed bug that if intervals were specified explicitly using
intervals, the wrong interval size was used when averaging (the default size of 100 was used).
mt_align_startadjusts trajectories so that they have the same start position (wrapper for
mt_calculate_deviationscalculates the idealized trajectory and the perpendicular deviations of the actual trajectory from it for each position in the trajectory array
dataargument. In this case, the
useargument will be ignored and only the resulting trajectory array will be returned
mt_plot_riverbednow preserves factor levels for facets
mt_calculate_derivativesnow allows for custom dimension names using the
mt_plot_per_trajectorynow receives the file name as the first argument
mt_import_mousetrapnow offers possibility to combine several variables in mouse-tracking raw data
mt_plot_riverbednow allows for faceting
mt_check_resolutionnow offers possibility to check (relative) frequencies of desired timestamp differences
mt_plot_riverbedcan no longer be set via
y_label(but can be added using the
ylab(), see Examples)