TrajsBuild: Construct multiple trajectories

Description

Reads multiple trajectories from files, performs some basic sanity checks on them, and optionally smooths and scales them. Attempts to collect and report errors for multiple trajectories in a single call.

Usage

TrajsBuild(
  fileNames,
  fps = NULL,
  scale = NULL,
  spatialUnits = NULL,
  timeUnits = NULL,
  csvStruct = list(x = 1, y = 2, time = NULL),
  smoothP = 3,
  smoothN = 41,
  translateToOrigin = FALSE,
  rootDir = NULL,
  csvReadFn = function(filename, ...) utils::read.csv(filename, stringsAsFactors = FALSE,
    ...),
  ...
)

Value

A list of trajectories.

Arguments

fileNames: Vector of the names of CSV files containing trajectory coordinates. All of the files must have the same columns. All file names must be unique. If rootDir is not NULL, then the file names are treated as regular expressions.
fps: Vector of frames-per-second values corresponding to the trajectories in fileNames. If length is 1, it is repeated to length(fileNames).
scale: Vector of scale values corresponding to the trajectories in fileNames. May be specified as character expressions (e.g. "1 / 1200") rather than numeric values. If NULL, the trajectories will not be scaled. If length is 1, it is repeated to length(fileNames).
spatialUnits: Abbreviated name of spatial coordinate units after scaling, e.g. "m".
timeUnits: Abbreviated name of temporal units, e.g. "s".
csvStruct: A list which identifies the columns in each CSV file which contain x-, y-, and optionally time-values.
smoothP: Filter order to be used for Savitzky-Golay smoothing (see TrajSmoothSG). If NA, no smoothing is performed.
smoothN: Filter length to be used for Savitzky-Golay smoothing (must be odd, see TrajSmoothSG). If NA, no smoothing is performed.
translateToOrigin: If TRUE, each trajectory is translated so that its starting point is at (0, 0).
rootDir: Optional name of a top level directory which contains the CSV files. If rootDir is not NULL, the CSV files may be located anywhere within rootDir or its sub-directories.
csvReadFn: Function used to read the CSV files. Required to accept arguments filename, ..., and return a data frame of coordinates, or a list of multiple data frames (see read.csv, read.csv2). The default function calls read.csv with argument stringsAsFactors = FALSE.
...: Additional arguments passed to csvReadFn.

Details

If rootDir is not null, it should be the name of a directory which is searched for the files in fileNames. The found files are then used as the list of files to be read in. This may be useful when the names of the files are known, but their exact location within a directory structure is not known.

For each file name in fileNames, reads the file by calling csvReadFn to obtain a set of coordinates and optionally times. A Trajectory is then constructed by passing the coordinates to TrajFromCoords, passing in the appropriate fps value, and x, y and time column names/indices from csvStruct. If scale is not NULL, the trajectory is scaled by calling TrajScale. If smoothP and smoothN are not NULL, the trajectory is smoothed by calling TrajSmoothSG.

Examples

Run this code

if (FALSE) {
# Names of CSV files containing trajectory coordinates
fileNames <- c('xy001.csv', 'xy003.csv', 'xy004.csv')
# The files are all located somewhere under this directory
rootDir <- '.'
# Scale for these files is 1 / pixels per metre
scale <- c('1/1200', '1/1350', '1/1300')
# Files have columns y, x
csvStruct <- list(x = 2, y = 1)
# Apply default smoothing, and the files are formatted as conventional CSV,
# so there's no need to specify csvReadFn
trjs <- TrajsBuild(fileNames, fps = 50, scale = scale, units = "m",
                   csvStruct = csvStruct, rootDir = rootDir)
}