Skip to contents

Nearest centroid (NC) sampling

Source: R/sample_nc.R
sample_nc.Rd

Sampling using the nearest centroid (NC) approach described in Melville & Stone (2016).

Usage

sample_nc(
  mraster,
  nSamp,
  k = 1,
  iter = 500,
  algorithm = "Lloyd",
  access = NULL,
  buff_inner = NULL,
  buff_outer = NULL,
  plot = FALSE,
  details = FALSE,
  filename = NULL,
  overwrite = FALSE
)

Arguments

mraster

spatRaster. ALS metrics raster.

nSamp

Numeric. Number of desired samples.

k

Numeric. The number of nearest neighbours to take for each k-means center. When k = 1 (default), the output number of samples will match nSamp. Increases to k results in a multiplicative result total number of samples nSamp * k.

iter

Numeric. The maximum number of kmeans iterations allowed.

algorithm

Character. Lloyd (default) or MacQueen kmeans algorithms.

access

sf 'LINESTRING' or 'MULTILINESTRING'. Access network.

buff_inner

Numeric. Inner buffer boundary specifying distance from access where plots cannot be sampled.

buff_outer

Numeric. Outer buffer boundary specifying distance from access where plots can be sampled.

plot

Logical. Plot mraster with allocated samples.

details

Logical. If FALSE (default) output is only stratification raster. If TRUE return a list where $details is additional stratification information and $raster is the output stratification spatRaster.

filename

Character. Path to write output samples.

overwrite

Logical. Choice to overwrite existing filename if it exists.

Value

An sf object with nSamp randomly sampled points.

Note

When details = TRUE, a list is returned where:

  1. samples output nearest centroid samples with kcenter attribute linking to associated kmeans centers.

  2. kmeans is a list output of the kmeans function

  3. centers Un-scaled kmeans center values for each layer in mraster with kcenter attribute to link with the same attribute in samples.

  4. kplot is a ggplot scatterplot object visualizing the kmeans centers and associated nearest neighbor samples.

References

G. Melville & C. Stone (2016) Optimising nearest neighbour information—a simple, efficient sampling strategy for forestry plot imputation using remotely sensed data, Australian Forestry, 79:3, 217-228, DOI: 10.1080/00049158.2016.1218265

See also

Other sample functions: sample_ahels(), sample_balanced(), sample_clhs(), sample_existing(), sample_srs(), sample_strat(), sample_sys_strat(), sample_systematic()

Author

Tristan R.H. Goodbody

Examples

#--- Load raster and access files ---#
r <- system.file("extdata", "mraster.tif", package = "sgsR")
mr <- terra::rast(r)

#--- perform simple random sampling ---#
sample_nc(
  mraster = mr,
  nSamp = 5,
)
#> K-means being performed on 3 layers with 5 centers.
#> Simple feature collection with 5 features and 4 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: 431970 ymin: 5341550 xmax: 438150 ymax: 5343130
#> Projected CRS: UTM Zone 17, Northern Hemisphere
#>        zq90 pzabove2  zsd kcenter               geometry
#> 29612 21.10     85.2 5.93       1 POINT (433990 5341650)
#> 2718  12.60     39.8 3.46       2 POINT (433230 5343090)
#> 8052   4.93     21.1 1.15       3 POINT (435470 5342810)
#> 31376 10.90     80.2 2.60       4 POINT (431970 5341550)
#> 2218  16.80     86.7 3.93       5 POINT (438150 5343130)