Return the GRTSmaster_habitats data source or a 10-layered variant as a SpatRaster object

Source: R/GRTSmh.R

By default, the GRTSmaster_habitats data source is returned as a single-layered SpatRaster object with decimal integer ranking numbers as values. If brick = TRUE, a ten-layered SpatRaster is returned (data source GRTSmh_brick; resolution 32 m) with the decimal integer ranking numbers of 10 hierarchical levels of the GRTS cell addresses, including the one from GRTSmaster_habitats (with GRTS cell addresses at the resolution level). The coordinate reference system is 'BD72 / Belgian Lambert 72' (EPSG-code 31370).

read_GRTSmh(
  file = file.path(locate_n2khab_data(),
    c("10_raw/GRTSmaster_habitats/GRTSmaster_habitats.tif",
    "20_processed/GRTSmh_brick/GRTSmh_brick.tif")),
  brick = FALSE
)

Arguments

file

The absolute or relative file path of the data source. The default follows the data management advice in the vignette on data storage (run vignette("v020_datastorage")). It uses the first n2khab_data folder that is found when sequentially climbing up 0 to 10 levels in the file system hierarchy, starting from the working directory.
brick

Logical; determines whether the single- or ten-layered SpatRaster is returned. See the Details section.

Value

A single- or a ten-layered SpatRaster object, always with 21041043 cells.

If the package is configured to use the raster package (see n2khab_options()), a RasterLayer is returned if brick = FALSE and a RasterBrick if brick = TRUE.

Details

The data source GRTSmaster_habitats, provided and documented in Zenodo, is a monolayered GeoTIFF file covering the whole of Flanders and the Brussels Capital Region at a resolution of 32 m. Its values are unique decimal integer ranking numbers from the GRTS algorithm applied to the Flemish and Brussels area. Beware that not all GRTS ranking numbers are present in the data source, as the original GRTS raster has been clipped with the Flemish outer borders (i.e., not excluding the Brussels Capital Region).

The GRTS algorithm uses a quadrant-recursive, hierarchically randomized function that maps the unit square to the unit interval, resulting in a base-4 GRTS address for each location (see read_GRTSmh_base4frac). The ranking numbers in GRTSmaster_habitats are base-10 numbers and follow the reverse hierarchical order: each consecutive subset of ranking numbers corresponds to a spatially balanced sample of locations. Hence, it allows dynamical sample sizes. More information on the GRTS algorithm can be found in Stevens & Olsen (2003, 2004) and in the GRTS and spsurvey packages.

Depending on the value of the brick argument, the function either returns the GRTSmaster_habitats data source as a single-layered SpatRaster (brick = FALSE), or (brick = TRUE) returns the GRTSmh_brick data source as a ten-layered SpatRaster (resolution 32 m) with the decimal integer ranking numbers of 10 hierarchical levels of the GRTS cell addresses, including the one from GRTSmaster_habitats (with GRTS cell addresses at the resolution level). The GRTSmh_brick data source is a processed dataset (ten-layered GeoTIFF), available at Zenodo, and can only be returned by the function when it is already present as a file. See R-code in the n2khab-preprocessing repository for its creation from the GRTSmaster_habitats data source.

Both GeoTIFFs (GRTSmaster_habitats, GRTSmh_brick) use the INT4S datatype.

The higher-level ranking numbers of the ten-layered variant allow spatially balanced samples at lower spatial resolution than that of 32 m, and can also be used for aggregation purposes. The provided hierarchical levels correspond to the resolutions vector 32 * 2^(0:9) (minimum: 32 meters, maximum: 16384 meters), with the corresponding SpatRaster layers named as level0 to level9.

References

Stevens D.L. & Olsen A.R. (2003). Variance estimation for spatially balanced samples of environmental resources. Environmetrics 14 (6): 593–610. doi:10.1002/env.606 .

Stevens D.L. & Olsen A.R. (2004). Spatially Balanced Sampling of Natural Resources. Journal of the American Statistical Association 99 (465): 262–278. doi:10.1198/016214504000000250 .

See also

Other functions involved in processing the 'GRTSmaster_habitats' data source: convert_base4frac_to_dec(), convert_dec_to_base4frac(), read_GRTSmh_base4frac(), read_GRTSmh_diffres()

Examples

if (FALSE) {
# This example supposes that your working directory or a directory up to 10
# levels above has
# the 'n2khab_data' folder AND that the latest version of the
# 'GRTSmaster_habitats' data source is present in the default subdirectory.
# In all other cases, this example won't work but at least you can consider
# what to do.
r <- read_GRTSmh()
r
r10 <- read_GRTSmh(brick = TRUE)
r10
}