pack.RdPack/Unpack values as low-fidelity representation into a single 32-bit integer.
These functions require a packing spec (pack_spec) which defines how values
are converted to/from their low-fidelity representations.
pack(values, pack_spec) unpack(int32, pack_spec)
| values | named vector or list of values |
|---|---|
| pack_spec | list describing the low-fidelity representation of each value |
| int32 | standard R integer with the packed bits |
pack() takes a named list of values and returns an integer. unpack()
takes an integer and returns a named list of values.
The packing specification (pack_spec) is a named list detailing how
values should be converted to their low-fidelity representations.
The name of the values in the pack_spec correspond to the names in
the values argument to pack().
The following are valid types for packing:
integer - A standard integer value
double - A standard double precision floating point value
logical - A standard R logical values
choice - Analogous to storing a factor
scaled - Storing a scaled value in the available bits and then re-scaling when unpacking
colour - A standard hex colour value of the form '#123456'
custom - User must specify functions to convert value to low-fidelity representation and reconstruction
Integers are packed by truncating leading bits that aren't needed e.g. the number 8 only needs 4 bis to represent it, and the other leading 28 bits can be ignored.
Packing an integer in this way is lossless - the reconstructed value using
unpack() will be identical to the original value.
specification
nbits - total number of bits to use
signed - keep a sign bit? Default: FALSE
mult - pre-scale the value when packing, and undo scaling
when unpacking. i.e. (value + offset) * mult. Default: 1
offset - offset the value when packing, and undo offset when
unpacking . i.e. (value + offset) * mult. Default: 0
Doubles are packed by truncating the mantissa and re-encoding the exponent. This will almost definitely lead to loss of precision, and any reconstructed value will not be identical to the original.
float_name - name of floating point representation to use. Options:
'single' - single precision 32-bits
'fp24' - 24bit float
'bfloat16' - 16 bit float
'half' - half precision 16-bits
nbits - total number of bits to use. If specified, this takes
precedence over the float_name value.
maxval - only used if nbits is specified. Used to
calculate the total bits in the exponent.
signed - keep a sign bit? Only used if nbits is
specified. Default: FALSE
float_bits - [advanced] A 3-element numeric vector giving the
number of bits to assign to the sign, exponent and mantissa,
respecively. If given, float_bits takes precedence over
both nbits and float_name.
Logical values only require a single bit, but more bits can be specified if desired.
nbits - total number of bits to use. Optional. Default: 1
A choice is very similar to a factor, but the labels are only stored in the specification, and the index is 0-based (instead of 1-based)
options - vector of options to match values against. Only
the index of the value into this list is stored.
nbits - total number of bits to use. Optional. If not given,
it is calculated to be the number of bits necessary to store all
possible options.
Specifying the stored of a scaled value is sometimes easier than trying to work out how to corectly store a double precision floating point.
nbits - number of bits to use
min - minimum value to be stored. Default: 0
max - maximum value to be stored in the given bits. Every
stored value is scaled by (2^nbits - 1)/max
when pack()ed, and unscaled when unpacked().
Packing a colour is achieved by truncating the bits for each of the R, G and B channels separately.
nbits - number of bits to use
rgb_bits - [advanced] A 3-element numeric vector giving the
number of bits to assign to the R, G and B channels
respecively. If given, rgb_bits takes precedence over
nbits.
This packing specification allows you to specify a function to convert a value into a low-fidelity representation, and a matching function to reconstruct the original value.
See vignette('packing-specification', package = 'lofi') for more examples
on using a custom packing specification.
nbits - number of bits to use
pack_func - a function. Alternatively, can specify a formula
which will be converted internally to a function taking a single
argument, .x.
unpack_func - a function. Alternatively, can specify a formula
which will be converted internally to a function taking a single
argument, .x.
# Specify how to convert values to low-fidelity representation pack_spec <- list( x = list(type = 'double', float_name = 'bfloat16'), valid = list(type = 'logical'), stars = list(type = 'integer', mult = 10, nbits = 6), alpha = list(type = 'scaled', max = 1, nbits = 5), grade = list(type = 'choice', options = c('A', 'B', 'C', 'D')) ) # Assemble the values values <- list( x = 1.234e21, valid = TRUE, stars = 4.5, # Star rating 0-5. 1 decimal place. alpha = 0.8, # alpha. range [0, 1] grade = 'B' ) # pack them into a single integer packed_values <- pack(values, pack_spec) # Reconstruct the initial values from the packed values unpack(packed_values, pack_spec)#> $x #> [1] 1.226708e+21 #> #> $valid #> [1] TRUE #> #> $stars #> [1] 4.5 #> #> $alpha #> [1] 0.8064516 #> #> $grade #> [1] "B" #>#> $x #> [1] 1.226708e+21 #> #> $valid #> [1] TRUE #> #> $stars #> [1] 4.5 #> #> $alpha #> [1] 0.8064516 #> #> $grade #> [1] "B"