as.ltraj {adehabitatLT}R Documentation

Working with Trajectories in 2D Space: the Class ltraj

Description

The class ltraj is intended to store trajectories of animals. Trajectories of type II correspond to trajectories for which the time is available for each relocation (mainly GPS and radio-tracking). Trajectories of type I correspond to trajectories for which the time has not been recorded (e.g. sampling of tracks in the snow).

as.ltraj creates an object of this class.

summary.ltraj returns the number of relocations (and missing values) for each "burst" of relocations and each animal.

rec recalculates the descriptive parameters of an object of class ltraj (e.g. after a modification of the contents of this object, see examples)

Usage

as.ltraj(xy, date, id, burst = id, typeII = TRUE,
         slsp = c("remove", "missing"),
         infolocs = data.frame(pkey = paste(id, date, sep="."),
                               row.names=row.names(xy)),
         proj4string = CRS())
## S3 method for class 'ltraj'
print(x, ...)
## S3 method for class 'ltraj'
summary(object, ...)
rec(x, slsp = c("remove", "missing"))

Arguments

x, object

an object of class ltraj

xy

a data.frame containing the x and y coordinates of the relocations

date

for trajectories of type II, a vector of class POSIXct giving the date for each relocation. For trajectories of type I, this argument is not taken into account.

id

either a character string indicating the identity of the animal or a factor with length equal to nrow(xy)

burst

either a character string indicating the identity of the burst of relocations or a factor with length equal to nrow(xy)

typeII

logical. TRUE indicates a trajectory of type II (time recorded, e.g. radio-tracking), whereas FALSE indicates a trajectory of type I (time not recorded, e.g. sampling of tracks in the snow)

slsp

a character string used for the computation of the turning angles (see details)

infolocs

if not NULL, a data frame containing additionnal information on the relocations (e.g., precision). By default, a primary key is generated.

proj4string

an object of class CRS storing the projection information of the relocations.

...

For other functions, arguments to be passed to the generic functions summary and print

Details

Objects of class ltraj allow the analysis of animal movements. They contain the descriptive parameters of the moves generally used in such studies (coordinates of the relocations, date, time lag, relative and absolute angles, length of moves, increases in the x and y direction, and dispersion R2n, see below), as well as optionally metadata on the relocations (precision, etc.).

The computation of turning angles may be problematic when successive relocations are located at the same place. In such cases, at least one missing value is returned. For example, let r1, r2, r3 and r4 be 4 successive relocations of a given animal (with coordinates (x1,y1), (x2,y2), etc.). The turning angle in r2 is computed between the moves r1-r2 and r2-r3. If r2 = r3, then a missing value is returned for the turning angle at relocation r2. The argument slsp controls the value returned for relocation r3 in such cases. If slsp == "missing", a missing value is returned also for the relocation r3. If slsp == "remove", the turning angle computed in r3 is the angle between the moves r1-r2 and r3-r4.

For a given individual, trajectories are often sampled as "bursts" of relocations. For example, when an animal is monitored using radio-tracking, the data may consist of several circuits of activity (two successive relocations on one circuit are often highly autocorrelated, but the data from two circuits may be sampled at long intervals in time). These bursts are indicated by the attribute burst. Note that the bursts should be unique: do not use the same burst id for bursts collected on different animals.

Two types of trajectories can be stored in objects of class ltraj: trajectories of type I correspond to trajectories where the time of relocations is not recorded. It may be because it could not be noted at the time of sampling (e.g. sampling of animals' tracks in the snow) or because the analyst decided that he did not want to take it into account, i.e. to study only its geometrical properties. In this case, the variable date in each burst of the object contains a vector of integer giving the order of the relocations in the trajectory (i.e. 1, 2, 3, ...). Trajectories of type II correspond to trajectories for which the time is available for each relocation. It is stored as a vector of class POSIXct in the column date of each burst of relocations. The type of trajectory should be defined when the object of class ltraj is defined, with the argument typeII. Note that the time zone of dates in objects of type II should be the same for all bursts (this is checked by the functions of adehabitatLT).

Concerning trajectories of type II, in theory, it is expected that the time lag between two relocations is constant in all the bursts and all the ids of one object of class ltraj (don't mix animals located every 10 minutes and animals located every day in the same object). Indeed, some of the descriptive parameters of the trajectory do not have any sense when the time lag varies. For example, the distribution of relative angles (angles between successive moves) depends on a given time scale; the angle between two during 10-min moves of a whitestork does not have the same biological meaning as the angle between two 1-day move. If the time lag varies, the underlying process varies too. For this reason, most functions of adehabitatLT have been developed for "regular" trajectories, i.e. trajectories with a constant time lag (see help(sett0)). Furthermore, several functions are intended to help the user to transform an object of class ltraj into a regular object (see for example help(sett0), and particularly the examples to see how regular trajectories can be obtained from GPS data).

Nevertheless, the class ltraj allows for variable time lag, which often occur with some modes of data collection (e.g. with Argos collars). But *we stress that their analysis is still an open question!!*

Finally, the class ltraj deals with missing values in the trajectories. Missing values are frequent in the trajectories of animals collected using telemetry: for example, GPS collar may not receive the signal of the satellite at the time of relocation. Most functions dealing with the class ltraj have a specified behavior in case of missing values.

It is recommended to store the missing values in the data *before* the creation of the object of class ltraj. For example, the GPS data imported within R contain missing values. It is recommended to *not remove* these missing values before the creation of the object!!! These missing values may present patterns (e.g. failure to locate the animal at certain time of the day or in certain habitat types), and *the analysis of these missing values should be part of the analysis of the trajectory* (e.g. see help(runsNAltraj) and help(plotNAltraj).

However, sometimes, the data come without any information concerning the location of these missing values. If the trajectory is approximately regular (i.e. approximately constant time lag), it is possible to determine where these missing values should occur in the object of class ltraj. This is the role of the function setNA.

One word now about the attribute infolocs of the object of class ltraj. This attribute is intended to store metadata concerning the relocations building the trajectory (the precision of the relocations, the value of environmental variables at this place, etc.). There are constraints on the structure of this attribute. Although any variable can be stored in this attribute, it is required that: (i) all the relocations take a value (or a missing value) for all variables, (ii) all the variables are measured (or correspond to missing values) for all bursts and ids. This means for example that the function c.ltraj cannot be used to combine an object where only variable "A" is stored as metadata and an object where only variable "B" is stored as metadata. The function removeinfo can be used to remove this attribute. Note also that the data.frames in the list infolocs should have the same row.names as the corresponding elements in the object of class "ltraj".

Finally, note that an object of class ltraj *can* have an attribute named "proj4string", storing the projection information of the object. The package adehabitatLT does not manage projection information, but this attribute can be useful when an object of class ltraj is converted to other classes (in particular spatial classes). Note that this attribute can be NULL (identical to a NA CRS).

Value

summary.ltraj returns a data frame.
All other functions return objects of class ltraj. An object of class ltraj is a list with one component per burst of relocations. Each component is a data frame with two attributes and one optionnal attribute: the attribute "id" indicates the identity of the animal, and the attribute "burst" indicates the identity of the burst. An optional attribute "infolocs" contains any additional information desired by the user (precision, etc.). Each main data frame stores the following columns:

x

the x coordinate for each relocation

y

the y coordinate for each relocation

date

the date for each relocation (type II) or a vector of integer giving the order of the relocations in the trajectory.

dx

the increase of the move in the x direction. At least two successive relocations are needed to compute dx. Missing values are returned otherwise.

dy

the increase of the move in the y direction. At least two successive relocations are needed to compute dy. Missing values are returned otherwise.

dist

the length of each move. At least two successive relocations are needed to compute dist. Missing values are returned otherwise.

dt

the time interval between successive relocations

R2n

the squared net displacement between the current relocation and the first relocation of the trajectory

abs.angle

the angle between each move and the x axis. At least two successive relocations are needed to compute abs.angle. Missing values are returned otherwise.

rel.angle

the turning angles between successive moves. At least three successive relocations are needed to compute rel.angle. Missing values are returned otherwise.

Author(s)

Clement Calenge clement.calenge@ofb.gouv.fr
Stephane Dray dray@biomserv.univ-lyon1.fr

References

Calenge, C., Dray, S. and Royer, M. (2009) The concept of animals' trajectories from a data analysis perspective. Ecological Informatics, 4: 34–41.

See Also

is.regular and sett0 for additional information on "regular" trajectories. setNA and runsNAltraj for additional information on missing values in trajectories. c.ltraj to combine several objects of class ltraj, Extract.ltraj to extract or replace bursts of relocations, plot.ltraj and trajdyn for graphical displays, gdltraj to specify a time period.

Examples


data(puechabonsp)
locs <- puechabonsp$relocs
head(locs)
xy <- coordinates(locs)
df <- as.data.frame(locs)
id <- df[,1]

######################################################
##
## Example of a trajectory of type I (time not recorded)

(litrI <- as.ltraj(xy, id = id, typeII=FALSE))
plot(litrI)

## The components of the object of class "ltraj"
head(litrI[[1]])


######################################################
##
## Example of a trajectory of type II (time recorded)


### Conversion of the date to the format POSIX
da <- as.character(df$Date)
da <- as.POSIXct(strptime(as.character(df$Date),"%y%m%d", tz="Europe/Paris"))


### Creation of an object of class "ltraj", with for 
### example the first animal
(tr1 <- as.ltraj(xy[id=="Brock",],
                 date = da[id=="Brock"],
                 id="Brock"))

## The components of the object of class "ltraj"
head(tr1[[1]])

## With all animals
(litr <- as.ltraj(xy, da, id = id))

## Change something manually in the first burst:
head(litr[[1]])
litr[[1]][3,"x"] <- 700000

## Recompute the trajectory
litr <- rec(litr)
## Note that descriptive statistics have changed (e.g. dx)
head(litr[[1]])



######################################################
##
## Example of a trajectory of type II (time recorded)
## with an infolocs attribute:

data(capreochiz)
head(capreochiz)

## Create an object of class "ltraj"
cap <- as.ltraj(xy = capreochiz[,c("x","y")], date = capreochiz$date,
                id = "Roe.Deer", typeII = TRUE,
                infolocs = capreochiz[,4:8])
cap



[Package adehabitatLT version 0.3.25 Index]