land_points: Generates point coordinates

In phuais/multilandR: multilandr: Landscape Analysis at Multiple Spatial Scales

Generates point coordinates

Description

Generates point coordinates over a rasterlayer extent.

Usage

land_points(
  raster,
  approach = "grid",
  n = NULL,
  try = NULL,
  values = NULL,
  patch_conditions = NULL,
  trim = TRUE,
  attempts = 10,
  distance = NULL,
  offset = FALSE,
  closest_cell = FALSE,
  parallel = FALSE,
  cores = 1,
  progress = TRUE
)

Arguments

raster	An object of class 'SpatRaster', ' RasterLayer', 'RasterStack', or 'RasterBrick'.
approach	One of the following: "grid" to generate points through a grid, "random" to generate points at random locations, or "patch" to generate points inside patches that meet pre-defined conditions. See Details.
n	Number of point to generate.
try	Number of points to be generated in each turn. Only applies if approach = "random". See Details.
values	The values of the rasterlayer where points should be placed. Only applies if approach = "random".
patch_conditions	The conditions that patches must meet to be included as the patches from which points will be generated. Only applies if approach = "patch". See Details.
trim	Logical. If TRUE (default) the number of final points will be trimmed to the value defined in n.
attempts	Number of attempts to generate new random points given the total required points (n) and the minimum distance required in distance. Only applies if approach = "random". See Details.
distance	Distance between points of the grid (if approach = "grid") or minimum distance between generated points (if approach = "random").
offset	Logical. If TRUE, each point coordinates will be randomly displaced around the area occupied by the raster cell size. If FALSE (default), each point will be located at the center of a given raster cell. Only applies if approach = "random".
closest_cell	Logical. If approach = "patch", whether to return the coordinates of each patch centroid even if they fall outside the patch (FALSE, default) or to move the point to the closest cell of the patch if this happens (TRUE).
parallel	Logical. If TRUE, part of the processes will be parallelized. See Details.
cores	Number of cores to use if parallel = TRUE.
progress	Logical. If TRUE (default), progress of the analysis will be printed.

Details

If approach = "random", the user can restrict the locations of new generated points inside raster cells with certain value or values, by defining them in values. Also a minimum distance between the generated points can be defined in distance (also applies for the resolution of the grid if approach = "grid").

If approach = "random" and a minimum distance was defined, the function will generate new "random" points in sequential passes. In each pass, the function will try to generate new points taking into account the minimum distance between points, by randomly generating a number of points as defined in try. The function will perform this task until the new generated points is equal or higher than n. If try = NULL (default), try will equals n. If in each turn no new points were added (i.e. new points were located at less than the minimum distance to other previously generated points), the function will record this event. If this event happens more than the number of times defined in attempts before the total generated points equals n, the function will terminate, and return the points that were successfully generated given the required parameters. The user may try different values for n, try and attempts to get a desirable result.

If approach = "patch", the function will return as many points as patches that meet certain conditions in relation to pre-defined metric values. Conditions can be defined inside argument patch_conditions. This must be a list, with each element as a new list with the condition that the patch must meet in relation to the value of certain patch-level metric, as follows:

 list(list(class, metric, minimum value, maximum value),
      list(class, metric, minimum value, maximum value), ...)

• class: the class (raster value) of the patch that must meet the defined conditions. More than one class can be specified.

• metric: the patch-level metric whose values must meet the defined conditions. Only one metric per condition can be defined. Available patch-level metrics can be found in metrics_list() and in documentation of the package landscapemetrics().

• minimum value: the minimum value that the metric must have for the retained patches. If equal to -Inf, and a maximum value is defined, patches whose values in the defined metric are equal or lower to the maximum value will be retained.

• maximum value: the maximum value that the metric must have in the retained patches. If equal to Inf, and a minimum value is defined, patches whose values in the defined metric are equal or higher to the minimum value will be retained.

Retained patches will be those patches that meet all patch conditions at the same time. Returned point's coordinates will equal the centroid of each patch. If closest_cell = TRUE, the point's coordinates of the centroids that did not fall inside the patch will be moved to the closest cell belonging to that patch.

If parallel = TRUE the function will parallelize part of the processes. Parallelization is done to obtain the coordinates of the patches if approach = "patch". The number of cores must be declared in cores (parallelization requires at least two cores). To use this functionality, package parallel must be installed. So far, parallelization will run in LINUX and MAC, but not in Windows.

Value

An object of class 'SpatVector' containing the coordinates of the generated points.

See Also

mland()

Examples

# Loads raster
elchaco <- terra::rast(system.file("extdata", "elchaco.tif", package = "multilandr"))

# Returns points at "random" locations, but inside cells of value equals to 1.
chaco_coords <- land_points(elchaco, approach = "random", values = 1, n = 500)

# The same but points must be separated by at least 300 m between each other. Also, each point
# is randomly displaced inside the raster cell.
chaco_coords2 <- land_points(elchaco, approach = "random", values = 1, n = 500,
                             try = 100, distance = 300, offset = TRUE)

## Not run: 
# Returns as many points as patches that meet the defined condition. This is
# all patches of value equal to 1 of area between 9 and 11 hectares.
patch_sites <- land_points(elchaco, approach = "patch",
                           patch_conditions = list(list(1, "area", 8, 12)))

## End(Not run)

phuais/multilandR documentation built on Feb. 11, 2024, 9:27 p.m.