Skip to contents

sample_lsm

Source: R/sample_lsm.R
sample_lsm.Rd

Sample metrics

Usage

sample_lsm(
  landscape,
  y,
  plot_id = NULL,
  shape = "square",
  size = NULL,
  all_classes = FALSE,
  return_raster = FALSE,
  verbose = TRUE,
  progress = FALSE,
  ...
)

Arguments

landscape

A categorical raster object: SpatRaster; Raster* Layer, Stack, Brick; stars or a list of SpatRasters.

y

2-column matrix with coordinates, sf point geometries, or sf polygon geometries.

plot_id

Vector with id of sample points. If not provided, sample points will be labelled 1...n.

shape

String specifying plot shape. Either "circle" or "square"

size

Approximated size of sample plot. Equals the radius for circles or half of the side-length for squares in map units. For lines size equals the width of the buffer.

all_classes

Logical if NA should be returned for classes not present in some sample plots.

return_raster

Logical if the clipped raster of the sample plot should be returned

verbose

Print warning messages.

progress

Print progress report.

...

Arguments passed on to calculate_lsm().

Value

tibble

Details

This function samples the selected metrics in a buffer area (sample plot) around sample points, sample lines or within provided polygons. The size of the actual sampled landscape can be different to the provided size due to two reasons. Firstly, because clipping raster cells using a circle or a sample plot not directly at a cell center lead to inaccuracies. Secondly, sample plots can exceed the landscape boundary. Therefore, we report the actual clipped sample plot area relative in relation to the theoretical, maximum sample plot area e.g. a sample plot only half within the landscape will have a percentage_inside = 50. Additionally, if the polygon representing the sample plot is smaller than the cell size of the raster, the percentage_inside may exceed 100%.Please be aware that the output is slightly different to all other lsm-function of landscapemetrics.

Please be aware that the function behaves differently for POLYGONS and MULTIPOLYGONS. In the first case, each polygon is used as a singular sample area, while in the second case all polygons are used as one sample area.

The metrics can be specified by the arguments what, level, metric, name and/or type (combinations of different arguments are possible (e.g. level = "class", type = "aggregation metric"). If an argument is not provided, automatically all possibilities are selected. Therefore, to get all available metrics, don't specify any of the above arguments.

For all metrics based on distances or areas please make sure your data is valid using check_landscape.

See also

list_lsm
calculate_lsm

Examples

landscape <- terra::rast(landscapemetrics::landscape)

# use a matrix
sample_points <- matrix(c(10, 5, 25, 15, 5, 25), ncol = 2, byrow = TRUE)
sample_lsm(landscape, y = sample_points, size = 15, what = "lsm_l_np")
#> Warning: The 'perecentage_inside' is below 90% for at least one buffer.
#> Warning: Please use 'check_landscape()' to ensure the input data is valid.
#> # A tibble: 3 × 8
#>   layer level     class    id metric value plot_id percentage_inside
#>   <int> <chr>     <int> <int> <chr>  <dbl>   <int>             <dbl>
#> 1     1 landscape    NA    NA np        20       1              55.6
#> 2     1 landscape    NA    NA np        20       2              66.7
#> 3     1 landscape    NA    NA np        14       3              44.4