Landscapemetrics

https://r-spatialecology.github.io/landscapemetrics/
Admin
Landscapemetrics is an R package for calculating landscape metrics for categorical landscape...
Tokens:169,410
Snippets:1,074
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Development Dependencies

Source: https://r-spatialecology.github.io/landscapemetrics/CONTRIBUTING.html

Install all development dependencies for the landscapemetrics package using devtools. Ensure the package passes R CMD check afterwards.

```r
devtools::install_dev_deps()

```

--------------------------------

### Create Example Sample Points

Source: https://r-spatialecology.github.io/landscapemetrics/articles/articles/guide_sample_lsm.html

Generates a matrix of sample points for use in landscape metric calculations.

```r
# create some example points
(points <- matrix(c(10, 5, 25, 15, 5, 25), ncol = 2, byrow = TRUE))
##      [,1] [,2]
## [1,]   10    5
## [2,]   25   15
## [3,]    5   25
```

--------------------------------

### Get Boundaries as Matrix

Source: https://r-spatialecology.github.io/landscapemetrics/reference/get_boundaries.html

This example demonstrates how to use the `return_raster = FALSE` argument in `get_boundaries` to retrieve boundary coordinates as a matrix. This can be useful for further programmatic manipulation.

```r
landscape <- terra::rast(landscapemetrics::landscape)
class_1 <- get_patches(landscape, class = 1)[[1]][[1]]

get_boundaries(class_1, return_raster = FALSE)
```

--------------------------------

### Install landscapemetrics Package

Source: https://r-spatialecology.github.io/landscapemetrics/index.html

Installs the stable version of the landscapemetrics package from CRAN or the development version from GitHub.

```r
install.packages("landscapemetrics")
```

```r
# install.packages("remotes")
remotes::install_github("r-spatialecology/landscapemetrics")
```

--------------------------------

### GNU GPL Notice for Source Files

Source: https://r-spatialecology.github.io/landscapemetrics/LICENSE.html

Include this notice at the start of each source file to state the exclusion of warranty and provide licensing details.

```text
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) 2018 Marco Sciaini

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
```

--------------------------------

### Combine Patch Metric Calculations (Simplified)

Source: https://r-spatialecology.github.io/landscapemetrics/articles/get_started.html

Demonstrates combining patch metric calculations using dplyr::bind_rows. This is a simplified version of the previous example.

```r
patch_metrics <- dplyr::bind_rows(
  lsm_p_cai(landscape),
  lsm_p_circle(landscape),
  lsm_p_enn(landscape)
  )
```

--------------------------------

### Load Required R Packages

Source: https://r-spatialecology.github.io/landscapemetrics/articles/articles/irregular_areas.html

Installs and loads the `landscapemetrics`, `sf`, `terra`, and `tidyr` R packages. These are essential for landscape metric calculation and data manipulation.

```r
library(landscapemetrics)
library(sf)
library(terra)
library(tidyr)
```

--------------------------------

### Load Landscape Data

Source: https://r-spatialecology.github.io/landscapemetrics/reference/show_cores.html

Loads the example landscape data using terra::rast. This is a prerequisite for using the show_cores function.

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

--------------------------------

### Example Landscape Map

Source: https://r-spatialecology.github.io/landscapemetrics/reference/landscape.html

Generates an example raster object representing a landscape, useful for demonstrating landscapemetrics functions. This map is a simulated neutral landscape model.

```R
landscape
```

--------------------------------

### Create Example Sample Points

Source: https://r-spatialecology.github.io/landscapemetrics/articles/guide_sample_lsm.html

Define sample locations as a 2-column matrix for use with sampling functions. Coordinates represent x and y positions.

```r
# create some example points
(points <- matrix(c(10, 5, 25, 15, 5, 25), ncol = 2, byrow = TRUE))
```

--------------------------------

### Calculate Metrics by Level and Type

Source: https://r-spatialecology.github.io/landscapemetrics/reference/calculate_lsm.html

Illustrates calculating metrics filtered by both 'level' and 'type' arguments. This example selects 'aggregation metric' type for 'class' and 'landscape' levels.

```r
calculate_lsm(landscape, level = c("class", "landscape"),
type = "aggregation metric")
```

--------------------------------

### Calculate SPLIT for each class

Source: https://r-spatialecology.github.io/landscapemetrics/reference/lsm_c_split.html

This example demonstrates how to calculate the Splitting Index for each class in a landscape raster. Ensure your landscape data is valid using `check_landscape` before calculation.

```r
landscape <- terra::rast(landscapemetrics::landscape)
lsm_c_split(landscape)
#> # A tibble: 3 × 6
#>   layer level class    id metric value
#>   <int> <chr> <int> <int> <chr>  <dbl>
#> 1     1 class     1    NA split   68.1
#> 2     1 class     2    NA split   75.5
#> 3     1 class     3    NA split   13.1
```

--------------------------------

### Displaying Boundary Matrix Data

Source: https://r-spatialecology.github.io/landscapemetrics/reference/get_boundaries.html

This example shows the raw output of a boundary calculation, highlighting NA values and the structure of the resulting matrix. It is useful for understanding the default representation of boundary data.

```r
## [25,]    NA    NA    NA    NA    NA    NA    NA    NA    NA    NA    NA    NA
## [26,]    NA    NA    NA    NA    NA    NA    NA    NA    NA    NA    NA    NA
## [27,]    NA    NA    NA    NA    NA    NA    NA    NA    NA    NA    NA    NA
## [28,]    NA    NA    NA    NA    NA    NA    NA    NA    NA    NA    NA    NA
## [29,]    NA    NA    NA    NA    NA    NA     1    NA    NA    NA    NA    NA
## [30,]    NA    NA    NA    NA    NA    NA    NA     1     1    NA    NA    NA
##       [,26] [,27] [,28] [,29] [,30]
##  [1,]    NA    NA    NA    NA    NA
##  [2,]    NA    NA    NA    NA    NA
##  [3,]    NA    NA    NA    NA    NA
##  [4,]    NA    NA    NA    NA    NA
##  [5,]    NA    NA    NA    NA    NA
##  [6,]    NA    NA    NA    NA    NA
##  [7,]    NA    NA    NA    NA    NA
##  [8,]    NA    NA    NA    NA    NA
##  [9,]    NA    NA    NA    NA    NA
## [10,]    NA    NA    NA    NA    NA
## [11,]    NA    NA    NA    NA    NA
## [12,]    NA    NA    NA    NA    NA
## [13,]    NA    NA    NA    NA    NA
## [14,]    NA    NA    NA    NA    NA
## [15,]    NA    NA    NA    NA    NA
## [16,]    NA    NA    NA    NA    NA
## [17,]    NA    NA    NA    NA    NA
## [18,]    NA    NA    NA    NA    NA
## [19,]    NA    NA    NA    NA    NA
## [20,]    NA    NA    NA    NA    NA
## [21,]    NA    NA    NA    NA    NA
## [22,]    NA    NA    NA    NA    NA
## [23,]    NA    NA    NA    NA    NA
## [24,]    NA    NA    NA    NA    NA
## [25,]    NA    NA    NA    NA    NA
## [26,]    NA    NA    NA    NA    NA
## [27,]    NA     1    NA    NA    NA
## [28,]     1     1    NA    NA    NA
## [29,]     1     1    NA    NA    NA
## [30,]    NA    NA    NA    NA    NA
## 
```

--------------------------------

### List Specific Metric Using 'what' Argument

Source: https://r-spatialecology.github.io/landscapemetrics/reference/list_lsm.html

Query for a specific metric, like 'shape index', using the `what` argument. This example demonstrates how to retrieve details for `lsm_p_shape`.

```r
list_lsm(metric = "area", what = "lsm_p_shape")
#> Warning: Only using 'what' argument.
#> # A tibble: 1 × 5
#>   metric name        type         level function_name
#>   <chr>  <chr>       <chr>        <chr> <chr>        
#> 1 shape  shape index shape metric patch lsm_p_shape  
```

--------------------------------

### Calculate CAI_SD for a landscape

Source: https://r-spatialecology.github.io/landscapemetrics/reference/lsm_c_cai_sd.html

This example demonstrates how to calculate the CAI_SD metric for a given landscape raster. Ensure the landscape data is valid using `check_landscape` before calculation.

```r
landscape <- terra::rast(landscapemetrics::landscape)
lsm_c_cai_sd(landscape)
#> # A tibble: 3 × 6
#>   layer level class    id metric value
#>   <int> <chr> <int> <int> <chr>  <dbl>
#> 1     1 class     1    NA cai_sd  20.9
#> 2     1 class     2    NA cai_sd  20.2
#> 3     1 class     3    NA cai_sd  24.0
```

--------------------------------

### Calculate Splitting Index for a Landscape

Source: https://r-spatialecology.github.io/landscapemetrics/reference/lsm_l_split.html

This example demonstrates how to calculate the Splitting Index for a given landscape raster. Ensure your landscape data is valid using `check_landscape` before calculation.

```r
landscape <- terra::rast(landscapemetrics::landscape)
lsm_l_split(landscape)
#> # A tibble: 1 × 6
#>   layer level     class    id metric value
#>   <int> <chr>     <int> <int> <chr>  <dbl>
#> 1     1 landscape    NA    NA split   9.59
```

--------------------------------

### Calculate FRAC_SD for a landscape

Source: https://r-spatialecology.github.io/landscapemetrics/reference/lsm_c_frac_sd.html

This example demonstrates how to calculate the FRAC_SD metric for a given landscape raster. Ensure the landscape object is a valid categorical raster and specify the desired directions for connectivity.

```r
landscape <- terra::rast(landscapemetrics::landscape)
lsm_c_frac_sd(landscape)
```

--------------------------------

### Calculate CIRCLE_SD for a landscape

Source: https://r-spatialecology.github.io/landscapemetrics/reference/lsm_c_circle_sd.html

This example demonstrates how to calculate the CIRCLE_SD metric for a given landscape raster. Ensure the landscape data is valid using `check_landscape` before calculation.

```r
landscape <- terra::rast(landscapemetrics::landscape)
lsm_c_circle_sd(landscape)
```

--------------------------------

### Calculate Mean Perimeter-Area Ratio by Class

Source: https://r-spatialecology.github.io/landscapemetrics/reference/lsm_c_para_mn.html

This example demonstrates how to calculate the mean perimeter-area ratio for each class in a landscape raster. Ensure your landscape data is valid using `check_landscape` before computation.

```r
landscape <- terra::rast(landscapemetrics::landscape)
lsm_c_para_mn(landscape)
```

--------------------------------

### Calculate ENN_SD for a landscape

Source: https://r-spatialecology.github.io/landscapemetrics/reference/lsm_l_enn_sd.html

This example demonstrates how to calculate the standard deviation of Euclidean nearest-neighbor distances for a given landscape raster. Ensure the 'terra' package is installed and the landscape data is loaded.

```r
landscape <- terra::rast(landscapemetrics::landscape)
lsm_l_enn_sd(landscape)
```

--------------------------------

### List Specific Metrics by Function Name

Source: https://r-spatialecology.github.io/landscapemetrics/reference/list_lsm.html

Select specific metrics by providing their function names as a character vector to the `what` argument. For example, to get details for 'lsm_c_ca' and 'lsm_l_ta', use `what = c("lsm_c_ca", "lsm_l_ta")`.

```r
list_lsm(what = c("lsm_c_ca", "lsm_l_ta"))
```

--------------------------------

### Calculate All Landscape Metrics

Source: https://r-spatialecology.github.io/landscapemetrics/reference/calculate_lsm.html

Demonstrates how to calculate all available landscape metrics for a given raster object. Set progress to TRUE to see a progress report during calculation.

```r
landscape <- terra::rast(landscapemetrics::landscape)
calculate_lsm(landscape, progress = TRUE)
```

--------------------------------

### Get unique values from a terra raster object

Source: https://r-spatialecology.github.io/landscapemetrics/reference/get_unique_values.html

Demonstrates how to get unique values from a single terra raster layer. Note that double values are converted to integers.

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

get_unique_values(landscape)
#> Warning: Double values will be converted to integer.
#> $layer_1
#> [1] 1 2 3
#

```

--------------------------------

### List Metrics Using Only the 'what' Argument

Source: https://r-spatialecology.github.io/landscapemetrics/reference/list_lsm.html

Retrieve information for specific metrics by providing a vector of metric names or function names to the `what` argument. This example lists 'total core area' and 'total area'.

```r
list_lsm(what = c("lsm_c_tca", "lsm_l_ta"))
#> # A tibble: 2 × 5
#>   metric name            type                 level     function_name
#>   <chr>  <chr>           <chr>                <chr>     <chr>        
#> 1 tca    total core area core area metric     class     lsm_c_tca    
#> 2 ta     total area      area and edge metric landscape lsm_l_ta     
```

--------------------------------

### Basic Usage of show_patches

Source: https://r-spatialecology.github.io/landscapemetrics/reference/show_patches.html

Demonstrates the default usage of the show_patches function with a sample landscape raster. This will display all patches with default settings.

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

show_patches(landscape)
```

--------------------------------

### Internal Datasets

Source: https://r-spatialecology.github.io/landscapemetrics/reference/index.html

This section lists the internal datasets available within the landscapemetrics package, which can be useful for examples and testing.

```APIDOC
## Internal Datasets

### `lsm_abbreviations_names`

Tibble of abbreviations coming from FRAGSTATS.

### `landscape`

Example map (random cluster neutral landscape model).

### `augusta_nlcd`

Augusta NLCD 2011.

### `podlasie_ccilc`

Podlasie ESA CCI LC.
```

--------------------------------

### Calculate Specific Landscape Metrics by 'what' Argument

Source: https://r-spatialecology.github.io/landscapemetrics/reference/calculate_lsm.html

Shows how to calculate specific metrics by providing a vector of metric identifiers to the 'what' argument. This includes patch-level metrics and class/landscape-level metrics.

```r
calculate_lsm(landscape, what = c("patch", "lsm_c_te", "lsm_l_pr"))
```

--------------------------------

### Interactive Mode Notice for Landscapemetrics

Source: https://r-spatialecology.github.io/landscapemetrics/LICENSE.html

This notice should be displayed when the program starts in interactive mode, informing users about warranty and redistribution terms.

```text
landscapemetrics Copyright (C) 2018 Marco Sciaini
This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type 'show c' for details.
```

--------------------------------

### List Metrics Based on Multiple 'what' Criteria

Source: https://r-spatialecology.github.io/landscapemetrics/reference/list_lsm.html

Use the `what` argument with a vector of metric names to retrieve information for multiple specific metrics. This example lists metrics related to 'area' and a specific shape metric.

```r
list_lsm(metric = "area", what = c("patch", "lsm_l_ta"))
#> Warning: Only using 'what' argument.
#> # A tibble: 13 × 5
#>    metric name                                type           level function_name
#>    <chr>  <chr>                               <chr>          <chr> <chr>        
#>  1 area   patch area                          area and edge… patch lsm_p_area   
#>  2 cai    core area index                     core area met… patch lsm_p_cai    
#>  3 circle related circumscribing circle       shape metric   patch lsm_p_circle 
#>  4 contig contiguity index                    shape metric   patch lsm_p_contig 
#>  5 core   core area                           core area met… patch lsm_p_core   
#>  6 enn    euclidean nearest neighbor distance aggregation m… patch lsm_p_enn    
#>  7 frac   fractal dimension index             shape metric   patch lsm_p_frac   
#>  8 gyrate radius of gyration                  area and edge… patch lsm_p_gyrate 
#>  9 ncore  number of core areas                core area met… patch lsm_p_ncore  
#> 10 para   perimeter-area ratio                shape metric   patch lsm_p_para   
#> 11 perim  patch perimeter                     area and edge… patch lsm_p_perim  
#> 12 shape  shape index                         shape metric   patch lsm_p_shape  
#> 13 ta     total area                          area and edge… land… lsm_l_ta     
```

--------------------------------

### Calculate Implemented Distribution Statistics

Source: https://r-spatialecology.github.io/landscapemetrics/articles/articles/landscape_distribution_statistics.html

Demonstrates how to calculate pre-implemented distribution statistics for shape index at class and landscape levels using landscapemetrics.

```R
# calculate mean shape index on class level
mean_shape_c <- lsm_c_shape_mn(landscape)

# calculate standard deviation of shape index on landscape level
sd_shape_l <- lsm_l_shape_sd(landscape)
```

--------------------------------

### Get Smallest Circumscribing Circle

Source: https://r-spatialecology.github.io/landscapemetrics/articles/articles/utility.html

Calculates the smallest circumscribing circle for each patch, returning the diameter. This considers the entire cells, including corners.

```r
class_1 <- get_patches(landscape, class = 1)

# get smallest circumscribing circle for each patch
circle <- get_circumscribingcircle(class_1$layer_1$class_1)
circle
```

--------------------------------

### List All Available Landscape Metrics

Source: https://r-spatialecology.github.io/landscapemetrics/articles/get_started.html

Lists all available landscape metrics in the package. The output is a tibble containing metric details.

```r
list_lsm()
```

--------------------------------

### Get Boundaries as SpatRaster

Source: https://r-spatialecology.github.io/landscapemetrics/reference/get_boundaries.html

This snippet shows the default usage of `get_boundaries` which returns boundary information as a SpatRaster object. It requires a patch object as input.

```r
landscape <- terra::rast(landscapemetrics::landscape)
class_1 <- get_patches(landscape, class = 1)[[1]][[1]]

get_boundaries(class_1)
```

--------------------------------

### Load Libraries and Data

Source: https://r-spatialecology.github.io/landscapemetrics/articles/articles/landscape_distribution_statistics.html

Loads necessary R libraries and the sample landscape data for analysis.

```R
library(landscapemetrics)
library(terra)
library(dplyr)

# internal data needs to be read
landscape <- terra::rast(landscapemetrics::landscape)
```

--------------------------------

### Calculate ENN_CV for a Landscape

Source: https://r-spatialecology.github.io/landscapemetrics/reference/lsm_l_enn_cv.html

This example demonstrates how to calculate the ENN_CV metric for a given landscape raster. Ensure the landscape data is valid using `check_landscape` before calculation.

```r
landscape <- terra::rast(landscapemetrics::landscape)
lsm_l_enn_cv(landscape)
```

--------------------------------

### Calculate Perimeter of All Patches

Source: https://r-spatialecology.github.io/landscapemetrics/articles/get_started.html

Demonstrates how to calculate a specific landscape metric, the perimeter of all patches, using the `lsm_p_perim` function. The output is a tibble containing details for each patch.

```R
# import raster
# for local file: rast("pathtoyourraster/raster.asc")
# ... or any other raster file type, geotiff, ...

# Calculate e.g. perimeter of all patches
lsm_p_perim(landscape)
#> # A tibble: 28 × 6
#>    layer level class    id metric value
#>    <int> <chr> <int> <int> <chr>  <dbl>
#>  1     1 patch     1     1 perim      4
#>  2     1 patch     1     2 perim     12
#>  3     1 patch     1     3 perim     60
#>  4     1 patch     1     4 perim      4
#>  5     1 patch     1     5 perim      4
#>  6     1 patch     1     6 perim     68
#>  7     1 patch     1     7 perim     22
#>  8     1 patch     1     8 perim     10
#>  9     1 patch     1     9 perim     10
#> 10     1 patch     2    10 perim     38
#> # ℹ 18 more rows
```

--------------------------------

### Calculate ENN_SD for a landscape

Source: https://r-spatialecology.github.io/landscapemetrics/reference/lsm_c_enn_sd.html

This example demonstrates how to calculate the ENN_SD metric for a given landscape raster. Ensure the landscape data is valid using `check_landscape` before calculation.

```r
landscape <- terra::rast(landscapemetrics::landscape)
lsm_c_enn_sd(landscape)
```

--------------------------------

### Calculate Patch Metrics with SDMTools

Source: https://r-spatialecology.github.io/landscapemetrics/articles/comparing_tools.html

This snippet demonstrates how to calculate patch metrics using the SDMTools package. It involves binarizing each class in the landscape, performing connected components labeling, and then calculating patch statistics.

```R
# binarize every class in the landscape and calculate patch metrics
sdmtools_result <- lapply(terra::unique(landscape), FUN = function(x){
  tmp_land <- landscape
  terra::values(tmp_land)[terra::values(tmp_land) != x] <- NA
  terra::values(tmp_land)[terra::values(tmp_land) == x] <- 1
  ccl <- SDMTools::ConnCompLabel(raster::raster(tmp_land))
  PatchStat(ccl)
})

# combine to one data frame
sdmtools_result <- dplyr::bind_rows(sdmtools_result, .id = "Class")
```

--------------------------------

### Load Libraries and Landscape Data

Source: https://r-spatialecology.github.io/landscapemetrics/articles/articles/guide_moving_window.html

Loads the necessary R libraries (landscapemetrics, terra, ggplot2) and reads the example landscape data into a terra SpatRaster object.

```r
library(landscapemetrics)
library(terra)
library(ggplot2)

# internal data needs to be read
landscape <- terra::rast(landscapemetrics::landscape)
```

--------------------------------

### Calculate Metrics with a Circular Moving Window

Source: https://r-spatialecology.github.io/landscapemetrics/reference/window_lsm.html

Illustrates the use of `window_lsm` with a custom circular window matrix to calculate specified landscape metrics. This allows for more nuanced neighborhood definitions compared to standard square windows.

```R
window_circular <- matrix(c(NA, 1, NA, 1, 1, 1, NA, 1, NA), nrow = 3, ncol = 3)
window_lsm(landscape, window = window_circular, what = c("lsm_l_pr", "lsm_l_joinent"))
```

--------------------------------

### Getting Patches for Each Class

Source: https://r-spatialecology.github.io/landscapemetrics/articles/articles/utility.html

The 'get_patches' function extracts all patches for each class in the landscape, labeling them sequentially. This function is a core component for internal landscape metric calculations.

```r
get_patches(landscape)
#> $layer_1
#> $layer_1$class_1
#> class       : SpatRaster 
#> dimensions  : 30, 30, 1  (nrow, ncol, nlyr)
#> resolution  : 1, 1  (x, y)
#> extent      : 0, 30, 0, 30  (xmin, xmax, ymin, ymax)
#> coord. ref. :  
#> source(s)   : memory
#> name        : lyr.1 
#> min value   :     1 
#> max value   :     9 
#> 
#> $layer_1$class_2
#> class       : SpatRaster 
#> dimensions  : 30, 30, 1  (nrow, ncol, nlyr)
#> resolution  : 1, 1  (x, y)
#> extent      : 0, 30, 0, 30  (xmin, xmax, ymin, ymax)
#> coord. ref. :  
#> source(s)   : memory
#> name        : lyr.1 
#> min value   :    10 
#> max value   :    22 
#> 
#> $layer_1$class_3
#> class       : SpatRaster 
#> dimensions  : 30, 30, 1  (nrow, ncol, nlyr)
#> resolution  : 1, 1  (x, y)
#> extent      : 0, 30, 0, 30  (xmin, xmax, ymin, ymax)
#> coord. ref. :  
#> source(s)   : memory
#> name        : lyr.1 
#> min value   :    23 
#> max value   :    28
```

--------------------------------

### sample_lsm

Source: https://r-spatialecology.github.io/landscapemetrics/reference/sample_lsm.html

Samples landscape metrics in a buffer area around sample points, lines, or within provided polygons. Metrics can be specified, and the function handles coordinate transformations and potential inaccuracies in area calculations.

```APIDOC
## Function: sample_lsm

### Description
This function samples landscape metrics in a buffer area (sample plot) around sample points, sample lines or within provided polygons. It allows for the specification of metrics and handles various parameters related to sampling shape, size, and coordinate system transformations.

### Arguments
* `landscape` (SpatRaster, Raster* Layer/Stack/Brick, stars, or list of SpatRasters): A categorical raster object.
* `y` (2-column matrix or spatial object): Coordinates or spatial object defining the sample locations.
* `plot_id` (Vector, optional): Vector with IDs for sample points. If not provided, points are labeled 1 to n.
* `shape` (String): Specifies the plot shape, either "circle" or "square".
* `size` (Numeric, optional): Approximated size of the sample plot (radius for circles, half side-length for squares, or buffer width for lines) in map units.
* `transform` (Logical): If TRUE, planar CRS are transformed to lon/lat for accurate area calculations of buffer areas.
* `all_classes` (Logical): If TRUE, NA is returned for classes not present in some sample plots.
* `return_raster` (Logical): If TRUE, the clipped raster of the sample plot is returned.
* `verbose` (Logical): If TRUE, prints warning messages.
* `progress` (Logical): If TRUE, prints progress report.
* `...`: Arguments passed on to `calculate_lsm()`.

### Value
tibble: A data frame containing the sampled landscape metrics.

### Details
The function samples metrics within specified buffer areas. Users can specify metrics using arguments like `what`, `level`, `metric`, `name`, and/or `type`. If these arguments are not provided, all available metrics are selected. For metrics based on distances or areas, it is recommended to use `check_landscape()` to ensure data validity. The function accounts for potential inaccuracies in sampled area size due to cell clipping or exceeding landscape boundaries, reporting `percentage_inside` to indicate the proportion of the sample plot within the landscape. Area calculations use `terra::expanse()`, and results may be influenced by the CRS and the `transform` argument. The behavior differs for POLYGONS and MULTIPOLYGONS.

### See Also
`list_lsm`, `calculate_lsm`

### Examples
```R
landscape <- terra::rast(landscapemetrics::landscape)

# Use a matrix for sample points
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
```
```

--------------------------------

### Landscapemetrics Function Structure

Source: https://r-spatialecology.github.io/landscapemetrics/articles/get_started.html

Illustrates the naming convention for landscapemetrics functions, which typically start with 'lsm_', followed by the level (patch, class, or landscape), and then the metric abbreviation.

```R
# general structure
lsm_"level"_"metric"

# Patch level
## lsm_p_"metric"
lsm_p_enn()

# Class level
## lsm_c_"metric"
lsm_c_enn()

# Landscape level
## lsm_p_"metric"
lsm_l_enn()
```

--------------------------------

### List Aggregation Metrics for Patch and Landscape Levels

Source: https://r-spatialecology.github.io/landscapemetrics/reference/list_lsm.html

Use `list_lsm` to find aggregation metrics available at both the patch and landscape levels. This helps in understanding which metrics can be calculated for individual patches and for the entire landscape.

```r
list_lsm(level = c("patch", "landscape"), type = "aggregation metric")
#> # A tibble: 15 × 5
#>    metric   name                                  type       level function_name
#>    <chr>    <chr>                                 <chr>      <chr> <chr>        
#>  1 enn      euclidean nearest neighbor distance   aggregati… patch lsm_p_enn    
#>  2 ai       aggregation index                     aggregati… land… lsm_l_ai     
#>  3 cohesion patch cohesion index                  aggregati… land… lsm_l_cohesi…
#>  4 contag   connectance                           aggregati… land… lsm_l_contag 
#>  5 division division index                        aggregati… land… lsm_l_divisi…
#>  6 enn_cv   euclidean nearest neighbor distance   aggregati… land… lsm_l_enn_cv 
#>  7 enn_mn   euclidean nearest neighbor distance   aggregati… land… lsm_l_enn_mn 
#>  8 enn_sd   euclidean nearest neighbor distance   aggregati… land… lsm_l_enn_sd 
#>  9 iji      interspersion and juxtaposition index aggregati… land… lsm_l_iji    
#> 10 lsi      landscape shape index                 aggregati… land… lsm_l_lsi    
#> 11 mesh     effective mesh size                   aggregati… land… lsm_l_mesh   
#> 12 np       number of patches                     aggregati… land… lsm_l_np     
#> 13 pd       patch density                         aggregati… land… lsm_l_pd     
#> 14 pladj    percentage of like adjacencies        aggregati… land… lsm_l_pladj  
#> 15 split    splitting index                       aggregati… land… lsm_l_split  
```

--------------------------------

### Calculate NCORE for each patch

Source: https://r-spatialecology.github.io/landscapemetrics/reference/lsm_p_ncore.html

This example demonstrates how to calculate the NCORE metric for each patch in a given landscape raster. It requires the 'terra' package for raster manipulation and the 'landscapemetrics' package.

```r
landscape <- terra::rast(landscapemetrics::landscape)
lsm_p_ncore(landscape)
```

--------------------------------

### Set `to_disk` Option in landscapemetrics

Source: https://r-spatialecology.github.io/landscapemetrics/reference/options_landscapemetrics.html

Demonstrates how to set the global `to_disk` option for the landscapemetrics package. This option controls whether intermediate patch data is stored in memory or written to disk, impacting memory usage for large rasters.

```R
options_landscapemetrics(to_disk = NULL)
```

```R
options(to_disk = TRUE)
```
Tokens:
Raw