Usage
dp_pathways(
resistance,
present,
future,
radius,
source_threshold = 0.01,
radius_units = c("pixels", "km"),
resistance_is = "resistances",
normalize = TRUE,
n_draws = 32,
n_dipoles = 1e+05,
seed = NULL
)Arguments
- resistance
A terra::SpatRaster or file path: the resistance (or conductance) surface. Or a circuit from
dp_circuit(), to reuse its factorization.- present, future
terra::SpatRasters or file paths on the same grid as
resistance: present and future source strength, e.g. habitat suitability. NA counts as 0.- radius
Numeric. The dispersal radius: pairs of cells are counted if their centres are at most this far apart. In pixels by default (see
radius_units).Infcounts all pairs.- source_threshold
Numeric. Cells with source strength below this are not sources. Default
0.01.- radius_units
Character.
"pixels"(default): the radius counts cells, so the kernel is the cells with \(dr^2 + dc^2 \le\)radius\(^2\), as inos_run()."km": great-circle distance between cell centres on lon/lat grids (the kernel narrows in degrees of longitude towards the poles), or distance in the coordinate reference system's units, converted to km, on projected grids.- resistance_is
Character. Whether
resistanceholds"resistances"(default) or"conductances". Ignored for a circuit.- normalize
Logical. Also compute flow potential (the same dipoles on the uniform circuit) and normalized current. Default
TRUE.- n_draws
Integer. Number of draws (solves). Default
32.- n_dipoles
Integer. Number of dipoles per draw. Default
1e5.- seed
Integer or
NULL. Seed for the random draws. IfNULL(default), one is drawn from R's random number generator, soset.seed()also makes runs reproducible. The seed used is returned as the"seed"attribute.
Value
As for dp_omni(). The "halves" diagnostic is over cells that
are present or future sources.
Details
Maps the pathways that connect present habitat to future habitat within dispersal reach: random-sign dipoles with one end in present habitat and the other in future habitat. Magnitude only, without direction.
As dp_omni(), with pairs \((i, j)\) weighted by
\(p_i f_j k(d_{ij})\): \(i\) in present habitat, \(j\) in future
habitat, within radius of each other. The pairing is one-way, but the
squared current of a pair is the same in both directions, so random
signs are valid. Stable habitat (suitable in both eras) takes part at
both ends, unlike in dp_flux(). See dp_omni() for the estimator,
accuracy, reproducibility and performance.
Examples
if (FALSE) { # circuitscaper::cs_julia_available()
resistance <- terra::rast(system.file("extdata/resistance.tif",
package = "circuitscaper"))
present <- terra::rast(system.file("extdata/source.tif", package = "circuitscaper"))
future <- terra::flip(present, "horizontal")
result <- dp_pathways(resistance, present, future, radius = 20, seed = 1)
terra::plot(result)
DONTSHOW({JuliaConnectoR::stopJulia()})
}
