| 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
|
| 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:
-
Prepare the data.
makeObsData(),resolveSiteIDs()andmakeInitCohorts()turn a raw tree list into FINN's input tables: the observations, the environment of every year and the initial cohorts (finn_data). -
Build the model.
finn()assembles one process per component (growth, mortality, regeneration, competition), each built withcreateProcess()(mechanistic, with a linear or neural-network response to the environment) orcreateHybrid()(a neural network). -
Fit it.
fit()estimates all processes jointly against all observed responses; its argumentholdoutevaluates the model right after the fit. -
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. -
Look inside.
plot.finn_class()draws the fitted parameters,ALE()the effects of the environment, also of a neural network. -
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:
Maximilian Pichler maximilian.pichler@biologie.uni-regensburg.de (ORCID)
See Also
Useful links:
Report bugs at https://github.com/FINNverse/FINN/issues
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 |
( |
env |
( |
init_cohort |
( |
env_autoscale |
( |
sim_seed |
( |
plot |
( |
process |
( |
scale |
( |
... |
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.
Sensitivity of basal area for different combinations of dbh, number of trees to patch size.
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 |
trees |
A tensor or array representing the number of trees. Defaults to |
species |
A tensor or array representing the species. Defaults to |
dims |
A numeric vector representing the dimensions of the arrays (sites, patches, cohorts). Defaults to |
sp |
An integer representing the number of species. Defaults to |
device |
A character string specifying the device to use ('cpu' or 'cuda'). Defaults to |
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
dbhA tensor representing the diameter at breast height for each cohort.
treesA tensor representing the number of trees in each cohort.
speciesA tensor representing the species of each cohort.
dimsA vector representing the dimensions of the arrays (sites, patches, cohorts).
spAn integer representing the number of species.
dbh_rA numeric array representing the diameter at breast height in R array format.
trees_rA numeric array representing the number of trees in R array format.
species_rAn integer array representing the species in R array format.
device_rA character string specifying the device in R format ('cpu' or 'cuda').
obsDF2arraysTransforms data.table into array
site_idsThe user
siteIDs in the order of the site dimension when the cohorts were built fromobs_df(the lookup table from array position to user id);NULLwhen built from arrays, where the site dimension is1: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 |
scaling |
The |
Value
env with the scaled predictor columns, as a data.table.
See Also
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 |
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
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 |
( |
env |
( |
init_cohort |
( |
env_autoscale |
( |
sim_seed |
( |
env_only |
( |
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
|
p |
torch.Tensor Success (death) probability per element, of the shape
of |
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 |
sample_size |
integer Number of draws; only the default |
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 |
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 |
obs |
Observations as |
type |
|
species |
|
response |
Responses to draw, any of |
sites |
Site ids to include; |
tree_data |
|
n_species |
Number of species in the recruitment panel. Default |
species_names |
Species names for the labels: a character vector in
species order, a vector named by species number, or a table with
|
... |
Unused. |
x |
A |
Details
-
type = "scatter"(default): observed against simulated fordbh,ba,treesandgrowth, with the 1:1 line and R2 (1 - SSE/SST) in each panel; for mortality the ROC curve of the interval death probability with its AUC (each tree at risk is one case,n_diedpositives andn_at_risk - n_diednegatives; without those two columns inobs, a scatter of the annual rates); for recruitment, whose site-level values are too noisy for a correlation, the ratio of simulated to observed recruitment summed over all sites, per species (then_speciesspecies with most observed recruitment). Withtree_data, the dbh panel shows the largest diameter instead of the mean: per site, census and species, or, all species pooled, per site and census (the maximum over the species), which is robust against a few large or many small trees. The simulation must have recorded its cohorts at the census steps (simulateForest(..., return_cohorts = <steps>), a step being the position of the census year among the years ofenv;evaluate()does this itself). -
type = "heatmap": the skill per species at a glance, every species a row (by name): R2 of every response and the AUC of mortality on the left, the ratio of simulated to observed on the right (log scale, white at 1, so over- and underestimation show as colours). -
type = "timeseries": the simulated trajectory over the years as a line and the observations as points at their census years, averaged over the selected sites. With all species pooled,baandtreesare the stand totals and the other responses the mean over the species.
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, |
species |
torch.Tensor (int64) species index for each cohort, |
trees |
torch.Tensor Number of trees in each cohort, |
parComp |
torch.Tensor Competition parameters, one row per species and two columns: the
height parameter of |
h |
(Optional) Defaults to NULL: the light each cohort receives at its own height. Any
non- |
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 |
logical Use the continuous competition formulation. Defaults to FALSE. |
light_mask |
logical Take the height quantiles over the live cohorts only
( |
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 |
spec |
how to scale each predictor. One of:
|
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 |
( |
env |
( |
init_cohort |
( |
env_autoscale |
( |
sim_seed |
( |
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 |
( |
optimize |
( |
dispersion_parameter |
( |
NN |
( |
dropout |
( |
encoder_layers |
( |
|
( | |
sample_regeneration |
( |
transformer |
( |
emb_dim |
( |
dim_feedforward |
( |
mortality_draw |
( |
regeneration_sampler |
( |
cap, prior, prior_lambda |
Accepted for symmetry with
|
theta_floor |
( |
optimizeTheta |
( |
mortality_floor, mortality_ceiling |
( |
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 |
( |
func |
( |
initSpecies |
( |
initEnv |
( |
|
( | |
optimizeSpecies |
( |
optimizeEnv |
( |
inputNN, outputNN |
Not used in 0.2.0: the input dimension of the
environmental-response network always follows from |
dispersion_parameter |
( |
NN |
( |
upper, lower |
( |
dropout |
( |
sample_regeneration |
( |
n_quantiles |
( |
continuous |
( |
light_mask |
( |
custom_parameters |
( |
mortality_draw |
( |
regeneration_sampler |
( |
growth_scale |
( |
cap, prior, prior_lambda |
The Beverton-Holt cap of
|
theta_floor |
( 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, 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 |
optimizeTheta |
( Use |
mortality_floor, mortality_ceiling |
( The defaults are The floor exists because the shape of |
reg_floor |
( |
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:
-
funcimplements the mechanistic process equation itself. The package's default process functions (growth, mortality, regeneration, competition) reproduce the equations described by Pichler & Käber (2026); a custom function with the same arguments can be passed instead to use a different functional form while keeping the process embedded in, and jointly calibrated with, the rest of the model. The environmental-response function is, by default (
hidden = NULL), a linear/logistic niche function with one coefficient per environmental covariate (named informula) and per species, comparable to a classic species distribution model. Settinghiddento a vector of hidden-layer sizes (e.g.c(25L)) instead replaces this function with a feed-forward neural network, whilefuncand the species-specific process parameters remain mechanistic – the "Level 1" hybridization described in the paper.
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 |
|
holdout |
|
bare_ground |
( |
years |
( |
sites |
With |
patches |
( |
train |
|
x |
A |
species |
( |
... |
|
type |
|
set |
|
Details
-
Training data: the model is simulated from the training initial state under the training environment and compared with the observations it was fitted to, aggregated the way
fit()scores them (seecomparePlot()). -
Holdout (
holdout = list(data =, env =, init_cohort =)): the same on data the model has not seen, e.g. a spatially separate set of sites. -
Bare ground (
bare_ground = TRUE): the run ofsimulateForest(model, bare_ground = TRUE, years = , sites = ), from an empty stand foryearsyears under the mean climate of the fitted environment held constant, or under each site's mean climate withsites(seesimulateForest()). Optional, because a long run takes time.
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 |
( |
env |
( |
init_cohort |
( |
nperm |
( |
method |
( |
seed |
( |
sim_seed |
( |
env_autoscale |
( |
... |
passed to |
Details
Two scorings via method:
-
"rmse"— RMSE between the unpermuted and permuted rate, in units of that species' rate SD. Unbounded; larger = more important. -
"sobol"— total-effect estimator0.5 * mean(MSE_shift) / Var(rate); dimensionless (only bounded in[0, 1]under independent predictors — FINN's climate predictors are usually correlated, so treat it as relative).
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,yearsite index and simulated year (
1..22).temp,tempmax,tempminannual mean, warmest-month maximum and coldest-month minimum temperature, degrees C (bioclim 1, 5, 6).
prec,precwarmqannual and warmest-quarter precipitation, mm (bioclim 12, 18).
precseasprecipitation 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,yearsite and patch index;
yearis 0.species,species_namespecies index
1..11and name, coded as in fia_species_dt.dbhdiameter at breast height, cm.
treestrees represented by the record (
1;NAfor records that are not living stems).treeNameunique 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,yearinteger site index (
1..200) and the years since the site's first inventory (10,20;21or22for one site each).period_lengthyears since the previous inventory (
10;11or12for the late inventory): the window over which the simulation is aggregated before it meets the observation.species,species_namespecies index
1..11and its name;"other"pools the species outside the 98 % most abundant stems.baliving basal area, m2 – the mean over the site's patches (0.06 ha each;
makeObsData(aggregate_by_site = TRUE)).treesliving stems, mean per patch (hence fractional).
dbhmean diameter at breast height of living trees, cm (
NAwhen there are none).growth,growth_nmean annual relative dbh growth rate of the survivors,
(dbh / dbh_before)^(1 / period_length) - 1per tree (tree-weighted over patches), and the number of trees behind it.n_at_risk,n_died,morttrees 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 scoresmortweighted byn_at_risk.regrecruits 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,yearsite index and the census that closes the interval, on the axis of fia_obs_dt (
10,20;21or22).patchIDpatch (FIA subplot) index, as in fia_init_trees.
speciesspecies index
1..11(fia_species_dt), the species the tree was recorded as at the start of the interval.dbhdiameter at breast height at the start of the interval, cm.
growththe tree's yearly relative growth rate over the interval,
(dbh_end / dbh)^(1 / period_length) - 1;NAfor a tree that died.died1if the tree was dead at the end of the interval,0if alive.period_lengthyears 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 |
( |
mortality_process |
( |
growth_process |
( |
regeneration_process |
( |
competition_process |
( |
recruits_dbh |
( |
growth_rate |
( |
recruit_obs_weight |
( |
... |
Arguments of earlier versions, still accepted with a warning:
|
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 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:
-
competition works out how much light reaches each cohort from the basal area of the taller trees on its patch (
competition()); -
growth increases each cohort's diameter, depending on its light, size, species and the site's environment (
growth()); -
mortality removes a share of each cohort's trees, depending on its growth, light, size, species and environment (
mortality()); -
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:
-
fully mechanistic – the equation, with a linear or logistic response to the environment. Every parameter has a meaning and a unit.
-
level 1 – the equation, but its environmental response is a small network (
createProcess(hidden = c(20, 20))). The demography stays the package's equation, so the model still extrapolates the way that equation says it should, while the response to climate is free in shape. -
level 2 – the equation itself replaced by a network (
createHybrid()). The data get the most freedom and the fitted process the least interpretation.
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 |
( |
lr_scheduler |
( |
lr_scheduler_params |
( |
clip_norm |
( |
... |
Further arguments for |
x |
( |
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.
-
optimizeris the rule that turns a gradient into a step. The default, Adam (torch::optim_ignite_adam), adapts the step size per parameter and works well without tuning. Anytorchoptimizer generator can be passed; extra arguments for it, such asweight_decay, go into.... -
lr_schedulerlowers the learning rate during the fit. The default"none"keepslrconstant."step"multiplies the learning rate bygammaeverystep_sizeepochs,"exponential"multiplies it bygammaevery epoch,"cosine"lets it fall smoothly toeta_minoverT_maxepochs, and"plateau"lowers it byfactorafterpatienceepochs without an improvement of the total loss. A schedule helps when the losses keep oscillating late in a fit. Advanced: afunction(optimizer)that returns atorchlearning-rate scheduler (an object with a$step()method). -
lr_scheduler_paramstunes the chosen schedule, e.g.list(step_size = 50, gamma = 0.5)for"step",list(T_max = 200)for"cosine",list(factor = 0.5, patience = 20)for"plateau". Entries that are not given take defaults scaled toepochsandlr. -
clip_normlimits how large a single step can be. Gradients are clipped to this norm, separately for three groups of parameters (the species parameters of the mechanistic processes, the environmental-response networks, and the parameters of the likelihoods), so that a group with large gradients cannot swamp the others. A single number applies the same budget to every group; a named list, e.g.list(mechanistic = 2, nn = 1, loss = 5), sets groups individually.
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
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
-
envis the time axis. Every row is one site in one simulated time step (usually one year), and every site has the same years. The first row of a site drives the first step, starting from the site's initial trees. -
init_cohortis the starting state: the trees of every site at the first census, grouped into cohorts. The number of patches per site is read from it. -
datais what the simulation is compared with: for every site, census year and species, the observed stand variables and demographic rates. An observation with a givenyearis compared with the simulated state at the end of the step with thatyearinenv, so everyyearindatamust also be ayearofenv. -
disturbance(optional) removes trees in given years. -
tree_data(optional) holds the individual trees, for the two ways of scoring growth and mortality per tree (finn_loss).
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
-
makeObsData()turns a tree list (one row per tree and inventory, with site, patch, year, species name, dbh and status) into the observation table, per patch or aggregated per site, with the units above. -
resolveSiteIDs()replaces site, patch and species names by the integer codes, aligns the observation, environment and tree tables on them, and can build the initial cohorts in the same call. -
makeInitCohorts()buildsinit_cohortfrom the trees at the first census. -
climateDF2array(),obsDF2arrays()andCohortMat()are the lower-level converters behind them.
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:
-
"mean"– the abundance-weighted mean over the cohorts of a site and species. The default fordbh,growthandmortality. -
"sum"– the sum over cohorts. The default forba,treesandregeneration. -
"size_classes"– stem counts per diameter class, fortreesonly. Needsbreaks(the class boundaries in cm) and optionallytau(the softness of the class edges in cm, default 1).Kbreaks giveK + 1classes, read from the columnsn_class_1, ...,n_class_K+1ofdata. With a Poisson family this scores total abundance and size composition at once (independent Poisson class counts factorise into a Poisson total times a multinomial composition). Class membership is a difference of sigmoids rather than a hard cut, so the term stays differentiable in the diameter; smalltauapproaches hard binning. -
"quantiles"– the abundance-weighted diameter quantiles instead of the mean, fordbhonly. Needsprobs(e.g.c(0.1, 0.5, 0.9)) and optionallytau(the softness on the cumulative-abundance scale, default 0.05). The observation is read from the columnsdbh_q10,dbh_q50,dbh_q90ofdata(dbh_q<100*p>). Where size classes ask how many stems fall in an interval, this asks how thick the stem at a given position of the distribution is: the upper quantile speaks about the big trees that carry the basal area, which a count likelihood weighs like saplings. -
"tree"– no aggregation: the growth and mortality equations are evaluated on the observed trees at their observed diameters, with the light of the observed stand, and compared tree by tree. Forgrowthandmortalityonly; needstree_data. See Scoring individual trees.
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 |
( |
data |
( |
env |
( |
disturbance |
( |
patches |
( |
patch_size |
( |
init_cohort |
( |
epochs |
( |
lr |
( |
batchsize |
( |
loss_family |
(named |
loss_aggregation |
(named |
loss_resolution |
( |
loss_weights |
( |
weight_scale |
( |
loss_recruit |
( |
tree_data |
( |
control |
( |
device |
( |
threads |
( |
update_step |
( |
start_time |
( |
plot_progress |
( |
folder |
( |
checkpoints |
( |
shuffle |
( |
record_gradients |
( |
env_autoscale |
( |
nonfinite |
( |
reanchor |
( |
anchor_cohorts |
( Build the arrays directly –
|
anchor_mode |
( |
anchor_min_dbh |
( |
teacher_forcing |
( Mutually exclusive with
|
rb_gradient |
( |
trees_offset |
( |
holdout |
|
... |
Arguments of earlier versions, still accepted with a warning:
|
loss |
Deprecated name of |
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:
-
reanchorandteacher_forcing– different estimators, not settings of one. -
loss_aggregation = "tree"andloss_resolution = "tree"– the two per-tree routes score different objects (the observed tree at its measured diameter against the simulated cohort it became) and cannot run in one fit; finn_loss compares them side by side.
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
|
light_steepness |
numeric Steepness of the light-response sigmoid. Defaults to 10. |
debug |
logical If TRUE, return the intermediate components as a list
( |
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.
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:
-
siteID integer index of sites
1..S. -
patchID integer index of patches within site
1..P_s. -
species integer species code
1..sp. -
dbh numeric DBH in cm (either exact or binned midpoints).
-
trees integer count of trees in the cohort.
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
|
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 |
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):
-
dbh,trees,species: tensors per cohort. -
dims: integer vectorc(S, P, K)for sites, patches, cohorts. -
sp: integer number of species. -
device_r: the device given at construction ("cpu"). -
dbh_r,trees_r,species_r: R arrays. -
obsDF2arrays: method convertingobs_dfinto arrays.
Value
If treeID_table = FALSE, a FINN::CohortMat object.
If TRUE, a list with:
-
initCohort: theCohortMatobject. -
init_trees: theobs_dfpassed toCohortMat(), with thecohortIDof every row.
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, |
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
|
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 |
rates |
|
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:
-
obs_dt: observations at site or patch level, one row per site (and patch), inventoryyearand species.period_lengthis the number of years since the site's previous inventory (NAat its first).growthis the mean relative diameter growth rate of the surviving trees (per year, or over the interval, seerates), andgrowth_nis how many trees that mean rests on. Both matter: means are aggregated across patches TREE-WEIGHTED (bygrowth_n), because that is the quantity the model predicts - it simulatessum(g*trees)/sum(trees)over the whole site, so an unweighted mean of patch means would be a different number.growth_nalso travels with the response sofitcan weight the likelihood by it: 34% of patch-level growth observations rest on a single tree while others average 30+, and the variance of a mean is\sigma^2/n. Mortality comes back as a closed-cohort pair of counts,n_at_risk(trees alive at the start of the interval) andn_died(how many of them were dead at the end), plus the derived ratemort(NAwhere no cohort was at risk): the yearly rate1 - (1 - n_died / n_at_risk)^(1 / period_length), orn_died / n_at_riskwithrates = "interval".fit()scoresmortwith the binomial loss weighted byn_at_risk.regis the number of recruits per hectare over the interval. -
tree_dt: input trees with added growth fields and species recode:year_before,dbh_before,period_length(years since the tree's previous record),rel_growth(the increment over the interval,dbh/dbh_before - 1) andgrowth(the tree's growth rate in the unit ofrates, the quantity behindobs_dt$growthand thegrowthcolumn offit(tree_data = )); an input columngrowthis replaced.
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 ( |
growth |
torch.Tensor (Optional) Growth entering the mortality response; defaults to the model's current growth. |
growth_scale |
numeric Growth enters the logit as |
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 |
additional_cols |
character vector Optional. Further numeric columns of
|
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 |
process |
( |
scale |
( |
species_names |
Species names for the legend (see |
... |
currently ignored. |
Value
invisibly, the ggplot object.
See Also
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 |
|
pars |
Which parameters: |
species |
Species numbers to draw; |
env |
Table whose predictor ranges the niches span, in the format of
the |
species_names |
Species names for the labels: a character vector in
species order, a vector named by species number, or a table with |
parameter_names |
Names of the species-specific parameters of a process
function of your own, as a list by process, e.g.
|
... |
Unused. |
Details
-
Process parameters (
pars = "process", the default): one panel per parameter of the growth, mortality, regeneration and competition processes, and the recruit dispersiontheta; one point per species, on the constrained scale the process function uses, the axis spanning the fitted values. A bound of the admissible range set by the argumentslowerandupperofcreateProcess()(forthetathe floor, its argumenttheta_floor) is drawn as a dashed line where a value comes near it, and a species whose parameter ended the fit at a bound is an open triangle (seecreateProcess()on what such a parameter means). -
Environmental niches (
pars = "env"): for each process whose environmental response is linear (nohidden, no customNN, notcreateHybrid()), the fitted environmental term of every species across the range each predictor covers inenv, with the other predictors held at their mean. The curve is the linear predictor the process function receives (pred): for FINN's default functions growth and regeneration useexp(pred)and mortalityplogis(pred + ...), so a curve higher up means faster growth, more recruits or more deaths. The x axis is on the original scale of the predictor; the stored standardisation offit()is applied internally. A process with a network response is skipped with a warning: it has no coefficients to show, andALE()is the way to look at it. Competition does not depend on the environment.
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 |
y |
|
response |
Responses to draw, any of |
sites |
Site ids to include; |
... |
|
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 |
species_names |
Species names for the legend (see |
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 |
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 |
|
env |
( |
disturbance |
( |
patches |
( |
patch_size |
( |
init_cohort |
( |
device |
( |
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 |
debug |
( |
recruits |
( |
obs_recruits |
( |
... |
Advanced options forwarded to the internal simulator, chiefly
|
model |
|
bare_ground |
( |
years |
( |
sites |
|
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 |
( |
tree_data |
( |
env |
( |
patches |
( |
patch_size |
( |
device |
( |
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).
-
regeneration(): the core alone. The expected recruitment is not bounded; it grows with the environmental response. -
regeneration_capped(): the default since 0.2.0, used whenregeneration_processisNULL. The core is capped by a Beverton-Holt term,K m / (K + m).createProcess(cap = "all")(default) gives one capKshared by all species,cap = "species"one per species. The cap carries a prior,prior_lambda * (log K - log prior)^2, withprior = "max_obs_recruits"(the largest observed recruitment per ha and year) andprior_lambda = 0.1by default. The cap bounds the MEAN recruitment only. It does not bound the variance of the recruit draw, which around a capped mean is stillK + K^2 / theta(see the dispersion section below). -
regeneration_saturation(): the same function asregeneration_capped()under its older name, kept as a deprecated alias for one release. -
regeneration_adult(): the capped process with a seed source. The recruitment of a species is multiplied byf(A) = A / (A + A_half), whereAis the density of its own adults (stems above an adult thresholdx) pooled over the patches of the site. A species without adults on a site recruits only atreg_floor.xandA_halfare declared throughcreateProcess(custom_parameters = ); see its help page. -
regeneration_adult_effect(): the adult density as an effect on recruitment instead of a gate,f(A) = f0 + (1 - f0) A / (A + A_half)withf0 = plogis(reg_adult_logitf0), the share of the potential recruitment a species gets without adults on the site (seed rain from outside, advance regeneration). Prefer it toregeneration_adult()whenever a species must be able to establish where it has no adults: colonisation from an empty stand, and any free run from bare ground, needf0 > 0.f0 -> 1removes the adult effect,f0 -> 0isregeneration_adult().
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:
-
sample_regeneration = TRUE(default): recruits are drawn from a negative binomial with that mean and sizetheta(the dispersion, next section), usingcreateProcess(regeneration_sampler = )."refined"(default since 0.2.0) draws the Gamma-mixed Poisson exactly where its rate is below 2 and uses a Gaussian approximation above."gaussian"reproduces results published before 0.2.0; its guards act as a recruitment floor of 0.0011 per cell and year (seernbinom_torch_refined()). -
sample_regeneration = FALSE: the expected number is used and rounded. Wherever the expected number per patch is below 0.5 the rounding delivers no recruit at all. At small patches and low rates this is a silent zero for every sparse species, however well its rate is calibrated.
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:
-
dispersion_parameter: the starting value, or the fixed value whenthetais not trained. Default1. -
optimizeTheta:TRUE(default) trainstheta.FALSEkeeps it atdispersion_parameterfor the whole fit, in the draw and in the likelihood alike. -
theta_floor: a lower bound applied whereverthetais read, trained or not. Default0.5since 0.2.0;0orNULLremoves it. A fixeddispersion_parameterbelow the floor is raised to the floor.
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
-
Default settings (
regeneration_capped, trainedthetawiththeta_floor = 0.5,"nbinom"): the fit is stable, and in one converged pair of fits on the German national forest inventory the recruitment level was calibrated as well as with a fixedtheta. Do not read the level from a fit stopped early; check that$param_historyhas settled. -
For short fits, or when the recruitment level should not depend on how long the fit runs: keep
thetafixed (createProcess(optimizeTheta = FALSE), withdispersion_parameter1 or higher), or usefit(loss_family = c(..., regeneration = "poisson")). Mind thatrecruit_obs_weightis ignored under"poisson"(above). -
When small trees are sampled too sparsely, and in particular when the spatial pattern of recruitment is not predictable from the predictors (on the German national forest inventory no configuration ranked sites better than a Spearman correlation of about 0.08 out of sample): use the staged route of the previous section.
-
Check before interpreting recruitment: compare the predicted and the observed total recruitment, and the regeneration loss in
m$historyagainst its intercept-only baseline (withloss_weights = "auto", a value of 1 is no better than predicting the mean).
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, |
trees |
torch.Tensor stems per cohort, |
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:
-
reg_logK(optional, see above): the log Beverton-Holt cap, stems ha^-1 step^-1; -
reg_adult_logx: the log adult threshold,x = exp(reg_adult_logx)in the units ofdbh. Oncexfalls below the smallest diameter present, every stem counts as an adult andxstops receiving gradient; -
reg_adult_logA: the log half-saturation adult density,A_half = exp(reg_adult_logA)stems ha^-1.
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, |
trees |
torch.Tensor stems per cohort, |
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:
-
reg_adult_logx: the log adult threshold,x = exp(reg_adult_logx)in the units ofdbh; -
reg_adult_logA: the log half-saturation adult density,A_half = exp(reg_adult_logA)stems ha^-1; -
reg_adult_logitf0: the logit of the share without adults,f0 = plogis(reg_adult_logitf0).
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 |
createInitCohorts |
logical. If TRUE, build FINN initial cohorts from
the living trees of the first inventory ( |
time_axis |
|
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:
-
siteID_dt: site/patch/year index map (OrigYearis the calendar year). -
tree_dt: tree table with indices and standardized species. -
env_dt: environment table with indices, the years of the simulation:siteID,yearand the predictors, whatfit(env = )takes (siteID_dtmaps the ids back to the site names). -
obs_dt: site-aggregated observations by species, withperiod_length. -
obs_dt_patches: patch-level observations by species. -
species_dt: species lookup (species,species_name). -
initCohorts(optional): FINNCohortMatobject. -
initCohort_dt(optional): trees used to build cohorts.
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:
-
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 carryn_at_riskandn_died) and n; for mortality also the tree-level AUC and the ratio of predicted to observed deaths. On the training data and, whenevaluate()or the argumentholdoutoffit()stored one, on the holdout. The observations are compared with the simulation aggregated the wayfit()scores it (seecomparePlot()). Without a stored evaluation,summary()runsevaluate()on the training data first (one simulation) and stores it on the model. -
Convergence: by how many percent each loss term changed over the last
epochs_backepochs (the mean of the lastepochs_backepochs against the mean of theepochs_backbefore), as a table with one sentence on the largest change; and how much the parameters moved over the lastepochs_backepochs, as a table with one row per process (growth, mortality, regeneration, competition) and part (its species parameters, where they are fitted (optimizeSpecies = TRUEincreateProcess()), 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, soepochs_backcan be at most 50; for a model fitted before this version the parameter snapshots of the fit (model$param_history, everycheckpointsepochs) 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 offit()whoseepochsis a multiple ofcheckpoints). 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. -
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. -
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 |
( |
env, init_cohort |
( |
importance |
( |
env_autoscale |
( |
sim_seed |
( |
nperm |
( |
scale |
( |
epochs_back |
( |
... |
|
species_names, parameter_names |
Names of the species and of the
parameters of a process function of one's own, as for |
x |
A |
species |
( |
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