Generate Protect Zone Raster for ELSA Analysis — make_protect

This function creates a SpatRaster layer representing planning units eligible for protect actions in the ELSA framework. Areas with high human footprint, agriculture, or built-up land cover are excluded. Optionally, the result can be inverted to serve as a locked-out constraint for spatial prioritization tools such as prioritizr.

Usage

make_protect_zone(
  iso3,
  pus,
  current_protected_areas,
  lulc_proportions = NULL,
  agricultural_areas_input = NULL,
  built_areas_input = NULL,
  lulc_raster = NULL,
  hii_input = NULL,
  hii_threshold = NULL,
  hii_quantile = 0.95,
  lulc_product = c("esri_10m", "dynamic_world", "esa_worldcover", "local"),
  agriculture_lulc_value = NULL,
  built_area_lulc_value = NULL,
  agriculture_threshold = 0.1,
  built_areas_threshold = 0.1,
  filter_patch_size = TRUE,
  min_patch_size = 20,
  make_locked_out = FALSE,
  output_path = NULL
)

Arguments

iso3: ISO3 country code (e.g., "NPL").
pus: A SpatRaster defining the planning units.
current_protected_areas: a sf or SpatVector object of current protected areas. If NULL, elsar::make_protected_areas() will be used.
lulc_proportions: A multi-band SpatRaster from download_lulc_proportions() containing pre-computed class proportions. If provided, bands named "agriculture" and "built_area" will be used automatically, overriding agricultural_areas_input and built_areas_input.
agricultural_areas_input: A SpatRaster representing binary or probabilistic agricultural areas (optional).
built_areas_input: A SpatRaster representing binary or probabilistic built-up areas (optional).
lulc_raster: A SpatRaster LULC map used to extract agriculture/built-up areas if not already provided (default: NULL).
hii_input: A SpatRaster of the Human Footprint Index, or NULL. If NULL, the protect zone starts with all planning units eligible and applies only agriculture and built-area exclusions.
hii_threshold: A fixed numeric HII threshold. If NULL, hii_quantile is used to estimate it.
hii_quantile: A quantile threshold (e.g., 0.95) used to calculate the HII threshold within protected areas if hii_threshold is NULL.
lulc_product: Character. LULC product used for class value lookups: "esri_10m" (default), "dynamic_world", "esa_worldcover", or "local". When "local", explicit class values must be provided.
agriculture_lulc_value: Integer or NULL. LULC value representing agriculture. If NULL, automatically determined from lulc_product. Default is NULL.
built_area_lulc_value: Integer or NULL. LULC value representing built-up areas. If NULL, automatically determined from lulc_product. Default is NULL.
agriculture_threshold: Minimum fraction for agriculture to exclude a cell (default: 0.1).
built_areas_threshold: Minimum fraction for built-up area to exclude a cell (default: 0.1).
filter_patch_size: Logical. Whether to remove small isolated patches (default: TRUE).
min_patch_size: Integer. Minimum patch size to retain (in raster cells; default: 20).
make_locked_out: Logical. If TRUE, invert the raster to produce a locked-out constraint (default: FALSE).
output_path: Optional directory to write the result as a COG.

Value

A SpatRaster with values 1 (eligible) and 0 (excluded), or the inverse if make_locked_out = TRUE.

Details

The Human Footprint Index (HII) threshold can be defined either as a fixed value (hii_threshold) or estimated from the upper 95% quantile (hii_quantile) of values within protected areas.

Examples

if (FALSE) { # \dontrun{
protect_zone <- make_protect_zone(
  pus = planning_units,
  iso3 = "NPL",
  hii_input = hii_raster,
  agricultural_areas_input = crop_raster,
  built_areas_input = built_raster,
  lulc_raster = NULL,
  hii_quantile = 0.95,
  output_path = "outputs/"
)
} # }