
Directional and Undirected Flow Between Two Distributions
Source:R/dp-directionality.R
dp_directionality.RdUsage
dp_directionality(
resistance,
origin,
destination,
radius = Inf,
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.- origin, destination
terra::SpatRasters or file paths on the same grid as
resistance: origin and destination strength, e.g. habitat suitability in two periods or seasons. NA counts as 0.- radius
Numeric. The dispersal radius: origin and destination cells are paired if their centres are at most this far apart. In pixels by default (see
radius_units). DefaultInf, no distance limit.- source_threshold
Numeric. Cells with origin or destination strength below this are not origins or destinations. 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 and normalized current for both maps (on the uniform circuit, conductance 1 on the same cells). 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
A terra::SpatRaster with layers:
- directionality
The ratio \(R\) above, between 0 and 1.
- flux_current
The directional map's RMS current, as
dp_flux(cell_value = "rms")'scurrent.- flux_flow_potential, flux_normalized_current
(with
normalize) Asdp_flux()'sflow_potentialandnormalized_current.- flow_x, flow_y
Net flow through the cell towards the east and the north, as from
dp_flux().- omni_current
The undirected map's current, as
dp_omni(destination = )'scurrent.- omni_flow_potential, omni_normalized_current
(with
normalize) Asdp_omni()'sflow_potentialandnormalized_current.
Attributes: "halves", comparing the estimates from odd and even draws
on origin and destination cells, as in dp_omni(), for the undirected
layers and directionality; "seed"; and "in_reach", as in
dp_flux().
Details
Maps movement between an origin and a destination distribution both ways
at once, from the same pairs of cells: the directional map of
dp_flux(), where flows in opposite directions cancel, and the
undirected map of dp_omni() with a destination, where they don't.
Their ratio, directionality, shows where movement between the two
distributions is one-way and where it runs both ways.
Current flows along the circuit's links: the resistors joining each cell
to its 8 neighbours (see dp_circuit()). Both maps sum over pairs of an
origin cell \(i\) and a destination cell \(j\), with weights
\(o_i d_j k(d_{ij})\): \(o\) and \(d\) are origin and destination
strength, and \(k\) is 1 for cells within radius of each other (in the
same component) and 0 otherwise. With \(W\) the total weight and
\(I_e(i,j)\) the current through link \(e\) when one unit flows from
\(i\) to \(j\), the directional map is the pairs' weighted mean
current, \(F_e = \sum_{i,j} o_i d_j k(d_{ij}) I_e(i,j) / W\), and the
undirected map their summed squared current,
\(U_e = \sum_{i,j} o_i d_j k(d_{ij}) I_e(i,j)^2\).
Since \(U_e / W\) is the pairs' weighted mean square current, the
ratio
$$R_e = \frac{W F_e^2}{U_e} = 1 - \frac{\mathrm{Var}(I_e)}{\mathrm{E}[I_e^2]}$$
is between 0 and 1. Like an \(R^2\), it is the share of the pairs'
squared current that their mean flow accounts for, and so the share of
the power they dissipate in the link: 1 where all pairs cross the link in
the same direction, and near 0 where their flows cancel. A cell's
directionality is the same ratio over the links that meet at it,
\(W \sum_e F_e^2 / \sum_e U_e\): the links' \(R_e\) averaged with
weights \(U_e\).
The directional map is exact; the undirected map is estimated from random
dipoles centered on the pairs' mean, as in dp_omni() with a
destination: the draws estimate only the variance of the pairs'
currents, and the mean's exact squared current is added back. So
directionality never exceeds 1, and its noise, about
\(R (1 - R) \times 1.4 / \sqrt{\mathrm{n\_draws}}\), vanishes where
movement is one-way. (Without centering, it would be about
\(R \times 1.4 / \sqrt{\mathrm{n\_draws}}\), and largest there.) It
is NA where the undirected current is zero.
The layers are as from dp_flux(cell_value = "rms") and
dp_omni(destination = ), with the same arguments, but computed together:
one circuit, one set of pair weights, and one kernel.
Examples
if (FALSE) { # circuitscaper::cs_julia_available(circuitscape = FALSE)
resistance <- terra::rast(system.file("extdata/resistance.tif",
package = "circuitscaper"))
origin <- terra::rast(system.file("extdata/source.tif", package = "circuitscaper"))
destination <- terra::rast(system.file("extdata/ground.tif", package = "circuitscaper"))
result <- dp_directionality(resistance, origin, destination, radius = 45,
normalize = FALSE, seed = 1)
terra::plot(result[[c("flux_current", "omni_current", "directionality")]])
DONTSHOW({JuliaConnectoR::stopJulia()})
}