Package {circuitscaper}

circuitscaper: 'Circuitscape' and 'Omniscape' Connectivity Analysis via 'Julia'

Description

Provides an R-native interface to the 'Circuitscape.jl' and 'Omniscape.jl' 'Julia' packages for landscape connectivity modeling using circuit theory. Users work entirely in R with familiar objects (SpatRaster, file paths) while 'Julia' handles computation invisibly. Supports all four 'Circuitscape' modes (pairwise, one-to-all, all-to-one, advanced) and 'Omniscape' moving-window analysis. Methods are described in McRae (2006) doi:10.1111/j.0014-3820.2006.tb00500.x and Landau et al. (2021) doi:10.21105/joss.02829.

Author(s)

Maintainer: Matthew Kling mattkling@berkeley.edu [copyright holder]

Authors:

• Matthew Kling mattkling@berkeley.edu [copyright holder]

See Also

Useful links:

• https://github.com/matthewkling/circuitscaper

• https://matthewkling.github.io/circuitscaper/

• Report bugs at https://github.com/matthewkling/circuitscaper/issues

Advanced Circuitscape Analysis

Description

Solve a single circuit with user-specified source and ground layers.

Usage

cs_advanced(
  resistance,
  source,
  ground,
  resistance_is = "resistances",
  ground_is = "resistances",
  use_unit_currents = FALSE,
  use_direct_grounds = FALSE,
  short_circuit = NULL,
  source_ground_conflict = "keepall",
  four_neighbors = FALSE,
  avg_resistances = FALSE,
  solver = "cg+amg",
  output_dir = NULL,
  verbose = FALSE
)

Arguments

Details

Unlike the other Circuitscape modes, advanced mode does not iterate over focal nodes. Instead, the user provides explicit source current and ground conductance rasters, and a single circuit is solved. This gives full control over the current injection pattern and is useful for modeling specific scenarios such as directional movement between a defined source area and destination.

Value

A terra::SpatRaster with the following layers:

current

Current density at each cell.

voltage

Voltage at each cell. Voltage is analogous to movement probability and decreases with distance from sources.

References

McRae, B.H. (2006). Isolation by resistance. Evolution, 60(8), 1551–1561. doi:10.1111/j.0014-3820.2006.tb00500.x

Circuitscape.jl: https://docs.circuitscape.org/Circuitscape.jl/latest/

See Also

cs_pairwise(), cs_one_to_all(), cs_all_to_one(), cs_setup()

Examples

library(terra)
res <- rast(system.file("extdata/resistance.tif", package = "circuitscaper"))
origin <- rast(system.file("extdata/source.tif", package = "circuitscaper"))
dest <- rast(system.file("extdata/ground.tif", package = "circuitscaper"))
result <- cs_advanced(res, origin, dest, ground_is = "conductances")
plot(result)

All-to-One Circuitscape Analysis

Description

For each focal node in turn, inject current at all other focal nodes and ground that single node.

Usage

cs_all_to_one(
  resistance,
  locations,
  resistance_is = "resistances",
  four_neighbors = FALSE,
  avg_resistances = FALSE,
  short_circuit = NULL,
  included_pairs = NULL,
  write_voltage = FALSE,
  cumulative_only = TRUE,
  source_strengths = NULL,
  solver = "cg+amg",
  output_dir = NULL,
  verbose = FALSE
)

Arguments

Details

All-to-one mode iterates over each focal node. In each iteration, all other focal nodes are injected with 1 amp of current each, and the focal node is connected to ground. This produces a current map showing how current converges on that node from across the landscape.

This mode is useful for identifying the most accessible or reachable sites in the network, emphasizing current flow toward each ground node. The cumulative map sums across all iterations and highlights cells that are important for connectivity across the full set of nodes.

Value

A terra::SpatRaster with the following layers:

cumulative_current

Current flow summed across all iterations.

current_N

Per-node current map for focal node N, where N is the integer node ID from the locations raster. One layer per focal node.

References

McRae, B.H. (2006). Isolation by resistance. Evolution, 60(8), 1551–1561. doi:10.1111/j.0014-3820.2006.tb00500.x

Circuitscape.jl: https://docs.circuitscape.org/Circuitscape.jl/latest/

See Also

cs_pairwise(), cs_one_to_all(), cs_advanced(), cs_setup()

Examples

library(terra)
res <- rast(system.file("extdata/resistance.tif", package = "circuitscaper"))
coords <- matrix(c(10, 40, 40, 40, 10, 10, 40, 10), ncol = 2, byrow = TRUE)
result <- cs_all_to_one(res, coords)
plot(result)

Install Julia and Required Packages

Description

Downloads and installs Julia, Circuitscape.jl, and Omniscape.jl. This is the recommended first step after installing the circuitscaper R package.

Usage

cs_install_julia(force = FALSE, version = "latest")

Arguments

Details

In interactive sessions, prompts for confirmation before downloading. In non-interactive sessions (e.g., CI), proceeds without prompting.

Value

Invisibly returns TRUE on success, FALSE if cancelled.

Examples

## Not run: 
cs_install_julia()

## End(Not run)

Check if Julia and Required Packages Are Available

Description

Tests whether Julia is installed and the Circuitscape and Omniscape Julia packages can be loaded. This is a lightweight check that does not initialize a full Julia session. It is used internally by example code and can be called by users to verify their setup before running analyses.

Usage

cs_julia_available()

Value

TRUE if Julia is found on the system PATH and the 'Circuitscape' and 'Omniscape' Julia packages load successfully, FALSE otherwise.

Examples

cs_julia_available()

One-to-All Circuitscape Analysis

Description

For each focal node in turn, inject current at that node and ground all other focal nodes simultaneously.

Usage

cs_one_to_all(
  resistance,
  locations,
  resistance_is = "resistances",
  four_neighbors = FALSE,
  avg_resistances = FALSE,
  short_circuit = NULL,
  included_pairs = NULL,
  write_voltage = FALSE,
  cumulative_only = TRUE,
  source_strengths = NULL,
  solver = "cg+amg",
  output_dir = NULL,
  verbose = FALSE
)

Arguments

Details

One-to-all mode iterates over each focal node. In each iteration, the focal node is injected with 1 amp of current and all remaining focal nodes are simultaneously connected to ground. This produces a current map showing how current spreads from that node through the landscape to reach the others.

This mode is useful for mapping how well each site is connected to the rest of the focal node network, emphasizing current dispersal from each source. The cumulative map sums across all iterations and highlights cells that are important for connectivity across the full set of nodes.

Value

A terra::SpatRaster with the following layers:

cumulative_current

Current flow summed across all iterations.

current_N

Per-node current map for focal node N, where N is the integer node ID from the locations raster. One layer per focal node.

References

McRae, B.H. (2006). Isolation by resistance. Evolution, 60(8), 1551–1561. doi:10.1111/j.0014-3820.2006.tb00500.x

Circuitscape.jl: https://docs.circuitscape.org/Circuitscape.jl/latest/

See Also

cs_pairwise(), cs_all_to_one(), cs_advanced(), cs_setup()

Examples

library(terra)
res <- rast(system.file("extdata/resistance.tif", package = "circuitscaper"))
coords <- matrix(c(10, 40, 40, 40, 10, 10, 40, 10), ncol = 2, byrow = TRUE)
result <- cs_one_to_all(res, coords)
plot(result)

Pairwise Circuitscape Analysis

Description

Compute pairwise effective resistances and cumulative current flow between all pairs of focal nodes.

Usage

cs_pairwise(
  resistance,
  locations,
  resistance_is = "resistances",
  four_neighbors = FALSE,
  avg_resistances = FALSE,
  short_circuit = NULL,
  included_pairs = NULL,
  write_voltage = FALSE,
  cumulative_only = TRUE,
  source_strengths = NULL,
  solver = "cg+amg",
  output_dir = NULL,
  verbose = FALSE
)

Arguments

Details

Pairwise mode iterates over every unique pair of focal nodes. For each pair, one node is injected with 1 amp of current and the other is connected to ground. The effective resistance between the pair is recorded, and the resulting current flow is accumulated across all pairs into a cumulative current map that highlights important movement corridors.

This is the most common Circuitscape mode and is typically used to quantify connectivity between discrete habitat patches or populations. The resistance matrix can be used as a distance metric in analyses such as isolation by resistance.

Value

A named list with:

current_map

A terra::SpatRaster. By default contains a single cumulative_current layer (current flow summed across all pairs). When cumulative_only = FALSE, additional per-pair layers are included (e.g., current_1_2, current_1_3). When write_voltage = TRUE, per-pair voltage layers are included (e.g., voltage_1_2, voltage_1_3).

resistance_matrix

A symmetric numeric matrix of pairwise effective resistances between focal nodes, with node IDs as row and column names.

References

McRae, B.H. (2006). Isolation by resistance. Evolution, 60(8), 1551–1561. doi:10.1111/j.0014-3820.2006.tb00500.x

Circuitscape.jl: https://docs.circuitscape.org/Circuitscape.jl/latest/

See Also

cs_one_to_all(), cs_all_to_one(), cs_advanced(), cs_setup()

Examples

library(terra)
res <- rast(system.file("extdata/resistance.tif", package = "circuitscaper"))
coords <- matrix(c(10, 40, 40, 40, 10, 10, 40, 10), ncol = 2, byrow = TRUE)
result <- cs_pairwise(res, coords, cumulative_only = FALSE)
plot(result$current_map)
result$resistance_matrix

Set Up Julia and Load Circuitscape/Omniscape

Description

Initialize the Julia session and load the Circuitscape and Omniscape Julia packages. This is called automatically on first use of any ⁠cs_*⁠ or ⁠os_*⁠ function. Call explicitly to control the Julia path, number of threads, or pre-warm the session.

Usage

cs_setup(julia_home = NULL, threads = 1L, quiet = TRUE, ...)

Arguments

Details

cs_setup() does not install Julia or Julia packages. If Julia is not found or the required packages are missing, it throws an informative error directing you to cs_install_julia().

cs_setup() will:

• Verify that Julia is installed and accessible.

• Verify that the Circuitscape and Omniscape Julia packages are installed.

• Load both packages and warm up the JIT compiler.

Once Julia is initialized, it stays warm for the R session. Subsequent calls to cs_setup() return immediately.

Threading

Julia's thread count is fixed at startup and cannot be changed mid-session. Multi-threading is used by os_run() when parallelize = TRUE. Circuitscape functions (cs_pairwise, cs_one_to_all, etc.) do not benefit from multiple threads.

cs_setup(threads = 4)
os_run(resistance, radius = 50, parallelize = TRUE)

Value

Invisibly returns TRUE on success.

References

McRae, B.H. (2006). Isolation by resistance. Evolution, 60(8), 1551–1561. doi:10.1111/j.0014-3820.2006.tb00500.x

Landau, V.A., Shah, V.B., Anantharaman, R. & Hall, K.R. (2021). Omniscape.jl: Software to compute omnidirectional landscape connectivity. Journal of Open Source Software, 6(57), 2829. doi:10.21105/joss.02829

Circuitscape.jl: https://docs.circuitscape.org/Circuitscape.jl/latest/

Omniscape.jl: https://docs.circuitscape.org/Omniscape.jl/latest/

See Also

cs_install_julia(), cs_pairwise(), os_run()

Examples

cs_setup()
cs_setup(threads = 4)
cs_setup(julia_home = "/usr/local/julia/bin")

Define a Condition for Conditional Omniscape Connectivity

Description

Creates a condition specification for use with the condition argument of os_run(). Conditional connectivity restricts which source cells are connected to each target, based on how their values on a condition layer (e.g., climate, land cover class) compare. Conditions can compare present-day values at both sources and targets, or present-day values at sources against future values at targets (e.g., for climate-tracking connectivity).

Usage

os_condition(
  present,
  future = NULL,
  type = c("equal", "within"),
  lower = NULL,
  upper = NULL
)

Arguments

Details

Omniscape evaluates each moving-window target against every source cell in the window, and sets the strength of any source that fails the comparison to zero for that target. The target's value is summarized over its block (see block_size in os_run()): the median for "within", and the mode for "equal". When block_size = 1 this is simply the target cell's value.

Omniscape requires a condition value at every source cell. Source cells with a missing (NA) present-day condition value are not filtered out; they remain sources for every target. os_run() warns if it detects this.

"equal" compares values exactly, so it is only meaningful for categorical (integer-valued) layers; a warning is issued if a SpatRaster supplied with type = "equal" contains non-integer values.

Up to two conditions can be combined by passing a list of two os_condition() objects to os_run(); a source must satisfy both to be connected.

Value

An object of class "os_condition": a list with elements present, future, type, lower, and upper.

References

Omniscape.jl conditional connectivity options: https://docs.circuitscape.org/Omniscape.jl/latest/usage/

See Also

os_run()

Examples

library(terra)
temp_now <- rast(nrows = 20, ncols = 20, vals = rep(1:20, each = 20))
temp_future <- temp_now + 2

# Climate-tracking: connect sources to targets whose future temperature is
# between 1 unit cooler and 3 units warmer than the source's present value
# (i.e., source - target_future within [-3, 1])
os_condition(temp_now, future = temp_future, lower = -3, upper = 1)

# Categorical: connect only cells of the same land cover class
landcover <- rast(nrows = 20, ncols = 20, vals = sample(1:3, 400, TRUE))
os_condition(landcover, type = "equal")

Run Omniscape Moving-Window Connectivity Analysis

Description

Performs an Omniscape analysis, computing omnidirectional landscape connectivity using a moving window approach based on circuit theory.

Usage

os_run(
  resistance,
  radius,
  source_strength = NULL,
  block_size = 1L,
  source_threshold = 0,
  r_cutoff = Inf,
  resistance_is = "resistances",
  calc_normalized_current = TRUE,
  calc_flow_potential = TRUE,
  condition = NULL,
  condition_type = NULL,
  parallelize = FALSE,
  julia_threads = 2L,
  solver = "cg+amg",
  output_dir = NULL,
  verbose = FALSE
)

Arguments

Value

A terra::SpatRaster with the following layers (depending on options):

cumulative_current

Raw cumulative current flow. Always present. Higher values indicate cells that carry more current across all moving-window iterations.

flow_potential

Expected current under homogeneous resistance (if calc_flow_potential = TRUE). Reflects the spatial configuration of sources independently of landscape resistance.

normalized_current

Cumulative current divided by flow potential (if calc_normalized_current = TRUE). Values greater than 1 indicate cells where connectivity is higher than expected given the source geometry; values less than 1 indicate relative barriers. This is typically the most informative layer for identifying corridors and pinch points.

References

Landau, V.A., Shah, V.B., Anantharaman, R. & Hall, K.R. (2021). Omniscape.jl: Software to compute omnidirectional landscape connectivity. Journal of Open Source Software, 6(57), 2829. doi:10.21105/joss.02829

Omniscape.jl: https://docs.circuitscape.org/Omniscape.jl/latest/

See Also

os_condition(), cs_pairwise(), cs_setup()

Examples

library(terra)
res <- rast(system.file("extdata/resistance.tif", package = "circuitscaper"))
result <- os_run(res, radius = 10)
plot(result)

# Conditional connectivity: only connect cells in the same zone
# (here, the left and right halves of the landscape)
zones <- (init(res, "col") > ncol(res) / 2) + 1
result_cond <- os_run(res, radius = 10, condition = zones)
plot(result_cond)