General-purpose reshape and aggregation function for mousetrap data.

mt_reshape is the general function used in the mousetrap package for filtering, merging, reshaping, and aggregating mouse-tracking measures or trajectories in combination with other trial data. Several additional (wrapper) functions for more specific purposes (cf. "See Also") are available.

mt_reshape(
  data,
  use = "trajectories",
  use_variables = NULL,
  use2 = "data",
  use2_variables = NULL,
  subset = NULL,
  subject_id = NULL,
  aggregate = FALSE,
  aggregate_subjects_only = FALSE,
  .funs = "mean",
  trajectories_long = TRUE,
  convert_df = TRUE,
  mt_id = "mt_id",
  mt_seq = "mt_seq",
  aggregation_function = NULL
)

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 data should be reshaped. The corresponding data are selected from data using data[[use]]. Usually, this value corresponds to either "trajectories", "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 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.
convert_df: logical indicating if the reshaped data should be converted to a data.frame using as.data.frame. This will drop potentially existing additional classes (such as tbl_df) that result from the internally used dplyr functions for data grouping and aggregation. As these 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.
aggregation_function: Deprecated. Please use .funs instead.

Value

A data.frame containing the reshaped data.

Details

mt_reshape uses the rownames of data[[use]] and data[[use2]] for merging the trajectories / measures and the trial data. For convenience (and for trajectories in long format also of necessity), an additional column (labelled as specified in the mt_id argument) is added to the reshaped data containing the rownames as trial identifier.

The main purpose of this function is to reshape the trajectory data into a two-dimensional data.frame, as this format is required for many further analyses and plots in R.

Besides, it should aid the user in combining data contained in different parts of the mousetrap data object, e.g., a condition variable stored in data[["data"]] with trajectory data stored in data[["trajectories"]] (or mouse-tracking measures stored in data[["measures"]]).

Finally, it offers the possibility to aggregate trajectories and measures for different conditions and/or subjects.

The package also includes several functions that wrap mt_reshape and serve specific purposes. They are often easier to use, and thus recommended over mt_reshape unless the utmost flexibility is required. These functions are described in the section "See Also".

Note also that many merging, reshaping, and aggregation procedures can be performed directly by using some of the basic R functions, e.g., merge and aggregate, or through the R packages dplyr or reshape2, if desired.

Author

Pascal J. Kieslich

Felix Henninger

Examples

# Time-normalize trajectories
mt_example <- mt_time_normalize(mt_example)

# Reshape time-normalized trajectories data into long format
# adding Condition variable
trajectories_long <- mt_reshape(mt_example,
 use="tn_trajectories",
 use2_variables="Condition"
 )

# Reshape time-normalized trajectories data into wide format
# only keeping xpos and ypos
# and adding Condition variable
trajectories_wide <- mt_reshape(mt_example,
  use="tn_trajectories", use_variables = c("xpos","ypos"),
  use2_variables = "Condition",
  trajectories_long = FALSE
  )