Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!
Get Started for Free

get_patches

get_patches

Description

Connected components labeling to derive patches in a landscape.

Usage

get_patches(landscape, class, directions, to_disk, return_raster)

## S3 method for class 'RasterLayer'
get_patches(
  landscape,
  class = "all",
  directions = 8,
  to_disk = getOption("to_disk", default = FALSE),
  return_raster = TRUE
)

## S3 method for class 'RasterStack'
get_patches(
  landscape,
  class = "all",
  directions = 8,
  to_disk = getOption("to_disk", default = FALSE),
  return_raster = TRUE
)

## S3 method for class 'RasterBrick'
get_patches(
  landscape,
  class = "all",
  directions = 8,
  to_disk = getOption("to_disk", default = FALSE),
  return_raster = TRUE
)

## S3 method for class 'stars'
get_patches(
  landscape,
  class = "all",
  directions = 8,
  to_disk = getOption("to_disk", default = FALSE),
  return_raster = TRUE
)

## S3 method for class 'list'
get_patches(
  landscape,
  class = "all",
  directions = 8,
  to_disk = getOption("to_disk", default = FALSE),
  return_raster = TRUE
)

## S3 method for class 'matrix'
get_patches(
  landscape,
  class = "all",
  directions = 8,
  to_disk = getOption("to_disk", default = FALSE),
  return_raster = FALSE
)

Arguments

landscape

Raster* Layer, Stack, Brick, SpatRaster (terra), stars, or a list of rasterLayers.
class

Either "all" (default) for every class in the raster, or specify class value. See Details.
directions

The number of directions in which patches should be connected: 4 (rook's case) or 8 (queen's case).
to_disk

Logical argument, if FALSE results of get_patches are hold in memory. If true, get_patches writes temporary files and hence, does not hold everything in memory. Can be set with a global option, e.g. option(to_disk = TRUE). See Details.
return_raster

If false, matrix is returned

Details

Searches for connected patches (neighbouring cells of the same class i). The 8-neighbours rule ('queen's case) or 4-neighbours rule (rook's case) is used. Returns a list with raster. For each class the connected patches have the value 1 - n. All cells not belonging to the class are NA.

Landscape metrics rely on the delineation of patches. Hence, get_patches is heavily used in landscapemetrics. As raster can be quite big, the fact that get_patches creates a copy of the raster for each class in a landscape becomes a burden for computer memory. Hence, the argument to_disk allows to store the results of the connected labeling algorithm on disk. Furthermore, this option can be set globally, so that every function that internally uses get_patches can make use of that.

Value

List

References

Vincent, L., Soille, P. 1991. Watersheds in digital spaces: an efficient algorithm based on immersion simulations. IEEE Transactions on Pattern Analysis and Machine Intelligence. 13 (6), 583-598

Examples

# check for patches of class 1
patched_raster <- get_patches(landscape, class = 1)

# count patches
length(raster::unique(patched_raster[[1]]))

# check for patches of every class
patched_raster <-  get_patches(landscape)
landscapemetrics

Landscape Metrics for Categorical Map Patterns

v1.5.2
GPL-3
Authors
Maximillian H.K. Hesselbarth [aut, cre] (<https://orcid.org/0000-0003-1125-9918>), Marco Sciaini [aut] (<https://orcid.org/0000-0002-3042-5435>), Jakub Nowosad [aut] (<https://orcid.org/0000-0002-1057-3721>), Sebastian Hanss [aut] (<https://orcid.org/0000-0002-3990-4897>), Laura J. Graham [ctb] (Input on package structure), Jeffrey Hollister [ctb] (Input on package structure), Kimberly A. With [ctb] (Input on package structure), Florian Privé [ctb] (Original author of underlying C++ code for get_nearestneighbour() function), Project Nayuki [ctb] (Original author of underlying C++ code for get_circumscribingcircle and lsm_p_circle), Matt Strimas-Mackey [ctb] (Bugfix in sample_metrics())
Initial release

We don't support your browser anymore

Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.