Converts base 4 fractions, representing the full GRTS addresses from the
raster data source `GRTSmaster_habitats`

into decimal (i.e. base 10)
integer values.
Before the actual conversion happens, leading digits from the full GRTS
address can be discarded according to the `level`

specified by the user.
Hence, the result may correspond to the GRTS ranking at a lower spatial
resolution.

convert_base4frac_to_dec(x, level)

## Arguments

x |
A scalar or vector of base 4 fractions, originating from the
`GRTSmaster_habitats` data source. |

level |
The number of leading digits to discard from the GRTS base 4
address, i.e. from the '`xxx...` ' digits behind the decimal mark in
the '`0.xxxxxxxxxxxxx` ' base 4 fractions.
Only values from `0` (maintain full address) to `12` (only return
last digit) are sensible, as the GRTS addresses are `13` digits long. |

## Value

The corresponding decimal (i.e. base 10) integer scalar or vector.

## Details

For example, the base 4 fraction `0.0000000000100`

is converted into decimal integer `16`

(`= 4^2`

) as long as the
`level`

argument is `10`

or lower (if not, it will be `0`

) and
`0.0000000000101`

is converted into either `17`

(
`level <= 10`

) or `1`

(if `level`

is `11`

or `12`

).

Long base 4 fractions seem to be handled and stored easier than long
(base 4) integers.
This approach follows the one of Stevens & Olsen (2004) to represent
the reverse hierarchical order in a GRTS sample.

The function works on a vector and retains `NA`

values.
As such, it can be used in `raster::calc()`

.
When writing such a raster to a file, it is recommended to use the
`INT4U`

data type (see `dataType`

).

## References

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

## Examples

oldoption <- options(list(digits = 15, scipen = 999))
# one scalar:
convert_base4frac_to_dec(0.1010101010101, level = 0)
#> [1] 17895697
# vector, level 0:
convert_base4frac_to_dec(c(NA, 0.1010101010101), level = 0)
#> [1] NA 17895697
# vector, level 5:
convert_base4frac_to_dec(c(NA, 0.1010101010101), level = 5)
#> [1] NA 4369
# same vector, all sensible levels computed:
sapply(0:12, function(i) {
convert_base4frac_to_dec(c(NA, 0.1010101010101),
level = i
)
})
#> [,1] [,2] [,3] [,4] [,5] [,6] [,7] [,8] [,9] [,10] [,11] [,12]
#> [1,] NA NA NA NA NA NA NA NA NA NA NA NA
#> [2,] 17895697 1118481 1118481 69905 69905 4369 4369 273 273 17 17 1
#> [,13]
#> [1,] NA
#> [2,] 1
options(oldoption)