plant: A package for modelling forest trait ecology and evolution

The plant package for R is an extensible framework for modelling size- and trait-structured demography, ecology and evolution in simulated forests. At its core, plant is an individual-based model where plant physiology and demography are mediated by traits. Individual plants from multiple species can be grown in isolation, in patches of competing plants or in metapopulations under a disturbance regime. These dynamics can be integrated into metapopulation-level estimates of invasion fitness and vegetation structure. Accessed from R, the core routines in plant are written in C++. The package provides for alternative physiology models and for capturing trade-offs among parameters. A detailed test suite is provided to ensure correct behaviour of the code.

Development status. Active development happens on the develop branch, which is currently well ahead of the most recent tagged release. Notably, develop includes a new physiological model, TF24, which we plan to document and ship in an upcoming release. If you want the latest features (including TF24), install from develop (see Installation); for a stable, citable version, install a tagged release.

Current development is tracked on our project board and in the issue tracker — that's the best place to see what's planned, report bugs, or pick up something to contribute.

The plant model family

The plant model is developed across three companion repositories, with work
coordinated on a shared project board
("Plant model development"):

Issues from all three repositories feed into the
project board, which is the
single place to see what is planned, in progress, or done across the family.

Citation

Falster DS, FitzJohn RG, Brännström Å, Dieckmann U, Westoby M (2016) plant: A package for modelling forest trait ecology & evolution. Methods in Ecology and Evolution 7: 136-146. doi: 10.1111/2041-210X.12525

Documentation

An overview of the plant package is given by the above publication. Further background on the default FF16 growth model is available in Falster et al 2011 (10.1111/j.1365-2745.2010.01735.x) and Falster et al 2017 (10.1101/083451).

The narrative documentation — user guides, theory, and worked examples — now lives at Overstorey, a dedicated field guide to the plant model (source). The package's own pkgdown site hosts the API/function reference. Initial versions of some of this material were also included as supplementary material with the publication about plant, which can be accessed here.

Package structure

Plant is a complex package, using C++20 behind the scenes for speed with R6 classes (via the Rcpp and RcppR6 packages). In this blog post, Rich FitzJohn and I describe the key technologies used to build the plant package.

If you are interested in developing or extending plant, start with agents.md, which documents the package architecture, the C++/R interface, the build workflow, and how to add a new model. The plant-new-strategy skill (.claude/skills/plant-new-strategy/) walks through scaffolding and implementing a new strategy.

Installation

Requirements

• You must be using R 4.5.0 or newer. At this stage the package is not on CRAN. Your options for installing are described below.

• Installation requires a C++20 compatible compiler (recent versions of clang/gcc on macOS and Linux satisfy this). On Windows machines you will need to install Rtools. When I tried this in Rstudio, the program automagically sensed the absence of a compiler and asked if I wanted to install Rtools. Click Yes!

Option 1, using remotes::install_github

The plant package can be installed direct from github using the remotes package:

remotes::install_github("traitecoevo/plant", dependencies=TRUE)

To install a specific (older) release, decide for the version number that you want to install in https://github.com/traitecoevo/plant/releases e.g.

remotes::install_github("traitecoevo/plant@v1.0.0", dependencies=TRUE)

with "v1.0.0" replaced by the appropriate version number. Note, the latest version of plant resides on the develop branch, which is sporadically released. plant follows semantic versioning meaning that major version indicate a potential break in backward compatibility.

Option 2, building from source

If familiar with git you might find it easiest to build plant directly from the source code. This is most useful if developing new models or strategies, or to contribute new features.

First, clone the plant repository

git clone https://github.com/traitecoevo/plant

Open an R session in the folder, then to install dependencies run

devtools::install_deps()

Then to compile the project

devtools::install()

or

devtools::load_all()

Getting started

The best place to start is Overstorey, which hosts the full narrative documentation and a set of tutorial guides. In particular:

• Get started with plant — an overview of the package and a minimal worked example.
• Individuals, Patch dynamics and Demography — the core simulation workflows.
• Parameters — configuring strategies, traits and control settings.

The package's pkgdown site hosts the function reference.

A minimal example, growing a patch of competing plants with the default FF16 model:

library(plant)

# Set up parameters for the default FF16 model and add a strategy
p <- scm_base_parameters("FF16")
p <- add_strategies(p, trait_matrix(0.0825, "lma"))

# Run the deterministic (method-of-characteristics) solver and collect output
results <- run_scm(p, collect = TRUE)

If you want to develop or extend plant (e.g. add a new strategy/model), see agents.md and the plant-new-strategy skill (.claude/skills/plant-new-strategy/).

Benchmarking

For fair performance comparisons across branches, rebuild compiled code before
running benchmarks:

make
Rscript -e "devtools::load_all(quiet=TRUE); run_plant_benchmarks()"

Running benchmarks without a fresh make can compare stale binaries and give
misleading timing differences.

Reporting issues

Questions, bug reports and feature requests are welcome via the
GitHub issue tracker. New issues are
automatically added to the project board
with status Backlog.

To keep the board sortable, please:

1. Apply one type label — the three repositories share the same set:

   • bug — an existing feature not functioning as intended
   • task — a discrete piece of work needed for a feature
   • epic — a new feature or capability, usually an umbrella over several tasks

2. Prefix the title with a theme tag in square brackets, e.g.
   [speed] Cache the light-environment spline. Use an existing theme where it
   fits; otherwise [other]:

   [TF24 hydraulics] · [TF24 allometry] · [TF24 nsc] · [acclimation] ·
   [simplify interface] · [evol assembly] · [Env drivers] · [speed] ·
   [patch variations] · [documentation] · [other]

A title may carry more than one tag when it genuinely spans themes
(e.g. [speed] [TF24 hydraulics] …).

Publications using plant

Here are some example publications using plant:

• Falster DS, FitzJohn RG, Brännström Å, Dieckmann U, Westoby M (2016) plant: A package for modelling forest trait ecology & evolution. Methods in Ecology and Evolution 7: 136-146. DOI: 10.1111/2041-210X.12525  code: github
• Falster DS, Duursma RA, FitzJohn RG (2018) How functional traits influence plant growth and shade tolerance across the life cycle. Proceedings of the National Academy of Sciences 115: E6789–E6798. DOI: 10.1073/pnas.1714044115  code: github
• Falster DS, Kunstler GK, FitzJohn RG, Westoby M (2021) Emergent shapes of trait-based competition functions from resource-based models: a Gaussian is not normal in plant communities. The American Naturalist 198: 256–267. DOI: 10.1086/714868  code: github

Contributing

Contributions are welcome. By submitting a pull request or code to this repository, you agree to the terms of the Contributor License Agreement.

Plant family

plant is part of the plant family of packages in the
traitecoevo org, built around the
plant forest model. Docs hub:
https://traitecoevo.github.io/overstorey/.

Contributing: please skim the family
issue guide
before filing — issues across the family are triaged on
board #5, and cross-package context lives in
plant-meta.