mt_average: Average trajectories across intervals.

Description

Average trajectory data across specified intervals (e.g., constant time intervals). For every variable that was recorded and stored in the trajectory array (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).

Usage

mt_average(data, use = "trajectories", save_as = "av_trajectories", dimension = "timestamps", intervals = NULL, interval_size = 100, max_interval = NULL, show_progress = TRUE)

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.

dimension

a character string specifying which values should be used for determining the intervals for averaging ("timestamps" by default).

intervals

an optional numeric vector. If specified, these values are taken as the borders of the intervals (interval_size and max_interval are ignored).

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 interval_size). If specified, only values will be used for averaging where the dimension values are smaller than max_interval. If unspecified (the default), all values will be included.

show_progress

logical indicating whether function should report on its progress.

Value

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

Details

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_calculate_derivatives should be called before averaging.

Examples

Run this code

mt_example <- mt_calculate_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",
  dimension = "steps", intervals = c(0.5,33.5,67.5,101.5))