rubitMetrics: A wrapper combining several functions which calculate a range...

In JoGall/rubitrail: rubitrail, a package to analyse the output of UbiTrail, an open-source video tracking program for analysis of animal locomotion.

Description

This function loads processed X,Y-trajectories returned from rubitBasic, and returns data on metrics on velocity, position (e.g. thigmotaxis, exploration), turning angle, and activity (i.e. pause / walk events).

Usage

rubitMetrics(LIST, scale = 1, speed_smooth = 21, turn_resample_rate = 1,
  activity_window = 1, activity_min_speed = 0.1, n_radials = 1,
  n_slices = 1, area_rad = NA, thigmo_dist = NA, n_bootstraps = 20,
  verbose = FALSE)

Arguments

LIST	a list of matrices containing processed X,Y-trajectories returned from rubitBasic.
scale	a numeric to calibrate the true spatial scale, in pixels per mm. At the default value, measurements are returned in pixels.
speed_smooth	the size of the rolling median window used to smooth speed and acceleration, in frames.
turn_resample_rate	the number of seconds over which to resample X,Y-coordinate data and calculate turning angle from.
activity_window	the window size used to define changes in activity, in seconds.
activity_min_speed	the minimum speed threshold used to define changes in activity below which no movement is inferred, in mm/second.
n_radials	the number of concentric circles to divide a circular area into.
n_slices	the number of slices to divide a circular area into.
area_rad	the minimum radius of the area. If an area shows insufficient movement to define a minimum enclosing circle of at least this radius, then a new minimum enclosing circle is calculated using area_rad and area metainformation stored in attributes(m). This unit is defined in pixels unless scale != 1.
thigmo_dist	the distance from the boundary perimeter defined as being central (i.e. not thigmotaxis), in mm. If thigmo_dist = NA, thigmotaxis is defined as movement in the outer 50% of the area (i.e. > R/sqrt(2) from the area centre, where R is the radius of the whole area).
n_bootstraps	the number of random data samples used to calculate the minimum enclosing circle defining each circular area.
verbose	logical; if TRUE, the function will print messages at every step.

Value

A list of numerical matrices. Each matrix corresponds to an area.

Note

The returned list contains a numerical matrix for each area. The attributes of list contain metadata and additional information is present in each of the attributes of each matrix. Re-encoding a new framerate with adj_fps can correct potential errors made during video recording and/or tracking analysis. Check that the value returned by calcFPS matches the calculated framerate of the original video (e.g. using the 'ffprobe' function in FFmpeg [https://ffmpeg.org/].

See Also

rubitToDF for converting the returned lists (or list of lists) to a dataframe for ease of further analysis. See rubitBasic, rubitCalcSpeed, rubitCalcPosition, rubitCalcTurning, and rubitCalcActivity to understand the different steps of processing used in this function.

Examples

### Extract metrics from a single UbiTrail results file:
###-------------------------------------------------------
## Locate raw data example included with package
FILE <- system.file("extdata", "tenebrio_ubitrail.csv.gz", package = "rubitrail")

## Basic processing
tenebrio_basic <- rubitBasic(FILE, scale= 2.08, hz = 30, start_at = 0, end_at = 60, adj_fps = 19.05, k = 21, a = -0.005, b = -0.006, verbose = TRUE)

## Extract metrics from processed data
rubitMetrics(tenebrio_basic, scale = 2.08, n_radials = 8, n_slices = 12, area_rad = 90, thigmo_dist = 20, verbose = TRUE)


### Extract metrics from multiple UbiTrail results files:
###-------------------------------------------------------
## Create a filelist of all UbiTrail results files in a directory:
#filelist <- list.files()

## Apply basic processing function over filelist
#basic_data <- lapply(filelist, rubitBasic, scale = 2.08, hz = 30, start_at = 0, end_at = 60, verbose = TRUE)

## Apply metrics function over processed list of data
#lapply(basic_data, rubitMetrics, scale = 2.08, n_radials = 8, n_slices = 12, area_rad = 90, thigmo_dist = 20, verbose = TRUE)

JoGall/rubitrail documentation built on May 7, 2019, 10:53 a.m.