mt_aggregate {mousetrap}

Aggregate mouse-tracking data per condition.

Description

mt_aggregate is used for aggregating mouse-tracking measures (or trajectories) per condition. One or several condition variables can be specified using use2_variables. Aggregation will be performed separately for each level of the condition variables. mt_aggregate is a wrapper function for mt_reshape.

Usage

mt_aggregate(
  data,
  use = "measures",
  use_variables = NULL,
  use2 = "data",
  use2_variables = NULL,
  subject_id = NULL,
  trajectories_long = TRUE,
  ...
)

Arguments

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 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 provided as 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.

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 position in a trajectory is placed in another row (whereby the order of the positions is logged in the variable mt_seq). If FALSE, every trajectory is saved in wide format and the respective positions are indexed 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).

Value

A data.frame containing the aggregated data.

Author(s)

Pascal J. Kieslich

Felix Henninger

See Also

mt_aggregate_per_subject for aggregating mouse-tracking measures and trajectories per subject.

summarize_at for aggregating data using the dplyr package.

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"
)