Overview

Run_CS.ini() is a low-level Circuitscape wrapper for cases where you want to run Circuitscape directly from R without going through the optimization workflow.

It complements Run_CS.jl() rather than replacing it.

• Run_CS.jl() is tailored to the package optimization workflow.
• Run_CS.ini() is tailored to direct Circuitscape runs.
• Both use Julia and Circuitscape.jl through JuliaConnectoR.

The main advantage of Run_CS.ini() is that it lets you work from R objects while still thinking in terms of the Circuitscape .ini file.

Julia Setup

You still need Julia and Circuitscape.jl installed.

JULIA_HOME <- "C:/Users/your-name/AppData/Local/Programs/Julia-<version>/bin/"

Pass JULIA_HOME directly to Run_CS.ini(). The package temporarily configures JULIA_BINDIR for that call and restores the previous value when the function returns, which keeps other R projects from inheriting this vignette’s Julia choice.

Example Inputs

pts <- vect(samples[, 2:3], type = "points")
surface <- terra::subset(surfaces, "continuous")

pts
#> class       : SpatVector
#> geometry    : points
#> dimensions  : 25, 0  (geometries, attributes)
#> extent      : 6.25, 19.25, 6.25, 19.25  (xmin, xmax, ymin, ymax)
#> coord. ref. :
surface
#> class       : SpatRaster
#> size        : 50, 50, 1  (nrow, ncol, nlyr)
#> resolution  : 0.5, 0.5  (x, y)
#> extent      : 0, 25, 0, 25  (xmin, xmax, ymin, ymax)
#> coord. ref. : 
#> source(s)   : memory
#> name        : continuous
#> min value   :   6.514823
#> max value   :  13.376758

Pairwise Circuitscape with INI-Style Options

pairwise_out <- Run_CS.ini(
  r = surface,
  CS_Point.File = pts,
  JULIA_HOME = JULIA_HOME,
  scenario = "pairwise",
  connect_four_neighbors_only = TRUE,
  write_cur_maps = TRUE,
  write_cum_cur_map_only = TRUE,
  return = "all",
  rm.files = FALSE
)

The returned object includes the raw Julia result, a parsed pairwise matrix when one can be extracted, any current map written by Circuitscape, the final config, and the paths to generated files.

names(pairwise_out)
pairwise_out$ini_file
pairwise_out$pairwise_matrix
pairwise_out$config

Working from R Objects Instead of Manual Files

Run_CS.ini() can now write several Circuitscape support files directly from R objects.

Supported convenience inputs include:

• mask_file
• source_file
• ground_file
• included_pairs_file
• reclass_file

source_r <- rast(surface)
ground_r <- rast(surface)
mask_r <- rast(surface)

source_vals <- rep(0, ncell(source_r))
ground_vals <- rep(0, ncell(ground_r))
source_vals[5] <- 1
ground_vals[ncell(ground_r) - 4] <- 1

values(source_r) <- source_vals
values(ground_r) <- ground_vals
values(mask_r) <- 1

advanced_out <- Run_CS.ini(
  r = surface,
  JULIA_HOME = JULIA_HOME,
  scenario = "advanced",
  source_file = source_r,
  ground_file = ground_r,
  ground_file_is_resistances = FALSE,
  mask_file = mask_r,
  return = "all",
  rm.files = FALSE
)

keep_pairs <- data.frame(
  node1 = c(1, 1, 2),
  node2 = c(2, 3, 4)
)

pairwise_subset <- Run_CS.ini(
  r = surface,
  CS_Point.File = pts,
  JULIA_HOME = JULIA_HOME,
  included_pairs_file = keep_pairs,
  return = "all",
  rm.files = FALSE
)

pairwise_exclude <- Run_CS.ini(
  r = surface,
  CS_Point.File = pts,
  JULIA_HOME = JULIA_HOME,
  included_pairs_file = list(
    mode = "exclude",
    pairs = keep_pairs
  ),
  return = "all"
)

reclass_tbl <- data.frame(
  from = c(1, 2, 3),
  to = c(5, 25, 100)
)

reclass_out <- Run_CS.ini(
  r = terra::subset(surfaces, "categorical"),
  CS_Point.File = pts,
  JULIA_HOME = JULIA_HOME,
  reclass_file = reclass_tbl,
  return = "all",
  rm.files = FALSE
)

Existing Paths Still Work

If you already have files prepared on disk, you can still pass them directly.

Run_CS.ini(
  r = "my_surface.asc",
  CS_Point.File = "my_points.txt",
  JULIA_HOME = JULIA_HOME,
  mask_file = "mask.asc",
  source_file = "sources.asc",
  ground_file = "grounds.asc",
  included_pairs_file = "pairs.txt",
  return = "all"
)

Inspecting the Generated INI

Keeping the files can be useful while debugging or comparing against a hand-written Circuitscape setup.

out <- Run_CS.ini(
  r = surface,
  CS_Point.File = pts,
  JULIA_HOME = JULIA_HOME,
  scenario = "pairwise",
  return = "all",
  rm.files = FALSE
)

readLines(out$ini_file)

Return Modes

raw_out <- Run_CS.ini(..., return = "compute")
matrix_out <- Run_CS.ini(..., return = "matrix")
map_out <- Run_CS.ini(..., return = "current_map")
all_out <- Run_CS.ini(..., return = "all")

• compute returns the raw Julia object
• matrix returns a parsed pairwise matrix when possible
• current_map returns the cumulative current map raster when written
• all returns the full bundle

Relationship to the Optimization Workflow

If your goal is landscape genetic optimization, the usual workflow is still:

1. GA.prep()
2. gdist.prep() or jl.prep()
3. SS_optim(), MS_optim(), or all_comb()

Use Run_CS.ini() when you want more direct access to Circuitscape itself, especially for advanced mode or for explicit .ini-style control.

Quick reference: direct Circuitscape control

library(ResistanceGA2)
library(terra)

# 1. Choose the Julia bin/ directory for this project.
JULIA_HOME <- "C:/Users/your-name/AppData/Local/Programs/Julia-<version>/bin/"

# 2. Prepare bundled example inputs.
surfaces <- resistance_surfaces
if (inherits(surfaces, "PackedSpatRaster")) {
  surfaces <- terra::unwrap(surfaces)
}
surface <- terra::subset(surfaces, "continuous")
pts <- terra::vect(samples[, 2:3], type = "points")

# 3. Run Circuitscape with explicit .ini-style control.
out <- Run_CS.ini(
  r = surface,
  CS_Point.File = pts,
  JULIA_HOME = JULIA_HOME,
  scenario = "pairwise",
  return = "all",
  rm.files = FALSE
)

# 4. Inspect the outputs that Circuitscape and ResistanceGA2 created.
out$pairwise_matrix  # parsed pairwise matrix, when available
out$ini_file         # generated .ini file for debugging or reuse
out$generated_files  # Circuitscape output files written during the run

How to read the output: Run_CS.ini(return = "all") returns the raw Julia result, any parsed pairwise matrix, any cumulative current map, the generated .ini file, the final Circuitscape configuration, and the files written during the run. Use this mode when you are debugging or translating a hand-written Circuitscape analysis into a reproducible R workflow.

Summary of key functions

See also

• vignette("Julia_Guide", package = "ResistanceGA2"), installing Julia, configuring JULIA_HOME, and troubleshooting Julia/Circuitscape setup.
• vignette("GettingStarted", package = "ResistanceGA2"), the core ResistanceGA2 workflow.
• vignette("ResistanceGA", package = "ResistanceGA2"), full optimization workflows using gdist.inputs or jl.inputs.