Package {FINN}


Type: Package
Title: Forest Informed Neural Networks
Version: 0.2.0
Maintainer: Yannek Käber <y.kaeber@posteo.de>
Description: A hybrid dynamic forest (gap) model (FINN) that can be configured as a fully mechanistic, process-based model, like classic forest gap models, or with its demographic processes (growth, mortality, regeneration) replaced by deep neural networks (DNNs), or any combination of the two. Provides functions to define a model and its mechanistic or empirical components, calibrate it to forest inventory data, and interpret the calibrated processes. FINN is implemented with the 'torch' package, which supplies GPU support and the automatic differentiation used to calibrate the model by stochastic gradient descent; no knowledge of 'torch' is required. The hybrid modeling approach is described in Pichler and Käber (2026) <doi:10.1111/2041-210x.70347>.
License: GPL (≥ 3)
Encoding: UTF-8
LazyData: true
URL: https://github.com/FINNverse/FINN, https://finnverse.github.io/FINN/
BugReports: https://github.com/FINNverse/FINN/issues
Depends: R (≥ 4.1.0)
LinkingTo: Rcpp
Imports: abind, cli, stats, utils, data.table, coro, Rcpp, torch, ggplot2, glue, grid
Suggests: testthat (≥ 3.0.0), knitr, rmarkdown
RoxygenNote: 7.3.3
VignetteBuilder: knitr
Config/testthat/edition: 3
NeedsCompilation: yes
Packaged: 2026-11-19 15:14:42 UTC; yannekkaber
Author: Maximilian Pichler ORCID iD [aut], Yannek Käber ORCID iD [aut, cre]
Repository: CRAN
Date/Publication: 2026-11-19 16:30:20 UTC

FINN: Forest Informed Neural Networks

Description

FINN is a differentiable forest gap model. A forest is represented as cohorts of same-species, same-size trees that are updated each timestep by four demographic processes — competition, growth, mortality and regeneration. Each process can be a mechanistic function, a neural network, or a mixture of the two, and the whole model is calibrated end-to-end by gradient descent through the simulation (implemented in torch).

Getting started

The functions in the order of a typical analysis:

  1. Prepare the data. makeObsData(), resolveSiteIDs() and makeInitCohorts() turn a raw tree list into FINN's input tables: the observations, the environment of every year and the initial cohorts (finn_data).

  2. Build the model. finn() assembles one process per component (growth, mortality, regeneration, competition), each built with createProcess() (mechanistic, with a linear or neural-network response to the environment) or createHybrid() (a neural network).

  3. Fit it. fit() estimates all processes jointly against all observed responses; its argument holdout evaluates the model right after the fit.

  4. Evaluate it. evaluate() compares simulations with the observations of the training data and a holdout and returns the result (also kept in the model); comparePlot() draws observed against simulated, as a scatter page, a heatmap per species or a time series; summary.finn_class() shows the skill, the convergence of the fit and the effects of the environment.

  5. Look inside. plot.finn_class() draws the fitted parameters, ALE() the effects of the environment, also of a neural network.

  6. Simulate. simulateForest() runs the model forward, also from bare ground (bare_ground = TRUE); plot.finn_simulation() draws the result.

The vignettes give a guided tour: browseVignettes("FINN").

Author(s)

Maintainer: Yannek Käber y.kaeber@posteo.de (ORCID)

Authors:

See Also

Useful links:

Examples


library(data.table)
# the bundled Oregon FIA data: observations, environment and initial trees
Nsp   <- max(fia_obs_dt$species)
train <- 1:4; hold <- 5:6
init  <- makeInitCohorts(fia_init_trees[siteID %in% train], Nspecies = Nsp)

# build the model: the environmental responses as linear functions of
# temperature and precipitation
FINN.seed(1)
m <- finn(N_species = Nsp, recruits_dbh = 12.9,
          growth_process       = createProcess(~ temp + prec, growth),
          mortality_process    = createProcess(~ temp + prec, mortality),
          regeneration_process = createProcess(~ temp + prec, regeneration_capped))

# fit all processes jointly (a real calibration runs hundreds of epochs)
fit(m, data = fia_obs_dt[siteID %in% train], env = fia_env_dt[siteID %in% train],
    init_cohort = init, epochs = 3L, patch_size = 0.06, plot_progress = FALSE)

# evaluate on two sites the model has not seen, with a bare-ground run
ev <- evaluate(m, holdout = list(
  data = fia_obs_dt[siteID %in% hold], env = fia_env_dt[siteID %in% hold],
  init_cohort = makeInitCohorts(fia_init_trees[siteID %in% hold], Nspecies = Nsp)),
  bare_ground = TRUE, years = 100)
plot(ev)                         # observed against simulated
plot(ev, type = "bare_ground")   # succession from an empty stand

# skill, convergence and environmental effects; the fitted parameters
summary(m)
plot(m)


Accumulated local effect plots

Description

Calculates accumulated local effects (ALE) for the three processes

Usage

ALE(
  model,
  env = NULL,
  init_cohort = NULL,
  env_autoscale = TRUE,
  sim_seed = 42L,
  plot = TRUE,
  process = NULL,
  scale = FALSE,
  ...
)

Arguments

model

(finn_class)
Model object of class finn_class.

env

(data.table|data.frame)
Environmental covariates for which the ALE should be calculated. If NULL (default) the training env cached by fit() is used.

init_cohort

(CohortMat)
Initial cohort of class CohortMat. If NULL (default) the training init_cohort cached by fit() is used (or bare ground if none was cached).

env_autoscale

(logical(1))
If TRUE (default) env is assumed to be on the raw (unscaled) scale and the model's stored env_scaling is applied internally before the effects are computed, mirroring how the model was fitted (see fit()'s env_autoscale). Set FALSE if env is already on the model scale, or for a model fitted without autoscaling.

sim_seed

(integer(1))
Seed applied via FINN.seed() before the state-harvesting simulation, so the (stochastic) conditional effects / ALE are reproducible and cacheable. NULL disables seeding.

plot

(logical(1))
If TRUE (default) an ALE plot is drawn via plot.FINNale() (rows = processes, columns = environmental predictors, one coloured line per species).

process

(character|NULL)
If given (one of "growth", "mortality", "regeneration") only that process is plotted. NULL (default) plots all three.

scale

(logical(1))
Only for the plot (plot = TRUE): if TRUE each drawn curve is divided by the SD of its process x species rate, yielding dimensionless, comparable effects (the curve's variance then equals the Sobol-style normalised importance). The returned tables are not changed; they carry the SD as rate_sd. Default FALSE.

...

Not supported yet.

Value

A list of class FINNale with one table per process (⁠$growth⁠, ⁠$mortality⁠, ⁠$regeneration⁠). Each table gives the accumulated local effect (ale, on the scale of the process rate) of every driver (var) across its observed range (x), per species, and rate_sd, the SD of that process x species rate. When plot = TRUE the effects are also drawn.

See Also

plot.FINNale() to draw the curves, conditionalEffects() and averageConditionalEffects() for the local slopes behind them, summary.finn_class() and feature_importance() for variable importance

Examples


library(data.table)
# a small model fitted on three Oregon FIA sites (?fia_obs_dt, ?fit); the NN
# variant is the same call with `hidden = c(10, 10)` on the process
sites <- 1:3
Nsp   <- max(fia_obs_dt$species)
init  <- makeInitCohorts(fia_init_trees[siteID %in% sites], Nspecies = Nsp)
FINN.seed(1)
m <- finn(
  N_species            = Nsp, recruits_dbh = 12.9,
  growth_process       = createProcess(~ temp + prec, FINN::growth,
                                       optimizeSpecies = TRUE, optimizeEnv = TRUE),
  mortality_process    = createProcess(~ temp + prec, FINN::mortality,
                                       optimizeSpecies = TRUE, optimizeEnv = TRUE),
  regeneration_process = createProcess(~ temp + prec, FINN::regeneration,
                                       optimizeSpecies = TRUE, optimizeEnv = TRUE))
fit(m, data = fia_obs_dt[siteID %in% sites], env = fia_env_dt[siteID %in% sites],
    init_cohort = init, epochs = 2L, patches = 4, patch_size = 0.06, plot_progress = FALSE)

# accumulated local effects of every driver, per process and species. `env` and
# `init_cohort` default to the ones fit() cached, so the curves are read over
# exactly the range the model was trained on.
ale <- ALE(m, plot = FALSE)
head(ale$growth)

# the curves of one process, one panel per driver and one line per species;
# `scale = TRUE` divides each drawn curve by the SD of its process x species
# rate, so that the panels of different processes become comparable
ALE(m, process = "growth", scale = TRUE)


Calculate the Basal Area of a Stand

Description

This function calculates the basal area of a stand based on the diameter at breast height (dbh), the number of trees, and the patch size in hectares.

Usage

BA_stand(dbh, trees, patch_size_ha)

Arguments

dbh

A torch tensor or numeric vector representing the diameter at breast height of the trees in centimeters.

trees

A torch tensor or numeric vector representing the number of trees.

patch_size_ha

A numeric value representing the size of the patch in hectares.

Details

The basal area of a stand is the cross-sectional area of all trees in a stand per unit area. This function calculates the basal area per ha using the formula:

BA = \left( \frac{\pi \left( \frac{\text{dbh}}{100} \right)^2}{4} \right) \times \text{trees} \div \text{patch\_size\_ha}

The formula takes into account the diameter at breast height (dbh) in centimeters, the number of trees, and the size of the patch in hectares to calculate the basal area in square meters per hectare.

This plot illustrates the basal area for different combinations of dbh and number of trees.

dbh, trees, basal area

Sensitivity of basal area for different combinations of dbh, number of trees to patch size.

Patch size, dbh, trees, basal area

Value

An object of the type and shape of dbh (a torch.Tensor for tensors): the basal area of each cohort in square meters per hectare.

See Also

BA_stem() for one stem, competition(), which turns the basal area of the taller cohorts into the light a cohort receives

Examples


# three cohorts on a patch of 0.1 ha: two 50-cm trees, ten 20-cm trees and
# forty 5-cm trees
cohorts <- data.frame(siteID = 1, patchID = 1, cohortID = 1:3, species = 1,
                      dbh = c(50, 20, 5), trees = c(2, 10, 40))
cohort <- CohortMat(obs_df = cohorts)
ba <- BA_stand(cohort$dbh, cohort$trees, patch_size_ha = 0.1)
ba          # m^2/ha per cohort, [sites, patches, cohorts]
ba$sum()    # the stand: 7.9 m^2/ha

# the same trees on a patch half the size are twice the basal area per hectare
BA_stand(cohort$dbh, cohort$trees, patch_size_ha = 0.05)$sum()

# numeric vectors work as well
BA_stand(dbh = c(50, 20, 5), trees = c(2, 10, 40), patch_size_ha = 0.1)


Calculate the basal area of a tree given the diameter at breast height (dbh)

Description

This function calculates the basal area of a tree given the diameter at breast height (dbh): the area of a circle of that diameter, pi * (dbh / 200)^2, in square metres for a dbh in centimetres. It is the tensor counterpart of dbh2ba().

Usage

BA_stem(dbh)

Arguments

dbh

torch.Tensor (or numeric vector) The diameter at breast height of the tree, in cm.

Value

An object of the type of dbh (a torch.Tensor for a tensor) with the basal area of one stem, in m^2.

See Also

BA_stand() for the basal area per hectare of a cohort, dbh2ba()

Examples


# one stem of 10, 30 and 50 cm: 0.008, 0.071 and 0.196 m^2
dbh = torch::torch_tensor(c(10, 30, 50))
basal_area = BA_stem(dbh)
print(basal_area)

# the same numbers without torch
BA_stem(c(10, 30, 50))


Cohort Matrix Class

Description

A torch nn_module holding the cohorts of every site and patch as three aligned tensors – dbh, trees and species – each shaped ⁠[sites, patches, cohorts]⁠. It is FINN's initial state: build it from an inventory with makeInitCohorts() or from a cohort table with obs_df, and pass it to fit(), predict.finn_class() or simulateForest() as init_cohort. The three tensors are registered as buffers, so a CohortMat moves between devices with the model and carries no gradient. asDF() converts it back to a cohort table (a data.frame with siteID, patchID, cohortID, species, dbh, trees).

Build the cohort tensors, either from a cohort table (obs_df) or from arrays of dbh, trees and species

Store a plain R copy of the cohort arrays (used by restore())

Rebuild the tensors from the stored R copy when they are no longer valid, as after readRDS() of a saved CohortMat (or of the list resolveSiteIDs() returns) in a new session

Convert the cohort tensors back to a cohort table

Usage

CohortMat(
  obs_df = NULL,
  dbh = NULL,
  trees = NULL,
  species = NULL,
  dims = c(50, 30, 10),
  sp = 10,
  device = "cpu"
)

Arguments

obs_df

A data frame containing columns "siteID", "patchID", "species", "dbh", and "trees". If provided, it will be used to initialize the tensors.

dbh

A tensor or array representing the diameter at breast height. Defaults to self$dbh.

trees

A tensor or array representing the number of trees. Defaults to self$trees.

species

A tensor or array representing the species. Defaults to self$species.

dims

A numeric vector representing the dimensions of the arrays (sites, patches, cohorts). Defaults to self$dims.

sp

An integer representing the number of species. Defaults to self$sp.

device

A character string specifying the device to use ('cpu' or 'cuda'). Defaults to self$device.

Value

A CohortMat, a torch nn_module whose dbh, trees and species buffers hold the cohorts as ⁠[sites, patches, cohorts]⁠ tensors.

The CohortMat, invisibly.

A data.frame with one row per cohort and the columns siteID, patchID, cohortID, species, dbh and trees.

Fields

dbh

A tensor representing the diameter at breast height for each cohort.

trees

A tensor representing the number of trees in each cohort.

species

A tensor representing the species of each cohort.

dims

A vector representing the dimensions of the arrays (sites, patches, cohorts).

sp

An integer representing the number of species.

dbh_r

A numeric array representing the diameter at breast height in R array format.

trees_r

A numeric array representing the number of trees in R array format.

species_r

An integer array representing the species in R array format.

device_r

A character string specifying the device in R format ('cpu' or 'cuda').

obsDF2arrays

Transforms data.table into array

site_ids

The user siteIDs in the order of the site dimension when the cohorts were built from obs_df (the lookup table from array position to user id); NULL when built from arrays, where the site dimension is 1:N.

See Also

makeInitCohorts() to build one from a tree list, obsDF2arrays() and array2obsDF() for the conversion between table and arrays, finn_data for the role of init_cohort

Examples


# from a cohort table: one site, two patches, three cohorts
cohorts <- data.frame(siteID = 1, patchID = c(1, 1, 2), cohortID = c(1, 2, 1),
                      species = c(1, 2, 1), dbh = c(35, 12, 20), trees = c(3, 10, 6))
init <- CohortMat(obs_df = cohorts, sp = 2)
init$dbh$shape   # sites x patches x cohorts
init$trees_r     # the same content as an R array; empty slots hold 0
init$asDF()      # and back to a table

# from arrays: every patch of two sites starts with one cohort of twenty
# 10-cm trees of species 1
dims <- c(2, 4, 1)
init2 <- CohortMat(dbh = array(10, dims), trees = array(20, dims),
                   species = array(1L, dims), dims = dims, sp = 2)
head(init2$asDF(), 3)

# trees of the bundled Oregon FIA data as an initial state (?fia_init_trees)
first3 <- fia_init_trees[fia_init_trees$siteID %in% 1:3, ]
init3 <- makeInitCohorts(first3, Nspecies = max(fia_init_trees$species))
init3$dims


Set Seed for Reproducibility in R and Torch

Description

This function sets the seed for both R's random number generator and Torch's random number generator, ensuring reproducibility across operations that involve both R and Torch.

Usage

FINN.seed(seed)

Arguments

seed

An integer value to set as the seed for both R and Torch. This ensures that random operations in both environments produce consistent results.

Details

The function calls set.seed() to set the seed for R's random number generator and torch::torch_manual_seed() to set the seed for Torch's random number generator. This is useful for ensuring reproducibility in scripts that rely on both R and Torch for random operations.

Value

This function does not return a value. It sets the seed internally for both R and Torch.

See Also

base::set.seed(), torch::torch_manual_seed()

Examples


# the same seed gives the same draws, in R and in torch
FINN.seed(123)
a <- c(runif(1), as.numeric(torch::torch_rand(1)))
FINN.seed(123)
b <- c(runif(1), as.numeric(torch::torch_rand(1)))
identical(a, b)

# seed before finn() and fit() to make a fit reproducible: the starting
# values of the parameters and the simulated deaths and recruits are random


Apply stored z-standardization to environmental predictors

Description

Re-applies the constants learned by compute_env_scaling() to env. The transformation uses the stored mean/sd only and never recomputes them from env, so calibration and prediction use an identical transformation (the usual pitfall of scale() inside a model formula is avoided).

Usage

apply_env_scaling(env, scaling)

Arguments

env

A data.frame/data.table of raw environmental data.

scaling

The data.frame returned by compute_env_scaling(), or NULL (in which case env is returned unchanged). For a model fit with env_autoscale = TRUE this is model$env_scaling.

Value

env with the scaled predictor columns, as a data.table.

See Also

compute_env_scaling, fit

Examples

# reproduce the standardization a model fit with env_autoscale = TRUE used:
env <- data.frame(siteID = 1:3, year = 1L, temp = c(4, 6, 8), prec = c(700, 850, 1000))
scaling <- compute_env_scaling(env)
scaling
apply_env_scaling(env, scaling)

# new sites are put on the scale of the first table, not on their own: a
# site at 6 degrees and 850 mm is the average site of `env`, so it maps to 0
new_env <- data.frame(siteID = 4:5, year = 1L, temp = c(6, 10), prec = c(850, 1150))
apply_env_scaling(new_env, scaling)

Transform Arrays to Observation Data Table

Description

This function transforms arrays of species, dbh, and trees back into a cohort table, the inverse of obsDF2arrays().

Usage

array2obsDF(obs_array)

Arguments

obs_array

A list containing three arrays species, dbh and trees, each of dimension sites x patches x cohorts.

Value

A data.frame with one row per cohort and the columns siteID, patchID, cohortID (the positions in the three array dimensions), species, dbh and trees. Slots with dbh of 0 or NA (no cohort) are left out.

See Also

obsDF2arrays(), CohortMat

Examples

# 2 sites x 2 patches x 2 cohort slots; a dbh of 0 marks an empty slot
obs_array <- list(
  species = array(c(1, 2), dim = c(2, 2, 2)),
  dbh = array(c(10, 20, 30, 0), dim = c(2, 2, 2)),
  trees = array(c(100, 200, 150, 0), dim = c(2, 2, 2)))
result <- array2obsDF(obs_array)
result   # six cohorts: the two empty slots are dropped


Average conditional effects of a FINN model

Description

Summarises the conditional effects into a per process x species x variable average marginal effect: the mean local derivative (mean_effect, an approximate linear effect). Derived cheaply from the cached conditional effects.

Usage

averageConditionalEffects(
  model,
  env = NULL,
  init_cohort = NULL,
  env_autoscale = TRUE,
  sim_seed = 42L,
  env_only = TRUE
)

Arguments

model

(finn_class)
fitted model.

env

(data.table|data.frame|NULL)
env covariates; NULL uses the cached training env.

init_cohort

(CohortMat|NULL)
initial cohort; NULL uses the cached training init_cohort.

env_autoscale

(logical(1))
see ALE().

sim_seed

(integer(1))
seed for the state-harvesting simulation (see ALE()).

env_only

(logical(1))
if TRUE (default) report only the environmental predictors of each process; if FALSE also include the stand-state inputs (dbh, light, growth) each process depends on.

Value

a named list (one entry per process) of data.frames with columns ⁠species, variable, mean_effect⁠.

See Also

conditionalEffects(), summary.finn_class(), which prints these effects

Examples


library(data.table)
# a small model fitted on three Oregon FIA sites (?fia_obs_dt, ?fit); the NN
# variant is the same call with `hidden = c(10, 10)` on the process
sites <- 1:3
Nsp   <- max(fia_obs_dt$species)
init  <- makeInitCohorts(fia_init_trees[siteID %in% sites], Nspecies = Nsp)
FINN.seed(1)
m <- finn(
  N_species            = Nsp, recruits_dbh = 12.9,
  growth_process       = createProcess(~ temp + prec, FINN::growth,
                                       optimizeSpecies = TRUE, optimizeEnv = TRUE),
  mortality_process    = createProcess(~ temp + prec, FINN::mortality,
                                       optimizeSpecies = TRUE, optimizeEnv = TRUE),
  regeneration_process = createProcess(~ temp + prec, FINN::regeneration,
                                       optimizeSpecies = TRUE, optimizeEnv = TRUE))
fit(m, data = fia_obs_dt[siteID %in% sites], env = fia_env_dt[siteID %in% sites],
    init_cohort = init, epochs = 2L, patches = 4, patch_size = 0.06, plot_progress = FALSE)

# one number per driver and process: the average slope over the observed range,
# which is the linear-model coefficient a mechanistic process would report and
# the closest thing a neural-network process has to one
ace <- averageConditionalEffects(m)
head(ace$growth)
# with the stand-state inputs of each process (dbh, light, ...) as well
head(averageConditionalEffects(m, env_only = FALSE)$mortality)


Draw binomial counts from per-trial Bernoulli probabilities

Description

The mortality draw selected with createProcess(mortality_draw = "bernoulli"): every element of n gets max(n) reparameterised Bernoulli trials with probability p, of which the first n are kept and summed. The result is integer-valued and matches the binomial in mean and variance, and it keeps a gradient path to p (a straight-through sigmoid) and to n (a soft mask). The price is memory: the trials are laid out along an extra dimension of length max(n), so the cost grows with the largest cohort.

Usage

binomial_from_bernoulli(n, p)

Arguments

n

torch.Tensor Number of Bernoulli trials (trees at risk) per element, with at least two dimensions (FINN passes ⁠[sites, patches, cohorts]⁠) and a largest value of at least 1.

p

torch.Tensor Success (death) probability per element, of the shape of n.

Value

A torch tensor of the shape of n: the number of successes per element, a whole number between 0 and n.

See Also

binomial_from_gamma(), binomial_from_poisson(), createProcess() (mortality_draw)

Examples


FINN.seed(1)
# one site, 5000 patches, two cohorts of 5 and 40 trees, 30 % mortality
n <- torch::torch_tensor(array(rep(c(5, 40), each = 5000), dim = c(1, 5000, 2)))
p <- torch::torch_full(c(1, 5000, 2), 0.3)
deaths <- torch::as_array(binomial_from_bernoulli(n, p))
dim(deaths)
# binomial mean n * p = 1.5 and 12, variance n * p * (1 - p) = 1.05 and 8.4
sapply(c("n = 5" = 1, "n = 40" = 2),
       function(k) c(mean = mean(deaths[1, , k]), var = var(deaths[1, , k])))


Draw deaths from a Gamma matched to the binomial

Description

The mortality draw of FINN before 0.2.0, selected with createProcess(mortality_draw = "gamma"): a Gamma distribution with the mean n * p and the variance n * p * (1 - p) of the binomial, sampled with rsample() so that the draw carries a pathwise gradient to n and p. The draw is continuous, not an integer count; the simulation rounds it afterwards. See binomial_from_poisson() for what that rounding costs and createProcess() for the other draws.

Usage

binomial_from_gamma(n, p, sample_size = 1)

Arguments

n

torch.Tensor Number of trees at risk per cohort.

p

torch.Tensor Mortality probability per cohort, strictly between 0 and 1 (the Gamma's shape n * p / (1 - p) degenerates at both ends).

sample_size

integer Number of draws; only the default 1 is used by FINN (the leading sample dimension is dropped).

Value

A torch tensor of the shape of n with continuous, positive draws whose mean is n * p and whose variance is n * p * (1 - p).

See Also

binomial_from_poisson(), binomial_from_bernoulli(), createProcess() (mortality_draw)

Examples


FINN.seed(1)
n <- torch::torch_full(c(10000), 40)   # 10 000 cohorts of 40 trees
p <- torch::torch_full(c(10000), 0.3)
d <- as.numeric(binomial_from_gamma(n, p))
# the binomial has mean 12 and variance 8.4; the draws are not integers
c(mean = mean(d), var = var(d))
head(d, 3)


Draw deaths as a Bernoulli/Poisson count

Description

The alternative mortality draw, selected with createProcess(mortality_draw = "poisson"). The default since 0.2.0 is mortality_draw = "binomial", the exact binomial; binomial_from_gamma() (mortality_draw = "gamma") reproduces results published before 0.2.0. A cohort of one tree or fewer (n <= 1.5) is a Bernoulli trial and is drawn as one; every larger cohort is drawn from a Poisson capped at n.

Usage

binomial_from_poisson(n, p)

Arguments

n

torch.Tensor Number of trees at risk per cohort.

p

torch.Tensor Annual mortality probability per cohort.

Details

binomial_from_gamma() matches a Gamma to the binomial's first two moments and rsample()s it, which buys a pathwise gradient – the hazard it guards against is a discrete draw having no gradient at all. The forward pass then rounds that draw straight-through (finn-class.R), so the gradient flows through a quantity the simulation discards, and the rounded count delivers a measured 0.68-0.72 of the calibrated deaths for one-tree cohorts at annual probabilities of 0.01-0.10 (5e5 draws per probability; 0.76 at p = 0.26). This draw is integer-valued, exact in expectation for small n*p, and carries no pathwise gradient, which is how Lin et al. (2026) treat discrete events in a differentiable crop model: resolve them before differentiation and hold them fixed during gradient evaluation. The Bernoulli branch is not cosmetic – capping a Poisson at a one-tree cohort delivers only 88\ suppressed stem, which is the stem that decides thinning.

The choice shows up in the simulated stand rather than in a holdout score: a long simulation to equilibrium separates the two draws by a factor of several in basal area and stem number, while the fitted loss moves far less, because the rounded deficit is a bias on the trajectory and not on the parameters.

Value

A torch tensor of integer death counts, never exceeding n.

References

Lin et al. (2026). doi:10.48550/arXiv.2610.36827

See Also

binomial_from_gamma(), binomial_from_bernoulli(), createProcess() (mortality_draw)

Examples


FINN.seed(1)
# cohorts of one tree are Bernoulli trials, larger cohorts a capped Poisson
n <- torch::torch_tensor(rep(c(1, 40), each = 10000))
p <- torch::torch_full(c(20000), 0.1)
d <- as.numeric(binomial_from_poisson(n, p))
# mean deaths per cohort: expected 0.1 (one tree) and 4 (forty trees)
tapply(d, rep(c("n = 1", "n = 40"), each = 10000), mean)
range(d)   # whole trees, and never more than the cohort holds


Convert a climate data frame to a FINN environment array

Description

Reshapes a long-format climate table into the site x year x variable array FINN uses internally, auto-detecting the time resolution from the columns.

Usage

climateDF2array(climate_dt, env_vars)

Arguments

climate_dt

A data.frame/data.table of climate values in long format, with siteID, a time column (e.g. year), and one column per variable.

env_vars

character Names of the environmental variable columns to extract.

Value

A numeric array of environmental values indexed by site, time and variable: ⁠[site, year, variable]⁠ for a yearly table, ⁠[site, year, month, variable]⁠ with a month column and ⁠[site, year, month, day, variable]⁠ with a day column. Sites and years are in increasing order; the array has no dimnames, and the year axis holds only the years present in the table. A combination of siteID, year (and month, day where present) that appears more than once is an error, whether or not the rows are identical. Missing (siteID, year) combinations become NA in the array.

See Also

finn_data for the env table of fit(), which is converted with this function

Examples

library(data.table)
# yearly climate of three sites over 22 years -> array [site, year, variable]
env <- fia_env_dt[siteID %in% 1:3]
a <- climateDF2array(env, env_vars = c("temp", "prec"))
dim(a)
head(a[1, , ])                # site 1; the rows are the years 1, 2, ...

# a monthly table (siteID, year, month) gives a fourth dimension of 12 months
monthly <- CJ(siteID = 1:2, year = 2001:2002, month = 1:12)
monthly[, temp := 10 + 8 * sin((month - 4) / 12 * 2 * pi)]
dim(climateDF2array(monthly, env_vars = "temp"))

Compare a simulation with observations

Description

Pairs a simulation with the observed data and draws, per response, how well they agree. The simulation is aggregated the way fit() scores it: the stand states dbh, ba and trees at the census year, growth and mort compounded over the period_length years before the census (the geometric mean of 1 + g minus one; one minus the geometric-mean survival), and the expected recruits (r_mean_ha) summed over them for reg (see finn_loss and, for the observed columns, finn_data). An observation is placed as in fit(): its year is a year of the env the simulation was run with, and the simulated step is the position of that year among the years of env (for a plain site table, which does not carry those years, year is taken as the step itself). Observations of a site or a species that is not in the simulation, or of a year that is not simulated, are left out with a message. Both tables may come in long (variable, value) or wide form.

Usage

comparePlot(
  sim,
  obs,
  type = c("scatter", "timeseries", "heatmap"),
  species = NULL,
  response = NULL,
  sites = NULL,
  tree_data = NULL,
  n_species = 12L,
  species_names = NULL,
  ...
)

## S3 method for class 'finn_heatmap'
print(x, ...)

## S3 method for class 'finn_comparison'
print(x, ...)

Arguments

sim

The result of simulateForest() or predict() for the sites of obs, started from the same initial state (or its site table).

obs

Observations as makeObsData() returns them (wide), or long with variable and value; period_length, n_at_risk and n_died are used where present.

type

"scatter" (default), "heatmap" or "timeseries".

species

NULL (default) pools all species in one panel per response; species numbers draw one row of panels per species.

response

Responses to draw, any of "dbh", "ba", "trees", "growth", "mort", "reg" (and "dbh_max" with tree_data); NULL (default) all that are observed.

sites

Site ids to include; NULL (default) all.

tree_data

NULL (default), or the observed trees in the format of the tree_data of fit() (see finn_data: siteID, year, species, dbh at the start of the interval, and growth, died, period_length; the interval is taken from obs when the trees do not carry it): adds the largest diameter (dbh_max) to the comparison.

n_species

Number of species in the recruitment panel. Default 12.

species_names

Species names for the labels: a character vector in species order, a vector named by species number, or a table with species and species_name. NULL (default): the names the simulation carries from the model, else the species_name column of obs.

...

Unused.

x

A finn_comparison object (the scatter view of comparePlot()).

Details

plot(sim, obs) is the same as comparePlot(sim, obs) (see plot.finn_simulation()).

Value

type = "scatter": a finn_comparison object (a list of the ggplot panels scatter, mort and reg, which print() arranges on one page), invisibly; type = "heatmap": a finn_heatmap object (the panels skill and ratio, side by side when printed), invisibly; type = "timeseries": the ggplot object, invisibly. It is printed. The paired table is attached as attribute "matched" and the skill measures as "skill" (per response, and per species when species is given; the measures are described in summary.finn_class()).

See Also

evaluate(), which returns the same comparison and keeps it on the model, and summary.finn_class(), which prints it; plot.finn_simulation() for the simulation alone.

Examples


library(data.table)
sites <- 1:3
Nsp   <- max(fia_obs_dt$species)
init  <- makeInitCohorts(fia_init_trees[siteID %in% sites], Nspecies = Nsp)
FINN.seed(1)
m <- finn(N_species = Nsp, recruits_dbh = 12.9,
          growth_process       = createProcess(~ temp + prec, growth),
          mortality_process    = createProcess(~ temp + prec, mortality),
          regeneration_process = createProcess(~ temp + prec, regeneration_capped))
fit(m, data = fia_obs_dt[siteID %in% sites], env = fia_env_dt[siteID %in% sites],
    init_cohort = init, epochs = 2L, patches = 4, patch_size = 0.06,
    plot_progress = FALSE)
sim <- simulateForest(m, env = fia_env_dt[siteID %in% sites], init_cohort = init)
comparePlot(sim, fia_obs_dt[siteID %in% sites])
plot(sim, fia_obs_dt[siteID %in% sites], type = "timeseries", species = 1:2)


Compute the fraction of available light (light) for each cohort based on the given parameters

Description

This function calculates the fraction of available light for each cohort of trees based on their diameter at breast height (dbh), species, number of trees, and global parameters.

Usage

competition(
  dbh,
  species,
  trees,
  parComp,
  h = NULL,
  patch_size_ha,
  ba = NULL,
  cohortHeights = NULL,
  n_quantiles = 10,
  continuous = FALSE,
  light_mask = TRUE
)

Arguments

dbh

torch.Tensor Diameter at breast height for each cohort, in cm, ⁠[sites, patches, cohorts]⁠.

species

torch.Tensor (int64) species index for each cohort, ⁠[sites, patches, cohorts]⁠.

trees

torch.Tensor Number of trees in each cohort, ⁠[sites, patches, cohorts]⁠.

parComp

torch.Tensor Competition parameters, one row per species and two columns: the height parameter of height() and the competition strength.

h

(Optional) Defaults to NULL: the light each cohort receives at its own height. Any non-NULL value returns the light at the forest floor instead, one value per patch (⁠[sites, patches, 1]⁠), which is what the regeneration process is given; the value itself is not used.

patch_size_ha

numeric Patch size in hectares.

ba

torch.Tensor (Optional) Pre-computed basal area. Defaults to NULL.

cohortHeights

torch.Tensor (Optional) Pre-computed cohort heights. Defaults to NULL.

n_quantiles

integer Number of height quantiles used when continuous = FALSE. Defaults to 10.

continuous

logical Use the continuous competition formulation. Defaults to FALSE.

light_mask

logical Take the height quantiles over the live cohorts only (trees > 0.5), leaving every cohort's real height as the bin query. Defaults to TRUE since 0.2.0: unmasked, the padded cohort width is set by the widest site in the batch, so the same stand's light depends on which other sites happen to share its batch. FALSE reproduces earlier results. See createProcess() for the measurement.

Details

The light of a cohort is one minus the weighted basal area of the cohorts of its patch that are taller than it (by more than 0.1 m), light = max(0, 1 - sum(BA_taller * parComp[, 2] * 0.1)), where BA is the basal area in m^2/ha (BA_stand()) and the height comes from height() with the species' height parameter parComp[, 1]. With a competition strength of 0.2 (about the start value) a cohort under 50 m^2/ha of taller trees receives no light. In a model the function is the competition process, createProcess(func = competition); it takes no environment.

Value

torch.Tensor Fraction of available light (between 0 and 1) for each cohort, ⁠[sites, patches, cohorts]⁠; with h given, the light at the forest floor, ⁠[sites, patches, 1]⁠.

See Also

height(), BA_stand(), createProcess() (n_quantiles, continuous, light_mask), finn()

Examples


# the light of three cohorts on one 0.1 ha patch: two 50-cm trees, ten 20-cm
# trees and forty 5-cm trees of one species (height parameter 0.5,
# competition strength 0.2)
shape   <- c(1, 1, 3)
dbh     <- torch::torch_tensor(array(c(50, 20, 5), shape))
trees   <- torch::torch_tensor(array(c(2, 10, 40), shape))
species <- torch::torch_tensor(array(1L, shape), dtype = torch::torch_long())
parComp <- torch::torch_tensor(matrix(c(0.5, 0.2), nrow = 1))
# the tallest cohort is in full light, each smaller one is shaded by the
# basal area above it
competition(dbh, species, trees, parComp, patch_size_ha = 0.1, continuous = TRUE)
# the light that reaches the forest floor, where the recruits start
competition(dbh, species, trees, parComp, h = 0, patch_size_ha = 0.1)

# the light model as the competition process of a model. It takes no
# environment; `continuous = TRUE` compares every pair of cohorts instead of
# binning them into height quantiles
m <- finn(N_species = 2,
          competition_process = createProcess(func = competition, continuous = TRUE))

# a 30-year simulation from bare ground; an unfitted model uses `env` as
# given (no scaling constants yet), so the predictor is passed standardised
env <- data.frame(siteID = 1L, year = 1:30, temp = 0)
sim <- simulateForest(m, env = env, patches = 5, patch_size = 0.1)
tail(sim$wide$site)


Compute per-predictor environmental scaling

Description

Computes the centering and scaling constants of every numeric environmental predictor in env (all columns except the keys siteID and year), so they can be re-applied unchanged to new data at prediction time. Every supported mode is an affine map (x - center) / scale, so the stored (variable, center, scale) table is applied by apply_env_scaling and inverted by ALE unchanged, whatever the mode. A predictor with (near-)zero standard deviation is given scale = 1 (centred only) to avoid division by zero.

Usage

compute_env_scaling(env, spec = TRUE)

Arguments

env

A data.frame/data.table with siteID, year and the environmental predictor columns.

spec

how to scale each predictor. One of:

  • TRUE – z-standardise every predictor (center = mean, scale = sd); the default and the historical behaviour.

  • FALSE – handled by the caller (no scaling table computed).

  • a length-1 string applied to all predictors, or a vector/list with one entry per predictor. Entries may be:

    • "auto" z-standardise (mean / sd),

    • "identity" (alias "none") leave unchanged (center 0, scale 1),

    • "0to1" min-max to ⁠[0, 1]⁠ (center min, scale range),

    • a function f(x) returning list(center=, scale=) – a custom affine scaler (e.g. robust: function(x) list(center=median(x), scale=IQR(x))). Non-affine transforms are intentionally not supported because ALE needs an invertible mapping. Unnamed vectors/lists are matched to predictors by position; named ones by variable name (predictors not named default to "auto").

Value

A data.frame with columns variable, center, scale; or NULL if there are no numeric predictors. This is the object stored on a fitted model as model$env_scaling when it is fit with env_autoscale = TRUE.

See Also

apply_env_scaling, fit (env_autoscale), finn_data

Examples

# the constants fit(env_autoscale = TRUE) stores on a model for this table
compute_env_scaling(fia_env_dt)
# keep one predictor on its own scale
compute_env_scaling(fia_env_dt, spec = c(temp = "auto", prec = "identity"))
# min-max scaling for every predictor, or a custom (robust) scaler for one
head(compute_env_scaling(fia_env_dt, spec = "0to1"), 3)
robust <- function(x) list(center = median(x), scale = IQR(x))
head(compute_env_scaling(fia_env_dt, spec = list(temp = robust)), 3)

Conditional effects of a FINN model

Description

Computes (and caches on the model) the conditional effects — the local derivatives of each demographic process (growth, mortality, regeneration) with respect to its inputs, per process and per species. This is the shared primitive behind ALE(), averageConditionalEffects() and the analytical variable importance in summary.finn_class().

Usage

conditionalEffects(
  model,
  env = NULL,
  init_cohort = NULL,
  env_autoscale = TRUE,
  sim_seed = 42L
)

Arguments

model

(finn_class)
fitted model.

env

(data.table|data.frame|NULL)
env covariates; NULL uses the cached training env.

init_cohort

(CohortMat|NULL)
initial cohort; NULL uses the cached training init_cohort.

env_autoscale

(logical(1))
see ALE().

sim_seed

(integer(1))
seed for the state-harvesting simulation (see ALE()).

Value

an object of class FINNconditionalEffects (also cached on model$conditional_effects): a list with one element per process (growth, mortality, regeneration), each a list with one element per species holding the inputs the process was evaluated at (X), the local derivatives with respect to them (grads) and the predicted rate (pred).

See Also

averageConditionalEffects() for one number per driver, ALE() for the curves

Examples


library(data.table)
# a small model fitted on three Oregon FIA sites (?fia_obs_dt, ?fit); the NN
# variant is the same call with `hidden = c(10, 10)` on the process
sites <- 1:3
Nsp   <- max(fia_obs_dt$species)
init  <- makeInitCohorts(fia_init_trees[siteID %in% sites], Nspecies = Nsp)
FINN.seed(1)
m <- finn(
  N_species            = Nsp, recruits_dbh = 12.9,
  growth_process       = createProcess(~ temp + prec, FINN::growth,
                                       optimizeSpecies = TRUE, optimizeEnv = TRUE),
  mortality_process    = createProcess(~ temp + prec, FINN::mortality,
                                       optimizeSpecies = TRUE, optimizeEnv = TRUE),
  regeneration_process = createProcess(~ temp + prec, FINN::regeneration,
                                       optimizeSpecies = TRUE, optimizeEnv = TRUE))
fit(m, data = fia_obs_dt[siteID %in% sites], env = fia_env_dt[siteID %in% sites],
    init_cohort = init, epochs = 2L, patches = 4, patch_size = 0.06, plot_progress = FALSE)

# the local slope of each process with respect to each of its inputs, at the
# states the fitted model passes through: a list per process and species
ce <- conditionalEffects(m)
names(ce)
# species 1, growth: the inputs, the slopes and the predicted rate
str(ce$growth[[1]], max.level = 1)


Define a hybrid (deep-neural-network) demographic process for FINN

Description

Configures a process (growth, mortality, or regeneration) in which the entire process equation – not just its environmental-response function – is replaced by a deep neural network (DNN), for use as growth_process, mortality_process, or regeneration_process in finn(). This is the second ("Level 2") level of hybridization described by Pichler & Käber (2026); to replace only the environmental-response function while keeping the rest of the process mechanistic ("Level 1"), use createProcess() instead. competition_process must always be created with createProcess(), as the competition (light availability) process does not support full replacement by a DNN.

Usage

createHybrid(
  formula = NULL,
  optimize = TRUE,
  dispersion_parameter = 1,
  NN = NULL,
  dropout = 0.3,
  encoder_layers = 1L,
  hidden = c(50L, 50L),
  sample_regeneration = TRUE,
  transformer = TRUE,
  emb_dim = 20L,
  dim_feedforward = 256L,
  mortality_draw = c("binomial", "bernoulli", "poisson", "gamma"),
  regeneration_sampler = c("refined", "gaussian"),
  cap = c("all", "species"),
  prior = "max_obs_recruits",
  prior_lambda = 0.1,
  theta_floor = 0.5,
  optimizeTheta = TRUE,
  mortality_floor = 0.001,
  mortality_ceiling = 0.999
)

Arguments

formula

(formula)
Environmental predictors passed to the network, evaluated against the env data. Default NULL uses ~. (all available environmental covariates).

optimize

(logical(1))
Should the network's weights be estimated during fit()? Default TRUE.

dispersion_parameter

(numeric(1))
Initial dispersion parameter of the negative binomial distribution used to sample recruits, or its fixed value with optimizeTheta = FALSE. Only used when this object is the regeneration process. See recruitment.

NN

(nn_module)
Not supported in 0.2.0. A custom module was accepted and then ignored, so a non-NULL value now raises an error; shape the default network with hidden, dropout and transformer instead.

dropout

(numeric(1))
Dropout rate of the network. Default 0.3; the Barro Colorado Island case study of Pichler & Käber (2026) used 0.1.

encoder_layers

(integer(1))
Number of transformer encoder layers. Only used when transformer = TRUE.

hidden

(integer())
Hidden-layer sizes of the feed-forward network. Only used when transformer = FALSE.

sample_regeneration

(logical(1))
Should recruits actually be sampled from the negative binomial regeneration distribution (TRUE), or only its expectation used (FALSE)? Only used when this object is the regeneration process. With FALSE the expected number of recruits per patch is rounded, so wherever it is below 0.5 no recruit enters at all. See recruitment.

transformer

(logical(1))
Use a transformer encoder architecture (TRUE, default) or a feed-forward network (FALSE).

emb_dim

(integer(1))
Embedding dimension for the species/cohort/ environment features.

dim_feedforward

(integer(1))
Dimension of the feed-forward sublayer within each transformer encoder layer. Only used when transformer = TRUE.

mortality_draw

(character(1))
How the number of dead trees is drawn, "binomial" (default since 0.2.0), "bernoulli", "poisson" or "gamma"; see createProcess(). Only used when this object is the mortality process.

regeneration_sampler

(character(1))
How recruits are drawn, "refined" (default since 0.2.0) or "gaussian"; see createProcess(). Only used when this object is the regeneration process.

cap, prior, prior_lambda

Accepted for symmetry with createProcess(), but not used in 0.2.0: the hybrid regeneration network has no Beverton-Holt cap. See regeneration_capped() for the cap of the mechanistic process.

theta_floor

(numeric(1))
Lower bound on the recruit dispersion par_theta_recruits, default 0.5 since 0.2.0, 0 or NULL to leave it unbounded as in 0.1.0; see createProcess(). Only used when this object is the regeneration process. The floor keeps the fit stable. In one converged pair of fits on the German national forest inventory it calibrated the recruitment level as well as a fixed theta, but only after the parameters had settled; read the level once ⁠$param_history⁠ shows them settled, or fix theta (optimizeTheta = FALSE) for short fits. See recruitment.

optimizeTheta

(logical(1))
Should the recruit dispersion be estimated during fit()? Default TRUE; FALSE keeps it at dispersion_parameter, which is the choice when the recruitment level is to be calibrated; see createProcess() and recruitment. Only used when this object is the regeneration process.

mortality_floor, mortality_ceiling

(numeric(1))
The interval the mortality probability is clamped to per simulation step before the death draw, defaults 0.001 and 0.999; see createProcess(). Only used when this object is the mortality process.

Details

The network receives the same cohort- and site-level information that the corresponding mechanistic process equation would use – diameter at breast height, number of trees, available light, species identity and the site's environmental predictors (plus the growth rate, for the mortality process) – and predicts the process output directly. Species identity is passed through a learned embedding layer rather than treated as a categorical covariate with per-species coefficients, so the network can learn low-dimensional "contrasts" between species or plant functional types (PFTs). An inverse-link function appropriate to each process is applied to the network's output: a sigmoid for mortality (a per-tree death probability, as for mortality), and an exponential for growth and regeneration (always-positive rates; for regeneration this is the mean of the negative binomial distribution from which recruits are drawn, as for regeneration).

Two network architectures are available, selected with transformer. The default (transformer = TRUE) is a small transformer encoder (encoder_layers layers, embedding dimension emb_dim, feed-forward dimension dim_feedforward) that embeds each cohort, its species and the site's environment and attends across the cohorts of a patch. Setting transformer = FALSE instead uses a feed-forward network with hidden layers hidden (default two layers of 50 units each) and dropout, matching the architecture used by Pichler & Käber (2026) for the Barro Colorado Island case study (where dropout was set to 10%).

As with createProcess(), hybrid processes are calibrated jointly, end-to-end, with the remaining mechanistic or hybrid processes via fit(), rather than pre-trained in isolation and plugged in afterwards. optimize controls whether the network's weights are estimated during fitting or kept fixed at their (random) initial values, and dispersion_parameter/ sample_regeneration have the same meaning as in createProcess() and are only used when this object is the regeneration process.

Value

A list of class "hybrid" containing the process definition and associated parameters, to be passed as growth_process, mortality_process, or regeneration_process to finn().

References

Pichler, M., & Käber, Y. (2026). Inferring processes within dynamic forest models using hybrid modelling. Methods in Ecology and Evolution. doi:10.1111/2041-210x.70347

See Also

createProcess(), finn(), recruitment

Examples

# A hybrid process is a recipe, like createProcess(): no data and no torch
# are needed until the model is built. The default network is a small
# transformer encoder
growth_process <- createHybrid(formula = ~ temp + prec)
class(growth_process)

# a feed-forward network with two hidden layers instead, as in the Barro
# Colorado Island case study of the paper
mortality_process <- createHybrid(~ temp + prec, transformer = FALSE,
                                  hidden = c(50L, 50L), dropout = 0.1)


library(data.table)
# a model whose growth is a network while mortality, regeneration and
# competition stay mechanistic, fitted for two epochs on three sites of the
# bundled Oregon FIA data (?fia_obs_dt)
sites <- 1:3
Nsp   <- max(fia_obs_dt$species)
init  <- makeInitCohorts(fia_init_trees[siteID %in% sites], Nspecies = Nsp)
FINN.seed(1)
m <- finn(N_species = Nsp, recruits_dbh = 12.9,
          growth_process       = createHybrid(~ temp + prec, transformer = FALSE,
                                              hidden = c(16L, 16L), dropout = 0.1),
          mortality_process    = createProcess(~ temp + prec, mortality),
          regeneration_process = createProcess(~ temp + prec, regeneration_capped))
fit(m, data = fia_obs_dt[siteID %in% sites], env = fia_env_dt[siteID %in% sites],
    init_cohort = init, epochs = 2L, patches = 4, patch_size = 0.06,
    plot_progress = FALSE)
# the network takes the place of the growth equation in the simulation
sim <- simulateForest(m, env = fia_env_dt[siteID %in% sites], init_cohort = init)
head(sim$long$site[variable == "growth" & year == 10 & value > 0])


Define a demographic process for FINN

Description

Configures one demographic process (growth, mortality, regeneration or competition) for use as mortality_process, growth_process, regeneration_process, or competition_process in finn(), either as a fully mechanistic process with an explicit, interpretable functional form, or – if hidden is supplied – as the first ("Level 1") level of hybridization described by Pichler & Käber (2026): only the process' environmental-response function is replaced by a small feed-forward neural network, while the rest of the process equation remains mechanistic. To replace the entire process equation with a neural network ("Level 2"), use createHybrid() instead.

Usage

createProcess(
  formula = NULL,
  func,
  initSpecies = NULL,
  initEnv = NULL,
  hidden = NULL,
  optimizeSpecies = FALSE,
  optimizeEnv = TRUE,
  inputNN = NULL,
  outputNN = NULL,
  dispersion_parameter = 1,
  NN = NULL,
  upper = NULL,
  lower = NULL,
  dropout = 0,
  sample_regeneration = TRUE,
  n_quantiles = 10L,
  continuous = FALSE,
  light_mask = TRUE,
  custom_parameters = NULL,
  mortality_draw = c("binomial", "bernoulli", "poisson", "gamma"),
  regeneration_sampler = c("refined", "gaussian"),
  growth_scale = NULL,
  cap = c("all", "species"),
  prior = "max_obs_recruits",
  prior_lambda = 0.1,
  theta_floor = 0.5,
  optimizeTheta = TRUE,
  mortality_floor = 0.001,
  mortality_ceiling = 0.999,
  reg_floor = 0.001
)

Arguments

formula

(formula)
Environmental predictors for this process' environmental-response function, evaluated against the env data. Default NULL uses ~. (all available environmental covariates).

func

(function)
Mechanistic process equation, e.g. growth, mortality, regeneration, or competition, or a custom function with the same arguments. Required.

initSpecies

(matrix)
Optional custom initial values for the species-specific process parameters. Default NULL draws random initial values.

initEnv

(list)
Optional custom initial values for the parameters of the environmental-response network/regression. Default NULL draws random initial values. For the linear/logistic response (no hidden) this is a matrix with one row per species and one column per term of formula (the intercept first when the formula has one). Without it the mortality response starts at about 2 % per time step (intercept qlogis(0.02), other weights 0; with hidden layers the output bias carries it) and the other processes at torch's random start; e.g. initEnv = matrix(c(-3, 0), N_species, 2, byrow = TRUE) for ~ 1 + temp starts mortality at 5 %.

hidden

(integer())
Hidden-layer sizes of the feed-forward neural network that replaces the environmental-response function (Level 1 hybrid). Default NULL keeps the environmental response mechanistic (linear/logistic).

optimizeSpecies

(logical(1))
Should the species-specific process parameters be estimated during fit()? Default FALSE.

optimizeEnv

(logical(1))
Should the parameters of the environmental-response function be estimated during fit()? Default TRUE.

inputNN, outputNN

Not used in 0.2.0: the input dimension of the environmental-response network always follows from formula and env, and its output dimension is the number of species. Leave at NULL.

dispersion_parameter

(numeric(1))
Initial dispersion parameter of the negative binomial distribution used to sample recruits (the size theta), or its fixed value with optimizeTheta = FALSE. Only used when this process is the regeneration process. See recruitment.

NN

(nn_module)
Optional custom torch module overriding the default environmental-response network architecture.

upper, lower

(numeric())
Boundaries (natural scale) for the species-specific process parameters, one value per parameter of the process. They are guard rails that keep the optimiser inside the range in which the equations stay meaningful, not ranges taken from the data, and fit() does not move them. The defaults, as lower / upper: growth c(0.01, 0.01) / c(0.99, 4.0) (light requirement of the shade response, size decay); mortality c(-10, -10, -10) / c(10, 10, 10) (the shade, size and growth coefficients of the logit); regeneration 0.01 / 0.99 (light requirement); competition c(0.3, 0.0) / c(log(2.3), 2.0) (height parameter, competition strength), where the height parameter is capped so that no species grows taller than 130 m (see height()). A parameter that ends a fit at its bound is not identified by the data; widening the bounds is a decision for 0.2.1.

dropout

(numeric(1))
Dropout rate of the environmental-response network. Ignored unless hidden is set.

sample_regeneration

(logical(1))
Should recruits actually be sampled from the negative binomial regeneration distribution (TRUE), or only its expectation used (FALSE)? Only used when this process is the regeneration process. With FALSE the expected number of recruits per patch is rounded, so wherever it is below 0.5 no recruit enters at all: a silent zero for sparse species on small patches. See recruitment.

n_quantiles

(integer(1))
Number of height classes used to discretize cohorts when computing shading/light availability. Only used when this process is the competition process and continuous = FALSE.

continuous

(logical(1))
Compute shading continuously for every pair of cohorts (TRUE) instead of binning cohorts into n_quantiles height classes (FALSE, default). Only used when this process is the competition process.

light_mask

(logical(1))
Take the height quantiles of the binned competition over the LIVE cohorts only. The cohort dimension is padded to the widest site x patch in the batch and an empty slot has height 0.001, so with enough padding every live cohort is searchsorted into the top bin, where nothing shades anything: measured on a 251 m2/ha stand of ten live cohorts, 100 padded slots put all ten at light 1.00. Only the quantile INPUT is masked, so every cohort keeps its real height as the bin query. TRUE is the default since 0.2.0, because the padded width is set by the widest site in the BATCH: the same stand of ten cohorts gets light 1.00 throughout beside a neighbour holding a hundred, and its correct gradient down to 0.159 beside a neighbour holding ten. Batch composition is not part of the model, so the unmasked quantile made the fitted objective depend on batchsize. FALSE reproduces results published before 0.2.0. Ignored when continuous = TRUE, which compares pairs and is correct at any padding.

custom_parameters

(⁠named list⁠ or NULL)
Extra parameters that a custom func needs, declared here so they are registered on the model by finn(), optimised jointly by fit() (when trainable), and round-tripped by torch_save()/torch_load(). Each element is either a numeric vector (a trainable parameter with that starting value) or a list with init (numeric, length 1 or N_species) and optional trainable (logical, default TRUE; FALSE makes it a fixed buffer). The custom function accesses each as self[[name]]. Parameterise in the unconstrained space and apply any link inside the function (e.g. store ⁠log K⁠ and use exp(self$logK)), mirroring FINN's own ⁠par_*_unconstrained⁠ convention.

mortality_draw

(character(1))
How the number of dead trees is drawn from the cohort's mortality probability. Only used when this process is the mortality process. "binomial" (default since 0.2.0) is torch's exact binomial sampler: integer-valued, exact in both moments, at constant memory. It has no gradient of its own, which costs nothing under fit(rb_gradient = TRUE) (the default), where the gradient is taken through the expected number of deaths. Under fit(rb_gradient = FALSE) there is no such path, and "binomial" falls back to the "gamma" draw. "bernoulli" gives each tree of the cohort its own reparameterised Bernoulli trial (binomial_from_bernoulli()), which is integer-valued, matches the binomial in both moments – measured 12.011 / 8.387 against an exact 12.000 / 8.400 at n = 40, p = 0.3 – and keeps a gradient path to p through a straight-through sigmoid. It expands each cell to the largest cohort in the batch, so its memory grows with the largest trees value in the data. "poisson" draws a Bernoulli where the cohort holds one tree or fewer and a Poisson capped at the cohort size otherwise: integer-valued, exact in expectation for small n*p, and no pathwise gradient – which costs nothing now that fit(rb_gradient = TRUE) takes the gradient through the expectation anyway. The Bernoulli branch matters because capping a Poisson at a one-tree cohort delivers only 88 % of the calibrated probability at the p = 0.26 of a suppressed stem. "gamma" (the behaviour of every published FINN result) matches a Gamma to the binomial's first two moments and rsample()s it, which gives a pathwise gradient – the hazard a discrete draw does not cover – but the forward pass rounds that draw straight-through, so the gradient flows through a quantity the simulation discards and the rounded count delivers a measured 0.68-0.72 of the calibrated deaths for one-tree cohorts at annual probabilities of 0.01-0.10. See binomial_from_poisson() for the measured effect on the simulated stand.

regeneration_sampler

(character(1))
How recruits are drawn from the negative binomial. Only used when this process is the regeneration process and sample_regeneration = TRUE. "refined" (default since 0.2.0) samples exactly below lambda = 2 and drops both guards below, neither of which applies to torch_poisson; see rnbinom_torch_refined(). Above lambda = 2 it is still the floored Gaussian draw, which delivers about half a recruit per draw too few (measured over 1e6 draws: -0.43 at lambda = 2.5, -0.50 from lambda = 20, against about 0 with rounding). Rounding instead of flooring is planned for 0.2.1; it changes results, so it is not in this release. "gaussian" (the behaviour of every published FINN result) offsets the Gamma draw by +0.001, clamps the probability at 1e-4 and pushes the result through lambda + eps*sqrt(lambda). The offset and the clamp guard the Gaussian branch against a negative draw and against a NaN gradient through log(0); together they are a recruitment FLOOR of 0.0011 per cell-year, which at a FINN patch of 0.0168 ha is 0.066 recruits ha^-1 yr^-1 per species – over a pool of a hundred-odd species, as large as a temperate inventory's whole ingrowth.

growth_scale

(numeric(1) or NULL)
Overrides the growth_scale default of the process func. Only used when this process is the mortality process and func declares that argument. NULL (the default) keeps the function's own default, which for mortality() is 0.01 – growth enters the logit in %/yr. growth_scale = 1 feeds it the raw annual relative rate, the behaviour of 0.1.0. The value is set as the function's formal rather than passed down the forward pass, so a custom mortality func without the argument keeps working unchanged.

cap, prior, prior_lambda

The Beverton-Holt cap of regeneration_capped(): cap = "all" (default, one cap shared by all species) or "species"; prior = "max_obs_recruits" (default, the largest observed recruitment rate in the fitted data, recruits per ha and year) or a positive number; prior_lambda (default 0.1) the strength of the pull of ⁠log K⁠ towards ⁠log prior⁠. See regeneration_capped(). Only used when this process is the regeneration process and its func uses the cap.

theta_floor

(numeric(1))
Lower bound on the negative-binomial recruit dispersion par_theta_recruits, applied wherever it is read: the recruit draw and the regeneration likelihood. Default 0.5 since 0.2.0; 0 or NULL leaves it unbounded, as in 0.1.0. Only used when this object is the regeneration process.

theta is trained, and it collapses, because lowering it widens the regeneration likelihood and so cheapens that term without improving the predicted mean. The same parameter sets the variance of the simulated recruit draw, mu + mu^2/theta, which then turns bursty: on the German NFI it reached 0.035 by epoch 50 and the simulated stand overshot observed recruitment 133-fold, with basal-area and stem losses flat until epoch 25 and running away after. The Beverton-Holt cap does not prevent this – it bounds the mean, and the variance around a capped mean is still K + K^2/theta.

The floor keeps the fit stable, and in one converged pair of fits on the German national forest inventory it calibrated the recruitment level as well as a fixed theta: out of sample on a spatially blocked holdout, 1.06 times the observed level after 2000 epochs (about 126 000 optimizer steps) against 1.04 for optimizeTheta = FALSE. A fit stopped early is different: after 50 of those epochs (3 150 optimizer steps) the floored theta still put the level about 12 times too high, a fixed theta 2 to 3 times. Read the level only once the parameters have settled, or fix theta for short fits. See recruitment.

optimizeTheta

(logical(1))
Should the recruit dispersion par_theta_recruits be estimated during fit()? Default TRUE. With FALSE it stays at dispersion_parameter for the whole fit (a buffer, not a parameter), in the recruit draw and in the regeneration likelihood alike; theta_floor still applies. Only used when this process is the regeneration process.

Use FALSE for short fits, or when the recruitment level should not depend on how long the fit runs: a trained theta falls on sparse recruitment data, and with the floor (theta_floor) the level is right only once the fit has converged, while a fixed theta gets there sooner. dispersion_parameter = 1 is FINN's start value; on the German national forest inventory it matched the floored theta at convergence. A higher value such as 50 brings the recruit draw close to a Poisson draw: the variance mu + mu^2/theta approaches mu while the expected count per patch mu stays small against theta (at theta = 50 the excess is 2 % of the mean at mu = 1 and 20 % at mu = 10). Per-patch recruit counts are usually small enough for that; larger counts need a larger value. See recruitment.

mortality_floor, mortality_ceiling

(numeric(1))
The interval the per-cohort mortality probability is clamped to per simulation step, before the death draw. Only used when this process is the mortality process; the per-tree mortality loss is not bounded by either.

The defaults are 0.001 and 0.999 (0.1 % and 99.9 % per step). Until 0.2.0 the interval was hard-coded to ⁠[0.01, 0.99]⁠, which is why a simulated low-mortality stand – a mature unthinned stand, a slow-growing species, an equilibrium run – lost stems the observations did not: at a 1 % floor it loses 1 % of every cohort per step however low the fitted rate.

The floor exists because the shape of binomial_from_gamma(), n*p/(1-p), degenerates as p -> 0. Measured with that draw, it stays finite with an unbiased mean gradient down to 1e-4, but single-draw gradients grow heavy-tailed as n*p shrinks – the largest per-tree gradient is about ten times the old default's at 1e-3 and about a hundred times at 1e-4 – so 1e-3 is the lowest tested value and is the new default.

reg_floor

(numeric)
A small recruitment that every species gets in every patch and time step, whatever the light and the environment, in trees per ha and time step. Only used when this process is the regeneration process (regeneration(), regeneration_capped(), regeneration_adult() and regeneration_adult_effect() add it to their expected recruitment: mean = regP * exp(env) + reg_floor). Default 1e-3, which keeps the recruitment likelihood finite where the light response closes and adds next to nothing. One value for all species or one per species. Before 0.2.0 the floor was hard-coded to 0.2, which with many species adds a large recruitment that does not depend on anything (65 species x 0.2 = 13 trees per ha and year); models saved before then keep that value when reloaded. finn(reg_floor = ), the argument of earlier versions, is still accepted with a warning and overrides this value.

Details

Each demographic process in FINN is the product of (i) a process equation func that operates on the cohort state (dbh, number of trees, available light, species) and species-specific process parameters, and (ii) a species- and process-specific environmental-response function that maps site-level environmental predictors to a scalar effect on the process (see finn() for the underlying equations). createProcess() configures both parts:

formula selects which columns of the env data (passed to fit() or predict.finn_class()) enter the environmental-response function; initSpecies/initEnv allow supplying custom starting values for the process parameters/environmental-response model instead of the package's random initialization; optimizeSpecies/optimizeEnv control whether these parameters are estimated during fit() or held fixed at their initial values; and upper/lower set box constraints (on the natural process-parameter scale) within which the species-specific process parameters are constrained during optimization.

Value

A list of class "process" containing the process definition and associated parameters, to be passed as mortality_process, growth_process, regeneration_process, or competition_process to finn().

References

Pichler, M., & Käber, Y. (2026). Inferring processes within dynamic forest models using hybrid modelling. Methods in Ecology and Evolution. doi:10.1111/2041-210x.70347

See Also

createHybrid(), finn(), recruitment for the recruitment options and how to combine them

Examples

# A process is a recipe: createProcess() needs neither data nor torch, and the
# predictors named in `formula` are looked up in `env` when the model is
# fitted or simulated. Here: growth responding to temperature and precipitation
growth_process <- createProcess(formula = ~ temp + prec, func = growth)
class(growth_process)
deparse(growth_process$formula)

# the same equation with its species parameters estimated as well (by default
# only the environmental response is), and a quadratic temperature response
growth_process <- createProcess(~ temp + I(temp^2) + prec, func = growth,
                                optimizeSpecies = TRUE)

# level-1 hybrid: the environmental response of mortality as a small neural
# network with two hidden layers; the mortality equation stays mechanistic
mortality_process <- createProcess(~ temp + prec, func = mortality,
                                   hidden = c(16L, 16L), dropout = 0.1)

# the regeneration process with a smaller recruitment floor, a cap per
# species and a fixed recruit dispersion
regeneration_process <- createProcess(~ temp, func = regeneration_capped,
                                      reg_floor = 1e-4, cap = "species",
                                      optimizeTheta = FALSE)

# competition takes no environment; continuous = TRUE compares every pair of
# cohorts instead of binning them into height classes
competition_process <- createProcess(func = competition, continuous = TRUE)


# the processes become a model in finn(), here for the 11 species of the
# bundled Oregon FIA data (?fia_obs_dt), whose env table has `temp` and `prec`
m <- finn(N_species = 11, recruits_dbh = 12.9,
          growth_process       = growth_process,
          mortality_process    = mortality_process,
          regeneration_process = regeneration_process,
          competition_process  = competition_process)
# the species parameters of growth: light requirement and size decay
head(as.matrix(m$par_growth), 3)


Convert DBH to basal area

Description

Computes basal area in m^2 from diameter at breast height in cm:

BA = \pi \left(\frac{\mathrm{DBH}}{200}\right)^2

Usage

dbh2ba(dbh)

Arguments

dbh

numeric vector of diameters (cm).

Value

numeric vector of basal areas (m^2).

See Also

BA_stem() and BA_stand(), the versions for torch tensors

Examples

dbh2ba(c(10, 30, 50))   # basal area of one stem of 10, 30 and 50 cm

# basal area per hectare of a 0.06 ha plot from its tree list
dbh <- c(12.9, 25.4, 31.0, 48.3)
sum(dbh2ba(dbh)) / 0.06

Evaluate a fitted model

Description

An optional step after fit() that simulates the model and returns what is needed to judge it, as an object of class finn_evaluation with a print() and a plot() method. The model keeps the same object as model$evaluation; summary() prints it and comparePlot() draws the same comparison from a simulation. Calling fit() with its argument holdout runs it right after the fit.

Usage

evaluate(
  model,
  holdout = NULL,
  bare_ground = FALSE,
  years = 500L,
  sites = NULL,
  patches = NULL,
  train = NULL
)

## S3 method for class 'finn_evaluation'
print(x, species = FALSE, ...)

## S3 method for class 'finn_evaluation'
plot(x, type = c("scatter", "heatmap", "bare_ground"), set = NULL, ...)

Arguments

model

A model built by finn() and fitted with fit().

holdout

NULL (default) or a list with the holdout data (observations as for fit()), its env and its init_cohort, and optionally disturbance (see finn_data for the four tables) and tree_data (the observed trees, as for fit(): adds the largest diameter dbh_max to the comparison, see comparePlot()). Without init_cohort the holdout sites start from bare ground, with a warning.

bare_ground

(logical(1))
Run the bare-ground simulation too. Default FALSE.

years

(integer(1))
With bare_ground = TRUE: the length of the run in years, as in simulateForest(). Default 500.

sites

With bare_ground = TRUE, as in simulateForest(): NULL (default) one run under the mean climate of all sites, or site ids for one run per site under that site's mean climate.

patches

(integer(1))
Number of patches per site of a run that starts from bare ground; NULL (default) the patch count the model was fitted with (model$patches), or 100 for a model fitted before 0.2.0. Not used for a set with an init_cohort: its patch count comes from the initial cohorts.

train

NULL (default): the training data the model keeps from fit(). A list like holdout for a model that keeps none (fitted before 0.2.0, e.g. read with torch::torch_load()).

x

A finn_evaluation object, as evaluate() returns it.

species

(logical(1))
print(): also the skill per species. Default FALSE.

...

print(): unused. plot(): for the comparison, the arguments species, response, sites and n_species of comparePlot(); for type = "bare_ground", passed to plot.finn_simulation().

type

plot(): "scatter" (default) or "heatmap", the figures of comparePlot() from the stored comparison, or "bare_ground", the succession of the bare-ground runs (see plot.finn_simulation()).

set

plot(): "holdout" (default when there is one) or "train".

Details

Value

An object of class finn_evaluation: a list with train and, when given, holdout (each with the paired table matched and the skill measures skill overall and skill_species per species; the measures are described in summary.finn_class()), and with bare_ground = TRUE also bare_ground (the simulation, as simulateForest() returns it) and bare_ground_settings (years, sites, patches). print() shows the skill tables; plot() draws the comparison (type = "scatter" or "heatmap", as comparePlot()) or the bare-ground runs (type = "bare_ground"). The same object is kept on the model as model$evaluation (a new call replaces it), where summary.finn_class() reads it.

See Also

comparePlot(), summary.finn_class(), simulateForest()

Examples


library(data.table)
Nsp  <- max(fia_obs_dt$species)
train <- 1:3; hold <- 4:5
init_tr <- makeInitCohorts(fia_init_trees[siteID %in% train], Nspecies = Nsp)
init_ho <- makeInitCohorts(fia_init_trees[siteID %in% hold], Nspecies = Nsp)
FINN.seed(1)
m <- finn(N_species = Nsp, recruits_dbh = 12.9,
          growth_process       = createProcess(~ temp + prec, growth),
          mortality_process    = createProcess(~ temp + prec, mortality),
          regeneration_process = createProcess(~ temp + prec, regeneration_capped))
fit(m, data = fia_obs_dt[siteID %in% train], env = fia_env_dt[siteID %in% train],
    init_cohort = init_tr, epochs = 2L, patches = 4, patch_size = 0.06,
    plot_progress = FALSE)
ev <- evaluate(m, holdout = list(data = fia_obs_dt[siteID %in% hold],
                                 env = fia_env_dt[siteID %in% hold], init_cohort = init_ho),
               bare_ground = TRUE, years = 50)
ev                                  # the skill on the training data and the holdout
plot(ev)                            # observed against simulated on the holdout
plot(ev, type = "heatmap")          # the skill of every species
plot(ev, type = "bare_ground")      # the bare-ground run
summary(m)                          # the model keeps the evaluation


Permutation feature importance for FINN demographic rates

Description

Permutes each environmental predictor of a process and measures how strongly the permutation shifts that process's predicted rate, per process and per species. Unlike the analytical ALE-variance importance, this re-simulates the model, so it captures the full dynamical response (feedback through the stand state) rather than the process response function alone. It does NOT use the conditional-effects cache.

Usage

feature_importance(
  model,
  env = NULL,
  init_cohort = NULL,
  nperm = 20L,
  method = c("rmse", "sobol"),
  seed = NULL,
  sim_seed = 42L,
  env_autoscale = TRUE,
  ...
)

Arguments

model

(finn_class)
fitted model.

env

(data.table|data.frame|NULL)
env covariates; NULL uses the cached training env.

init_cohort

(CohortMat|NULL)
init cohort; NULL uses the cached training init_cohort.

nperm

(integer(1))
number of permutation replicates (default 20).

method

(character(1))
"rmse" or "sobol".

seed

(integer(1)|NULL)
R RNG seed controlling which permutations are drawn.

sim_seed

(integer(1)|NULL)
torch seed for common random numbers across runs.

env_autoscale

(logical(1))
see ALE(). TRUE (default) leaves predict() to rescale raw env internally; FALSE treats env as already on the model scale.

...

passed to predict() (e.g. patches, patch_size).

Details

Two scorings via method:

Predictors are read per-process from the model formulas, so processes with different formulas get different variable sets. Common random numbers (sim_seed, applied to the torch simulation RNG) make the stochastic mortality/regeneration draws shared across the reference and permuted runs, so a driver with no effect returns ~0.

Value

a named list (one per process) of data.frames with columns ⁠species, variable, importance⁠, sorted within species.

See Also

summary.finn_class() (importance = "permutation"), ALE()

Examples


library(data.table)
# a small model fitted on three Oregon FIA sites (?fia_obs_dt, ?fit); the NN
# variant is the same call with `hidden = c(10, 10)` on the process
sites <- 1:3
Nsp   <- max(fia_obs_dt$species)
init  <- makeInitCohorts(fia_init_trees[siteID %in% sites], Nspecies = Nsp)
FINN.seed(1)
m <- finn(
  N_species            = Nsp, recruits_dbh = 12.9,
  growth_process       = createProcess(~ temp + prec, FINN::growth,
                                       optimizeSpecies = TRUE, optimizeEnv = TRUE),
  mortality_process    = createProcess(~ temp + prec, FINN::mortality,
                                       optimizeSpecies = TRUE, optimizeEnv = TRUE),
  regeneration_process = createProcess(~ temp + prec, FINN::regeneration,
                                       optimizeSpecies = TRUE, optimizeEnv = TRUE))
fit(m, data = fia_obs_dt[siteID %in% sites], env = fia_env_dt[siteID %in% sites],
    init_cohort = init, epochs = 2L, patches = 4, patch_size = 0.06, plot_progress = FALSE)

# permutation importance: how much the simulated rate of a process shifts
# when a driver is shuffled between sites and years. `nperm` is small here
# to keep the example quick; use more for a real reading.
fi <- feature_importance(m, nperm = 2L, seed = 1L)
head(fi$growth)
# `method = "sobol"` gives the dimensionless Sobol-style score instead


Oregon FIA calibration data: site climate

Description

Climate per site and year for the fia_obs_dt training sites (fia_env_dt) and the fia_obs_test holdout sites (fia_env_test), in natural units (not standardised – fit() z-scales internally with env_autoscale). One row per simulated year ⁠1..22⁠: the row of year k drives the year that ends k years after the first inventory, so every site x year in the observation tables is covered, and the years after a site's last inventory are simulated but not scored. The climate is the plot's WorldClim normal, the same in every year.

Usage

fia_env_dt

fia_env_test

Format

A data.table with 4400 rows and 8 columns: 200 sites x 22 years, one row per site x year.

siteID, year

site index and simulated year (⁠1..22⁠).

temp, tempmax, tempmin

annual mean, warmest-month maximum and coldest-month minimum temperature, degrees C (bioclim 1, 5, 6).

prec, precwarmq

annual and warmest-quarter precipitation, mm (bioclim 12, 18).

precseas

precipitation seasonality, coefficient of variation (bioclim 15).

An object of class data.table (inherits from data.frame) with 4400 rows and 8 columns.

Source

A seeded subsample of Oregon plots of the US Forest Inventory and Analysis (FIA) database, with WorldClim bioclimatic variables attached per plot. The preparation script and the provenance of the source tables are in the package repository (dev/make_extdata.R, data-raw/README.md).

See Also

Other fia datasets: fia_init_trees, fia_obs_dt, fia_species_dt, fia_tree_dt

Examples

library(data.table)
head(fia_env_dt)
# one row per site and simulated year; the climate of a site is its normal,
# repeated for every year
fia_env_dt[, .(sites = uniqueN(siteID), first_year = min(year), last_year = max(year))]
# the range of the two predictors the package examples use, over the sites
fia_env_dt[year == 1, .(temp_min = min(temp), temp_max = max(temp),
                        prec_min = min(prec), prec_max = max(prec))]

Oregon FIA calibration data: initial tree list

Description

The year-0 tree list of the fia_obs_dt training sites (fia_init_trees) and the fia_obs_test holdout sites (fia_init_test): what a site looked like at the first census, from which makeInitCohorts() builds the initial cohorts a fit or simulation starts from (makeInitCohorts(fia_init_trees, Nspecies = 11)).

Usage

fia_init_trees

fia_init_test

Format

A data.table with one row per tree (6039 / 6083 rows) and 28 columns. The ones FINN uses:

siteID, patchID, year

site and patch index; year is 0.

species, species_name

species index ⁠1..11⁠ and name, coded as in fia_species_dt.

dbh

diameter at breast height, cm.

trees

trees represented by the record (1; NA for records that are not living stems).

treeName

unique tree identifier.

The remaining columns (siteName, patchName, OrigYear, FIA's SPCD and STATUSCD, status, living, and the per-tree change fields such as dbh_before, dbh_growth, mort, reg) are carried over from the remeasurement tree list produced by makeObsData(); at year 0 most of them are NA by construction.

An object of class data.table (inherits from data.frame) with 6083 rows and 28 columns.

Source

A seeded subsample of Oregon plots of the US Forest Inventory and Analysis (FIA) database, with WorldClim bioclimatic variables attached per plot. The preparation script and the provenance of the source tables are in the package repository (dev/make_extdata.R, data-raw/README.md).

See Also

Other fia datasets: fia_env_dt, fia_obs_dt, fia_species_dt, fia_tree_dt

Examples

library(data.table)
head(fia_init_trees[, .(siteID, patchID, species, species_name, dbh, trees, treeName)])
# living stems and their mean diameter per species at the first inventory
fia_init_trees[!is.na(trees), .(stems = sum(trees), mean_dbh = round(mean(dbh), 1)),
               by = species_name][order(-stems)]

# the initial state of a fit or a simulation, here for three sites: one
# cohort per tree
init <- makeInitCohorts(fia_init_trees[siteID %in% 1:3], Nspecies = 11)
init$dims   # sites, patches, cohorts


Oregon FIA calibration data: training sites

Description

A ready-to-fit sample of the US Forest Inventory and Analysis (FIA) network in Oregon: 200 training sites (⁠fia_*_dt⁠ / fia_init_trees) and 200 disjoint holdout sites (⁠fia_*_test⁠) that are never seen during fitting, so a model fit on the training tables can be scored genuinely out of sample. The tables are already in FINN's input format – IDs resolved, species re-indexed ⁠1..K⁠ – so they go straight into fit() / simulateForest() without makeObsData() or resolveSiteIDs(). The D-Fit_to_FIA and E-Mortality vignettes are the worked examples.

Usage

fia_obs_dt

fia_obs_test

Format

fia_obs_dt and fia_obs_test: one row per site x year x species (4400 rows, 14 columns). The year-0 initial state is in fia_init_trees / fia_init_test.

siteID, year

integer site index (⁠1..200⁠) and the years since the site's first inventory (10, 20; 21 or 22 for one site each).

period_length

years since the previous inventory (10; 11 or 12 for the late inventory): the window over which the simulation is aggregated before it meets the observation.

species, species_name

species index ⁠1..11⁠ and its name; "other" pools the species outside the 98 % most abundant stems.

ba

living basal area, m2 – the mean over the site's patches (0.06 ha each; makeObsData(aggregate_by_site = TRUE)).

trees

living stems, mean per patch (hence fractional).

dbh

mean diameter at breast height of living trees, cm (NA when there are none).

growth, growth_n

mean annual relative dbh growth rate of the survivors, (dbh / dbh_before)^(1 / period_length) - 1 per tree (tree-weighted over patches), and the number of trees behind it.

n_at_risk, n_died, mort

trees alive at the start of the interval and how many of them had died by its end, summed over patches, and the annual mortality rate 1 - (1 - n_died / n_at_risk)^(1 / period_length). The binomial mortality loss scores mort weighted by n_at_risk.

reg

recruits over the interval, trees per hectare (mean over patches).

An object of class data.table (inherits from data.frame) with 4400 rows and 14 columns.

Details

All nine objects are data.tables. Attach data.table to use its [ semantics on them, and data.table::copy() one before modifying it by reference (⁠:=⁠), as with any package dataset.

The tables are on an annual time axis: one simulation step is one year. The first inventory (2001-02) is the initial state, year 0; the two remeasurements are observations at the number of years since it, 10 and 20 (21 for one training site and 22 for one holdout site, whose third inventory came late), each with period_length, the years since the previous inventory. Growth and mortality are yearly rates; fit() compounds the simulated yearly rates of the period_length years before each inventory into the same per-year rate before comparing, and compares reg with the recruits simulated over those years. The trees behind the mortality counts are in fia_tree_dt. Before FINN 0.2.0 the tables had one step per ten-year interval (year 1 and 2, rates over the interval); makeObsData(rates = "interval") and resolveSiteIDs(time_axis = "census") still build such tables.

Source

A seeded subsample of Oregon plots of the US Forest Inventory and Analysis (FIA) database, with WorldClim bioclimatic variables attached per plot. The preparation script and the provenance of the source tables are in the package repository (dev/make_extdata.R, data-raw/README.md).

See Also

fia_env_dt, fia_init_trees, fia_tree_dt, fia_species_dt

Other fia datasets: fia_env_dt, fia_init_trees, fia_species_dt, fia_tree_dt

Examples

library(data.table)
fia_obs_dt[year == 10, .(sites = uniqueN(siteID), ba = mean(ba)), by = species_name]
# the observation windows: inventory year x interval length, sites
unique(fia_obs_dt[, .(siteID, year, period_length)])[, .N, by = .(year, period_length)]

Oregon FIA calibration data: species coding

Description

The species index shared by all ⁠fia_*⁠ tables. Derived from the training sites, so species is ⁠1..11⁠ in every table.

Usage

fia_species_dt

Format

A data.table with 11 rows and 2 columns, species (integer index) and species_name (Latin name, or "other" for the pooled rare species).

Source

A seeded subsample of Oregon plots of the US Forest Inventory and Analysis (FIA) database, with WorldClim bioclimatic variables attached per plot. The preparation script and the provenance of the source tables are in the package repository (dev/make_extdata.R, data-raw/README.md).

See Also

Other fia datasets: fia_env_dt, fia_init_trees, fia_obs_dt, fia_tree_dt

Examples

library(data.table)
fia_species_dt
# put names on a table that carries only the species index
deaths <- fia_tree_dt[, .(trees = .N, died = sum(died)), by = species]
merge(fia_species_dt, deaths, by = "species")

Oregon FIA calibration data: the trees behind the mortality counts

Description

One row per tree and remeasurement interval for the fia_obs_dt training sites (fia_tree_dt) and the fia_obs_test holdout sites (fia_tree_test): every tree alive at the start of an interval, with its diameter then and its fate over the interval. These are the closed cohorts whose counts (n_at_risk, n_died) the site tables carry, and the tree_data of fit(loss_aggregation = c(mortality = "tree")) and predictTrees(), which score the mortality function on every observed tree instead of on the site's pooled rate (see finn_loss). The ids, time axis and species coding are those of the site tables, so the two join on siteID, year and species. All trees of the FIA macroplot are kept: the per-tree loss scores fates and needs no area expansion.

Usage

fia_tree_dt

fia_tree_test

Format

A data.table with one row per tree and interval (9979 rows and 661 deaths / 10109 rows and 734 deaths) and 8 columns:

siteID, year

site index and the census that closes the interval, on the axis of fia_obs_dt (10, 20; 21 or 22).

patchID

patch (FIA subplot) index, as in fia_init_trees.

species

species index ⁠1..11⁠ (fia_species_dt), the species the tree was recorded as at the start of the interval.

dbh

diameter at breast height at the start of the interval, cm.

growth

the tree's yearly relative growth rate over the interval, (dbh_end / dbh)^(1 / period_length) - 1; NA for a tree that died.

died

1 if the tree was dead at the end of the interval, 0 if alive.

period_length

years from the start to the end of the interval, as in fia_obs_dt.

An object of class data.table (inherits from data.frame) with 10109 rows and 8 columns.

Details

In a few cells (21 of the training and 22 of the holdout site x year x species cells) the tree table holds trees that the site table's counts do not: the site table has no row for a species whose trees had all died by a census. The tree table keeps them (5 and 7 deaths); everywhere else the counts agree exactly. Two holdout sites whose first inventory found only dead trees have no tree at risk and so no row.

Source

A seeded subsample of Oregon plots of the US Forest Inventory and Analysis (FIA) database, with WorldClim bioclimatic variables attached per plot. The preparation script and the provenance of the source tables are in the package repository (dev/make_extdata.R, data-raw/README.md).

See Also

fia_obs_dt, predictTrees(), finn_loss

Other fia datasets: fia_env_dt, fia_init_trees, fia_obs_dt, fia_species_dt

Examples

library(data.table)
# deaths and trees at risk per interval, and the yearly mortality by size class
fia_tree_dt[, .(trees = .N, deaths = sum(died)), by = year]
fia_tree_dt[, .(trees = .N, annual_mortality = round(1 - (1 - mean(died))^(1 / 10), 4)),
            by = .(dbh_class = cut(dbh, c(0, 20, 30, 45, 61, 80, 100, Inf)))][order(dbh_class)]

Build a FINN forest model

Description

Builds a FINN (Forest Informed Neural Network) model: a forest simulator that follows groups of similar trees (cohorts) on small patches of forest through time, year by year, and that can learn its parameters from forest inventory data. Each of the four demographic processes – competition for light, growth, mortality and regeneration – is either a classic, interpretable equation (createProcess()) or a neural network (createHybrid()). Whatever the mix, all processes are estimated together, in one go, by fit().

finn() only assembles the model. Nothing is estimated yet: pass the result to fit() to estimate the parameters from your data, and to simulateForest() to simulate forest development.

Usage

finn(
  N_species,
  mortality_process = createProcess(func = mortality),
  growth_process = createProcess(func = growth),
  regeneration_process = createProcess(func = regeneration_capped),
  competition_process = createProcess(func = competition),
  recruits_dbh = 1,
  growth_rate = c("annual", "period"),
  recruit_obs_weight = 1,
  ...
)

Arguments

N_species

(integer(1))
Number of species in the data. Species are coded ⁠1, ..., N_species⁠ in every table (resolveSiteIDs() does the coding).

mortality_process

(process)
How trees die. Default createProcess(func = mortality), the mortality equation of mortality() with a logistic response to every environment column. Build your own with createProcess() or createHybrid(). Its environmental response starts at about 2 % mortality per time step (an intercept of qlogis(0.02), every other weight 0), so that an unfitted stand on yearly steps does not die out; createProcess(initEnv = ) sets another start, see mortality().

growth_process

(process)
How trees grow in diameter. Default createProcess(func = growth), the growth equation of growth() with a linear response to every environment column. Build your own with createProcess() or createHybrid().

regeneration_process

(process)
How new trees appear. Default createProcess(func = regeneration_capped): the regeneration equation of regeneration_capped(), whose expected recruitment is capped (new in 0.2.0). Alternatives: regeneration() (no cap, the equation of the paper), regeneration_adult() (recruitment limited by the adults of the same species on the site) and regeneration_adult_effect() (adults raise recruitment, but a species without adults still recruits). See recruitment for the recruitment options and how they act together. Build your own with createProcess() or createHybrid().

competition_process

(process)
How trees shade each other. Default createProcess(func = competition), the light model of competition(). Only createProcess() is accepted here, and competition cannot depend on the environment in this version.

recruits_dbh

(numeric(1))
Diameter (cm) at which new trees enter the simulation. Default 1. Set it to the smallest diameter your inventory records (12.9 cm for the bundled FIA data), so that simulated recruits are the trees the inventory counts as recruits.

growth_rate

(character(1))
What the growth column of the data is, so that fit() compares it with the right simulated quantity. "annual" (default): a rate per time step – with annual steps the mean annual relative growth rate over the observation interval (each year's dbh / dbh_before - 1, compounded to one rate per year). FINN compounds its simulated per-step rates over the interval the same way, so the two are the same quantity (see fit()). "period": the relative diameter increment over the whole observation interval (dbh_end / dbh_start - 1), which compounds the per-step rates; FINN then compounds its simulated rates the same way. The two only differ when an observation interval spans several time steps (period_length in the data). If unsure, keep the default: with annual time steps it is the annual growth rate. makeObsData() returns the annual rate (as in the bundled FIA data); with makeObsData(rates = "interval") it returns the increment between two censuses, which is the per-step rate only when one step is one census interval. The terms follow Kohyama, Kohyama & Sheil (2018), who distinguish a rate per year from the change over a census interval.

recruit_obs_weight

(numeric(1))
Only for inventories that do not count recruits per hectare (angle-count sampling, small-tree subplots): the factor that turns a recruitment density into the counts such a design tallies. Default 1, which leaves per-hectare data as they are. See recruitment.

...

Arguments of earlier versions, still accepted with a warning: reg_floor (now createProcess(reg_floor = ) of the regeneration process) and growth_period_scale (TRUE is now growth_rate = "period").

Details

The defaults work for a first model: finn(N_species = 11) builds a model whose four processes are the package's own equations, with every column of the environment table as a predictor. Pass a process built with createProcess() to choose the predictors (its formula), to change the equation (its func), or to fix parameters; pass one built with createHybrid() to replace the whole process by a neural network.

One time step of FINN: the cohorts of a patch and the site's environment enter competition, growth, mortality and regeneration, which produce the cohorts of the next step and the simulated stand variables.

One simulation step. The cohorts of a patch at time t – their size, species, number of trees and cohort id – and the site's environment are the inputs. Competition turns the cohorts into the light each of them receives; growth, mortality and regeneration then act on every cohort, each of them either a mechanistic equation (the gear) or, in a hybrid model, a neural network, and each with its own response to the environment. The distribution drawn beside a process is the one its outcome is drawn from or scored with: Gaussian for growth, binomial for the deaths, negative binomial for the recruits. Out come the cohorts of the next step and the quantities FINN reports for every site and year – mean diameter, basal area, number of trees, and the growth, mortality and recruitment rates.

The figure is Figure 1 of Pichler & Käber (2026), reproduced from the preprint version of that paper (arXiv:2508.01228), which is published under CC BY 4.0. The caption above is ours, not the paper's.

How FINN simulates a forest. A site is a set of patches (small plots of patch_size ha). On each patch the trees are kept as cohorts, each with a species, a diameter at breast height (dbh, cm) and a number of trees. Every simulated time step, usually one year, runs the four processes in turn:

  1. competition works out how much light reaches each cohort from the basal area of the taller trees on its patch (competition());

  2. growth increases each cohort's diameter, depending on its light, size, species and the site's environment (growth());

  3. mortality removes a share of each cohort's trees, depending on its growth, light, size, species and environment (mortality());

  4. regeneration adds new cohorts of small trees (recruits_dbh), depending on light, species and environment (regeneration_capped()).

Growth, mortality and regeneration each carry their own response to the environment: for every species, the columns of the environment table that the process' formula names are turned into one number that scales the process. By default that response is a simple linear (growth, regeneration) or logistic (mortality) function with one coefficient per predictor and species; createProcess(hidden = ) turns it into a small neural network. The simulated stand variables (mean dbh, basal area, number of trees) and the simulated rates (growth, mortality, recruitment) of every site and year are what fit() compares with the observations.

The default processes are, in 0.2.0, createProcess(func = growth), createProcess(func = mortality), createProcess(func = regeneration_capped) and createProcess(func = competition): the equations of Pichler & Käber (2026), with one change – recruitment is capped (regeneration_capped() is new in 0.2.0; regeneration() is the uncapped process of the paper). A process written in the signature as createProcess(func = ) uses every column of the environment table (formula = ~.) and its default settings. Passing NULL for a process is still accepted and means the same default. The competition process cannot depend on the environment in this version.

Patches, and why there are several. FINN is a gap model: how much light a tree gets depends on the trees standing next to it, so the unit of simulation is a patch small enough that one large tree shades it (patch_size, in ha). A site is simulated as several such patches that share the site's environment, and a site's stand variables are the mean over its patches. The patches mean two different things depending on where the simulation starts. With an init_cohort built from an inventory they are the inventory's own subplots, each carrying its real trees, and the patch count comes from that table rather than from patches. From bare ground (init_cohort = NULL) they are stochastic replicates of the same site: more of them means a smoother trajectory, at a cost that grows with their number.

What is estimated, and how. Everything that is switched on, at once. A process built with createProcess() estimates the weights of its environmental response by default (optimizeEnv = TRUE), and its per-species parameters only when asked to (optimizeSpecies = TRUE; by default they keep their starting values). These, and where a process is a network that network's weights, form one parameter vector, and fit() moves it by gradient descent through the simulation: the model is run forward over the observed years, the simulated stand variables and rates are compared with the observations, and the gradient is carried back through the time loop by automatic differentiation. No process is fitted on its own and plugged in afterwards. That is what lets a process that has been replaced by a network still be identified: it has to produce a stand that the other three processes can also live with.

Mechanistic, hybrid, or in between. Each process is set independently:

Competition is mechanistic at every level. A mixed model is the normal case: the process you suspect is misspecified goes to level 1 or 2, the others stay mechanistic, and the comparison between the two fits is the result.

Setting up a first model. Three choices carry most of the outcome. recruits_dbh must be the diameter at which your inventory starts counting trees, or the simulation recruits trees the data never recorded. patch_size must be the area one plot of that inventory covers. And a process' formula should name the predictors you would defend in a regression rather than every column of env, because each one costs a coefficient per species.

Checking a fitted model. fit(plot_progress = TRUE) and ⁠$history⁠ say whether the fit moved and which response drove it; summary.finn_class() reports the skill on the training data and a holdout (stored by evaluate(), drawn by comparePlot()), whether the fit has settled, and the environmental importances; plot.finn_class() draws the fitted parameters; ALE() shows the fitted environmental responses, including those of a network; simulateForest() from bare ground (bare_ground = TRUE) shows what the model does outside the observation window. The last one is worth the time: a model that predicts the holdout well and grows an implausible stand from bare ground has usually learned the observed window rather than the dynamics that produced it.

Value

An object of class finn_class (a torch::nn_module): the assembled, not yet fitted model, ready for fit() or simulateForest().

References

Pichler, M., & Käber, Y. (2026). Inferring processes within dynamic forest models using hybrid modelling. Methods in Ecology and Evolution. doi:10.1111/2041-210x.70347

Kohyama, T. S., Kohyama, T. I., & Sheil, D. (2018). Definition and estimation of vital rates from repeated censuses: choices, comparisons and bias corrections focusing on trees. Methods in Ecology and Evolution, 9, 809-821. doi:10.1111/2041-210X.12929

See Also

fit() to estimate the parameters, simulateForest() to simulate, finn_data for the input tables, recruitment for the recruitment options

Examples


library(data.table)

# --- the bundled data -------------------------------------------------
# 200 plots of the US Forest Inventory and Analysis programme in Oregon,
# 11 tree species, four subplots per plot, each plot measured twice about
# ten years apart. `year` counts years from the start of the panel.
#  * fia_obs_dt     one row per plot, year and species: the stand variables
#                   (dbh, ba, trees) and the rates (growth, mort, reg) that
#                   an inventory yields -- these are what fit() scores
#  * fia_env_dt     climate of every plot and year (temp, prec, ...)
#  * fia_init_trees the individual trees of the first census, the state the
#                   simulation starts from
#  * fia_species_dt the species codes 1..11 and their names
head(fia_obs_dt)
fia_species_dt

op <- par(mfrow = c(1, 2))
# what the model has to reproduce: the stand of each plot, per year
stand <- fia_obs_dt[, .(ba = sum(ba, na.rm = TRUE)), by = .(siteID, year)]
plot(stand$year, stand$ba, pch = 16, col = "#2b6a4d40",
     xlab = "year of the panel", ylab = "basal area (m^2/ha)",
     main = "observed stands")
# and the size distribution it starts from
hist(fia_init_trees$dbh[which(fia_init_trees$living)], breaks = 40, col = "grey80",
     border = "white", xlab = "dbh at the first census (cm)",
     main = "initial trees")
par(op)

# --- the workflow -----------------------------------------------------
# The whole workflow on three Oregon FIA sites: build, estimate, simulate.
# A real calibration uses all sites and hundreds of epochs.
sites <- 1:3
Nsp   <- max(fia_obs_dt$species)

# 1. build the model: growth, mortality and regeneration respond to annual
#    temperature and precipitation; competition has no environment
m <- finn(N_species = Nsp, recruits_dbh = 12.9,
          growth_process       = createProcess(~ temp + prec, growth),
          mortality_process    = createProcess(~ temp + prec, mortality),
          regeneration_process = createProcess(~ temp + prec, regeneration_capped))
m

# 2. estimate the parameters from the inventory: the observed stand
#    variables and rates (data), the climate of every year (env) and the
#    trees at the first census (init_cohort)
init <- makeInitCohorts(fia_init_trees[siteID %in% sites], Nspecies = Nsp)
FINN.seed(1)
fit(m, data = fia_obs_dt[siteID %in% sites], env = fia_env_dt[siteID %in% sites],
    init_cohort = init, epochs = 2L, patches = 4, patch_size = 0.06,
    plot_progress = FALSE)
tail(m$history, 1)   # the loss of every response in the last epoch

# 3. simulate the three sites over the years of `env` with the fitted model
sim <- simulateForest(m, env = fia_env_dt[siteID %in% sites],
                      init_cohort = init, patches = 4, patch_size = 0.06)
head(sim$long$site)

# the same model with the defaults spelled out: every process uses every
# column of `env` as a predictor
m2 <- finn(N_species = Nsp, recruits_dbh = 12.9,
           growth_process       = createProcess(func = growth),
           mortality_process    = createProcess(func = mortality),
           regeneration_process = createProcess(func = regeneration_capped),
           competition_process  = createProcess(func = competition))


Settings of the optimizer used by fit()

Description

Collects the settings of the optimization behind fit() in one object, passed as fit(control = finnControl(...)). The defaults are robust in most cases: a fit needs no control argument at all. The learning rate lr, the number of epochs and the batchsize are changed much more often, so they stay arguments of fit() itself.

Usage

finnControl(
  optimizer = torch::optim_ignite_adam,
  lr_scheduler = "none",
  lr_scheduler_params = list(),
  clip_norm = 2,
  ...
)

## S3 method for class 'finnControl'
print(x, ...)

Arguments

optimizer

(function)
A torch optimizer generator. Default torch::optim_ignite_adam.

lr_scheduler

(character(1) or function)
Learning-rate schedule: "none" (default), "step", "exponential", "cosine", "plateau", or a ⁠function(optimizer)⁠ returning a torch scheduler. See Details.

lr_scheduler_params

(list)
Settings of the chosen schedule. See Details.

clip_norm

(numeric(1) or named list)
Gradient-norm budget per parameter group. Default 2.

...

Further arguments for optimizer, e.g. weight_decay = 1e-4.

x

(finnControl)
The object to print.

Details

fit() estimates the parameters by gradient descent: in every epoch it simulates the sites, compares the simulation with the observations (see finn_loss), and moves every parameter a small step in the direction that makes the comparison better. finnControl() sets how those steps are taken.

Before 0.2.0 these were arguments of fit() itself. The old form is still accepted with a warning, e.g. fit(lr_scheduler = "step") becomes fit(control = finnControl(lr_scheduler = "step")).

Value

A list of class finnControl, to be passed to fit(control = ).

See Also

fit(), finn_loss

Examples


# the defaults, which most fits can keep
finnControl()

# halve the learning rate every 50 epochs and allow larger steps
ctrl <- finnControl(lr_scheduler = "step",
                    lr_scheduler_params = list(step_size = 50, gamma = 0.5),
                    clip_norm = 5)

library(data.table)
sites <- 1:3
Nsp   <- max(fia_obs_dt$species)
init  <- makeInitCohorts(fia_init_trees[siteID %in% sites], Nspecies = Nsp)
m <- finn(N_species = Nsp, recruits_dbh = 12.9,
          growth_process       = createProcess(~ temp + prec, growth),
          mortality_process    = createProcess(~ temp + prec, mortality),
          regeneration_process = createProcess(~ temp + prec, regeneration_capped))
fit(m, data = fia_obs_dt[siteID %in% sites], env = fia_env_dt[siteID %in% sites],
    init_cohort = init, epochs = 2L, patches = 4, patch_size = 0.06,
    control = ctrl, plot_progress = FALSE)


The input tables of FINN: observations, environment, initial trees

Description

fit() and simulateForest() take their input as a few plain tables (data.frame or data.table), all keyed by an integer site index siteID and a year. This page says what each table must contain, what may be missing, and what FINN fills in by itself. The bundled Oregon FIA data (fia_obs_dt, fia_env_dt, fia_init_trees) are a complete example and the vignette Preparing your data for FINN (vignette("C-Data_preparation", package = "FINN")) builds them from a raw tree list.

The short version: build data and env with makeObsData() and resolveSiteIDs(), the initial trees with makeInitCohorts(), and pass them to fit(data = , env = , init_cohort = ). The three helpers produce exactly the columns below.

How the tables fit together

The sites of data, env and init_cohort must be the same set; the ids need not be ⁠1..N⁠. Species are coded ⁠1..N_species⁠ in every table. resolveSiteIDs() turns site names and species names into these codes and returns the lookup tables.

data – the observations

One row per siteID, year and species. Columns:

column what it is
siteID integer site index
year the census year; must be a year of env
species integer species code ⁠1..N_species⁠
dbh mean diameter at breast height of the living trees of that species, cm
ba basal area of the living trees, m2 per patch (the mean over the site's patches)
trees number of living trees per patch (the mean over the patches; may be fractional)
growth mean relative diameter growth rate of the survivors per time step (per year): over an interval of p years, (dbh / dbh_before)^(1 / p) - 1 per tree (to give the increment over the whole interval instead, see finn(growth_rate = ))
mort mortality rate per time step of the trees alive at the previous census: over p years, 1 - (1 - n_died / n_at_risk)^(1 / p) (0 to 1)
reg recruits (trees that grew past recruits_dbh) since the previous census, per hectare

dbh, ba and trees describe the stand at the census; growth, mort and reg describe what happened since the previous census. One time step is normally one year: year counts years (e.g. since the first inventory), growth and mort are yearly rates and period_length is the number of years since the previous census. Optional columns, filled in by FINN when absent:

column what it is when absent
period_length the number of time steps (years) since the previous census (the interval the rates refer to) one step: each rate is compared with a single simulated step
n_at_risk trees alive at the previous census behind mort 1: every mortality observation weighs the same
growth_n trees behind the growth mean 1: every growth observation weighs the same

With period_length, the simulated growth and mortality of the interval's steps are compounded into one rate per year and the simulated recruitment is summed before they are compared with the observation: a ten-year inventory interval is ten simulated years, and the yearly rates of data are compared with the geometric mean of 1 + g minus one and with one minus the geometric mean survival of the ten simulated years – the functional makeObsData() derives the observed rates with. n_at_risk and growth_n weight the mortality and growth terms by the number of trees behind each observation (a mortality rate from 100 trees says more than one from a single tree). makeObsData() produces all of them. Further optional columns exist for the size-class and quantile aggregations (n_class_1, ..., dbh_q10, ...; see finn_loss).

Missing values. Every response column must exist, but any value may be NA: a response that was not observed in a cell (site, year, species) is simply left out of the comparison for that cell, and the other responses of the cell are still used. A species that does not occur on a site needs a row with 0 for ba, trees and reg (so that FINN learns it is absent) and NA for dbh, growth and mort (there is no tree to measure). makeObsData() writes these rows.

Incomplete series. Sites need not share census years, and a site may have fewer censuses than another: a (site, year) with no row is treated as unobserved in that year, and period_length may differ between sites and censuses. When it does, every site is scored over its own interval. A census with NA period_length next to one with a value counts as a one-step interval on the usual path; on the per-site path (interval lengths that differ between sites, loss_aggregation = "tree") every window is read from the column and a site without a finite value stops the fit with a message. Years of env before a site's first census and after its last are simulated but not scored.

Units. Use the units of your inventory consistently: dbh in cm, areas in m2 per patch of patch_size ha, recruits per hectare. The per-hectare quantities depend on patch_size, so pass the plot size of the inventory to fit(patch_size = ).

head(fia_obs_dt[, .(siteID, year, period_length, species, dbh, ba, trees, growth, mort,
                    reg, n_at_risk, growth_n)], 2)
#>    siteID  year period_length species    dbh    ba trees  growth  mort   reg n_at_risk growth_n
#> 1:      1    10            10       1 92.837 0.342   0.5 0.00356     0     0         2        2
#> 2:      1    10            10       2     NA 0.000   0.0      NA    NA     0         0        0

env – the environment of every simulated step

One row per siteID and year, with one column per predictor and nothing else: no patch column, no response. Every site must have the same years, every (site, year) a value of every predictor, and the years must run from the first step to simulate to the last observation in data; a year that is missing or NA cannot be simulated and stops the fit with a message. At least one predictor is needed; a process whose formula names none has nothing to respond to.

The predictors are given in their natural units. fit(env_autoscale = TRUE) (the default) standardises every column to mean 0 and standard deviation 1 and stores the constants on the model, so the same raw table layout works for simulateForest() afterwards. For the bundled FIA data the predictors are the bioclimatic variables of each plot:

head(fia_env_dt, 3)
#>    siteID  year  temp tempmax tempmin  prec precseas precwarmq
#> 1:      1     1  3.96    24.7   -10.4   547     30.0       101
#> 2:      1     2  3.96    24.7   -10.4   547     30.0       101
#> 3:      1     3  3.96    24.7   -10.4   547     30.0       101

The row of year k drives the simulated year that ends at k, starting from the initial trees at year 0, so an inventory at year 10 is compared with the stand after ten simulated years and env starts at year 1.

A climate that does not change between years is repeated for every year, as here; a year-by-year climate gives every step its own row. Which columns a process uses is set by createProcess(formula = ), e.g. ~ temp + prec; the default ~. uses every predictor column.

disturbance – optional

One row per siteID and year, over exactly the sites and years of env, with the column intensity: the probability (0 to 1) that a patch of the site loses all its trees in that year. Every patch is drawn separately, so an intensity of 0.1 clears on average one patch in ten; use 0 where nothing happens. NULL (the default) means no disturbance.

init_cohort – the initial trees

A CohortMat, the trees of every site at the first census grouped into cohorts of one species and one diameter per patch, built by makeInitCohorts() from a table with siteID, patchID, species, dbh and optionally trees (stems the row stands for, default 1). makeInitCohorts(dbh_binsize = ) bins the diameters into fewer, cheaper cohorts; without it every tree is a cohort, which the per-tree scoring needs. The number of patches per site is read from init_cohort, so fit(patches = ) is ignored when it is given. Without init_cohort every site starts from bare ground with patches empty patches – a succession run, not a calibration.

tree_data – optional, the individual trees

One row per tree and census, needed only to score growth or mortality per tree. Always: siteID, year (the census that closes the tree's interval, the year the same interval has in data), patchID, species, growth (its relative growth rate per time step, NA if not observed) and died (0/1 over the interval, NA if not observed). For loss_aggregation = "tree" also dbh at the start of the interval, and optionally trees; for loss_resolution = "tree" also cohortID, the cohort the tree started as (makeInitCohorts(treeID_table = TRUE) returns the table that carries it). finn_loss explains the two routes.

The helper functions

See Also

fit(), finn_loss, fia_obs_dt, fia_env_dt, fia_init_trees, vignette("C-Data_preparation", package = "FINN")

Examples

library(data.table)
# the input tables of a fit, here for three sites of the bundled Oregon FIA
# sample
sites <- 1:3
obs <- fia_obs_dt[siteID %in% sites]
env <- fia_env_dt[siteID %in% sites, .(siteID, year, temp, prec)]

# `data`: one row per site, census year and species
head(obs[, .(siteID, year, species, dbh, ba, trees, growth, mort, reg, period_length)])
# `env`: one row per site and simulated year, up to the last census
env[, .(first_year = min(year), last_year = max(year)), by = siteID]
obs[, .(census_years = toString(unique(year))), by = siteID]


# `init_cohort`: the trees of the first census
Nsp  <- max(fia_obs_dt$species)
init <- makeInitCohorts(fia_init_trees[siteID %in% sites], Nspecies = Nsp)
init$dims   # sites, patches (the patch count of the fit), cohorts

# fit() checks the tables before anything runs. `epochs = 0` stops after
# that set-up, which is a quick way to test a new data set
m <- finn(N_species = Nsp, recruits_dbh = 12.9,
          growth_process       = createProcess(~ temp + prec, growth),
          mortality_process    = createProcess(~ temp + prec, mortality),
          regeneration_process = createProcess(~ temp + prec, regeneration_capped))
fit(m, data = obs, env = env, init_cohort = init, epochs = 0L,
    patch_size = 0.06, plot_progress = FALSE)
m$env_scaling   # the standardisation of the predictors, learned from `env`

# an `env` that ends before the last census is refused, with the reason
try(fit(m, data = obs, env = env[year <= 15], init_cohort = init, epochs = 0L,
        patch_size = 0.06, plot_progress = FALSE))


How fit() compares the simulation with the observations: the loss

Description

fit() estimates the parameters by making the simulation match the observations. "Match" is measured by the loss: for each of the six responses – dbh, ba, trees, growth, mortality, regeneration – the simulated value of every site, census year and species is compared with the observed one through a likelihood, the six comparisons are added up, and fit() lowers that sum. This page explains the arguments of fit() that set the comparison: loss_family, loss_aggregation, loss_resolution, loss_weights and weight_scale, loss_recruit, and tree_data. Their defaults are robust in most cases: a first fit needs none of them.

The six responses and their likelihoods (loss_family)

Each response has its own likelihood, chosen for the kind of number it is. The defaults, following Pichler & Käber (2026):

response what is compared default alternatives
dbh mean diameter, cm "mse" (squared error) "gaussian", "none"
ba basal area per patch "mse" "gaussian", "none"
trees number of trees per patch "poisson" (a count) "nbinom", "mse", "none"
growth mean annual relative growth rate "mse" "gaussian", "none"
mortality share of the trees that died, 0 to 1 "binomial" "mse", "gaussian", "poisson", "none"
regeneration recruits per hectare over the interval "nbinom" (an overdispersed count) "poisson", "mse", "gaussian", "none"

loss_family is a named character vector; name only what departs from the defaults, e.g. loss_family = c(trees = "nbinom"). "mse" is the squared error, equivalent to a Gaussian likelihood with a fixed variance; "gaussian" additionally estimates the variance. "binomial" is the Bernoulli/binomial likelihood for a proportion in [0, 1] (the model predicts the probability of dying through a sigmoid), weighted by the number of trees at risk when data carries n_at_risk; it respects the bounds and the mean-variance link of a proportion, which "mse" ignores. "nbinom" is implemented for trees and regeneration only. "none" switches a response off: it contributes nothing and needs no column in data – use it when a response was not observed, or when its information enters through another term (e.g. dbh = "none" and ba = "none" once the size distribution is scored through size classes, below).

The rates are compared over the observation interval: with period_length in data, the simulated yearly growth and mortality are compounded into one rate per year (the geometric mean of 1 + g, one minus the geometric mean survival – as makeObsData() derives the observed rates) and simulated recruitment is summed, before they meet the observation (see finn_data and fit()). Growth is compared as a relative rate (dbh / dbh_before - 1), the model's own quantity; training against the absolute increment was tested and was worse and more seed-variable, because it couples the growth parameters to whichever trees happen to be present. finn(growth_rate = ) says whether the observed growth is a rate per time step or the increment over the whole interval.

For regeneration, "nbinom" (the default) uses the recruit dispersion theta of the regeneration process and applies finn(recruit_obs_weight = ); "poisson" has no dispersion parameter, so it cannot collapse, but in 0.2.0 it ignores recruit_obs_weight and scores per-hectare values, with trees_offset added to the prediction. See recruitment.

A missing observation (NA) is left out of its term; the other responses of that cell are still scored. A term that is not finite at a step (an overflowing likelihood) is dropped from that step with the default fit(nonfinite = "drop_term") and counted in model$nonfinite_counts.

Balancing the six terms (loss_weights, weight_scale)

The six terms are summed, and their raw sizes differ by orders of magnitude: on the bundled FIA data dbh is a squared error in cm2 (about 430 at the start) while growth is a squared error on a ratio (about 0.03). Summed as they are, dbh would take 87 % of the objective and growth 1 %, and growth would never improve.

loss_weights = "auto" (the default) fixes this without knowing the units. Each term is divided by its intercept-only baseline: the loss that predicting the single best constant (the mean of the observations) would get. Every term then measures the same thing on the same scale, the fraction of its own null deviance. For a squared error the baseline is the variance of the observations, so this is scaling by 1 / var(y); for the Poisson, negative-binomial and binomial terms it is the corresponding null deviance, where a standard deviation would be the wrong scale. The baselines are stored in model$loss_baseline, the resulting weights in model$loss_weights, and every fit reports each response's share of the objective at the baseline. It is a weighting for a balanced objective, not the joint likelihood of the six responses.

A useful side effect: the per-response values in model$history read directly as "how much better than the mean" – 1 is no better than the intercept, below 1 is better, above 1 is worse.

A numeric loss_weights vector (six numbers, in the order dbh, ba, trees, growth, mortality, regeneration) multiplies the balanced terms, so each number reads as that response's relative share: c(1, 1, 1, 2, 1, 1) gives growth twice the weight of every other response. On the FIA example, balancing the objective is worth about +0.24 Spearman correlation on held-out growth, more than tuning lr or epochs (vignette Fitting FINN to FIA data). weight_scale = FALSE (or "raw") applies the vector to the raw, unbalanced terms instead – the meaning the argument weights had before 0.2.0, kept for reproducing earlier analyses; the shares are reported in both modes.

How cohorts become the compared quantity (loss_aggregation)

The simulation works on cohorts; the observation is one number per site, year and species. loss_aggregation says how the cohorts are summarised before the comparison, per response, as a named character vector or – for a type that needs settings – a named list. Anything not named keeps its default, so the argument only ever states what departs from it:

Example – score the size distribution through stem counts and the two rates per tree:

fit(m, data = obs_dt, env = env, tree_data = tree_obs_dt,
    loss_family      = c(dbh = "none", ba = "none"),
    loss_aggregation = list(trees  = list(type = "size_classes",
                                          breaks = seq(20, 60, by = 10)),
                            growth = "tree", mortality = "tree"))

Scoring individual trees (tree_data, loss_resolution)

By default growth and mortality are scored per site, species and census, as means over cohorts. Two options score them per tree instead; both take the tree table in tree_data (finn_data lists its columns), but they ask different questions.

loss_aggregation = c(growth = "tree", mortality = "tree") predicts each OBSERVED tree: the equations run on its measured dbh at the start of the interval with the light of the observed stand, and only the yearly environment changes across the interval. It measures the error of the growth and mortality functions alone. loss_resolution = "tree" predicts each SIMULATED cohort that started as an observed tree, along the model's own trajectory (simulated growth, competitors, light). It measures the error of the functions plus the drift of the simulated stand.

loss_aggregation = "tree" loss_resolution = "tree"
the tree is observed: measured dbh, observed competitors, yearly environment simulated: the cohort it started as, along the model's trajectory
measures the growth and mortality functions alone the functions plus the drift of the simulated stand
responses chosen separately, e.g. only mortality = "tree" growth and mortality together
init_cohort any, incl. binned (makeInitCohorts(dbh_binsize = )) one cohort per tree (makeInitCohorts() without dbh_binsize)
tree_data needs dbh at the interval start cohortID of the initial cohort
combines with the simulated dbh/ba/trees/regeneration terms reanchor and teacher_forcing
diagnostics predictTrees() ⁠$tree_deaths⁠, ⁠$tree_pred⁠

Use the first to estimate the process functions from the trees as observed, the second to test whether simulated trajectories follow the real trees. The two cannot be combined in one fit.

Under loss_resolution = "tree" the two terms replace the per-cell terms rather than adding to them (scoring a response twice under two weights is a redundancy the optimiser can trade against itself); the loss vector, loss_weights and ⁠$history⁠ keep their six positions. The correspondence is carried by the cohort ids: a cohort keeps the id of the slot it was created in, so cohort j of a (site, patch) is tree j of the list that generation started from; recruits get ids above that block. A generation starts at init_cohort and restarts at every anchor under reanchor/teacher_forcing. Growth is scored over the interval as the aggregate term is, mortality as the compounded probability 1 - prod(1 - m) against the tree's 0/1 fate – never the sampled death, which at one tree is a coin flip. A cohort the simulation kills inside a window is kept with trees = 0 until its generation ends, so both terms score every tree and the scored sample does not depend on the parameters; ⁠$tree_deaths⁠ reports per census and epoch how often the simulation killed a tree the inventory found alive (frac_killed), in which year (mean_kill_year), and the share that entered the window already dead (frac_ghost). With the binned competition a killed cohort still occupies a slot of the height quantiles, so createProcess(light_mask = TRUE) (the default) or continuous = TRUE is needed for the competition process; fit() warns otherwise.

Where the recruits come from (loss_recruit)

loss_recruit = "simulated" (the default) lets the regeneration process recruit, and its parameters are estimated with the rest. An inventory samples small trees sparsely, so recruitment is the hardest process to estimate jointly: a mis-fitted regeneration process feeds a wrong stand into every later interval, and growth and mortality compensate for it. loss_recruit = "observed" therefore drives the stand with the OBSERVED recruitment: reg in data divided by period_length is the expected recruitment per hectare and year in every simulated year of that interval, drawn per patch by the recruit sampler as usual. In that call the regeneration term is weighted 0, every parameter of the regeneration process is frozen (and gets its previous state back when fit() returns), and growth, mortality and competition are estimated on a stand that recruits what was observed. The regeneration process is then fitted in a call of its own, with the other processes' optimizeSpecies and optimizeEnv off. Refused: an NA reg in an interval that needs it, a simulated year in two intervals or before a site's first interval, and reanchor/teacher_forcing. simulateForest() with recruits = "observed" simulates the same way for checking such a model; recruitment has the unit chain and the staged recipe.

Reading the fit

model$history holds the six (weighted) terms per epoch, model$loss_baseline the intercept-only baselines, model$loss_weights the weights in force, and model$param_history the parameters at every checkpoints epochs. A fit has converged when the parameters stop moving, not when the losses look flat.

References

Pichler, M., & Käber, Y. (2026). Inferring processes within dynamic forest models using hybrid modelling. Methods in Ecology and Evolution. doi:10.1111/2041-210x.70347

See Also

fit(), finn_data, recruitment, predictTrees()

Examples


library(data.table)
# three sites of the bundled Oregon FIA sample and two epochs per fit, to
# show the arguments; a real calibration uses all sites and many epochs
sites <- 1:3
Nsp   <- max(fia_obs_dt$species)
obs   <- fia_obs_dt[siteID %in% sites]
env   <- fia_env_dt[siteID %in% sites]
init  <- makeInitCohorts(fia_init_trees[siteID %in% sites], Nspecies = Nsp)
FINN.seed(1)
m <- finn(N_species = Nsp, recruits_dbh = 12.9,
          growth_process       = createProcess(~ temp + prec, growth),
          mortality_process    = createProcess(~ temp + prec, mortality),
          regeneration_process = createProcess(~ temp + prec, regeneration_capped))

# the defaults: six likelihoods, balanced by their intercept-only baselines
fit(m, data = obs, env = env, init_cohort = init, epochs = 2L,
    patch_size = 0.06, plot_progress = FALSE)
m$loss_baseline   # the loss of predicting the mean, per response
m$loss_weights    # 1 / baseline: the weight of each response
# the six terms per epoch (1 = no better than the mean); the seventh
# column is not used
do.call(rbind, m$history)

# another likelihood for the stem counts, and mean dbh left out of the loss
fit(m, data = obs, env = env, init_cohort = init, epochs = 2L,
    patch_size = 0.06, plot_progress = FALSE,
    loss_family = c(trees = "nbinom", dbh = "none"))
do.call(rbind, m$history)

# mortality scored on every observed tree instead of on the site's rate
fit(m, data = obs, env = env, init_cohort = init, epochs = 2L,
    patch_size = 0.06, plot_progress = FALSE,
    tree_data = fia_tree_dt[siteID %in% sites],
    loss_aggregation = c(mortality = "tree"))


Estimate the parameters of a FINN model

Description

Estimates the parameters of a model built with finn() from forest inventory data. The model simulates every site from its initial trees through the years of env, the simulation is compared with the observed stand variables and demographic rates in data, and the parameters of all processes – the species parameters of the mechanistic equations (for a process built with createProcess(optimizeSpecies = TRUE)), their responses to the environment, and the weights of any neural-network process – are adjusted together, in one joint optimization, until the simulation matches the observations as well as it can. The processes are never calibrated one at a time: this joint calibration is what makes the estimated processes consistent with each other.

The defaults are robust in most cases. A first call needs data, env, init_cohort, patch_size and epochs; everything else can stay as it is. finn_data explains the input tables, finn_loss how the simulation is compared with the observations.

Usage

fit(
  model,
  data = NULL,
  env,
  disturbance = NULL,
  patches = 100L,
  patch_size = 0.1,
  init_cohort = NULL,
  epochs = 20L,
  lr = 0.01,
  batchsize = NULL,
  loss_family = c(dbh = "mse", ba = "mse", trees = "poisson", growth = "mse", mortality =
    "binomial", regeneration = "nbinom"),
  loss_aggregation = NULL,
  loss_resolution = c("site", "tree"),
  loss_weights = "auto",
  weight_scale = TRUE,
  loss_recruit = c("simulated", "observed"),
  tree_data = NULL,
  control = finnControl(),
  device = c("cpu", "gpu"),
  threads = NULL,
  update_step = 1L,
  start_time = 1L,
  plot_progress = TRUE,
  folder = NULL,
  checkpoints = 100L,
  shuffle = TRUE,
  record_gradients = FALSE,
  env_autoscale = TRUE,
  nonfinite = c("drop_term", "skip_step"),
  reanchor = FALSE,
  anchor_cohorts = NULL,
  anchor_mode = "replace",
  anchor_min_dbh = NULL,
  teacher_forcing = FALSE,
  rb_gradient = TRUE,
  trees_offset = 0.01,
  holdout = NULL,
  ...,
  loss = NULL
)

Arguments

model

(finn_class)
The model built by finn().

data

(data.frame)
The observations: one row per site, census year and species, with the columns siteID, year, species, dbh, ba, trees, growth, mort and reg; optionally period_length, n_at_risk and growth_n. NA marks a response that was not observed and is left out of the comparison. makeObsData() and resolveSiteIDs() build this table from a tree list. The columns, their units, missing values and incomplete series are explained in finn_data, with the bundled fia_obs_dt as the example.

env

(data.frame)
The environment of every site and simulated year: one row per siteID and year, plus one column per predictor (for the bundled FIA data temp and prec, annual mean temperature and precipitation; see fia_env_dt). The rows are the simulated time steps, so env must cover every year from the first step to the last observation; the predictors are in natural units and standardised internally (env_autoscale). See finn_data.

disturbance

(data.frame or NULL)
Optional disturbances: one row per siteID and year with the column intensity, the probability (0 to 1) that a patch of that site loses all its trees in that year. Must have the same sites and years as env. NULL (default): no disturbance. See finn_data.

patches

(integer(1))
Number of patches per site when the fit starts from bare ground (init_cohort = NULL). Default 100. Ignored, with a warning when it differs, as soon as init_cohort is given: the patch count then comes from the initial cohorts. The patch count of the fit is stored as model$patches; simulateForest() and evaluate() take it when their patches is not given.

patch_size

(numeric(1))
Area of one patch in ha. Default 0.1. Use the plot size of the inventory (the bundled FIA data: 0.06). A model that was fitted or simulated with another patch size before gives a warning.

init_cohort

(CohortMat)
The trees of every site at the first census, from makeInitCohorts(). NULL (default) starts every site from bare ground with patches empty patches (no stems). See finn_data.

epochs

(integer(1))
Number of passes over the data. Default 20; a real calibration takes hundreds, until the parameters stop moving. epochs = 0 runs the set-up only (data tensors, loss_baseline, loss_weights) and trains nothing.

lr

(numeric(1))
Learning rate, the size of a parameter step. Default 0.01. Lower it when the losses oscillate; see also finnControl() for a learning-rate schedule.

batchsize

(integer(1))
Number of sites simulated between two parameter updates. NULL (default) takes all sites at once. Smaller batches use less memory and update more often per epoch.

loss_family

(named character)
The likelihood each response is compared with: dbh and ba by squared error ("mse"), trees by a Poisson, growth by squared error, mortality by a binomial, recruitment (regeneration) by a negative binomial. The defaults are robust in most cases; name only what departs from them, e.g. c(trees = "nbinom"), or "none" to leave a response out. See finn_loss.

loss_aggregation

(named character or list)
How the simulated cohorts are summarised before they meet an observation: the default is the mean over cohorts for dbh, growth and mortality and the sum for ba, trees and regeneration, which matches the tables makeObsData() builds. The alternatives ("size_classes", "quantiles", "tree") are described in finn_loss.

loss_resolution

(character(1))
Whether growth and mortality are scored per site, year and species ("site", default) or per individual simulated tree ("tree", which needs tree_data with a cohortID column). See finn_loss.

loss_weights

("auto" or numeric(6))
The weight of each response in the sum of the six losses, in the order dbh, ba, trees, growth, mortality, regeneration. "auto" (default) makes the six comparable by dividing each by its intercept-only baseline, so no response drowns the others; a numeric vector then multiplies these balanced terms (c(1, 1, 1, 2, 1, 1) gives growth twice the weight). Before 0.2.0 the argument was called weights, which is still accepted with a warning. See finn_loss.

weight_scale

(logical(1) or character(1))
Whether a numeric loss_weights vector applies to the baseline-balanced losses (TRUE or "auto", default) or to the raw, unbalanced losses (FALSE or "raw", the meaning of weights before 0.2.0). See finn_loss.

loss_recruit

(character(1))
Where the recruits of the simulated stand come from during the fit. "simulated" (default): from the regeneration process, which is estimated with the rest. "observed": the observed recruitment (reg in data) is fed into the simulation, the regeneration process is frozen and left out of the loss, and growth and mortality are estimated on a stand that recruits what was observed – the first stage of a staged calibration, see recruitment. Before 0.2.0 the argument was called recruits, which is still accepted with a warning. See finn_loss.

tree_data

(data.frame or NULL)
Individual observed trees, one row per tree and census, only needed to score growth or mortality per tree (loss_aggregation = "tree" or loss_resolution = "tree"). Unlike data, which holds one row per site, year and species, it holds the trees themselves. Columns and the two per-tree routes: finn_loss and finn_data.

control

(finnControl)
Settings of the optimizer: the optimizer itself, a learning-rate schedule and its parameters, gradient clipping. The defaults of finnControl() are robust in most cases.

device

(character(1))
"cpu" (default) or "gpu"; "cuda" is accepted as a synonym for "gpu". Only NVIDIA cards are supported, and a card does not always pay: see the section on speed below.

threads

(integer(1) or NULL)
torch's intra-op thread count during the fit. NULL (the default) leaves torch's setting alone, including one made through OMP_NUM_THREADS or torch::torch_set_num_threads(). Extra threads rarely pay; threads = 1 is the considerate choice when several fits share a machine. The previous count is restored afterwards where torch allows it (OpenMP builds, e.g. Linux). torch's native backend (macOS) accepts one change per session, so there the session keeps the count fit() set, and a count fixed earlier in the session cannot be changed (fit() then says so).

update_step

(integer(1))
Every how many simulated years the gradient is cut (truncated backpropagation through time). Default 1: a loss sees the processes of its own year only. The parameters are updated once per batch, with the gradients of all cuts added up. A loss is only scored at a year that is a multiple of update_step, so an observation year off that grid is not scored, and fit() stops when none is on it. The simulated state runs on uncut. Larger values let the loss see a longer stretch of the trajectory at a higher cost and with fading gradients.

start_time

(integer(1))
Reserved for a burn-in: the simulated year from which observations are scored. In 0.2.0 it has no effect – every observation year in data is scored – and a value other than 1 gives a warning. Start env at the first year you want simulated and leave out of data what should not be scored; see finn_data.

plot_progress

(logical(1))
Draw the losses of every response per epoch while fitting, each as a fraction of its value in the first epoch. Default TRUE.

folder

(character(1) or NULL)
Folder in which the model is saved every checkpoints epochs (⁠epoch_<n>model.pt⁠, readable with torch::torch_load()). NULL (default): no checkpoints.

checkpoints

(integer(1))
Every how many epochs the parameters are recorded in model$param_history and, with folder, the model is saved. Default 100.

shuffle

(logical(1))
Draw the batches in a new random order every epoch. Default TRUE.

record_gradients

(logical(1))
Also record the gradients of every parameter at each checkpoint, in model$gradients. Default FALSE; the record can get large.

env_autoscale

(logical(1) or character)
How the predictors in env are standardised before they enter the processes. TRUE (default): every predictor to mean 0 and standard deviation 1. FALSE: as supplied. Or one entry per predictor (named, or in column order): "auto", "identity", "0to1" or a function f(x) returning list(center =, scale =), e.g. c(temp = "auto", management = "identity") to keep an ordinal predictor on its own scale. The constants are stored on the model (model$env_scaling) and re-applied by simulateForest(), so env is always passed in natural units. See finn_data.

nonfinite

(character(1))
What happens when one of the six loss terms is not finite at a scored timestep (an overflowing likelihood, a target outside the family's support). "drop_term" (default) leaves only that term out of the timestep's gradient and reported loss; the other responses are still backpropagated there, and the occurrences are counted per response in model$nonfinite_counts and summarised in a warning when the fit ends. "skip_step" discards the WHOLE timestep – none of the six terms is backpropagated or reported there – which is what every version before drop_term existed did; use it to reproduce such a fit. The difference only shows once a term overflows: with finite losses the two are identical.

reanchor

(logical(1))
Fit by multiple shooting instead of single shooting. With the default FALSE the cohort state is initialised once from init_cohort and then runs free over the whole horizon, so simulation error compounds across every observation. With TRUE the simulated state is discarded at every timestep for which anchor_cohorts supplies an observed tree list and rebuilt from it, after that timestep's loss has been backpropagated – drift is then bounded by one inter-census segment. This is not the same as the gradient truncation controlled by update_step, which cuts the gradient but keeps the state; set update_step to the segment length to let the gradient span the whole segment.

anchor_cohorts

(list())
Named list of CohortMat objects, the observed state to restart from. Names are the simulation timesteps to re-anchor at (integers as characters, and entries of the model's internal year_sequence, i.e. timesteps that carry an observation). Every anchor must have the same number of species, sites and patches as init_cohort; the number of cohorts may differ between anchors and from init_cohort. The last observation year needs no anchor – nothing is simulated after it – and an anchor may not fall inside another observation's period_length window, because the aggregated rates would then mix pre- and post-anchor state. fit() copies the anchors onto its own device and never modifies them, so one list can be reused across fits. Ignored unless reanchor = TRUE.

Build the arrays directly – CohortMat(dbh = , trees = , species = , dims = , sp = ) – rather than via CohortMat(obs_df = ). The obs_df path runs obsDF2arrays(), which rounds trees to whole stems and silently renumbers any siteID/patchID that is not a complete 1:n sequence; on a simulated or partly empty stand that corrupts the anchor, and a renumbered site no longer aligns with init_cohort.

anchor_mode

(character(1))
What an anchor does to the simulated state. "replace" (default) overwrites it wholesale. "merge" keeps the simulated cohorts with dbh < anchor_min_dbh and concatenates them with the full anchor. Use "merge" whenever the inventory has a minimum-dbh threshold (FIA: 12.7 cm): an anchor built from it contains no small trees, so "replace" deletes FINN's entire regeneration pool at every census – on FIA that inflates 200-year equilibrium basal area by 41%. Nothing is double counted, because the observation is complete at and above the threshold. Ignored unless reanchor = TRUE.

anchor_min_dbh

(numeric(1))
The inventory's minimum-dbh threshold, in the units of the dbh column. Required by anchor_mode = "merge", ignored by "replace".

teacher_forcing

(logical(1))
Fit by direct estimation instead of by simulation, and never run a trajectory at all. The cohort state is reset at every timestep to the observed stand at the census that STARTS that timestep's observation interval – init_cohort for the first interval, then anchor_cohorts – so each year's demographic rates are evaluated at an observed state and the simulated state is never carried forward. The interval rates are then aggregated over the window and scored exactly as fit() already scores them, so growth, mortality and regeneration keep their usual meaning. The three STATE responses (dbh, ba, trees) leave the loss: predicting them requires a trajectory, and there is none here.

Mutually exclusive with reanchor, which is a different estimator: re-anchoring still free-runs the whole segment between two censuses and scores where it lands. update_step is inert under teacher forcing – there is no multi-year trajectory to truncate – and the anchor validation refuses any update_step that would change which observations are scored.

anchor_cohorts must supply an anchor for every observed timestep except the last (nothing is conditioned on the final census, because nothing follows it). Only fit() teacher-forces; simulateForest() always simulates, so a teacher-forced model is still validated by single shooting.

rb_gradient

(logical(1))
Take the gradient of the drawn death and recruitment counts through their expectation instead of through the draw. The stand still dies and recruits discretely, but the reparameterised draw and the rounding's surrogate no longer carry the sampler's noise into the gradient (on a national inventory most of the mortality gradient was draw noise without it). Default TRUE since 0.2.0; set FALSE to reproduce a fit made before that. The setting also decides which death draw the default createProcess(mortality_draw = "binomial") uses: the exact binomial with TRUE, the Gamma draw of earlier versions with FALSE (see createProcess()). It is stored on the model, so later simulations draw the same way as the last fit.

trees_offset

(numeric(1))
Offset added to the predicted stem count before the trees count likelihood, which is -Inf (poisson) or arbitrarily steep (nbinom) where a species' simulated count is exactly zero and the observed one is not. On the scale of the predicted count, so per patch. The default 0.01 keeps that cell's gradient comparable with every other term; the historical 1e-5 (poisson) and 0.001 (nbinom) left it at y/offset, four orders above the rest. NULL restores those two historical constants and so reproduces a fit made before 0.2.0.

holdout

NULL (default), or a list with holdout data, env and init_cohort (and optionally disturbance and tree_data), as the holdout of evaluate(): after the fit, evaluate() simulates the training data and the holdout and stores the comparison on the model (model$evaluation, an object of class finn_evaluation with a print() and a plot() method), which summary.finn_class() prints. The same as calling evaluate(model, holdout = ) after the fit, except that fit() returns the model; if that evaluation fails, the fit is kept and a warning says why.

...

Arguments of earlier versions, still accepted with a warning: weights (now loss_weights), recruits (now loss_recruit), and optimizer, lr_scheduler, lr_scheduler_params, clip_norm (now members of control, see finnControl()). Any other named argument is passed on to the optimizer, as before; finnControl() is the place for it now.

loss

Deprecated name of loss_family, still accepted with a warning.

Details

What happens in a fit. Every epoch, fit() takes the sites in batches of batchsize, simulates each batch over the years of env starting from init_cohort, and at every year that has observations compares the simulated mean dbh, basal area, number of trees, growth, mortality and recruitment with the observed ones, response by response, through the likelihoods in loss_family. The six comparisons are added up into one number, the loss, and every parameter is moved a small step (lr) in the direction that lowers it. FINN is written in torch, so these directions (gradients) come from automatic differentiation; no knowledge of torch is needed. After epochs passes over the data the model holds the estimated parameters; fit() changes the model in place and also returns it. The per-response losses of every epoch are in model$history.

Rates over an observation interval. An inventory interval of period_length years is that many simulated years. The simulated yearly rates of those years are compounded into one rate per year before they meet the observation, with the same functional makeObsData() uses for the observed rate: growth as the geometric mean of 1 + g minus one, mortality as one minus the geometric mean of the yearly survival 1 - m; the recruits are summed and the stand variables are taken at the census year. A year in which a species has no trees in the simulation counts as growth 0 and survival 1, and the rate is spread over the full period_length, because the observed rate is derived from the counts over the whole interval. With finn(growth_rate = "period") growth is the compounded increment over the interval instead.

Reading the progress. With the default loss_weights = "auto" every response's loss is reported as a fraction of the loss a constant prediction (the mean of the observations) would get: 1 means no better than the mean, below 1 better. model$history holds these fractions, one vector per epoch in the order dbh, ba, trees, growth, mortality, regeneration (a seventh, unused entry is 0); the plot drawn with plot_progress = TRUE shows each of them relative to its value in the first epoch. A fit has converged when the parameters stop moving (model$param_history), not merely when the losses look flat; see the vignette Fitting FINN to FIA data.

Long simulated series. Taking the gradient through a long simulation is slow and the signal fades. fit() therefore cuts the gradient every update_step years; the gradients of the cuts are added up and the parameters are updated once per batch of sites. The simulated state itself runs on uncut. The default of one year is the fastest and the most short-sighted; larger values let a loss see further back at a higher cost.

Advanced estimators. reanchor restarts the simulated stand from the observed trees at every census (multiple shooting), teacher_forcing evaluates the rates on the observed stands and never simulates a trajectory, and loss_resolution/loss_aggregation = "tree" score single trees. They are for specific questions; the default single-shooting fit is what the vignettes use.

Value

The fitted model, invisibly. fit() trains the model in place, so the returned object is the one passed in, now carrying the training results (e.g. ⁠$history⁠, ⁠$loss_weights⁠, ⁠$loss_baseline⁠, ⁠$param_history⁠), the patch count of the fit (⁠$patches⁠) and, with holdout, the evaluation (⁠$evaluation⁠).

What makes a fit faster, and what does not

A fit is bound by the number of small tensor operations a simulated year issues, not by the arithmetic in them. So a GPU does not always pay (measure one configuration before committing a long fit to it), more threads rarely help (threads = 1 is usually fastest and the considerate setting on a shared machine), and several fits run side by side use a machine better than one fit given all of it. What does shorten a fit is fewer epochs: watch model$param_history and stop when the parameters settle instead of fixing a large epochs in advance.

Bounds on simulated mortality

Before the death draw, the simulation clamps the per-cohort mortality probability of every step to the interval createProcess(mortality_floor = 0.001, mortality_ceiling = 0.999) of the mortality process, so at least 0.1 % and at most 99.9 % of a cohort is at risk per simulated step however extreme the fitted rate. The bound is per step, not per year: on five-year steps the floor is 0.02 %/yr, on decadal ones 0.01 %/yr. Until 0.2.0 the interval was hard-coded to ⁠[0.01, 0.99]⁠, which made simulated low-mortality stands lose stems the observations did not. The per-tree mortality loss is not affected by either bound; it clamps at 1e-6. See createProcess().

The arguments that shape the loss, and how they combine

Ten arguments change what fit() optimises. They are not alternatives to one another: each sits on its own axis, and a fit picks one value on every axis. finn_loss carries the detail; this is the map.

axis argument what it decides default
which responses are scored ⁠loss_family = c(<response> = "none")⁠ leaves that response out of the loss entirely all six scored
which likelihood loss_family the distribution each response is compared with mse, mse, poisson, mse, binomial, nbinom
how the simulation is summarised loss_aggregation what the cohorts are reduced to before they meet an observation: "mean", "sum", "size_classes", "quantiles", "tree" mean for dbh, growth, mortality; sum for ba, trees, regeneration
at what resolution growth and mortality are scored loss_resolution "site": per site, year and species. "tree": per simulated cohort that started as an observed tree "site"
how the six terms are combined loss_weights, weight_scale "auto" divides each term by its intercept-only baseline; a numeric vector then multiplies those balanced terms, or the raw ones under weight_scale = "raw" "auto", "auto"
where the recruits come from loss_recruit "observed" feeds the observed recruitment into the simulation, freezes the regeneration process and drops its loss term "simulated"
how the state is propagated reanchor + anchor_cohorts, anchor_mode, anchor_min_dbh; teacher_forcing the estimator -- see the table below single shooting
how far the gradient reaches update_step truncated backpropagation through time: the gradient is cut every update_step years, the state is not 1

The three estimators differ in how much of the trajectory each gradient sees, and therefore in what the fit is asked to get right:

state over the horizon scored responses needs
single shooting (default) initialised once, free-running to the end; error compounds across every census all six init_cohort
multiple shooting (reanchor = TRUE) free-running within a census interval, rebuilt from the observed trees at each anchor after that step's loss all six anchor_cohorts per observed timestep
direct estimation (teacher_forcing = TRUE) never carried forward: reset to the observed stand at every timestep growth, mortality, regeneration only -- dbh, ba and trees leave the loss, because predicting them needs a trajectory anchor_cohorts for every observed timestep but the last

update_step is a different axis from all three: it cuts the gradient but keeps the state, so under single shooting the stand still compounds while the parameters only see update_step years at a time. It is inert under teacher forcing, where there is no multi-year trajectory to truncate.

What cannot be combined:

What a value silently implies: loss_recruit = "observed" removes the regeneration term, so a fit under it cannot be compared with one under "simulated" by its total loss; teacher_forcing = TRUE removes three more; and loss_weights = "auto" rescales whatever is left, so the total loss is only comparable between fits that score the same set of responses.

See Also

finn_data for the input tables, finn_loss for how the simulation is compared with the observations, finnControl() for the optimizer settings, recruitment for the recruitment options (loss_recruit, the regeneration likelihood), simulateForest() to simulate with the fitted model, evaluate(), summary.finn_class() and plot.finn_class() to judge the fit

Examples


library(data.table)
# three Oregon FIA sites over two epochs; a real calibration runs hundreds
sites <- 1:3
Nsp   <- max(fia_obs_dt$species)
init  <- makeInitCohorts(fia_init_trees[siteID %in% sites], Nspecies = Nsp)
FINN.seed(1)
m <- finn(N_species = Nsp, recruits_dbh = 12.9,
          growth_process       = createProcess(~ temp + prec, growth),
          mortality_process    = createProcess(~ temp + prec, mortality),
          regeneration_process = createProcess(~ temp + prec, regeneration_capped))
fit(m, data = fia_obs_dt[siteID %in% sites], env = fia_env_dt[siteID %in% sites],
    init_cohort = init, epochs = 2L, patches = 4, patch_size = 0.06,
    plot_progress = FALSE)

# the per-response losses over the epochs, and the baselines they were
# scaled by to make `loss_weights = "auto"` comparable across responses
tail(m$history, 2)
m$loss_baseline

# give growth twice the weight of every other response, and lower the
# learning rate every 50 epochs
fit(m, data = fia_obs_dt[siteID %in% sites], env = fia_env_dt[siteID %in% sites],
    init_cohort = init, epochs = 2L, patches = 4, patch_size = 0.06,
    loss_weights = c(1, 1, 1, 2, 1, 1),
    control = finnControl(lr_scheduler = "step",
                          lr_scheduler_params = list(step_size = 50, gamma = 0.5)),
    plot_progress = FALSE)


Growth

Description

FINN's mechanistic growth process: the relative diameter growth of a cohort in one simulation step, growth = shade * exp(pred) * exp(-parGrowth[, 2] * dbh), so that the diameter after the step is dbh * (1 + growth). shade is the light response, a sigmoid in the available light centred on the species' light requirement parGrowth[, 1] and rescaled to run from 0 in full shade to 1 in full light; exp(pred) is the species' environmental response; and the last term lets the relative growth decline with size at the species' rate parGrowth[, 2] (per cm).

Usage

growth(
  dbh,
  species,
  parGrowth,
  pred,
  light,
  light_steepness = 10,
  debug = FALSE,
  trees = NULL
)

Arguments

dbh

torch.Tensor Diameter at breast height of each cohort, in cm.

species

torch.Tensor (int64) Species index of each cohort.

parGrowth

torch.Tensor Growth parameters per species, two columns: the light requirement of the shade response (between 0 and 1) and the size decay (per cm).

pred

torch.Tensor Environmental response per species, on the log scale.

light

torch.Tensor Available light for each cohort (0 to 1), from competition().

light_steepness

numeric Steepness of the light-response sigmoid. Defaults to 10.

debug

logical If TRUE, return the intermediate components as a list (shade, light, environment, growth). Defaults to FALSE.

trees

torch.Tensor (Optional) Number of trees per cohort. Not part of the equation; the model passes it for its records. Defaults to NULL.

Value

torch.Tensor The relative diameter growth of each cohort per simulation step, ⁠[sites, patches, cohorts]⁠, non-negative; or, if debug = TRUE, a list of the intermediate components.

See Also

createProcess(), mortality(), which takes this growth as an input, finn(), predictTrees() to evaluate the fitted function on observed trees

Examples


# growth as the growth process of a model: the equation above with its two
# species parameters, and a linear response to one environmental predictor
m <- finn(N_species = 2, growth_process = createProcess(~ 1 + temp, growth))

# a 30-year simulation from bare ground on one site. A model that was not
# fitted has no scaling constants for `env` yet and uses it as given, so the
# predictor is passed standardised (0 = an average site).
env <- data.frame(siteID = 1L, year = 1:30, temp = 0)
sim <- simulateForest(m, env = env, patches = 5, patch_size = 0.1)
tail(sim$wide$site)


Calculate the height of a tree based on its diameter at breast height and an allometry parameter

Description

Calculate the height of a tree based on its diameter at breast height and an allometry parameter

Usage

height(dbh, parHeight)

Arguments

dbh

A numeric value representing the diameter at breast height of the tree in cm.

parHeight

A numeric value representing the species height allometry.

Details

This function calculates the height of a tree based on the diameter at breast height (dbh) and a parameter parHeight.

The height is calculated using the formula:

height = \left( \exp \left( \frac{(\text{dbh} \times \text{parHeight})}{(\text{dbh} + 100)} \right) - 1 \right) \times 100 + 0.001

where dbh is the diameter at breast height of the tree in cm and parHeight is an allometric species specific parameter.

As the diameter grows, the height approaches (\exp(\text{parHeight}) - 1) \times 100 m: 35 m for parHeight = 0.3, 65 m for 0.5, 101 m for 0.7. When the height parameter is fitted (the first column of the competition parameters), FINN keeps it between 0.3 and \log(2.3) \approx 0.83, so no species can grow taller than 130 m, the physical limit of tree height (Koch et al. 2004). Values below 0.3 suit small trees and shrubs; set createProcess(lower = ) for them.

Value

A numeric vector (or torch.Tensor, for tensor input) with the height of the tree in m.

References

Koch, G. W., Sillett, S. C., Jennings, G. M. & Davis, S. D. (2004). The limits to tree height. Nature 428, 851-854.

Parameter range

See Also

competition(), which ranks the cohorts of a patch by this height

Examples

# a 30-cm tree of a species with parHeight = 0.5 is about 12 m tall
height(30, 0.5)
# the same diameter for a tall-growing and a short-growing species
height(c(30), c(0.5,0.3))
# two diameters of one species
height(c(30,20), c(0.5))

# the height curve of three species; the asymptote is (exp(parHeight) - 1) * 100 m
dbh <- seq(0, 150, by = 10)
round(sapply(c(low = 0.3, mid = 0.5, tall = 0.7), function(p) height(dbh, p)), 1)


Make initial cohorts for FINN

Description

Builds the initial state of a fit or a simulation, the init_cohort of fit and simulateForest, from the trees of the first inventory: every tree becomes a cohort of its own, or, with dbh_binsize, the trees of a patch and species are pooled into diameter classes. The function prepares obs_df in the format expected by CohortMat and calls it. The long-table schema of obs_df is:

Usage

makeInitCohorts(
  init_trees,
  dbh_binsize = NULL,
  min_dbh = NULL,
  Nspecies,
  treeID_table = FALSE,
  singleCohortTreeNames = NULL
)

Arguments

init_trees

data.table of initial trees with columns siteID, patchID, species, dbh (cm), treeName and trees (the number of trees the row stands for, usually 1). Without dbh_binsize a column cohortID is added to the table by reference.

dbh_binsize

numeric or NULL. Bin width in cm. If NULL, keep exact DBH.

min_dbh

numeric or NULL. Lower bound for binning. If NULL, uses min DBH.

Nspecies

integer. Number of species levels passed to sp.

treeID_table

logical. If TRUE, also return the cohort table used.

singleCohortTreeNames

character vector or NULL. Tree names excluded from binning and kept as single-tree cohorts.

Details

Aggregates initial trees into cohorts by DBH bins or exact DBH and constructs a FINN::CohortMat object.

Internally calls:

FINN::CohortMat(
  obs_df = <data.frame with columns siteID, patchID, cohortID, species, dbh, trees>,
  dbh    = NULL,
  trees  = NULL,
  species= NULL,
  dims   = c(S, P, K),   # inferred from obs_df
  sp     = Nspecies,     # passed from argument
  device = "cpu"
)

Key fields of the resulting CohortMat (a torch nn_module):

Value

If treeID_table = FALSE, a FINN::CohortMat object. If TRUE, a list with:

See Also

CohortMat, resolveSiteIDs, which calls this function for the first inventory, fit and simulateForest (init_cohort), finn_data

Examples


library(data.table)
# one cohort per observed tree, which is what `loss_resolution = "tree"` needs
init <- makeInitCohorts(fia_init_trees[siteID %in% 1:3],
                        Nspecies = max(fia_obs_dt$species))
dim(init$dbh)   # sites x patches x cohorts

sum(init$trees_r)   # the living trees of the three sites

# 5 cm diameter bins instead: fewer cohorts, so a much cheaper simulation.
# Binning adds up `trees`; rows without a count (the records of dead trees
# in this table, trees = NA) carry no stems, so leave them out first, or a
# bin holding only such rows becomes an empty cohort
living <- fia_init_trees[siteID %in% 1:3 & !is.na(trees)]
binned <- makeInitCohorts(living, dbh_binsize = 5,
                          Nspecies = max(fia_obs_dt$species))
dim(binned$dbh)
sum(binned$trees_r)   # the same trees in fewer cohorts

# the cohort table behind the tensors, with the cohort of every tree
tab <- makeInitCohorts(living, Nspecies = max(fia_obs_dt$species),
                       treeID_table = TRUE)
head(tab$init_trees[, .(siteID, patchID, cohortID, species, dbh, trees, treeName)])


Create observation data from trees

Description

Derives stand metrics by site/patch/species/year from tree measurements, filters sites, harmonizes years, optionally aggregates by site.

Usage

makeObsData(
  tree_dt,
  plotsize,
  aggregate_by_site = TRUE,
  minNyears = 2,
  fix_period_length = NULL,
  dbh_growth_thresh = c(-10, 50),
  Npatches = NULL,
  Nspecies = NULL,
  NspeciesQuantile = NULL,
  rates = c("annual", "interval")
)

Arguments

tree_dt

data.table of tree records with siteName, patchName, year, treeName, species_name, dbh, status (one of "alive", "new", "dead") and living. Mortality is derived from status; a mort column, if present, is ignored.

plotsize

numeric plot area used to scale recruitment.

aggregate_by_site

logical. Aggregate patches to site level. Default TRUE.

minNyears

integer or NULL. Keep sites with at least this many years and equal counts across patches. Default 2.

fix_period_length

integer or NULL. If set, drop sites whose inventory interval differs. Default NULL.

dbh_growth_thresh

length-2 numeric or NULL. Drop sites where any tree dbh change falls outside this range. Default c(-10, 50).

Npatches

integer or NULL. If set, keep only sites with exactly this many patches.

Nspecies

integer or NULL. Cap species to the top N (others merged to "other").

NspeciesQuantile

numeric in (0,1] or NULL. Choose the smallest N covering this fraction of individuals. Used only when Nspecies is NULL: if both are given, Nspecies takes precedence.

rates

"annual" (default) or "interval": the unit of growth and mort. "annual" returns them per year, for a model simulated in yearly steps: a tree's growth over an interval of p years is (dbh/dbh_{before})^{1/p} - 1, and the mortality of a cohort is 1 - (1 - n_{died}/n_{at\,risk})^{1/p}, the constant yearly rates that compound to what was observed over the interval. "interval" returns them over the whole interval (dbh/dbh_before - 1 and n_died / n_at_risk), the output of FINN 0.1.0, for a model in which one simulation step is one census interval. p is year - year_before in the units of year, so year must be the calendar year of the inventory.

Details

FINN simulates the forest in steps of one year. With rates = "annual" the observation table is in the units that fit() compares with such a simulation: fit() compounds the simulated yearly growth and mortality of the period_length years before each census into one rate per year with the same functional (the geometric mean of 1 + g minus one, one minus the geometric mean survival), and sums the simulated recruits over them (see finn_data). rates = "interval" belongs with resolveSiteIDs(time_axis = "census"), where one simulation step is one census interval and nothing is compounded. The counts (n_at_risk, n_died, growth_n) and reg stay quantities of the whole interval in both modes: the counts weight the likelihood by the number of trees behind an observation, and reg is compared with the recruits summed over the interval. To use the table, express year as years since the first inventory, give env one row per site and year from 1 to the last census, and build the initial cohorts from the first inventory; resolveSiteIDs does all three.

Value

A list with:

See Also

resolveSiteIDs for the next step (integer ids, the annual time axis, the initial cohorts), finn_data for the tables fit takes, fia_obs_dt for a finished example, and vignette("C-Data_preparation", package = "FINN")

Examples

library(data.table)
# A tree list of eight Oregon FIA plots with four patches and three inventories
# each, one row per tree and inventory: siteName, patchName, treeName, year,
# species_name, dbh (cm), status ("new", "alive", "dead") and living.
tree_dt <- fread(system.file("extdata", "example_tree_dt.csv", package = "FINN"))
head(tree_dt[, .(siteName, patchName, treeName, year, species_name, dbh, status)])

obs <- makeObsData(
  tree_dt[complete == TRUE],    # fully remeasured plots only
  plotsize          = 0.06,     # ha per patch; recruits are scaled to per hectare
  aggregate_by_site = FALSE,    # keep the patches: resolveSiteIDs() needs them
  fix_period_length = 10,       # drop plots whose remeasurement interval is not 10 years
  NspeciesQuantile  = 0.98)     # species covering 98 % of the stems; the rest is "other"
head(obs$obs_dt)

# mortality is a closed cohort: the trees alive at the start of the interval
# and how many of them had died by its end; `mort` is the yearly rate over the
# period_length years of the interval
obs$obs_dt[n_at_risk > 0, .(siteName, patchName, year, period_length, species_name,
                            n_at_risk, n_died, mort)][1:5]
# growth is a yearly rate too, and travels with the number of trees behind it
obs$obs_dt[growth_n > 0, .(siteName, year, species_name, growth, growth_n)][1:5]

# the same table with the rates over the whole ten-year interval (FINN 0.1.0)
obs10 <- makeObsData(tree_dt[complete == TRUE], plotsize = 0.06, aggregate_by_site = FALSE,
                     fix_period_length = 10, NspeciesQuantile = 0.98, rates = "interval")
obs10$obs_dt[growth_n > 0, .(siteName, year, species_name, growth, growth_n)][1:5]


Mortality

Description

FINN's mechanistic mortality process: the probability that a tree of a cohort dies in one simulation step. It is a logistic function of four terms, p = sigmoid(pred + light * parMort[, 1] + parMort[, 2] * dbh/100 + growth/growth_scale * parMort[, 3]), with one coefficient per species for each of shade, size and growth. pred is the species' environmental response on the logit scale, so a species with no environmental predictors dies at a constant rate. Growth enters as the rate the growth process produced in the same step, which is what makes mortality depend on a tree's recent performance rather than on its size alone.

The probability is clamped to ⁠[mortality_floor, mortality_ceiling]⁠ (default 0.001 / 0.999 per simulation step) and the number of deaths is then drawn with mortality_draw; both are settings of createProcess().

Usage

mortality(
  dbh,
  species,
  trees,
  parMort,
  pred,
  light,
  base_steepness = 5,
  debug = FALSE,
  growth = NULL,
  growth_scale = 0.01
)

Arguments

dbh

torch.Tensor Diameter of each cohort, in cm.

species

torch.Tensor Species index of each cohort.

trees

torch.Tensor Number of trees in each cohort.

parMort

torch.Tensor Mortality parameters per species, three columns: the shade, size and growth coefficients of the logit.

pred

torch.Tensor Environmental response per species, on the logit scale.

light

torch.Tensor Available light for each cohort.

base_steepness

numeric Not used by this function; kept in the signature for custom mortality functions written against it.

debug

logical If TRUE, return a list with the light (light), the mortality probability before any further step (environment) and the returned probability (predM, identical to environment). Defaults to FALSE.

growth

torch.Tensor (Optional) Growth entering the mortality response; defaults to the model's current growth.

growth_scale

numeric Growth enters the logit as growth / growth_scale. The default 0.01 expresses the annual relative growth in %/yr (about one standard deviation of observed growth), so that the growth coefficient parMort[, 3] acts per 1 %/yr and its bounds of +-10 allow a meaningful effect. With the raw rate (growth_scale = 1, the behaviour before 0.2.0) the term spans only a few tenths on the logit between slow and fast trees even at the bound. Set it for a fitted model through createProcess(func = FINN::mortality, growth_scale = 1), not through a wrapper function: the kernel reads self$record_raws from its own environment and a wrapper leaves that unbound.

Value

A torch tensor of per-cohort mortality probabilities per simulation step, ⁠[sites, patches, cohorts]⁠.

The starting value

The environmental response is sigmoid(pred). Before any fitting it starts at about 2 % mortality per time step: the intercept of the response is qlogis(0.02) and its other weights are 0 (with createProcess(hidden = ) the bias of the output layer carries the intercept), and the species terms for light, size and growth move it by at most about one logit unit. Until 0.2.0 the weights started at torch's random values, i.e. at sigmoid(0) = 0.5 per step, which on yearly steps emptied an unfitted stand within a decade. createProcess(initEnv = ) sets another start; a formula without an intercept (~ 0 + temp) leaves torch's start in place.

See Also

createProcess() (mortality_draw, mortality_floor, growth_scale), growth(), finn(), predictTrees() to evaluate the fitted function on observed trees

Examples


# mortality as the mortality process of a model, responding to one predictor;
# growth enters in %/yr (growth_scale = 0.01, the default)
m <- finn(N_species = 2,
          mortality_process = createProcess(~ 1 + temp, mortality, growth_scale = 0.01))

# a 30-year simulation from bare ground; an unfitted model uses `env` as
# given (no scaling constants yet), so the predictor is passed standardised
env <- data.frame(siteID = 1L, year = 1:30, temp = 0)
sim <- simulateForest(m, env = env, patches = 5, patch_size = 0.1)
tail(sim$wide$site)

# the start of the environmental response: qlogis(0.02) and 0 per species
as.matrix(m$nn_mortality$parameters[[1]])


Convert a cohort table to arrays

Description

Reshapes a long cohort table (one row per cohort) into the ⁠[sites, patches, cohorts]⁠ arrays FINN works on. It is the step behind CohortMat(obs_df = ) and makeInitCohorts(); array2obsDF() is the way back.

Usage

obsDF2arrays(obs_dt, additional_cols = character(0))

Arguments

obs_dt

data.frame The cohort table, with the columns siteID, patchID, cohortID (integers; cohortID numbers the cohorts within a patch from 1), species (integer code), dbh (cm) and trees (number of trees in the cohort; rounded to whole trees).

additional_cols

character vector Optional. Further numeric columns of obs_dt to return as arrays of the same shape.

Value

A named list of arrays species, dbh, trees (and one per additional_cols), each of dimension sites x patches x largest number of cohorts in a patch. Slots without a cohort hold dbh = 0, trees = 0 and the placeholder species = 1. The site dimension follows the sorted user siteIDs (sorted with method = "radix", so independent of the locale); the user ids in that order are attached as attribute "site_ids", so a site set that is not 1:N keeps its identity. CohortMat stores them as ⁠$site_ids⁠, and fit / predict.finn_class check them against data and env.

See Also

array2obsDF(), CohortMat, makeInitCohorts()

Examples

obs_dt <- data.frame(
  siteID = c(1, 1, 2), patchID = c(1, 2, 1), cohortID = c(1, 1, 2),
  species = c(1, 2, 1), dbh = c(10, 20, 30), trees = c(100, 200, 150),
  height = c(5, 10, 15))
result <- obsDF2arrays(obs_dt, additional_cols = c("height"))
dim(result$dbh)     # 2 sites x 2 patches x 2 cohort slots
result$dbh[1, , ]   # site 1: one cohort in each patch
result$trees[2, , ] # site 2: patch 1 holds a cohort in slot 2, patch 2 is empty

Plot ALE curves of a FINN model

Description

Plots the accumulated local effect (ALE) curves produced by ALE() as a grid: one row per demographic process (growth, mortality, regeneration) and one column per environmental predictor. When several species are present, their curves are overlaid in the same panel as one coloured line each.

Usage

## S3 method for class 'FINNale'
plot(x, process = NULL, scale = FALSE, species_names = NULL, ...)

Arguments

x

an object of class FINNale (returned by ALE()).

process

(character|NULL)
restrict the plot to one process ("growth", "mortality" or "regeneration"); NULL (default) plots all three.

scale

(logical(1))
if TRUE, divide each curve by the SD of its process x species rate so the effects are dimensionless and comparable (a shared y-axis is then used); if FALSE (default) the raw ALE is shown with free y-axes.

species_names

Species names for the legend (see plot.finn_class()); NULL (default): the names the model keeps from fit().

...

currently ignored.

Value

invisibly, the ggplot object.

See Also

ALE()

Examples


library(data.table)
# a small model fitted on two Oregon FIA sites (see ?fit), then its ALE curves
sites <- 1:2
Nsp   <- max(fia_obs_dt$species)
init  <- makeInitCohorts(fia_init_trees[siteID %in% sites], Nspecies = Nsp)
FINN.seed(1)
m <- finn(N_species = Nsp, recruits_dbh = 12.9,
          growth_process       = createProcess(~ temp + prec, growth),
          mortality_process    = createProcess(~ temp + prec, mortality),
          regeneration_process = createProcess(~ temp + prec, regeneration_capped))
fit(m, data = fia_obs_dt[siteID %in% sites], env = fia_env_dt[siteID %in% sites],
    init_cohort = init, epochs = 1L, patches = 4, patch_size = 0.06,
    plot_progress = FALSE)

ale <- ALE(m, plot = FALSE)
plot(ale, process = "growth")
# all three processes on a common, dimensionless scale
plot(ale, scale = TRUE)


Plot the fitted parameters of a FINN model

Description

Draws the fitted parameters themselves, per species, on the scale on which they enter the model – no simulation is involved. By default the process parameters; pars = "env" switches to the environmental niches.

Usage

## S3 method for class 'finn_class'
plot(
  x,
  pars = c("process", "env"),
  species = NULL,
  env = NULL,
  species_names = NULL,
  parameter_names = NULL,
  ...
)

Arguments

x

A model built by finn(), usually fitted with fit().

pars

Which parameters: "process" (default) the species-specific process parameters, "env" the environmental niches. The argument and its two values are those of the plot() method of FINN 0.1.0, so a call such as plot(m, pars = "env") keeps working.

species

Species numbers to draw; NULL (default) all.

env

Table whose predictor ranges the niches span, in the format of the env of fit() (see finn_data); NULL (default) the environment the model was fitted on. Only used with pars = "env".

species_names

Species names for the labels: a character vector in species order, a vector named by species number, or a table with species and species_name. NULL (default): the names fit() kept from the species_name column of the data, else "species 1", "species 2", ...

parameter_names

Names of the species-specific parameters of a process function of your own, as a list by process, e.g. list(mortality = c("shade", "size", "growth")). NULL (default): the documented names for FINN's own process functions (growth(), mortality(), regeneration(), regeneration_capped(), competition()), else "parameter 1", "parameter 2", ...

...

Unused.

Details

Value

The ggplot object, invisibly (NULL when there is nothing to draw); it is printed.

See Also

ALE() for the effect of a network response, summary.finn_class() for the skill, the convergence and the environmental importances of a fit, plot.finn_simulation() for a simulation.

Examples


library(data.table)
sites <- 1:3
Nsp   <- max(fia_obs_dt$species)
init  <- makeInitCohorts(fia_init_trees[siteID %in% sites], Nspecies = Nsp)
FINN.seed(1)
m <- finn(N_species = Nsp, recruits_dbh = 12.9,
          growth_process       = createProcess(~ temp + prec, growth),
          mortality_process    = createProcess(~ temp + prec, mortality),
          regeneration_process = createProcess(~ temp + prec, regeneration_capped))
fit(m, data = fia_obs_dt[siteID %in% sites], env = fia_env_dt[siteID %in% sites],
    init_cohort = init, epochs = 2L, patches = 4, patch_size = 0.06,
    plot_progress = FALSE)
plot(m)
plot(m, pars = "env", species = 1:3)


Plot a FINN simulation

Description

Draws the trajectories returned by simulateForest() or predict(): one panel per response, one line per species, averaged over the sites (dbh over the sites where the species has trees); with sites one site (or the average over a few). To see every site, loop over them. The n_species leading species are coloured and named, every other species is a pale grey line, and the stand total of ba and trees is dashed.

Usage

## S3 method for class 'finn_simulation'
plot(
  x,
  y = NULL,
  response = NULL,
  sites = NULL,
  ...,
  n_species = 6L,
  species_names = NULL
)

## S3 method for class 'finn_simulation'
print(x, ...)

Arguments

x

The object returned by simulateForest() or predict() (class finn_simulation).

y

NULL (default), or observations to compare with (the obs of comparePlot()).

response

Responses to draw, any of "dbh", "ba", "trees", "growth", "mort", "reg", "r_mean_ha"; NULL (default) the stand variables ba, dbh and trees. With y, as in comparePlot().

sites

Site ids to include; NULL (default) all.

...

plot(): passed to comparePlot() when y is given (type, species), otherwise unused. print(): passed to the print method of a list.

n_species

Number of species drawn in colour: those reaching the highest value of the first response; every other species is a pale grey line. Default 6. With y, the n_species of comparePlot() (its default when not given).

species_names

Species names for the legend (see plot.finn_class()); NULL (default): the names the simulation carries from the model.

Details

A bare-ground run (simulateForest(bare_ground = TRUE)) is drawn as a succession: basal area by default, one panel per site, labelled with the site's mean climate.

Given observations as the second argument, plot(sim, obs) compares the simulation with them instead: it is comparePlot(), with the same arguments.

print() of a simulation shows the list of tables as before 0.2.0, without the class attribute.

Value

plot(): the ggplot object, invisibly; it is printed. print(): x, invisibly.

See Also

plot.finn_class() for the fitted parameters, comparePlot() and evaluate() for the comparison with observations.

Examples


library(data.table)
sites <- 1:3
Nsp   <- max(fia_obs_dt$species)
init  <- makeInitCohorts(fia_init_trees[siteID %in% sites], Nspecies = Nsp)
FINN.seed(1)
m <- finn(N_species = Nsp, recruits_dbh = 12.9,
          growth_process       = createProcess(~ temp + prec, growth),
          mortality_process    = createProcess(~ temp + prec, mortality),
          regeneration_process = createProcess(~ temp + prec, regeneration_capped))
fit(m, data = fia_obs_dt[siteID %in% sites], env = fia_env_dt[siteID %in% sites],
    init_cohort = init, epochs = 2L, patches = 4, patch_size = 0.06,
    plot_progress = FALSE)
sim <- simulateForest(m, env = fia_env_dt[siteID %in% sites], init_cohort = init)
plot(sim)
plot(sim, response = c("growth", "mort"), sites = 1)
# against the observations
plot(sim, fia_obs_dt[siteID %in% sites])


Convert Prediction Arrays to Data Frames

Description

This function takes prediction arrays from a model output and converts them into data frames. The data frames can be returned in either 'wide' or 'long' format. The function processes site-level, patch-level, and cohort-level predictions.

Usage

pred2DF(pred, format = "wide")

Arguments

pred

A list containing prediction arrays for site-level, patch-level, and cohort-level data. Each element of pred should have a structure similar to what is outlined in the details section.

format

A character string indicating the desired format of the output data frames. Must be either "wide" (default) or "long".

Details

The pred argument should be a list containing at least a Predictions element, which itself is a list of arrays. The arrays represent predictions for different metrics such as dbh/ba, tree counts, AL (aboveground live biomass), growth rates, mortality rates, and regeneration rates for sites, patches, or cohorts. The dimensionality of the arrays should correspond to different factors, such as siteID, year, species, and optionally patch or cohortID.

The function first converts each prediction array into a data frame, properly naming and converting the relevant dimensions. It then merges these data frames by common identifiers such as siteID, year, species, patch, and cohortID. Depending on the format parameter, the data frames are returned in either a wide format (one row per site/patch/cohort per year with multiple columns for different metrics) or a long format (one row per site/patch/cohort per year per metric).

Value

A list of data frames. The list may contain up to three elements: site, patch, and cohort, corresponding to the processed site-level, patch-level, and cohort-level predictions, respectively.

See Also

predict.finn_class() / simulateForest(), which call this function and return its result as ⁠$wide⁠ and ⁠$long⁠

Examples

# a minimal prediction object of the shape pred2DF() expects: one array
# [site, year, species] per variable. predict()/simulateForest() build it
# from the simulation and return the tables, so pred2DF() is rarely called
# directly.
metrics <- c("dbh", "ba", "trees", "growth", "mort", "reg", "r_mean_ha")
arr <- array(1, dim = c(1, 2, 3), dimnames = list(1, 1:2, 1:3))  # [site, year, species]
pred <- list(Predictions = list(Site = stats::setNames(
  lapply(metrics, function(m) arr), metrics)))
result <- pred2DF(pred, format = "long")
head(result$site)
# one column per variable instead of one row
head(pred2DF(pred, format = "wide")$site, 3)


Simulate a forest with a FINN model

Description

Simulates every site of env forward through its years, starting from the trees in init_cohort (or from bare ground), with the model's current parameters – usually after fit() has estimated them. Returns the simulated stand variables and demographic rates per site, year and species, and on request the individual cohorts. predict(model, ...) is the S3 method for the stats::predict generic; simulateForest() is the same function under a name that says what it does.

Usage

## S3 method for class 'finn_class'
predict(
  object,
  env,
  disturbance = NULL,
  patches = 100L,
  patch_size = NULL,
  init_cohort = NULL,
  device = c("cpu", "gpu"),
  return_cohorts = FALSE,
  debug = FALSE,
  recruits = c("simulated", "observed"),
  obs_recruits = NULL,
  ...
)

simulateForest(
  model,
  env = NULL,
  disturbance = NULL,
  patches = 100L,
  patch_size = NULL,
  init_cohort = NULL,
  device = c("cpu", "gpu"),
  return_cohorts = FALSE,
  debug = FALSE,
  recruits = c("simulated", "observed"),
  obs_recruits = NULL,
  bare_ground = FALSE,
  years = 500L,
  sites = NULL,
  ...
)

Arguments

object

(finn_class)
The model built by finn(), fitted with fit().

env

(data.frame)
The environment of every site and simulated year: one row per siteID and year, plus one column per predictor, as in fit(). Every row is one simulated step. See finn_data. Required, except in simulateForest() with bare_ground = TRUE: there NULL (default) takes the environment the model was fitted on, and a table given is the one the mean climate is taken from.

disturbance

(data.frame or NULL)
Optional disturbances: one row per siteID and year with the column intensity, the probability (0 to 1) that a patch of that site loses all its trees in that year. See finn_data.

patches

(integer(1))
Number of patches per site when the simulation starts from bare ground (init_cohort = NULL). Not given: the patch count the model was fitted with (model$patches), or 100 for a model fitted before 0.2.0 or never fitted. Ignored, with a warning when it differs, as soon as init_cohort is given: the patch count then comes from the initial cohorts.

patch_size

(numeric(1))
Area of one patch in ha. NULL (default) takes the patch size the model was fitted with (model$patch_size_ha), or 0.1 for a model that was never fitted. A value that differs from the fitted one gives a warning: every per-hectare quantity changes with it.

init_cohort

(CohortMat)
The trees every site starts with, from makeInitCohorts(). NULL (default) starts from bare ground with patches empty patches per site (a succession run): no stems, every tree comes from the regeneration process. See finn_data.

device

(character(1))
"cpu" or "gpu"; "cuda" is accepted as a synonym for "gpu". Only NVIDIA cards are supported.

return_cohorts

Whether the individual cohorts are returned in addition to the site-level output. Storing cohorts every timestep is expensive, so the default is FALSE (none). Use TRUE (or "all") for every timestep, "last" for the final timestep only, or an integer vector of timesteps to store just those. Recorded cohorts appear as ⁠$long$cohort⁠ / ⁠$wide$cohort⁠.

debug

(logical(1))
If TRUE, the state of every cohort at every step is stored, with the intermediate quantities of the processes.

recruits

(character(1))
Where the recruits come from. "simulated" (the default) is the model's regeneration process. "observed" feeds the observed recruitment in obs_recruits instead, as fit(loss_recruit = "observed") does, to check a model calibrated that way on the intervals it was calibrated on. With observed recruitment the model is not an autonomous simulator: every simulated year must lie in an observed interval, and a bare-ground, succession or projection run beyond them is refused. See recruitment for the unit chain.

obs_recruits

(data.frame)
The observed recruitment for recruits = "observed", required there and refused otherwise: a table like the data of fit() with siteID, year, species, reg and period_length, rows for every species (0 where none recruited), the sites of env and years among those of env. Intervals map to simulated years exactly as in fit. An NA reg in an interval, a year in two intervals and a year in none are errors.

...

Advanced options forwarded to the internal simulator, chiefly batchsize (split the sites into batches of this many to cap memory for very large runs). The default processes all sites in one batch and is what almost all users want.

model

(finn_class)
The model built by finn(), fitted with fit().

bare_ground

(logical(1))
simulateForest() only: TRUE runs the model from an empty stand for years years under a constant climate, the mean of every predictor over the environment the model was fitted on (or over env when given); see Bare-ground runs in the details. init_cohort must be left out (an error otherwise) and disturbance is ignored. Default FALSE.

years

(integer(1))
simulateForest() with bare_ground = TRUE: the length of the run in years. Default 500.

sites

simulateForest() with bare_ground = TRUE: NULL (default) one run under the mean climate of all sites (siteID 1 in the result), or site ids for one run per site under that site's mean climate (the siteID of the fitted environment, or of env when given, kept in the result).

Details

The simulation uses the environment of every row of env in turn; the first row of a site drives the first step from init_cohort. env must be in natural units: the standardisation learned by fit() is applied automatically. A model that has not been fitted has no standardisation yet, so it must be given env on the scale its processes expect; fit it first (two epochs are enough for a trial).

Bare-ground runs. simulateForest(model, bare_ground = TRUE) builds the environment itself: the model starts from an empty stand and runs for years years under a constant climate, the mean of every predictor over the environment the model was fitted on, or with sites one run per site under that site's mean. It shows what the model does outside the observation window; evaluate() stores such a run on the model.

Value

A named list of class finn_simulation, which plot.finn_simulation() draws. ⁠$long$site⁠ (and ⁠$wide$site⁠) give the site-level results, averaged over the patches: columns siteID, year, species, variable (dbh, ba, trees, growth, mort, reg, r_mean_ha) and value; ⁠$wide$site⁠ has one column per variable instead. siteID is the id used in env; year is the simulation step, counted from 1 (the k-th year of a site's env is step k), whatever the values of env$year; the years of env are kept as the attribute "env_years", with which comparePlot() places observations. When return_cohorts is set, ⁠$long$cohort⁠ / ⁠$wide$cohort⁠ add the per-cohort state (dbh, trees, species, growth g, mortality m, ...) for the requested timesteps.

See Also

fit(), finn_data for the input tables, recruitment for the recruitment options (recruits, obs_recruits), plot.finn_simulation() to draw the result, comparePlot() and evaluate() to compare it with observations

Examples


library(data.table)
# three Oregon FIA sites: estimate the parameters (two epochs, for the
# example), then simulate the sites over the years of `env` from the
# observed stands
sites <- 1:3
Nsp   <- max(fia_obs_dt$species)
init  <- makeInitCohorts(fia_init_trees[siteID %in% sites], Nspecies = Nsp)
FINN.seed(1)
m <- finn(N_species = Nsp, recruits_dbh = 12.9,
          growth_process       = createProcess(~ temp + prec, growth),
          mortality_process    = createProcess(~ temp + prec, mortality),
          regeneration_process = createProcess(~ temp + prec, regeneration_capped))
fit(m, data = fia_obs_dt[siteID %in% sites], env = fia_env_dt[siteID %in% sites],
    init_cohort = init, epochs = 2L, patches = 4, patch_size = 0.06,
    plot_progress = FALSE)

sim <- predict(m, env = fia_env_dt[siteID %in% sites], init_cohort = init,
               return_cohorts = "last")
head(sim$long$site)

# the cohorts of the final timestep, kept because of `return_cohorts`
head(sim$long$cohort)

# a 50-year succession from bare ground, with the climate of year 1 repeated
succession <- fia_env_dt[siteID %in% sites & year == 1][rep(1:3, each = 50)]
succession[, year := rep(1:50, times = 3)]
sim50 <- simulateForest(m, env = succession, patches = 4)
sim50$long$site[variable == "ba", .(ba = sum(value)), by = .(siteID, year)][year %in% c(10, 50)]

# the same kind of run in one call: from an empty stand under the mean
# climate of the fitted environment, held constant
bare <- simulateForest(m, bare_ground = TRUE, years = 30)
plot(bare)


Predict growth and mortality for individual observed trees

Description

Predict growth and mortality for individual observed trees

Usage

predictTrees(
  model,
  tree_data,
  env,
  patches = 100L,
  patch_size = NULL,
  device = c("cpu", "gpu")
)

Arguments

model

(finn_class)
A (fitted) model.

tree_data

(data.table|data.frame)
Observed trees: siteID, year, patchID, species, dbh (at the interval start) and period_length (the interval, in timesteps).

env

(data.table|data.frame)
Environment, as for fit.

patches

(integer(1))
Not used: the patch dimension of the observed-tree tensors is the number of distinct patchIDs in tree_data (it used to be patches, and the extra patches were empty). Kept so existing calls run unchanged.

patch_size

(numeric(1))
Area of one patch in ha. Defaults to the one the model was last fitted or simulated with (model$patch_size_ha); pass a value only to override it. A model that was never fitted or simulated has none, so give it here. The value is stored on the model.

device

(character(1))
"cpu" or "gpu"; "cuda" is accepted as a synonym for "gpu".

Details

The tree-level counterpart of predict.finn_class. Where predict() simulates a stand forward and reports site-level states, this evaluates the growth and mortality kernels on trees you observed: light is computed from the observed stand, the kernels run on those trees at their observed diameters, and the annual rates are accumulated over each site's remeasurement interval — growth as the per-year rate of the compounded annual rates (the geometric mean of 1 + g, as makeObsData() derives the observed rate), mortality as the complement of the product of annual survivals.

It is the same code path fit(..., loss_aggregation = c(growth = "tree", mortality = "tree")) scores, so a validation report cannot drift from the objective it is validating.

Value

One row per row of tree_data, in the same order (.row records the original position), with growth_pred (the relative growth rate per year over the interval, compounded as described above) and mort_pred (probability of dying during the interval). Bind these onto tree_data directly rather than joining on siteID/year/patchID, which would be many-to-many.

See Also

predict.finn_class() / simulateForest() for the simulated stand, finn_loss for the per-tree losses that share this code, fia_tree_dt for a table of observed trees with their fates

Examples


library(data.table)
# the growth and mortality kernels applied to the trees as observed, so the
# error of the two functions alone, with no simulated stand in between
sites <- 1:3
Nsp   <- max(fia_obs_dt$species)
init  <- makeInitCohorts(fia_init_trees[siteID %in% sites], Nspecies = Nsp)
FINN.seed(1)
m <- finn(
  N_species            = Nsp, recruits_dbh = 12.9,
  growth_process       = createProcess(~ temp + prec, FINN::growth),
  mortality_process    = createProcess(~ temp + prec, FINN::mortality),
  regeneration_process = createProcess(~ temp + prec, FINN::regeneration))
fit(m, data = fia_obs_dt[siteID %in% sites], env = fia_env_dt[siteID %in% sites],
    init_cohort = init, epochs = 2L, patches = 4, patch_size = 0.06,
    plot_progress = FALSE)

# `fia_init_trees` is a pure initial state, so name the census the trees are
# scored against and the interval, in timesteps (years), that reaches it
trees <- fia_init_trees[siteID %in% sites,
                        .(siteID, patchID, species, dbh, year = 10L,
                          period_length = 10)]
pred  <- predictTrees(m, tree_data = trees,
                      env = fia_env_dt[siteID %in% sites], patch_size = 0.06)
head(pred)

# the bundled tree table carries the observed fates, so prediction and
# observation can be compared tree by tree: here the predicted probability
# of dying within the interval for the trees that died and those that lived
obs_trees <- fia_tree_dt[siteID %in% sites]
p <- predictTrees(m, tree_data = obs_trees, env = fia_env_dt[siteID %in% sites],
                  patch_size = 0.06)
tapply(p$mort_pred, obs_trees$died, mean)


Recruitment in FINN: the options and how to choose them

Description

Recruitment in FINN is set in several places: the regeneration process function and its arguments in createProcess() (or createHybrid()), two arguments of finn(), and the likelihood and recruitment mode of fit(), predict.finn_class() and simulateForest(). This page says what each option does, how they act together, and which combination to use for which purpose. The individual help pages carry the full argument descriptions.

One simulated year of recruitment runs in three steps. The regeneration process returns an EXPECTED recruitment per hectare for every site, patch and species. This rate is turned into a whole number of recruits per patch, which enter the stand as new cohorts at finn(recruits_dbh = ). During fit() the expected rate (not the drawn recruits), summed over an observation interval, is compared with the observed reg by the regeneration likelihood.

The recruitment process

The process is the func of the regeneration process passed to finn(regeneration_process = ). All mechanistic variants share the same core: a light response gated by the species parameter parReg, times the environmental response exp(env), plus the additive floor createProcess(reg_floor = ) of the regeneration process (default 1e-3 stems per ha and year).

A regeneration process built with createHybrid() replaces the whole equation by a network. In 0.2.0 it has no Beverton-Holt cap: createHybrid() accepts cap, prior and prior_lambda, but the network does not use them.

From expected recruitment to recruits

The expected rate per ha times patch_size (in ha) is the expected number of recruits per patch. createProcess(sample_regeneration = ) decides how it becomes a whole number:

The recruit dispersion theta

par_theta_recruits is the negative-binomial size theta, one value per species. It sets the variance of the recruit draw, mu + mu^2 / theta, and the width of the negative-binomial regeneration likelihood. Three arguments of createProcess() (and createHybrid()) control it:

With the default fit(rb_gradient = TRUE), theta is set only by the regeneration likelihood. On sparse, zero-heavy recruitment data the likelihood optimum of theta is very small: a small theta widens the likelihood and so lowers the loss without improving the predicted mean, and the same small theta makes the simulated draws bursty. A free theta can therefore run away.

What the floor does: it keeps the fit stable, and in a fit run to convergence it costs nothing we could resolve. In one converged pair of fits on the German national forest inventory (2000 epochs, about 126 000 optimizer steps), the model with the floor predicted the recruitment level on a spatially blocked holdout at 1.06 times the observed and the one with a fixed theta of 1 (optimizeTheta = FALSE) at 1.04; their recruitment likelihoods were within 0.003 of each other (0.897 and 0.894 relative to an intercept-only null), and they agreed on basal area, stem numbers, growth and the mortality AUC to three decimals. Early in a fit the two settings differ: after 50 of those 2000 epochs (3 150 optimizer steps on that inventory) a floored theta still put the level about 12 times too high, a fixed theta 2 to 3 times, and a free theta had run away by four orders of magnitude. Count the budget in optimizer steps, not epochs: on a small data set 50 epochs can be 50 steps. So read the recruitment level only once the parameters have settled (⁠$param_history⁠), whichever setting you use; for short fits, a fixed theta gets the level right sooner.

The likelihood and the observation operator

fit(loss_family = c(regeneration = )) chooses the regeneration likelihood. "nbinom" (default) uses theta as above. "poisson" has no dispersion parameter and so cannot collapse; theta then only shapes the recruit draw.

finn(recruit_obs_weight = w) is an observation operator: it maps the predicted and the observed recruitment per ha alike into the count space of the sampling design before they are compared, so that the likelihood sees the counts that were actually tallied. For an angle-count inventory w = g(recruits_dbh) / BAF. For a fixed-radius small-tree plot that counts the stems in a diameter band below the recruitment threshold,

⁠w = plot area (ha) x residence time in the band (years) / observation period (years)⁠,

where the residence time is the band width divided by the diameter growth of the stems in it. One tallied stem then stands for 1 / w recruits per ha over the observation period. The residence time is an assumption and should be estimated from the data where possible: w scales every absolute recruitment number the fit returns, though not the ranking between model configurations.

In 0.2.0 recruit_obs_weight is applied only under "nbinom". With loss_family["regeneration"] = "poisson" (or "mse", "gaussian") the term scores the per-ha values as they are and recruit_obs_weight has no effect, without a warning; the Poisson variance then is that of a per-ha value, not of the tallied count. The Poisson term adds fit(trees_offset = ) (default 0.01) to the prediction.

Feeding observed recruitment

fit(loss_recruit = "observed") drives the simulated stand with the observed recruitment instead of the regeneration process. The observed reg divided by period_length is the expected recruitment per ha and year in every year of that interval; times patch_size it is drawn per patch by the recruit sampler, as above. Growth, mortality and competition run and are trained as usual. The regeneration term is weighted 0 and every regeneration parameter (species parameters, environment response, cap, theta, custom parameters) is frozen for that call. predict() and simulateForest() take recruits = "observed" and the table obs_recruits to simulate the same way. With observed recruitment the model is not an autonomous simulator: every simulated year must lie in an observed interval, and bare-ground, succession or projection runs are refused.

The intended use is a staged calibration when the inventory samples small trees too sparsely to calibrate recruitment jointly with the rest. First fit the demography (growth, mortality, competition) with fit(loss_recruit = "observed"); then fit the regeneration process on its own, with the other processes frozen (optimizeSpecies/optimizeEnv = FALSE, or through loss_weights).

One caveat: the fed per-site count is a noisy estimate, and it is re-sampled as if it were the mean. The observation noise of a sparse small-tree count therefore enters the simulated stand. On the German national forest inventory one tallied small tree stands for about 1 600 stems per ha per decade, and the fed counts carry a variance comparable to that of the whole stem-count column, which costs accuracy in the simulated stem counts.

Choosing

See Also

createProcess(), createHybrid(), finn(), fit(), simulateForest(), regeneration(), regeneration_capped(), regeneration_adult(), regeneration_adult_effect()

Examples


library(data.table)
# three sites of the bundled Oregon FIA sample and two epochs per fit, to
# show the options; a real calibration uses all sites and many epochs
sites <- 1:3
Nsp   <- max(fia_obs_dt$species)
obs   <- fia_obs_dt[siteID %in% sites]
env   <- fia_env_dt[siteID %in% sites]
init  <- makeInitCohorts(fia_init_trees[siteID %in% sites], Nspecies = Nsp)

# the default regeneration process: a cap shared by all species with its
# prior from the data, and a trained recruit dispersion with a floor of 0.5
FINN.seed(1)
m <- finn(N_species = Nsp, recruits_dbh = 12.9,
          growth_process       = createProcess(~ temp + prec, growth),
          mortality_process    = createProcess(~ temp + prec, mortality),
          regeneration_process = createProcess(~ temp + prec, regeneration_capped))
fit(m, data = obs, env = env, init_cohort = init, epochs = 2L,
    patch_size = 0.06, plot_progress = FALSE)
exp(as.numeric(m$reg_logK))         # the cap, recruits per ha and year
max(obs$reg / obs$period_length)    # its prior: the largest observed rate

# a fixed recruit dispersion and no recruitment floor
m_fixed <- finn(N_species = Nsp, recruits_dbh = 12.9,
                growth_process       = createProcess(~ temp + prec, growth),
                mortality_process    = createProcess(~ temp + prec, mortality),
                regeneration_process = createProcess(~ temp + prec, regeneration_capped,
                                                     optimizeTheta = FALSE,
                                                     dispersion_parameter = 1,
                                                     reg_floor = 0))

# the first stage of a staged calibration: the observed recruits drive the
# stand, the regeneration process is frozen and its loss term is dropped
fit(m_fixed, data = obs, env = env, init_cohort = init, epochs = 2L,
    patch_size = 0.06, plot_progress = FALSE, loss_recruit = "observed")
do.call(rbind, m_fixed$history)     # the regeneration column (6) is 0


Regeneration without a recruitment cap

Description

FINN's uncapped mechanistic regeneration process: the mean number of recruits a species contributes to one patch in one simulation step, in stems per hectare, mean = regP * exp(pred) + reg_floor. regP is the patch's light response, a sigmoid in the available light centred on the species' light requirement parReg and shifted to be 0 without light, so a shade-tolerant species (small parReg) recruits under a closed canopy and a light-demanding one does not. exp(pred) is the species' environmental response, and reg_floor (createProcess(), default 1e-3) is an additive floor that keeps a species from being lost for good.

The mean is unbounded in pred, so a steep climate coefficient can turn a favourable site into a recruitment burst of hundreds of stems in one year. regeneration_capped() adds a Beverton-Holt cap and is the default regeneration process since 0.2.0; this function is the uncapped process of Pichler & Käber (2026) and stays available as the opt-in.

Usage

regeneration(species, parReg, pred, light, debug = FALSE)

Arguments

species

torch.Tensor species information.

parReg

torch.Tensor Regeneration parameters. 0 <= parReg <= 1 This parameter denotes the fraction of light needed for a species to regenerate. In general low values for high regeneration and high values for low regeneration.

pred

torch.Tensor Prediction values.

light

torch.Tensor Available light variable for calculation.

debug

logical If TRUE, return the intermediate components as a list. Defaults to FALSE.

Value

torch.Tensor Mean recruitment per species, stems ha^-1 step^-1, shaped ⁠[sites, patches, species]⁠ – a per-HECTARE rate, not a per-patch count: forward() multiplies it by patch_size_ha itself before the recruit draw. It includes the additive reg_floor and is unbounded above.

See Also

regeneration_capped() (the default regeneration process since 0.2.0), regeneration_adult(), recruitment for the recruitment options and how to combine them

Examples


# the uncapped regeneration of the paper instead of the default
# regeneration_capped(); recruits enter at 1 cm (recruits_dbh)
m <- finn(N_species = 2, recruits_dbh = 1,
          regeneration_process = createProcess(~ 1 + temp, regeneration))

# a 30-year simulation from bare ground; an unfitted model uses `env` as
# given (no scaling constants yet), so the predictor is passed standardised
env <- data.frame(siteID = 1L, year = 1:30, temp = 0)
sim <- simulateForest(m, env = env, patches = 5, patch_size = 0.1)
tail(sim$wide$site)


Regeneration limited by conspecific adult density

Description

A mechanistic extension of regeneration_capped in which recruitment needs a seed source: the mean recruitment of a species scales with the density of its own ADULTS on the site, the stems whose diameter exceeds an adult threshold x.

Usage

regeneration_adult(
  species,
  parReg,
  pred,
  light,
  dbh = NULL,
  trees = NULL,
  debug = FALSE
)

Arguments

species

torch.Tensor species information.

parReg

torch.Tensor Regeneration parameters. 0 <= parReg <= 1 This parameter denotes the fraction of light needed for a species to regenerate. In general low values for high regeneration and high values for low regeneration.

pred

torch.Tensor Prediction values.

light

torch.Tensor Available light variable for calculation.

dbh

torch.Tensor cohort diameters, ⁠[sites, patches, cohorts]⁠.

trees

torch.Tensor stems per cohort, ⁠[sites, patches, cohorts]⁠.

debug

logical If TRUE, return the intermediate components as a list. Defaults to FALSE.

Details

For species k on a site,

A_k = \frac{1}{P a} \sum_{\mathrm{cohorts\ of\ } k} n \, \sigma\!\left(\frac{d - x_k}{\tau}\right)

is the conspecific adult density (stems ha^-1), pooled over the P patches of the site (area a each) because seeds disperse beyond one patch. The soft threshold (tau = 2 dbh units) keeps x_k differentiable; a hard d > x would give it no gradient. The seed-limitation term

f(A_k) = \frac{A_k}{A_k + A_{1/2,k}}

is 0 without adults and approaches 1 once adults are abundant, so the mean recruitment

m = r(\mathrm{light}) \, e^{\mathrm{env}} f(A) + \mathrm{reg\_floor}

falls to the floor (read it as immigration from outside the site) where the species has no adult, and rises to the light- and environment-driven potential of regeneration where adults are many. The result is capped with the same Beverton-Holt term as regeneration_capped, ⁠K m / (K + m)⁠.

The cap reg_logK is created by finn() as for regeneration_capped, with its resolution from createProcess(cap = ) and its prior from prior/prior_lambda, so it need not be declared. A reg_logK declared in custom_parameters (as in the example) is kept and sets the resolution by its length, but its start value is replaced by the resolved prior at the first fit(). Declare the two adult parameters with createProcess(custom_parameters = ); a length-1 init gives one shared value and a length-N_species init one value per species:

forward() passes dbh and trees to a regeneration function only when its signature has them, so the other regeneration functions are unaffected. Called without dbh/trees (as the ALE code in xAI.R does), the function returns recruitment with the seed source present (f = 1).

Value

torch.Tensor mean recruitment, stems ha^-1 step^-1, ⁠[sites, patches, species]⁠. With debug = TRUE, a list that also holds adults (A, stems ha^-1, ⁠[sites, 1, species]⁠) and seed (f(A)).

See Also

regeneration_capped, regeneration_adult_effect() (adult density as an effect, not a gate), createProcess(), recruitment for the recruitment options and how to combine them

Examples


library(data.table)
# three sites of the bundled Oregon FIA sample (?fia_obs_dt)
sites <- 1:3
Nsp   <- max(fia_obs_dt$species)
init  <- makeInitCohorts(fia_init_trees[siteID %in% sites], Nspecies = Nsp)

FINN.seed(1)
m <- finn(
  N_species = Nsp, recruits_dbh = 12.9,
  regeneration_process = createProcess(
    ~ temp + prec, FINN::regeneration_adult,
    custom_parameters = list(reg_logK       = rep(log(50), Nsp),
                             reg_adult_logx = rep(log(20), Nsp),   # adult from 20 cm
                             reg_adult_logA = rep(log(20), Nsp)),  # f = 0.5 at 20 adults/ha
    optimizeSpecies = TRUE, optimizeEnv = TRUE))
fit(m, data = fia_obs_dt[siteID %in% sites], env = fia_env_dt[siteID %in% sites],
    init_cohort = init, epochs = 2L, patches = 4, patch_size = 0.06, plot_progress = FALSE)
# the fitted cap, adult threshold (cm) and half-saturation adult density (per ha)
exp(as.numeric(m$reg_logK)); exp(as.numeric(m$reg_adult_logx)); exp(as.numeric(m$reg_adult_logA))


Regeneration with an effect of conspecific adult density

Description

A variant of regeneration_adult in which the density of conspecific adults is an EFFECT on recruitment rather than a gate: a species without adults on the site still recruits a share f0 of its potential, so bare ground can be colonised from an empty stand.

Usage

regeneration_adult_effect(
  species,
  parReg,
  pred,
  light,
  dbh = NULL,
  trees = NULL,
  debug = FALSE
)

Arguments

species

torch.Tensor species information.

parReg

torch.Tensor Regeneration parameters. 0 <= parReg <= 1 This parameter denotes the fraction of light needed for a species to regenerate. In general low values for high regeneration and high values for low regeneration.

pred

torch.Tensor Prediction values.

light

torch.Tensor Available light variable for calculation.

dbh

torch.Tensor cohort diameters, ⁠[sites, patches, cohorts]⁠.

trees

torch.Tensor stems per cohort, ⁠[sites, patches, cohorts]⁠.

debug

logical If TRUE, return the intermediate components as a list. Defaults to FALSE.

Details

The conspecific adult density A_k (stems ha^-1) is computed as in regeneration_adult: the stems of species k weighted by a soft adult threshold sigmoid((d - x_k) / tau) (tau = 2 dbh units), pooled over the patches of the site. The adult term is

f(A_k) = f_{0,k} + (1 - f_{0,k}) \frac{A_k}{A_k + A_{1/2,k}}

with f_0 = \mathrm{sigmoid}(\mathrm{reg\_adult\_logitf0}) \in (0, 1), and the mean recruitment is

m = r(\mathrm{light}) \, e^{\mathrm{env}} f(A) + \mathrm{reg\_floor},

capped by the Beverton-Holt term of regeneration_capped, ⁠K m / (K + m)⁠.

f0 is the share of the potential recruitment a species gets on a site without conspecific adults – seed rain from outside the site, advance regeneration. It rises to 1 as adults become abundant. f0 -> 1 means no adult effect (the process becomes regeneration_capped); f0 -> 0 recovers the gate of regeneration_adult, where a species without adults recruits only at reg_floor.

The soft threshold counts small stems partly: a 1-cm stem is about 1.5 % of an adult at x = 9.4 cm, so a low A_half gives a non-zero adult term even in a stand of seedlings.

The cap reg_logK is created by finn() as for regeneration_capped (resolution from createProcess(cap = ), prior from prior/prior_lambda), so it need not be declared. Declare the three adult parameters with createProcess(custom_parameters = ); a length-1 init gives one shared value and a length-N_species init one value per species:

As for regeneration_adult, forward() passes dbh and trees because the signature has them. Called without dbh/trees (as the ALE code in xAI.R does), the function returns recruitment with the seed source present (f = 1).

Value

torch.Tensor mean recruitment, stems ha^-1 step^-1, ⁠[sites, patches, species]⁠. With debug = TRUE, a list that also holds adults (A, stems ha^-1, ⁠[sites, 1, species]⁠), f0 and seed (f(A)).

See Also

regeneration_adult, regeneration_capped, createProcess(), recruitment for the recruitment options and how to combine them

Examples


library(data.table)
# three sites of the bundled Oregon FIA sample (?fia_obs_dt)
sites <- 1:3
Nsp   <- max(fia_obs_dt$species)
init  <- makeInitCohorts(fia_init_trees[siteID %in% sites], Nspecies = Nsp)

FINN.seed(1)
m <- finn(
  N_species = Nsp, recruits_dbh = 12.9,
  regeneration_process = createProcess(
    ~ temp + prec, FINN::regeneration_adult_effect,
    custom_parameters = list(reg_adult_logx    = rep(log(20), Nsp),   # adult from 20 cm
                             reg_adult_logA    = rep(log(20), Nsp),   # half effect at 20 adults/ha
                             reg_adult_logitf0 = qlogis(0.2)),        # 20 % without adults, shared
    optimizeSpecies = TRUE, optimizeEnv = TRUE))
fit(m, data = fia_obs_dt[siteID %in% sites], env = fia_env_dt[siteID %in% sites],
    init_cohort = init, epochs = 2L, patches = 4, patch_size = 0.06, plot_progress = FALSE)
# the fitted share of the potential recruitment without conspecific adults
plogis(as.numeric(m$reg_adult_logitf0))


Regeneration with a Beverton-Holt recruitment cap

Description

The default regeneration process since 0.2.0, and a drop-in alternative to the uncapped regeneration. It caps the otherwise unbounded mean recruitment with a Beverton-Holt density dependence, recruits = K * m / (K + m), where m is the mechanistic mean recruitment (identical to regeneration) and K is a fitted carrying capacity (stems ha^-1 step^-1). As m grows, recruitment saturates towards K. regeneration_saturation() is the same function under its older name, kept as a deprecated alias for one release.

Usage

regeneration_capped(species, parReg, pred, light, debug = FALSE)

regeneration_saturation(species, parReg, pred, light, debug = FALSE)

Arguments

species

torch.Tensor species information.

parReg

torch.Tensor Regeneration parameters. 0 <= parReg <= 1 This parameter denotes the fraction of light needed for a species to regenerate. In general low values for high regeneration and high values for low regeneration.

pred

torch.Tensor Prediction values.

light

torch.Tensor Available light variable for calculation.

debug

logical If TRUE, return the intermediate components as a list. Defaults to FALSE.

Details

The cap is the parameter reg_logK (K = exp(reg_logK)), which FINN creates itself – there is nothing to declare. createProcess(cap = ) decides its resolution: "all" (the default) gives one cap shared by every species, "species" one cap per species. Read the fitted value back with exp(as.numeric(m$reg_logK)).

Value

torch.Tensor Mean recruitment, stems ha^-1 step^-1, ⁠[sites, patches, species]⁠ – a per-HECTARE rate, not a per-patch count. forward() multiplies it by patch_size_ha itself before the recruit draw, and reg is scored on the per-hectare value.

The prior on the cap

A cap that only the data constrain runs to whatever the fitted window supports, which on a national inventory is far above anything observed. So the cap carries a prior, added to the objective as ⁠prior_lambda * (log K - log prior)^2⁠ per cap – the same form as the L2 pull of a staged calibration. It is added after the loss_weights = "auto" baseline scaling, so prior_lambda means the same thing on every dataset.

createProcess(prior = "max_obs_recruits"), the default, resolves the prior from the data at the start of fit(): the largest observed recruitment rate per timestep, max(reg / period_length). The division matters on any inventory with a remeasurement interval, because reg is the SUM over that interval while the cap bounds the mean of one timestep – taking the column as supplied would place the prior a factor period_length too high, and the cap would never bind. A number sets the prior directly, on that same per-timestep scale. prior_lambda = 0 switches the prior off and leaves the cap to the data alone. Scoring no recruitment at all is an error rather than a silent default, because nothing else in the objective constrains a cap.

The resolved value is also the cap's starting value, and it is resolved only on the FIRST fit() of a model: a second call continues from the trained cap instead of resetting it to the prior.

With cap = "species" the prior is hierarchical: each species' log cap is pulled towards the mean of all current log caps rather than towards a fixed value, so the prior penalises how far the species spread apart and leaves the overall level to the data. Every species still starts at the observed maximum.

See Also

regeneration, regeneration_adult(), regeneration_adult_effect(), createProcess(), recruitment for the recruitment options and how to combine them

Examples


library(data.table)
Nsp <- max(fia_obs_dt$species)
# the default: one cap for all species, prior from the data
m <- finn(N_species = Nsp, recruits_dbh = 12.9)

# one cap per species, a fixed prior (stems per ha and year), a stronger pull
m2 <- finn(N_species = Nsp, recruits_dbh = 12.9,
           regeneration_process = createProcess(~ temp + prec, regeneration_capped,
                                                cap = "species", prior = 500, prior_lambda = 1))

# the cap is created and resolved by fit(); read it back on the natural scale
sites <- 1:3
init  <- makeInitCohorts(fia_init_trees[siteID %in% sites], Nspecies = Nsp)
fit(m2, data = fia_obs_dt[siteID %in% sites], env = fia_env_dt[siteID %in% sites],
    init_cohort = init, epochs = 1L, patch_size = 0.06, plot_progress = FALSE)
exp(as.numeric(m2$reg_logK))   # one carrying capacity per species


Resolve site, patch, and year indices for FINN inputs

Description

Joins tree, environment, and observation tables; assigns integer indices for site, patch and year; standardizes species coding; and returns aligned data plus optional initial cohorts.

Usage

resolveSiteIDs(
  tree_dt,
  env_dt,
  obs_dt,
  createInitCohorts = TRUE,
  time_axis = c("annual", "census")
)

Arguments

tree_dt

data.table with tree-level data including siteName, patchName, year, species_name, dbh, status, living, and optional trees.

env_dt

data.table with environment data including siteName and year (calendar year; see Details for the years needed).

obs_dt

data.table with observations including siteName, patchName, year, species_name, and stand metrics (ba, dbh, trees, growth, mort, n_at_risk, n_died, reg, period_length), as returned by makeObsData.

createInitCohorts

logical. If TRUE, build FINN initial cohorts from the living trees of the first inventory (year == 0) on either time axis. Default TRUE.

time_axis

"annual" (default) or "census". "census" is the axis of FINN 0.1.0: year is the index of the inventory (0, 1, 2, ...), one simulation step is one census interval (period_length = 1), env_dt keeps the inventory years, and the observations of the first inventory stay in obs_dt. Use it with makeObsData(rates = "interval"). Unlike 0.1.0, which built the initial cohorts from the second inventory, the census axis now starts from the first one, so 0.1.0 results are not reproduced exactly.

Details

With time_axis = "annual" (the default) one simulation step is one year: year becomes the number of years since the first inventory of the site's patch (0 at the first inventory, e.g. 10 and 20 at the next two), the first inventory is the initial state (the initial cohorts, not an observation), the observations carry period_length in years, and env_dt is returned with one row per site and year 1..Tmax, Tmax being the longest time from a first to a last inventory. The environment row of year k drives the simulated year that ends at year k, so an inventory k years after the first is compared with the stand after k simulated years. env_dt therefore needs one row per site and calendar year from the year after the site's first inventory to Tmax years after it; a climate that does not change is repeated for every year.

Value

A list with:

The list can be stored with saveRDS() and read back with readRDS(): initCohorts keeps a plain R copy of its arrays and rebuilds its torch tensors, which saveRDS() cannot store, when fit(), simulateForest() or predict.finn_class() use it (or by x$initCohorts$restore(), see CohortMat). Cohorts saved with FINN before 0.2.0 carry no such copy; rebuild them from the table with x$initCohorts <- makeInitCohorts(x$initCohort_dt, Nspecies = nrow(x$species_dt)).

See Also

makeObsData for the step before, makeInitCohorts for the initial cohorts on their own, fit and finn_data for where the tables go

Examples

library(data.table)
# eight Oregon FIA plots, three inventories each; see the data-preparation vignette
tree_dt <- fread(system.file("extdata", "example_tree_dt.csv", package = "FINN"))
env_dt  <- fread(system.file("extdata", "example_env_dt.csv",  package = "FINN"))
obs <- makeObsData(tree_dt[complete == TRUE], plotsize = 0.06, aggregate_by_site = FALSE,
                   fix_period_length = 10, NspeciesQuantile = 0.98)

# Names become integer ids shared by every table, calendar years become years
# since the first inventory: 0 (the initial state), 10 and 20. Pass the tree
# list makeObsData() returned: it carries the same species lumping as obs_dt.
# createInitCohorts = FALSE leaves out the starting cohorts, which need torch.
inputs <- resolveSiteIDs(tree_dt = obs$tree_dt, obs_dt = obs$obs_dt, env_dt = env_dt,
                         createInitCohorts = FALSE)
inputs$species_dt
head(inputs$obs_dt)      # per site, year and species: what fit(data = ) takes
range(inputs$env_dt$year) # one row per site and simulated year: what fit(env = ) takes
head(inputs$siteID_dt)   # the map back to the inventory's own names

# with torch, the same call also builds the starting cohorts (a CohortMat)
inputs <- resolveSiteIDs(tree_dt = obs$tree_dt, obs_dt = obs$obs_dt, env_dt = env_dt)
inputs$initCohorts$dims  # sites, patches, cohorts


Negative-binomial recruit draw without the recruitment floor

Description

The default regeneration sampler since 0.2.0, selected with createProcess(regeneration_sampler = "refined"); rnbinom_torch() (regeneration_sampler = "gaussian") reproduces results published before 0.2.0. Three differences: the probability clamp is 1e-10 instead of 1e-4, the Gamma draw is clamped at that same eps instead of taking +0.001 and an absolute value, and the draw goes through sample_poisson_refined() (an exact torch_poisson below lambda = 2, the Gaussian approximation above) instead of sample_poisson_gaussian().

Usage

rnbinom_torch_refined(pred, theta)

Arguments

pred

torch.Tensor Expected recruits per patch.

theta

torch.Tensor Negative-binomial dispersion.

Details

The +0.001 offset and the 1e-4 clamp exist for the Gaussian branch: they keep the Gamma draw off zero and stop log(0) sending a NaN gradient back through distr_gamma()$rsample(). Neither hazard applies to torch_poisson, and together they impose a recruitment FLOOR of 0.0011 per cell-year, which at a FINN patch of 0.0168 ha is 0.066 recruits ha^-1 yr^-1 per species – over a pool of a hundred-odd species, as large as the whole ingrowth a temperate inventory records. sample_poisson_gaussian() (lambda + eps*sqrt(lambda), rounded straight-through by the forward pass) rounds the floor away but also rounds the signal away: at a FINN patch of 0.0168 ha the per-cell mean is 0.001-0.008, and over 2e6 draws the delivered fraction of the calibrated mean was 0.000-0.048 at theta = 1.

One bias is left and is not repaired in 0.2.0: above lambda = 2 the draw is the Gaussian approximation FLOORED, so it delivers about half a recruit per draw too few (measured over 1e6 draws: -0.43 at lambda = 2.5, -0.50 from lambda = 20, against about 0 with rounding). It bites only where a cell's mean recruitment is above two, which the per-patch means above are not. Rounding instead of flooring is planned for 0.2.1; it changes results, so it is not in this release.

For the measured consequence of both repairs on the simulated stand, and why the holdout cannot separate them, see binomial_from_poisson().

Value

A torch tensor of recruit counts, of the shape of pred.

See Also

recruitment, createProcess() (regeneration_sampler, theta_floor)

Examples


FINN.seed(1)
# sparse recruitment: an expected 0.05 recruits per patch and year
mu    <- torch::torch_full(c(100000), 0.05)
theta <- torch::torch_tensor(1)
r <- as.numeric(rnbinom_torch_refined(mu, theta))
mean(r)    # the draw delivers the expected count ...
table(r)   # ... as whole recruits, most patches getting none


Generate Cohorts Using Weibull Distribution

Description

This function generates cohort data for tree populations using the Weibull distribution based on specified tree counts, diameter at breast height (DBH) shape, and scale parameters.

Usage

rweibull_cohorts(
  trees = NULL,
  dbh_shape = NULL,
  dbh_scale = NULL,
  dbh_class_range = 1,
  siteID = 1,
  patchID = 1,
  species = 1
)

Arguments

trees

Integer vector specifying the number of trees for each cohort. If a single integer is provided, it will be replicated for each draw.

dbh_shape

Numeric vector specifying the shape parameters of the Weibull distribution for DBH for each cohort. If a single numeric value is provided, it will be replicated for each draw.

dbh_scale

Numeric vector specifying the scale parameters of the Weibull distribution for DBH for each cohort. If a single numeric value is provided, it will be replicated for each draw.

dbh_class_range

Numeric value specifying the range of DBH classes. Default is 1.

siteID

Integer vector specifying the site ID for each cohort. If a single integer is provided, it will be replicated for each draw. Default is 1.

patchID

Integer vector specifying the patch ID for each cohort. If a single integer is provided, it will be replicated for each draw. Default is 1.

species

Integer vector specifying the species ID for each cohort. If a single integer is provided, it will be replicated for each draw. Default is 1.

Details

The function generates cohort data by drawing samples from the Weibull distribution for each cohort based on the specified shape and scale parameters. The resulting DBH values are binned into classes of width dbh_class_range, and each non-empty class becomes one cohort.

Value

A data frame with one row per non-empty diameter class and the columns siteID, patchID, cohortID (numbered over the whole table), species, dbh (cm) and trees, the format of CohortMat(obs_df = ).

See Also

CohortMat to turn the table into an initial state

Examples

set.seed(1)
# a stand of two species on one patch: 300 saplings of species 3 around
# 1 cm and 10 large trees of species 4 around 50 cm, in 0.1 cm classes
obs_df <- rweibull_cohorts(
  trees = c(300, 10),
  dbh_shape = c(3, 3),
  dbh_scale = c(1, 50),
  dbh_class_range = 0.1,
  siteID = c(1, 1),
  patchID = c(1, 1),
  species = c(3, 4)
)
head(obs_df)
# trees and cohorts per species
aggregate(cbind(trees, cohorts = 1) ~ species, data = obs_df, FUN = sum)

Summarise a fitted FINN model

Description

Collects what is needed to judge a fitted model, in this order:

  1. Skill: per response, R2 (1 - SSE/SST) and the correlation (Pearson r) of observed and simulated first, then RMSE, the bias, the ratio of the mean prediction to the mean observation (is the magnitude right?; for mortality weighted by the trees at risk, where the observations carry n_at_risk and n_died) and n; for mortality also the tree-level AUC and the ratio of predicted to observed deaths. On the training data and, when evaluate() or the argument holdout of fit() stored one, on the holdout. The observations are compared with the simulation aggregated the way fit() scores it (see comparePlot()). Without a stored evaluation, summary() runs evaluate() on the training data first (one simulation) and stores it on the model.

  2. Convergence: by how many percent each loss term changed over the last epochs_back epochs (the mean of the last epochs_back epochs against the mean of the epochs_back before), as a table with one sentence on the largest change; and how much the parameters moved over the last epochs_back epochs, as a table with one row per process (growth, mortality, regeneration, competition) and part (its species parameters, where they are fitted (optimizeSpecies = TRUE in createProcess()), its environmental response, i.e. the network or the linear climate effects, and for regeneration the recruit dispersion and the cap), naming the parameter that moved most. The change is the size of the step the values took as a percentage of their size, ⁠100 * |values now - values then| / |values then|⁠, over all species of a parameter (on the scale it acts on, e.g. "mortality: growth") or all weights of a network layer; 1 % means the values moved by about a hundredth of their size. fit() keeps the parameters of the last 51 epochs for this, so epochs_back can be at most 50; for a model fitted before this version the parameter snapshots of the fit (model$param_history, every checkpoints epochs) are used instead; they carry no epoch, so the epochs between them are estimated from the length of the loss history and their number (exact for one call of fit() whose epochs is a multiple of checkpoints). Below the explanation, one sentence names the species parameter that moved most and the largest change overall. A fit has settled when both are small; network weights can keep moving while the loss stays flat.

  3. Bare ground, when evaluate() stored a bare-ground run: per site, the total basal area and the leading species with its share, as the mean over the last tenth of the run.

  4. Environmental importance and average conditional effects, per process and species, from the model's conditional effects (computed once and cached, see ALE()). Where they cannot be computed for a model, a warning says why and the other sections are still returned.

print() shows it; print(s, epochs_back = 10) redoes the convergence check over another window without recomputing anything. plot.finn_class() draws the fitted parameters themselves.

Usage

## S3 method for class 'finn_class'
summary(
  object,
  env = NULL,
  init_cohort = NULL,
  importance = c("ale", "permutation"),
  env_autoscale = TRUE,
  sim_seed = 42L,
  nperm = 20L,
  scale = TRUE,
  epochs_back = 50L,
  ...,
  species_names = NULL,
  parameter_names = NULL
)

## S3 method for class 'summary.finn_class'
print(x, epochs_back = x$epochs_back, species = FALSE, ...)

Arguments

object

(finn_class)
fitted model.

env, init_cohort

(NULL or data)
interpretation data for the importance and the conditional effects; NULL uses the cached training data (see ALE()).

importance

(character(1))
"ale" (default) = analytical ALE-variance importance (cheap, from the cache); "permutation" = re-simulating permutation importance (see feature_importance()), cached on the model under the same input key.

env_autoscale

(logical(1))
see ALE().

sim_seed

(integer(1))
seed for the simulation (see ALE()).

nperm

(integer(1))
replicates for importance = "permutation".

scale

(logical(1))
for importance = "ale", divide Var(ALE) by the process x species rate variance so the importances are dimensionless and comparable across processes and species (Sobol-style). Default TRUE.

epochs_back

(integer(1))
the window of the convergence check, in epochs. Default 50.

...

summary(): passed to feature_importance() with importance = "permutation" (and from there to predict()). print(): unused.

species_names, parameter_names

Names of the species and of the parameters of a process function of one's own, as for plot.finn_class(); NULL (default): the species names the model keeps from fit() and the documented parameter names of FINN's own process functions.

x

A summary.finn_class object.

species

(logical(1))
also print the skill per species. Default FALSE.

Value

summary(): an object of class summary.finn_class, a list with skill (per set, overall), skill_species (per set and species), convergence (the loss history, the recent parameters, the parameter snapshots with their estimated spacing, and the bounds and names of the species parameters), bare_ground, importance, average_conditional_effects, method (the importance option), importance_label, species_names, environment_error (NULL, or why item 4 could not be computed) and epochs_back. print(): x, invisibly.

See Also

evaluate(), comparePlot(), plot.finn_class(), ALE(), averageConditionalEffects(), feature_importance()

Examples


library(data.table)
# a small model fitted on two Oregon FIA sites (see ?fit)
sites <- 1:2
Nsp   <- max(fia_obs_dt$species)
init  <- makeInitCohorts(fia_init_trees[siteID %in% sites], Nspecies = Nsp)
FINN.seed(1)
m <- finn(N_species = Nsp, recruits_dbh = 12.9,
          growth_process       = createProcess(~ temp + prec, growth),
          mortality_process    = createProcess(~ temp + prec, mortality),
          regeneration_process = createProcess(~ temp + prec, regeneration_capped))
fit(m, data = fia_obs_dt[siteID %in% sites], env = fia_env_dt[siteID %in% sites],
    init_cohort = init, epochs = 3L, patches = 4, patch_size = 0.06,
    plot_progress = FALSE)

s <- summary(m)
s
# the convergence check over the last two epochs instead
print(s, epochs_back = 2)
# the tables are also returned
s$skill$train