This function maps values from a dataset to bit flags that can be encoded into a bitfield.
bf_map(
protocol,
data,
registry,
...,
name = NULL,
pos = NULL,
na.val = NULL,
description = NULL
)
character(1)
the protocol based on which
the flag should be determined, see Details.
the object to build bit flags for.
registry(1)
an already defined bitfield
registry.
the protocol-specific arguments for building a bit flag, see Details.
character(1)
optional flag-name.
integerish(.)
optional position(s) in the bitfield
that should be set.
value, of the same encoding type as the flag, that needs to be
given, if the test for this flag results in NA
s.
character(.)
optional description that
should be used instead of the default protocol-specific description. This
description is used in the registry legend, so it must have as many entries
as there will be flags (two for a binary flag, as many as there are cases
for a enumeration flag and one for integer or numeric flags).
an (updated) object of class 'registry' with the additional flag defined here.
protocol
can either be the name of an internal item (see
bf_pcl
), a newly built local protocol
(bf_protocol
) or one that has been imported from the bitfield
community standards repo on github (bf_standards
). Any
protocol
has specific arguments, typically at least the name of the
column containing the values to test (x
). To make this function as
general as possible, all of these arguments are specified via the
...
argument of bf_map
. Internal
protocols are:
na
(x): test whether a variable contains NA
-values
(boolean).
nan
(x): test whether a variable contains NaN
-values
(boolean).
inf
(x): test whether a variable contains Inf
-values
(boolean).
identical
(x, y): element-wise test whether values are
identical across two variables (boolean).
range
(x, min, max): test whether the values are within a
given range (boolean).
matches
(x, set): test whether the values match a given set
(boolean).
grepl
(x, pattern): test whether the values match a given
pattern (boolean).
case
(...): test whether values are part of given cases
(enumeration).
nChar
(x): count the number of characters of the values
(unsigned integer).
nInt
(x): count the number of integer digits of the values
(unsigned integer).
nDec
(x): count the decimal digits of the variable values
(unsigned integer).
integer
(x, ...): encode the integer values as bit-sequence
(signed integer).
numeric
(x, ...): encode the numeric value as floating-point
bit-sequence (with an adapted precision) (floating-point).
The console output of various classes (such as tibble) shows
decimals that are not present or rounds decimals that are present, even for
ordinary numeric vectors. R stores numeric values internally as
double-precision floating-point values (with 64 bits, where 52 bits encode
the mantissa), which corresponds to a decimal precision of ~16 digits
(log10(2^52)
). Hence, if a bit flag doesn't seem to coincide with
the values you see in the console, double check the values with
sprintf("%16f", values)
. If you use a larger value than 16 for
precision, you'll see more digits, but those are not meaningful, as they
result merely from the binary-to-decimal conversion (check out
.makeEncoding
for an additional details.
reg <- bf_registry(name = "testBF", description = "test bitfield")
opr <- "identical"
# identify which arguments need to be given to call a test ...
formalArgs(eval(parse(text = bf_pcl[[opr]]$test)))
#> [1] "x" "y"
# put the test together
bf_map(protocol = opr, data = bf_tbl, registry = reg,
x = x, y = y, na.val = FALSE)
#> width 1
#> flags 1 -
#>
#> pos encoding type col
#> 1 0.0.1/0 identical x-y
# some other examples of ...
# boolean encoding
bf_map(protocol = "matches", data = bf_tbl, registry = reg,
x = commodity, set = c("soybean", "honey"))
#> width 1
#> flags 1 -
#>
#> pos encoding type col
#> 1 0.0.1/0 matches commodity-soybean-honey
bf_map(protocol = "range", data = bf_tbl, registry = reg,
x = yield, min = 10.4, max = 11)
#> width 1
#> flags 1 -
#>
#> pos encoding type col
#> 1 0.0.1/0 range yield-10.4-11
# enumeration encoding
bf_map(protocol = "case", data = bf_tbl, registry = reg,
yield >= 11, yield < 11 & yield > 9, yield < 9 & commodity == "maize")
#> Loading required package: dplyr
#>
#> Attaching package: ‘dplyr’
#> The following objects are masked from ‘package:stats’:
#>
#> filter, lag
#> The following objects are masked from ‘package:base’:
#>
#> intersect, setdiff, setequal, union
#> Loading required package: purrr
#> width 2
#> flags 1 --
#>
#> pos encoding type col
#> 1 0.0.2/0 case1 yield-commodity
# integer encoding
bf_map(protocol = "integer", data = bf_tbl, registry = reg,
x = as.integer(year), na.val = 0L)
#> Warning: NAs introduced by coercion
#> width 11
#> flags 1 -----------
#>
#> pos encoding type col
#> 1 0.0.11/0 integer year
# floating-point encoding
bf_map(protocol = "numeric", data = bf_tbl, registry = reg,
x = yield, decimals = 2)
#> width 12
#> flags 1 ------------
#>
#> pos encoding type col
#> 1 0.1.11/0 numeric yield