mland_metrics: Calculates landscape metrics
In phuais/multilandR: Landscape Analysis at Multiple Spatial Scales
View source: R/mland_metrics.R
mland_metrics R Documentation
Calculates landscape metrics
Description
Calculates landscape metrics of patch, class and/or landscape level via the package
landscapemetrics and user-defined functions from an object of class 'MultiLand'.
Usage
mland_metrics(
x,
raster = NULL,
points = NULL,
radii = NULL,
classes = NULL,
level = NULL,
metric = NULL,
name = NULL,
type = NULL,
what = NULL,
report_absences = TRUE,
absence_values = NULL,
ext_calc = NULL,
na.exclude = TRUE,
coords = FALSE,
update = NULL,
output = "MLM",
progress = TRUE,
...
)
Arguments
x
An object of class 'Multiland' generated with mland().
raster
Vector depicting the raster layers of x from which metrics will be
calculated. It can be a numeric vector, for rasterlayer numbers, or a character vector, for
raster layer names (if provided during the generation of x). If NULL, all raster layers will be
considered.
points
Numeric or character vector with the points from which metrics will be calculated.
If NULL, all points will be considered. See Details.
radii
Numeric vector depicting the radii from which metrics will be calculated.
If NULL, all radii will be considered.
classes
List containing the classes or classes names from which metrics will be calculated.
If NULL, all classes will be considered. See Details.
level, metric, name, type, what
Arguments passed to landscapemetrics::calculate_lsm(),
which define which metrics will be calculated. See Details.
report_absences
Logical. If TRUE (default), intersections with absences of particular
classes will be returned in the final data.frame. See Details.
absence_values
A list depicting which value for each class-level metric should be printed
if report_absences = TRUE. See Details.
ext_calc
A list containing vectors, each one of length equal to 2 or more: the first element of the vector
with the identification number of the extra raster layer defined in x, and next elements with a string with
the name of the function to be applied to the defined raster. See Details.
na.exclude
Logical. Whether to exclude (default) or not the NA values when performing
extra calculations to extra raster layers. Only applies if ext_calc is not NULL. See Details.
coords
Logical. If TRUE, the coordinates of the points will be returned in the data.frame
containing the values of the required metrics. Default FALSE.
update
An object of class 'MultiLandMetrics', if it is intended to be updated with
new or updated metrics data. See Details.
output
Either "MLM" (default) to output an object of class 'MultiLandMetrics' or "data" to output
only the data.frame with metric values.
progress
Logical. If TRUE (default), progress of calculations will be printed.
...
Other arguments passed to landscapemetrics::calculate_lsm(). See Details.
Details
Calculates landscape metrics from an object of class MultiLand
created with mland(). The function allows to define which metrics will be calculated in the
form defined by the function landscapemetrics::calculate_lsm() from package landscapemetrics, by
specifying one or more of the following arguments:
level: level of metrics. Either "patch", "class" or "landscape" (or vector with combination).
metric: abbreviation of metrics (e.g. "area").
name: full name of metrics (e.g. "core area").
type: type according to FRAGSTATS grouping (e.g. "aggregation metrics").
what: selected level of metrics: either "patch", "class" or "landscape". It is also possible to
specify functions as a vector of strings, e.g. what = c("lsm_c_ca", "lsm_l_ta").
Available metrics can be seen in metrics_list() and in the associated documentation of package
landscapemetrics.
mland_metrics() also allows to define some other parameters that filter how metrics are calculated,
by defining the raster layers, points, radii and classes to be taken into account.
If report_absences = TRUE (default), the function will print values of class-level metrics
from classes that are not present in particular landscapes, as a distinct row in the final
data.frame. This is particularly useful for certain class-level metrics in which the absence
of the class should be acknowledged, for instance, the percentage of landscape ('pland') for a forest class. For this
metric, a value of 0 (zero) should be printed for those landscapes where the class forest is not present.
By default, if report_absences = TRUE, the function will consider NA as the value
to be declared in the case that the class is absent in the landscape. To declare a different value
for a particular class-level metric, this can be declared inside argument absence_values. If
not NULL, this must be a list with the value that one ore more class-level metric should
have in the case of an absence of a class. For example, in the case of "pland", the argument
should be defined as follows: absence_values = list("pland" = 0). Note that the metric must be
identified with its abbreviation. You can see abbreviations for all available metrics in metrics_list(),
under the column "metric".
If argument points is a character vector,
mland_metrics() assumes that the 'MultiLand' object inputted in argument x was created with
site_ref = TRUE. This is, there is an column/attribute in the points layer with the names for
each distinct point. Therefore, the inputted values in argument points will be taken as these
identification names. Otherwise, if a numeric vector is inputted, these values
will be taken as the automatically generated point ids (created when running mland()).
The user may specify which classes will be considered when calculating the metrics, by
passing this information in the argument classes. Of course, this information only applies for
class-level metrics. The argument must be a list with as many elements as raster layers to be
considered (defined in argument raster, in ascending order: 1, 2, 3, ...). Each element must be a numeric vector
with the classes values (raster values) to be considered, or a character vector with
the names of the classes (if provided when generating x).
Other arguments can be passed to function landscapemetrics::calculate_lsm() through argument
.... These include specific arguments relative to the calculation of particular landscape
metrics. See the documentation of this function for more information.
Extra calculations can be performed through ext_calc. The functions defined here will take
the values of the extra raster layers defined in x as input. For instance, a plausible definition
could be ext_calc = list(1, "mean"), which will take the values from the extra raster layer 1,
and calculate its mean for each landscape. If na.exclude = TRUE (default), NA values will be excluded
from this task.
A previously generated 'MultiLandMetrics' object can be updated with new information regarding
other metrics, probably from other points, radii, raster layers, etc, that haven´t been
calculated in the previous time (or not). In this way, the returned object will be
the object provided in this argument, plus the additions of information about new metrics, and
changes to previously metric calculations. Note that if a particular metric is calculated for a
given raster layer, points, radii and or class, that were previously generated in the object
provided in update, the information of these metrics from the latter will be overwritten. Also
note that if in the previous 'MultiLandMetrics' object report_absences was TRUE for a given
set of metrics and other parameters (e.g. points, radii, raster layers, etc.), and in the new call
report_absences is FALSE (for the same set of other parameters), the rows depicting landscapes
with empty classes from the previous call will be mantained. If the intention is the removal of these rows,
the user should create a fresh new 'MultiLandMetrics' from scratch.
Value
If output = "MLM", an object of class 'MultiLandMetrics' will be returned. This object
can then be passed to functions metrics_corr(), metrics_plots, metrics_filter(), metrics_gradient()
and metrics_bind(). See
?MultiLandMetrics for more information regarding the content of this object. Otherwise,
if output = "data", only a data.frame with the calculated metrics will be returned.
See Also
metrics_corr(), metrics_plots(), metrics_filter(), metrics_gradient(), metrics_bind()
Examples
# Loads a 'MultiLand' object
ernesdesign <- system.file("extdata", "ernesdesign.zip", package = "multilandr")
ernesdesign <- mland_load(ernesdesign)
# Creates a 'MultiLandMetrics' object. It will calculate the "percentage of landscape"
# ("pland") and "edge density" ("ed") for all classes. Note that an absence value
# for each metric is declared, as the absence of a class for these metrics should be
# acknowledged as a 0 (percentage of zero and zero patches).
ed_metrics <- mland_metrics(ernesdesign, level = "class", metric = c("pland", "ed"),
absence_values = list("pland" = 0))
# Returns data.frame with the values of all metrics for each landscape
head(ed_metrics@data)
# Shows which metrics were calculated and are contained in the data.frame
ed_metrics@metrics
# If output = "data", only the data.frame will be returned
data <- mland_metrics(ernesdesign, level = "class", metric = "pland",
classes = c("Forest", "Crops"),
absence_values = list("pland" = 0),
output = "data")
# Calculate landscape metrics plus extra calculations for extra rasterlayer 1,
# the mean value, and a user defined function, which is the mean divided
# standard deviation.
# User-defined function
mean_sd <- function(x){ mean(x)/sd(x) }
ed_metrics2 <- mland_metrics(ernesdesign, level = "class",
metric = c("pland", "ed"),
absence_values = list("pland" = 0),
ext_calc = list(c(1, "mean"), c(1, "mean_sd")))
# We can calculate metrics for extra raster layers only
ed_metrics3 <- mland_metrics(ernesdesign, ext_calc = list(c(1, "mean", "mean_sd")))
# If metrics of different levels must be calculated, a better approach is to declare
# them inside the argument 'what', by naming the function associated with the metric.
# Also in this case, only the landscapes with a radius of 5000 m are considered.
# A list of available metrics with its names, abbreviations and function names can
# be seen in metrics_list() and in the documentation of the package landscapemetrics.
ed_metrics4 <- mland_metrics(ernesdesign,
what = c("lsm_c_area_mn", "lsm_l_ed", "lsm_l_shdi"),
radii = 5000)
# Calculates patch-level metrics of a particular landscape
ed_patchs <- mland_metrics(ernesdesign, points = "Algarrobo",
level = "patch", class = "Forest",
radii = 1000)
phuais/multilandR documentation built on Feb. 21, 2025, 7:52 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
View source: R/mland_metrics.R
| mland_metrics | R Documentation |
Calculates landscape metrics
Description
Calculates landscape metrics of patch, class and/or landscape level via the package
landscapemetrics and user-defined functions from an object of class 'MultiLand'.
Usage
mland_metrics(
x,
raster = NULL,
points = NULL,
radii = NULL,
classes = NULL,
level = NULL,
metric = NULL,
name = NULL,
type = NULL,
what = NULL,
report_absences = TRUE,
absence_values = NULL,
ext_calc = NULL,
na.exclude = TRUE,
coords = FALSE,
update = NULL,
output = "MLM",
progress = TRUE,
...
)
Arguments
x |
An object of class 'Multiland' generated with |
raster |
Vector depicting the raster layers of |
points |
Numeric or character vector with the points from which metrics will be calculated. If NULL, all points will be considered. See Details. |
radii |
Numeric vector depicting the radii from which metrics will be calculated. If NULL, all radii will be considered. |
classes |
List containing the classes or classes names from which metrics will be calculated. If NULL, all classes will be considered. See Details. |
level, metric, name, type, what |
Arguments passed to |
report_absences |
Logical. If TRUE (default), intersections with absences of particular classes will be returned in the final data.frame. See Details. |
absence_values |
A list depicting which value for each class-level metric should be printed
if |
ext_calc |
A list containing vectors, each one of length equal to 2 or more: the first element of the vector
with the identification number of the extra raster layer defined in |
na.exclude |
Logical. Whether to exclude (default) or not the NA values when performing
extra calculations to extra raster layers. Only applies if |
coords |
Logical. If TRUE, the coordinates of the points will be returned in the data.frame containing the values of the required metrics. Default FALSE. |
update |
An object of class 'MultiLandMetrics', if it is intended to be updated with new or updated metrics data. See Details. |
output |
Either "MLM" (default) to output an object of class 'MultiLandMetrics' or "data" to output only the data.frame with metric values. |
progress |
Logical. If TRUE (default), progress of calculations will be printed. |
... |
Other arguments passed to |
Details
Calculates landscape metrics from an object of class MultiLand
created with mland(). The function allows to define which metrics will be calculated in the
form defined by the function landscapemetrics::calculate_lsm() from package landscapemetrics, by
specifying one or more of the following arguments:
level: level of metrics. Either "patch", "class" or "landscape" (or vector with combination).
metric: abbreviation of metrics (e.g. "area").
name: full name of metrics (e.g. "core area").
type: type according to FRAGSTATS grouping (e.g. "aggregation metrics").
what: selected level of metrics: either "patch", "class" or "landscape". It is also possible to specify functions as a vector of strings, e.g. what = c("lsm_c_ca", "lsm_l_ta").
Available metrics can be seen in metrics_list() and in the associated documentation of package
landscapemetrics.
mland_metrics() also allows to define some other parameters that filter how metrics are calculated,
by defining the raster layers, points, radii and classes to be taken into account.
If report_absences = TRUE (default), the function will print values of class-level metrics
from classes that are not present in particular landscapes, as a distinct row in the final
data.frame. This is particularly useful for certain class-level metrics in which the absence
of the class should be acknowledged, for instance, the percentage of landscape ('pland') for a forest class. For this
metric, a value of 0 (zero) should be printed for those landscapes where the class forest is not present.
By default, if report_absences = TRUE, the function will consider NA as the value
to be declared in the case that the class is absent in the landscape. To declare a different value
for a particular class-level metric, this can be declared inside argument absence_values. If
not NULL, this must be a list with the value that one ore more class-level metric should
have in the case of an absence of a class. For example, in the case of "pland", the argument
should be defined as follows: absence_values = list("pland" = 0). Note that the metric must be
identified with its abbreviation. You can see abbreviations for all available metrics in metrics_list(),
under the column "metric".
If argument points is a character vector,
mland_metrics() assumes that the 'MultiLand' object inputted in argument x was created with
site_ref = TRUE. This is, there is an column/attribute in the points layer with the names for
each distinct point. Therefore, the inputted values in argument points will be taken as these
identification names. Otherwise, if a numeric vector is inputted, these values
will be taken as the automatically generated point ids (created when running mland()).
The user may specify which classes will be considered when calculating the metrics, by
passing this information in the argument classes. Of course, this information only applies for
class-level metrics. The argument must be a list with as many elements as raster layers to be
considered (defined in argument raster, in ascending order: 1, 2, 3, ...). Each element must be a numeric vector
with the classes values (raster values) to be considered, or a character vector with
the names of the classes (if provided when generating x).
Other arguments can be passed to function landscapemetrics::calculate_lsm() through argument
.... These include specific arguments relative to the calculation of particular landscape
metrics. See the documentation of this function for more information.
Extra calculations can be performed through ext_calc. The functions defined here will take
the values of the extra raster layers defined in x as input. For instance, a plausible definition
could be ext_calc = list(1, "mean"), which will take the values from the extra raster layer 1,
and calculate its mean for each landscape. If na.exclude = TRUE (default), NA values will be excluded
from this task.
A previously generated 'MultiLandMetrics' object can be updated with new information regarding
other metrics, probably from other points, radii, raster layers, etc, that haven´t been
calculated in the previous time (or not). In this way, the returned object will be
the object provided in this argument, plus the additions of information about new metrics, and
changes to previously metric calculations. Note that if a particular metric is calculated for a
given raster layer, points, radii and or class, that were previously generated in the object
provided in update, the information of these metrics from the latter will be overwritten. Also
note that if in the previous 'MultiLandMetrics' object report_absences was TRUE for a given
set of metrics and other parameters (e.g. points, radii, raster layers, etc.), and in the new call
report_absences is FALSE (for the same set of other parameters), the rows depicting landscapes
with empty classes from the previous call will be mantained. If the intention is the removal of these rows,
the user should create a fresh new 'MultiLandMetrics' from scratch.
Value
If output = "MLM", an object of class 'MultiLandMetrics' will be returned. This object
can then be passed to functions metrics_corr(), metrics_plots, metrics_filter(), metrics_gradient()
and metrics_bind(). See
?MultiLandMetrics for more information regarding the content of this object. Otherwise,
if output = "data", only a data.frame with the calculated metrics will be returned.
See Also
metrics_corr(), metrics_plots(), metrics_filter(), metrics_gradient(), metrics_bind()
Examples
# Loads a 'MultiLand' object
ernesdesign <- system.file("extdata", "ernesdesign.zip", package = "multilandr")
ernesdesign <- mland_load(ernesdesign)
# Creates a 'MultiLandMetrics' object. It will calculate the "percentage of landscape"
# ("pland") and "edge density" ("ed") for all classes. Note that an absence value
# for each metric is declared, as the absence of a class for these metrics should be
# acknowledged as a 0 (percentage of zero and zero patches).
ed_metrics <- mland_metrics(ernesdesign, level = "class", metric = c("pland", "ed"),
absence_values = list("pland" = 0))
# Returns data.frame with the values of all metrics for each landscape
head(ed_metrics@data)
# Shows which metrics were calculated and are contained in the data.frame
ed_metrics@metrics
# If output = "data", only the data.frame will be returned
data <- mland_metrics(ernesdesign, level = "class", metric = "pland",
classes = c("Forest", "Crops"),
absence_values = list("pland" = 0),
output = "data")
# Calculate landscape metrics plus extra calculations for extra rasterlayer 1,
# the mean value, and a user defined function, which is the mean divided
# standard deviation.
# User-defined function
mean_sd <- function(x){ mean(x)/sd(x) }
ed_metrics2 <- mland_metrics(ernesdesign, level = "class",
metric = c("pland", "ed"),
absence_values = list("pland" = 0),
ext_calc = list(c(1, "mean"), c(1, "mean_sd")))
# We can calculate metrics for extra raster layers only
ed_metrics3 <- mland_metrics(ernesdesign, ext_calc = list(c(1, "mean", "mean_sd")))
# If metrics of different levels must be calculated, a better approach is to declare
# them inside the argument 'what', by naming the function associated with the metric.
# Also in this case, only the landscapes with a radius of 5000 m are considered.
# A list of available metrics with its names, abbreviations and function names can
# be seen in metrics_list() and in the documentation of the package landscapemetrics.
ed_metrics4 <- mland_metrics(ernesdesign,
what = c("lsm_c_area_mn", "lsm_l_ed", "lsm_l_shdi"),
radii = 5000)
# Calculates patch-level metrics of a particular landscape
ed_patchs <- mland_metrics(ernesdesign, points = "Algarrobo",
level = "patch", class = "Forest",
radii = 1000)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.