mland: Generates object of class 'MultiLand'
In phuais/multilandR: multilandr: Landscape Analysis at Multiple Spatial Scales
mland R Documentation
Generates object of class 'MultiLand'
Description
Creates an object of class 'MultiLand', which is the
main object to be used by other functions
of the package to generate plots, calculate landscape metrics and perform other relevant
analyses.
Usage
mland(
points,
raster = NULL,
radii,
classnames = NULL,
site_ref = NULL,
bufftype = "round",
segs = 20,
ext_raster = NULL,
layer_names = NULL,
onthefly = FALSE,
progress = TRUE
)
Arguments
points
An object of class 'SpatVector', 'SpatialPoints' or 'SpatialPointsDataFrame', or a string with the
path to a shapefile.
raster, ext_raster
An object of class 'SpatRaster', 'RasterLayer', 'RasterStack', 'RasterBrick',
or a list of raster objects (any of 'RasterLayer' or 'SpatRaster').
radii
A numeric vector with the radii (in meters) from which buffers will be created.
classnames
A list matching each raster value with a class name. See Details.
site_ref
A string with the name of the column containing the identity of the sites in
points layer data. See Details.
bufftype
Type of buffer to be created: "round" for circular buffers (default) or "square".
segs
Number of line segments to use to approximate a quarter circle during buffer generation. Only valid when
bufftype = "round". Default is 20.
layer_names
A character vector with the names of the rasterlayers provided in raster
and ext_raster. See Details.
onthefly
Logical. If FALSE (default) intersections between buffers and rasterlayers will
be calculated. If TRUE, only buffers will be generated. See Details.
progress
Logical. If TRUE (default), progress of the analysis will be printed.
Details
mland() is the primary function of the package. It creates an object of class
'MultiLand' that holds relevant objects and information about points, buffers and intersections
between the latters and rasterlayers.
The function firstly creates buffers with center in the sites defined in points, and size defined by
the values of radii. If each point defined in points has an associated name or id for
ulterior identification, the user should provide the name of the attribute inside points
containing this information, by passing this string through the argument site_ref.
Argument raster must be provided with rasterlayers with discrete values from which different landscape metrics (provided by package landscapemetrics)
could be calculated. Extra rasterlayers can be provided in ext_raster, from which other metrics can be
calculated. For instance, an extra rasterlayer could be one depicting continuous values of slope,
from which a mean value per landscape may be calculated.
If onthefly = FALSE (default), intersections between buffers and rasterlayers defined in
raster and/or ext_raster will be generated. Otherwise, if onthefly = TRUE, only buffers will be generated. The
latter approach may be particularly useful for 'MultiLand' objects with numerous points
(hundreds or thousands), in order to avoid returning an object excessively heavy for memory. If
this is the case, intersections between buffers and rasterlayers will be generated when
required ("on the fly"). For instance, to calculate metrics with metrics().
The names of the provided rasterlayers can be defined in layer_names. If so, this must be
a character vector with as many names (strings) as provided rasterlayers in arguments raster and
ext_raster, in the mentioned order. If there is no need of a name for a particular raster layer, the given element in the vector
should be NA. Definition of these names could be useful when applying other functions of
the package to the object generated here. For instance, to get the name of the rasterlayer
of a particular row of the data.frame with landscape metrics exported by metrics().
Classes names can be associated with each value of the rasterlayers defined in raster, for a
easier future identification. If so, the user must provide a list with as many elements as
rasterlayers defined in raster. If a 'SpatRaster' with multiple layers, a 'RasterStack' or a
'RasterBrick' is provided, the
number of rasterlayers are extracted from these objects. Each element of the list must be a
vector built from concatenated pairs of values, with the value of the raster (the class) in the
first place and the associated class name in the second place. For example, in the case only
one rasterlayer is provided (with four unique values: 1, 2, 3 and 4), a plausible definition
for the argument classnames could be the following:
list(c(1, "Forest", 2, "Crops", 3, "Urban", 4, "Grassland"))
If, for instance, two rasterlayers are provided (with four unique values for the first layer,
and two unique values for the second one), a plausible definition would be:
list(c(1, "Forest", 2, "Crops", 3, "Urban", 4, "Grassland"),
c(1, "Burnt Areas", 2, "Non-burnt Areas"))
Value
An object of class 'MultiLand'. This object can be used to generate useful plots with
mland_plot(), calculate metrics with metrics() and calculate buffer's overlapping with
overlapping(). See ?MultiLand for more details on the content of this object.
See Also
mland_plot(), metrics(), overlapping(), land_points()
Examples
# Loads main raster and extra raster
elchaco <- terra::rast(system.file("extdata", "elchaco.tif", package = "multilandr"))
elchaco_ndvi <- terra::rast(system.file("extdata", "elchaco_ndvi.tif", package = "multilandr"))
# Classes names
cl_names <- c(1, "Forest",
2, "Grassland",
3, "Crops",
4, "Pastures",
5, "Water",
6, "Urban")
# Loads points
elchaco_sites <- terra::vect(system.file("extdata", "elchaco_sites.shp", package = "multilandr"))
# Creates 'MultiLand' object by loading main raster, an extra raster and points.
ernesdesign <- mland(points = elchaco_sites,
raster = elchaco,
radii = seq(1000, 5000, 1000),
classnames = list(cl_names),
site_ref = "name",
ext_raster = elchaco_ndvi,
layer_names = c("landuse", "NDVI"),
segs = 20)
# Returns basic information about the object
ernesdesign
# Returns the classes of each rasterlayer and its names, if initially provided
ernesdesign@classes
## Not run:
# Loads another main raster. Same classes as "elchaco", but a different year.
elchaco2 <- terra::rast(system.file("extdata", "elchaco2.tif", package = "multilandr"))
# Creates 'MultiLand' with two rasterlayers.
ernesdesign2 <- mland(points = elchaco_sites,
raster = list(elchaco, elchaco2),
radii = seq(1000, 5000, 1000),
classnames = list(cl_names, cl_names),
site_ref = "name",
segs = 20)
# Creates the same object but with "onthefly = T". Intersections between
# buffers and rasters will not be generated in this step
ernesdesign3 <- mland(points = elchaco_sites,
raster = list(elchaco, elchaco2),
radii = seq(1000, 5000, 1000),
classnames = list(cl_names, cl_names),
site_ref = "name",
segs = 20,
onthefly = T)
# Creates a MultiLand object with hundreds of points. In this case, these
# points were generated with land_points(), another function from this package. Also,
# "onthefly = TRUE" assures that no intersections between buffers and the raster are
# created in this step.
# Loads points
otf_sites <- terra::vect(system.file("extdata", "otf_sites.shp", package = "multilandr"))
# Creates MultiLand object
otf_design <- mland(points = otf_sites,
raster = elchaco,
radii = 2000,
classnames = list(c(1, "Forest",
2, "Grassland",
3, "Crops",
4, "Pastures",
5, "Water",
6, "Urban")),
onthefly = TRUE,
segs = 20)
## End(Not run)
phuais/multilandR documentation built on Feb. 11, 2024, 9:27 p.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.
| mland | R Documentation |
Generates object of class 'MultiLand'
Description
Creates an object of class 'MultiLand', which is the main object to be used by other functions of the package to generate plots, calculate landscape metrics and perform other relevant analyses.
Usage
mland(
points,
raster = NULL,
radii,
classnames = NULL,
site_ref = NULL,
bufftype = "round",
segs = 20,
ext_raster = NULL,
layer_names = NULL,
onthefly = FALSE,
progress = TRUE
)
Arguments
points |
An object of class 'SpatVector', 'SpatialPoints' or 'SpatialPointsDataFrame', or a string with the path to a shapefile. |
raster, ext_raster |
An object of class 'SpatRaster', 'RasterLayer', 'RasterStack', 'RasterBrick', or a list of raster objects (any of 'RasterLayer' or 'SpatRaster'). |
radii |
A numeric vector with the radii (in meters) from which buffers will be created. |
classnames |
A list matching each raster value with a class name. See Details. |
site_ref |
A string with the name of the column containing the identity of the sites in points layer data. See Details. |
bufftype |
Type of buffer to be created: "round" for circular buffers (default) or "square". |
segs |
Number of line segments to use to approximate a quarter circle during buffer generation. Only valid when
|
layer_names |
A character vector with the names of the rasterlayers provided in |
onthefly |
Logical. If FALSE (default) intersections between buffers and rasterlayers will be calculated. If TRUE, only buffers will be generated. See Details. |
progress |
Logical. If TRUE (default), progress of the analysis will be printed. |
Details
mland() is the primary function of the package. It creates an object of class
'MultiLand' that holds relevant objects and information about points, buffers and intersections
between the latters and rasterlayers.
The function firstly creates buffers with center in the sites defined in points, and size defined by
the values of radii. If each point defined in points has an associated name or id for
ulterior identification, the user should provide the name of the attribute inside points
containing this information, by passing this string through the argument site_ref.
Argument raster must be provided with rasterlayers with discrete values from which different landscape metrics (provided by package landscapemetrics)
could be calculated. Extra rasterlayers can be provided in ext_raster, from which other metrics can be
calculated. For instance, an extra rasterlayer could be one depicting continuous values of slope,
from which a mean value per landscape may be calculated.
If onthefly = FALSE (default), intersections between buffers and rasterlayers defined in
raster and/or ext_raster will be generated. Otherwise, if onthefly = TRUE, only buffers will be generated. The
latter approach may be particularly useful for 'MultiLand' objects with numerous points
(hundreds or thousands), in order to avoid returning an object excessively heavy for memory. If
this is the case, intersections between buffers and rasterlayers will be generated when
required ("on the fly"). For instance, to calculate metrics with metrics().
The names of the provided rasterlayers can be defined in layer_names. If so, this must be
a character vector with as many names (strings) as provided rasterlayers in arguments raster and
ext_raster, in the mentioned order. If there is no need of a name for a particular raster layer, the given element in the vector
should be NA. Definition of these names could be useful when applying other functions of
the package to the object generated here. For instance, to get the name of the rasterlayer
of a particular row of the data.frame with landscape metrics exported by metrics().
Classes names can be associated with each value of the rasterlayers defined in raster, for a
easier future identification. If so, the user must provide a list with as many elements as
rasterlayers defined in raster. If a 'SpatRaster' with multiple layers, a 'RasterStack' or a
'RasterBrick' is provided, the
number of rasterlayers are extracted from these objects. Each element of the list must be a
vector built from concatenated pairs of values, with the value of the raster (the class) in the
first place and the associated class name in the second place. For example, in the case only
one rasterlayer is provided (with four unique values: 1, 2, 3 and 4), a plausible definition
for the argument classnames could be the following:
list(c(1, "Forest", 2, "Crops", 3, "Urban", 4, "Grassland"))
If, for instance, two rasterlayers are provided (with four unique values for the first layer, and two unique values for the second one), a plausible definition would be:
list(c(1, "Forest", 2, "Crops", 3, "Urban", 4, "Grassland"),
c(1, "Burnt Areas", 2, "Non-burnt Areas"))
Value
An object of class 'MultiLand'. This object can be used to generate useful plots with
mland_plot(), calculate metrics with metrics() and calculate buffer's overlapping with
overlapping(). See ?MultiLand for more details on the content of this object.
See Also
mland_plot(), metrics(), overlapping(), land_points()
Examples
# Loads main raster and extra raster
elchaco <- terra::rast(system.file("extdata", "elchaco.tif", package = "multilandr"))
elchaco_ndvi <- terra::rast(system.file("extdata", "elchaco_ndvi.tif", package = "multilandr"))
# Classes names
cl_names <- c(1, "Forest",
2, "Grassland",
3, "Crops",
4, "Pastures",
5, "Water",
6, "Urban")
# Loads points
elchaco_sites <- terra::vect(system.file("extdata", "elchaco_sites.shp", package = "multilandr"))
# Creates 'MultiLand' object by loading main raster, an extra raster and points.
ernesdesign <- mland(points = elchaco_sites,
raster = elchaco,
radii = seq(1000, 5000, 1000),
classnames = list(cl_names),
site_ref = "name",
ext_raster = elchaco_ndvi,
layer_names = c("landuse", "NDVI"),
segs = 20)
# Returns basic information about the object
ernesdesign
# Returns the classes of each rasterlayer and its names, if initially provided
ernesdesign@classes
## Not run:
# Loads another main raster. Same classes as "elchaco", but a different year.
elchaco2 <- terra::rast(system.file("extdata", "elchaco2.tif", package = "multilandr"))
# Creates 'MultiLand' with two rasterlayers.
ernesdesign2 <- mland(points = elchaco_sites,
raster = list(elchaco, elchaco2),
radii = seq(1000, 5000, 1000),
classnames = list(cl_names, cl_names),
site_ref = "name",
segs = 20)
# Creates the same object but with "onthefly = T". Intersections between
# buffers and rasters will not be generated in this step
ernesdesign3 <- mland(points = elchaco_sites,
raster = list(elchaco, elchaco2),
radii = seq(1000, 5000, 1000),
classnames = list(cl_names, cl_names),
site_ref = "name",
segs = 20,
onthefly = T)
# Creates a MultiLand object with hundreds of points. In this case, these
# points were generated with land_points(), another function from this package. Also,
# "onthefly = TRUE" assures that no intersections between buffers and the raster are
# created in this step.
# Loads points
otf_sites <- terra::vect(system.file("extdata", "otf_sites.shp", package = "multilandr"))
# Creates MultiLand object
otf_design <- mland(points = otf_sites,
raster = elchaco,
radii = 2000,
classnames = list(c(1, "Forest",
2, "Grassland",
3, "Crops",
4, "Pastures",
5, "Water",
6, "Urban")),
onthefly = TRUE,
segs = 20)
## End(Not run)
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.