| title | subtitle | date | output | editor_options | bibliography | link-citations | always_allow_html | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Biomass_speciesFactorial Manual |
v.0.0.13 |
Last updated: 2025-08-25 |
|
|
citations/references_Biomass_speciesFactorial.bib |
true |
true |
(ref:Biomass-speciesFactorial) Biomass_speciesFactorial
Eliot McIntire eliot.mcintire@nrcan-rncan.gc.ca [aut]
Create and run a factorial simulation experiment for LANDIS-II-like species traits.
Table @ref(tab:moduleInputs-Biomass-speciesFactorial) shows the full list of module inputs.
| objectName | objectClass | desc | sourceURL |
|---|---|---|---|
| argsForFactorial | list | A named list of parameters in the species Table, with the range of values they each should take. Internally, this module will run `expand.grid` on these, then will take the 'upper triangle' of the array, including the diagonal. | NA |
Summary of user-visible parameters (Table @ref(tab:moduleParams-Biomass-speciesFactorial))
| paramName | paramClass | default | min | max | paramDesc |
|---|---|---|---|---|---|
| .plots | character | screen | NA | NA | Used by Plots function, which can be optionally used here |
| .plotInitialTime | numeric | 0 | NA | NA | Describes the simulation time at which the first plot event should occur. |
| .plotInterval | numeric | NA | NA | NA | Describes the simulation time interval between plot events. |
| .saveInitialTime | numeric | NA | NA | NA | Describes the simulation time at which the first save event should occur. |
| .saveInterval | numeric | NA | NA | NA | This describes the simulation time interval between save events. |
| .seed | list | NA | NA | Named list of seeds to use for each event (names). | |
| .useCache | character | NA | NA | NA | Should caching of events or module be used? |
| factorialSize | character | medium | small | large | If user does not supply an explicit `argsForFactorial`, then they can specify either 'small', 'medium' or 'large' to take default ones that have different numbers of factorial combinations. Smaller is faster and uses less RAM; larger is slower and uses more RAM. |
| initialB | numeric | 10 | 1 | NA | initial cohort biomass at `age = 1`. If `NA`, will use `maxBInFactorial/30` akin to the LANDIS-II Biomass Succession default. Must be greater than `P(sim)$minCohortBiomass` |
| maxBInFactorial | integer | 5000 | NA | NA | The arbitrary maximum biomass for the factorial simulations. This is a per-species maximum within a pixel. |
| minCohortBiomass | numeric | 9 | NA | NA | The smallest amount of biomass before a cohort is removed from a simulation. Barring removal via this parameter, cohorts can persist with B = 1 until age = longevity. |
| readExperimentFiles | logical | TRUE | NA | NA | Reads all the `cohortData` files that were saved to disk during the experiment. Note that this can be run even if `runExperiment = FALSE`. |
| runExperiment | logical | TRUE | NA | NA | A logical indicating whether to run the experiment (may take time). See `readExperimentFiles`, which may be useful if the `cohortData` files have already been saved and all that is needed is reading them in. |
Describe what happens for each event type.
Write what is plotted.
Write what is saved.
Description of the module outputs (Table @ref(tab:moduleOutputs-Biomass-speciesFactorial)).
| objectName | objectClass | desc |
|---|---|---|
| cohortDataFactorial | data.table | A large `cohortData` table ( sensu `Biomass_core`) columns necessary for running `Biomass_core`, e.g., `longevity`, `growthcurve`, `mortalityshape`, etc.. It will have unique species for unique combination of the `argsForFactorial`, and a fixed value for all other species traits. Currently, these are set to defaults internally. |
| factorialOutputs | data.table | A data.table of the `outputs(sim)` that is used during the factorial. This will give the file names of all the `cohortData` files that were produced. |
| speciesTableFactorial | data.table | A large species table ( sensu `Biomass_core`) with all columns necessary for running `Biomass_core`, e.g., `longevity`, `growthcurve`, `mortalityshape`, etc.. It will have unique species for unique combination of the `argsForFactorial`, and a fixed value for all other species traits. Currently, these are set to defaults internally. |
:::{.rmdwarning}
## This script is for running the species traits factorial design.
## It requires a version of Biomass_core that is .gitignored:
## - the version had many changes to accommodate the 'no regeneration' scenario;
## - many of the other changes have been subsequently incorporated into Biomass_core, so it may work with a newer version
options(
reproducible.cacheSaveFormat = "qs",
reproducible.showSimilar = TRUE,
reproducible.showSimilarDepth = 5,
reproducible.useMemoise = FALSE,
spades.moduleCodeChecks = FALSE,
spades.recoveryMode = FALSE
)
## Packages
if (!require("Require")) {
install.packages("Require"); require("Require")
}
Require("PredictiveEcology/SpaDES.install", upgrade = FALSE)
installSpaDES()
Require(c("PredictiveEcology/SpaDES.core@development (== 1.0.9.9004)",
"reproducible"), upgrade = FALSE)
## Modules
setPaths(rasterPath = tempdir(),
cachePath = file.path(tempdir(), "Cache"),
modulePath = file.path("modules"),
inputPath = file.path(getwd(), "inputs"),
outputPath = file.path(getwd(),"outputs"))
moduleNameAndBranch <- c("Biomass_speciesParameters@EliotTweaks",
"Biomass_speciesFactorial@main")
lapply(moduleNameAndBranch, function(modName) {
Cache(getModule, file.path("PredictiveEcology", modName), overwrite = TRUE)
})
modules <- gsub("@.+", "", moduleNameAndBranch)
modules <- c("Biomass_speciesFactorial", modules)
outputs <- data.frame(expand.grid(
objectName = c("species", "speciesEcoregion"),
saveTime = 0,
eventPriority = 10, fun = "qs::qsave",
stringsAsFactors = FALSE
))
## Slow and large :
## -- longevity 600 would be too big, use 400;
objects <- list(argsForFactorial = list(cohortsPerPixel = 1:2,
growthcurve = seq(0.65, 0.85, 0.02),
mortalityshape = seq(20, 25, 1),
longevity = seq(125, 400, 25),
mANPPproportion = seq(3.5, 6, 0.25))
)
## Fast
objects <- list(argsForFactorial = list(cohortsPerPixel = 1:2,
growthcurve = seq(0.65, 0.85, 0.1),
mortalityshape = seq(20, 25, 5),
longevity = seq(125, 600, 100),
mANPPproportion = seq(3.5, 6, 1))
)
## Medium
objects <- list(argsForFactorial = list(cohortsPerPixel = 1:2,
growthcurve = seq(0.65, 0.85, 0.02),
mortalityshape = seq(20, 25, 2),
longevity = seq(125, 600, 50),
mANPPproportion = seq(3.5, 6, 0.3))
)
simOut <- simInitAndSpades(
times = list(start = 0, end = 0),
modules = modules,
params = list(
Biomass_speciesFactorial = list(.plots = NA, runExperiment = TRUE),
Biomass_speciesParameters = list(.plots = "pdf")
),
outputs = outputs,
objects = objects,
debug = 1
)