Calculates a dynamic Brownian Bridge

This function uses a Move or MoveStack object to calculate the utilization distribution (UD) of the given track. It uses the dynamic Brownian Bridge Movement Model (dBBMM) to do so, having the advantage over the other Brownian Bridge Movement Model that changes in behavior are accounted for. It does so by using the behavioral change point analysis in a sliding window. For details see 'References'.

Usage

brownian.bridge.dyn(object, raster=1, dimSize=10, location.error, 
                    margin=11, window.size=31, ext=.3, bbox=NA,...)

Arguments

object

a move, moveStack, moveBurst, dBMvariance, dBMvarianceStack object. This object must be in a projection different to longitude/latitude, use spTransform to transform your coordinates.

raster

a RasterLayer object or a numeric value. If a RasterLayer is provided the brownian.bridge.dyn starts to calculate the UD based on that raster. If a numeric value is provided it is interpreted as the resolution of the square raster cells (in map units); the according raster will be calculated internally.

dimSize

numeric. dimSize is only used if raster is not set. dimSize is interpreted as the number of cells along the largest dimension of the track. The according raster will be calculated internally.

location.error

single numeric value or vector of the length of coordinates that describes the error of the location (sender/receiver) system in map units. Or a character string with the name of the column containing the location error can be provided.

margin

The margin used for the behavioral change point analysis. This number has to be odd.

window.size

The size of the moving window along the track. Larger windows provide more stable/accurate estimates of the brownian motion variance but are less well able to capture more frequent changes in behavior. This number has to be odd.

ext

Describes the amount of extension of the bounding box around the animal track. It can be numeric (same extension into all four directions), vector of two (first x, then y directional extension) or vector of four (xmin, xmax, ymin, ymax extension). Default is .3 (extends the bounding box by 30%). Only considered in combination with a numeric raster argument or the dimSize argument.

bbox

vector with 4 numbers defining a bounding box for the raster. Only considered in combination with a numeric raster argument or the dimSize argument.

...

Additional arguments:

time.step: It correspond to the size of the time intervals taken for every integration step (in minutes) and thus specifies the temporal resolution of the numerical integration. If left NULL 15 steps are taken in the shortest time interval. See 'Details'. Optional.
verbose: logical. default is TRUE; if FALSE printing messages about the computational size is suppressed. Optional.
burstType: character vector with the name(s) of burstId(s) for which the UD should be calculated. This attribute can only be used if a moveBurst is provided in the object argument. Optional.

Details

There are four ways to launch the brownian.bridge.dyn function:

1. Use a raster:
A RasterLayer object is set for the raster argument which is then used to calculate the UD.
(needed arguments: object, raster(=RasterLayer), location.error, margin, window.size; optional arguments: time.step, verbose, burstType)

2. Set the cell size
To set the cell size, set a numeric value for the raster argument without providing dimSize. The numeric raster argument is used as the cell sizes of the raster.
(needed arguments: object, raster(=numeric), location.error, margin, window.size; optional arguments: ext, bbox, time.step, verbose, burstType)

3. Set the number of cells (col/row)
To set the number of cells along the largest dimension a numeric dimSize argument can be set.
(needed arguments: object, dimSize, location.error, margin, window.size; optional arguments: ext, bbox, time.step, verbose, burstType)

4. Using default raster
When there are no values set, the default raster value is used to calculate and create a RasterLayer object, which is returned to the same function. Note: depending on the size of the area of interest, the default cell size value can result in a large number of cells which may take a very long time to calculate!

The function prints an estimate of the size of the computational task ahead. This can give an indication of how long the computation is going to take. It should scale roughly linearly with the duration of the computations although changes in the setup mean the computational complexity still is calculated base on the extent but this is not informative any more on the computation time. It is only useful as a rough indication of calculation duration.

time.step. The default value is the shortest time interval divided by 15. This means, if there is a location recorded e.g. every 30 mins, the function divides each segment into 2 mins chunks upon which it does the calculation. If for some reason there is one time interval of 15 secs in the track, each segment of the track will be divided into 1secs chunks, increasing the calculation time immensely. Before calculating the DBBMM, use e.g. min(timeLag(x=myMoveObject, units="mins")) to check which is the duration of the shortest time interval of the track. If the track contains time intervals much shorter than the scheduled on the tag, set the time.step e.g. to the scheduled time interval at which the tag was set, divided by 15.

Note

Note that the first few and last few segments of the trajectory are omitted in the calculation of the UD since a lower number of estimates for the Brownian motion variance are obtained for those segments.

Thanks to Ryan Nielson for making the BBMM package that served as an example for early versions of this code.

Value

'DBBMM' object, if move or dBMvariance object is provided

'DBBMMStack' object, if moveStack or dBMvarianceStack object is provided

'DBBMMBurstStack' object, if moveBurst object is provided

Author

Bart Kranstauber, Marco Smolla & Anne Scharf

References

Kranstauber, B., Kays, R., LaPoint, S. D., Wikelski, M. and Safi, K. (2012), A dynamic Brownian bridge movement model to estimate utilization distributions for heterogeneous animal movement. Journal of Animal Ecology. doi: 10.1111/j.1365-2656.2012.01955.x

Examples

## create a move object
data(leroy)
## change projection method to aeqd and center the coordinate system to the track
data2 <- spTransform(leroy[30:90,], CRSobj="+proj=aeqd +ellps=WGS84", center=TRUE)

## create a DBBMM object
dbbmm <- brownian.bridge.dyn(object=data2, location.error=12, dimSize=125, ext=1.2, 
           time.step=2, margin=15)
#> Computational size: 1.1e+07

plot(dbbmm)


# \dontshow{
data(fishers)
  leroy <- leroy[1:50]
  ricky<-move(system.file("extdata","ricky.csv.gz", package="move"))[1:50]
  leroy <- spTransform(leroy, 
           crs(ricky))
  stack <- moveStack(list(leroy,ricky))
  t <- brownian.bridge.dyn(spTransform(stack, center=TRUE), location.error=23.5, dimSize=1125, 
         time.step=6, ext=1.2)
#> Computational size: 1.2e+07
#> Computational size: 2.5e+08
# }