mousetrap (version 2.0.0)

mt_add_variables: Add new variables to trajectory array.

Description

Add new variables to the trajectory array (and remove potentially existing variables of the same name). This is mostly a helper function used by other functions in this package (e.g., mt_deviations). However, it can also be helpful if the user has calculated new variables for each logged coordinate and wants to add them to an existing trajectory array.

Usage

mt_add_variables(data, use = "trajectories", save_as = use, variables)

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 trajectory data should be used.

save_as

a character string specifying where the resulting trajectory data should be stored.

variables

either a character vector specifying the name of the new variables that should be added to the trajectory array. In this case, the new variables are added as additional columns to the trajectory array filled with NAs. Or a list of matrices that each contain the data of one of the to be added variables. In this case, the new variables with their values are added as additional columns to the trajectory array.

Value

A mousetrap data object (see mt_example) where the new variables have been added as additional columns to the trajectory array. Depending on the input to variables, the values for the added variables are either NAs or their actual values. If columns of the same name already existed, they have been removed. If the trajectory array was provided directly as data, only the trajectory array will be returned.

Examples

# Calculate new (arbitrary) variables for this example
# ... the sum of the x- and y-positions
xy_sum <- mt_example$trajectories[,"xpos",] + mt_example$trajectories[,"ypos",]
# ... the product of the x- and y-positions
xy_prod <- mt_example$trajectories[,"xpos",] * mt_example$trajectories[,"ypos",]

# Add the new variables to the trajectory array
mt_example <- mt_add_variables(mt_example,
  variables=list(xy_sum=xy_sum, xy_prod=xy_prod))