Average trajectory data across specified intervals (e.g., constant time intervals). For every specified dimension in the trajectory array (by default, every dimension, i.e., x- and y-position, possibly also velocity and acceleration etc.), the mean value for the respective interval is calculated (see Details for information regarding the exact averaging procedure).

mt_average( data, use = "trajectories", save_as = "av_trajectories", dimensions = "all", av_dimension = "timestamps", intervals = NULL, interval_size = 100, max_interval = NULL, verbose = FALSE, dimension = NULL )

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 | a character string specifying which trajectory data should be used. |

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

dimensions | a character vector specifying the dimensions in the
trajectory array that should be averaged. By default ( |

av_dimension | a character string specifying which values should be used
for determining the intervals for averaging ( |

intervals | an optional numeric vector. If specified, these values are
taken as the borders of the intervals ( |

interval_size | an integer specifying the size of the constant dimension interval. |

max_interval | an integer specifying the upper limit of the last
dimension value that should be included (therefore, it should be a multiple
of the |

verbose | logical indicating whether function should report its progress. |

dimension | Deprecated. Please use |

A mousetrap data object (see mt_example) with an additional
array (by default called `av_trajectories`

) that contains the average
trajectory data per dimension interval. If a trajectory array was provided
directly as `data`

, only the average trajectories will be returned.

For the dimension values used for averaging (specified in
`av_dimension`

), the mid point of the respective interval is reported,
which is helpful for plotting the trajectory data later on. However, this
value does not necessarily correspond to the empirical mean of the
dimension values in the interval.

For each interval, it is first determined which of the values lie within the respective interval of the dimension used for averaging (e.g., timestamps). Intervals are left-open, right-closed (e.g., if values are averaged across constant timestamps of 100 ms, a timestamp of 1200 would be included in the interval 1100-1200 while a timestamp of 1300 would be included in the interval 1200-1300). Then, all values for which the corresponding average dimension values lie within the interval are averaged.

In case the last interval is not fully covered (e.g., if the last timestamp has the value 1250), values for the corresponding interval (1200-1300) will be computed based on the average of the values up to the last existing value.

Note that `mt_average`

assumes that the trajectory variables are
recorded with a constant sampling rate (i.e., with a constant difference in
the timestamps). If the sampling rate varies considerably, mt_resample
should be called before averaging to arrive at equally spaced timestamps. The
sampling rate can be investigated using mt_check_resolution.

If average velocity and acceleration are of interest, mt_derivatives should be called before averaging.

mt_derivatives for calculating velocity and acceleration.

mt_resample for resampling trajectories using a constant time interval.

mt_example <- mt_derivatives(mt_example) # average trajectories across 100 ms intervals mt_example <- mt_average(mt_example, save_as="av_trajectories", interval_size=100) # average time-normalized trajectories across specific intervals # of the time steps mt_example <- mt_time_normalize(mt_example) mt_example <- mt_average(mt_example, use="tn_trajectories", save_as="av_tn_trajectories", av_dimension = "steps", intervals = c(0.5,33.5,67.5,101.5))