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.

`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
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 a new entry in the trajectory arrays third
dimension. Alternatively, 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 filled with `NA`

s.

## Value

A mousetrap data object (see mt_example) where the new
variables have been added to the trajectory array.
Depending on the input to `variables`

, the values for the added
variables are either `NA`

s 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.

## Author

Pascal J. Kieslich

Felix Henninger

## 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))
```