TrajFromCoords: Create a Trajectory Object

Description

TrajFromCoords creates a new trajectory object from a set of 2-dimensional cartesian coordinates, times and some metadata. The coordinates are sometimes referred to as "relocations". Rows containing NA coordinate or time values at the start or end of the trajectory are discarded. NA coordinates or times in the middle of the trajectory generate an error.

Usage

TrajFromCoords(
  track,
  xCol = 1,
  yCol = 2,
  timeCol = NULL,
  fps = 50,
  spatialUnits = "m",
  timeUnits = "s"
)

Value

An object with class "Trajectory", which is a data.frame with the following components:

x: X coordinates of trajectory points.
y: Y coordinates of trajectory points.
time: Time (in timeUnits) for each point. if timeCol is specified, values are track[,timeCol], otherwise values are calculated from fps.
displacementTime: Relative frame/observation times, with frame/observation 1 at time 0.
polar: Coordinates represented as complex numbers, to simplify working with segment angles. Beware when using complex numbers in R; Arg(0+0i) should be undefined but actually returns 0.
displacement: Displacement vectors (represented as complex numbers) between each pair of consecutive points.

In addition, any other columns coords are include in the data frame.

Arguments

track: data frame containing cartesian coordinates and optionally times for the points in the trajectory.
xCol: Name or index of the x column in track (default 1).
yCol: Name or index of the y column in track (default 2).
timeCol: optional name or index of the column which contains coordinate times.
fps: Frames per second - used to calculate relative coordinate times if track does not contain a time column. Time intervals between coordinate are assumed to be constant throught the entire track.
spatialUnits: Abbreviation for the x and y units.
timeUnits: Abbreviation for the units that time is recorded in.

Details

If timeCol is specified, track[,timeCol] is expected to contain the time (in some numeric units) of each coordinate. Otherwise, times are calculated for each point as (coord - 1) / fps where coord is the index of the point; in other words, sampling at constant time intervals is assumed. Time values require conversion if they are not numeric. It may be possible to use `strptime` for this purpose, or TrajConvertTime can be used to convert multiple field time values.

x and y must be square units. Longitude and latitude are not suitable for use as x and y values, since in general, 1° lat != 1° lon. To create a trajectory from positions in latitude and longitude, it is first necessary to transform the positions to a suitable spatial projection such as UTM (possibly by using spTransform from the rgdal package).

Leading and trailing rows with NA coordinate values are discarded. NA coordinate values within a trajectory generate an error.

Since columns in coords are preserved in the returned trajectory, if coords contains an x or y column which is not identified by xCol or yCal respectively, an error will occur. This is to prevent columns being inadvertently overwritten.

Examples

Run this code


coords <- data.frame(x = c(1, 1.5, 2, 2.5, 3, 4),
                     y = c(0, 0, 1, 1, 2, 1),
                     times = c(0, 1, 2, 3, 4, 5))
trj <- TrajFromCoords(coords, timeCol = "times")

par(mar = c(4, 4, 0.5, 0.5) + 0.1)
plot(trj)