trajr (version 1.0.0)

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, rootDir = NULL,
  csvReadFn = utils::read.csv, ...)

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)

smoothN

Filter length to be used for Savitzky-Golay smoothing (must be odd, see TrajSmoothSG)

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

...

Additional arguments passed to csvReadFn.

Value

A list of trajectories.

Details

For each file name in fileNames, searches through the folder rootDir (unless it's NULL) to find the file, then reads the file by calling csvReadFn to obtain a set of coordinates and optionally times. A Trajectory is 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 then scaled by calling TrajScale. If smoothP and smoothN are not NULL, the trajectory is smoothed by calling TrajSmoothSG.

See Also

read.csv, TrajFromCoords, TrajScale, TrajSmoothSG

Examples

# NOT RUN {
# 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)
# }
# NOT RUN {
# }