R: Predefined standard metrics functions

stdmetrics {lidR} | R Documentation

## Predefined standard metrics functions

### Description

Predefined metrics functions intended to me used in `*_metrics` function such as grid_metrics, hexbin_metrics, cloud_metrics, tree_metrics, voxel_metrics or point_metrics. Each function comes with a convenient shortcuts for lazy coding. The `lidR` package aims to provide an easy way to compute user-defined metrics rather than to provide them. However, for efficiency and to save time, sets of standard metrics have been predefined (see details). Every function can be computed by every `*_metrics` functions however `stdmetrics*` are more pixel-based metrics, `stdtreemetrics` are more tree-based metrics and `stdshapemetrics` are more point-based metrics. For example the metric zmean computed by `stdmetrics_z` makes sense when computed at the pixel level but brings no information at the voxel level.

### Usage

    stdmetrics(x, y, z, i, rn, class, dz = 1, th = 2, zmin = 0)

    stdmetrics_z(z, dz = 1, th = 2, zmin = 0)

    stdmetrics_i(i, z = NULL, class = NULL, rn = NULL)

    stdmetrics_rn(rn, class = NULL)

    stdmetrics_pulse(pulseID, rn)

    stdmetrics_ctrl(x, y, z)

    stdtreemetrics(x, y, z)

    stdshapemetrics(x, y, z)

    .stdmetrics

    .stdmetrics_z

    .stdmetrics_i

    .stdmetrics_rn

    .stdmetrics_pulse

    .stdmetrics_ctrl

    .stdtreemetrics

    .stdshapemetrics

### Arguments

`x, y, z, i` | Coordinates of the points, Intensity
`rn, class` | ReturnNumber, Classification
`dz` | numeric. Layer thickness metric entropy
`th` | numeric. Threshold for metrics pzabovex. Can be a vector to compute with several thresholds.
`zmin` | numeric. Lower bound of the integral for zpcumx metrics. See wiki page and Wood et al. (2008) reference.
`pulseID` | The number referencing each pulse

### Format

An object of class `formula` of length 2.

An object of class `formula` of length 2.

An object of class `formula` of length 2.

An object of class `formula` of length 2.

An object of class `formula` of length 2.

An object of class `formula` of length 2.

An object of class `formula` of length 2.

An object of class `formula` of length 2.

### Details

The function names, their parameters and the output names of the metrics rely on a nomenclature chosen for brevity:

- `z`: refers to the elevation

- `i`: refers to the intensity

- `rn`: refers to the return number

- `q`: refers to quantile

- `a`: refers to the ScanAngleRank or ScanAngle

- `n`: refers to a number (a count)

- `p`: refers to a percentage

For example the metric named `zq60` refers to the elevation, quantile, 60 i.e. the 60th percentile of elevations. The metric `pground` refers to a percentage. It is the percentage of points classified as ground. The function `stdmetric_i` refers to metrics of intensity. A description of each existing metric can be found on the lidR wiki page.
Some functions have optional parameters. If these parameters are not provided the function computes only a subset of existing metrics. For example, `stdmetrics_i` requires the intensity values, but if the elevation values are also provided it can compute additional metrics such as cumulative intensity at a given percentile of height.
Each function has a convenient associated variable. It is the name of the function, with a dot before the name. This enables the function to be used without writing parameters. The cost of such a feature is inflexibility. It corresponds to a predefined behaviour (see examples)

`stdmetrics`

  is a combination of `stdmetrics_ctrl` + `stdmetrics_z` + `stdmetrics_i` + `stdmetrics_rn`

`stdtreemetrics`

  is a special function that works with tree_metrics. Actually, it won't fail with other functions but the output makes more sense if computed at the individual tree level.

`stdshapemetrics`

  is a set of eigenvalue based feature described in Lucas et al, 2019 (see references).

### References

M. Woods, K. Lim, and P. Treitz. Predicting forest stand variables from LiDAR data in the Great Lakes – St. Lawrence forest of Ontario. The Forestry Chronicle. 84(6): 827-839. https://doi.org/10.5558/tfc84827-6

Lucas, C., Bouten, W., Koma, Z., Kissling, W. D., & Seijmonsbergen, A. C. (2019). Identification of Linear Vegetation Elements in a Rural Landscape Using LiDAR Point Clouds. Remote Sensing, 11(3), 292.

### See Also

cloud_metrics grid_metrics hexbin_metrics voxel_metrics tree_metrics point_metrics

### Examples

    LASfile <- system.file("extdata", "Megaplot.laz", package="lidR")
    las <- readLAS(LASfile, select = "*", filter = "-keep_random_fraction 0.5")

    # All the predefined metrics
    m1 <- grid_metrics(las, ~stdmetrics(X,Y,Z,Intensity,ReturnNumber,Classification,dz=1), res = 40)

    # Convenient shortcut
    m2 <- grid_metrics(las, .stdmetrics, res = 40)

    # Basic metrics from intensities
    m3 <- grid_metrics(las, ~stdmetrics_i(Intensity), res = 40)

    # All the metrics from intensities
    m4 <- grid_metrics(las, ~stdmetrics_i(Intensity, Z, Classification, ReturnNumber), res = 40)

    # Convenient shortcut for the previous example
    m5 <- grid_metrics(las, .stdmetrics_i, res = 40)

    # Combine some predefined function with your own new metrics
    # Here convenient shortcuts are no longer usable.
    myMetrics = function(z, i, rn)
    {
      first  <- rn == 1L
      zfirst <- z[first]
      nfirst <- length(zfirst)
      above2 <- sum(z > 2)

      x <- above2/nfirst*100

      # User's metrics
      metrics <- list(
         above2aboven1st = x,       # Num of returns above 2 divided by num of 1st returns
         zimean  = mean(z*i),       # Mean products of z by intensity
         zsqmean = sqrt(mean(z^2))  # Quadratic mean of z
       )

      # Combined with standard metrics
      return( c(metrics, stdmetrics_z(z)) )
    }

    m10 <- grid_metrics(las, ~myMetrics(Z, Intensity, ReturnNumber), res = 40)

    # Users can write their own convenient shorcuts like this:
    .myMetrics = ~myMetrics(Z, Intensity, ReturnNumber)
    m11 <- grid_metrics(las, .myMetrics, res = 40)

[Package lidR version 3.2.2 Index]