Decode (unpack) a bitfield

This function takes an integer bitfield and the registry used to build it upstream to decode it into bit representation and thereby unpack the data stored in the bitfield.

bf_decode(x, registry, flags = NULL, envir = NULL, verbose = TRUE)

Arguments

x

integer table or raster of the bitfield. For registries with a SpatRaster template, x should be a SpatRaster. For registries with a data.frame template, x should be a data.frame.

registry

registry(1)
the registry that should be used to decode the bitfield.

flags

character(.)
the name(s) of flags to extract from this bitfield; leave at NULL to extract the full bitfield.

envir

environment(1)
optional environment to store decoded flags as individual objects. If NULL (default), returns results as a list or SpatRaster. Use .GlobalEnv to store flags directly in the workspace.

verbose

logical(1)
whether or not to print the registry legend.

Value

Depending on the registry template type and envir parameter: If envir is NULL, returns a named list with decoded values for table templates, or a multi-layer SpatRaster for raster templates. If envir is specified, stores decoded flags as individual objects in that environment and returns invisible(NULL).

Examples

# build registry
reg <- bf_registry(name = "testBF", description = "test bitfield",
                   template = bf_tbl)
reg <- bf_map(protocol = "na", data = bf_tbl, registry = reg, x = commodity)
reg <- bf_map(protocol = "matches", data = bf_tbl, registry = reg,
              x = commodity, set = c("soybean", "maize"), na.val = FALSE)
reg
#>   type  data.frame
#>   width 2
#>   flags 2  -|-
#> 
#>   pos encoding name    col
#>   1   0.0.1/0  na      commodity
#>   2   0.0.1/0  matches commodity

# encode the flags into a bitfield
field <- bf_encode(registry = reg)
field
#> # A tibble: 9 × 1
#>   bf_int1
#>     <int>
#> 1       1
#> 2       1
#> 3       1
#> 4       2
#> 5       0
#> 6       1
#> 7       1
#> 8       1
#> 9       1

# decode (somewhere downstream) - returns a named list
decoded <- bf_decode(x = field, registry = reg)
#> # A tibble: 2 × 3
#>     pos name              desc                                                  
#>   <int> <chr>             <chr>                                                 
#> 1     1 na_commodity      'commodity' contains NA-values.                       
#> 2     2 matches_commodity The 'commodity' values match the set 'soybean, maize'.
decoded$na_commodity
#> [1] 0 0 0 1 0 0 0 0 0
decoded$matches_commodity
#> [1] 1 1 1 0 0 1 1 1 1

# alternatively, store directly in global environment
bf_decode(x = field, registry = reg, envir = .GlobalEnv, verbose = FALSE)
na_commodity
#> [1] 0 0 0 1 0 0 0 0 0
matches_commodity
#> [1] 1 1 1 0 0 1 1 1 1

# with raster data
library(terra)
bf_rst <- rast(nrows = 3, ncols = 3, vals = bf_tbl$commodity, names = "commodity")
bf_rst$yield <- rast(nrows = 3, ncols = 3, vals = bf_tbl$yield)

reg <- bf_registry(name = "testBF", description = "raster bitfield",
                   template = bf_rst)
reg <- bf_map(protocol = "na", data = bf_rst, registry = reg, x = commodity)
field <- bf_encode(registry = reg)
#> use `writeRaster(x, filename, datatype = 'INT1U', gdal = 'COMPRESS=DEFLATE')` to preserve bitfield values when saving to disk

# decode back to multi-layer raster
decoded <- bf_decode(x = field, registry = reg, verbose = FALSE)
decoded  # SpatRaster with one layer per flag
#> class       : SpatRaster 
#> size        : 3, 3, 1  (nrow, ncol, nlyr)
#> resolution  : 120, 60  (x, y)
#> extent      : -180, 180, -90, 90  (xmin, xmax, ymin, ymax)
#> coord. ref. : lon/lat WGS 84 (CRS84) (OGC:CRS84) 
#> source(s)   : memory
#> name        : na_commodity 
#> min value   :            0 
#> max value   :            1