% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/aggregate.R
\name{mt_aggregate}
\alias{mt_aggregate}
\title{Aggregate mouse-tracking data per condition.}
\usage{
mt_aggregate(
  data,
  use = "measures",
  use_variables = NULL,
  use2 = "data",
  use2_variables = NULL,
  subject_id = NULL,
  trajectories_long = TRUE,
  ...
)
}
\arguments{
\item{data}{a mousetrap data object created using one of the mt_import
functions (see \link{mt_example} for details). Alternatively, a trajectory
array can be provided directly (in this case \code{use} will be ignored).}

\item{use}{a character string specifying which dataset should be aggregated.
The corresponding data are selected from \code{data} using
\code{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.}

\item{use_variables}{a character vector specifying the mouse-tracking
variables to aggregate. If a data.frame with mouse-tracking measures is
provided as \code{data}, this corresponds to the column names. If a
trajectory array is provided, this argument should specify the labels of
respective array dimensions. If unspecified, all variables will be
aggregated.}

\item{use2}{a character string specifying where the data containing the
condition information can be found. Defaults to "data" as
\code{data[["data"]]} usually contains all non mouse-tracking trial data.
Alternatively, a data.frame can be provided directly.}

\item{use2_variables}{a character string (or vector) specifying the variables
(in \code{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 \link[dplyr:summarise_all]{summarize_at}.}

\item{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 \code{use2_variables}).}

\item{trajectories_long}{logical indicating if the reshaped trajectories
should be returned in long or wide format. If \code{TRUE}, every recorded
position in a trajectory is placed in another row (whereby the order of the
positions is logged in the variable \code{mt_seq}). If \code{FALSE}, every
trajectory is saved in wide format and the respective positions are indexed
by adding an integer to the corresponding label (e.g., \code{xpos_1},
\code{xpos_2}, ...). Only relevant if \code{data[[use]]} contains
trajectories.}

\item{...}{additional arguments passed on to \link{mt_reshape} (such as
\code{subset}).}
}
\value{
A \link{data.frame} containing the aggregated data.
}
\description{
\code{mt_aggregate} is used for aggregating mouse-tracking measures (or
trajectories) per condition. One or several condition variables can be
specified using \code{use2_variables}. Aggregation will be performed
separately for each level of the condition variables. \code{mt_aggregate} is
a wrapper function for \code{\link{mt_reshape}}.
}
\examples{
# Time-normalize trajectories
mt_example <- mt_time_normalize(mt_example)

# Aggregate time-normalized trajectories per condition
average_trajectories <-  mt_aggregate(mt_example,
  use="tn_trajectories",
  use2_variables="Condition"
)


# Calculate mouse-tracking measures
mt_example <- mt_measures(mt_example)

# Aggregate measures per condition
average_measures <- mt_aggregate(mt_example,
  use="measures", use_variables=c("MAD", "AD"),
  use2_variables="Condition"
)

# Aggregate measures per condition
# first within subjects and then across subjects
average_measures <- mt_aggregate(mt_example,
  use="measures", use_variables=c("MAD", "AD"),
  use2_variables="Condition",
  subject_id="subject_nr"
)

}
\seealso{
\link{mt_aggregate_per_subject} for aggregating mouse-tracking
measures and trajectories per subject.

\link[dplyr:summarise_all]{summarize_at} for aggregating data using the \code{dplyr}
package.
}
\author{
Pascal J. Kieslich

Felix Henninger
}
