passage {gdistance}

Probability of passage

Description

Calculates for each cell the number of passages of a random-walk or randomised shortest paths with given origin(s) and destination(s). Either the total or the net number of passages can be calculated. In the case of multiple origins or destinations, each receives equal weight.

Usage

passage(x, origin, goal, theta, ...)

Arguments

x

Object of class Transition*

origin

SpatialPoints, matrix or numeric object with coordinates or RasterLayer object with origin cells set to TRUE

goal

SpatialPoints, matrix or numeric object with coordinates or RasterLayer object with origin cells set to TRUE

theta

If zero or missing, a random walk results. If a numeric value 0 < theta < 20 is given, randomised shortest paths are calculated; theta is the degree from which the path randomly deviates from the shortest path

...

Additional arguments: totalNet ("total" or "net"), and output ("RasterLayer" or "Transition")

Details

The net number of passages between i and j is defined as: abs( passages from i to j - passages from j to i ).

Defaults for additional argument totalNet is "net" and for output it is "RasterLayer".

Random walk requires a symmetric transition matrix.

Value

RasterLayer or Transition object, depending on the output argument

Author(s)

Jacob van Etten. Implementation of randomised shortest paths based on Matlab code by Marco Saerens

References

McRae B.H., B.G. Dickson, and T. Keitt. 2008. Using circuit theory to model connectivity in ecology, evolution, and conservation. Ecology 89:2712-2724.

Saerens M., L. Yen, F. Fouss, and Y. Achbany. 2009. Randomized shortest-path problems: two related models. Neural Computation, 21(8):2363-2404.

See Also

commuteDistance, pathInc

Examples

#create a new raster and set all its values to unity.
raster <- raster(nrows=18, ncols=36)
raster <- setValues(raster,rep(1,ncell(raster)))

#create a Transition object from the raster
tr <- transition(raster,mean,4)
trC <- geoCorrection(tr, type="c", scl=TRUE)
trR <- geoCorrection(tr, type="r", scl=TRUE)

#create two coordinates
sP1 <- SpatialPoints(cbind(-105,55))
sP2 <- SpatialPoints(cbind(105,-55))

#randomised shortest paths with theta = 2
rSPraster <- passage(trC, sP1, sP2, 2)
plot(rSPraster)
points(sP1)
points(sP2)

#randomised shortest paths with theta = 0.05
rSPraster <- passage(trC, sP1, sP2, 0.05)
plot(rSPraster)
points(sP1)
points(sP2)

#randomised shortest paths with theta = 0.05
#and total
rSPraster <- passage(trC, sP1, sP2, 0.05, totalNet = "total")
plot(rSPraster)
points(sP1)
points(sP2)

#random walk
rwraster <- passage(trR, sP1, sP2)
plot(rwraster)
points(sP1)
points(sP2)