measure: Measure gridded objects
In EhrmannS/rasterTools: Obtain and process earth observation data

Description Usage Arguments Details Value Examples

Landscape metrics typically quantify spatial patterns of 2D lattices, such as maps of landscapes, artificial (spatial) patterns or even photographs.

1 2	measure(input = NULL, with = NULL, background = NA, simplify = TRUE)

`input`	[`RasterLayer(1)` \| `list(.)` thereof] an object or a named list of objects, which should be measured. Typically retrieved via `obtain`, and potentially processed with `modify`, but can also be assembled "by hand".
`with`	[`character(.)`] algorithm in which the operators (landscape metrics) to measure spatial patterns are specified; see Examples.
`background`	[`numeric(.)`] a set of values that are supposed to be regarded as background, i.e. that should not be considered for evaluating the equation(s).
`simplify`	[`logical(1)`] should a "nice looking" output be created, where the resulting values are associated to the correct ids (`TRUE`, default), or should the raw values be returned (`FALSE`)?

A landscape metric can be generic or derived. In the first case the metric is a list that includes the operator name and its arguments. In the latter case these generic metrics are considered as terms, while the derived metric is given as its mathematical equation, where the terms are related to each other. You can find the equations for landscape metrics in the vignette with vignette("landscape_metrics", package = "rasterTools")

The following operators for generic metrics are defined:

mAdjacency: Determine the adjacency matrix of a raster.
mArea: Calculate the area of objects in a raster.
mNumber: Count the number of objects in a raster.
mPerimeter: Calculate the length of the boundary of objects in a raster.
mValues: Summarise the values of objects in a raster.

depending on the employed metric, but typically a data.frame.

input <- rtRasters$categorical

# calculate generic metrics 'area per class' and 'area per landscape', 'obj' does
# not need to be specified per operator in the algorithm, as 'measure' assigns it.
myMetrics <- list(a_c = list(operator = "mArea", scale = "class"),
                  a_l = list(operator = "mArea", scale = "landscape"))
(measure(input = input, with = myMetrics))

# calculate 'class proportional area' and 'largest patch index'
# 1) define the terms (generic metrics) that are needed to compute the metrics
# 2) define the equations that are used based on these terms
myMetrics <- list(a_p = list(operator = "mArea", scale = "patch"),
                  a_c = list(operator = "mArea", scale = "class"),
                  a_l = list(operator = "mArea", scale = "landscape"),
                  mCPA = "a_c / a_l * 100",
                  mLPI = "max(a_p) / a_l * 100")
(measure(input = input, with = myMetrics, simplify = FALSE))

# however, in the above example patches are derived per class, which might
# not make sense ecologically, or be at best arbitrary. Instead we might
# want to treat all forest, irrespective of deciduous or coniferous as one
# patch.
substituted <- rSubstitute(input, old = c(41:47), new = list(id = 40))
visualise(raster::stack(input, substituted))

# now we can get perhaps more reasonable data in a simplified table
(measure(input = substituted, with = myMetrics))

# To come: set of spatial operations that enables more complex metrics
# derive 'Disjunct Cores Density', which is a rather complex metric