Type:	Package
Version:	1.5.0
License:	GPL (≥ 3)
Title:	Structurally Guided Sampling
Description:	Structurally guided sampling (SGS) approaches for airborne laser scanning (ALS; LIDAR). Primary functions provide means to generate data-driven stratifications & methods for allocating samples. Intermediate functions for calculating and extracting important information about input covariates and samples are also included. Processing outcomes are intended to help forest and environmental management practitioners better optimize field sample placement as well as assess and augment existing sample networks in the context of data distributions and conditions. ALS data is the primary intended use case, however any rasterized remote sensing data can be used, enabling data-driven stratifications and sampling approaches.
URL:	https://github.com/tgoodbody/sgsR, https://tgoodbody.github.io/sgsR/
BugReports:	https://github.com/tgoodbody/sgsR/issues
Depends:	R (≥ 3.5.0), methods
Imports:	dplyr, ggplot2, sf, terra, tidyr, clhs, SamplingBigData, BalancedSampling, spatstat.geom
Suggests:	knitr, rmarkdown, Rfast, testthat (≥ 3.0.0), doParallel, doSNOW, snow, foreach, entropy, roxygen2, covr, RANN, spelling
VignetteBuilder:	knitr
Config/testthat/edition:	3
Config/testthat/parallel:	true
Encoding:	UTF-8
RoxygenNote:	7.3.2
Language:	en-US
NeedsCompilation:	no
Packaged:	2025-06-17 20:28:11 UTC; goodb
Author:	Tristan RH Goodbody [aut, cre, cph], Nicholas C Coops [aut], Martin Queinnec [aut]
Maintainer:	Tristan RH Goodbody <goodbody.t@gmail.com>
Repository:	CRAN
Date/Publication:	2025-06-18 00:30:07 UTC

sgsR: Structurally Guided Sampling

Description

Structurally guided sampling (SGS) approaches for airborne laser scanning (ALS; LIDAR). Primary functions provide means to generate data-driven stratifications & methods for allocating samples. Intermediate functions for calculating and extracting important information about input covariates and samples are also included. Processing outcomes are intended to help forest and environmental management practitioners better optimize field sample placement as well as assess and augment existing sample networks in the context of data distributions and conditions. ALS data is the primary intended use case, however any rasterized remote sensing data can be used, enabling data-driven stratifications and sampling approaches.

Author(s)

Maintainer: Tristan RH Goodbody goodbody.t@gmail.com (ORCID) [copyright holder]

Authors:

• Nicholas C Coops nicholas.coops@ubc.ca (ORCID)

• Martin Queinnec queinnec@mail.ubc.ca (ORCID)

See Also

Useful links:

• https://github.com/tgoodbody/sgsR

• https://tgoodbody.github.io/sgsR/

• Report bugs at https://github.com/tgoodbody/sgsR/issues

Allocating strata: 'existing'

Description

Allocation algorithms based on 'existing'

Allocation algorithms

Usage

allocate_existing_prop(existing, nSamp)

allocate_existing_optim(existing, metric, nSamp)

allocate_existing_manual(existing, nSamp, weights)

allocate_existing_equal(existing, nSamp)

allocate_prop(sraster, nSamp)

allocate_optim(sraster, mraster, nSamp)

allocate_manual(sraster, nSamp, weights)

allocate_equal(sraster, nSamp)

allocate_existing(toSample, existing)

allocate_force(toSample, nSamp, diff)

Arguments

Value

Data frame of allocated samples by stratum. Used internally within sample_existing(type = "strat").

Data frame of allocated samples by stratum. Used internally within sample_strat().

Sample allocation type and count

Description

Determine how many samples to allocate within strata.

Usage

calculate_allocation(
  sraster,
  nSamp,
  allocation = "prop",
  weights = NULL,
  mraster = NULL,
  existing = NULL,
  force = FALSE
)

Arguments

Value

Returns a data.frame of:

• strata - Strata ID.

• total - Number of samples to be allocated. Values correspond to under representation (samples needed; positive value) or over representation (too many samples; negative value) based on the nSamp provided.

• need - Required samples per strata based on allocation method. Rounded.

Author(s)

Tristan R.H. Goodbody

References

Gregoire, T.G., & Valentine, H.T. (2007). Sampling Strategies for Natural Resources and the Environment (1st ed.). Chapman and Hall/CRC. https://doi.org/10.1201/9780203498880

See Also

Other calculate functions: calculate_allocation_existing(), calculate_coobs(), calculate_distance(), calculate_pcomp(), calculate_pop(), calculate_representation(), calculate_sampsize()

Examples

## Not run: 
#--- Load strata raster and existing samples---#
r <- system.file("extdata", "sraster.tif", package = "sgsR")
sr <- terra::rast(r)

e <- system.file("extdata", "existing.shp", package = "sgsR")
e <- sf::st_read(e)

#--- proportional allocation ---#
calculate_allocation(
  sraster = sr,
  nSamp = 10,
  allocation = "prop"
)

## End(Not run)

Sample allocation type and count

Description

Determine how many samples to allocate within strata.

Usage

calculate_allocation_existing(
  existing,
  nSamp,
  allocation = "prop",
  weights = NULL,
  metric = NULL,
  force = FALSE
)

Arguments

Value

Returns a data.frame of:

• strata - Strata ID.

• total - Number of samples to be allocated. Values correspond to under representation (samples needed; positive value) or over representation (too many samples; negative value) based on the nSamp provided.

• need - Required samples per strata based on allocation method. Rounded.

Author(s)

Tristan R.H. Goodbody

References

Gregoire, T.G., & Valentine, H.T. (2007). Sampling Strategies for Natural Resources and the Environment (1st ed.). Chapman and Hall/CRC. https://doi.org/10.1201/9780203498880

See Also

Other calculate functions: calculate_allocation(), calculate_coobs(), calculate_distance(), calculate_pcomp(), calculate_pop(), calculate_representation(), calculate_sampsize()

coobs algorithm sampling

Description

Perform the COunt of OBServations (coobs) algorithm using existing site data and raster metrics. This algorithm aids the user in determining where additional samples could be located by comparing existing samples to each pixel and associated covariates. The output coobs raster could be used to constrain clhs sampling to areas that are underreprented.

Usage

calculate_coobs(
  mraster,
  existing,
  cores = 1,
  threshold = 0.95,
  plot = FALSE,
  filename = NULL,
  overwrite = FALSE
)

Arguments

Value

Output raster with coobs and classified coobs layers.

Note

Special thanks to Dr. Brendan Malone for the original implementation of this algorithm.

Author(s)

Tristan R.H. Goodbody

References

Malone BP, Minasny B, Brungard C. 2019. Some methods to improve the utility of conditioned Latin hypercube sampling. PeerJ 7:e6451 DOI 10.7717/peerj.6451

See Also

Other calculate functions: calculate_allocation(), calculate_allocation_existing(), calculate_distance(), calculate_pcomp(), calculate_pop(), calculate_representation(), calculate_sampsize()

Examples

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

e <- system.file("extdata", "existing.shp", package = "sgsR")
e <- sf::st_read(e)

calculate_coobs(
  mraster = mr,
  existing = e,
  cores = 4
)

## End(Not run)

Distance to access layer

Description

Per pixel distance to nearest access vector. Intended to be used as a 'cost' constraint within the sample_clhs function

Usage

calculate_distance(
  raster,
  access,
  slope = FALSE,
  plot = FALSE,
  filename = NULL,
  overwrite = FALSE
)

Arguments

Value

Input raster with dist2access layer appended.

Author(s)

Tristan R.H. Goodbody

See Also

Other calculate functions: calculate_allocation(), calculate_allocation_existing(), calculate_coobs(), calculate_pcomp(), calculate_pop(), calculate_representation(), calculate_sampsize()

Examples

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

a <- system.file("extdata", "access.shp", package = "sgsR")
ac <- sf::st_read(a)

calculate_distance(
  raster = mr,
  access = ac,
)

## End(Not run)

Analyze optimal Latin hypercube sample number

Description

Population level analysis of metric raster data to determine optimal Latin Hypercube sample size

Usage

calculate_lhsOpt(
  mats,
  PCA = TRUE,
  quant = TRUE,
  KLdiv = TRUE,
  minSamp = 10,
  maxSamp = 100,
  step = 10,
  rep = 10,
  iter = 10000
)

Arguments

Value

data.frame with summary statistics.

Note

Special thanks to Dr. Brendan Malone for the original implementation of this algorithm.

Author(s)

Tristan R.H. Goodbody

References

Malone BP, Minasny B, Brungard C. 2019. Some methods to improve the utility of conditioned Latin hypercube sampling. PeerJ 7:e6451 DOI 10.7717/peerj.6451

Examples

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

#--- calculate lhsPop details ---#
mats <- calculate_pop(mraster = mr)

calculate_lhsOpt(mats = mats)

calculate_lhsOpt(
  mats = mats,
  PCA = FALSE,
  iter = 200
)

## End(Not run)

Raster principal components

Description

Calculate and rasterize principal components from a metric raster

Usage

calculate_pcomp(
  mraster,
  nComp,
  center = TRUE,
  scale = TRUE,
  maxcells = Inf,
  plot = FALSE,
  details = FALSE,
  filename = NULL,
  overwrite = FALSE,
  ...
)

Arguments

Value

Output raster with specified number of principal components as layers.

Author(s)

Tristan R.H. Goodbody

See Also

Other calculate functions: calculate_allocation(), calculate_allocation_existing(), calculate_coobs(), calculate_distance(), calculate_pop(), calculate_representation(), calculate_sampsize()

Examples

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

calculate_pcomp(
  mraster = mr,
  nComp = 2
)

pcomp <- calculate_pcomp(
  mraster = mr,
  nComp = 3,
  details = TRUE
)

#--- Display principal component details ---#
# pcomp$pca

#--- Display importance of components ---#
# summary(pcomp$pca)

Population descriptors

Description

Population matrices and descriptions of metric raster data

Calculates population level statistics including principal components, quantile matrix, and covariance matrix needed necessary for calculate_lhsOpt. Outputs can also be used as an input for sample_ahels.

Usage

calculate_pop(mraster, PCA = FALSE, matQ = TRUE, nQuant = 10, matCov = TRUE)

Arguments

Value

List of matrices to be used as input for calculate_lhsOpt.

Note

Special thanks to Dr. Brendan Malone for the original implementation of this algorithm.

Author(s)

Tristan R.H. Goodbody

References

Malone BP, Minasny B, Brungard C. 2019. Some methods to improve the utility of conditioned Latin hypercube sampling. PeerJ 7:e6451 DOI 10.7717/peerj.6451

See Also

Other calculate functions: calculate_allocation(), calculate_allocation_existing(), calculate_coobs(), calculate_distance(), calculate_pcomp(), calculate_representation(), calculate_sampsize()

Examples

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

calculate_pop(mraster = mr)

Compare sample representation within sraster strata

Description

Compare sample representation within sraster strata

Usage

calculate_representation(sraster, existing, drop = NULL, plot = FALSE)

Arguments

Details

Calculate how sraster strata are represented in existing samples

Value

Returns a tibble where:

• strata - sraster strata ID.

• srasterFreq - sraster coverage frequency.

• sampleFreq - Sampling frequency within sraster strata.

• diffFreq - Difference between srasterFreq & sampleFreq. Positive values indicate over representation.

• nSamp - Number of samples within each strata in existing.

• need - srasterFreq * sum(nSamp). Total theoretical number of required samples to be representative of strata coverage. This values is rounded. It is important for the user to consider diffFreq. A small difference - e.g. 1 in sampleFreq vs. srasterFreq frequency could make the algorithm allocate or remove samples that could likely be ignored.

Author(s)

Tristan R.H. Goodbody, Martin Queinnec

See Also

Other calculate functions: calculate_allocation(), calculate_allocation_existing(), calculate_coobs(), calculate_distance(), calculate_pcomp(), calculate_pop(), calculate_sampsize()

Examples

### --- generate example stratification ---###

#--- load ALS metrics from sgsR internal data ---#
r <- system.file("extdata", "mraster.tif", package = "sgsR")

#--- read ALS metrics using the terra package ---#
mraster <- terra::rast(r)

#--- perform stratification ---#
sraster <- strat_kmeans(
  mraster = mraster$zq90,
  nStrata = 6
)

### --- create existing sample network ---###

#--- simple random sampling ---#
existing <- sample_srs(
  raster = mraster$zq90,
  nSamp = 100
)

#--- calculate representation ---#

calculate_representation(
  sraster = sraster,
  existing = existing
)

Sample size determination

Description

Determine a samples size for simple random sampling using relative standard error

Usage

calculate_sampsize(
  mraster,
  rse = NULL,
  start = 0.01,
  end = 0.05,
  increment = 0.001,
  plot = FALSE
)

Arguments

Value

A data.frame of sample size and rse by raster variable.

Note

rse = (100 * SE) / mean)

Where:

• SE - Standard error of the mean

• s - Standard deviation of the observations

• n - Number of observations

Author(s)

Tristan R.H. Goodbody

References

Benedetti, R., Piersimoni, F., & Postiglione, P. (2015). Sampling spatial units for agricultural surveys. pp 202-203. Berlin: Springer.

See Also

Other calculate functions: calculate_allocation(), calculate_allocation_existing(), calculate_coobs(), calculate_distance(), calculate_pcomp(), calculate_pop(), calculate_representation()

Examples

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

calculate_sampsize(
  mraster = mr,
  rse = 0.01
)

calculate_sampsize(
  mraster = mr
)

calculate_sampsize(
  mraster = mr,
  rse = 0.025,
  start = 0.01,
  end = 0.08,
  increment = 0.01
)

#--- higher variance leads to need for more samples ---#

Check existing sample data against requirements

Description

This function checks whether the existing sample data meets certain requirements for use in downstream analyses.

Usage

check_existing(existing, raster, nSamp, plot = FALSE, details = NULL)

Arguments

Value

If requirements are met, the function returns the prepared existing sample data. Otherwise, it raises a stop error with a relevant message.

Get existing and XY coordinates

Description

This function extracts the 'X' and 'Y' coordinates from an 'sf' object and returns them in a data.frame format.

Usage

coords_existing(existing)

Arguments

Value

existing with respective 'X' and 'Y' columns representing the coordinates of the input sf object.

Extract metrics

Description

Extract metric values to existing samples

Usage

extract_metrics(
  mraster,
  existing,
  quiet = FALSE,
  data.frame = FALSE,
  filename = NULL,
  overwrite = FALSE
)

Arguments

Value

An sf or data.frame object of samples with metrics attributes.

Note

If data.frame = TRUE output will be written using write.table

Author(s)

Tristan R.H. Goodbody

See Also

Other extract functions: extract_strata()

Examples

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

#' #--- load existing samples ---#
e <- system.file("extdata", "existing.shp", package = "sgsR")
e <- sf::st_read(e)

extract_metrics(
  mraster = mr,
  existing = e
)

Extract strata

Description

Extract stratum values to existing samples

Usage

extract_strata(
  sraster,
  existing,
  quiet = FALSE,
  data.frame = FALSE,
  filename = NULL,
  overwrite = FALSE
)

Arguments

Value

An sf or data.frame object of samples with strata attribute.

Note

If data.frame = TRUE output will be written using write.table

Author(s)

Tristan R.H. Goodbody

See Also

Other extract functions: extract_metrics()

Examples

#--- Load sraster ---#
r <- system.file("extdata", "sraster.tif", package = "sgsR")
sr <- terra::rast(r)

#--- load existing samples ---#
e <- system.file("extdata", "existing.shp", package = "sgsR")
e <- sf::st_read(e)

extract_strata(
  sraster = sr,
  existing = e
)

Masking

Description

Mask covariates and existing samples by access

Usage

mask_access(raster, access, buff_inner = NULL, buff_outer)

mask_existing(access, existing, buff_inner = NULL, buff_outer)

Arguments

Value

Raster/existing samples masked by provided access layer and buffers.

Matrices

Description

Create covariate and sample matrices

Usage

mat_quant(vals, nQuant, nb)

mat_cov(vals, nQuant, nb, matQ)

mat_covNB(vals, nQuant, nb, matQ)

Arguments

Value

Covariate quantile and/or covariance matrices.

Plot

Description

Plot

Class Plot

Scatter Plot

Usage

classPlot(dfc, coordsgrps, mraster, mraster2, samp = 0.01)

plot_scatter(mraster, existing, reverse = FALSE, samp = 0.01)

Arguments

Value

Scatter plot of available raster cells coloured and delineated by stratum.

Note

Population in viridis and samples in red.

Prepare existing sample data

Description

This function prepares the existing sample data by ensuring that it meets the necessary requirements for downstream analysis. If the 'existing' object is not of class 'sf', this function checks that the data contains columns named "X" and "Y", and converts lowercase "x" and "y" column names to uppercase if necessary. If the 'raster' object is supplied, this function checks if 'existing' contains attributes with the same names as 'raster'. If it does not, this function extracts metrics at existing sample locations using the 'raster' object. If 'access' is not null, the function masks the existing sample locations with a buffered access area.

Usage

prepare_existing(
  existing,
  raster = NULL,
  access = NULL,
  buff_inner = NULL,
  buff_outer = NULL
)

Arguments

Sampling rules

Description

Sampling rules

Stratified rule 1

Stratified rule 2

AHELS nSamp

AHELS threshold

Usage

strat_rule1(n, s, i, strat_mask, add_strata, extraCols, mindist)

strat_rule2(n, s, add_strata, nCount, strata_m, extraCols, mindist)

ahels_nSamp(
  nSamp,
  nQuant,
  tolerance,
  nb,
  underRep,
  ratio,
  ratOrderUnder,
  matCovDens,
  matCovSampDens,
  samples,
  mats,
  vals
)

ahels_threshold(
  threshold,
  tolerance,
  nQuant,
  nb,
  ratio,
  underRep,
  ratOrderUnder,
  matCovDens,
  matCovSampDens,
  samples,
  mats,
  vals
)

Arguments

Value

Allocated samples to be returned by sample_strat() & sample_ahels().

Adapted Hypercube Evaluation of a Legacy Sample (ahels)

Description

Perform the adapted Hypercube Evaluation of a Legacy Sample (ahels) algorithm using existing site data and raster metrics. New samples are allocated based on quantile ratios between the existing sample and covariate dataset.

Usage

sample_ahels(
  mraster,
  existing,
  nQuant = 10,
  nSamp = NULL,
  threshold = 0.9,
  tolerance = 0,
  matrices = NULL,
  plot = FALSE,
  details = FALSE,
  filename = NULL,
  overwrite = FALSE
)

Arguments

Value

Returns sf point object with existing samples and supplemental samples added by the ahels algorithm.

Note

Messages in the algorithm will state that samples have been added to under-represented quantiles. The number between square brackets that follow represent the matrix row and column respectively that can be printed using details = TRUE.

In some cases, generally when a single metric is used as mraster, sampling ratios all be >= 1 before the nSamp number of samples are allocated. The algorithm will stop in this scenario.

Special thanks to Dr. Brendan Malone for the original implementation of this algorithm.

Author(s)

Tristan R.H. Goodbody

References

Malone BP, Minasny B, Brungard C. 2019. Some methods to improve the utility of conditioned Latin hypercube sampling. PeerJ 7:e6451 DOI 10.7717/peerj.6451

See Also

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

Examples

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

e <- system.file("extdata", "existing.shp", package = "sgsR")
e <- sf::st_read(e)

sample_ahels(
  mraster = mr,
  existing = e,
  plot = TRUE
)

#--- supply quantile and covariance matrices ---#
mat <- calculate_pop(mraster = mr)

sample_ahels(
  mraster = mr,
  existing = e,
  matrices = mat,
  nSamp = 300
)

## End(Not run)

Balanced sampling

Description

Balanced raster sampling using lcube and lpm2_kdtree methods

Usage

sample_balanced(
  mraster,
  nSamp,
  algorithm = "lpm2_kdtree",
  p = NULL,
  access = NULL,
  buff_inner = NULL,
  buff_outer = NULL,
  plot = FALSE,
  filename = NULL,
  overwrite = FALSE
)

Arguments

Value

An sf object with nSamp samples.

Author(s)

Tristan R.H. Goodbody

References

Anton Grafström and Jonathan Lisic (2019). BalancedSampling: Balanced and Spatially Balanced Sampling. R package version 1.5.5. https://CRAN.R-project.org/package=BalancedSampling

Jonathan Lisic and Anton Grafström (2018). SamplingBigData: Sampling Methods for Big Data. R package version 1.0.0. https://CRAN.R-project.org/package=SamplingBigData

Grafström, A. Lisic, J (2018). BalancedSampling: Balanced and Spatially Balanced Sampling. R package version 1.5.4. http://www.antongrafstrom.se/balancedsampling

See Also

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

Examples

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

sample_balanced(
  mraster = mr,
  nSamp = 200
)

Conditioned Latin Hypercube Sampling

Description

Conditioned Latin Hypercube Sampling using clhs functionality.

Usage

sample_clhs(
  mraster,
  nSamp,
  iter = 10000,
  cost = NULL,
  existing = NULL,
  access = NULL,
  buff_inner = NULL,
  buff_outer = NULL,
  plot = FALSE,
  details = FALSE,
  filename = NULL,
  overwrite = FALSE,
  ...
)

Arguments

Value

An sf object with nSamp stratified samples.

Author(s)

Tristan R.H. Goodbody

References

Minasny, B. and McBratney, A.B. 2006. A conditioned Latin hypercube method for sampling in the presence of ancillary information. Computers and Geosciences, 32:1378-1388.

Minasny, B. and A. B. McBratney, A.B.. 2010. Conditioned Latin Hypercube Sampling for Calibrating Soil Sensor Data to Soil Properties. In: Proximal Soil Sensing, Progress in Soil Science, pages 111-119.

Roudier, P., Beaudette, D.E. and Hewitt, A.E. 2012. A conditioned Latin hypercube sampling algorithm incorporating operational constraints. In: Digital Soil Assessments and Beyond. Proceedings of the 5th Global Workshop on Digital Soil Mapping, Sydney, Australia.

See Also

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

Examples

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

e <- system.file("extdata", "existing.shp", package = "sgsR")
e <- sf::st_read(e)

a <- system.file("extdata", "access.shp", package = "sgsR")
ac <- sf::st_read(a)

sample_clhs(
  mraster = mr,
  nSamp = 200,
  plot = TRUE,
  iter = 100
)

sample_clhs(
  mraster = mr,
  nSamp = 400,
  existing = e,
  iter = 250,
  details = TRUE
)

Sample existing

Description

Sub-sample an existing sample. Four sampling methods are available: clhs, balanced, srs and strat.

Usage

sample_existing(
  existing,
  nSamp,
  raster = NULL,
  type = "clhs",
  access = NULL,
  buff_inner = NULL,
  buff_outer = NULL,
  details = FALSE,
  filename = NULL,
  overwrite = FALSE,
  ...
)

Arguments

Value

An sf object of samples or a list object if details = TRUE

Note

When type = "clhs" or type = "balanced" all attributes in existing will be used for sampling. Remove attributes not indented for sampling' prior to using this algorithm.

Author(s)

Tristan R.H. Goodbody

See Also

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

Examples

r <- system.file("extdata", "mraster.tif", package = "sgsR")
mr <- terra::rast(r)

#--- generate an existing sample adn extract metrics ---#
e <- sample_systematic(raster = mr, cellsize = 200)
e <- extract_metrics(existing = e, mraster = mr)

#--- perform clhs (default) sub-sampling ---#
sample_existing(
  existing = e,
  nSamp = 50
)

#--- perform balanced sub-sampling ---#
sample_existing(
  existing = e,
  nSamp = 50,
  type = "balanced"
)

#--- perform simple random sub-sampling ---#
sample_existing(
  existing = e,
  nSamp = 50,
  type = "srs"
)

Sample Existing Data Using Balanced Sampling

Description

This function samples a given set of existing data using balanced sampling techniques, which ensures that each stratum or subgroup of data is proportionally represented in the sample.

Usage

sample_existing_balanced(
  existing,
  nSamp,
  algorithm = "lpm2_kdtree",
  p = NULL,
  filename = NULL,
  overwrite = FALSE,
  ...
)

Arguments

Value

An sf object that is a sub-sample of existing

Sub-sample using the conditional Latin hypercube sampling (CLHS)

Description

This function takes an existing sf object and returns a random sub-sample of size nSamp.

Usage

sample_existing_clhs(
  existing,
  nSamp,
  raster = NULL,
  cost = NULL,
  iter = 10000,
  details = FALSE,
  filename = NULL,
  overwrite = FALSE,
  ...
)

Arguments

Value

A subsampled SpatialPointsDataFrame object.

Randomly sample from an existing dataset

Description

This function takes an existing sf object and returns a random sub-sample of size nSamp.

Usage

sample_existing_srs(existing, nSamp, filename = NULL, overwrite = FALSE)

Arguments

Value

A data frame or spatial data frame containing the random sample.

Sample Existing Data Based on Strata

Description

This function takes a data frame of existing data, a data frame of desired sample sizes for each strata, the number of samples to take, and optionally a file name and overwrite parameter. It returns a sample of the existing data based on the desired sample sizes for each strata, and optionally writes the resulting samples to a file.

Usage

sample_existing_strat(
  existing,
  toSample,
  nSamp,
  filename = NULL,
  overwrite = FALSE
)

Arguments

Value

An sf object that is a sub-sample of existing

Nearest centroid (NC) sampling

Description

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

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.

Author(s)

Tristan R.H. Goodbody

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()

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,
)

Simple random sampling

Description

Randomly sample within a stratification raster extent.

Usage

sample_srs(
  raster,
  nSamp,
  mindist = NULL,
  access = NULL,
  buff_inner = NULL,
  buff_outer = NULL,
  plot = FALSE,
  filename = NULL,
  overwrite = FALSE
)

Arguments

Value

An sf object with nSamp randomly sampled points.

Author(s)

Tristan R.H. Goodbody & Martin Queinnec

See Also

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

Examples

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

a <- system.file("extdata", "access.shp", package = "sgsR")
ac <- sf::st_read(a)

#--- perform simple random sampling ---#
sample_srs(
  raster = sr,
  nSamp = 200,
)

Stratified sampling

Description

Sampling based on a stratified raster.

Usage

sample_strat(
  sraster,
  nSamp,
  allocation = "prop",
  method = "Queinnec",
  weights = NULL,
  force = FALSE,
  mraster = NULL,
  mindist = NULL,
  existing = NULL,
  include = FALSE,
  remove = FALSE,
  access = NULL,
  buff_inner = NULL,
  buff_outer = NULL,
  wrow = 3,
  wcol = 3,
  plot = FALSE,
  details = FALSE,
  filename = NULL,
  overwrite = FALSE
)

Arguments

Value

An sf object with nSamp stratified samples.

Note

The sampling is performed in 2 stages when method = "Queinnec":

1. Rule 1 - Sample within grouped stratum pixels defined within the wrow, wcol parameters

2. Rule 2 - If no samples exist to satisfy Rule 1 individual stratum pixels are sampled.

   The rule applied to allocate each sample is defined in the rule attribute of output samples.

existing may contain samples that fall in sraster cells that are 'NA'. If this occurs and include = TRUE, 'NA' samples are separated during sampling and re-appended at the end of the sampling process.

If the sraster provided contains factor values, the algorithm will automatically convert these into the numeric factor levels and perform sampling using those values. The categories (factor values) will be extracted and appended to the algorithm output as the 'category' attribute.

Author(s)

Tristan R.H. Goodbody & Martin Queinnec

References

Queinnec, M., White, J. C., & Coops, N. C. (2021). Comparing airborne and spaceborne photon-counting LiDAR canopy structural estimates across different boreal forest types. Remote Sensing of Environment, 262 (August 2020), 112510. https://doi.org/10.1016/j.rse.2021.112510

See Also

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

Examples

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


#--- perform stratified sampling random sampling ---#
sraster <- sample_strat(
  sraster = sr,
  nSamp = 50
)

Systematic stratified sampling

Description

Systematic stratified sampling with random start point and translation within a square or hexagonal tessellation for each stratum.

Usage

sample_sys_strat(
  sraster,
  cellsize,
  square = TRUE,
  location = "centers",
  force = FALSE,
  access = NULL,
  buff_inner = NULL,
  buff_outer = NULL,
  plot = FALSE,
  filename = NULL,
  overwrite = FALSE,
  details = FALSE
)

Arguments

Value

An sf object with sampled points over unique tessellations.

Note

Specifying location = "random" can result in tessellations with no samples. This results from raster have NA values at the random location chosen. Using force = TRUE removes areas of NA from sampling entirely, but considerably slows processing speeds. Thanks to R. Hijmans for help in debugging and providing suggestions for this script.

All stratum are sampled using random tessellation start points and translations.

Author(s)

Tristan R.H. Goodbody

See Also

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

Examples

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

#--- perform grid sampling ---#
sample_sys_strat(
  sraster = sr,
  cellsize = 1000
)

sample_sys_strat(
  sraster = sr,
  cellsize = 1000,
  square = FALSE,
  location = "corners"
)

Systematic sampling

Description

Systematic sampling with random start point and translation within a square or hexagonal tessellation.

Usage

sample_systematic(
  raster,
  cellsize,
  square = TRUE,
  location = "centers",
  force = FALSE,
  access = NULL,
  buff_inner = NULL,
  buff_outer = NULL,
  plot = FALSE,
  filename = NULL,
  overwrite = FALSE,
  details = FALSE,
  ...
)

Arguments

Value

An sf object with sampled points over a tessellation.

Note

Specifying location = "random" can result in tessellations with no samples. This results from raster have NA values at the random location chosen. Using force = TRUE removes areas of NA from sampling entirely, but considerably slows processing speeds. Thanks to R. Hijmans for help in debugging and providing suggestions for this script.

Author(s)

Tristan R.H. Goodbody, Lukas Winiwarter

See Also

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

Examples

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

sample_systematic(
  raster = mr,
  cellsize = 1000,
  location = "corners",
  plot = TRUE
)

sample_systematic(
  raster = mr,
  cellsize = 1000,
  square = FALSE,
  location = "random",
  plot = TRUE
)

Breaks stratification

Description

Stratify metrics raster using user defined breaks

Usage

strat_breaks(
  mraster,
  breaks,
  map = FALSE,
  plot = FALSE,
  details = FALSE,
  filename = NULL,
  overwrite = FALSE
)

Arguments

Value

Returns an output stratification spatRaster or a list when details = TRUE.

When a list is returned:

1. raster is a stratified spatRaster based on quantiles. If stack = TRUE will be the number of layers of mraster plus the final output

2. breaks is a list output of breaks

3. plot is a ggplot histogram object showing distribution(s) and break point(s).

Author(s)

Tristan R.H. Goodbody

See Also

Other stratify functions: strat_kmeans(), strat_map(), strat_poly(), strat_quantiles()

Examples

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

#--- create vector breaks ---#
br.zq90 <- c(3, 5, 11, 18)
br.pz2 <- c(20, 40, 60, 80)

strat_breaks(
  mraster = mr$zq90,
  breaks = br.zq90
)


strat_breaks(
  mraster = mr[[1:2]],
  breaks = list(br.zq90, br.pz2),
  details = TRUE
)

k-means stratification

Description

Stratify metrics raster using kmeans algorithm

Usage

strat_kmeans(
  mraster,
  nStrata,
  iter = 500,
  algorithm = "Lloyd",
  center = TRUE,
  scale = TRUE,
  plot = FALSE,
  details = FALSE,
  filename = NULL,
  overwrite = FALSE,
  ...
)

Arguments

Value

output stratification spatRaster, or a list when details = TRUE.

Author(s)

Tristan R.H. Goodbody

See Also

Other stratify functions: strat_breaks(), strat_map(), strat_poly(), strat_quantiles()

Examples

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

#--- perform stratification using k-means ---#
kmeans <- strat_kmeans(
  mraster = mr,
  nStrata = 5
)

kmeans <- strat_kmeans(
  mraster = mr,
  nStrata = 5,
  iter = 1000,
  algorithm = "MacQueen",
  details = TRUE
)

Map a raster stack of a list of rasters

Description

Map stratified rasters to a combined stratification.

Usage

strat_map(
  sraster,
  stack = FALSE,
  filename = NULL,
  overwrite = FALSE,
  plot = FALSE,
  details = FALSE
)

Arguments

Value

A spatRaster object.

Mapping

The mapping algorithm will take the stratification from sraster and combine it with overlying strata values across all layers. This will result in a strata attribute where the values from all inputs are combined.

i.e.

If strata_1 = 1 and strata_2 = 1 then strata = 11.

If strata_1 = 2 and strata_2 = 14 then strata = 214.

If strata_1 = "A" and strata_2 = 14 then strata = "A14".

Author(s)

Tristan R.H. Goodbody, Tommaso Trotto, Robert Hijmans

See Also

Other stratify functions: strat_breaks(), strat_kmeans(), strat_poly(), strat_quantiles()

Examples

#--- load input metrics rasters ---#
raster <- system.file("extdata", "sraster.tif", package = "sgsR")
sraster <- terra::rast(raster)

#--- read polygon coverage ---#
poly <- system.file("extdata", "inventory_polygons.shp", package = "sgsR")
fri <- sf::st_read(poly)

#--- stratify polygon coverage ---#
#--- specify polygon attribute to stratify ---#

attribute <- "NUTRIENTS"

#--- specify features within attribute & how they should be grouped ---#
#--- as a single vector ---#

features <- c("poor", "rich", "medium")

srasterfri <- strat_poly(
  poly = fri,
  attribute = attribute,
  features = features,
  raster = sraster
)

#--- map srasters with raster stack ---#
stack <- c(srasterfri, sraster)
strat_map(
  sraster = stack
)

#--- map sraster with list of rasters ---#
rast_list <- list(srasterfri, sraster)
strat_map(
  sraster = rast_list,
  stack = TRUE,
  details = TRUE
)

Stratify using polygons

Description

Stratify based on polygon coverage attributes and features.

Usage

strat_poly(
  poly,
  attribute,
  features,
  raster,
  filename = NULL,
  overwrite = FALSE,
  plot = FALSE,
  details = FALSE
)

Arguments

Value

A spatRaster object.

Author(s)

Tristan R.H. Goodbody

See Also

Other stratify functions: strat_breaks(), strat_kmeans(), strat_map(), strat_quantiles()

Examples

#--- load input metrics raster ---#
raster <- system.file("extdata", "sraster.tif", package = "sgsR")
sraster <- terra::rast(raster)

#--- read polygon coverage ---#
poly <- system.file("extdata", "inventory_polygons.shp", package = "sgsR")
fri <- sf::st_read(poly)

#--- stratify polygon coverage ---#
#--- specify polygon attribute to stratify ---#

attribute <- "NUTRIENTS"

#--- specify features within attribute & how they should be grouped ---#
#--- as a single vector ---#

features <- c("poor", "rich", "medium")

srasterpoly <- strat_poly(
  poly = fri,
  attribute = attribute,
  features = features,
  raster = sraster
)

#--- or as multiple lists ---#

g1 <- "poor"
g2 <- c("rich", "medium")

features <- list(g1, g2)

srasterpoly <- strat_poly(
  poly = fri,
  attribute = attribute,
  features = features,
  raster = sraster,
  details = TRUE
)

Quantiles stratification

Description

Stratify metric raster using metric quantiles.

Usage

strat_quantiles(
  mraster,
  nStrata,
  map = FALSE,
  plot = FALSE,
  details = FALSE,
  filename = NULL,
  overwrite = FALSE
)

Arguments

Value

Returns an output stratification spatRaster or a list when details = TRUE.

When a list is returned:

1. details lookUp table for stratification(s).

2. raster is a stratified spatRaster based on quantiles

3. plot is a ggplot histogram / scatter plot object (depends on whether metric2 was supplied). Histogram shows distribution and break points.

Author(s)

Tristan R.H. Goodbody

See Also

Other stratify functions: strat_breaks(), strat_kmeans(), strat_map(), strat_poly()

Examples

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

strat_quantiles(
  mraster = mr$zq90,
  nStrata = 4
)

strat_quantiles(
  mraster = mr[[1:2]],
  nStrata = list(c(0.2, 0.4, 0.8), 3),
  map = TRUE
)

Take Samples Based on Strata

Description

This function takes a data frame of existing data, a data frame of desired sample sizes for each strata, and a strata variable name, and returns a sample of the existing data based on the sample sizes for the specified strata.

Usage

take_samples(existing, toSample, strata)

Arguments

Value

A data frame containing a sample of the existing data based on the sample sizes for the specified strata.

Vectorization helpers

Description

Vectorization helpers

Breaks vectorize

Quantile breaks

Quantile vectorize by integer helper

Quantile vectorize by probabilities vector helper

Usage

calculate_breaks(mraster, breaks)

calculate_quantile_breaks(mraster, nStrata)

quantile_breaks_integer(mraster, nStrata)

quantile_breaks(mraster, nStrata)

Arguments

Write

Description

Write

Write samples

Write table

Write raster

Usage

write_samples(samples, filename = NULL, overwrite = FALSE)

write_samples_df(samples, filename = NULL, overwrite = FALSE)

write_raster(raster, filename = NULL, overwrite = FALSE)

Arguments

Value

No explicit output but files are written to disc if specified.