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 section or the documentation website.
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 vignette.
In total allometric
contains 2804 models across 73 publications, refer to the Current Status for a more complete view of available models.
Currently allometric
can be installed via CRAN:
install.packages("allometric")
For the latest release version, please install directly from GitHub using devtools
:
devtools::install_github("allometric/allometric")
Before beginning, make sure to install the models locally by running
library(allometric)
install_models()
This installs all available models from the public models repository.
Finally, load the models using the load_models()
function into a variable:
allometric_models <- load_models()
head(allometric_models)
#> # A tibble: 6 × 10
#> id model_type country region taxa pub_id model family_name covt_name
#> <chr> <chr> <list> <list> <list> <chr> <list> <list> <list>
#> 1 c208… site index <NULL> <NULL> <Taxa> barne… <FxdEffcM> <chr [1]> <chr [2]>
#> 2 6974… site index <NULL> <NULL> <Taxa> barre… <FxdEffcM> <chr [1]> <chr [2]>
#> 3 f622… stem heig… <NULL> <NULL> <Taxa> barre… <FxdEffcM> <chr [1]> <chr [1]>
#> 4 6677… stem heig… <NULL> <NULL> <Taxa> barre… <FxdEffcM> <chr [1]> <chr [1]>
#> 5 fea4… stem heig… <NULL> <NULL> <Taxa> barre… <FxdEffcM> <chr [1]> <chr [1]>
#> 6 2f12… stem heig… <NULL> <NULL> <Taxa> barre… <FxdEffcM> <chr [1]> <chr [1]>
#> # ℹ 1 more variable: pub_year <dbl>
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
#> # A tibble: 570 × 10
#> id model_type country region taxa pub_id model family_name
#> <chr> <chr> <list> <list> <list> <chr> <list> <list>
#> 1 be6c800c stem volume <NULL> <NULL> <Taxa> bell_1981 <FxdEffcM> <chr [3]>
#> 2 e10967a8 stem volume <NULL> <NULL> <Taxa> brackett_1… <FxdEffcM> <chr [1]>
#> 3 24e757f8 stem volume <NULL> <NULL> <Taxa> brackett_1… <FxdEffcM> <chr [1]>
#> 4 b07847c6 stem volume <NULL> <NULL> <Taxa> brackett_1… <FxdEffcM> <chr [1]>
#> 5 2b138c8c stem volume <NULL> <NULL> <Taxa> brackett_1… <FxdEffcM> <chr [1]>
#> 6 191a8865 stem volume <NULL> <NULL> <Taxa> brackett_1… <FxdEffcM> <chr [1]>
#> 7 5865e9eb stem volume <NULL> <NULL> <Taxa> brackett_1… <FxdEffcM> <chr [1]>
#> 8 e76edbdf stem volume <NULL> <NULL> <Taxa> brackett_1… <FxdEffcM> <chr [1]>
#> 9 c20b19ec stem volume <NULL> <NULL> <Taxa> brackett_1… <FxdEffcM> <chr [1]>
#> 10 3a6dac01 stem volume <NULL> <NULL> <Taxa> brackett_1… <FxdEffcM> <chr [1]>
#> # ℹ 560 more rows
#> # ℹ 2 more variables: covt_name <list>, pub_year <dbl>
Next, we can filter to include only Tsuga heterophylla using a special specifier called Taxon
that enables rigorous searching of species:
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
#> # A tibble: 4 × 10
#> id model_type country region taxa pub_id model family_name covt_name
#> <chr> <chr> <list> <list> <list> <chr> <list> <list> <list>
#> 1 2b13… stem volu… <NULL> <NULL> <Taxa> brack… <FxdEffcM> <chr [1]> <chr [2]>
#> 2 191a… stem volu… <NULL> <NULL> <Taxa> brack… <FxdEffcM> <chr [1]> <chr [2]>
#> 3 5865… stem volu… <NULL> <NULL> <Taxa> brack… <FxdEffcM> <chr [1]> <chr [2]>
#> 4 6142… stem volu… <NULL> <NULL> <Taxa> poude… <FxdEffcM> <chr [4]> <chr [2]>
#> # ℹ 1 more variable: pub_year <dbl>
We can see that we have 4 models to choose from. Let’s select the model from the publication poudel_2019
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()
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
.
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.
tsuga_poudel
#> Model Call:
#> vsia = f(dsob, hst)
#>
#> vsia [m3]: volume of the entire stem inside bark, including top and stump
#> dsob [cm]: diameter of the stem, outside bark at breast height
#> hst [m]: total height of the stem
#>
#> Parameter Estimates:
#> # A tibble: 1 × 3
#> a b c
#> <dbl> <dbl> <dbl>
#> 1 -9.98 1.96 0.925
#>
#> Model Descriptors:
#> # A tibble: 1 × 3
#> country region taxa
#> <list> <list> <list>
#> 1 <chr [2]> <chr [10]> <Taxa>
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).
Using the predict()
method we can easily use the function as defined by providing values of these two covariates.
predict(tsuga_poudel, 12, 65)
#> 0.2868491 [m^3]
or we can use the prediction function with a data frame of values
my_trees <- data.frame(dias = c(12, 15, 20), heights = c(65, 75, 100))
predict(tsuga_poudel, my_trees$dias, my_trees$heights)
#> Units: [m^3]
#> [1] 0.2868491 0.5068963 1.1618632
or even using the convenience of dplyr
#> dias heights vols
#> 1 12 65 0.2868491 [m^3]
#> 2 15 75 0.5068963 [m^3]
#> 3 20 100 1.1618632 [m^3]
The above example is a very basic use case for allometric
. Please refer to the Common Inventory Use Cases vignette for more complex examples.
In total allometric
contains 2804 models across 73 publications.
category | AF | AS | OC | SA |
---|---|---|---|---|
stem height | 5 | 4 | 2 | 5 |
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.
Other ideas? Contact bfrank70@gmail.com to help out.
The following vignettes available on the package website provide information to two primary audiences.
Users interested in finding models for analysis will find the following documentation most useful:
Users interested in contributing models to the package will find these vignettes the most useful: