get_cover_quantiles: Calculate quantiles of stratum vegetation cover based on...
In mbedward/CERMBlidar: A collection of functions to process aerial LIDAR data

get_cover_quantiles

R Documentation

Calculate quantiles of stratum vegetation cover based on LiDAR point counts

Description

This function takes a multi-band raster of LiDAR point counts for ground level and vegetation strata, arranged in increasing height order (i.e. ground is band 1), and returns a raster of vegetation cover estimates for strata. Estimates are based on a Bayesian approach, where the detection of stratum vegetation is viewed as a binomial sampling process. LiDAR points (i.e. discrete returns) from a stratum are treated as 'successes' while points from ground level and any lower strata are 'failures'. Under this model, the binomial probability of success is an estimator of vegetation cover, while the degree of certainty about the estimate will depend on the LiDAR point density. Selected quantiles for estimated cover are returned as raster bands for each stratum. The default is to calculate median cover and the central 90% bounds (5%, 50% and 95% quantiles) for each stratum. Optionally, the maximum likelihood estimate of mean cover can also be returned.

Usage

get_cover_quantiles(
  rcounts,
  probs = c(0.05, 0.5, 0.95),
  mle = FALSE,
  backgroundNA = TRUE,
  beta_prior = c(1, 1)
)

Arguments

`rcounts`	A raster object with a band of point count data for each vegetation stratum plus a band for the ground layer. Normally, this will be a `terra` package `SpatRaster` object generated by function `get_stratum_counts()`, but it may also be a `RasterStack` or `RasterBrick` (`raster` package) object. Important: the bands must be arranged in increasing height order, i.e. ground layer, then understorey layer(s), then overstorey layer(s).
`probs`	A numeric vector of one or more probability values specifying the quantiles of vegetation cover. The default `c(0.05, 0.5, 0.95)` returns quantiles for the median and the central 90% interval. To suppress quantile calculations and only return the maximum likelihood estimate of mean cover, set this argument to `NULL, NA` or an empty vector, and set argument `mle=TRUE`.
`mle`	A logical value specifying whether the maximum likelihood estimate (MLE) of mean cover should be returned in addition to any specified cover quantiles. The MLE is the same value as that returned by the deprecated function `get_stratum_cover`. Set to `FALSE` (default) if the MLE is not required; or to `TRUE` to return the MLE in addition to any quantiles specified via the `probs` argument. See Details for information.
`backgroundNA`	Controls what pixel value should be returned for a stratum when there are no LiDAR points for the stratum, any lower strata or ground. If set to `TRUE` (the default), such cases will have missing (`NA`) pixel values for all quantile layers for the stratum. If `FALSE`, pixel values will be calculated as quantiles of the prior beta distribution. Note that if maximum likelihood mean cover estimates are specified (via `mle=TRUE`) these will always be `NA` for any pixels without LiDAR data.
`beta_prior`	(Expert use only!) Either a numeric vector of two values defining the prior beta distribution to use for all strata, or a named list of two-element vectors where names match raster layer names for vegetation strata (case-insensitive). The default is `c(1,1)` for a `beta(1,1)` distribution which is equivalent to a uniform distribution on the (0,1) interval for all strata. This is probably what you want unless (a) you really know what you are doing and (b) there are particular reasons, i.e. previous studies or expert knowledge, to expect cover values for one or more strata to follow alternative distributions. For the list option, the default `c(1,1)` prior parameters will be used any strata not matched to list element names. The function `beta_prior_helper` can be used to explore candidate distributions given an expected cover value. See the examples and the Details section for further explanation.

Details

If we view the detection of vegetation within a stratum via discrete LiDAR returns as a binomial sampling process, then we can make use of the relationship between the binomial and beta distributions. For a given pixel, if we have n returns from vegetation within a stratum out of a total of N returns from that stratum or lower (including ground level), then the distribution of the possible vegetation cover values for the stratum that could result in the observed points counts will follow a beta distribution. For the baseline no-data case (ie. no LiDAR returns from the stratum or below, perhaps because higher strata blocked all LiDAR pulses), it is reasonable to depict the possible cover distribution as uniform between 0 and 1, i.e. with no data we have no reason to prefer any cover value over any other. This baseline can be represented as a beta(1, 1) distribution which, for quantile calculations, we refer to as the Bayesian prior distribution of cover values. Most of the time this is probably what you want to use. We use the LiDAR data within a pixel to update our expectation of stratum cover from the flat prior beta(1, 1) distribution to a beta(1+n, 1+n-N) distribution. We can then summarize this distribution via selected quantiles which can be output as raster layers.

Sometimes, it might be preferable to adopt something other than a uniform prior expectation for vegetation cover. For example, from previous studies and/or expert knowledge we might expect that tree canopy cover will typically be around 30%, relative to the pixel size being used for mapping, with a certain degree of variation around this value. In this case, a beta distribution can be chosen to represent this expectation (e.g. beta(2,5)) and specified for the stratum using the beta_prior argument. See examples below.

In addition to quantiles of stratum vegetation cover, this function can be used to calculate the simpler maximum likelihood estimate of mean cover (MLE), equivalent to the value returned by the deprecated function get_stratum_cover. The MLE is the ratio of the number of LiDAR points returned from within the stratum height range to the total number of points returned between ground level and the top of the stratum. This value corresponds to the mode of the beta distribution used to calculate quantiles, assuming that the default beta(1,1) prior distribution has been specified.

Value

A SpatRast (terra package) raster object with a layer for each requested quantile within each stratum. For example, calculating the default median plus 90% bounds (0.05 and 0.95 quantiles) for 5 vegetation strata would return a raster object with 15 layers. Layers are arranged by stratum, then by quantile. Layer names have the form stratum_q_prob, e.g. 'TallShrub_q_0.5' for the median (50%) quantile. If the maximum likelihood cover estimate has been requested (mle=TRUE), this will appear before any quantile layers for each stratum with a name of the form stratum_mle.

Examples

## Not run: 
# Estimate quantiles of vegetation cover for each stratum corresponding to
# 50\
#
probs <- c(0.05, 0.25, 0.5, 0.75, 0.95)
rcover <- get_cover_quantiles(rcounts, probs)

# Alternatively, calculate the maximum likelihood cover estimate for each
# stratum. Note that this is insensitive to LiDAR point density, i.e. it provides
# no indication of the uncertainty associated with the estimates.
#
rcover_mle <- get_cover_quantiles(rcounts, probs = NULL, mle = TRUE)

# An example of setting 'informed' beta priors for two strata:
# 'LowShrub' and 'MediumTree', corresponding to an expectation of 25\
# for shrubs and 40\
# strata names. The default \code{beta(1,1)} prior will be used for other strata.
#
beta_prior <- list(lowshrub=c(2,4), mediumtree=c(2,2.5))

## End(Not run)

mbedward/CERMBlidar documentation built on April 10, 2024, 2:05 p.m.