% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mousetrap-package.R
\docType{package}
\name{mousetrap-package}
\alias{mousetrap}
\alias{mousetrap-package}
\title{Process and analyze mouse-tracking data}
\description{
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.
}
\section{Read functions}{


Depending on the file format, one of the standard R functions for reading
files into R can be used (e.g., \link[utils]{read.table} or
\link[utils:read.table]{read.csv}).

If raw data were collected using
\href{http://www.mousetracker.org/}{MouseTracker}, the mousetrap package
provides the \link{read_mt} function to read files in the ".mt" format.

If several raw data files should be read and merged, the
\link[readbulk]{read_bulk} function from the
\href{http://pascalkieslich.github.io/readbulk/}{readbulk} package can be
used (or the \link[readbulk]{read_opensesame} function, if data were
collected using \href{https://osdoc.cogsci.nl/}{OpenSesame}).
}

\section{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 \link{mt_example}.

\link{mt_import_mousetrap} imports mouse-tracking data that were recorded
using the \href{https://github.com/pascalkieslich/mousetrap-os}{mousetrap
plugin} for \href{https://osdoc.cogsci.nl/}{OpenSesame}.

\link{mt_import_wide} imports mouse-tracking data saved in a wide format
(e.g., data collected using
\href{http://www.mousetracker.org/}{MouseTracker}).

\link{mt_import_long} imports mouse-tracking data saved in a long format.
(e.g., trajectories exported using \link{mt_export_long}).
}

\section{Geometric preprocessing functions}{


A number of functions are available that perform geometric preprocessing
operations.

\link{mt_remap_symmetric} remaps mouse trajectories to one side (or one
quadrant) of the coordinate system.

\link{mt_align} is a general purpose function for aligning and rescaling
trajectories. For specific operations, you can rely on one of the
following functions.

\link{mt_align_start} aligns the start position of trajectories.

\link{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").
}

\section{Resampling and interpolation functions}{


A number of functions are available that perform resampling and
interpolation operations.

\link{mt_exclude_initiation}	excludes the initial phase of a trial without
mouse movement.

\link{mt_exclude_finish}	excludes a potential phase without mouse movement at the end of a trial.

\link{mt_time_normalize}	performs time-normalization using equidistant time
intervals, resulting in an identical number of samples for all
trajectories.

\link{mt_resample}	resamples trajectories so that samples occur at constant
intervals of a specified length.

\link{mt_average} averages trajectory coordinates (and related variables)
for time bins of constant duration.

\link{mt_length_normalize} re-represents each trajectory spatially so that
adjacent points on the trajectory become equidistant to each other.
}

\section{Data handling functions}{


A number of functions are available for data handling operations, such as
filtering or adding of new variables or trajectories.

\link{mt_subset}	filters mouse-tracking data by trials, so that only those
meeting the defined criteria are included.

\link{mt_add_variables} adds new, self created variables to a trajectory
array.

\link{mt_add_trajectory} adds a new trajectory to a trajectory array.

\link{mt_bind} joins two trajectory arrays.
}

\section{Analysis functions}{


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.

\link{mt_derivatives} calculates distance, velocity, and
acceleration for trajectories.

\link{mt_angles} calculates movement angles for trajectories.

\link{mt_deviations} calculates the deviations from an idealized
trajectory (straight line).

\link{mt_measures}	calculates a set of mouse-tracking measures.

\link{mt_sample_entropy}	calculates sample entropy.

\link{mt_standardize} standardizes mouse-tracking measures onto a common
scale (separately for subsets of the data, e.g., per participant).

\link{mt_scale_trajectories} provides different options for standardizing
variables in a mouse trajectory array.

\link{mt_check_bimodality}	assesses the bimodality of mouse-tracking
measure distributions.

\link{mt_check_resolution}	checks the (temporal) logging resolution of raw
trajectories.

\link{mt_count} counts the number of observations for each trajectory.
}

\section{Cluster functions}{


A number of different functions for clustering trajectories is provided.

\link{mt_distmat} computes the dissimilarity/distance between each pair of
trajectories.

\link{mt_cluster} performs trajectory clustering with a specified number of
clusters.

\link{mt_cluster_k} estimates the optimal number of clusters using various
methods.

\link{mt_map} maps trajectories onto a predefined set of prototype
trajectories (a core set is provided in \link{mt_prototypes}).
}

\section{Reshaping, aggregation, and export functions}{


A number of helper functions are provided for aggregating, plotting, and
exporting the multi-dimensional mouse trajectory arrays.

\link{mt_reshape} is a general purpose reshaping and aggregation function
for mousetrap data.

\link{mt_aggregate} aggregates mouse-tracking data per condition.

\link{mt_aggregate_per_subject}	aggregates mouse-tracking data per
(within subjects-) condition separately for each subject.

\link{mt_export_long} exports mouse-tracking data in long format.

\link{mt_export_wide} exports mouse-tracking data in wide format.
}

\section{Visualization functions}{


The following functions can be used for plotting trajectory data, e.g.,
individual and aggregated trajectories or velocity profiles.

\link{mt_plot}	plots individual trajectory data.

\link{mt_plot_aggregate}	plots aggregated trajectory data.

\link{mt_plot_add_rect} adds rectangles to a trajectory plot.

\link{mt_plot_riverbed} plots the relative frequency of a selected variable
across time.

\link{mt_plot_per_trajectory} creates a pdf with separate plots per
trajectory.

\link{mt_heatmap} and \link{mt_heatmap_ggplot} plot trajectory heatmaps.

\link{mt_diffmap} for creating a difference-heatmap of two trajectory
heatmap images.

\link{mt_animate} creates a gif trajectory animation.
}

\section{Helper functions}{


\link{bimodality_coefficient} calculates the bimodality coefficient.

\link{scale_within} scales and centers variables within the levels of
another variable.

\link{bezier} creates Bezier-curves using the Bernstein approximation.
}

\section{Datasets}{


\link{mt_example} and \link{mt_example_raw} contain a mouse-tracking
example dataset for demonstrations using the \code{mousetrap} package.

\link{KH2017} and \link{KH2017_raw} contain a mouse-tracking dataset from
Kieslich & Henninger (2017).
}

\examples{
\dontrun{
KH2017 <- mt_import_mousetrap(subset(KH2017_raw,correct==1))
KH2017 <- mt_remap_symmetric(KH2017)
KH2017 <- mt_align_start(KH2017)
}

KH2017 <- mt_time_normalize(KH2017)
KH2017 <- mt_measures(KH2017)

mt_aggregate(
  KH2017, use="measures",
  use_variables=c("MAD", "AD"),
  use2_variables="Condition",
  subject_id="subject_nr"
)

mt_plot_aggregate(KH2017,
  use="tn_trajectories",
  x="xpos", y="ypos", color="Condition",
  subject_id="subject_nr"
)

\dontrun{
mt_plot(KH2017,
  use="tn_trajectories",
  x="xpos", y="ypos", color="Condition"
)
}
}
\seealso{
Useful links:
\itemize{
  \item \url{https://pascalkieslich.github.io/mousetrap/}
  \item \url{https://github.com/pascalkieslich/mousetrap}
  \item Report bugs at \url{https://github.com/pascalkieslich/mousetrap/issues}
}

}
\author{
\strong{Maintainer}: Pascal J. Kieslich \email{pascal.kieslich@gmail.com} (\href{https://orcid.org/0000-0002-0853-9364}{ORCID})

Authors:
\itemize{
  \item Dirk U. Wulff \email{dirk.wulff@gmail.com} (\href{https://orcid.org/0000-0002-4008-8022}{ORCID})
  \item Felix Henninger \email{mailbox@felixhenninger.com} (\href{https://orcid.org/0000-0002-7730-9511}{ORCID})
  \item Jonas M. B. Haslbeck \email{jonas.haslbeck@googlemail.com}
}

Other contributors:
\itemize{
  \item Sarah Brockhaus [contributor]
}

}
\keyword{internal}
