diff --git a/NEWS.md b/NEWS.md
index 5a34bd9..bef0c1c 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,7 +1,7 @@
# mousetrap 3.2.2
## Announcements
-* A updated 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
+* 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)
@@ -13,6 +13,7 @@
# 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
diff --git a/_pkgdown.yml b/_pkgdown.yml
index d6a3241..6778ff9 100644
--- a/_pkgdown.yml
+++ b/_pkgdown.yml
@@ -34,7 +34,7 @@ navbar:
type: default
left:
- text: Overview
- href: reference/mousetrap.html
+ href: reference/mousetrap-package.html
- text: Reference
href: reference/index.html
- text: News
diff --git a/docs/404.html b/docs/404.html
index d4aafd0..42db92e 100644
--- a/docs/404.html
+++ b/docs/404.html
@@ -32,14 +32,14 @@
mousetrap
- 3.2.1
+ 3.2.2
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
+
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
@Misc{,
- title = {Movement tracking of cognitive processes: {A} tutorial using mousetrap},
+ title = {Movement tracking of psychological processes: {A} tutorial using mousetrap},
author = {Dirk U. Wulff and Pascal J. Kieslich and Felix Henninger and Jonas M. B. Haslbeck and Michael Schulte-Mecklenbeck},
- year = {2021},
+ year = {2023},
publisher = {PsyArXiv},
- url = {https://psyarxiv.com/v685r},
+ url = {https://osf.io/preprints/psyarxiv/v685r},
doi = {10.31234/osf.io/v685r},
}
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.
+
+
+
+
+
Read functions
+
+
+
+
Depending on the file format, one of the standard R functions for reading
+files into R can be used (e.g., read.table or
+read.csv).
+
If raw data were collected using
+MouseTracker, the mousetrap package
+provides the read_mt function to read files in the ".mt" format.
+
If several raw data files should be read and merged, the
+read_bulk function from the
+readbulk package can be
+used (or the read_opensesame function, if data were
+collected using OpenSesame).
+
+
+
Import functions
+
+
+
+
The initial step to prepare data for analysis in the mousetrap package 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_wide imports mouse-tracking data saved in a wide format
+(e.g., data collected using
+MouseTracker).
+
mt_import_long imports mouse-tracking data saved in a long format.
+(e.g., trajectories exported using mt_export_long).
+
+
+
Geometric preprocessing functions
+
+
+
+
A number of functions are available that perform geometric preprocessing
+operations.
+
mt_remap_symmetric remaps mouse trajectories to one side (or one
+quadrant) of the coordinate system.
+
mt_align is a general purpose function for aligning and rescaling
+trajectories. For specific operations, you can rely on one of the
+following functions.
+
mt_align_start aligns the start position of trajectories.
+
mt_align_start_end aligns all trajectories so that they share a
+common initial and final coordinate (this is also sometimes referred to as
+"space-normalization").
+
+
+
Resampling and interpolation functions
+
+
+
+
A number of functions are available that perform resampling and
+interpolation operations.
+
mt_exclude_initiation excludes the initial phase of a trial without
+mouse movement.
+
mt_exclude_finish excludes a potential phase without mouse movement at the end of a trial.
+
mt_time_normalize performs time-normalization using equidistant time
+intervals, resulting in an identical number of samples for all
+trajectories.
+
mt_resample resamples trajectories so that samples occur at constant
+intervals of a specified length.
+
mt_average averages trajectory coordinates (and related variables)
+for time bins of constant duration.
+
mt_length_normalize re-represents each trajectory spatially so that
+adjacent points on the trajectory become equidistant to each other.
+
+
+
Data handling functions
+
+
+
+
A number of functions are available for data handling operations, such as
+filtering or adding of new variables or trajectories.
+
mt_subset filters mouse-tracking data by trials, so that only those
+meeting the defined criteria are included.
+
mt_add_variables adds new, self created variables to a trajectory
+array.
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_angles calculates movement angles for trajectories.
+
mt_deviations calculates the deviations from an idealized
+trajectory (straight line).
+
mt_measures calculates a set of mouse-tracking measures.
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
save_as
a character string specifying where the resulting trajectory
data should be stored.
+
+
xpos
a vector of x positions. Ignored, if xypos is provided.
+
+
ypos
a vector of y positions. Ignored, if xypos is provided.
+
+
xypos
a matrix, the first column corresponding to the x positions, the
second to the y positions.
+
+
id
a character string specifying the identifier of the to be added
trajectory.
+
Value
-
A mousetrap data object (see mt_example) where the new
+
+
+
A mousetrap data object (see mt_example) where the new
trajectory has been added.
If the trajectory array was provided directly as data, only the
trajectory array will be returned.
@@ -105,11 +120,11 @@
Author
Examples
-
# Add additional prototype to mt_prototypes
-mt_prototypes_ext<-mt_add_trajectory(mt_prototypes,
- xpos =c(0,1,-1,1,-1), ypos =c(0,1.5,1.5,1.5,1.5), id ="dCoM3"
-)
-
+
# Add additional prototype to mt_prototypes
+mt_prototypes_ext<-mt_add_trajectory(mt_prototypes,
+ xpos =c(0,1,-1,1,-1), ypos =c(0,1.5,1.5,1.5,1.5), id ="dCoM3"
+)
+
mt_add_variables(data, use ="trajectories", save_as =use, variables)
+
mt_add_variables(data, use ="trajectories", save_as =use, variables)
@@ -73,12 +73,18 @@
Arguments
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
save_as
a character string specifying where the resulting trajectory
data should be stored.
+
+
variables
a list of matrices that each contain the data of
one of the to be added variables. In this case, the new variables with
@@ -86,10 +92,13 @@
Arguments
dimension. Alternatively, a character vector specifying the name of the new
variables that should be added to the trajectory array. In this case, the
new variables are filled with NAs.
+
Value
-
A mousetrap data object (see mt_example) where the new
+
+
+
A mousetrap data object (see mt_example) where the new
variables have been added to the trajectory array.
Depending on the input to variables, the values for the added
variables are either NAs or their actual values. If columns of the
@@ -105,16 +114,16 @@
Author
Examples
-
# Calculate new (arbitrary) variables for this example
-# ... the sum of the x- and y-positions
-xy_sum<-mt_example$trajectories[,,"xpos"]+mt_example$trajectories[,,"ypos"]
-# ... the product of the x- and y-positions
-xy_prod<-mt_example$trajectories[,,"xpos"]*mt_example$trajectories[,,"ypos"]
-
-# Add the new variables to the trajectory array
-mt_example<-mt_add_variables(mt_example,
- variables=list(xy_sum=xy_sum, xy_prod=xy_prod))
-
+
# Calculate new (arbitrary) variables for this example
+# ... the sum of the x- and y-positions
+xy_sum<-mt_example$trajectories[,,"xpos"]+mt_example$trajectories[,,"ypos"]
+# ... the product of the x- and y-positions
+xy_prod<-mt_example$trajectories[,,"xpos"]*mt_example$trajectories[,,"ypos"]
+
+# Add the new variables to the trajectory array
+mt_example<-mt_add_variables(mt_example,
+ variables=list(xy_sum=xy_sum, xy_prod=xy_prod))
+
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which dataset should be aggregated.
The corresponding data are selected from data using
data[[use]]. Usually, this value corresponds to either
"tn_trajectories" or "measures", depending on whether the time-normalized
trajectories or derived measures should be aggregated.
+
+
use_variables
a character vector specifying the mouse-tracking
variables to aggregate. If a data.frame with mouse-tracking measures is
@@ -95,21 +99,29 @@
Arguments
trajectory array is provided, this argument should specify the labels of
respective array dimensions. If unspecified, all variables will be
aggregated.
+
+
use2
a character string specifying where the data containing the
condition information can be found. Defaults to "data" as
data[["data"]] usually contains all non mouse-tracking trial data.
Alternatively, a data.frame can be provided directly.
+
+
use2_variables
a character string (or vector) specifying the variables
(in data[[use2]]) across which the trajectories / measures will be
aggregated. For each combination of levels of the grouping variable(s),
aggregation will be performed separately using summarize_at.
+
+
subject_id
an optional character string specifying the column that
contains the subject identifier. If specified, aggregation will be
performed within subjects first (i.e., within subjects for all available
values of the grouping variables specified in use2_variables).
+
+
trajectories_long
logical indicating if the reshaped trajectories
should be returned in long or wide format. If TRUE, every recorded
@@ -119,13 +131,18 @@
Arguments
by adding an integer to the corresponding label (e.g., xpos_1,
xpos_2, ...). Only relevant if data[[use]] contains
trajectories.
+
+
...
additional arguments passed on to mt_reshape (such as
subset).
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which dataset should be aggregated.
The corresponding data are selected from data using
data[[use]]. Usually, this value corresponds to either
"tn_trajectories" or "measures", depending on whether the time-normalized
trajectories or derived measures should be aggregated.
+
+
use_variables
a character vector specifying the mouse-tracking
variables to aggregate. If a data.frame with mouse-tracking measures is
@@ -97,19 +101,27 @@
Arguments
trajectory array is provided, this argument should specify the labels of
respective array dimensions. If unspecified, all variables will be
aggregated.
+
+
use2
a character string specifying where the data containing the
condition information can be found. Defaults to "data" as
data[["data"]] usually contains all non mouse-tracking trial data.
Alternatively, a data.frame can be provided directly.
+
+
use2_variables
a character string (or vector) specifying the variables
(in data[[use2]]) across which the trajectories / measures will be
aggregated. For each combination of levels of the grouping variable(s),
aggregation will be performed separately using summarize_at.
+
+
subject_id
a character string specifying which column contains the
subject identifier.
+
+
trajectories_long
logical indicating if the reshaped trajectories
should be returned in long or wide format. If TRUE, every recorded
@@ -119,13 +131,18 @@
Arguments
by adding an integer to the corresponding label (e.g., xpos_1,
xpos_2, ...). Only relevant if data[[use]] contains
trajectories.
+
+
...
additional arguments passed on to mt_reshape (such as
subset).
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
save_as
a character string specifying where the resulting trajectory
data should be stored.
+
+
dimensions
a character string specifying which trajectory variables
should be used. Can be of length 2 or 3 for two-dimensional or
three-dimensional alignment respectively.
+
+
coordinates
either a numeric vector of length 4 specifying the xstart,
ystart, xend, yend coordinates of the trajectory start and end points. Can
@@ -97,26 +105,37 @@
Arguments
to set coordinates to c(0,0,-1,1), and wide to set
coordinates to c(0,0,-1,1.2). In the three-dimensional case,
coordinates is a vector of length 6.
+
+
align_start
boolean specifying whether the start points of all
trajectories should be aligned to the position specified in
coordinates. See Details.
+
+
align_end
boolean specifying whether the end points of all trajectories
should be aligned to the position specified in coordinates. See
Details.
+
+
align_side
character string specifying whether all trajectories should
be flipped to the left side (left), the right side (right),
or not at all (no). Assumes that first entry in dimensions
are the x positions.
+
+
verbose
logical indicating whether function should report its
progress.
+
Value
-
A mousetrap data object (see mt_example) with aligned
+
+
+
A mousetrap data object (see mt_example) with aligned
trajectories. Per default, the dimensions in the original trajectory array
will be replaced. If a different trajectory array is specified using
save_as, a new trajectory array will be created (including only the
@@ -155,10 +174,10 @@
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
save_as
a character string specifying where the resulting trajectory
data should be stored.
+
+
dimensions
a character vector specifying the dimensions in the
trajectory array that should be aligned.
+
+
start
a numeric vector specifying the start values for each dimension,
i.e., the values the first recorded position should have in every trial. If
NULL, trajectories are aligned to the mean first position across all
trials.
+
+
verbose
logical indicating whether function should report its
progress.
+
Value
-
A mousetrap data object (see mt_example) with aligned
+
+
+
A mousetrap data object (see mt_example) with aligned
trajectories. All other trajectory dimensions not specified in
dimensions (e.g., timestamps) will be kept as is in the resulting
trajectory array. If the trajectory array was provided directly as
@@ -114,21 +127,21 @@
Author
Examples
-
# Import raw trajectories for demonstration
-mt_example<-mt_import_mousetrap(mt_example_raw)
-
-# Align trajectories to start coordinates (0,0)
-mt_example<-mt_align_start(mt_example,
- start=c(0,0))
-
-
-# Import raw trajectories for demonstration
-mt_example<-mt_import_mousetrap(mt_example_raw)
-
-# Align trajectories to mean first coordinates
-mt_example<-mt_align_start(mt_example,
- start=NULL)
-
+
# Import raw trajectories for demonstration
+mt_example<-mt_import_mousetrap(mt_example_raw)
+
+# Align trajectories to start coordinates (0,0)
+mt_example<-mt_align_start(mt_example,
+ start=c(0,0))
+
+
+# Import raw trajectories for demonstration
+mt_example<-mt_import_mousetrap(mt_example_raw)
+
+# Align trajectories to mean first coordinates
+mt_example<-mt_align_start(mt_example,
+ start=NULL)
+
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
save_as
a character string specifying where the resulting trajectory
data should be stored.
+
+
dimensions
a character vector specifying the dimensions in the
trajectory array that should be aligned.
+
+
start
a numeric vector specifying the start values for each dimension,
i.e., the values the first recorded position should have in every trial. If
NULL, trajectories are aligned to the mean first position across all
trials.
+
+
end
a numeric vector specifying the end values for each dimension,
i.e., the values the last recorded position should have in every trial. If
@@ -98,13 +108,18 @@
Arguments
trials. Note that in this case trajectories should be remapped to one side
before alignment (e.g., using mt_remap_symmetric) so that the mean
last position is meaningful.
+
+
verbose
logical indicating whether function should report its
progress.
+
Value
-
A mousetrap data object (see mt_example) with aligned
+
+
+
A mousetrap data object (see mt_example) with aligned
trajectories. All other trajectory dimensions not specified in
dimensions (e.g., timestamps) will be kept as is in the resulting
trajectory array. If the trajectory array was provided directly as
@@ -132,22 +147,22 @@
Author
Examples
-
# Align start and end positions to specific coordinates
-mt_example<-mt_align_start_end(mt_example,
- start=c(0,0), end=c(-1,1))
-
-
-# Import raw trajectories for demonstration
-mt_example<-mt_import_mousetrap(mt_example_raw)
-
-# Remap trajectories
-mt_example<-mt_remap_symmetric(mt_example)
-
-# Align trajectories to mean first and last coordinates
-mt_example<-mt_align_start_end(mt_example,
- start=NULL, end=NULL)
-
-
+
# Align start and end positions to specific coordinates
+mt_example<-mt_align_start_end(mt_example,
+ start=c(0,0), end=c(-1,1))
+
+
+# Import raw trajectories for demonstration
+mt_example<-mt_import_mousetrap(mt_example_raw)
+
+# Remap trajectories
+mt_example<-mt_remap_symmetric(mt_example)
+
+# Align trajectories to mean first and last coordinates
+mt_example<-mt_align_start_end(mt_example,
+ start=NULL, end=NULL)
+
+
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
dimensions
a character string specifying which trajectory variables
should be used. Must be of length 2.
+
+
save_as
a character string specifying where the resulting trajectory
data should be stored.
+
+
na_replace
logical specifying whether NAs in the angle values
should be replaced using the next existing angle value (see Details).
Defaults to FALSE.
+
+
unit
character specifying the unit for the angles. Default is
"radian", alternative is "degree".
+
+
verbose
logical indicating whether function should report its
progress.
+
Value
-
A mousetrap data object (see mt_example) with point-based and
+
+
+
A mousetrap data object (see mt_example) with point-based and
vertical-based angles added as additional variables to the trajectory array
(called angle_p and angle_v). If a trajectory array was
provided directly as data, only the trajectory array will be
@@ -135,14 +150,14 @@
Author
Examples
-
# Calculate movement angles
-mt_example<-mt_angles(mt_example)
-
-# Calculate movement angles (in degree)
-# and replace NAs with next existing value
-mt_example<-mt_angles(mt_example,
- unit="degree", na_replace=TRUE)
-
+
# Calculate movement angles
+mt_example<-mt_angles(mt_example)
+
+# Calculate movement angles (in degree)
+# and replace NAs with next existing value
+mt_example<-mt_angles(mt_example,
+ unit="degree", na_replace=TRUE)
+
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
dimensions
a character vector specifying the two dimensions in the
trajectory array that contain the mouse positions. Usually (and by
default), the first value in the vector corresponds to the x-positions
(xpos) and the second to the y-positions (ypos).
+
+
timestamps
a character string specifying the trajectory dimension
containing the timestamps. If NULL linearly increasing timestamps
are assumed, producing a perfectly constant timestamp interval.
+
+
filename
character string specifying the path and filename of the
resulting .gif. If the extension of filename is not
.gif, .gif is added at the end. Must not contain spaces.
+
+
xres
numeric specifying the resolution of the .gif file.
+
+
seconds
numeric specifying the duration of the .gif file.
+
+
framerate
numeric specifying the framerate of the .gif file.
Defaults to 24 implying smooth non-discrete frame transitions for the human
eye.
+
+
speed
numeric specifying the speed of the trajectories with regard to
their original velocity profile. I.e., a value of .5 shows trajectories in
half of the original velocities, whereas a value of 2 shows trajectories in
double of the original velocities.
+
+
density
integer specifying the number of trajectories to be added
each frame. I.e., if density = 10, seconds = 10,
framerate = 24 and speed = .5 then the animation will show 10
x 10 x 24 x .5 = 1200 trajectories.
+
+
jitter
logical specifying whether the density should be jittered. If
TRUE, density varies according to
rgeom (1/density).
+
+
remove
logical specifying whether trajectories that reached their end
points should be removed from the rest of the animation. Defaults to
FALSE implying that all finished trajectories remain visible.
+
+
bg
character string specifying the background color.
+
+
col
character string specifying the foreground color, i.e., the color
used to draw the trajectories.
+
+
lwd
numeric specifying the line width of the trajectories.
+
+
loop
logical specifying whether gif should be looped. If FALSE
(the default), the last frame will remain visible after the animation is
finished. If TRUE, the gif will infinitely repeat itself.
+
+
bounds
numeric vector specifying the xleft, xright, ybottom, and ytop
limits of the animation canvas. Defaults to NULL in which case the
animation canvas is set to include all existing trajectory points,
irrespective of how extreme they may be.
+
+
norm
logical specifying whether the trajectories should be remapped to
the mt-space. See mt_align. Note that aligning often requires
that that all trajectories are flipped to one side first (see
mt_remap_symmetric).
+
+
upscale
numeric specifying a scaling factor for the animation
resolution. E.g, upscale = 2 implies that the x-resolution in
.gif file is 2*xres.
+
+
decay
numeric defining a within-trajectory gradient of color intensity.
Specifically, values larger than 1 will give more recent movements higher
color intensities than movements that lie longer in the past, and vice
versa.
+
+
max_intensity
numeric specifying the maximum color intensity. A value
of, e.g., 5, implies that color intensity is limited to 5 overlapping
@@ -175,24 +215,33 @@
Arguments
overlap, but there will be no difference between the latter and a point at
which 6 trajectories overlap. If decay is unequal 1, this metric
refers to the most intense color point within the trajectory.
+
+
discard_images
logical specifying whether the temporary folder
containing the temporary .png images should be deleted. Defaults to
TRUE.
+
+
im_path
character string specifying the location of ImageMagick's
convert function. If NULL, the convert function is
expected in '/usr/local/bin/convert', the default location for Linux
and OSX operating systems. The location has to be specified explicitly for
Windows (see Details and Examples).
+
+
parallel
logical specifying whether the temporary .png images
should be created using parallel processing (uses
clusterApplyLB). Process will be run on the maximum
number of available cores (as determined by detectCores).
+
+
verbose
logical indicating whether function should report its
progress.
+
Details
@@ -229,26 +278,26 @@
Author
Examples
-
if(FALSE){
-# Preprocess trajectory data
-mt_example<-mt_align_start(mt_example)
-mt_example<-mt_remap_symmetric(mt_example)
-
-# Create animated trajectory gif
-# (under Linux / OSX)
-mt_animate(mt_example,filename ="MyMovie.gif")
-
-# Increase duration and density while decreasing speed
-mt_animate(mt_example, filename ="MyMovie2.gif",
- seconds =10, speed =.3, density =10)
-
-# Create animated trajectory gif
-# (under Windows - ImageMagick version specific example)
-mt_animate(mt_example,filename ="MyMovie.gif",
- im_path ="C:/Program Files/ImageMagick-7.0.5-Q16/convert.exe")
-
-}
-
+
if(FALSE){
+# Preprocess trajectory data
+mt_example<-mt_align_start(mt_example)
+mt_example<-mt_remap_symmetric(mt_example)
+
+# Create animated trajectory gif
+# (under Linux / OSX)
+mt_animate(mt_example,filename ="MyMovie.gif")
+
+# Increase duration and density while decreasing speed
+mt_animate(mt_example, filename ="MyMovie2.gif",
+ seconds =10, speed =.3, density =10)
+
+# Create animated trajectory gif
+# (under Windows - ImageMagick version specific example)
+mt_animate(mt_example,filename ="MyMovie.gif",
+ im_path ="C:/Program Files/ImageMagick-7.0.5-Q16/convert.exe")
+
+}
+
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
save_as
a character string specifying where the resulting trajectory
data should be stored.
+
+
dimensions
a character vector specifying the dimensions in the
trajectory array that should be averaged. By default ("all"), all
trajectory dimensions will be averaged.
+
+
av_dimension
a character string specifying which values should be used
for determining the intervals for averaging ("timestamps" by
default).
+
+
intervals
an optional numeric vector. If specified, these values are
taken as the borders of the intervals (interval_size and
max_interval are ignored).
+
+
interval_size
an integer specifying the size of the constant dimension
interval.
+
+
max_interval
an integer specifying the upper limit of the last
dimension value that should be included (therefore, it should be a multiple
of the interval_size). If specified, only values will be used for
averaging where the dimension values are smaller than max_interval.
If unspecified (the default), all values will be included.
+
+
verbose
logical indicating whether function should report its
progress.
+
Value
-
A mousetrap data object (see mt_example) with an additional
+
+
+
A mousetrap data object (see mt_example) with an additional
array (by default called av_trajectories) that contains the average
trajectory data per dimension interval. If a trajectory array was provided
-directly as data, only the average trajectories will be returned.
-For the dimension values used for averaging (specified in
+directly as data, only the average trajectories will be returned.
+
+
+
For the dimension values used for averaging (specified in
av_dimension), the mid point of the respective interval is reported,
which is helpful for plotting the trajectory data later on. However, this
value does not necessarily correspond to the empirical mean of the
@@ -161,19 +182,19 @@
Author
Examples
-
mt_example<-mt_derivatives(mt_example)
-
-# average trajectories across 100 ms intervals
-mt_example<-mt_average(mt_example, save_as="av_trajectories",
- interval_size=100)
-
-# average time-normalized trajectories across specific intervals
-# of the time steps
-mt_example<-mt_time_normalize(mt_example)
-mt_example<-mt_average(mt_example,
- use="tn_trajectories", save_as="av_tn_trajectories",
- av_dimension ="steps", intervals =c(0.5,33.5,67.5,101.5))
-
+
mt_example<-mt_derivatives(mt_example)
+
+# average trajectories across 100 ms intervals
+mt_example<-mt_average(mt_example, save_as="av_trajectories",
+ interval_size=100)
+
+# average time-normalized trajectories across specific intervals
+# of the time steps
+mt_example<-mt_time_normalize(mt_example)
+mt_example<-mt_average(mt_example,
+ use="tn_trajectories", save_as="av_tn_trajectories",
+ av_dimension ="steps", intervals =c(0.5,33.5,67.5,101.5))
+
mt_check_bimodality(
+data,
+ use ="measures",
+ use_variables =NULL,
+ methods =c("BC", "HDS"),
+ B =2000,
+ grouping_variables =NULL,
+...
+)
@@ -78,32 +78,47 @@
Arguments
data
a mousetrap data object created using one of the mt_import
functions (see mt_example for details).
+
+
use
a character string specifying which data should be used. By
default, points to the measures data.frame created using
mt_measures.
+
+
use_variables
a vector specifying for which mouse-tracking measures
bimodality should be assessed.
+
+
methods
a character string (or vector) specifying which methods should
be used for assessing bimodality (see Details).
+
+
B
an integer specifying the number of replicates used in the Monte
Carlo test (only relevant if "HDS_sim" is included in methods, see
Details).
+
+
grouping_variables
a character string (or vector) specifying one or
more variables in data[["data"]]. If specified, bimodality will be
assessed separately for each level of the variable. If unspecified (the
default), bimodality is checked across all trials.
+
+
...
additional arguments passed on to mt_reshape (such as
subset).
+
Value
-
A list of several data.frames. Each data.frame contains the value
+
+
+
A list of several data.frames. Each data.frame contains the value
returned by the respective method for assessing bimodality (see Details) -
separately per condition (specified in the row dimension) and measure
(specified in the column dimension).
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
timestamps
a character string specifying the trajectory dimension
containing the timestamps.
+
+
desired
an optional integer. If specified, additional statistics are
computed concerning the (relative) frequencies with which exactly the
desired timestamp difference (with tolerance 1e-12) occurred.
+
+
digits
an optional integer. If specified, timestamps will be rounded
before performing any checks. Potentially useful if timestamps are recorded
with submillisecond precision.
+
Value
-
A list with various descriptive statistics. For convenience, the
+
+
+
A list with various descriptive statistics. For convenience, the
relative frequencies are rounded to 4 decimal places.
@@ -115,7 +126,7 @@
Author
Examples
-
mt_check_resolution(mt_example)
+
mt_check_resolution(mt_example)#> $summary#> Min. 1st Qu. Median Mean 3rd Qu. Max. #> 1.000 10.000 10.000 9.977 10.000 14.000
@@ -133,7 +144,7 @@
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
save_as
a character string specifying where the resulting data should
be stored.
+
+
dimensions
a character vector specifying which trajectory variables
should be used. Can be of length 2 or 3, for two-dimensional or
three-dimensional trajectories respectively.
+
+
n_cluster
an integer specifying the number of clusters to estimate.
+
+
method
character string specifying the clustering procedure. Either
hclust (the default) or kmeans.
+
+
weights
numeric vector specifying the relative importance of the
variables specified in dimensions. Defaults to a vector of 1s
implying equal importance. Technically, each variable is rescaled so that
the standard deviation matches the corresponding value in weights.
To use the original variables, set weights = NULL.
+
+
pointwise
boolean specifying the way in which dissimilarity between
the trajectories is measured. If TRUE (the default),
@@ -113,39 +127,54 @@
Arguments
(by treating the various points as independent dimensions). This is only
relevant if method is "hclust". See mt_distmat for further
details.
+
+
minkowski_p
an integer specifying the distance metric for the cluster
solution. minkowski_p = 1 computes the city-block distance,
minkowski_p = 2 (the default) computes the Euclidian distance,
minkowski_p = 3 the cubic distance, etc. Only relevant if
method is "hclust". See mt_distmat for further details.
+
+
hclust_method
character string specifying the linkage criterion used.
Passed on to the method argument of hclust. Default is
set to ward.D. Only relevant if method is "hclust".
+
+
kmeans_nstart
integer specifying the number of reruns of the kmeans
procedure. Larger numbers minimize the risk of finding local minima. Passed
on to the nstart argument of kmeans. Only relevant if
method is "kmeans".
+
+
na_rm
logical specifying whether trajectory points containing NAs
should be removed. 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. This is necessary to compute distance
between trajectories.
+
+
cluster_output
logical. If FALSE (the default), the mousetrap
data object with the cluster assignments is returned (see Value). If
TRUE, the output of the cluster method (kmeans or
hclust) is returned directly.
+
+
verbose
logical indicating whether function should report its
progress.
+
Value
-
A mousetrap data object (see mt_example) with an additional
+
+
+
A mousetrap data object (see mt_example) with an additional
data.frame added to it (by default called clustering) that
contains the cluster assignments. If a trajectory array was provided
directly as data, only the clustering data.frame will be
@@ -177,7 +206,7 @@
Details
top-left corner of the coordinate system (mt_remap_symmetric or
mt_align can be used to achieve this). Furthermore, it is recommended
to use length normalized trajectories (see mt_length_normalize; Wulff
-et al., 2019, Wulff et al., 2021).
+et al., 2019, Wulff et al., 2023).
References
@@ -187,9 +216,9 @@
References
Johnson (Eds.), 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. (2021). Movement tracking of cognitive
+Schulte-Mecklenbeck, M. (2023). 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. (2022).
Measuring the (dis-)continuous mind: What movement trajectories
reveal about cognition. Manuscript in preparation.
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
dimensions
a character vector specifying which trajectory variables
should be used. Can be of length 2 or 3, for two-dimensional or
three-dimensional trajectories respectively.
+
+
kseq
a numeric vector specifying set of candidates for k. Defaults to
2:15, implying that all values of k within that range are compared using
the metrics specified in compute.
+
+
compute
character vector specifying the to be computed measures. Can
be any subset of c("stability","gap","jump","slope").
+
+
method
character string specifying the type of clustering procedure
for the stability-based method. Either hclust or kmeans.
+
+
weights
numeric vector specifying the relative importance of the
variables specified in dimensions. Defaults to a vector of 1s
implying equal importance. Technically, each variable is rescaled so that
the standard deviation matches the corresponding value in weights.
To use the original variables, set weights = NULL.
+
+
pointwise
boolean specifying the way in which dissimilarity between
the trajectories is measured. If TRUE (the default),
@@ -113,44 +127,63 @@
Arguments
(by treating the various points as independent dimensions). This is only
relevant if method is "hclust". See mt_distmat for further
details.
+
+
minkowski_p
an integer specifying the distance metric for the cluster
solution. minkowski_p = 1 computes the city-block distance,
minkowski_p = 2 (the default) computes the Euclidian distance,
minkowski_p = 3 the cubic distance, etc. Only relevant if
method is "hclust". See mt_distmat for further details.
+
+
hclust_method
character string specifying the linkage criterion used.
Passed on to the method argument of hclust. Default is
set to ward.D. Only relevant if method is "hclust".
+
+
kmeans_nstart
integer specifying the number of reruns of the kmeans
procedure. Larger numbers minimize the risk of finding local minima. Passed
on to the nstart argument of kmeans. Only relevant if
method is "kmeans".
+
+
n_bootstrap
an integer specifying the number of bootstrap comparisons
used by stability. See cStability.
+
+
model_based
boolean specifying whether the model-based or the
model-free should be used by stability, when method is
kmeans. See cStability and Haslbeck & Wulff (2020).
+
+
n_gap
integer specifying the number of simulated datasets used by
gap. See Tibshirani et al. (2001).
+
+
na_rm
logical specifying whether trajectory points containing NAs
should be removed. 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. This is necessary to compute distance
between trajectories.
+
+
verbose
logical indicating whether function should report its
progress.
+
Value
-
A list containing two lists that store the results of the different
+
+
+
A list containing two lists that store the results of the different
methods. kopt contains the estimated k for each of the
methods specified in compute. paths contains the values for
each k in kseq as computed by each of the methods specified
@@ -213,19 +246,19 @@
mt_count(data, use ="trajectories", save_as ="measures", dimensions ="xpos")
+
mt_count(data, use ="trajectories", save_as ="measures", dimensions ="xpos")
@@ -69,24 +69,40 @@
Arguments
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
save_as
a character string specifying where the resulting trajectory
data should be stored.
+
+
dimensions
a character vector specifying the name of the dimension(s)
that should be used for counting the number of observations. If several
dimensions are specified, the number of complete observations are reported.
+
Value
-
A mousetrap data object (see mt_example).
-If a data.frame with label specified in save_as (by default
+
+
+
If a data.frame with label specified in save_as (by default
"measures") already exists, the number of observations (called nobs)
-are added as additional column. If not, an additional data.framewill be added.
-If a trajectory array was provided directly as data, only a named
+are added as additional column. If not, an additional data.frame
+
+
+
will be added.
+
+
+
If a trajectory array was provided directly as data, only a named
character vector will be returned.
@@ -96,15 +112,15 @@
Author
Examples
-
# Retrieve vector that counts number of observations
-mt_count(mt_example$trajectories)
+
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
save_as
a character string specifying where the resulting trajectory
data should be stored.
+
+
dimensions
a character vector specifying across which dimension(s)
distances, velocity, and acceleration are calculated. By default
(c("xpos","ypos")), they are calculated across both x and y
dimensions. Alternatively, only one dimension can be specified, e.g.,
"xpos" or "ypos".
+
+
timestamps
a character string specifying the trajectory dimension
containing the timestamps.
+
+
prefix
an optional character string that is added as a prefix to the
to be created new trajectory dimensions.
+
+
absolute
logical indicating if absolute values for distances and
velocities should be reported. Only relevant if a single dimension is
specified in dimensions (see Details).
+
+
return_delta_time
logical indicating if the timestamp differences
should be returned as well (as "delta_time").
+
+
verbose
logical indicating whether function should report its
progress.
+
Value
-
A mousetrap data object (see mt_example) with Euclidian
+
+
+
A mousetrap data object (see mt_example) with Euclidian
distance, velocity, and acceleration added as additional variables to the
trajectory array (called dist, vel, and acc, if no
prefix was specified). If the trajectory array was provided directly as
@@ -157,15 +176,15 @@
Author
Examples
-
# Calculate derivatives looking at movement
-# across both dimensions
-mt_example<-mt_derivatives(mt_example)
-
-# Calculate derivatives only looking at movement along x dimension
-# reporting absolute values for distance and velocity
-mt_example<-mt_derivatives(mt_example,
- dimensions="xpos", absolute=TRUE)
-
+
# Calculate derivatives looking at movement
+# across both dimensions
+mt_example<-mt_derivatives(mt_example)
+
+# Calculate derivatives only looking at movement along x dimension
+# reporting absolute values for distance and velocity
+mt_example<-mt_derivatives(mt_example,
+ dimensions="xpos", absolute=TRUE)
+
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
save_as
a character string specifying where the resulting trajectory
data should be stored.
+
+
dimensions
a character vector specifying the two dimensions in the
trajectory array that contain the mouse positions. By default
(c("xpos","ypos")), the x- and y-positions are used.
+
+
start_ideal
an optional vector specifying the start position (see
Example). If specified, this position will be used as the starting point of
the idealized trajectory (instead of the actual starting point).
+
+
end_ideal
an optional vector specifying the end position (see
Example). If specified, this position will be used as the end point of the
idealized trajectory (instead of the actual end point).
+
+
prefix
an optional character string that is added as a prefix to the
to be created new trajectory dimensions.
+
+
verbose
logical indicating whether function should report its
progress.
+
Value
-
A mousetrap data object (see mt_example) where the positions
+
+
+
A mousetrap data object (see mt_example) where the positions
of the idealized trajectory (by default called xpos_ideal and
ypos_ideal) and the perpendicular deviations of the actual
trajectory from the idealized trajectory (by default called
@@ -144,15 +161,15 @@
Author
Examples
-
# Calculate deviations from idealized trajectory
-# (straight line connecting the start and end point of each trial)
-mt_example<-mt_deviations(mt_example)
-
-# Calculate deviations from idealized trajectory with
-# constant start and end points across trials
-mt_example<-mt_deviations(mt_example,
- start_ideal=c(0,0), end_ideal=c(-665,974))
-
+
# Calculate deviations from idealized trajectory
+# (straight line connecting the start and end point of each trial)
+mt_example<-mt_deviations(mt_example)
+
+# Calculate deviations from idealized trajectory with
+# constant start and end points across trials
+mt_example<-mt_deviations(mt_example,
+ start_ideal=c(0,0), end_ideal=c(-665,974))
+
an object of class mousetrap), a trajectory object of class
array, or an object of class mt_heatmap_raw (as created by
mt_heatmap_raw).
+
+
y
an object of class mousetrap), a trajectory object of class
array, or an object of class mt_heatmap_raw (as created by
mt_heatmap_raw). The class of y must match the class of
x, unless y is NULL.
+
+
condition
either a character value specifying which variable codes the
two conditions (in x[[use2]]) that should be compared - or a vector
@@ -99,57 +103,84 @@
Arguments
trajectories between the two conditions. If condition is specified,
y will be ignored (unless x and y are of class
heatmap_raw).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
dimensions
a character vector specifying the trajectory variables used
to create the heatmap. The first two entries are used as x and
y-coordinates, the third, if provided, will be added as color information.
+
+
use2
an optional character string specifying where the data that
contain the condition variable can be found. Defaults to "data" as
x[["data"]] usually contains all non mouse-tracking trial data.
+
+
filename
a character string giving the name of the file. If
NULL (the default), the R standard device is used for plotting.
Otherwise, the plotting device is inferred from the file extension. Only
supports devices tiff, png,
pdf.
+
+
bounds
numeric vector specifying the corners (xmin, ymin, xmax, ymax)
of the plot region. By default (bounds = NULL), bounds are
determined based on the data input.
+
+
xres
an integer specifying the number of pixels along the x-dimension.
An xres of 1000 implies an 1000*N px, where N is determined so that
the trajectories aspect ratio is preserved (provided the bounds are
unchanged).
+
+
upscale
a numeric value by which the output resolution of the image is
increased or decreased. Only applies if device is one of tiff, png, or pdf.
+
+
smooth_radius
a numeric value specifying the standard deviation of the
gaussian smoothing. If zero, smoothing is omitted.
+
+
colors
a character vector specifying the colors used to color
cases of image1 > image2, image1 ~ image2, image1 < image2,
respectively. Note that the colors are used in that specific order.
Defaults to c("#00863F", "#FFFFFF", "#FF1900") which specifies
a green-black-red color gradient.
+
+
n_shades
integer specifying the number of shades for the color
gradient between the first and second, and the second and third color in
colors.
+
+
plot
logical specifying whether resulting image should be plotted
(plot = TRUE, the default). If (plot = FALSE), an object of
class mt_object_raw is returned.
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
save_as
a character string specifying where the resulting data should
be stored.
+
+
dimensions
a character vector specifying which trajectory variables
should be used. Can be of length 2 or 3 for two-dimensional or
three-dimensional trajectories respectively.
+
+
weights
numeric vector specifying the relative importance of the
variables specified in dimensions. Defaults to a vector of 1s
implying equal importance. Technically, each variable is rescaled so that
the standard deviation matches the corresponding value in weights.
To use the original variables, set weights = NULL.
+
+
pointwise
boolean specifying the way dissimilarity between the
trajectories is measured (see Details). If TRUE (the default),
mt_distmat measures the average dissimilarity and then sums the
results. If FALSE, mt_distmat measures dissimilarity once
(by treating the various points as independent dimensions).
+
+
minkowski_p
an integer specifying the distance metric.
minkowski_p = 1 computes the city-block distance, minkowski_p
= 2 (the default) computes the Euclidian distance, minkowski_p = 3
the cubic distance, etc.
+
+
na_rm
logical specifying whether trajectory points containing NAs
should be removed. 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. This is necessary to compute distance
between trajectories.
+
Value
-
A mousetrap data object (see mt_example) with an additional
+
+
+
A mousetrap data object (see mt_example) with an additional
object added (by default called distmat) containing the distance
matrix. If a trajectory array was provided directly as data, only
the distance matrix will be returned.
Raw mouse-tracking dataset for demonstrations of the mousetrap package
-
mt_example_raw
+
mt_example_raw
@@ -111,10 +111,10 @@
Details
References
Kieslich, P. J., & Henninger, F. (2017). Mousetrap: An
integrated, open-source mouse-tracking package. Behavior Research
-Methods, 49(5), 1652-1667. doi: 10.3758/s13428-017-0900-z
Dale, R., Kehoe, C., & Spivey, M. J. (2007). Graded motor responses in the
time course of categorizing atypical exemplars. Memory & Cognition,
-35(1), 15-28. doi: 10.3758/BF03195938
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
save_as
a character string specifying where the resulting trajectory
data should be stored.
+
+
dimensions
a character vector specifying the dimensions in the
trajectory array that contain the mouse positions.
+
+
timestamps
a character string specifying the trajectory dimension
containing the timestamps.
+
+
verbose
logical indicating whether function should report its
progress.
+
Value
-
A mousetrap data object (see mt_example) from which a
+
+
+
A mousetrap data object (see mt_example) from which a
potential phase without mouse movement at the end of the trial was removed.
If the trajectory array was provided directly as data, only the
trajectory array will be returned.
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
save_as
a character string specifying where the resulting trajectory
data should be stored.
+
+
dimensions
a character vector specifying the dimensions in the
trajectory array that contain the mouse positions.
+
+
timestamps
a character string specifying the trajectory dimension
containing the timestamps.
+
+
reset_timestamps
logical indicating whether the timestamps should be
reset after removing the initial phase without movement (see Details).
+
+
verbose
logical indicating whether function should report its
progress.
+
Value
-
A mousetrap data object (see mt_example) from which the
+
+
+
A mousetrap data object (see mt_example) from which the
initial phase without mouse movement was removed. If the trajectory array
was provided directly as data, only the trajectory array will be
returned.
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which data should be exported. The
corresponding data are selected from data using data[[use]].
Usually, this value corresponds to either "trajectories" or
"tn_trajectories", depending on whether the raw or the time-normalized
trajectories should be exported.
+
+
use_variables
a character vector specifying which mouse-tracking
variables should be exported. This corresponds to the labels of the
trajectory array dimensions. If unspecified, all variables will be
exported.
+
+
use2
an optional character string specifying where the other trial
data can be found. Defaults to "data" as data[["data"]] usually
contains all non mouse-tracking trial data. Alternatively, a data.frame can
be provided directly.
+
+
use2_variables
an optional character string (or vector) specifying the
variables (in data[[use2]]) that should be merged with the data.
+
+
...
additional arguments passed on to mt_reshape (such as
subset).
mt_export_long: Export mouse-tracking data in long format
-
mt_export_wide: Export mouse-tracking data in wide format
+
mt_export_long(): Export mouse-tracking data in long format
+
mt_export_wide(): Export mouse-tracking data in wide format
See also
@@ -137,16 +150,16 @@
Author
Examples
-
# Export data in long format
-# (and include information about condition and subject_nr)
-mt_data_long<-mt_export_long(mt_example,
- use2_variables=c("subject_nr","Condition"))
-
-# Export data in wide format
-# (and include information about condition and subject_nr)
-mt_data_wide<-mt_export_wide(mt_example,
- use2_variables=c("subject_nr","Condition"))
-
+
# Export data in long format
+# (and include information about condition and subject_nr)
+mt_data_long<-mt_export_long(mt_example,
+ use2_variables=c("subject_nr","Condition"))
+
+# Export data in wide format
+# (and include information about condition and subject_nr)
+mt_data_wide<-mt_export_wide(mt_example,
+ use2_variables=c("subject_nr","Condition"))
+
usually an object of class mousetrap. Alternatively, a
trajectory array or an object of class mt_heatmap_raw.
+
+
use
a character string specifying which trajectory data should be
used.
+
+
dimensions
a character vector specifying the trajectory variables used
to create the heatmap. The first two entries are used as x and
y-coordinates, the third, if provided, will be added as color information.
+
+
filename
a character string giving the name of the file. If
NULL (the default), the R standard device is used for plotting.
Otherwise, the plotting device is inferred from the file extension. Only
supports devices tiff, png,
pdf.
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
dimensions
a character vector specifying the trajectory variables used
to create the heatmap. The first two entries are used as x and
y-coordinates, the third, if provided, will be added as color information.
+
+
use2
an optional character string specifying where the data that
contain the variables used for faceting can be found (in case these
arguments are specified). Defaults to "data" as data[["data"]]
usually contains all non mouse-tracking trial data.
+
+
facet_row
an optional character string specifying a variable in
data[[use2]] that should be used for (row-wise) faceting.
+
+
facet_col
an optional character string specifying a variable in
data[[use2]] that should be used for (column-wise) faceting.
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
dimensions
a character vector specifying the trajectory variables used
to create the heatmap. The first two entries are used as x and
y-coordinates, the third, if provided, will be added as color information.
+
+
variable
boolean or numeric vector matching the number of trajectories
that if provided will be used as color information. variable is only
considered when length(dimensions) < 3.
+
+
bounds
numeric vector specifying the corners (xmin, ymin, xmax, ymax)
of the plot region. By default (bounds = NULL), bounds are
determined based on the data input.
+
+
xres
an integer specifying the number of pixels along the x-dimension.
An xres of 1000 implies an 1000*N px, where N is determined so that
the trajectories aspect ratio is preserved (provided the bounds are
unchanged).
+
+
upsample
a numeric value by which the number of points used to
represent individual trajectories are increased or decreased. Values of
smaller than one will improve speed but also introduce a certain level of
granularity.
+
+
norm
a logical specifying whether the data should be warped into
standard space. If norm = TRUE, this overrules bounds.
+
+
colors
a character vector specifying two or three colors used to color
the background, the foreground (trajectories), and the values of a third
dimension (if specified).
+
+
n_shades
an integer specifying the number of shades for the color
gradient between the first and second, and the second and third color in
colors.
+
+
smooth_radius
a numeric value specifying the standard deviation of the
gaussian smoothing. If zero, smoothing is omitted.
+
+
low_pass
an integer specifying the allowed number of counts per pixel.
This arguments limits the maximum pixel color intensity.
+
+
auto_enhance
boolean. If TRUE (the default), the image is
adjusted so that the mean color intensity matches mean_image and
mean_color.
+
+
mean_image
a numeric value between 0 and 1 specifying the average
foreground color intensity across the entire image. Defaults to 0.1.
+
+
mean_color
a numeric value between 0 and 1 specifying the average
third dimension's color intensity across the entire image. Defaults to 0.1.
Only relevant if a third dimension is specified in colors.
+
+
aggregate_lwd
an integer specifying the width of the aggregate
trajectory. If aggregate_lwd is 0 (the default), the aggregate
trajectory is omitted.
+
+
aggregate_col
a character value specifying the color of the aggregate
trajectory.
+
+
n_trajectories
an optional integer specifying the number of
trajectories used to create the image. By default, all trajectories are
used. If n_trajectories is specified and smaller than the number of
trajectories in the trajectory array, then n_trajectories are
randomly sampled.
+
+
seed
an optional integer specifying the seed used for the trajectory
sampling.
+
+
verbose
logical indicating whether function should report its
progress.
+
Value
-
An object of class mt_object_raw containing in a matrix format
+
+
+
An object of class mt_object_raw containing in a matrix format
the image's pixel information, the aggregate trajectory, and the colors.
package. Specifically, it returns a list that includes the trajectory data as
an array (called trajectories), and all other data as a data.frame
(called data). This data structure can then be passed on to other
-functions within this package (see mousetrap for an overview).
+functions within this package (see mousetrap for an overview).
a data.frame in long format, containing the raw data.
+
+
xpos_label
a character string specifying the column containing the
x-positions.
+
+
ypos_label
a character string specifying the column containing the
y-positions.
+
+
zpos_label
an optional character string specifying the column
containing the z-positions.
+
+
timestamps_label
a character string specifying the column containing
the timestamps. If no timestamps are found in the data, a timestamps
variable with increasing integers will be created (assuming equidistant
time steps).
+
+
add_labels
a character vector specifying columns containing additional
mouse-tracking variables.
+
+
mt_id_label
a character string (or vector) specifying the name of the
column that provides a unique ID for every trial (the trial identifier). If
@@ -118,22 +130,31 @@
Arguments
by combining the values of each variable. The trial identifier will be set
as the rownames of the resulting trajectories and trial data, and
additionally be stored in the column "mt_id" in the trial data.
+
+
mt_seq_label
a character string specifying the column that indicates
the order of the logged coordinates within a trial. If no column of the
specified name is found in the data.frame, the coordinates will be imported
in the order in which they were stored in raw_data.
+
+
reset_timestamps
logical indicating if the first timestamp should be
subtracted from all timestamps within a trial. Default is TRUE as it
is recommended for all following analyses in mousetrap.
+
+
verbose
logical indicating whether function should report its
progress.
# Create data in long format for test purposes
-mt_data_long<-mt_export_long(mt_example,
- use2_variables=c("subject_nr","Condition"))
-
-# Import the data using mt_import_long
-mt_data<-mt_import_long(mt_data_long)
-
-
-if(FALSE){
-# Import a hypothetical dataset that contains the
-# custom mouse-tracking variables angle and velocity
-mt_data<-mt_import_long(exp_data,
- add_labels=c("angle", "velocity"))
-}
-
+
# Create data in long format for test purposes
+mt_data_long<-mt_export_long(mt_example,
+ use2_variables=c("subject_nr","Condition"))
+
+# Import the data using mt_import_long
+mt_data<-mt_import_long(mt_data_long)
+
+
+if(FALSE){
+# Import a hypothetical dataset that contains the
+# custom mouse-tracking variables angle and velocity
+mt_data<-mt_import_long(exp_data,
+ add_labels=c("angle", "velocity"))
+}
+
Import mouse-tracking data recorded using the mousetrap plug-ins in OpenSesa
package. Specifically, it returns a list that includes the trajectory data as
an array (called trajectories), and all other data as a data.frame
(called data). This data structure can then be passed on to other
-functions within this package (see mousetrap for an overview).
+functions within this package (see mousetrap for an overview).
a character string specifying the name of the column(s) in
which the x-positions are stored (see Details).
+
+
ypos_label
a character string specifying the name of the column(s) in
which the y-positions are stored (see Details).
+
+
timestamps_label
a character string specifying the name of the column(s)
in which the timestamps are stored (see Details).
+
+
mt_id_label
an optional character string (or vector) specifying the
name of the column that provides a unique ID for every trial (the trial
@@ -113,32 +121,49 @@
Arguments
identifier will be set as the rownames of the resulting trajectories
and trial data, and additionally be stored in the column "mt_id" in the
trial data.
+
+
split
a character string indicating how the different timestamps and
coordinates within a trial are separated.
+
+
duplicates
a character string indicating how duplicate timestamps
within a trial are handled (see Details).
+
+
unordered
a character string indicating how unordered (i.e.,
non-monotonically increasing) timestamps within a trial are handled (see
Details).
+
+
reset_timestamps
logical indicating if the first timestamp should be
subtracted from all timestamps within a trial. Default is TRUE as it
is recommended for all following analyses in mousetrap.
+
+
digits
an optional integer. If specified, timestamps will be rounded.
Potentially useful if timestamps are recorded with submillisecond
precision.
+
+
verbose
logical indicating whether function should report its
progress.
+
Value
-
A mousetrap data object (see mt_example).
-If mouse-tracking data were recorded using the mousetrap plug-ins for
+
+
+
If mouse-tracking data were recorded using the mousetrap plug-ins for
OpenSesame, the unit of the timestamps is milliseconds.
@@ -182,7 +207,7 @@
Details
References
Kieslich, P. J., & Henninger, F. (2017). Mousetrap: An
integrated, open-source mouse-tracking package. Behavior Research
-Methods, 49(5), 1652-1667. doi: 10.3758/s13428-017-0900-z
list that includes the trajectory data as an array (called
trajectories), and all other data as a data.frame (called
data). This data structure can then be passed on to other functions
-within this package (see mousetrap for an overview).
+within this package (see mousetrap for an overview).
a character string specifying the core of the column labels
containing the x-positions (e.g., "X" for "X_1", "X_2", ...).
+
+
ypos_label
a character string specifying the core of the column labels
containing the y-positions (e.g., "Y" for "Y_1", "Y_2", ...).
+
+
zpos_label
a character string specifying the core of the column labels
containing the z-positions.
+
+
timestamps_label
an optional character string specifying the core of
the column labels containing the timestamps. If no timestamps are found in
the data, a timestamps variable with increasing integers will be created
(assuming equidistant time steps).
+
+
add_labels
a character vector specifying the core of columns
containing additional mouse-tracking variables.
+
+
mt_id_label
an optional character string (or vector) specifying the
name of the column that provides a unique ID for every trial (the trial
@@ -123,25 +135,36 @@
Arguments
identifier will be set as the rownames of the resulting trajectories
and trial data, and additionally be stored in the column "mt_id" in the
trial data.
+
+
pos_sep
a character string indicating the character that connects the
core label and the position, (e.g., "_" for "X_1", "Y_1", ...).
+
+
pos_ids
the vector of IDs used for indexing the x-coordinates,
y-coordinates etc. (e.g., 1:101 for time-normalized trajectories from
MouseTracker). If unspecified (the default), column labels for the
respective variable will be extracted using grep (see Details).
+
+
reset_timestamps
logical indicating if the first timestamp should be
subtracted from all timestamps within a trial. Default is TRUE as it
is recommended for all following analyses in mousetrap.
+
+
verbose
logical indicating whether function should report its
progress.
# Create data in wide format for test purposes
-mt_data_wide<-mt_export_wide(mt_example,
- use2_variables=c("subject_nr", "Condition"))
-
-# Import the data using mt_import_wide
-mt_data<-mt_import_wide(mt_data_wide,
- xpos_label="xpos", ypos_label="ypos",
- timestamps_label="timestamps")
+
# Create data in wide format for test purposes
+mt_data_wide<-mt_export_wide(mt_example,
+ use2_variables=c("subject_nr", "Condition"))
+
+# Import the data using mt_import_wide
+mt_data<-mt_import_wide(mt_data_wide,
+ xpos_label="xpos", ypos_label="ypos",
+ timestamps_label="timestamps")#> No mt_id_label provided. A new trial identifying variable called mt_id was created.#> No pos_ids provided. The following variables were found using grep:#> 465 variables found for timestamps.#> 465 variables found for xpos.#> 465 variables found for ypos.
-
+
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
dimensions
a character string specifying which trajectory variables
should be used. Can be of length 2 or 3 for two-dimensional or
three-dimensional data.
+
+
save_as
a character string specifying where the resulting trajectory
data should be stored.
+
+
n_points
an integer or vector of integers specifying the number of
points used to represent the spatially rescaled trajectories. If a single
integer is provided, the number of points will be constant across
trajectories. Alternatively, a vector of integers can provided that specify
the number of points for each trajectory individually.
+
Value
-
A mousetrap data object (see mt_example) with an additional
+
+
+
A mousetrap data object (see mt_example) with an additional
array (by default called ln_trajectories) containing the length
normalized trajectories. If a trajectory array was provided directly as
data, only the length normalized trajectories will be returned.
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
save_as
a character string specifying where the resulting data should
be stored.
+
+
dimensions
a character vector specifying which trajectory variables
should be used. Can be of length 2 or 3 for two-dimensional or
three-dimensional trajectories respectively.
+
+
prototypes
a trajectory array containing the prototypes the
trajectories are mapped to. As a starting point, the trajectories stored in
mt_prototypes can be used. See Details and Examples for selecting
prototypes and creating new ones.
+
+
weights
numeric vector specifying the relative importance of the
variables specified in dimensions. Defaults to a vector of 1s
implying equal importance. Technically, each variable is rescaled so that
the standard deviation matches the corresponding value in weights.
To use the original variables, set weights = NULL.
+
+
pointwise
boolean specifying the way dissimilarity between the
trajectories is measured (see Details). If TRUE (the default),
mt_distmat measures the average dissimilarity and then sums the
results. If FALSE, mt_distmat measures dissimilarity once
(by treating the various points as independent dimensions).
+
+
na_rm
logical specifying whether trajectory points containing NAs
should be removed. 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. This is necessary to compute distance
between trajectories.
+
+
minkowski_p
an integer specifying the distance metric.
minkowski_p = 1 computes the city-block distance, minkowski_p
= 2 (the default) computes the Euclidian distance, minkowski_p = 3
the cubic distance, etc.
+
+
use2
an optional character string specifying where the data that
contain the variables used for grouping can be found (in case
grouping_variables are specified). Defaults to "data" as
data[["data"]] usually contains all non mouse-tracking trial data.
+
+
grouping_variables
a character string (or vector) specifying one or
more variables in use2. If specified, prototypes will be rescaled
separately to match the coordinate system of the trajectories for each
level of the variable(s). If unspecified (the default), the prototypes are
rescaled in the same way across all trajectories.
+
Value
-
A mousetrap data object (see mt_example) with an additional
+
+
+
A mousetrap data object (see mt_example) with an additional
data.frame (by default called prototyping) that contains the
best fitting prototype for each trajectory (the number of the prototype is
specified under prototype, the label of the prototype under
@@ -161,7 +184,7 @@
Details
trajectories end in the top-left corner of the coordinate system
(mt_remap_symmetric or mt_align can be used to achieve this).
Furthermore, it is recommended to use length normalized trajectories (see
-mt_length_normalize; Wulff et al., 2019, Wulff et al., 2021).
+mt_length_normalize; Wulff et al., 2019, Wulff et al., 2023).
References
@@ -171,9 +194,9 @@
References
Johnson (Eds.), 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. (2021). Movement tracking of cognitive
+Schulte-Mecklenbeck, M. (2023). 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. (2022).
Measuring the (dis-)continuous mind: What movement trajectories
reveal about cognition. Manuscript in preparation.
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
save_as
a character string specifying where the calculated measures
should be stored.
+
+
dimensions
a character vector specifying the two dimensions in the
trajectory array that contain the mouse positions. Usually (and by
default), the first value in the vector corresponds to the x-positions
(xpos) and the second to the y-positions (ypos).
+
+
timestamps
a character string specifying the trajectory dimension
containing the timestamps.
+
+
flip_threshold
a numeric value specifying the distance that needs to
be exceeded in one direction so that a change in direction counts as a
flip. If several thresholds are specified, flips will be returned in
separate variables for each threshold value (the variable name will be
suffixed with the threshold value).
+
+
hover_threshold
an optional numeric value. If specified, hovers
(and hover_time) will be calculated as the number (and total time)
@@ -116,109 +128,151 @@
Arguments
hovers and hover_time will be returned in separate variables for each
threshold value (the variable name will be suffixed with the threshold
value).
+
+
hover_incl_initial
logical indicating if the calculation of hovers
should include a potential initial phase in the trial without mouse
movements (this initial phase is included by default).
+
+
initiation_threshold
a numeric value specifying the distance from the
start point of the trajectory that needs to be exceeded for calculating the
initiation time. By default, it is 0, meaning that any movement counts as
movement initiation.
+
+
verbose
logical indicating whether function should report its
progress.
+
Value
-
A mousetrap data object (see mt_example) where an additional
+
+
+
A mousetrap data object (see mt_example) where an additional
data.frame has been added (by default called "measures") containing
the per-trial mouse-tracking measures. Each row in the data.frame
corresponds to one trajectory (the corresponding trajectory is identified
via the rownames and, additionally, in the column "mt_id"). Each column in
the data.frame corresponds to one of the measures. If a trajectory array
was provided directly as data, only the measures data.frame will be
-returned.
-The following measures are computed for each trajectory (the labels
+returned.
+
+
+
The following measures are computed for each trajectory (the labels
relating to x- and y-positions will be adapted depending on the values
specified in dimensions). Please note that additional information is
provided in the Details section.
mt_id
Trial ID (can be used for merging measures data.frame with
other trial-level data)
+
xpos_max
Maximum x-position
+
xpos_min
Minimum x-position
+
ypos_max
Maximum y-position
+
ypos_min
Minimum y-position
+
MAD
Signed Maximum absolute deviation from the direct path
connecting start and end point of the trajectory (straight line).
If the MAD occurs above the direct path, this is denoted by
a positive value; if it occurs below, by a negative value.
+
MAD_time
Time at which the maximum absolute deviation was reached
first
+
MD_above
Maximum deviation above the direct path
+
MD_above_time
Time at which the maximum deviation above was reached
first
+
MD_below
Maximum deviation below the direct path
+
MD_below_time
Time at which the maximum deviation below was reached
first
+
AD
Average deviation from direct path
+
AUC
Area under curve, the geometric area between the actual
trajectory and the direct path where areas below the direct path have been
subtracted
+
xpos_flips
Number of directional changes along x-axis (exceeding the
distance specified in flip_threshold)
+
ypos_flips
Number of directional changes along y-axis (exceeding the
distance specified in flip_threshold)
+
xpos_reversals
Number of crossings of the y-axis
+
ypos_reversals
Number of crossings of the x-axis
+
RT
Response time, time at which tracking stopped
+
initiation_time
Time at which first mouse movement was initiated
+
idle_time
Total time without mouse movement across the entirety of
the trial
+
hover_time
Total time of all periods without movement in a trial
(whose duration exceeds the value specified in hover_threshold)
+
hovers
Number of periods without movement in a trial (whose duration
exceeds the value specified in hover_threshold)
+
total_dist
Total distance covered by the trajectory
+
vel_max
Maximum velocity
+
vel_max_time
Time at which maximum velocity occurred first
+
vel_min
Minimum velocity
+
vel_min_time
Time at which minimum velocity occurred first
+
acc_max
Maximum acceleration
+
acc_max_time
Time at which maximum acceleration occurred first
+
acc_min
Minimum acceleration
+
acc_min_time
Time at which minimum acceleration occurred first
+
Details
@@ -300,15 +354,15 @@
Author
Examples
-
mt_example<-mt_derivatives(mt_example)
-mt_example<-mt_deviations(mt_example)
-mt_example<-mt_measures(mt_example)
-
-# Merge measures with trial data
-mt_example_results<-dplyr::inner_join(
-mt_example$data, mt_example$measures,
- by="mt_id")
-
+
mt_example<-mt_derivatives(mt_example)
+mt_example<-mt_deviations(mt_example)
+mt_example<-mt_measures(mt_example)
+
+# Merge measures with trial data
+mt_example_results<-dplyr::inner_join(
+mt_example$data, mt_example$measures,
+ by="mt_id")
+
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectories should be
plotted. The corresponding trajectories are selected from data using
@@ -122,45 +124,71 @@
Arguments
"trajectories", "tn_trajectories" or "av_trajectories", depending on
whether the raw, time-normalized or averaged trajectories should be
plotted.
+
+
use2
a character string specifying where the data that contain the
variables used for determining the color and linetype can be
found (in case these arguments are specified). Defaults to "data" as
data[["data"]] usually contains all non mouse-tracking trial data.
+
+
x
a character string specifying which dimension in the trajectory
array should be displayed on the x-axis (defaults to xpos).
+
+
y
a character string specifying which dimension in the trajectory
array should be displayed on the y-axis (defaults to ypos).
+
+
color
an optional character string specifying which variable in
data[[use2]] should be used for coloring the trajectories.
+
+
linetype
an optional character string specifying which variable in
data[[use2]] should be used for varying the linetype of the
trajectories.
+
+
alpha
an optional numeric value between 0 and 1 that can be used to
make the plotted lines (and points) semitransparent.
+
+
size
an optional numeric value that can be used to vary the width of
the plotted trajectory lines.
+
+
facet_row
an optional character string specifying a variable in
data[[use2]] that should be used for (row-wise) faceting.
+
+
facet_col
an optional character string specifying a variable in
data[[use2]] that should be used for (column-wise) faceting.
+
+
wrap_var
an optional character string specifying variable(s) in
data[[use2]] that should be used for wrapping.
+
+
wrap_ncol
an optional integer specifying the number of columns if
wrapping is used.
+
+
points
logical. If TRUE, points will be added to the plot using
geom_point.
+
+
return_type
a character string specifying which type of object should
be returned. If "plot" (the default), a new ggplot is created and
@@ -168,21 +196,30 @@
Arguments
"mapping", only the ggplot object containing the mapping but without
any geoms is returned. If "geoms", only the geoms are returned,
which allows adding the plotted trajectories to an existing ggplot.
+
+
mt_id
a character string specifying the internal label used for the
trial identifier (passed on to the group aesthetic). Only relevant for
mt_plot.
+
+
only_ggplot
Deprecated. Please use return_type instead.
+
+
...
additional arguments passed on to mt_reshape (such as
subset).
+
+
subject_id
a character string specifying which column contains the
subject identifier. Only relevant for mt_plot_aggregate. If
specified, aggregation will be performed within subjects first. Note that
aggregation will be performed separately for each level, including all
subjects for whom data are available.
+
Details
@@ -210,8 +247,8 @@
Details
Functions
-
mt_plot: Plot individual trajectory data
-
mt_plot_aggregate: Plot aggregated trajectory data
+
mt_plot(): Plot individual trajectory data
+
mt_plot_aggregate(): Plot aggregated trajectory data
See also
@@ -230,81 +267,81 @@
Author
Examples
-
## Plot individual example trajectories
-
-# Time-normalize trajectories
-mt_example<-mt_time_normalize(mt_example)
-
-# Plot all time-normalized trajectories
-# varying the color depending on the condition
-mt_plot(mt_example, use="tn_trajectories",
- color="Condition")
+
## Plot individual example trajectories
+
+# Time-normalize trajectories
+mt_example<-mt_time_normalize(mt_example)
+
+# Plot all time-normalized trajectories
+# varying the color depending on the condition
+mt_plot(mt_example, use="tn_trajectories",
+ color="Condition")
-
-# ... setting alpha < 1 for semi-transparency
-mt_plot(mt_example, use="tn_trajectories",
- color="Condition", alpha=.2)
+
+# ... setting alpha < 1 for semi-transparency
+mt_plot(mt_example, use="tn_trajectories",
+ color="Condition", alpha=.2)
-
-# ... with custom colors
-mt_plot(mt_example, use="tn_trajectories",
- color="Condition")+
-ggplot2::scale_color_brewer(type="qual")
+
+# ... with custom colors
+mt_plot(mt_example, use="tn_trajectories",
+ color="Condition")+
+ggplot2::scale_color_brewer(type="qual")
-
-# Create separate plots per Condition
-mt_plot(mt_example, use="tn_trajectories",
- facet_col="Condition")
+
+# Create separate plots per Condition
+mt_plot(mt_example, use="tn_trajectories",
+ facet_col="Condition")
-
-# Create customized plot by setting the return_type option to "mapping"
-# to setup an empty plot. In a next step, a geom is added.
-# In this example, only points are plotted.
-mt_plot(mt_example, use="tn_trajectories",
- color="Condition", return_type="mapping")+
-ggplot2::geom_point()
+
+# Create customized plot by setting the return_type option to "mapping"
+# to setup an empty plot. In a next step, a geom is added.
+# In this example, only points are plotted.
+mt_plot(mt_example, use="tn_trajectories",
+ color="Condition", return_type="mapping")+
+ggplot2::geom_point()
-
-# Plot velocity profiles based on the averaged trajectories
-# varying the color depending on the condition
-mt_example<-mt_derivatives(mt_example)
-mt_example<-mt_average(mt_example, interval_size=100)
-mt_plot(mt_example, use="av_trajectories",
- x="timestamps", y="vel", color="Condition")
+
+# Plot velocity profiles based on the averaged trajectories
+# varying the color depending on the condition
+mt_example<-mt_derivatives(mt_example)
+mt_example<-mt_average(mt_example, interval_size=100)
+mt_plot(mt_example, use="av_trajectories",
+ x="timestamps", y="vel", color="Condition")
-
-
-## Plot aggregate trajectories for KH2017 data
-
-# Time-normalize trajectories
-KH2017<-mt_time_normalize(KH2017)
-
-# Plot aggregated time-normalized trajectories per condition
-mt_plot_aggregate(KH2017, use="tn_trajectories",
- color="Condition")
+
+
+## Plot aggregate trajectories for KH2017 data
+
+# Time-normalize trajectories
+KH2017<-mt_time_normalize(KH2017)
+
+# Plot aggregated time-normalized trajectories per condition
+mt_plot_aggregate(KH2017, use="tn_trajectories",
+ color="Condition")
-
-# ... first aggregating trajectories within subjects
-mt_plot_aggregate(KH2017, use="tn_trajectories",
- color="Condition", subject_id="subject_nr")
+
+# ... first aggregating trajectories within subjects
+mt_plot_aggregate(KH2017, use="tn_trajectories",
+ color="Condition", subject_id="subject_nr")
-
-# ... adding points for each position to the plot
-mt_plot_aggregate(KH2017, use="tn_trajectories",
- color="Condition", points=TRUE)
+
+# ... adding points for each position to the plot
+mt_plot_aggregate(KH2017, use="tn_trajectories",
+ color="Condition", points=TRUE)
-
-if(FALSE){
-
-# Create combined plot of individual and aggregate trajectories
-# by first plotting the individual trajectories using mt_plot.
-# In a next step, the aggregate trajectories are added using the
-# mt_plot_aggregate function with the return_type argument set to "geom".
-mt_plot(KH2017, use="tn_trajectories", color="Condition", alpha=.05)+
-mt_plot_aggregate(KH2017, use="tn_trajectories",
- color="Condition", return_type="geom", size=2)
-}
-
+
+if(FALSE){
+
+# Create combined plot of individual and aggregate trajectories
+# by first plotting the individual trajectories using mt_plot.
+# In a next step, the aggregate trajectories are added using the
+# mt_plot_aggregate function with the return_type argument set to "geom".
+mt_plot(KH2017, use="tn_trajectories", color="Condition", alpha=.05)+
+mt_plot_aggregate(KH2017, use="tn_trajectories",
+ color="Condition", return_type="geom", size=2)
+}
+
# Load ggplot2
-library(ggplot2)
-
-# Import, flip, and time-normalize raw trajectories
-mt_example<-mt_import_mousetrap(mt_example_raw)
-mt_example<-mt_remap_symmetric(mt_example,remap_xpos="no")
-mt_example<-mt_time_normalize(mt_example)
-
-# Create rectangles matrix
-rectangles<-matrix(
-# (The matrix is n x 4, and contains
-# all relevant data for every button,
-# (i.e. x, y, width and height values)
-# in separate rows)
-c(
--840, 525, 350, -170,
-840, 525, -350, -170
-),
- ncol=4, byrow=TRUE)
-
-# Plot all time-normalized trajectories
-# varying the color depending on the condition
-# and add rectangles
-mt_plot(mt_example,
- use="trajectories",
- x="xpos", y="ypos", color="Condition"
-)+mt_plot_add_rect(rect=rectangles)
+
# Load ggplot2
+library(ggplot2)
+
+# Import, flip, and time-normalize raw trajectories
+mt_example<-mt_import_mousetrap(mt_example_raw)
+mt_example<-mt_remap_symmetric(mt_example,remap_xpos="no")
+mt_example<-mt_time_normalize(mt_example)
+
+# Create rectangles matrix
+rectangles<-matrix(
+# (The matrix is n x 4, and contains
+# all relevant data for every button,
+# (i.e. x, y, width and height values)
+# in separate rows)
+c(
+-840, 525, 350, -170,
+840, 525, -350, -170
+),
+ ncol=4, byrow=TRUE)
+
+# Plot all time-normalized trajectories
+# varying the color depending on the condition
+# and add rectangles
+mt_plot(mt_example,
+ use="trajectories",
+ x="xpos", y="ypos", color="Condition"
+)+mt_plot_add_rect(rect=rectangles)
-
-
+
+
mt_plot_per_trajectory(
- file,
- data,
- use ="trajectories",
- x ="xpos",
- y ="ypos",
- xlim =NULL,
- ylim =NULL,
- axes_exact =FALSE,
- points =FALSE,
- rect =NULL,
- color ="black",
- fill =NA,
- verbose =FALSE,
- ...
-)
+
mt_plot_per_trajectory(
+file,
+data,
+ use ="trajectories",
+ x ="xpos",
+ y ="ypos",
+ xlim =NULL,
+ ylim =NULL,
+ axes_exact =FALSE,
+ points =FALSE,
+ rect =NULL,
+ color ="black",
+ fill =NA,
+ verbose =FALSE,
+...
+)
@@ -89,10 +89,14 @@
Arguments
file
a character string specifying the name of the PDF file. Passed on
to pdf.
+
+
data
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectories should be
plotted. The corresponding trajectories are selected from data using
@@ -100,42 +104,65 @@
Arguments
"trajectories", "tn_trajectories" or "av_trajectories", depending on
whether the raw, time-normalized or averaged trajectories should be
plotted.
+
+
x
a character string specifying which dimension in the trajectory
array should be displayed on the x-axis (defaults to xpos).
+
+
y
a character string specifying which dimension in the trajectory
array should be displayed on the y-axis (defaults to ypos).
+
+
xlim
optional argument specifying the limits for the x axis (passed on
to coord_cartesian). If not specified (the default),
sensible axis limits will be computed.
+
+
ylim
optional argument specifying the limits for the y axis (passed on
to coord_cartesian). If not specified (the default),
sensible axis limits will be computed.
+
+
axes_exact
logical. If TRUE, axes will be set without offset
exactly at the limits of the x and y axes (which can be specified using
xlim and ylim]).
+
+
points
logical. If TRUE, points will be added to the plot using
geom_point.
+
+
rect
optional argument passed on to mt_plot_add_rect. If
specified, rectangles (usually representing the response buttons) will be
plotted for each trajectory plot.
+
+
color
optional argument passed on to mt_plot_add_rect. Only
relevant if rect is specified.
+
+
fill
optional argument passed on to mt_plot_add_rect. Only
relevant if rect is specified.
+
+
verbose
logical indicating whether function should report its
progress.
mousetrap data object containing the data to be plotted.
+
+
use
character string specifying the set of trajectories to use in the
plot. The steps of this set will constitute the x axis. Defaults to
'tn_trajectories', which results in time steps being plotted on the x axis.
+
+
y
variable in the mousetrap data object to be plotted on the
output's y dimension. Defaults to 'xpos', the cursor's x coordinate.
+
+
y_range
numerical vector containing two values that represent the
upper and lower ends of the y axis. By default, the range is calculated
from the data provided.
+
+
y_bins
number of bins to distribute along the y axis (defaults to
250).
+
+
facet_row
an optional character string specifying a variable in
data[[facet_data]] that should be used for (row-wise) faceting. If
specified, separate riverbed plots for each level of the variable will be
created.
+
+
facet_col
an optional character string specifying a variable in
data[[facet_data]] that should be used for (column-wise) faceting.
If specified, separate riverbed plots for each level of the variable will
be created.
+
+
facet_data
a character string specifying where the (optional) data
containing the faceting variables can be found.
+
+
grid_colors
a character string or vector of length 2 specifying the
grid color(s). If a single value is provided, this will be used as the grid
color. If a vector of length 2 is provided, the first value will be used as
the color for the major grid lines, the second value for the minor grid
lines. If set to NA, no grid lines are plotted.
+
+
na.rm
logical specifying whether missing values should be removed.
This is not done by default, because generally riverbed plots are generated
from preprocess trajectories (e.g., time-normalized trajectories) that all
have the same length (i.e., the same number of steps).
+
Details
@@ -147,29 +166,29 @@
Author
Examples
-
# Time-normalize trajectories
-KH2017<-mt_time_normalize(KH2017)
-
-# Create riverbed plot for all trials
-mt_plot_riverbed(KH2017)
+
# Time-normalize trajectories
+KH2017<-mt_time_normalize(KH2017)
+
+# Create riverbed plot for all trials
+mt_plot_riverbed(KH2017)
-
-if(FALSE){
-# Create separate plots for typical and atypical trials
-mt_plot_riverbed(mt_example, facet_col="Condition")
-
-
-# Create riverbed plot for all trials with custom x and y axis labels
-mt_plot_riverbed(mt_example)+
-ggplot2::xlab("Time step")+ggplot2::ylab("X coordinate")
-
-# Note that it is also possible to replace the
-# default scale for fill with a custom scale
-mt_plot_riverbed(mt_example, facet_col="Condition")+
-ggplot2::scale_fill_gradientn(colours=grDevices::heat.colors(9),
- name="Frequency", trans="log", labels=scales::percent)
-}
-
+
+if(FALSE){
+# Create separate plots for typical and atypical trials
+mt_plot_riverbed(mt_example, facet_col="Condition")
+
+
+# Create riverbed plot for all trials with custom x and y axis labels
+mt_plot_riverbed(mt_example)+
+ggplot2::xlab("Time step")+ggplot2::ylab("X coordinate")
+
+# Note that it is also possible to replace the
+# default scale for fill with a custom scale
+mt_plot_riverbed(mt_example, facet_col="Condition")+
+ggplot2::scale_fill_gradientn(colours=grDevices::heat.colors(9),
+ name="Frequency", trans="log", labels=scales::percent)
+}
+
Mouse- and hand-trajectories often occur in types. In such cases, movement
trajectory data should be analyzed in terms of discrete type assignments
-(Wulff et al., 2021). To this end mt_map can be used to map mouse- or
+(Wulff et al., 2023). To this end mt_map can be used to map mouse- or
hand-trajectory to the closest of several predefined prototypes.
mt_prototypes provides a core set of prototypes that has been shown to
represent well a large fraction of empirical movement trajectories (Wulff et
@@ -84,9 +84,9 @@
Details
References
Wulff, D. U., Kieslich, P. J., Henninger, F., Haslbeck, J. M.
-B., & Schulte-Mecklenbeck, M. (2021). Movement tracking of cognitive
+B., & Schulte-Mecklenbeck, M. (2023). 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. (2022).
Measuring the (dis-)continuous mind: What movement trajectories
reveal about cognition. Manuscript in preparation.
mt_qeffect(
+data,
+compare,
+ use ="measures",
+ measure ="MAD",
+ direction ="upward",
+ n_steps =100,
+ return_data =FALSE,
+...
+)
@@ -76,26 +76,43 @@
Arguments
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
compare
either a vector, the label of a variable in , or a mousetrap object.
+
+
use
a character string specifying which trajectory data should be
used.
+
+
measure
a character value specifying the variable used to calculate the
effect between
Nothing, when image is plotted using an external device. Otherwise an
+
+
+
Nothing, when image is plotted using an external device. Otherwise an
object of class mt_object_raw containing in a matrix format the
image's pixel information.
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
save_as
a character string specifying where the resulting trajectory
data should be stored.
+
+
dimensions
a character vector specifying the two dimensions in the
trajectory array that contain the mouse positions, the first value
corresponding to the x-positions, the second to the y-positions.
+
+
remap_xpos
character string indicating the direction in which to remap
values on the x axis. If set to "left" (as per default), trajectories with
an endpoint on the right (i.e. with a positive x-value) will be remapped to
the left. The alternatives are "right" which has the reverse effect, and
"no", which disables remapping on the horizontal dimension.
+
+
remap_ypos
character string defining whether tracks directed downwards
on the y axis should be remapped so that they end with a positive y value.
This will be performed if this parameter is set to "up" (which is the
default), and the reverse occurs if the parameter is set to "down". If it
is set to "no", y-values remain untouched.
+
Value
-
A mousetrap data object (see mt_example) with remapped
+
+
+
A mousetrap data object (see mt_example) with remapped
trajectories. If the trajectory array was provided directly as data,
only the trajectory array will be returned.
@@ -127,17 +140,17 @@
Author
Examples
-
# Remap trajectories so that all trajectories
-# end in the top-left corner
-mt_example<-mt_import_mousetrap(mt_example_raw)
-mt_example<-mt_remap_symmetric(mt_example)
-
-# Only flip trajectories vertically so that all
-# trajectories end in the upper half of the screen
-mt_example<-mt_import_mousetrap(mt_example_raw)
-mt_example<-mt_remap_symmetric(mt_example,
- remap_xpos="no", remap_ypos="up")
-
+
# Remap trajectories so that all trajectories
+# end in the top-left corner
+mt_example<-mt_import_mousetrap(mt_example_raw)
+mt_example<-mt_remap_symmetric(mt_example)
+
+# Only flip trajectories vertically so that all
+# trajectories end in the upper half of the screen
+mt_example<-mt_import_mousetrap(mt_example_raw)
+mt_example<-mt_remap_symmetric(mt_example,
+ remap_xpos="no", remap_ypos="up")
+
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
save_as
a character string specifying where the resulting trajectory
data should be stored.
+
+
dimensions
a character vector specifying the dimensions in the
trajectory array that should be resampled. If "all", all trajectory
dimensions except the timestamps will be resampled.
+
+
timestamps
a character string specifying the trajectory dimension
containing the timestamps.
+
+
step_size
an integer specifying the size of the constant time
interval. The unit corresponds to the unit of the timestamps.
+
+
exact_last_timestamp
logical indicating if the last timestamp should
always be appended (which is the case by default). If FALSE, the
last timestamp is only appended if it is a multiple of the step_size.
+
+
constant_interpolation
an optional integer. If specified, constant
instead of linear interpolation will be performed for all adjacent
timestamps whose difference exceeds the number specified for
constant_interpolation. The unit corresponds to the unit of the
timestamps.
+
+
verbose
logical indicating whether function should report its
progress.
+
Value
-
A mousetrap data object (see mt_example) with an additional
+
+
+
A mousetrap data object (see mt_example) with an additional
array (by default called rs_trajectories) containing the resampled
trajectories. If a trajectory array was provided directly as data,
only the resampled trajectories will be returned.
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which data should be reshaped. The
corresponding data are selected from data using data[[use]].
@@ -96,45 +98,63 @@
Arguments
"tn_trajectories", or "measures", depending on whether the analysis
concerns raw trajectories, time-normalized trajectories, or derived
measures.
+
+
use_variables
a character vector specifying which mouse-tracking
variables should be reshaped. Corresponds to the column names in case a
data.frame with mouse-tracking measures is provided. Corresponds to the
labels of the array dimensions in case a trajectory array is provided. If
unspecified, all variables will be reshaped.
+
+
use2
an optional character string specifying where the other trial
data can be found. Defaults to "data" as data[["data"]] usually
contains all non mouse-tracking trial data. Alternatively, a data.frame can
be provided directly.
+
+
use2_variables
an optional character string (or vector) specifying the
variables (in data[[use2]]) that should be merged with the data. If
aggregate==TRUE, the trajectories / measures will be aggregated
separately for each of the levels of these variables using
summarize_at.
+
+
subset
a logical expression (passed on to subset) indicating
elements or rows to keep. If specified, data[[use2]] will be
subsetted using this expression, and, afterwards, data[[use]] will
be filtered accordingly.
+
+
subject_id
an optional character string specifying which column
contains the subject identifier in data[[use2]]. If specified and
aggregate==TRUE, aggregation will be performed within subjects
first.
+
+
aggregate
logical indicating whether data should be aggregated. If
use2_variables are specified, aggregation will be performed
separately for each of the levels of the use2_variables.
+
+
aggregate_subjects_only
logical indicating whether data should only be
aggregated per subject (if subject_id is specified and
aggregate==TRUE).
+
+
.funs
the aggregation function(s) passed on to
summarize_at. By default, the mean is
calculated.
+
+
trajectories_long
logical indicating if the reshaped trajectories
should be returned in long or wide format. If TRUE, every recorded
@@ -144,6 +164,8 @@
Arguments
by adding an integer to the corresponding label (e.g., xpos_1,
xpos_2, ...). Only relevant if data[[use]] contains
trajectories.
+
+
convert_df
logical indicating if the reshaped data should be converted
to a data.frame using as.data.frame. This will
@@ -153,22 +175,31 @@
Arguments
additional classes might - on rare occasions - cause problems with
functions from other packages, the reshaped data are converted to "pure"
data.frames by default.
+
+
mt_id
a character string specifying the name of the column that will
contain the trial identifier in the reshaped data. The values for the trial
identifier correspond to the rownames of data[[use]] and
data[[use2]].
+
+
mt_seq
a character string specifying the name of the column that will
contain the integers indicating the order of the mouse positions per
trajectory in the reshaped data. Only relevant if data[[use]]
contains trajectories and trajectories_long==TRUE.
mt_sample_entropy(
- data,
- use ="tn_trajectories",
- save_as ="measures",
- dimension ="xpos",
- m =3,
- r =NULL,
- use_diff =TRUE,
- verbose =FALSE
-)
+
mt_sample_entropy(
+data,
+ use ="tn_trajectories",
+ save_as ="measures",
+ dimension ="xpos",
+ m =3,
+ r =NULL,
+ use_diff =TRUE,
+ verbose =FALSE
+)
@@ -76,37 +76,60 @@
Arguments
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
save_as
a character string specifying where the calculated measures
should be stored.
+
+
dimension
a character string specifying the dimension based on which
sample entropy should be calculated. By default (xpos), the x-positions are
used.
+
+
m
an integer passed on to the sample entropy function (see Details).
+
+
r
a numeric value passed on to the sample entropy function (see
Details).
+
+
use_diff
logical indicating if the differences of the dimension values
should be computed before calculating sample entropy (which is done by
default, see Details).
+
+
verbose
logical indicating whether function should report its
progress.
+
Value
-
A mousetrap data object (see mt_example).
-If a data.frame with label specified in save_as (by default
+
+
+
If a data.frame with label specified in save_as (by default
"measures") already exists, the sample entropy values are added as
-additional column.
-If not, an additional data.frame will be added.
-If a trajectory array was provided directly as data, only the
+additional column.
If a trajectory array was provided directly as data, only the
data.frame will be returned.
@@ -153,16 +176,16 @@
Author
Examples
-
# Calculate sample entropy based on time-normalized
-# trajectories and merge results with other meausres
-# derived from raw trajectories
-mt_example<-mt_measures(mt_example)
-mt_example<-mt_time_normalize(mt_example,
- save_as="tn_trajectories", nsteps=101)
-mt_example<-mt_sample_entropy(mt_example,
- use="tn_trajectories", save_as="measures",
- dimension="xpos", m=3)
-
+
# Calculate sample entropy based on time-normalized
+# trajectories and merge results with other meausres
+# derived from raw trajectories
+mt_example<-mt_measures(mt_example)
+mt_example<-mt_time_normalize(mt_example,
+ save_as="tn_trajectories", nsteps=101)
+mt_example<-mt_sample_entropy(mt_example,
+ use="tn_trajectories", save_as="measures",
+ dimension="xpos", m=3)
+
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
save_as
a character string specifying where the resulting trajectory
data should be stored.
+
+
var_names
character vector giving the labels of the to be
standardized variables.
+
+
center
logical specifying whether variables should be centered (i.e.,
mean = 0). Can be a logical vector, in which case the values of
scale are mapped to the variables specified in var_names.
+
+
scale
logical or numeric specifying the scaling of the variables. When
logical, scale = TRUE normalizes the trajectory variable to sd = 1,
@@ -98,6 +108,8 @@
Arguments
specific value in scale. Can also be a numeric vector, in which case the
values of scale are mapped to the variables specified in
var_names.
+
+
within_trajectory
logical specifying whether trajectory variables
should be scaled within or across trajectories. If within_trajectory
@@ -107,18 +119,25 @@
Arguments
only true in the aggregate (i.e., across all trajectories). Can be a
logical vector, in which case the values of scale are mapped to the
variables specified in var_names.
+
+
prefix
character string added to the names of the new standardized
variables. If prefix = "", the original variables will be
overwritten.
+
+
transform
function that takes a numeric matrix as argument and returns
a numeric matrix of same size with transformed values. If NULL the
original values are passed on to standardization.
+
Value
-
A mousetrap data object (see mt_example) with an additional
+
+
+
A mousetrap data object (see mt_example) with an additional
variable containing the standardized trajectory variable added to the
trajectory array). If the trajectory array was provided directly as
data, only the trajectory array will be returned.
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
dimensions
a character string specifying which trajectory variables
should be used. Can be of length 2 or 3 for two-dimensional or
three-dimensional data.
+
+
save_as
a character string specifying where the resulting trajectory
data should be stored.
+
+
n_points
an integer or vector of integers specifying the number of
points used to represent the spatially rescaled trajectories. If a single
integer is provided, the number of points will be constant across
trajectories. Alternatively, a vector of integers can provided that specify
the number of points for each trajectory individually.
+
Value
-
A mousetrap data object (see mt_example) with an additional
+
+
+
A mousetrap data object (see mt_example) with an additional
array containing the spatialized trajectories. If a trajectory array was
provided directly as data, only the spatialized trajectories will be
returned.
Standardize mouse-tracking measures per level of other variables.
-
mt_standardize(
- data,
- use ="measures",
- use_variables =NULL,
- within =NULL,
- prefix ="z_",
- center =TRUE,
- scale =TRUE
-)
+
mt_standardize(
+data,
+ use ="measures",
+ use_variables =NULL,
+ within =NULL,
+ prefix ="z_",
+ center =TRUE,
+ scale =TRUE
+)
@@ -78,30 +78,45 @@
Arguments
data
a mousetrap data object created using one of the mt_import
functions (see mt_example for details).
+
+
use
a character string specifying which data should be used. By
default points to the measures data.frame created using
mt_measures.
+
+
use_variables
a vector specifying which variables should be
standardized. If unspecified, all variables will be standardized.
+
+
within
an optional character string specifying one or more variables
in data[["data"]]. If specified, all measures will be standardized
separately for each level of the variable (or for each combination of
levels, if more than one variable is specified).
+
+
prefix
a character string that is inserted before each standardized
variable. If an empty string is specified, the original variables are
replaced.
a mousetrap data object created using one of the mt_import
functions (see mt_example for details).
+
+
subset
a logical expression (passed on to subset) indicating
the rows to keep. Missing values are taken as FALSE.
+
+
check
a character string specifying which data should be used for
checking the subset condition.
+
Value
-
A mousetrap data object (see mt_example) with filtered
+
+
+
A mousetrap data object (see mt_example) with filtered
data and trajectories.
@@ -112,13 +119,13 @@
Author
Examples
-
# Subset based on trial data
-mt_example_atypical<-mt_subset(mt_example, Condition=="Atypical")
-
-# Subset based on mouse-tracking measure (MAD)
-mt_example<-mt_measures(mt_example)
-mt_example_mad_sub<-mt_subset(mt_example, MAD<400, check="measures")
-
+
# Subset based on trial data
+mt_example_atypical<-mt_subset(mt_example, Condition=="Atypical")
+
+# Subset based on mouse-tracking measure (MAD)
+mt_example<-mt_measures(mt_example)
+mt_example_mad_sub<-mt_subset(mt_example, MAD<400, check="measures")
+
a mousetrap data object created using one of the mt_import
functions (see mt_example for details). Alternatively, a trajectory
array can be provided directly (in this case use will be ignored).
+
+
use
a character string specifying which trajectory data should be
used.
+
+
save_as
a character string specifying where the resulting trajectory
data should be stored.
+
+
dimensions
a character vector specifying the dimensions in the
trajectory array that should be time-normalized. If "all", all
trajectory dimensions except the timestamps will be time-normalized.
+
+
timestamps
a character string specifying the trajectory dimension
containing the timestamps.
+
+
nsteps
an integer specifying the number of equally sized time steps.
+
+
verbose
logical indicating whether function should report its
progress.
+
Value
-
A mousetrap data object (see mt_example) with an additional
+
+
+
A mousetrap data object (see mt_example) with an additional
array (by default called tn_trajectories) containing the
time-normalized trajectories. In this array, another dimension (called
steps) has been added with increasing integer values indexing the
@@ -144,9 +159,9 @@
a character string specifying the filename of the .mt file.
+
+
columns
either 'all' or a character vector specifying the to be
extracted variables. Defaults to 'all' in which case all existing variables
will be extracted.
+
+
add_trialid
boolean specifying whether an additional column containing
the trial number should be added.
+
+
add_filename
boolean specifying whether an additional column
containing the file name should be added.
+
Value
-
A data.frame with one row per trial. Variables are ordered
+
+
+
A data.frame with one row per trial. Variables are ordered
according to columns, x-coordinates, y-coordinates, and timestamps.
@@ -116,21 +125,21 @@
Author
Examples
-
if(FALSE){
-# Read a single raw data file from MouseTracker
-# (stored in the current working directory)
-mt_data_raw<-read_mt("example.mt")
-
-# Use read_bulk to read all raw data files ending with ".mt" that are
-# stored in the folder "raw_data" (in the current working directory)
-library(readbulk)
-mt_data_raw<-read_bulk("raw_data", fun=read_mt, extension=".mt")
-
-# Import the data into mousetrap
-mt_data<-mt_import_wide(mt_data_raw)
-}
-
-
+
if(FALSE){
+# Read a single raw data file from MouseTracker
+# (stored in the current working directory)
+mt_data_raw<-read_mt("example.mt")
+
+# Use read_bulk to read all raw data files ending with ".mt" that are
+# stored in the folder "raw_data" (in the current working directory)
+library(readbulk)
+mt_data_raw<-read_bulk("raw_data", fun=read_mt, extension=".mt")
+
+# Import the data into mousetrap
+mt_data<-mt_import_wide(mt_data_raw)
+}
+
+
a character string (or vector) specifying one or more
variables that scale is applied to. If unspecified,
scale_within will be applied to all variables in data.
+
+
within
an optional character string specifying the name of one or more
variables in data. If specified, scale is applied separately
for each of the levels of the variable (or for each combination of levels,
if more than one variable is specified). Alternatively, a vector directly
containing the level values.
+
+
prefix
a character string that is inserted before each scaled
variable. By default (empty string) the original variables are replaced.
+
+if (FALSE) {
+mt_plot(KH2017,
+ use="tn_trajectories",
+ x="xpos", y="ypos", color="Condition"
+)
+}
+
