rcontroll: individual-based forest growth simulator TROLL

rcontroll integrates the individual-based and spatially-explicit TROLL model to simulate forest ecosystem and species dynamics forward in time. rcontroll provides user-friendly functions to set up and analyse simulations with varying community compositions, ecological parameters, and climate conditions.

Description

TROLL is coded in C++ and it typically simulates hundreds of thousands of individuals over hundreds of years. The rcontroll R package is a wrapper of TROLL. rcontroll includes functions that generate inputs for simulations and run simulations. Finally, it is possible to analyse the TROLL outputs through tables, figures, and maps taking advantage of other R visualisation packages. rcontroll also offers the possibility to generate a virtual LIDAR point cloud that corresponds to a snapshot of the simulated forest.

Construction and manipulation of input files

As stated above, three types of input data are needed for a typical TROLL simulation: (i) climate data, (ii) plant functional traits, (iii) global model parameters. Pre-simulation functions include global parameters definition (generate_parameters function) and climate data generation (generate_climate function). rcontroll also includes default data for species and climate inputs for a typical French Guiana rainforest site. The purpose of the generate_climate function with the help of the corresponding vignette is to create TROLL climate inputs from ERA5-Land (Muñoz-Sabater et al. 2021), a global climatic reanalysis dataset that is freely available. The ERA5-Land climate reanalysis is available at 9 km spatial resolution and hourly temporal resolution since 1950, and daily or monthly means are available and their uncertainties reported. Therefore, rcontroll users only need to input the species-specific trait data to run TROLL simulations, irrespective of the site. TROLL was originally developed for tropical and subtropical forests, so certain assumptions must be critically examined when applying it outside the tropics. The input files can be used to start a TROLL simulation run within the rcontroll environment (see below), or saved so that the TROLL simulation can be started as a command line tool.

Simulations

The default option is to run a TROLL simulation using the troll function of the rcontroll package, which currently calls version 3.1.7 of TROLL using the Rcpp package (Eddelbuettel & François 2011). The output is stored in a trollsim R class. For multiple runs, users can rely on the stack function, and the output is stored in the trollstack class. Both trollsim and trollstack values can be accessed using object attributes in the form of simple R objects (with @ in R). They consist of eight simulation attributes: (1) name, (2) path to saved files, (3) parameters, (4) inputs, (5) log, (6) initial and final state, (7) ecosystem output metrics, and (8) species output metrics. The initial and final states are represented by a table with the spatial position, size and other relevant traits of all trees at the start and end of the simulation. The ecosystem and species metrics are summaries of ecosystem processes and states, such as net primary production and aboveground biomass, and they are documented at species level and aggregated over the entire stand. Simulations can be saved using a user-defined path when run and later loaded as a simple simulation (load_output function) or a stack of simulations (load_stack function).

Simulated airborne lidar scanning option

TROLL also has the capacity of generating point clouds from virtual aerial lidar scannings of simulated forest scenes. Within each cubic metre voxel of the simulated stand, points are generated probabilistically, with the probability depending both on the amount of light reaching the particular voxel and the amount of leaf matter intercepting light within the voxel. Extinction and interception of light are based on the Beer-Lambert law, but an effective extinction factor is used to account for differences between the near-infrared and visible light. The definition of the lidar parameters (generate_lidar function) is optional but allows the user to add a virtual aerial lidar scan for a time step of the TROLL simulation. When this option is enabled, the cloud of points from simulated aerial lidar scans are stored as LAS using the R package lidR (Roussel et al., 2020) as a ninth attribute of the trollsim and trollstack objects.

Manipulation of simulation outputs

rcontroll includes functions to manipulate simulation outputs. Simulation outputs can be retrieved directly from the trollsim or trollstackobjects and summarised or plotted in the R environment with the print, summary and autoplot functions. The get_chm function allows users to retrieve canopy height models from aerial lidar point clouds (Fig. 2). In addition, a rcontroll function is available to visualise TROLL simulations as an animated figure (autogif function, Fig. 1).

Installation

You can install the latest version of rcontroll from Github using the devtools package:

if (!requireNamespace("devtools", quietly = TRUE))
  install.packages("devtools")

devtools::install_github("sylvainschmitt/rcontroll")

Usage

library(rcontroll)
data("TROLLv3_species")
data("TROLLv3_climatedaytime12")
data("TROLLv3_daytimevar")
sim <- troll(name = "test",
             global = generate_parameters(iterperyear = 12, nbiter = 12*1),
             species = TROLLv3_species,
             climate = TROLLv3_climatedaytime12,
             daily = TROLLv3_daytimevar)
autoplot(sim, what = "species", 
         species = c("Cecropia_obtusa","Dicorynia_guianensis",
                     "Eperua_grandiflora","Vouacapoua_americana")) +
  theme(legend.position = "bottom")