Merge branch 'master' of https://github.com/PascalKieslich/mousetrap

.Rbuildignore

@@ -7,3 +7,6 @@ cran-comments.md
 LICENSE
 ^docs$
 ^_pkgdown\.yml$
+^\.github$
+^actions$
+^Makefile$

.github/workflows/rhub.yaml

@@ -0,0 +1,79 @@
+# R-hub's genetic GitHub Actions workflow file. It's canonical location is at
+# https://github.com/r-hub/rhub2/blob/v1/inst/workflow/rhub.yaml
+# You can update this file to a newer version using the rhub2 package:
+#
+# rhub2::rhub_setup()
+#
+# It is unlikely that you need to modify this file manually.
+
+name: R-hub
+run-name: ${{ github.event.inputs.name || format('Manually run by {0}', github.triggering_actor) }} (${{ github.event.inputs.id }})
+
+on:
+  workflow_dispatch:
+    inputs:
+      config:
+        description: 'A comma separated list of R-hub platforms to use.'
+        type: string
+        default: 'linux,windows,macos'
+      name:
+        description: 'Run name. You can leave this empty now.'
+        type: string
+      id:
+        description: 'Unique ID. You can leave this empty now.'
+        type: string
+
+jobs:
+
+  setup:
+    runs-on: ubuntu-latest
+    outputs:
+      containers: ${{ steps.rhub-setup.outputs.containers }}
+      platforms: ${{ steps.rhub-setup.outputs.platforms }}
+
+    steps:
+    # NO NEED TO CHECKOUT HERE
+    - uses: r-hub/rhub2/actions/rhub-setup@v1
+      with:
+        config: ${{ github.event.inputs.config }}
+      id: rhub-setup
+
+  linux-containers:
+    needs: setup
+    if: ${{ needs.setup.outputs.containers != '[]' }}
+    runs-on: ubuntu-latest
+    name: ${{ matrix.config.label }}
+    strategy:
+      fail-fast: false
+      matrix:
+        config: ${{ fromJson(needs.setup.outputs.containers) }}
+    container:
+      image: ${{ matrix.config.container }}
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: r-hub/rhub2/actions/rhub-check@v1
+        with:
+          token: ${{ secrets.RHUB_TOKEN }}
+          job-config: ${{ matrix.config.job-config }}
+
+  other-platforms:
+    needs: setup
+    if: ${{ needs.setup.outputs.platforms != '[]' }}
+    runs-on: ${{ matrix.config.os }}
+    name: ${{ matrix.config.label }}
+    strategy:
+      fail-fast: false
+      matrix:
+        config: ${{ fromJson(needs.setup.outputs.platforms) }}
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: r-hub/rhub2/actions/rhub-setup-r@v1
+        with:
+          job-config: ${{ matrix.config.job-config }}
+          token: ${{ secrets.RHUB_TOKEN }}
+      - uses: r-hub/rhub2/actions/rhub-check@v1
+        with:
+          job-config: ${{ matrix.config.job-config }}
+          token: ${{ secrets.RHUB_TOKEN }}

DESCRIPTION

@@ -1,15 +1,15 @@
 Package: mousetrap
 Type: Package
-Version: 3.1.5
-Date: 2020-08-26
+Version: 3.2.3.9000
 Title: Process and Analyze Mouse-Tracking Data
 Description: 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.
     An introduction into mouse-tracking analyses using mousetrap can be found
-    in Kieslich, Henninger, Wulff, Haslbeck, & Schulte-Mecklenbeck (2019)
-    <doi: 10.4324/9781315160559-9> (preprint: https://psyarxiv.com/zuvqa/).
+    in Wulff, Kieslich, Henninger, Haslbeck, & Schulte-Mecklenbeck (2023)
+    <doi:10.31234/osf.io/v685r> (preprint: 
+    <https://osf.io/preprints/psyarxiv/v685r>).
 Maintainer: Pascal J. Kieslich <pascal.kieslich@gmail.com>
 Authors@R: c(
     person(c("Pascal","J."), "Kieslich", role= c("aut", "cre"),
@@ -25,7 +25,7 @@ Authors@R: c(
     		email = "jonas.haslbeck@googlemail.com"),
     person("Sarah", "Brockhaus", role = "ctb")
     )
-URL: https://github.com/pascalkieslich/mousetrap
+URL: https://pascalkieslich.github.io/mousetrap/, https://github.com/pascalkieslich/mousetrap
 BugReports: https://github.com/pascalkieslich/mousetrap/issues
 License: GPL-3
 Depends:
@@ -49,11 +49,13 @@ Imports:
     fastcluster,
     parallel,
     fields,
-    rlang
+    rlang,
+    lifecycle
 Suggests:
     readbulk,
     testthat
 LinkingTo: Rcpp
 Encoding: UTF-8
 LazyData: TRUE
-RoxygenNote: 7.1.1
+RoxygenNote: 7.2.3
+Roxygen: list(markdown = TRUE)

NAMESPACE

@@ -23,6 +23,7 @@ export(mt_derivatives)
 export(mt_deviations)
 export(mt_diffmap)
 export(mt_distmat)
+export(mt_exclude_finish)
 export(mt_exclude_initiation)
 export(mt_export_long)
 export(mt_export_wide)
@@ -32,6 +33,7 @@ export(mt_heatmap_raw)
 export(mt_import_long)
 export(mt_import_mousetrap)
 export(mt_import_wide)
+export(mt_length_normalize)
 export(mt_map)
 export(mt_measures)
 export(mt_plot)
@@ -44,14 +46,14 @@ export(mt_resample)
 export(mt_reshape)
 export(mt_sample_entropy)
 export(mt_scale_trajectories)
-export(mt_space_normalize)
 export(mt_spatialize)
 export(mt_standardize)
 export(mt_subset)
 export(mt_time_normalize)
 export(read_mt)
 export(scale_within)
 importFrom(Rcpp,sourceCpp)
+importFrom(lifecycle,deprecate_soft)
 importFrom(magrittr,"%>%")
 importFrom(rlang,.data)
 useDynLib(mousetrap, .registration = TRUE)

NEWS.md

@@ -1,3 +1,61 @@
+# mousetrap 3.2.3
+
+## Internal changes
+* Added link to online documentation in package description
+* Improved efficiency of heatmap examples
+
+# 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 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. (2021). _Movement tracking of cognitive processes: A tutorial using mousetrap._ PsyArXiv. https://doi.org/10.31234/osf.io/v685r Note that this tutorial has been updated and a new preprint has been published (see 3.2.2 release above).
+* 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

R/angles.R

@@ -74,10 +74,10 @@ mt_angles <- function(data,
     stop('Not all dimensions exist.')
 
   # Get angles
-  anglesP <- getAnglesP(trajectories[,,dimensions[1]],
-                        trajectories[,,dimensions[2]])
-  anglesV <- getAnglesV(trajectories[,,dimensions[1]],
-                        trajectories[,,dimensions[2]])
+  anglesP <- getAnglesP(extract_dimensions(trajectories,dimensions[1]),
+                        extract_dimensions(trajectories,dimensions[2]))
+  anglesV <- getAnglesV(extract_dimensions(trajectories,dimensions[1]),
+                        extract_dimensions(trajectories,dimensions[2]))
 
   # Replace NAs (where angle could not be calculated, see documentation)
   if (na_replace == TRUE) {

R/animate.R

@@ -1,8 +1,12 @@
 #' Create gif trajectory animation.
 #' 
+#' @description 
+#' `r lifecycle::badge("experimental")`
+#' 
 #' \code{mt_animate} animates trajectories using the animation package. Note
 #' that this function has beta status.
 #' 
+#' @details 
 #' \code{mt_animate} produces a .gif file showing a continuous stream of 
 #' animated trajectories. The function first produces a series of \emph{.png} 
 #' images, which then are combined into a \emph{.gif} animation using 

R/bimodality.R

@@ -19,7 +19,7 @@
 #' Pfister, R., Schwarz, K. A., Janczyk, M., Dale, R., & Freeman, J. B. (2013).
 #' Good things peak in pairs: A note on the bimodality coefficient.
 #' \emph{Frontiers in Psychology, 4}, 700.
-#' \url{http://dx.doi.org/10.3389/fpsyg.2013.00700}
+#' \doi{10.3389/fpsyg.2013.00700}
 #' 
 #' @seealso \link[psych]{skew} for calculating skewness and kurtosis.
 #'

R/cluster.R

@@ -10,7 +10,7 @@
 #' computed by \link{mt_distmat}.
 #' 
 #' Mouse trajectories often occur in distinct, qualitative types (see Wulff et
-#' al., in press; Wulff et al., 2018). Common trajectory types are linear
+#' al., 2019; Wulff et al., 2022). Common trajectory types are linear
 #' trajectories, mildly and strongly curved trajctories, and single and multiple
 #' change-of-mind trials (see also \link{mt_map}). \code{mt_cluster} can tease
 #' these types apart.
@@ -31,8 +31,8 @@
 #' trajectories share the same direction, e.g., that all trajectories end in the
 #' top-left corner of the coordinate system (\link{mt_remap_symmetric} or
 #' \link{mt_align} can be used to achieve this). Furthermore, it is recommended
-#' to use spatialized trajectories (see \link{mt_spatialize}; Wulff et al., in
-#' press; Haslbeck et al., 2018).
+#' to use length normalized trajectories (see \link{mt_length_normalize}; Wulff
+#' et al., 2019, Wulff et al., 2023).
 #'
 #' @inheritParams mt_time_normalize
 #' @param save_as a character string specifying where the resulting data should
@@ -86,32 +86,32 @@
 #' @references 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.), \emph{A Handbook of Process Tracing Methods} (pp. 131-145). New York, NY:
-#'   Routledge.
+#'   Johnson (Eds.), \emph{A Handbook of Process Tracing Methods} (pp. 131-145).
+#'   New York, NY: Routledge.
+#'   
+#'   Wulff, D. U., Kieslich, P. J., Henninger, F., Haslbeck, J. M. B., &
+#'   Schulte-Mecklenbeck, M. (2023). \emph{Movement tracking of psychological
+#'   processes: A tutorial using mousetrap.} PsyArXiv.
+#'   \doi{10.31234/osf.io/v685r}
 #'    
-#'   Wulff, D. U., Haslbeck, J. M. B., & Schulte-Mecklenbeck, M. (2018).
+#'   Wulff, D. U., Haslbeck, J. M. B., & Schulte-Mecklenbeck, M. (2022).
 #'   \emph{Measuring the (dis-)continuous mind: What movement trajectories
 #'   reveal about cognition}. Manuscript in preparation.
 #'
-#'   Haslbeck, J. M. B., Wulff, D. U., Kieslich, P. J., Henninger, F., &
-#'   Schulte-Mecklenbeck, M. (2018). \emph{Advanced mouse- and hand-tracking
-#'   analysis: Detecting and visualizing clusters in movement trajectories}.
-#'   Manuscript in preparation.
-#'
 #' @seealso \link{mt_distmat} for more information about how the distance matrix is 
 #'   computed when the hclust method is used.
 #'
 #'   \link{mt_cluster_k} for estimating the optimal number of clusters.
 #'
 #' @examples
-#' # Spatialize trajectories
-#' KH2017 <- mt_spatialize(KH2017)
+#' # Length normalize trajectories
+#' KH2017 <- mt_length_normalize(KH2017)
 #'
 #' # Cluster trajectories
-#' KH2017 <- mt_cluster(KH2017, use="sp_trajectories")
+#' KH2017 <- mt_cluster(KH2017, use="ln_trajectories")
 #' 
 #' # Plot clustered trajectories
-#' mt_plot(KH2017,use="sp_trajectories",
+#' mt_plot(KH2017,use="ln_trajectories",
 #'   use2="clustering",facet_col="cluster")
 #'
 #' @author
@@ -122,7 +122,7 @@
 #' @export
 
 mt_cluster <- function(data,
-                      use='sp_trajectories',
+                      use='ln_trajectories',
                       save_as='clustering',
                       dimensions=c('xpos', 'ypos'),
                       n_cluster=5, # k value