terralink

Standalone R implementation of the TerraLink corridor optimization workflows (raster + vector).

This package mirrors the current QGIS TerraLink plugin capabilities while keeping the workflow scriptable and clear for R users.

Raster inputs are polygonized and analyzed through the vector corridor pipeline, matching the current QGIS plugin workflow. The R result still includes rasterized display layers for raster runs, but the corridor selection itself is the shared vector-polygonized workflow.

Canonical TerraLink strategies:

• most_connected_networks
• most_connected_networks_2
• largest_single_network
• landscape_fluidity

Current state

• Raster and vector workflows share the same corridor-selection backend.
• Raster runs accept patch values/ranges and optional impassable values/ranges, then polygonize habitat before corridor generation.
• Vector runs accept polygon patches and optional polygon obstacles.
• Both workflows return PRE/POST metrics and strategy-specific run statistics.
• R raster runs additionally return corridor_raster and contiguous_raster objects for plotting and optional GeoTIFF export.
• The QGIS plugin and web runner save vector-style corridor outputs for raster inputs; the R package exposes both the vectorized result and rasterized display rasters.

What TerraLink is for

TerraLink is designed for scenario-based corridor planning rather than one-shot "best answer" mapping.

A typical workflow is:

1. load habitat data
2. choose a strategy that matches the ecological outcome you care about
3. set approximate planning constraints such as budget, corridor width, and search distance
4. run a few plausible scenarios
5. compare the PRE/POST metrics and mapped outputs

This is the same framing used in the QGIS plugin: TerraLink is most useful when you compare alternatives and decide which tradeoff is best for the landscape, not when you expect a single universal score to answer the problem.

Project links

• TerraLink online tool: https://sorusconsultingllc.com/tools/terralink-online
• QGIS plugin source: https://github.com/sorus-tools/TerraLink
• Contact: info@sorusconsultingllc.com

Install

install.packages("remotes")
remotes::install_local("/path/to/terralink")
library(terralink)

Quick start

library(terralink)

paths <- terralink_sample_data()
paths
# $raster   -> .../extdata/habitat.tif
# $vector   -> .../extdata/patches.gpkg
# $obstacle -> .../extdata/impassable.gpkg

# Raster workflow
res_r <- terralink_raster(
  raster = paths["raster"],
  patch_values = 1,
  obstacle_values = 2,
  budget = 220,
  min_patch_size = 10,
  min_corridor_width = 3,
  max_search_distance = 30,
  corridor_cell_assignment = "sum_total_network_area",
  units = "pixels",
  strategy = "most_connected_networks"
)
plot(res_r)

# Vector workflow
res_v <- terralink_vector(
  patches = paths["vector"],
  budget = 2.5,
  min_patch_size = 0.1,
  min_corridor_width = 20,
  max_search_distance = 500,
  units = "metric",
  strategy = "most_connected_networks"
)
plot(res_v)

Optimization modes

The TerraLink 1.8 strategies are not interchangeable labels. Each one rewards a different kind of connectivity improvement.

• largest_single_network: build one dominant connected backbone.
• most_connected_networks: Most Connected Networks A; maximize total habitat area placed into connected subnetworks.
• most_connected_networks_2: Most Connected Networks B; prioritize high-value joins between existing components, including components that are already subnetworks.
• landscape_fluidity: improve movement quality, alternative routing, and bottleneck relief.

In practice:

• use largest_single_network when you want one strong consolidated system
• use most_connected_networks when you want broad structural integration by connected subnetwork area
• use most_connected_networks_2 when you want pair-value-driven joins between components or subnetworks
• use landscape_fluidity when movement redundancy and detour relief matter

That distinction matters because structural metrics and functional accessibility metrics capture different ecological processes, so mode choice should follow the planning question rather than habit.

Units

For terralink_raster():

• units = "pixels" keeps patch size, budget, corridor width, and search distance in raster-cell units.
• units = "metric" uses hectares for patch size and budget, and meters for corridor width and search distance.
• units = "imperial" uses acres for patch size and budget, and feet for corridor width and search distance.

For terralink_vector():

• units = "metric" uses hectares for patch size and budget, and meters for corridor width and search distance.
• units = "imperial" uses acres for patch size and budget, and feet for corridor width and search distance.

This differs from the QGIS dialog labels, where measured search radius is shown in km/mi for user convenience.

Scripts

Packaged scripts are discoverable from R:

terralink_examples()
terralink_examples("raster")
terralink_examples("vector")
terralink_sample_data()

Main scripts:

• inst/scripts/run_raster.R
• inst/scripts/run_vector.R
• inst/scripts/example_raster_barbados.R
• inst/scripts/example_vector_barbados.R

The two example_*_barbados.R scripts use the exact parameter sets validated during raster/vector parity testing.

Outputs

Raster:

• corridors: selected corridor geometries from the vector-polygonized backend.
• networks: connected patch-plus-corridor network polygons.
• corridor_raster: rasterized corridor display layer, labeled according to corridor_cell_assignment.
• contiguous_raster: rasterized habitat + corridor connected networks.
• patches: patch-label raster.
• patch_table, summary fields, strategy statistics, and metrics report text.

Raster runs are delegated through the vector engine after polygonizing habitat and impassable areas, so raster and vector workflows share the same corridor-selection core.

When write_outputs = TRUE, raster runs write GeoTIFF display rasters plus CSV summaries/tables and the metrics report. They do not write the same QGIS GeoPackage bundle unless you export the returned sf objects yourself.

Vector:

• corridors (sf): buffered corridor polygons with metrics.
• networks (sf): dissolved connected networks.
• CSV summary + metrics report text.

When write_outputs = TRUE, vector runs write a GeoPackage containing corridor and network layers, a CSV summary, and the metrics report.

Interpreting metrics

The package writes PRE/POST metrics so you can compare scenarios on the same landscape.

The most useful habit is comparative interpretation:

• compare scenario A vs scenario B on the same data
• compare PRE vs POST for the same scenario
• avoid treating one metric value as a context-free "true" connectivity score

Some metrics are mainly structural, such as connected habitat area and largest network area. Others are closer to functional accessibility or whole-network movement behavior, such as habitat availability and fluidity-oriented summaries. That distinction is important when deciding whether your goal is consolidation, broad structural gain, or species-relevant reachability.

Raster and vector workflows share the same corridor-selection backend in TerraLink 1.8, but they can still differ modestly because raster inputs are first converted into polygon patches and optional obstacle polygons before corridor generation. The safest comparison is still scenario-vs-scenario within the same pipeline.

Obstacle-aware routing (optional)

If you want corridors to route around impassable features, install the optional packages and enable obstacles:

# Optional (for shortest-path routing around obstacles)
install.packages(c("gdistance", "raster", "sp"))

result <- terralink_vector(
  patches = terralink_sample_data("vector"),
  budget = 2.5,
  min_corridor_width = 20,
  max_search_distance = 500,
  units = "metric",
  obstacle_layers = terralink_sample_data("obstacle"),
  obstacle_resolution = 10
)

Raster mode supports impassable values/ranges directly from the raster and funnels them through the same vector corridor engine:

result <- terralink_raster(
  raster = terralink_sample_data("raster"),
  patch_values = 1,
  obstacle_values = 2,
  budget = 220,
  units = "pixels"
)