Merge pull request #86 from PredictiveEcology/development

update `main`!

.github/workflows/render-module-rmd.yaml

@@ -3,12 +3,10 @@ on:
     branches:
       - main
       - master
-      - development
   push:
     branches:
       - main
       - master
-      - development
     paths:
       - .github/workflows/render-module-rmd.yaml
       - Biomass_core.Rmd

.gitignore

@@ -19,8 +19,13 @@ citations/*.csl
 *_cache/
 *_files/
 
+## don't ignore tables needed for manual
+!tables/*
+
 ## these are downloaded automatically, no point in caching
 figures/*Badge.png
 
 CHECKSUMS.txt
 
+
+Biomass_core2.Rmd

Biomass_core.Rmd

@@ -388,8 +388,8 @@ further detail.
 \blandscape
 
 ```{r invariantSpptraits, echo = FALSE, eval = TRUE, message = FALSE, results = 'asis'}
-tab <- read.xlsx("tables/exampleTables.xlsx", sheet = "invariantTraits", 
-                 colNames = TRUE, sep.names = " ")
+tab <- openxlsx::read.xlsx("tables/exampleTables.xlsx", sheet = "invariantTraits", 
+                           colNames = TRUE, sep.names = " ")
 caption <- paste("Example of an invariant species traits table (the",
                  "`species` table object in the module), with species (ref:Abie-sp),",
                  "(ref:Pice-eng), (ref:Pice-gla), (ref:Pinu-sp), (ref:Popu-sp) and (ref:Pseud-men).",
@@ -597,6 +597,13 @@ dynamics. Should contain one colour per species in the `species` table and,
 potentially a colour for species mixtures (named "Mixed"). Vector names must
 follow `species$speciesCode`.
 
+-   `sppNameVector` -- (OPTIONAL) a character vector of species to be simulated.
+If provided, *Biomass_core* uses this vector to (attempt to) obtain `speciesLayers`
+for the listed species. If not provided, the user (or another module) can pass a filtered `sppEquiv` table
+(i.e., containing only the species that are to be simulated). If neither is provided,
+then *Biomass_core* attempts to use any species for which if finds available species
+(ref:percent) cover data in the study area.
+
 **Cohort-simulation-related objects**
 
 -   `cohortData` -- a `data.table` containing initial cohort information per
@@ -618,7 +625,7 @@ columns:
 
     -   *mortality* -- integer. Cohort dead biomass of the current year in
     $g/m^2$. Usually filled with 0s in initial conditions.
-    
+
     -   *aNPPAct* -- integer. Actual aboveground net primary productivity of the
     current year in $g/m^2$. `B` is the result of the previous year's `B`
     minus the current year's `mortality` plus `aNPPAct`. Usually filled with
@@ -736,14 +743,11 @@ However, any of the objects changed/output by *Biomass_core* (listed in Table
 \@ref(tab:moduleOutputs-Biomass-core)) can be saved via the `outputs` argument
 in `simInit`[^biomass_core-5].
 
-\newpage
-\blandscape
-
 ```{r moduleOutputs-Biomass-core, echo = FALSE, eval = TRUE, message = FALSE, results = 'asis'}
 df_outputs <- moduleOutputs("Biomass_core", "..")
 caption <- "List of (ref:Biomass-core) output objects and their description."
 
-panble(df_outputs, caption, landscape = TRUE,
+panble(df_outputs, caption, 
        panderArgs = list("justify" = "left", 
                          "digits" = 3, "split.cells" = c(15, 15, 40), "split.tables" = Inf),
        kable_stylingArgs = list(full_width = TRUE))
@@ -1053,10 +1057,8 @@ dir.create(pkgPath, recursive = TRUE)
 .libPaths(pkgPath, include.site = FALSE)
 
 if (!require(Require, lib.loc = pkgPath)) {
-  remotes::install_github(
-    paste0("PredictiveEcology/",
-           "Require@5c44205bf407f613f53546be652a438ef1248147"),
-    upgrade = FALSE, force = TRUE)
+  remotes::install_github("PredictiveEcology/Require@5c44205bf407f613f53546be652a438ef1248147",
+                          upgrade = FALSE, force = TRUE)
   library(Require, lib.loc = pkgPath)
 }
 
@@ -1077,8 +1079,7 @@ dependencies are installed in their correct version.
 modules in the `paths$modulePath`, and `Require` installs them.
 
 ```{r getModule-Biomass-core, eval=FALSE}
-Require(paste0("PredictiveEcology/",
-               "SpaDES.project@6d7de6ee12fc967c7c60de44f1aa3b04e6eeb5db"), 
+Require("PredictiveEcology/SpaDES.project@6d7de6ee12fc967c7c60de44f1aa3b04e6eeb5db", 
         require = FALSE, upgrade = FALSE, standAlone = TRUE)
 
 paths <- list(inputPath = normPath(file.path(tempDir, "inputs")), 

Biomass_core.md

@@ -837,6 +837,13 @@ dynamics. Should contain one colour per species in the `species` table and,
 potentially a colour for species mixtures (named "Mixed"). Vector names must
 follow `species$speciesCode`.
 
+-   `sppNameVector` -- (OPTIONAL) a character vector of species to be simulated.
+If provided, *Biomass_core* uses this vector to (attempt to) obtain `speciesLayers`
+for the listed species. If not provided, the user (or another module) can pass a filtered `sppEquiv` table
+(i.e., containing only the species that are to be simulated). If neither is provided,
+then *Biomass_core* attempts to use any species for which if finds available species
+(ref:percent) cover data in the study area.
+
 **Cohort-simulation-related objects**
 
 -   `cohortData` -- a `data.table` containing initial cohort information per
@@ -969,6 +976,12 @@ and `B` composition, even if the user supplies other initial groupings
    <td style="text-align:left;"> table of species equivalencies. See `LandR::sppEquivalencies_CA`. </td>
    <td style="text-align:left;"> NA </td>
   </tr>
+  <tr>
+   <td style="text-align:left;"> sppNameVector </td>
+   <td style="text-align:left;"> character </td>
+   <td style="text-align:left;"> an optional vector of species names to be pulled from `sppEquiv`. Species names must match `P(sim)$sppEquivCol` column in `sppEquiv`. If not provided, then species will be taken from the entire `P(sim)$sppEquivCol` column in `sppEquiv`. See `LandR::sppEquivalencies_CA`. </td>
+   <td style="text-align:left;"> NA </td>
+  </tr>
   <tr>
    <td style="text-align:left;"> studyArea </td>
    <td style="text-align:left;"> SpatialPolygonsDataFrame </td>
@@ -1093,6 +1106,14 @@ event (growth and mortality are always yearly);
    <td style="text-align:left;"> NA </td>
    <td style="text-align:left;"> A numeric scalar indicating how large each chunk of an internal data.table is, when processing by chunks </td>
   </tr>
+  <tr>
+   <td style="text-align:left;"> initialB </td>
+   <td style="text-align:left;"> numeric </td>
+   <td style="text-align:left;"> 10 </td>
+   <td style="text-align:left;"> 1 </td>
+   <td style="text-align:left;"> NA </td>
+   <td style="text-align:left;"> initial biomass values of new age-1 cohorts. If `NA` or `NULL`, initial biomass will be calculated as in LANDIS-II Biomass Suc. Extension (see Scheller and Miranda, 2015 or `?LandR::.initiateNewCohorts`) </td>
+  </tr>
   <tr>
    <td style="text-align:left;"> gmcsGrowthLimits </td>
    <td style="text-align:left;"> numeric </td>
@@ -1133,14 +1154,6 @@ event (growth and mortality are always yearly);
    <td style="text-align:left;"> NA </td>
    <td style="text-align:left;"> Initial time for the growth event to occur </td>
   </tr>
-  <tr>
-   <td style="text-align:left;"> initialB </td>
-   <td style="text-align:left;"> numeric </td>
-   <td style="text-align:left;"> 10 </td>
-   <td style="text-align:left;"> 1 </td>
-   <td style="text-align:left;"> NA </td>
-   <td style="text-align:left;"> initial biomass values of new age-1 cohorts </td>
-  </tr>
   <tr>
    <td style="text-align:left;"> initialBiomassSource </td>
    <td style="text-align:left;"> character </td>
@@ -1243,7 +1256,7 @@ event (growth and mortality are always yearly);
    <td style="text-align:left;"> NA </td>
    <td style="text-align:left;"> NA </td>
    <td style="text-align:left;"> NA </td>
-   <td style="text-align:left;"> defines the plotting time step. If `NA`, the default, .plotInterval is set to successionTimestep. </td>
+   <td style="text-align:left;"> defines the plotting time step. If `NA`, the default, `.plotInterval` is set to `successionTimestep`. </td>
   </tr>
   <tr>
    <td style="text-align:left;"> .plots </td>

R/age-cohorts.R

@@ -1,3 +1,31 @@
+#' Reclassify cohort ages
+#'
+#' Collapses cohorts into age bins defined by `successionTimestep`,
+#'  thereby reducing the number of cohorts in a `pixelGroup`.
+#'
+#' @param cohortData A `data.table` with columns: `pixelGroup`, `ecoregionGroup`,
+#'   `speciesCode`, and optionally `age`, `B`, `mortality`, `aNPPAct`, and `sumB`.
+#' @param successionTimestep The time between successive seed dispersal events.
+#'   In LANDIS-II, this is called "Succession Timestep".
+#' @param stage `character`. Either "spinup" or "nonSpinup", depending on whether
+#'   the functions is running during spin-up stage or not. See details.
+#' @param byGroups columns in `cohortData` defining that will define groups of
+#'   cohorts whose ages will be collapsed.
+#'
+#' @detail at each step defined by `successionTimestep` (i.e. if `successionTimestep` = 10,
+#'   at every 10 years), cohorts are collapsed into age bins defined by
+#'   `successionTimestep` (i.e. if `successionTimestep` = 10, 10-year bins). When
+#'   collapsing cohorts, their biomass (B), lost biomass (mortality) and primary
+#'   productivity (aNPPact) are summed.
+#'   If `stage == "spinup"` cohorts are not collapsed.
+#'
+#' @references Scheller, R.M. & Miranda, B.R. (2015). LANDIS-II Biomass Succession v3.2 Extension  – User Guide.
+#'
+#' @return
+#' @export
+#'
+#' @importFrom data.table rbindlist
+#' @importFrom LandR asInteger
 ageReclassification <- compiler::cmpfun(function(cohortData, successionTimestep, stage,
                                                  byGroups = c("pixelGroup", "speciesCode", "age")) {
 
@@ -21,7 +49,7 @@ ageReclassification <- compiler::cmpfun(function(cohortData, successionTimestep,
     # NOTE: We do not need to squash if there is nothing to squash, i.e., cases with 1 species in a pixelGroup that is <successionTimestep old,
     #       don't need to be squashed.
     anyDuplicates <- duplicated(targetData, by = byGroupsNoAge)
-    cdColNames <- colnames(cohortData)
+
     message("  Setting all ages <= ", successionTimestep, " to ", successionTimestepPlusOne)
     if (any(anyDuplicates)) {
       # pull out only duplicated types. NOTE "which = TRUE" gives only the indices of the joined rows;