nh_sample: Create points in features in reference raster cells

In VANatHeritage/nhSDM: Tools for Natural Heritage SDMs

Create points in features in reference raster cells

Description

For each spatial feature, a given number (num_samps) of points are created in cells that the feature intersects.

Usage

nh_sample(spf, rast, num.samps = NULL, replace = FALSE, force.min = FALSE)

Arguments

spf	input spatial features (sp or sf spatial object)
rast	raster dataset with extent overlapping spf
num.samps	number of samples to create in each feature (see details)
replace	whether to sample with or without replacement
force.min	whether to force num.samps points in features, even if they are duplicates

Details

num.samps can be a a proportion (a decimal value < 1), single integer, or vector of integers equal to length of spf indicated the number of samples to take from each feature. If left NULL, num.samps will be set to the number of cells [n] intersecting the feature. If a proportion is given (e.g., 0.5), than [n * num.samps] will be returned. If a single integer is given, num.samps points will be sampled in each feature.

When replace = FALSE and force.min = FALSE (defaults), each cell can only contain one point (across each feature, and the entire returned set of points). In this case, when the number of samples points to create exceeds the number of unique cells intersected by a given feature, the number of samples for that feature equals the number of cells. If replace = TRUE, sampling is done with replacement and duplicates may be taken. The special case replace = FALSE and force.min = TRUE will always return num.samps per feature. It only produces duplicates if num.samps exceeds the number of cells intersecting the feature, in which case it will replicate the samples until num.samps is reached.

If CRS do not match, the features will be transformed to the CRS of the raster.

A column 'feat.id' is added to the output point features to indicate the row number of the feature that the point was generated within.

Value

sp or sf object (points)

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")
spf$num.samps <- sample(1:5, nrow(spf), replace = T)
spf.samps <- nh_sample(spf, rast, num.samps =spf$num.samps, replace = F, force.min = T)
nrow(spf.samps) == sum(spf$num.samps)  # Should be TRUE when force.min = T.

## End(Not run)

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