Usage
dp_pairwise(
resistance,
locations,
method = c("random", "exact"),
resistance_is = "resistances",
n_draws = 32,
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.- locations
The focal nodes: a two-column matrix or data frame of x and y coordinates (each snapped to the cell it falls in), or a terra::SpatRaster or file path on the same grid as
resistancewith a positive integer ID at each focal node's cell and 0 or NA elsewhere. Each node is one cell; focal regions of several cells aren't supported.- method
Character.
"random"(default) for random dipoles, or"exact"for the exact sum from one solve per node.- resistance_is
Character. Whether
resistanceholds"resistances"(default) or"conductances". Ignored for a circuit.- n_draws
Integer. Number of draws (solves) for
method = "random". Default32.- 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 one layer, current. Attributes:
"n_pairs", the number of pairs counted; for method = "random", also
"halves" (see dp_omni()) and "seed".
Details
Maps connectivity among every pair of a set of focal nodes, the
squared-current analogue of cs_pairwise()'s cumulative current map, at
a cost that doesn't grow with the number of nodes.
For each link \(e\) of the circuit (see dp_circuit()), the target is
\(\sum_{i<j} I_e(i,j)^2\), over unordered pairs of focal nodes, where
\(I_e(i,j)\) is the current through \(e\) when one unit flows from
node \(i\) to node \(j\). A cell's value is
\(\sqrt{\frac{1}{2}\sum_{e \ni \mathrm{cell}} (\cdot)}\) over its
links, as in dp_omni(). Pairs are counted only within groups of cells
connected to each other (no current passes across NA cells).
With method = "random", each draw injects
\(\sum_{i<j} \xi_{ij}(e_i - e_j)\), every pair weighted by an
independent standard normal \(\xi_{ij}\), and solves the circuit once;
the mean squared current over draws estimates the target without bias.
Its time hardly depends on the number of nodes (building each injection
takes \(O(N^2)\), which is small next to a solve until \(N\) is in
the thousands). With method = "exact", one solve per node gives the
exact target, using
\(\sum_{i<j}(y_i - y_j)^2 = N\sum_i y_i^2 - (\sum_i y_i)^2\) for each
link, with \(y_i\) its current when node \(i\) is the source.
Unlike Circuitscape's cell maps, no current is added at focal nodes for the current injected there.
Reproducibility is as for dp_omni().
Examples
if (FALSE) { # circuitscaper::cs_julia_available()
resistance <- terra::rast(system.file("extdata/resistance.tif",
package = "circuitscaper"))
set.seed(1)
nodes <- terra::spatSample(resistance, 30, xy = TRUE)[, 1:2]
result <- dp_pairwise(resistance, nodes, seed = 1)
exact <- dp_pairwise(resistance, nodes, method = "exact")
terra::plot(c(result, exact))
DONTSHOW({JuliaConnectoR::stopJulia()})
}
