---
output: github_document
---
```{r include=FALSE}
library(dplyr)
library(tidyr)
library(lemon)
library(allometric)
knitr::opts_chunk$set(
comment = "#>"
)
install_models()
allometric_models <- load_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")) %>%
distinct(id, model_type, continent) %>%
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
[](https://github.com/allometric/allometric/actions/workflows/check-standard.yaml)
`r badger::badge_devel("allometric/allometric", "blue")`
[](https://app.codecov.io/gh/allometric/allometric)
[](https://www.youtube.com/playlist?list=PLP5y0kzuWunWiUHpgoppVlTC_c2KYlrRK)
`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. Get started by going to
the [Installation](#installation) section or the [documentation website](https://allometric.org).
`allometric` 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 [Contributing a Model](https://allometric.org/articles/installing_a_model.html) vignette.
In total **`allometric` contains `r n_models` models across `r n_pubs` publications**,
refer to the [Current Status](#current-status) for a more complete view of
available models.
## Installation
Currently `allometric` can be installed via CRAN:
```{r eval=FALSE}
install.packages("allometric")
```
For the latest release version, please install directly from GitHub using
`devtools`:
```{r eval=FALSE}
devtools::install_github("allometric/allometric")
```
Before beginning, make sure to install the models locally by running
```{r eval=F}
library(allometric)
install_models()
```
This installs all available models from the public [models](https://github.com/allometric/models) repository.
Finally, load the models using the `load_models()` function into a variable:
```{r}
allometric_models <- load_models()
head(allometric_models)
```
## Finding a Model
`allometric_models` is a `tibble` dataframe. Each row represents one
allometric model with various attributes. Users interact with this table the
way they would with any other `tibble`.
For example, we can use `dplyr` to filter this table to find models for
analysis. Let's say I am interested in finding stem volume models for
*Tsuga heterophylla*. First, let us filter the `model_type` to include only
stem volume models
```{r}
stemvol_models <- allometric_models %>%
filter(model_type == "stem volume")
stemvol_models
```
Next, we can filter to include only *Tsuga heterophylla* using a special
specifier called `Taxon` that enables rigorous searching of species:
```{r}
tsuga_het_taxon <- Taxon(
family = "Pinaceae", genus = "Tsuga", species = "heterophylla"
)
tsuga_vol_models <- stemvol_models %>%
filter(purrr::map_lgl(taxa, ~ tsuga_het_taxon %in% .))
tsuga_vol_models
```
We can see that we have `r nrow(tsuga_vol_models)` models to choose from. Let's
select the model from the publication `poudel_2019`
```{r}
tsuga_poudel <- tsuga_vol_models %>% select_model("6142693f")
```
This example is very basic, and more complex search examples can be found in
the [`load_models()`](https://allometric.org/reference/load_models.html)
documentation. Models can be searched not only by their taxonomic information,
but also the types of measurements the models require, their geographic region,
and other attributes. We highly encourage users review the linked examples for
production use of `allometric`.
## Using the Model
`tsuga_poudel` now represents an allometric model that can be used for
prediction. We must next figure out how to use the model.
Using the standard output of `tsuga_poudel` 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}
tsuga_poudel
```
We can see from the `Model Call` section that `tsuga_poudel` will require
two covariates called `dsob`, which refers to diameter outside bark at
breast height, and `hst`, the height of the main stem. `allometric` uses a
variable naming system to determine the names of response variables and
covariates (refer to the [Variable Naming System vignette](https://allometric.org/articles/variable_naming_system.html)).
Using the `predict()` method we can easily use the function as defined
by providing values of these two covariates.
```{r eval=T}
predict(tsuga_poudel, 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(tsuga_poudel, my_trees$dias, my_trees$heights)
```
or even using the convenience of `dplyr`
```{r}
my_trees %>%
mutate(vols = predict(tsuga_poudel, dias, heights))
```
The above example is a very basic use case for `allometric`. Please refer to the
[Common Inventory Use Cases vignette](https://allometric.org/articles/inventory_example.html)
for more complex examples.
## Current Status
In total **`allometric` contains `r n_models` models across `r n_pubs` publications**.
```{r echo=FALSE}
knitr::kable(model_summ.fmt, format = "markdown")
```
## 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/allometric/models/issues/new?assignees=brycefrank&labels=add+publication&projects=&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/allometric/models/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/allometric/models/labels/digitization%20needed).
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://allometric.org/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.
## Next Steps
The following vignettes available on the [package website](https://allometric.org/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://allometric.org/articles/inventory_example.html)
Users interested in **contributing models** to the package will find these vignettes the most useful:
- [Contributing a Model](https://allometric.org/articles/installing_a_model.html)
- [Describing a Model with Descriptors](https://allometric.org/articles/descriptors.html)
- [Variable Naming System](https://allometric.org/articles/variable_naming_system.html)
Total Commits: 516
Total Committers: 4
Avg Commits per committer: 129.0
Development Distribution Score (DDS): 0.021
Commits in past year: 82
Committers in past year: 2
Avg Commits per committer in past year: 41.0
Development Distribution Score (DDS) in past year: 0.061
Total issues: 142
Total pull requests: 10
Average time to close issues: 30 days
Average time to close pull requests: about 3 hours
Total issue authors: 4
Total pull request authors: 2
Average comments per issue: 0.71
Average comments per pull request: 0.8
Merged pull request: 10
Bot issues: 0
Bot pull requests: 0
Past year issues: 6
Past year pull requests: 1
Past year average time to close issues: 3 days
Past year average time to close pull requests: 4 minutes
Past year issue authors: 2
Past year pull request authors: 1
Past year average comments per issue: 0.33
Past year average comments per pull request: 2.0
Past year merged pull request: 1
Past year bot issues: 0
Past year bot pull requests: 0