README last updated: 2023-03-22
Starting from v2.0.0, landscapemetrics does not support the
sppackages. They are replaced by
sf, respectively. More information about the
terrapackage can be found here: https://rspatial.org/index.html.
landscapemetrics is a
R package for calculating landscape metrics
for categorical landscape patterns in a tidy workflow. The package can
be used as a drop-in replacement for FRAGSTATS (McGarigal et al.
2012), as it offers a reproducible workflow for landscape analysis in a
single environment. It also allows for calculations of four theoretical
metrics of landscape complexity: a marginal entropy, a conditional
entropy, a joint entropy, and a mutual information (Nowosad and
objects and takes
RasterBricks lists of
stars as input arguments. Every
function can be used in a piped workflow, as it always takes the data as
the first argument and returns a
To cite landscapemetrics or acknowledge its use, please cite the following Software note, substituting the version of the application that you used for ‘ver. 0’:
Hesselbarth, M.H.K., Sciaini, M., With, K.A., Wiegand, K., Nowosad, J. 2019. landscapemetrics: an open‐source R tool to calculate landscape metrics. Ecography, 42: 1648-1657 (ver. 0).
For more information see Publication
vignette. The get a BibTex entry, please use
There are several ways to install landscapemetrics:
# Get the stable version from CRAN install.packages("landscapemetrics") # Alternatively, you can install the development version from Github # install.packages("remotes") remotes::install_github("r-spatialecology/landscapemetrics")
Due to an improved connected-component labelling algorithm (landscapemetrics v1.4 and higher), patches are labeled in a different order than before and therefore different patch IDs might be used compared to previous versions. However, results for all metrics are identical.
The resolution of a raster cell has to be in meters, as the package
converts units internally and returns results in either meters, square
meters or hectares. Before using landscapemetrics, be sure to check
your raster (see
All functions in landscapemetrics start with
landscape metrics). The second part of the name specifies
the level (patch -
p, class -
c or landscape -
l). The last part
of the function name is the abbreviation of the corresponding metric
enn for the euclidean nearest-neighbor distance):
# 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()
All functions return an identical structured tibble:
Using metric functions
Every function follows the same implementation design, so the usage is quite straightforward:
library(landscapemetrics) library(landscapetools) # landscape raster show_landscape(landscape, discrete = TRUE)
# calculate for example the Euclidean nearest-neighbor distance on patch level lsm_p_enn(landscape) #> # A tibble: 27 × 6 #> layer level class id metric value #> <int> <chr> <int> <int> <chr> <dbl> #> 1 1 patch 1 1 enn 7 #> 2 1 patch 1 2 enn 4 #> 3 1 patch 1 3 enn 2.83 #> 4 1 patch 1 4 enn 2 #> 5 1 patch 1 5 enn 2 #> 6 1 patch 1 6 enn 2.83 #> 7 1 patch 1 7 enn 4.12 #> 8 1 patch 1 8 enn 4.12 #> 9 1 patch 1 9 enn 4.24 #> 10 1 patch 2 10 enn 4.47 #> # … with 17 more rows # calculate the total area and total class edge length lsm_l_ta(landscape) #> # A tibble: 1 × 6 #> layer level class id metric value #> <int> <chr> <int> <int> <chr> <dbl> #> 1 1 landscape NA NA ta 0.09 lsm_c_te(landscape) #> # A tibble: 3 × 6 #> layer level class id metric value #> <int> <chr> <int> <int> <chr> <dbl> #> 1 1 class 1 NA te 180 #> 2 1 class 2 NA te 227 #> 3 1 class 3 NA te 321
There is also a wrapper around every metric in the package to quickly calculate a bunch of metrics:
# calculate all metrics on patch level calculate_lsm(landscape, level = "patch") #> Warning: Please use 'check_landscape()' to ensure the input data is valid. #> # A tibble: 324 × 6 #> layer level class id metric value #> <int> <chr> <int> <int> <chr> <dbl> #> 1 1 patch 1 1 area 0.0001 #> 2 1 patch 1 2 area 0.0005 #> 3 1 patch 1 3 area 0.0148 #> 4 1 patch 1 4 area 0.0001 #> 5 1 patch 1 5 area 0.0001 #> 6 1 patch 1 6 area 0.0014 #> 7 1 patch 1 7 area 0.0003 #> 8 1 patch 1 8 area 0.0005 #> 9 1 patch 1 9 area 0.0001 #> 10 1 patch 2 10 area 0.0035 #> # … with 314 more rows
landscapemetrics further provides several visualization functions,
e.g. show all labeled patches or the core area of all patches. All
visualization functions start with the prefix
Important building blocks of the package are exported to help facilitate
analysis or the development of new metrics. They all start with the
get_. All of them are implemented with Rcpp and have either
memory or performance advantages compared to raster functions.
For more details, see the
One of the major motivations behind landscapemetrics is the idea to provide an open-source code collection of landscape metrics. This includes, besides bug reports, especially the idea to include new metrics and functions. Therefore, in case you want to suggest new metrics or functions and in the best case even contribute code, we warmly welcome to do so! For more information see CONTRIBUTING.
Maintainers and contributors must follow this repository’s CODE OF CONDUCT.
McGarigal, K., Cushman, S.A., and Ene E. 2012. FRAGSTATS v4: Spatial Pattern Analysis Program for Categorical and Continuous Maps. Computer software program produced by the authors at the University of Massachusetts, Amherst. Available at the following website: https://www.umass.edu/landeco/
Nowosad J., TF Stepinski. 2019. Information theory as a consistent framework for quantification and classification of landscape patterns. https://doi.org/10.1007/s10980-019-00830-x