rubitBasic: Reads a raw UbiTrail result file and returns filtered...

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 smooths, interpolates and resamples X,Y-trajectories from raw tracking before calculating the distance between successive positions. These data can then be used with rubitMetrics to extract a range of behavioural metrics.

Usage

rubitBasic(FILE, scale = 1, hz = 30, start_at = NA, end_at = NA,
  adj_fps = NA, k = 15, p = 0.001, nmin = k * 10, a = 0, b = 0,
  c = 0, filterFUN = rubitMedianFilter,
  interpFUN = rubitLinearInterpolate, verbose = FALSE)

Arguments

FILE	a .csv result file outputted by UbiTrail.
scale	a numeric to calibrate the true spatial scale, in pixels per mm. At the default value, measurements are returned in pixels.
hz	the frequency of resampling, in Hz. This argument is passed to the interpolation function.
start_at, end_at	the desired start and end times to interpolate and/or cut data to, in minutes.
adj_fps	encodes a new framerate, in Hz.
k	the level of smoothing for raw trajectories. This argument is passed to the filter function.
p	the threshold used to remove outliers, as a proportion of the overall likelihood distribution; e.g. for p = 0.01, the largest 1% of outliers will be removed. See rubitRemoveOutliers for more information.
nmin	the minimal number of reads. If not enough reads are presents in an area, an empty matrix is returned.
a, b, c	parameters to correct lens distortion. See lensCorrection for more information.
filterFUN	the filter function to be used. It must have the same arguments as rubitMedianFilter.
interpFUN	the interpolation function to be used. It must have the same arguments as rubitLinearInterpolate.
verbose	logical; if TRUE, the function will print messages at every step.

Value

A list of numerical matrices, with each matrix corresponding to an area. The attributes of list contain metadata about the original video file and attributes of each matrix contain information on the dimensions of the area.

Note

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

rubitMetrics for extracting behavioural metrics from processed trajectories outputted by this function. rubitToDF converts the list (or list of lists) returned by this function into a dataframe for ease of further analysis. See rubitLinearInterpolate, rubitMedianFilter, and rubitRemoveOutliers to understand the different steps of processing used in this function. See codecalcFPS for calculating the framerate of data and see lensCorrection for more information on lens distortion.

Examples

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

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)

## See general metadata:
attributes(tenebrio_basic)

## See information on area '01':
attributes(tenebrio_basic[['01']])


### Read a list of UbiTrail results files:
###----------------------------------------
## Create a filelist of all UbiTrail results files in a directory:
# filelist <- list.files()

## Apply function over filelist:
lapply(filelist, rubitBasic, scale= 2.08, hz = 30, start_at = 0, end_at = 60, verbose = TRUE)

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