allodb.Rmd

---
title: "Using allodb to estimate aboveground biomass"
output: rmarkdown::html_vignette
vignette: >
 %\VignetteIndexEntry{Using allodb to estimate aboveground biomass}
 %\VignetteEngine{knitr::rmarkdown}
 %\VignetteEncoding{UTF-8}
---
  
```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  echo = TRUE
)
```

## Installation

Install the development version of _allodb_ from GitHub:

```{r install, eval=FALSE}
# install.packages("remotes")
remotes::install_github("ropensci/allodb")
```

## Load the census data

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 (1st census in 2008, trees from 1 hectare). Data can be requested through the ForestGEO portal (https://forestgeo.si.edu/)

```{r load-census-data}
require(allodb)
data(scbi_stem1)
str(scbi_stem1)
``` 

## Load and modify the equation table 

`allodb` provides a dataframe containing `r nrow(allodb::equations)` parsed allometric equations. 

```{r load-equations}
data(equations)
``` 

Additional information about the equation table can be found in the equation metadata. 

```{r load-metadata}
data(equations_metadata)
``` 

This equation table is the default in all functions of the package. Users can modify the set of equations that will be used to estimate biomass using the `new_equations()` function: users can work on a subset of those equations, or add new equations to the table (see `?allodb::new_equations`). The customized equation table should be provided as an argument in the `get_biomass()` (or other) function (argument name: `new_eqtable`). 

### Subset the equation table 

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

### Add new equations

```{r add-equations}
eq_tab_add <- new_equations(
  new_taxa = c("Quercus ilex", "Castanea sativa"),
  new_allometry = c("0.12*dbh^2.5", "0.15*dbh^2.7"),
  new_coords = c(4, 44),
  new_min_dbh = c(5, 10),
  new_max_dbh = c(35, 68),
  new_sample_size = c(143, 62)
)
## show added equations - they contain "new" in their equation_id
head(eq_tab_add[grepl("new", eq_tab_add$equation_id), ])
```


## Estimate the aboveground biomass

The aboveground biomass (AGB) can be estimated using the `get_biomass()` function: the required arguments are the diameter at breast height (DBH, in cm), the taxonomic identification (to the genus or species level), and the location (long-lat coordinates). The output is the aboveground biomass of the tree in kg. 

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

The `get_biomass()` function can also be used to estimate the AGB of all trees in one (or several) censuses. 

```{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)
  )
```

```{r plot-agb-scbi, fig.width = 6, fig.height = 5}
plot(
  x = scbi_stem1$dbh,
  y = scbi_stem1$agb,
  col = factor(scbi_stem1$genus),
  xlab = "DBH (cm)",
  ylab = "AGB (kg)"
)
```

## How AGB is estimated 

### Attribute a weight to each equation in the equation table for each taxon/location combination

Within the `get_biomass()` function, new allometric equations are calibrated for each taxon/location combinations in the user-provided dataframe. This is done by attributing a weight to each equation in the equation table, based on its sampling size, and taxonomic and climatic similarity with the taxon/location 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)
```

### Resample equations 

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, fig.width = 6, fig.height = 5}
df_resample <-
  resample_agb(
    genus = "Acer",
    species = "rubrum",
    coords = c(-78, 38),
    nres = 1e4
  )

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

### Calibrate a new equation for each taxon/location combination

The resampled values are then used to fit the following nonlinear model: $AGB = a \cdot dbh ^ b + e$, with i.i.d. $e \sim \mathcal{N}(0, sigma^2)$. The parameters (_a_, _b_, and _sigma_) are returned by the `est_params()` function. In other words, this function calibrates new allometric equations from sampling previous ones. New allometric equations are calibrated for each species and location by resampling the original compiled equations; equations with a larger sample size, and/or higher taxonomic rank, and climatic similarity with the species and location in question are given a higher weight in this process.

```{r est-params-acer, fig.width = 6, fig.height = 5}
pars_acer <- est_params(
  genus = "Acer",
  species = "rubrum",
  coords = c(-78, 38)
)
plot(
  df_resample$dbh,
  df_resample$agb,
  xlab = "DBH (cm)",
  ylab = "Resampled AGB values (kg)"
)
curve(pars_acer$a * x^pars_acer$b,
  add = TRUE, col = 2, lwd = 2
)
```

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

```{r est-params-all}
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. 

## Visualize the recalibration of equations

The recalibrated equation for one taxon/location combination can be easily visualized with the `illustrate_allodb()` function, which returns a ggplot (see package `ggplot2`) with all resampled values, and the top equations used displayed in the legend. The user can control the number of equations and equation information shown in the legend. The red dotted line is the recalibrated equation used in the `get_biomass()` function. 

```{r illustrate-allodb, fig.height = 4, fig.width=8}
illustrate_allodb(
  genus = "Acer",
  species = "rubrum",
  coords = c(-78, 38)
)
```

```{r illustrate-allodb2, fig.height = 5, fig.width=10}
illustrate_allodb(
  genus = "Acer",
  species = "rubrum",
  coords = c(-78, 38),
  neq = 15,
  eqinfo = c("equation_taxa", "geographic_area")
)
```