mousetrap (version 1.2.0)

mt_reshape: 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, aggregation_function = mean, trajectories_long = TRUE, mt_seq = "mt_seq")

Arguments

data

a mousetrap data object created using one of the mt_import functions (see mt_example for details).

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

a 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

a 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 dcast.

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

a 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).

aggregation_function

the aggregation function passed on to dcast. 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.

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. Only relevant if data[[use]] contains trajectories and trajectories_long==TRUE.

Value

A data.frame containing the reshaped data.

Details

mt_reshape uses the mt_id variable for merging the trajectories / measures (in data[[use]]) and the trial data (in data[[use2]]).

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 reshape2 or dplyr, if desired.

See Also

mt_aggregate for aggregating mouse-tracking measures and trajectories.

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

merge for merging data in R.

aggregate for aggregating data in R.

dcast for reshaping and aggregating data using the reshape2 package.

Regarding the dangers of using mt_reshape, please consider the following limerick before applying the function:

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
  )