as.ltraj: Working with Trajectories in 2D Space: the Class ltraj
In adehabitatLT: Analysis of Animal Movements
as.ltraj 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
adehabitatLT documentation built on Sept. 11, 2024, 7:15 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| as.ltraj | 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 |
xy |
a data.frame containing the x and y coordinates of the relocations |
date |
for trajectories of type II, a vector of class |
id |
either a character string indicating the identity of the
animal or a factor with length equal to |
burst |
either a character string indicating the identity of the
burst of relocations or a factor with length equal to
|
typeII |
logical. |
slsp |
a character string used for the computation of the turning angles (see details) |
infolocs |
if not |
proj4string |
an object of class CRS storing the projection information of the relocations. |
... |
For other functions, arguments to be passed to the generic
functions |
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 |
dy |
the increase of the move in the y direction. At least two
successive relocations are needed to compute |
dist |
the length of each move. At least two
successive relocations are needed to compute |
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 |
rel.angle |
the turning angles between successive moves. At least
three successive relocations are needed to compute |
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
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.