vignettes/v030_GRTSmh.Rmd
v030_GRTSmh.RmdGeneral note: the below vignette contains frozen output of 29 May 2019. This makes it possible to build the package with vignettes without access to the data sources.
With this vignette, you get acquainted with three functions that usually return a RasterLayer or a RasterBrick:
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. 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 and Olsen
(2003, 2004) and in the GRTS and spsurvey
packages.
The following data sources are available:
GRTSmaster_habitats, discussed
above and available at Zenodo
GRTSmh_brick (Zenodo-link):
10-layered GeoTIFF with the decimal integer ranking numbers of 10
hierarchical levels (0 - 9) of the GRTS cell addresses, including the
one from GRTSmaster_habitats (i.e. level 0; for more
details see the read_GRTSmh() documentation)GRTSmh_diffres (Zenodo-link): file
collection composed of nine monolayered GeoTIFF files plus a GeoPackage
with six polygon layers. They provide the hierarchical levels 1 to 9 of
the GRTSmh_brick data source at the corresponding spatial
resolution, i.e. at lower resolutions than
GRTSmaster_habitats (for more details see the
read_GRTSmh_diffres() documentation)GRTSmh_base4frac (Zenodo-link): is like
a mirror to GRTSmaster_habitats, holding the ranking
numbers as base 4 fractions. These are numbers like
0.3213210231312, representing the reverse-ordered base-4
GRTS address behind the decimal mark: the digit for level 0 is 2, for
level 1 it is 1, …, for level 13 it is 3). Hence, it is a direct
representation of the hierarchical GRTS addresses, allowing the
derivation of other datasets. More details are in the
read_GRTSmh_base4frac() documentation.For more information on data storage and locations, see
vignette("v020_datastorage").
In the below R code, it is supposed that a n2khab_data
folder is present in the current directory or up to 10 levels higher.
See the vignette("v020_datastorage") for more
information.
read_GRTSmh() by default returns the
GRTSmaster_habitats dataset:
read_GRTSmh()
#> class : RasterLayer
#> dimensions : 2843, 7401, 21041043 (nrow, ncol, ncell)
#> resolution : 32, 32 (x, y)
#> extent : 22029.59, 258861.6, 153054.1, 244030.1 (xmin, xmax, ymin, ymax)
#> crs : +proj=lcc +lat_1=51.16666723333333 +lat_2=49.8333339 +lat_0=90 +lon_0=4.367486666666666 +x_0=150000.013 +y_0=5400088.438 +ellps=intl +towgs84=-106.8686,52.2978,-103.7239,0.3366,-0.457,1.8422,-1.2747 +units=m +no_defs
#> source : [...]/n2khab_data/10_raw/GRTSmaster_habitats/GRTSmaster_habitats.tif
#> names : GRTSmaster_habitats
#> values : 1, 67108857 (min, max)With the argument brick = TRUE however, you will get the
GRTSmh_brick data source,
i.e. GRTSmaster_habitats plus 9 extra layers:
read_GRTSmh(brick = TRUE)
#> class : RasterBrick
#> dimensions : 2843, 7401, 21041043, 10 (nrow, ncol, ncell, nlayers)
#> resolution : 32, 32 (x, y)
#> extent : 22029.59, 258861.6, 153054.1, 244030.1 (xmin, xmax, ymin, ymax)
#> crs : +proj=lcc +lat_1=51.16666723333333 +lat_2=49.8333339 +lat_0=90 +lon_0=4.367486666666666 +x_0=150000.013 +y_0=5400088.438 +ellps=intl +towgs84=-106.8686,52.2978,-103.7239,0.3366,-0.457,1.8422,-1.2747 +units=m +no_defs
#> source : [...]/n2khab_data/20_processed/GRTSmh_brick/GRTSmh_brick.tif
#> names : level0, level1, level2, level3, level4, level5, level6, level7, level8, level9
#> min values : 1, 1, 1, 1, 1, 1, 1, 1, 1, 1
#> max values : 67108857, 16777209, 4194297, 1048569, 262137, 65529, 16377, 4089, 1017, 253The higher-level ranking numbers of the RasterBrick 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 resolution vector 32 * 2^(0:9) (minimum:
32 meters, maximum: 16384 meters), with the corresponding RasterBrick
layers named as level0 to level9.
read_GRTSmh_diffres() by default returns one RasterLayer
from the GRTSmh_diffres data source, i.e. with the GRTS
ranking numbers of the user-specified hierarchical level. This is done
at the corresponding spatial resolution of the GRTS algorithm,
which is the fundamental distinction from
read_GRTSmh(brick = TRUE).
The resolutions of each level are the following (in meters):
| level | resolution |
|---|---|
| 1 | 64 |
| 2 | 128 |
| 3 | 256 |
| 4 | 512 |
| 5 | 1024 |
| 6 | 2048 |
| 7 | 4096 |
| 8 | 8192 |
| 9 | 16384 |
An example with level 5:
read_GRTSmh_diffres(level = 5)
#> class : RasterLayer
#> dimensions : 89, 232, 20648 (nrow, ncol, ncell)
#> resolution : 1024, 1024 (x, y)
#> extent : 22030, 259598, 153054, 244190 (xmin, xmax, ymin, ymax)
#> crs : +proj=lcc +lat_1=51.16666723333333 +lat_2=49.8333339 +lat_0=90 +lon_0=4.367486666666666 +x_0=150000.013 +y_0=5400088.438 +ellps=intl +towgs84=-106.8686,52.2978,-103.7239,0.3366,-0.457,1.8422,-1.2747 +units=m +no_defs
#> source : [...]/n2khab_data/20_processed/GRTSmh_diffres/GRTSmh_diffres.5.tif
#> names : level5
#> values : 1, 65529 (min, max)Alternatively, a dissolved, polygonized variant of the corresponding
GRTSmh_brick level can be returned as an sf
object. In order not to inflate the data source, this was only made
available for levels 4 to 9.
read_GRTSmh_diffres(level = 5, polygon = TRUE)
#> Simple feature collection with 13791 features and 1 field
#> geometry type: POLYGON
#> dimension: XY
#> bbox: xmin: 22029.59 ymin: 153054.1 xmax: 258861.6 ymax: 244030.1
#> epsg (SRID): 31370
#> proj4string: +proj=lcc +lat_1=51.16666723333333 +lat_2=49.8333339 +lat_0=90 +lon_0=4.367486666666666 +x_0=150000.013 +y_0=5400088.438 +ellps=intl +towgs84=-106.8686,52.2978,-103.7239,0.3366,-0.457,1.8422,-1.2747 +units=m +no_defs
#> First 10 features:
#> value geom
#> 1 23390 POLYGON ((178093.6 244030.1...
#> 2 56158 POLYGON ((178701.6 243646.1...
#> 3 23134 POLYGON ((177581.6 243870.1...
#> 4 60254 POLYGON ((179757.6 243454.1...
#> 5 6750 POLYGON ((176621.6 243390.1...
#> 6 60254 POLYGON ((180333.6 243230.1...
#> 7 58718 POLYGON ((176653.6 243166.1...
#> 8 52318 POLYGON ((177677.6 243166.1...
#> 9 3166 POLYGON ((178701.6 243166.1...
#> 10 15454 POLYGON ((179725.6 243166.1...Its use is just to return the base-4-fraction-converted
GRTSmaster_habitats as a RasterLayer:
options(scipen = 999, digits = 15)
read_GRTSmh_base4frac()
#> class : RasterLayer
#> dimensions : 2843, 7401, 21041043 (nrow, ncol, ncell)
#> resolution : 32, 32 (x, y)
#> extent : 22029.591973471, 258861.591973471, 153054.113583292, 244030.113583292 (xmin, xmax, ymin, ymax)
#> crs : +proj=lcc +lat_1=51.16666723333333 +lat_2=49.8333339 +lat_0=90 +lon_0=4.367486666666666 +x_0=150000.013 +y_0=5400088.438 +ellps=intl +towgs84=-106.8686,52.2978,-103.7239,0.3366,-0.457,1.8422,-1.2747 +units=m +no_defs
#> source : [...]/n2khab_data/20_processed/GRTSmh_base4frac/GRTSmh_base4frac.tif
#> names : GRTSmh_base4frac
#> values : 0.0000000000001, 0.3333333333321 (min, max)Note that the used options are necessary when treating these base-4-fraction GRTS addresses as characters; otherwise scientific notations will be used.
Also, be warned that R does not actually regard the values as base 4, but as base 10. 1
So, what really matters is only the notation with many
digits, to be regarded as a base 4 fraction (and hence,
handling it as a character in conversions is often necessary). The
n2khab package also exports a
convert_dec_to_base4frac() and a
convert_base4frac_to_dec() function in its namespace. These
functions will be relevant if you need to do such conversions yourself,
and they are used in the code to generate the processed data sources.↩︎