mousetrap 3.2.3

Internal changes

• Added link to online documentation in package description
• Moved heatmap examples to dontrun to temporarily address CRAN clang18 issue

mousetrap 3.2.2

Announcements

• A tutorial to movement tracking of psychological processes with the mousetrap R package has been published as a preprint. Please cite it as follows when using mousetrap in your research: Wulff, D. U.*, Kieslich, P. J.*, Henninger, F., Haslbeck, J. M. B., & Schulte-Mecklenbeck, M. (2023). Movement tracking of psychological processes: A tutorial using mousetrap. PsyArXiv. https://doi.org/10.31234/osf.io/v685r

Bugs fixed

• mt_import_long: Preserve original trial order when importing trajectories. This also fixes the issue that trajectories are imported incorrectly when mt_id_label contains mixed case (closes #17, thanks to @LiKao)

Internal changes

• Implemented a suggestion by CRAN team regarding the setup of the package overview help file (accommodating changes in roxygen2)

mousetrap 3.2.1

Announcements

• A tutorial to movement tracking of cognitive processes with the mousetrap R package has been published as a preprint. Please cite it as follows when using mousetrap in your research: Wulff, D. U., Kieslich, P. J., Henninger, F., Haslbeck, J. M. B., & Schulte-Mecklenbeck, M. (2021). Movement tracking of cognitive processes: A tutorial using mousetrap. PsyArXiv. https://doi.org/10.31234/osf.io/v685r
• After more than 5 years, mousetrap finally has a logo (thanks to Dirk Wulff)

General changes to existing functions

• Introduction of lifecycle badges for experimental and deprecated functions using the lifecycle package
• mt_space_normalize function that was already deprecated and replaced with mt_align_start_end has been removed

New functions

• mt_exclude_finish: Remove a potential phase without mouse movement at the end of the trial

Changes in specific functions

• mt_average: Removed dimension argument which was already deprecated and replaced with av_dimension

Bugs fixed

• mt_time_normalize and mt_resample: Setting the dimensions argument to "all" now works (up to now, the functions simply returned an error when setting dimensions = "all")
• mt_angles: Now also works for the edge case that the trajectory array only contains a single trajectory (closes #15)
• mt_heatmap: Now passes on the verbose argument to the internally used mt_heatmap_raw function to prevent messages from mt_heatmap_raw if verbose = FALSE

Internal changes

• Added internal extract_dimensions function for extracting dimensions from trajectory array that also handles edge case of trajectory array with single trajectory

mousetrap 3.2.0

General changes to existing functions

• The mt_spatialize function has been replaced with mt_length_normalize (to achieve consistent naming analogous to mt_time_normalize). The new function offers the same functionality with the exception that the created trajectories are now by default called ln_trajectories (instead of sp_trajectories), which stands for length-normalized trajectories and should ensure consistency in naming with time-normalized trajectories.
• Because of the renaming of sp_trajectories to ln_trajectories, all functions that by default were using the sp_trajectories are now by default using ln_trajectories (e.g., mt_cluster and mt_map). Additionally, to ease the transition many mousetrap functions now internally flexibly exchange ln_trajectories and sp_trajectories in the use argument (if the specified trajectories are missing and the other trajectories are found) and throw a warning if they replace one with the other.

Changes in specific functions

• mt_spatialize: function is deprecated and replaced with mt_length_normalize. The reason for this is to achieve consistent naming analogous to mt_time_normalize. The mt_length_normalize function offers the same functionality as mt_spatialize with the exception that the created trajectories are now by default called ln_trajectories (instead of sp_trajectories), which stands for length-normalized trajectories and should ensure consistency in naming with time-normalized trajectories.
• mt_import_mousetrap: Now can also import trajectory coordinates when they are stored in scientific notation in the raw data (e.g., 2.98e-8).
• mt_plot and mt_plot_aggregate: Replaced only_ggplot with return_type argument. The new return_type argument allows for further customization of the plots: If return_type == "plot" (the default), a new ggplot is created and the trajectories are plotted using geom_path (corresponds to the old default behavior, where only_ggplot was set to FALSE). If return_type == "mapping", only the ggplot object containing the mapping but without any geoms is returned (corresponds to the old behavior where only_ggplot was set to TRUE). If return_type == "geoms", only the geoms are returned, which allows adding the plotted trajectories to an existing ggplot (new functionality).

Bugs fixed

• mt_exclude_initiation: Bug fixed so that the correct initial position is used when removing the initial period without movement in a trial. Previously, mt_exclude_initiation was only behaving as intended when the initial position was (0,0), which probably was the case in many settings (in particular, if the trajectories were aligned using mt_align_start with default start values). If the initial position in a trial corresponded to a different value, the initial period without movement in most cases was simply not removed. This has now been fixed (closes #14).

mousetrap 3.1.5

Changes in specific functions

• mt_measures: Introduced initiation_threshold argument to allow specifying a minimum distance from the start point of the trajectory that needs to be exceeded for calculating the initiation time.
• mt_import_mousetrap and mt_check_resolution: Introduced digits argument. If specified, timestamps will be rounded which can potentially be useful if timestamps are recorded with submillisecond precision.
• mt_import_mousetrap: Introduced unordered argument that allows for different options to handle unordered, that is, non-monotonically increasing timestamps within a trial.
• mt_plot and mt_plot_aggregate: Introduced wrap_var and wrap_ncol arguments that add wrapping to trajectory plots (i.e., splitting a plot across multiple columns and rows based on the levels of a single variable or a combination of variables).
• mt_plot_riverbed: Introduced na.rm argument which, if set to TRUE, allows the creation of riverbed plots from trajectories with unequal length (whether this is in practice desirable or not is an open question).

Internal changes

• mt_import_long: Replaced dplyr/tidyr standard evaluation functions by using embracing and pivoting.
• mt_reshape: Replaced dplyr/tidyr standard evaluation functions by using embracing and pivoting.
• mt_plot_riverbed and mt_heatmap_ggplot: Replaced geom_raster with geom_tile.
• Minor updates in documentation regarding function links and author information.

mousetrap 3.1.4

Announcements

• A book chapter on the mousetrap software packages has been published. It covers many common analyses using the mousetrap R package. Please cite it as follows when using mousetrap in your research:
• Kieslich, P. J., Henninger, F., Wulff, D. U., Haslbeck, J. M. B., & Schulte-Mecklenbeck, M. (2019). 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 (pp. 111-130). 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. (2019). Mouse-tracking: Detecting types in movement trajectories. In M. Schulte-Mecklenbeck, A. Kühberger, & J. G. Johnson (Eds.), A Handbook of Process Tracing Methods (pp. 131-145). New York, NY: Routledge.

Changes in specific functions

• mt_measures: Introduced hover_incl_intial argument to make inclusion of a potential initial phase without movement optional when calculating hovers. By default, this initial phase is included (as in previous versions).
• mt_measures: Multiple values can now be specified in the hover_threshold argument. If this is done, hovers and hover_time will be returned in separate variables for each threshold value (the variable name will be suffixed with the threshold value).
• mt_measures: Multiple values can now be specified in the flip_threshold argument. If this is done, flips (e.g., xpos_flips) will be returned in separate variables for each threshold value (the variable name will be suffixed with the threshold value).

Internal changes

• When checking the class of an object, inherits is now used consistently instead of the class function to avoid problems with future R releases (>=4.0.0).

mousetrap 3.1.3

Changes in specific functions

• mt_sample_entropy: By default, sample entropy is calculated based on the differences of the position values (following Hehman et al., 2015). An optional argument use_diff now has been introduced to allow users to override this behavior and use the untransformed values instead, by setting use_diff=FALSE.
• mt_align_start_end: Now checks, if start and end points are equal for a trial (separately per dimension). If so, returns a warning message as the aligned trajectory values for the respective dimension will be NaN/Inf/-Inf.

mousetrap 3.1.2

Changes in documentation

• citation("mousetrap") now returns the correct citation for the mousetrap package.
• Updated mousetrap book chapter citations (see announcements above for correct citation).

Changes in specific functions

• mt_import_long: internal change (prefix row_number() function with dplyr) to accomodate changes in dplyr 0.8.0.

mousetrap 3.1.1

Announcements

• Book chapters on the mousetrap software packages have been accepted for publication. See version 3.1.3 above for updated references (as the book chapters meanwhile have been published).
• If you have any questions when using mousetrap, you can now ask them in the mousetrap forum at http://forum.cogsci.nl/index.php?p=/categories/mousetrap

Changes in specific functions

• 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 facet_row and facet_col arguments.
• mt_diffmap: the condition can 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 and mt_plot_aggregate: transparency and line width can now be varied via the alpha and size arguments.
• mt_plot_riverbed: introduced grid_colors argument for setting the grid colors (use grid_colors = NA to omit grid lines).
• mt_reshape: internal changes reflecting changes in dplyr::summarize_at.
• mt_align_start and mt_align_start_end: if start is 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 linetype argument was used in mt_plot)

mousetrap 3.1.0

Announcements

• A first paper on the mousetrap software packages has been accepted for publication. It presents the mousetrap plugin for creating mouse-tracking experiments in OpenSesame and also includes a short demonstration of basic analyses using the mousetrap R package.
• Reference: Kieslich, P. J., & Henninger, F. (in press). Mousetrap: An integrated, open-source mouse-tracking package. Behavior Research Methods. doi:10.3758/s13428-017-0900-z

Changes in specific functions

• mt_derivatives: now always reports acceleration as difference in absolute velocity (the argument acc_on_abs_vel has been removed). Besides, the argument absolute has 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 dimensions.
• mt_sample_entropy: the default values reported have changed (cf. bug fix below). mt_sample_entropy now only uses a custom function for computing sample entropy (which is faster and produces virtually identical results as pracma::sample_entropy if the same parameters are used). Therefore, the method argument has been removed. Besides, the lag argument has been renamed to m.
• mt_distmat, mt_cluster, mt_cluster_k, and mt_map: now provide the option to remove trajectory points containing missing values (by setting the na_rm argument to 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_distmat, mt_cluster, mt_cluster_k, and mt_map: now allow for specifying the relative importance of each trajectory dimension via the weights argument. Technically, each variable is rescaled so that the standard deviation matches the corresponding value in weights. By default, weights is 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.
• mt_map: uses mousetrap::mt_prototypes as default for prototypes if 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 within variable is specified.

Bugs fixed

• mt_sample_entropy: Bug fixed for method="pracma" (the default method): The window size argument (which used to be specified using the lag argument - now this has been renamed to m) was incorrectly passed on to the tau argument of pracma::sample_entropy. It should have beend passed on to the edim argument. After fixing this, both methods in mt_sample_entropy provided virtually identical results (which is why the method argument has been dropped, see above).

New functions

• 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.
• Please note that although these functions have been tested extensively, they still have beta status.

New data

• KH2017_raw: Raw mouse-tracking dataset from Kieslich & Henninger (in press).
• KH2017: Mouse-tracking dataset from Kieslich & Henninger (in press).