R/metrics.R

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

#' @include utils.R
#' @include basic.R
#' @include calcSpeed.R
#' @include calcPosition.R
#' @include calcTurning.R
#' @include calcActivity.R
NULL
#' A wrapper combining several functions which calculate a range of behavioural metrics from processed X,Y-trajectories.
#'
#' This function loads processed X,Y-trajectories returned from \code{rubitBasic}, and returns data on metrics on velocity, position (e.g. thigmotaxis, exploration), turning angle, and activity (i.e. pause / walk events).
#' 
#' @param LIST a list of matrices containing processed X,Y-trajectories returned from \code{rubitBasic}.
#' @param scale a numeric to calibrate the true spatial scale, in pixels per mm. At the default value, measurements are returned in pixels.
#' @param speed_smooth the size of the rolling median window used to smooth speed and acceleration, in frames.
#' @param turn_resample_rate the number of seconds over which to resample X,Y-coordinate data and calculate turning angle from.
#' @param activity_window the window size used to define changes in activity, in seconds.
#' @param activity_min_speed the minimum speed threshold used to define changes in activity below which no movement is inferred, in mm/second.
#' @param n_radials the number of concentric circles to divide a circular area into.
#' @param n_slices the number of slices to divide a circular area into.
#' @param 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 \code{area_rad} and area metainformation stored in \code{attributes(m)}. This unit is defined in pixels unless \code{scale} != 1.
#' @param 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).
#' @param n_bootstraps the number of random data samples used to calculate the minimum enclosing circle defining each circular area.
#' @param verbose logical; if TRUE, the function will print messages at every step.
#' @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 \code{adj_fps} can correct potential errors made during video recording and/or tracking analysis. Check that the value returned by \code{\link{calcFPS}} matches the calculated framerate of the original video (e.g. using the 'ffprobe' function in FFmpeg [\url{https://ffmpeg.org/}].
#' @return A list of numerical matrices. Each matrix corresponds to an area.
#' @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)
#'
#' @seealso \code{\link{rubitToDF}} for converting the returned lists (or list of lists) to a dataframe for ease of further analysis. See \code{\link{rubitBasic}}, \code{\link{rubitCalcSpeed}}, \code{\link{rubitCalcPosition}}, \code{\link{rubitCalcTurning}}, and \code{\link{rubitCalcActivity}} to understand the different steps of processing used in this function.
#' @export
rubitMetrics <- function(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){

	atrs <- attributes(LIST)  #remember original attributes

	if(verbose) print(sprintf("Calculating position..."))
	l <- lapply(LIST, rubitCalcPosition, scale = scale, area_rad = area_rad, thigmo_dist = thigmo_dist, n_radials = n_radials, n_slices = n_slices, n_bootstraps = n_bootstraps)
	
	if(verbose) print(sprintf("Calculating speeds..."))
	l <- lapply(l, rubitCalcSpeed, window = speed_smooth )
	
	if(verbose) print(sprintf("Resampling and calculating turning angles..."))
	turning <- lapply(l, rubitCalcTurning, resample = turn_resample_rate )

	if(verbose) print(sprintf("Calculating activity status..."))
	activity <- lapply(l, rubitCalcActivity, window = activity_window, min_speed = activity_min_speed)
	
	attributes(l) <- atrs  #reinstate attributes

	#return three datasets as a list of lists of matrices
    return(list(
		speed = l,
		turning = turning,
		activity = activity)
	)
}