README.Rmd

---
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-",
  fig.width = 6,
  fig.height = 5
)
```

# <img src="https://i.imgur.com/39pvr4n.png" align="left" height=44 /> allodb: An R package for biomass estimation at extratropical forest plots

<!-- badges: start -->
[![peer-review](https://badges.ropensci.org/436_status.svg)](https://github.com/ropensci/software-review/issues/436)
[![Codecov test coverage](https://codecov.io/gh/ropensci/allodb/branch/master/graph/badge.svg)](https://app.codecov.io/gh/ropensci/allodb?branch=master)
[![R-CMD-check](https://github.com/ropensci/allodb/workflows/R-CMD-check/badge.svg)](https://github.com/ropensci/allodb/actions)
[![R-CMD-check](https://github.com/ropensci/allodb/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ropensci/allodb/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/ropensci/allodb/graph/badge.svg)](https://app.codecov.io/gh/ropensci/allodb)
<!-- badges: end -->

## Introduction

Allometric equations for calculation of tree aboveground biomass (AGB) form the basis for estimates of forest carbon storage and exchange with the atmosphere. While standard models exist to calculate forest biomass across the tropics, we lack a standardized tool for computing AGB across the global extratropics.

_allodb_ was conceived as a framework to standardize and simplify the biomass estimation process across globally distributed extratropical forests (mainly temperate and boreal forests). 
With _allodb_ we aimed to: a) compile relevant published and unpublished allometries, focusing on AGB but structured to handle other variables (e.g., height); b) objectively select and integrate appropriate available equations across the full range  of tree sizes; and c) serve as a platform for future updates and expansion to other research sites.

The _allodb_ package contains a dataset of systematically selected published allometric equations. This dataset was built based on 701 woody species identified at 24 large [ForestGEO forest dynamic plots](https://forestgeo.si.edu/) representing all major extratropical forest types. A total of 570 parsed allometric equations to estimate individual tree biomass were retrieved, checked, and combined using a weighting function designed to ensure optimal equation selection over the full tree size range with smooth transitions across equations. The equation dataset used can be customized with built-in functions that subset the original dataset and add new equations.

The package provides functions to estimate tree biomass based on user-provided census data (tree diameter, taxonomic identification, and plot coordinates). New allometric equations are calibrated for each species and location by resampling the original equations; equations with a larger sample size and/or higher taxonomic and climatic similarity with the species and location in question are given a higher weight in this process. 

## Installation

Install the development version of _allodb_ from GitHub:

```R
# install.packages("pak")
pak::pak("ropensci/allodb")
```

## Examples

Prior to calculating tree biomass using _allodb_, users need to provide a table (i.e. dataframe) with DBH (cm), parsed species Latin names, and site(s) coordinates. In the following examples we use data from the Smithsonian Conservation Biology Institute, USA (SCBI) ForestGEO dynamics plot (trees from 1 hectare surveyed in 2008). Full tree census data can be requested through the [ForestGEO portal](https://forestgeo.si.edu/explore-data).

```{r open-data}
library(allodb)
data(scbi_stem1)
``` 

The biomass of all trees in one (or several) censuses can be estimated using the `get_biomass` function. 

```{r calc-agb-all}
scbi_stem1$agb <-
  get_biomass(
    dbh = scbi_stem1$dbh,
    genus = scbi_stem1$genus,
    species = scbi_stem1$species,
    coords = c(-78.2, 38.9)
  )
```

Biomass for a single tree can be estimated given dbh and species identification (results in kilograms).

```{r calc-agb-poplar}
get_biomass(
  dbh = 50,
  genus = "liriodendron",
  species = "tulipifera",
  coords = c(-78.2, 38.9)
)
```

Users can modify the set of equations that will be used to estimate the biomass using the `new_equations` function. The default option is the entire _allodb_ equation table. Users can also work on a subset of those equations, or add new equations to the table (see `?allodb::new_equations`). This new equation table should be provided as an argument in the `get_biomass` function.  

```{r}
show_cols <- c("equation_id", "equation_taxa", "equation_allometry")
eq_tab_acer <- new_equations(subset_taxa = "Acer")
head(eq_tab_acer[, show_cols])
```

Within the `get_biomass` function, this equation table is used to calibrate a new allometric equation for all species/site combinations in the user-provided dataframe. This is done by attributing a weight to each equation based on its sampling size, and taxonomic and climatic similarity with the species/site combination considered. 

```{r weights}
allom_weights <-
  weight_allom(
    genus = "Acer",
    species = "rubrum",
    coords = c(-78, 38)
  )

## visualize weights
equ_tab_acer <- new_equations()
equ_tab_acer$weights <- allom_weights
keep_cols <-
  c(
    "equation_id",
    "equation_taxa",
    "sample_size",
    "weights"
  )
order_weights <- order(equ_tab_acer$weights, decreasing = TRUE)
equ_tab_acer <- equ_tab_acer[order_weights, keep_cols]
head(equ_tab_acer)
```

Equations are then resampled within their original DBH range: the number of resampled values for each equation is proportional to its weight (as attributed by the `weight_allom` function). 

```{r resample-acer, eval = TRUE}
df_resample <-
  resample_agb(
    genus = "Acer",
    species = "rubrum",
    coords = c(-78, 38)
  )

plot(
  df_resample$dbh,
  df_resample$agb,
  xlab = "DBH (cm)",
  ylab = "Resampled AGB values (kg)"
)
```


The resampled values are then used to fit the following nonlinear model: <img src="https://render.githubusercontent.com/render/math?math=AGB = a * dbh ^ b %2B e">, with i.i.d. <img src="https://render.githubusercontent.com/render/math?math=e ~N(0, sigma^2)">. The parameters (_a_, _b_, and _sigma_) are returned by the `est_params()` function.

The resampled values (dots) and new fitted equation (red dotted line) can be visualized with the `illustrate_allodb()` function. 

```{r est-params-acer, eval = TRUE, fig.height=4, fig.width=10}
pars_acer <- est_params(
  genus = "Acer",
  species = "rubrum",
  coords = c(-78, 38)
)
illustrate_allodb(
  genus = "Acer",
  species = "rubrum",
  coords = c(-78, 38)
)
```


The `est_params` function can be used for all species/site combinations in the dataset at once. 

```{r est-params-all, eval = TRUE}
params <- est_params(
  genus = scbi_stem1$genus,
  species = scbi_stem1$species,
  coords = c(-78.2, 38.9)
)
head(params)
```

AGB is then recalculated as `agb = a * dbh^b` within the `get_biomass` function.

Please note that this package is released with a [Contributor
Code of Conduct](https://ropensci.org/code-of-conduct/). 
By contributing to this project, you agree to abide by its terms.

## Contributors


<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->

All contributions to this project are gratefully acknowledged using the [`allcontributors` package](https://github.com/ropensci/allcontributors) following the [all-contributors](https://allcontributors.org) specification. Contributions of any kind are welcome!

### Code

<table>

<tr>
<td align="center">
<a href="https://github.com/gonzalezeb">
<img src="https://avatars.githubusercontent.com/u/26872628?v=4" width="100px;" alt=""/>
</a><br>
<a href="https://github.com/ropensci/allodb/commits?author=gonzalezeb">gonzalezeb</a>
</td>
<td align="center">
<a href="https://github.com/maurolepore">
<img src="https://avatars.githubusercontent.com/u/5856545?v=4" width="100px;" alt=""/>
</a><br>
<a href="https://github.com/ropensci/allodb/commits?author=maurolepore">maurolepore</a>
</td>
<td align="center">
<a href="https://github.com/cpiponiot">
<img src="https://avatars.githubusercontent.com/u/20208665?v=4" width="100px;" alt=""/>
</a><br>
<a href="https://github.com/ropensci/allodb/commits?author=cpiponiot">cpiponiot</a>
</td>
<td align="center">
<a href="https://github.com/teixeirak">
<img src="https://avatars.githubusercontent.com/u/6355854?v=4" width="100px;" alt=""/>
</a><br>
<a href="https://github.com/ropensci/allodb/commits?author=teixeirak">teixeirak</a>
</td>
<td align="center">
<a href="https://github.com/jeroen">
<img src="https://avatars.githubusercontent.com/u/216319?v=4" width="100px;" alt=""/>
</a><br>
<a href="https://github.com/ropensci/allodb/commits?author=jeroen">jeroen</a>
</td>
</tr>

</table>


### Issue Authors

<table>

<tr>
<td align="center">
<a href="https://github.com/ValentineHerr">
<img src="https://avatars.githubusercontent.com/u/19673377?u=765bd08c7386c158384f7f801bce81bf8384517c&v=4" width="100px;" alt=""/>
</a><br>
<a href="https://github.com/ropensci/allodb/issues?q=is%3Aissue+author%3AValentineHerr">ValentineHerr</a>
</td>
<td align="center">
<a href="https://github.com/adamhsparks">
<img src="https://avatars.githubusercontent.com/u/3195906?u=ff1ca92ae028fe7eb18d006f92cb8a725625e69c&v=4" width="100px;" alt=""/>
</a><br>
<a href="https://github.com/ropensci/allodb/issues?q=is%3Aissue+author%3Aadamhsparks">adamhsparks</a>
</td>
<td align="center">
<a href="https://github.com/lucas-johnson">
<img src="https://avatars.githubusercontent.com/u/10555272?u=b7999b05830a0f3a5b4d1b2d332d7feb8b4ad026&v=4" width="100px;" alt=""/>
</a><br>
<a href="https://github.com/ropensci/allodb/issues?q=is%3Aissue+author%3Alucas-johnson">lucas-johnson</a>
</td>
</tr>

</table>


### Issue Contributors

<table>

<tr>
<td align="center">
<a href="https://github.com/ErvanCH">
<img src="https://avatars.githubusercontent.com/u/20225141?u=c7fa2b3442b355f716873403379f4b8c5eb47230&v=4" width="100px;" alt=""/>
</a><br>
<a href="https://github.com/ropensci/allodb/issues?q=is%3Aissue+commenter%3AErvanCH">ErvanCH</a>
</td>
<td align="center">
<a href="https://github.com/laosuz">
<img src="https://avatars.githubusercontent.com/u/30370734?v=4" width="100px;" alt=""/>
</a><br>
<a href="https://github.com/ropensci/allodb/issues?q=is%3Aissue+commenter%3Alaosuz">laosuz</a>
</td>
<td align="center">
<a href="https://github.com/tylerlittlefield">
<img src="https://avatars.githubusercontent.com/u/35909636?u=4fe1a340b52a9593fc786ac76d18ce2af971ebfd&v=4" width="100px;" alt=""/>
</a><br>
<a href="https://github.com/ropensci/allodb/issues?q=is%3Aissue+commenter%3Atylerlittlefield">tylerlittlefield</a>
</td>
<td align="center">
<a href="https://github.com/rudeboybert">
<img src="https://avatars.githubusercontent.com/u/4574203?u=0f8201cf7d22f17e52c85b215f3e68cecaa734ef&v=4" width="100px;" alt=""/>
</a><br>
<a href="https://github.com/ropensci/allodb/issues?q=is%3Aissue+commenter%3Arudeboybert">rudeboybert</a>
</td>
<td align="center">
<a href="https://github.com/tlbeckham">
<img src="https://avatars.githubusercontent.com/u/97658753?v=4" width="100px;" alt=""/>
</a><br>
<a href="https://github.com/ropensci/allodb/issues?q=is%3Aissue+commenter%3Atlbeckham">tlbeckham</a>
</td>
</tr>

</table>

<!-- markdownlint-enable -->
<!-- prettier-ignore-end -->
<!-- ALL-CONTRIBUTORS-LIST:END -->