adehabitatLT (version 0.3.28)

residenceTime: Trajectory Analysis using the Residence Time Method

Description

These functions can be used to apply the residence time method (Barraquand and Benhamou, 2008).

Usage

residenceTime(lt, radius, maxt, addinfo = FALSE,
              units = c("seconds", "hours", "days"))
# S3 method for resiti
print(x, ...)
# S3 method for resiti
plot(x, addpoints = FALSE, addlines = TRUE, ...)

Value

If addinfo = FALSE, the function residenceTime returns a list of class "resiti" where each element corresponds to a burst of the object lt. Each element is a data.frame

with two columns: the date and the residence time associated with the date.

Arguments

lt

an object of class ltraj

radius

the radius of the patch (in units of the coordinates)

maxt

maximum time threshold that the animal is allowed to spend outside the patch before that we consider that the animal actually left the patch (see Details)

addinfo

logical value. If TRUE, then the residence time method is added as a variable in the infolocs component of the object lt. If FALSE this function returns an object of class resiti

units

a character string indicating the time units of maxt

x

an object of class "resiti"

addpoints

logical. Whether points should be added to the plot.

addlines

logical. Whether lines should be added to the plot.

...

additionnal arguments to be passed to or from other methods

Author

Clement Calenge

Details

Barraquand and Benhamou (2008) proposed a new approach to identify the places where the animals spend the most of their time, relying on the calculation of their residence time in the various places where they have been relocated. This approach is similar to the first passage time method: for a given value of radius and for a given relocation, the first passage time is defined as the time required by the animal to pass through a circle of given radius centred on the relocation (see the help page of the function fpt for additional details). The residence time associated to a given relocation corresponds to the first passage time calculated at this place plus the passage times that occurred in this circle before or after the current relocation, *given* that the animal did not spent a time greater than maxt before reentering the circle (see Barraquand and Benhamou, 2008, for details). It is therefore computed by determining the various times at which the path intersects the perimeter of the circle centred on the current relocation, both forward and backward, and then by summing the durations associated with the various portions of the path occurring within the circle. The graphical examination of the changes with time allow to identify the dates and places where the animal spent most of its time.

A partitionning method can be used to segment the series formed by the residence time into homogeneous segments. Barraquand and Benhamou (2008) propose the method of Lavielle (1999, 2005). See the function lavielle for details about this method.

References

Barraquand, F. and Benhamou, S. (2008) Animal movement in heterogeneous landscapes: identifying profitable places and homogeneous movement bouts. Ecology, 89, 3336--3348.

See Also

lavielle for the partitionning of the trajectory based on the residence time.

Examples

if (FALSE) {
data(albatross)
ltr <- albatross[1]

## show the distances between successive relocations as a function
## of date
plotltr(ltr)

## focus on the first period
ltr <- gdltraj(ltr, as.POSIXct("2001-12-15", tz="UTC"),
               as.POSIXct("2003-01-10", tz="UTC"))

plot(ltr)
## We identify places that seem to be a patch and, with locator,
## we measure approximately their size.
## The approximate patch radius can be set equal to 100 km as a first try

plotltr(ltr, "dt")
## As a first try, we could set maxt equal to 15000 seconds, i.e.
## approximately 4 hours

## calculation of the residence time
res <- residenceTime(ltr, radius = 100000, maxt=4, units="hour")
plot(res)

## There seems to be about 10 segments. Let us try the method
## of Lavielle (1999, 2005) to segment this series:
## First calculate again the residence time as the infolocs attribute
## of the trajectory
res <- residenceTime(ltr, radius = 100000, maxt=4, addinfo = TRUE, units="hour")
res

## Note that the residence time is now an attribute of the infolocs
## component of res


## Now, use the Lavielle method, with Kmax set to 2-3 times the
## "optimal" number of segments, assessed visually according
## to the recommendations of Barraquand and Benhamou (2008)
## We set the minimum number of relocations in each segment to
## 10 observations (given that the relocations were theoretically
## taken every hour, this defines a patch as a place where the animal
## stays at least 10 hours: this also defines the scale of our study)

ii <- lavielle(res, which="RT.100000", Kmax=20, Lmin=10)

## Both the graphical method and the automated method to choose
## the optimal number of segments indicate 4 segments
## (see ?lavielle for a description of these methods):

chooseseg(ii)

## We identify the 4 segments: the method of Lavielle seems to do a good
## job:
(pa <- findpath(ii, 4))

## and we plot this partition:
plot(pa, perani=FALSE)


## Now, we could try a study at a smaller scale (patch = 50km):
res <- residenceTime(ltr, radius = 50000, maxt=4, addinfo = TRUE,
                     units="hour")
ii <- lavielle(res, which="RT.50000", Kmax=20, Lmin=10)

## 5 segments seem a good choice:
chooseseg(ii)

## There is more noise in the residence time, but
## the partition is still pretty clear:
(pa <- findpath(ii, 5))

## show the partition:
plot(pa, perani = FALSE)


## Now try at a larger scale (patch size=250 km)
res <- residenceTime(ltr, radius = 250000, maxt=4, addinfo = TRUE,
                     units="hour")
ii <- lavielle(res, which="RT.250000", Kmax=15, Lmin=10)

## 5 segments seem a good choice again:
chooseseg(ii)

## There is more noise in the residence time, but
## the partition is still pretty clear:
(pa <- findpath(ii, 5))

## show the partition:
plot(pa, perani = FALSE)

}