TrajFromCoords: Create a Trajectory Object

In JimMcL/trajr: Animal Trajectory Analysis

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

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.

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.

See Also

TrajsBuild, Traj3DFromCoords

Examples

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)

JimMcL/trajr documentation built on Jan. 31, 2024, 12:57 a.m.