-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathREADME.Rmd
More file actions
132 lines (94 loc) · 4.32 KB
/
README.Rmd
File metadata and controls
132 lines (94 loc) · 4.32 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
library(bitfield)
library(terra)
library(tibble)
```
# bitfield <a href='https://github.com/bitfloat/bitfield/'><img src='man/figures/logo.svg' align="right" height="200" /></a>
<!-- badges: start -->
[](https://cran.r-project.org/package=bitfield)
[](https://cran.r-project.org/package=bitfield)
[](https://github.com/bitfloat/bitfield/actions/workflows/R-CMD-check.yaml)
[](https://app.codecov.io/gh/bitfloat/bitfield)
[](https://lifecycle.r-lib.org/articles/stages.html#stable)
<!-- badges: end -->
## Overview
The `bitfield` package enables efficient storage and transmission of metadata and intermediate results across scientific workflows by encoding computational decisions into sequences of bits that transform to integer values. This approach allows storing rich contextual information - including quality assessments, uncertainty metrics, model parameters, and processing thresholds - in a single column of a table or raster layer.
Think of a bit as a switch representing off and on states. A sequence of n bits can accommodate 2^n states, enabling the encoding of boolean responses, categorical cases, integers, or even floating-point values with limited precision. The resulting bitfield creates a 'computational footprint' that preserves the context needed for cross-workflow integration and downstream reuse.
## Installation
Install the official version from CRAN:
```{r, eval=FALSE}
install.packages("bitfield")
```
Install the latest development version from GitHub:
```{r, eval=FALSE}
devtools::install_github("bitfloat/bitfield")
```
## Getting Started
### Tabular Data
```{r}
library(bitfield)
# Example data with quality issues
bf_tbl
```
Create a registry to capture metadata about your workflow:
```{r}
reg <- bf_registry(name = "data_quality",
description = "Quality assessment for agricultural data",
template = bf_tbl)
# Test for missing values (1 bit)
reg <- bf_map(protocol = "na", data = bf_tbl, x = commodity, registry = reg)
# Encode yield values with half precision (16 bits)
reg <- bf_map(protocol = "numeric", data = bf_tbl, x = yield,
format = "half", registry = reg)
# View the registry structure
reg
```
Encode the flags into integer representation:
```{r}
field <- bf_encode(registry = reg)
field
```
Decode the bitfield in a downstream application:
```{r}
decoded <- bf_decode(x = field, registry = reg, verbose = FALSE)
# Returns a named list with decoded values
names(decoded)
# Access individual flags
decoded$na_commodity
library(tibble)
tibble(original = bf_tbl$yield, decoded = decoded$numeric_yield)
```
### Raster Data
The same workflow applies to raster data - just use a `SpatRaster` as the template:
```{r}
library(terra)
# Create example raster
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)
# Create registry with raster template
reg_rst <- bf_registry(name = "raster_quality",
description = "Quality flags for raster data",
template = bf_rst)
reg_rst <- bf_map(protocol = "na", data = bf_rst, x = commodity, registry = reg_rst)
reg_rst <- bf_map(protocol = "numeric", data = bf_rst, x = yield,
format = "half", registry = reg_rst)
# Encode returns a SpatRaster
field_rst <- bf_encode(registry = reg_rst)
field_rst
# Decode returns a multi-layer SpatRaster
decoded_rst <- bf_decode(x = field_rst, registry = reg_rst, verbose = FALSE)
decoded_rst
```
## Getting Help
- Browse the [function reference](https://bitfloat.github.io/bitfield/reference/index.html) for detailed documentation
- Report bugs at [github.com/bitfloat/bitfield/issues](https://github.com/bitfloat/bitfield/issues)