forked from allometric/allometric
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
243 lines (183 loc) · 9.24 KB
/
README.Rmd
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
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
---
output: github_document
---
```{r include=FALSE}
library(dplyr)
library(tidyr)
library(lemon)
library(allometric)
options(width = 10000)
knitr::opts_chunk$set(
comment = "#>"
)
if (!exists("allometric_models")) {
allometric::install_models()
}
n_models <- nrow(allometric_models)
n_pubs <- length(unique(allometric_models$pub_id, na.rm = T))
continents <- read.csv(system.file("continents.csv", package = "allometric"),
na.strings = "")
summ_categories <- data.frame(
category = c(
rep("biomass component", 8),
rep("other", 6)
),
model_type = c(
"bark biomass", "branch biomass", "foliage biomass", "foliage ratio",
"branch ratio", "root biomass", "stem biomass", " biomass", "bark ratio",
"stem diameter", "stem ratio", "crown ratio", "stump diameter",
"VBAR"
)
)
model_summ <- allometric_models %>%
unnest_models("country") %>%
left_join(continents, by = c("country" = "iso_3166_1_a2")) %>%
group_by(model_type, continent) %>%
summarise(n=n()) %>%
merge(summ_categories, all.x=T)
model_summ[is.na(model_summ$category), 'category'] <- model_summ$model_type[is.na(model_summ$category)]
model_summ.fmt <- model_summ %>%
group_by(category, continent) %>%
summarise(n = sum(n)) %>%
tidyr::pivot_wider(names_from = "continent", values_from = "n") %>%
replace_na(list(AS = 0, `NA` = 0, EU = 0, AF = 0, OC = 0, SA = 0))
model_summ.fmt <- bind_rows(
list(
model_summ.fmt %>% filter(category != "other"),
model_summ.fmt %>% filter(category == "other")
)
)
```
# allometric <picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/brycefrank/allometric/master/man/figures/allo2-darkmode.svg"><source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/brycefrank/allometric/master/man/figures/allo2.svg"><img alt="Isometric logo of a tree" height="210" width="165" align="right"></picture>
<!-- badges: start -->
[](https://github.com/brycefrank/allometric/actions/workflows/check-standard.yaml)
`r badger::badge_devel("brycefrank/allometric", "blue")`
[](https://codecov.io/gh/brycefrank/allometric)
<!-- badges: end -->
`allometric` is an R package for predicting tree attributes with allometric
models. Thousands of allometric models exist in the scientific and technical
forestry literature, and `allometric` is a platform for archiving and using this
vast array of models in a robust and structured format.
`allometric` not only enables the use of allometric models for analysis, it
also provides a structured language for adding models to the package. If you
are interested in helping the developer in this process please refer to the
[Installing a Model](https://brycefrank.com/allometric/articles/installing_a_model.html) vignette.
In total **`allometric` contains `r n_models` models across `r n_pubs` publications**, the following
table displays the number of models by continent and category:
```{r echo=FALSE}
knitr::kable(model_summ.fmt, format = "markdown")
```
Refer to the [Reference](https://brycefrank.com/allometric/reference/index.html)
for a full list of publications disaggregated by allometric model type.
## How Can I Help?
`allometric` is a monumental undertaking, and already several people have come
forward and added hundreds of models. There are several ways to help out. The
following list is ranked from the least to most difficult tasks.
1. [Add missing publications as an Issue](https://github.com/brycefrank/allometric/issues/new?assignees=brycefrank&labels=add+publication&template=add-models-from-a-publication.md&title=%5BInsert+Author-Date+Citation%5D).
We always need help *finding publications* to add. If you know of a publication that is missing, feel free to add it as an Issue and we will eventually install the models contained inside.
2. [Find source material for a publication](https://github.com/brycefrank/allometric/labels/missing%20source).
Some publications are missing their original source material. Usually these are very old legacy publications. If you know where a publication might be found, or who to contact, leave a note on any of these issues.
3. [Help us digitize publications](https://github.com/brycefrank/allometric/issues?q=is%3Aissue+is%3Aopen+label%3A%22digitization+needed%22).
We always need help *digitizing legacy reports*, at this link you will find a list of reports that need manual digitization. These can be handled by anyone with Excel and a cup of coffee.
4. [Learn how to install and write models](https://brycefrank.com/allometric/articles/installing_a_model.html).
Motivated users can learn how to install models directly using the package functions and git pull requests. Users comfortable with R and git can handle this task.
Other ideas? Contact [email protected] to help out.
## Installation
Currently `allometric` is only available on GitHub, and can be installed using
`devtools`.
```{r eval=FALSE}
devtools::install_github("brycefrank/allometric")
```
## Getting Started
Most users will only be interested in finding and using allometric equations in
their analysis. `allometric` allows rapid searching of currently installed
models.
Before beginning, make sure to install the models locally by running
```{r eval=F}
library(allometric)
install_models()
```
This compiles the allometric models, and enables their use. `install_models()`
only needs to be ran at installation or following any package updates. After
running this function, the models are available in the variable
`allometric_models`. Refer to the `?allometric_models` help for more
information.
```{r}
head(allometric_models)
```
**Finding and Selecting a Model**
`allometric_models` is a `tibble::tbl_df` dataframe. Each row represents one
allometric model with various attributes. Some columns are `list` columns, which
are columns that contain lists with multiple values as their elements. One
example of this is the `family_name` column, which contains the names of all
authors for the publication that contains the model.
`list` columns enable rigorous searching of models covered in the
`?allometric_models` help page, but to get started we will use a helper
function called `unnest_models()` that will give us a clearer picture of the
available data. Using the `cols` argument we can specify which columns we want
to unnest. In this case we will unnest the `family_name` column.
```{r}
unnested_models <- unnest_models(allometric_models, cols = "family_name")
unnested_models
```
Now, each row represents unique data combinations for each model, which can be
quickly filtered by most users using `dplyr::filter`. For example, to find a
volume model for the genus Alnus that had `"Brackett"` as an author or co-author
we can use
```{r}
brackett_alnus_vol <- unnested_models %>%
dplyr::filter(
family_name == "Brackett", model_type == "stem volume",
genus == "Alnus"
)
brackett_alnus_vol
```
we can see that model `f21028ef` is a volume model written by Brackett for
*Alnus rubra*. The model can be selected using the `id` field:
```{r}
brackett_alnus_mod <- brackett_alnus_vol %>% select_model("f21028ef")
```
or by using the row index
```{r eval=F}
brackett_alnus_mod <- brackett_alnus_vol %>% select_model(1)
```
**Determine Needed Information**
`brackett_alnus_mod` now represents an allometric model that can be used for
prediction.
Using the standard output of `brackett_alnus_mod` we obtain a summary of the model form,
the response variable, the needed covariates and their units, a summary of
the model descriptors (i.e., what makes the model unique within the
publication), and estimates of the parameters.
```{r}
brackett_alnus_mod
```
We can see from the `Model Call` section that `brackett_alnus_mod` will require
two covariates called `dsob`, which refers to diameter outside bark at
breast height, and `hst`, the height of the main stem.
**Predict Using the Selected Model**
Using the `predict()` method we can easily use the function as defined
by providing values of these two covariates.
```{r eval=T}
predict(brackett_alnus_mod, 12, 65)
```
or we can use the prediction function with a data frame of values
```{r}
my_trees <- data.frame(dias = c(12, 15, 20), heights = c(65, 75, 100))
predict(brackett_alnus_mod, my_trees$dias, my_trees$heights)
```
or even using the convenience of `dplyr`
```{r}
my_trees %>%
mutate(vols = predict(brackett_alnus_mod, dias, heights))
```
## Next Steps
The following vignettes available on the [package website](https://brycefrank.com/allometric/index.html)
provide information to two primary audiences.
Users interested in finding models for analysis will find the following
documentation most useful:
- [Common Inventory Use Cases](https://brycefrank.com/allometric/articles/inventory_example.html)
- `?allometric_models`
Users interested in **contributing models** to the package will find these vignettes the most useful:
- [Installing a Model](https://brycefrank.com/allometric/articles/installing_a_model.html)
- [Describing a Model with Descriptors](https://brycefrank.com/allometric/articles/descriptors.html)
- [Variable Naming System](https://brycefrank.com/allometric/articles/variable_naming_system.html)