Skip to contents

[Experimental]

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 resistance with 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 resistance holds "resistances" (default) or "conductances". Ignored for a circuit.

n_draws

Integer. Number of draws (solves) for method = "random". Default 32.

seed

Integer or NULL. Seed for the random draws. If NULL (default), one is drawn from R's random number generator, so set.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()})
}