optimize_gradient: Optimize metric's gradient

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

Optimize metric's gradient

Description

Selects a set of points whose associated landscapes comprise an optimized gradient for a given landscape metric.

Usage

optimize_gradient(
  x,
  rasterlayer = NULL,
  class = NULL,
  radius = NULL,
  metric = NULL,
  n,
  cutpoints = NULL,
  breaks = NULL,
  output = "MLM"
)

Arguments

x	An object of class 'MultiLandMetrics' generated with metrics().
rasterlayer	The rasterlayer to be considered. If an extra rasterlayer must be specified, the string "ext" must precede the rasterlayer number (e.g. "ext1", "ext2")
class	The class to be considered, as a number or as a string with the name of the class.
radius	The radius to be considered.
metric	The metric to be considered. Metrics as extra calculations for extra rasterlayers must be provided as "fun_" + the name of the function.
n	The number of points that will comprise the gradient. See Details.
cutpoints	A sequence of numbers that will serve as numeric approximations to select the points that will comprise the gradient. See Details.
breaks	A unique number with the number of breaks that will generate the cutpoints for the specified metric values. Default is 10. See Details.
output	One of the following: "MLM" to return an updated version of the 'MultiLandMetrics' object provided in x (default), "spatial" to return a 'SpatVector' with the points of the selected landscapes, "data" to return a data.frame with the metric values information or "coords" to return a data.frame with geographical information of the selected points.

Details

The purpose of this function is to select a subset of landscapes that overall will generate an optimized gradient of values for a given landscape metric of a specified rasterlayer, class and radius. We can define a gradient as optimized if its values fulfill to cover a good range of values between a minimum and a maximum value. The final gradient will comprise the number of points specified in argument n. Note that only one landscape metric can be specified at a time.

The algorithm will select those points whose associated landscapes present values for the specified landscape metric that are the most close to the specified cutpoints. Alternatively, the user can provide a number of breaks from which the sequence of cutpoints will be generated. If both arguments are specified, the function will consider the values inputted in cutpoints. If both arguments are NULL, the algorithm will simply select n random points.

Value

A 'MultiLandMetrics' if output = "MLM", a 'SpatVector' if output = "spatial", a data.frame if output = "data" or a data.frame with geographical information of the points if output = "coords".

See Also

landscape_filter()

Examples

# Generates an optimized gradient for the landscape metric "pland", for the class "Forest".
pland_gradient <- optimize_gradient(otf_metrics, rasterlayer = 1, class = "Forest", radius = 2000,
                                    metric = "pland", n = 15, breaks = 10)
# Note that, in this case, specifications for the rasterlayer and the radius are redundant, and
# could be simply ignored and left as default, asthe object otf_metrics only comprises a unique
# rasterlayer and radius.

# By default, the output is an updated version of the object otf_metrics. In order to inspect
# the returned values, let's select only the dataframe containing the metric's values.
foo <- subset(pland_gradient@data, metric == "pland" & classname == "Forest",
              select = value)

# Next, we output the range of values we have obtained, note there are 15 points, as previously
# specified in the function definition in the argument 'n'
round(sort(foo$value), digits = 2)

# [1]  1.15  1.57  8.17  8.19 15.24 22.32 29.27 36.32 43.17 43.20 49.79 50.25 55.44 57.62 64.53

# Alternatively, we can define specific cutpoints around the landscapes will be selected in terms
# of its numeric closeness.
pland_gradient <- optimize_gradient(otf_metrics, rasterlayer = 1, class = "Forest", radius = 2000,
                                    metric = "pland", n = 15, cutpoints = seq(1, 60, 5))

# Again, we inspect the dataframe with the metric values to see our results.
foo <- subset(pland_gradient@data, metric == "pland" & classname == "Forest",
              select = value)

round(sort(foo$value), digits = 2)

# [1] 1.15  6.02  6.03 10.99 15.97 20.99 26.01 31.02 35.95 41.14 41.34 45.93 51.41 54.56 55.44

# Both alternatives generated a well-ranged gradient of values for the forest metric "pland"

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