BEACONs BUILDER

BUILDER is a user friendly software application, developed in C# .NET framework, to assist conservation planners with the design of ecological benchmarks. This package provides a set of R functions to call BUILDER and fetch the main output table. The partner package beaconstools provides functions to process and analyse output tables from BUILDER in R.

BUILDER explicitly incorporates hydrologic connectivity for the integration of aquatic and terrestrial conservation planning in protected areas design. BUILDER constructs ecological benchmarks using a deterministic construction algorithm that aggregates catchments to a user defined size and intactness. For the purpose of this demo, we will refer to the conservation areas created by BUILDER as benchmarks, however BUILDER can also be used to design conservation areas not intended to serve as benchmarks.

BUILDER constructs ecological benchmarks based on three principal criteria:

  • Intactness, a measure of the absence of human industrial activity and a proxy for the intactness of biological and physical processes
  • Hydrologic connectivity of intact water catchments, as a measure of the integrity of aquatic systems
  • Size, as a measure of the resilience of the system to disturbance

Catchments

The building blocks for BUILDER is a set of catchments with associated flow directions for the underlying stream network. This allows BUILDER to identify upstream and downstream catchments for any given location. Should we provide a brief description of the catchments dataset and how to download them?

Aggregation algorithm

BUILDER ‘grows’ ecological benchmarks using a deterministic construction algorithm that aggregates catchments. This process enables intactness, size and hydrologic criteria to be incorporated into benchmark design.

The starting catchments for building benchmarks are called seeds. These can be selected using size and intactness criteria e.g., all catchments that are 100% intact and greater than 500km2. Starting from a seed, BUILDER grows a benchmark by aggregating neighbouring catchments that exceed the user defined catchment-level intactness threshold. As catchments are added, growth is prioritized in the upstream direction. This emphasizes inclusion of headwaters within benchmarks, and encourages the formation of benchmarks along stream networks. Further, by adding all eligible upstream catchments before re-querying for more, benchmarks are grown with a more compact shape. If re-querying were to occur after adding each upstream catchment, benchmarks would tend to grow along single streams, resulting in linear configurations. To further compact the shape of the benchmark, BUILDER prioritizes the addition of catchments within hydrological zones (i.e. Fundamental Drainage Areas, FDAs) associated with the benchmark before adding catchments in a neighbouring FDA.

Once all available upstream catchments are added, BUILDER grows downstream. Downstream growth adds all neighbouring catchments downstream of the catchment aggregation then re-queries for upstream catchments. Benchmarks are grown until:

  1. There are no more neighbouring, intact catchments to add, or
  2. The benchmarks area exceeds the user-specified Area Target.

If the latter occurs, and the area-weighted intactness of the benchmark exceeds the benchmark-level intactness threshold, then the benchmark is included in the output.

BUILDER R Functions

BEACONs BUILDER has 5 main functions:

seeds

The function seeds() creates a seeds table, which is an input to builder().
It identifies seed catchments and assigns them an area target.

reserve_seeds

The function reserve_seeds() creates a seeds table based on conservation areas, which is an input to builder().
It identifies seed catchments inside a conservation area and assigns them an area target.

neighbours

The function neighbours() creates a table listing pairwise catchment neighbours. Used as an input to builder().

builder

The function builder() prepares the input files and parameters and passes them to a command line version of BUILDER executable software. The function then fetches and returns the main BUILDER output table into the R environment.

fetch_builder_output

The function fetch_builder_output() loads pre-processed builder() output table into the R environment. It reads the appropriate table based on the specified type and makes it available for subsequent analyses (e.g., polygon creation).

🏗️ Process

  1. Prepares input tables: neighbours, either seeds or reserve_seeds, and catchments.
  2. Make sure default parameters are relevant and Set BUILDER parameters such as catchment_level_intactness, conservation_area_intactness.
  3. builder() returns the *_COLUMN_All_Unique_BAs.csv file listing conservation areas and their catchments by default.
  4. To access output tables containing upstream or downstream attributes, use the fetch_builder_output function.
  5. Subsequent processing, such as creating polygons of benchmarks using builder() output and assessing ecological attributes is done using others BEACONs functions (see examples in section Articles).

🔧 Key Parameters

Parameter Description
Area target Set in the seeds table; minimum size (m²) for each conservation area.
Catchment intactness Minimum intactness required for catchments to be included.
Conservation area intactness Minimum area-weighted intactness for a conservation area to be returned.
Area target proportion Allows output of smaller areas (e.g., 0.9 returns areas >= 90% of the area target).

💡 Tip

Use output_dir to preserve BUILDER’s complete outputs when running multiple builds. These files can be further analyzed using others BEACONs functions.



Citation

Houle M, Vernier P, Lisgo K, Edwards M, Schmiegelow F (2025). BEACONs R_Tools_Public: Building conservation areas in R. Available at https://beaconsproject.github.io/R_tools_public/.