nh_best: Extract highest-value areas as polygons from an SDM...

In VANatHeritage/nhSDM: Tools for Natural Heritage SDMs

Extract highest-value areas as polygons from an SDM prediction raster, with optional feature mask

Description

If spf is given, areas intersecting these features (plus a buffer, if min.dist is specified) will not be included in the returned polygons.

Usage

nh_best(
  rast,
  spf = NULL,
  top.percent = NULL,
  min.size = NULL,
  min.dist = NULL,
  num.patches = NULL,
  rank.by = "area"
)

Arguments

rast	input raster model output with continuous values
spf	input spatial features (sp or sf spatial object); if given, it can be used to modify areas selected from rast
top.percent	numeric; percent (e.g.; 0.01 = 0.01%) of highest cell values in raster to extract
min.size	numeric; optional minimal area of an extracted polygon
min.dist	numeric; optional minimal distance from spf for patches. Default is 0 (can be adjacent to 'spf')
num.patches	numeric; optional number of patches to return, using rank.by criteria
rank.by	character; used for ranking patches when num.patches is not null; either 'area' (default) or 'value'

Details

top.percent and min.size will both be derived from spf if they are null and spf is given. In this case, top.percent will be set to be equal to spf's cell coverage (prevalence relative to non-NA areas in raster). min.size will be set to the area of the smallest feature in spf. If spf are line or point features, this will be zero.

rank.by only subsets the outputs if num.patches is set. rank.by must be set to "value" to return the mean prediction value of the patch.

For better performance, crop the raster prior to running, and/or use a very low top.percent value, to return a smaller proportion of the cells as polygons.

Value

sp or sf object (polygons)

Author(s)

David Bucklin

Examples

## Not run: 
spf <- sf::st_read("_data/occurrence/ambymabe.shp")
rast <- terra::rast("_data/species/ambymabe/outputs/model_predictions/ambymabe_20171018_130837.tif")
rast <- terra::crop(rast, spf)
best_polys <- nh_best(rast, spf, top.percent = 0.01, min.size = 10000, min.dist <- 10000, 
   num.patches = 100, rank.by = "value")

## End(Not run)

VANatHeritage/nhSDM documentation built on Feb. 1, 2024, 6:39 a.m.