Traj3DFromCoords: Create a 3D Trajectory Object

In JimMcL/trajr: Animal Trajectory Analysis

Create a 3D Trajectory Object

Description

Traj3DFromCoords creates a new 3-dimensional trajectory object from a set of 3-dimensional cartesian coordinates, times and some metadata. A 3D trajectory is a 2D trajectory (see TrajFromCoords) with the addition of a z coordinate. trajr functions that expect a 2D trajectory will work on a 3D trajectory by simply ignoring the z dimension, so should only be used with care. A small number of functions operate on 3D trajectories, and are prefixed by Traj3D. Existing trajr functions that that do not deal with spatial data (e.g. TrajDuration, TrajGetNCoords etc.) can safely be used.

Usage

Traj3DFromCoords(
  track,
  xCol = 1,
  yCol = 2,
  zCol = 3,
  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).
zCol	Name or index of the z column in track (default 3).
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, y and z units.
timeUnits	Abbreviation for the units that time is recorded in.

Details

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.

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.

Value

An object with class "Trajectory3D", 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	X and y coordinates represented as complex numbers, to simplify working with 2D segment angles. Note that the z dimension is not represented.
displacement	2-dimensional displacement vectors (represented as complex numbers) between each pair of consecutive points. Note that the z dimension is not represented.

See Also

Traj3DLength, Traj3DStepLengths, Traj3DDistance, Traj3DStraightness, Traj3DSmoothSG, Traj3DResampleTime, Traj3DRediscretize, TrajFromCoords for creating 2-dimensional trajectories

JimMcL/trajr documentation built on July 23, 2024, 2:06 a.m.