BUILDER R Functions

fetch_builder_output()

The fetch_builder_output() function reads and returns the appropriate output CSV file generated by the Builder tool, based on the specified type ("BENCHMARKS", "UPSTREAM", or "DOWNSTREAM").

The most recent matching file is selected if multiple are found. The file is returned as a tibble.

Usage

fetch_builder_output(builder_dir,
  type = "BENCHMARKS"
)

Arguments

  • builder_dir: Path to the Builder output directory.
  • type: Type of output to retrieve. Must be one of "BENCHMARKS", "UPSTREAM", or "DOWNSTREAM". Default is "BENCHMARKS".

📤 Output

A tibble of neighbouring pairs with columns CATCHNUM and neighbours.

Examples

Running the examples

  1. Download and unzip BEACONs R Tools

  2. Run the examples below.

# Load required libraries
library(dplyr)
library(utils)
library(sf)
library(ggplot2)
library(RColorBrewer)

# Set working directory
dirpath <- "path/to/BEACONs_R_Tools"
builder_outdir <- "path/to/builder/out_dir"

setwd(dirpath)
source("./R/builder.R")

#Set access path catchments layer and initialize
catchments_sf <- st_read(file.path(dirpath,"data","catchments_sample.shp"))

# Prefix given to identify unique conservation areas
colName <- "PB"

# --------------------------------------
#--RUN
# --------------------------------------
# Map potential conservation areas generated by BUILDER
out_tab <- fetch_builder_output(builder_outdir, type = "BENCHMARKS")

# Convert builder output tables to polygons
PBx_sf <- dissolve_catchments_from_table(catchments_sf = catchments_sf, 
                                             input_table = out_tab, 
                                             out_feature_id = colName)

# Pick random set of 12 to display
PBx_sample <- PBx_sf %>%
  slice_sample(n = 12)

# Set color palette
n <- nrow(PBx_sample)
palette <- brewer.pal(min(n, 12), "Set3")

# Plot catchments and conservation areas
ggplot() +
  geom_sf(data = catchments_sf, fill = "grey90", color = "black", alpha = 0.3) +
  geom_sf(data = PBx_sample, aes(fill = PB), color = "black", alpha = 0.7) +
  scale_fill_manual(values = palette) +
  labs(
    title = "Distinct Potential Conservation Areas",
    fill = "Conservation ID"
  ) +
  theme_minimal()