PascalKieslich/mousetrap: mousetrap v3.0.0

Announcements

• We are delighted that Dirk Wulff and Jonas Haslbeck have joined the mousetrap team! They are contributing a number of new functions, particularly for clustering and visualization.
• The documentation of the mousetrap package can now also be found online at http://pascalkieslich.github.io/mousetrap/

General changes to existing functions

• Introduction of class mousetrap for mousetrap data objects (such as mt_example). This facilitates, among other things, checking of the data class.
• Change of dimension order for all trajectory arrays: The old order was 1) trials, 2) variables, 3) samples. The new order is 1) trials, 2) samples, 3) variables. All functions and example data have been modified accordingly.
• Many reshape, aggregation, export, and plotting functions now accept a trajectory array as direct input to data.
• In case an analysis function adds measures to an existing data.frame, existing columns of the same name are now replaced and a warning is displayed (instead of merging the data.frames and adding generic suffixes).
• Arguments that were already deprecated and replaced (e.g., show_progress was replaced with verbose) have been removed.

Changes in specific functions

• mt_align_start: function is now vectorized and allows for optionally aligning to mean start position across trials; default for save_as argument is set to use.
• 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).
• mt_plot: introduced facet_row and facet_col arguments for faceting.
• mt_plot_add_rect: internal change to avoid warning message (due to changes in ggplot2).
• mt_plot_riverbed: explicitly remove zero frequencies instead of relying on the alpha parameter.

New functions

• 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_align_start and mt_align_start_end.
• 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_prototypes).

Bugs fixed

• 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=FALSE that function also works when multiple columns are merged and when all columns except mt_id are dropped beforehand.

Removed functions

• read_mousetracker: removed as it is recommended to directly import the MouseTracker raw data using the new function read_mt.
• mt_movement_angle: removed as it is replaced with new and more general function mt_angles.
• mt_calculate_derivatives, mt_calculate_deviations, mt_calculate_measures: removed as they were previously deprecated and replaced with mt_derivatives, mt_deviations, mt_measures.