mt_reshape: General-purpose reshape and aggregation function for...
In mousetrap: Process and Analyze Mouse-Tracking Data

mt_reshape

R Documentation

General-purpose reshape and aggregation function for mousetrap data.

Description

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.

Usage

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.

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.

Value

A data.frame containing the reshaped data.

Author(s)

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
  )

mousetrap documentation built on Oct. 23, 2023, 5:08 p.m.