General structure and goals

The biomass development is divided in two major components: (1) a database of allometric equations – i.e. the allodb package); and (2) functions that use those allometric ecuations from allodb to calculate biomass – i.e. the bmss package.

The two major components of the biomass development.

• The goal of allodb is to develop, host and give access to tables of allometric equations. (These tables are required to calculate biomass; you will see this below.)

A minimal example of tables in the allodb package.

• The goal of bmss is to calculate above ground biomass based on a table of biomass equations from allodb. bmss has three jobs:

  1. To decide which allometric equation to use for each individual stem;
  2. To calculate biomass, given an apprpriate allometric equation, for each individual stem.
  3. To Summarize the biomass of multiple stems within user-defined groups.

The three jobs of the bmss package.

The benefit of this structure is that it allows allodb and bmss to evolve independently. For example, we can update the database of allometric equations (allodb) while keeping intact the functions to calculate biomas (bmss); and viceversa. Another benefit is that the discussions about any one package can focus on that package’s specific goals. This means that notifications about one package (e.g. bmss) won’t bother the collaborators of the other package (e.g.allodb).

Comparision with previous structure

As Gabriel explained before (https://goo.gl/Mw2kBV), we had previously considered writing a funciton to calculate biomass using the allometric equationd for tropical forests published in Chave J, et al. (2014). But we now know that such functionality is already and well implemented in the BIOMASS package (Réjou-Méchain M, Tanguy A, Piponiot C, Chave J, Hérault B. 2017).

Instead, we now plan to specifically focus on ForestGEO’s sites: Our new goal is to compute all the required parameters (e.g. via BIOMASS) and produce a table with one allometric equation per site, species, or whatever useful category. That table will of course have gaps; but while new research fills those gaps, we can start using what we have.

Design

For an overview of the entire design see http://popplet.com/app/#/4303845.

allodb: What Goes Here and Where?

allodb is meant not to have functions but data. So instead of a code prototype, we describe what data it will host and where it will be placed. allodb will receive multiple tables of allometric equations from multiple researchers (e.g. Helene et al., Krista et al.). These are sume ideas to organize and clean those contributed tables:

1. Store the raw tables in either inst/extdata (if we want users to access each of the contributed tables) or in data-raw/ (if we do not want users to access those contributed tables);
2. Indicate who contributed to what equations – maybe in a variable that persists in the final versions of the table, so the users can see the credit;
3. clean each raw tables – a good place for the “clearner-code” is data-raw/;
4. compose all contributions into a single table – a good place for the “composer-code” is data-raw/.

Where to place data and code to clean it (via https://goo.gl/2Rbp2q and https://goo.gl/KGXXnm).

# Add a unique identifier to the user's data.
add_id) <- function(dbh) {
  # Identify each unique dbh in the user's data.
}

# Use specific equations that the user provides.
use_eqn <- function(dbh, eqn, ...) {
  # Reformat user's data so it can be combined with tables from allodb.
}

# Get equations for stems which the user has not provided equations for.
get_eqn <- function(site, spp, eqn, ...) {
  # Get sites' and species' table.
  # Exclude irrelevant sites and species.
}

# Combine equations from the user and from the allodb package.
join_eqn <- function(use_eqn(...), get_eqn()) {
  # Join user's and allodb's equations' tables to produce a table with one
  # equation for ech dbh that the user provided.
  
  # Case when user provides an equation for a specific dbh:
  #   Use that equation.
  # Case when user provides not an equation for a specific dbh:
  #   Use the most specific equation possible.
}

# Output the equations' table actually used.
show_eqn <- function(join_eqn(...)) {
  # Transform join_eqn() so the output is most informative.
}

# Output a table with one biomass result per stem.
biomass_per_individual <- function(...) {
  # Evaluate the allometric equations for each individual dbh measurement.
}

# Output a summary of the biomass of multiple stems by user-defined groups.
biomass <- function(groups, smry_fun, ...) {
  # Group by groups.
  # Apply the summary function to all stems within those groups.
}

References

@article{RN4652,
   author = {Réjou-Méchain, Maxime and Tanguy, Ariane and Piponiot, Camille and Chave, Jérôme and Hérault, Bruno},
   title = {biomass: an r package for estimating above-ground biomass and its uncertainty in tropical forests},
   journal = {Methods in Ecology and Evolution},
   volume = {8},
   number = {9},
   pages = {1163-1167},
   ISSN = {2041-210X},
   DOI = {10.1111/2041-210X.12753},
   url = {http://dx.doi.org/10.1111/2041-210X.12753},
   year = {2017},
   type = {Journal Article}
}

@article{RN4653,
   author = {Chave, Jérôme and Réjou-Méchain, Maxime and Búrquez, Alberto and Chidumayo, Emmanuel and Colgan, Matthew S. and Delitti, Welington B. C. and Duque, Alvaro and Eid, Tron and Fearnside, Philip M. and Goodman, Rosa C. and Henry, Matieu and Martínez-Yrízar, Angelina and Mugasha, Wilson A. and Muller-Landau, Helene C. and Mencuccini, Maurizio and Nelson, Bruce W. and Ngomanda, Alfred and Nogueira, Euler M. and Ortiz-Malavassi, Edgar and Pélissier, Raphaël and Ploton, Pierre and Ryan, Casey M. and Saldarriaga, Juan G. and Vieilledent, Ghislain},
   title = {Improved allometric models to estimate the aboveground biomass of tropical trees},
   journal = {Global Change Biology},
   volume = {20},
   number = {10},
   pages = {3177-3190},
   ISSN = {1365-2486},
   DOI = {10.1111/gcb.12629},
   url = {paper: http://dx.doi.org/10.1111/gcb.12629
supplement: http://chave.ups-tlse.fr/pantropical_allometry.htm},
   year = {2014},
   type = {Journal Article}
}