-
Notifications
You must be signed in to change notification settings - Fork 4
/
Biomass_core.Rmd
1326 lines (1055 loc) · 67 KB
/
Biomass_core.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
---
title: "LandR _Biomass_core_ Manual"
date: "Last updated: `r Sys.Date()`"
output:
bookdown::html_document2:
toc: true
toc_float: true
toc_depth: 4
theme: sandstone
number_sections: false
df_print: paged
keep_md: yes
editor_options:
chunk_output_type: console
bibliography: citations/references_Biomass_core.bib
citation-style: citations/ecology-letters.csl
link-citations: true
always_allow_html: true
---
<!-- the following are text references used in captions for LaTeX compatibility -->
(ref:Biomass-core) *Biomass_core*
(ref:Biomass-borealdataPrep) *Biomass_borealDataPrep*
(ref:percent) %
(ref:sufficient-light) *sufficient light*
(ref:Abie-sp) *Abies sp.* (Abie_sp)
(ref:Pinu-sp) *Pinus sp.* (Pinu_sp)
(ref:Pice-eng) *Picea engelmannii* (Pice_eng)
(ref:Pice-gla) *Picea glauca* (Pice_gla)
(ref:Popu-sp) *Populus sp.* (Popu_sp)
(ref:Pseud-men) *Pseudotsuga menziesii* (Pseu_men)
```{r setup-Biomass-core, include = FALSE}
## set cache.rebuild = TRUE whenever there are changes to the module code/metadata
knitr::opts_chunk$set(echo = TRUE, eval = FALSE, warning = FALSE,
cache = TRUE, cache.rebuild = FALSE, results = "hold", dpi = 300)
## get citation style
if (!file.exists("citations/ecology-letters.csl")) {
dir.create("citations", showWarnings = FALSE)
download.file("https://www.zotero.org/styles/ecology-letters", destfile = "citations/ecology-letters.csl")
}
library(Require)
Require(c("SpaDES.core", "git2r", "dplyr", "data.table", "kableExtra",
"openxlsx", "pander", "PredictiveEcology/SpaDES.docs"),
upgrade = FALSE, install = FALSE)
```
```{r badgeFigs-Biomass-core, include = FALSE, eval = TRUE, cache = FALSE}
dir.create("figures", showWarnings = FALSE)
if (!file.exists("figures/markdownBadge.png")) {
download.file(url = "https://img.shields.io/badge/Made%20with-Markdown-1f425f.png",
destfile = "figures/markdownBadge.png",
mode = 'wb')
}
if (!file.exists("figures/issuesBadge.png")) {
download.file(url = "https://img.shields.io/badge/Get%20help-Report%20issues-%3CCOLOR%3E.png",
destfile = "figures/issuesBadge.png",
mode = 'wb')
}
modversion <- paste(unlist(moduleMetadata(module = 'Biomass_core', path = '..')$version), collapse = ".")
download.file(url = paste0("https://img.shields.io/badge/Biomass_core-", paste0("v.%20", modversion),
"-%3CCOLOR%3E.png"),
destfile = "figures/moduleVersionBadge.png",
mode = 'wb')
```
``` {r moduleBadge-Biomass-core, echo = FALSE, eval = TRUE, cache = FALSE, results = "asis"}
## try to automatically get the commit URL and the path to the badge image
modulePath <- if (grepl("Biomass_core$", normPath("."))) {
normPath(".")
} else {
modulePath <- grep("Biomass_core$",
list.files(pattern = "Biomass_core", recursive = TRUE, include.dirs = TRUE),
value = TRUE)
modulePath <- grep("docs/", modulePath, value = TRUE, invert = TRUE) ## exclude "copied" modules dirs for bookdown
normPath(modulePath)
}
badgeURL <- if (!is_detached(modulePath)) {
commitSHA <- sha(revparse_single(modulePath, "HEAD"))
repo <- sub("[.]git$", "/commit/",
branch_remote_url(branch_get_upstream(repository_head(modulePath))))
paste0(repo, commitSHA)
} else {
## if detached point to the first remote
remote_url(modulePath)[1]
}
badgeURL <- sub(".*github[.]com:", "https://github.com/", badgeURL)
badgePath <- normPath("figures/moduleVersionBadge.png")
## make string of markdown code to be executed as-is
cat(paste0("[![module-version-Badge](", badgePath, ")](", badgeURL, ")"))
```
``` {r issuesBadge-Biomass-core, echo = FALSE, eval = TRUE, cache = FALSE, results = "asis"}
badgeURL <- "https://github.com/PredictiveEcology/Biomass_core/issues"
badgePath <- normPath("figures/issuesBadge.png")
## make string of markdown code to be executed as-is
cat(paste0("[![Issues-badge](", badgePath, ")](", badgeURL,")"))
```
#### Authors:
`r paste(as.character(moduleMetadata(module = 'Biomass_core', path = '..')$authors), sep = ', ')`
<!-- ideally separate authors with new lines, '\n' not working -->
**This documentation is work in progress. Potential discrepancies and omissions
may exist for the time being. If you find any, contact us using the "Get help"
link above.**
## Module Overview
### Quick links
- [General functioning](#general-functioning)
- [List of input objects](#inputs-list)
- [List of parameters](#params-list)
- [List of outputs](#outputs-list)
- [Simulation flow and module events](#sim-flow)
### Summary
LandR *Biomass_core* (hereafter *Biomass_core*) is the core forest succession
simulation module of the LandR ecosystem of `SpaDES` modules [see
@ChubatyMcIntire2019]. It simulates tree cohort ageing, growth, mortality and
competition for light resources, as well as seed dispersal (Fig.
\@ref(fig:fig-Biomass-core)), in a spatially explicit manner and using a yearly
time step. The model is based on the LANDIS-II Biomass Succession Extension
v.3.2.1 [LBSE, @SchellerMiranda2015], with a few changes (see [Differences
between *Biomass_core* and LBSE](#biomass-core-vs-lbse)). Nonetheless, the
essential functioning of the succession model still largely follows its
LANDIS-II counterpart, and we refer the reader to the corresponding LBSE manual
[@SchellerMiranda2015] for a detailed reading of the mechanisms implemented in
the model.
```{r fig-Biomass-core, echo = FALSE, eval = TRUE, out.width = "80%", fig.align = 'center', fig.cap = "(ref:Biomass-core) simulates tree cohort growth, mortality, recruitment and dispersal dynamics, as a function of cohort ageing and competition for light (shading) and space, as well as disturbances like fire (simulated using other modules)."}
## make sure all include_graphics have wd attached to figure path
## this is necessary to knit to pdf using child Rmds - see https://stackoverflow.com/questions/61065560/cant-compile-rmarkdown-pdf-with-image-in-child-rmd-latex-error-image-file
knitr::include_graphics(normPath("figures/Biomass_coreSchematic.png"))
```
### Links to other modules {#links-modules}
*Biomass_core* is intended to be used with data/calibration modules, disturbance
modules and validation modules, amongst others. The following is a list of the
modules most commonly used with *Biomass_core*. For those not yet in the [LandR
Manual](https://landr-manual.predictiveecology.org/) see the individual module's
documentation (`.Rmd` file) available in its repository.
See [here](https://rpubs.com/PredictiveEcology/LandR_Module_Ecosystem) for all
available modules and select *Biomass_core* from the drop-down menu to see
linkages.
**Data and calibration modules:**
- [*Biomass_speciesData*](https://github.com/PredictiveEcology/Biomass_speciesData):
grabs and merges several sources of species cover data, making species
percent cover ((ref:percent) cover) layers used by other LandR Biomass
modules. Default source data spans the entire Canadian territory;
- [*Biomass_borealDataPrep*](https://github.com/PredictiveEcology/Biomass_borealDataPrep):
prepares all parameters and inputs (including initial landscape conditions)
that *Biomass_core* needs to run a realistic simulation. Default
values/inputs produced are relevant for boreal forests of Western Canada;
- [*Biomass_speciesParameters*](https://github.com/PredictiveEcology/Biomass_speciesParameters):
calibrates four-species level traits using permanent sample plot data (i.e.,
repeated tree biomass measurements) across Western Canada.
**Disturbance-related modules:**
- [*Biomass_regeneration*](https://github.com/PredictiveEcology/Biomass_regeneration):
simulates cohort biomass responses to stand-replacing fires (as in LBSE),
including cohort mortality and regeneration through resprouting and/or
serotiny;
- [*Biomass_regenerationPM*](https://github.com/PredictiveEcology/Biomass_regenerationPM):
like *Biomass_regeneration*, but allowing partial mortality. Based on the
LANDIS-II Dynamic Fuels & Fire System extension [@SturtevantEtAl2018];
- *fireSense*: climate- and land-cover-sensitive fire model simulating fire
ignition, escape and spread processes as a function of climate and
land-cover. Includes built-in parameterisation of these processes using
climate, land-cover, fire occurrence and fire perimeter data. Requires using
*Biomass_regeneration* or *Biomass_regenerationPM*. See modules prefixed
"*fireSense\_*" at <https://github.com/PredictiveEcology/>;
- [*LandMine*](https://github.com/PredictiveEcology/LandMine): wildfire
ignition and cover-sensitive wildfire spread model based on a fire return
interval input. Requires using *Biomass_regeneration* or
*Biomass_regenerationPM*;
- [*scfm*](https://github.com/PredictiveEcology/scfm): spatially explicit fire
spread module parameterised and modelled as a stochastic three-part process
of ignition, escape, and spread. Requires using *Biomass_regeneration* or
*Biomass_regenerationPM*.
**Validation modules:**
- [*Biomass_validationKNN*](https://github.com/PredictiveEcology/Biomass_validationKNN):
calculates two validation metrics (mean absolute deviation and sum of
negative log-likelihoods) on species presences/absences and biomass-related
properties across the simulated landscape. By default, it uses an
independent dataset of species (ref:percent) cover and stand biomass for
2011, assuming that this is a second snapshot of the landscape.
## Module manual
### General functioning {#general-functioning}
*Biomass_core* is a forest landscape model based on the LANDIS-II Biomass
Succession Extension v.3.2.1 model [LBSE, @SchellerMiranda2015]. It is the core
forest succession model of the LandR ecosystem of `SpaDES` modules. Similarly to
LBSE, *Biomass_core* simulates changes in tree cohort aboveground biomass
($g/m^2$) by calculating growth, mortality and recruitment as functions of pixel
and species characteristics, competition and disturbances (Fig.
\@ref(fig:fig-Biomass-core)). Note that, by default, cohorts are unique
combinations of species and age, but this can be changed via the
`cohortDefinitionCols` parameter (see [List of parameters](#params-list)).
Specifically, cohort growth is driven by both invariant (growth shape parameter,
`growthcurve`) and spatio-temporally varying species traits (maximum biomass,
`maxB`, and maximum annual net primary productivity, `maxANPP`), while
background mortality (i.e., not caused by disturbances) depends only on
invariant species traits (`longevity` and mortality shape parameter,
`mortalityshape`). All these five traits directly influence the realised shape
of species growth curves, by determining how fast they grow (`growthcurve` and
`maxANPP`), how soon age mortality starts with respect to longevity
(`mortalityshape`) and the biomass a cohort can potentially achieve (`maxB`).
Cohort recruitment is determined by available "space" (i.e., pixel shade),
invariant species traits (regeneration mode, `postfireregen`, age at maturity,
`sexualmature`, shade tolerance, `shadetolerance`) and a third spatio-temporally
varying trait (species establishment probability, `establishprob`, called SEP
hereafter). The available "growing space" is calculated as the species' `maxB`
minus the occupied biomass (summed across other cohorts in the pixel). If there
is "space", a cohort can establish from one of three recruitment modes:
serotiny, resprouting and germination.
Disturbances (e.g., fire) can cause cohort mortality and trigger
post-disturbance regeneration. Two post-disturbance regeneration mechanisms have
been implemented, following LBSE: serotiny and resprouting
[@SchellerMiranda2015]. Post-disturbance mortality and regeneration only occur
in response to fire and are simulated in two separate, but interchangeable
modules, *Biomass_regeneration* and *Biomass_regenerationPM* that differ with
respect to the level of post-fire mortality they simulate (complete or partial
mortality, respectively).
Cohort germination (also called cohort establishment) occurs if seeds are
available from local sources (the pixel), or via seed dispersal. Seed dispersal
can be of three modes: 'no dispersal', 'universal dispersal' (arguably, only
interesting for dummy case studies) or 'ward dispersal' [@SchellerMiranda2015].
Briefly, the 'ward dispersal' algorithm describes a flexible kernel that
calculates the probability of a species colonising a neighbour pixel as a
function of distance from the source and dispersal-related (and invariant)
species traits, and is used by default.
Finally, both germination and regeneration success depend on the species'
probability of germination in a given pixel ([probabilities of
germination](#prob-germ)).
We refer the reader to @SchellerMiranda2015, @SchellerDomingo2011 and
@SchellerDomingo2012 for further details with respect to the above mentioned
mechanisms implemented in *Biomass_core*. In a later section of this manual, we
highlight existing [differences between *Biomass_core* and
LBSE](#biomass-core-vs-lbse), together with [comparisons between the two
modules](#biomass-core-vs-lbse-comparisons).
### Initialisation, inputs and parameters {#init-inputs-params}
To initialise and simulate forest dynamics in any given landscape,
*Biomass_core* requires a number of inputs and parameters namely:
- [initial cohort biomass and age](#initial-objs) values across the landscape;
- [invariant species traits](#invariant-traits) values;
- [spatio-temporally varying species traits](#varying-traits) values (or just
spatially-varying);
- [location- (ecolocation-) specific parameters](#ecolocation-traits);
- and the [probabilities of germination](#prob-germ) given a species' shade
tolerance and site shade.
These are detailed below and in the [full list of input objects](#inputs-list).
The *Biomass_borealDataPrep* module manual also provides information about the
estimation of many of these traits/inputs from available data, or their
adjustment using published values or our best knowledge of boreal forest
dynamics in Western Canada.
Unlike the initialisation in LBSE[^biomass_core-1], *Biomass_core* initialises
the simulation using data-derived initial cohort biomass and age. This
information is ideally supplied by data and calibration modules like
*Biomass_borealDataPrep* ([Links to other modules](#links-modules)), but
*Biomass_core* can also initialise itself using theoretical data.
Similarly, although *Biomass_core* can create all necessary traits and
parameters using theoretical values, for realistic simulations these should be
provided by data and calibration modules, like *Biomass_borealDataPrep* and
*Biomass_speciesParameters*. We advise future users and developers to become
familiar with these data modules and then try to create their own modules (or
modify existing ones) for their purpose.
[^biomass_core-1]: in LBSE the initialisation consists in "iterat[ing] the
number of time steps equal to the maximum cohort age for each site",
beginning at 0 minus *t* (*t =* oldest cohort age) and adding cohorts at the
appropriate time until the initial simulation time is reached (0)
[@SchellerMiranda2015].
#### Initial cohort biomass and age {#initial-objs}
Initial cohort biomass and age are derived from stand biomass (`biomassMap`
raster layer), stand age (`standAgeMap` raster layer) and species (ref:percent)
cover (`speciesLayers` raster layers) data (see Table
\@ref(tab:moduleInputs2-Biomass-core)) and formatted into the `cohortData`
object. The `cohortData` table is a central simulation object that tracks the
current year's cohort biomass, age, mortality (lost biomass) and aboveground net
primary productivity (ANPP) per species and pixel group (`pixelGroup`). At the
start of the simulation, `cohortData` will not have any values of cohort
mortality or ANPP.
Each `pixelGroup` is a collection of pixels that share the same ecolocation
(coded in the `ecoregionMap` raster layer) and the same cohort composition. By
default, an ecolocation is a combination of land-cover and ecological zonation
(see `ecoregionMap` in the [full list of inputs](#inputs-list)) and unique
cohort compositions are defined as unique combinations of species, age and
biomass. The `cohortData` table is therefore always associated with the current
year's `pixelGroupMap` raster layer, which provides the spatial location of all
`pixelGroups`, allowing to "spatialise" cohort information and dynamics (e.g.,
dispersal) on a pixel by pixel basis (see also
[Hashing](#biomass-core-vs-lbse-enhan2)).
The user, or another module, may provide initial `cohortData` and
`pixelGroupMap` objects to start the simulation, or the input objects necessary
to produce them: a study area polygon (`studyArea`), the `biomassMap`,
`standAgeMap`, `speciesLayers` and `ecoregionMap` raster layers (see the [list
of input objects](#inputs-list) for more detail).
#### Invariant species traits {#invariant-traits}
These are spatio-temporally constant traits that mostly influence population
dynamics (e.g., growth, mortality, dispersal) and responses to fire (fire
tolerance and regeneration).
By default, *Biomass_core* obtains trait values from available LANDIS-II tables
(see Table \@ref(tab:moduleInputs2-Biomass-core)), but traits can be
adjusted/supplied by the user or by other modules. For instance, using
*Biomass_borealDataPrep* will adjust some trait values for Western Canadian
boreal forests [e.g., longevity values are adjusted following
@BurtonCumming1995], while using *Biomass_speciesParameters* calibrates the
`growthcurve` and `mortalityshape` parameters and estimates two additional
species traits (`inflationFactor` and `mANPPproportion`) to calibrate `maxB` and
`maxANPP` (respectively).
Table \@ref(tab:invariantSpptraits) shows an example of a table of invariant
species traits. Note that *Biomass_core* (alone) requires all the columns Table
\@ref(tab:invariantSpptraits) in to be present, with the exception of
`firetolerance`, `postfireregen`, `resproutprob`, `resproutage_min` and
`resproutage_max`, which are used by the post-fire regeneration modules
(*Biomass_regeneration* and *Biomass_regenerationPM*).
Please see @SchellerDomingo2011 [p.18] and @SchellerMiranda2015 [p.16] for
further detail.
\newpage
\blandscape
```{r invariantSpptraits, echo = FALSE, eval = TRUE, message = FALSE, results = 'asis'}
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).",
" Note that these are theoretical values.")
## justify character columns to left, and numeric to right
justCols <- sapply(tab, function(x) ifelse(is.numeric(x), "right", "left"))
panble(tab, caption, landscape = TRUE, panderArgs = list("justify" = justCols),
kable_stylingArgs = list(full_width = TRUE))
```
\elandscape
#### Spatio-temporally varying species traits {#varying-traits}
These traits vary between species, by ecolocation and, potentially, by year if
the `year` column is not omitted and several years exist (in which case last
year's values up to the current simulation year are always used). They are
maximum biomass, `maxB`, maximum above-ground net primary productivity,
`maxANPP`, and species establishment probability, SEP (called `establishprob` in
the module). By default, *Biomass_core* assigns theoretical values to these
traits, and thus we recommend using *Biomass_borealDataPrep* to obtain realistic
trait values derived from data (by default, pertinent for Canadian boreal forest
applications), or passing a custom table directly. *Biomass_speciesParameters*
further calibrates `maxB` and `maxANPP` by estimating two additional invariant
species traits (`inflationFactor` and `mANPPproportion`; also for Western
Canadian forests). See Table \@ref(tab:varyingSpptraits) for an example.
```{r varyingSpptraits, echo = FALSE, eval = TRUE, message = FALSE, results = 'asis'}
tab <- read.xlsx("tables/exampleTables.xlsx", sheet = "spatially_varyingTraits",
colNames = TRUE, sep.names = " ")
caption <- paste("Example of a spatio-temporally varying species traits",
"table (the `speciesEcoregion` table object in the module), with two ecolocations",
"(called `ecoregionGroups`) and species (ref:Abie-sp),",
"(ref:Pice-eng), (ref:Pice-gla), (ref:Pinu-sp), (ref:Popu-sp) and (ref:Pseud-men).",
"If a simulation runs for 10 year using this table, trait values from",
"year 2 would be used during simulation years 2-10.")
## pander tables actually look nicer (no horizontal lines)
justCols <- sapply(tab, function(x) ifelse(is.numeric(x), "right", "left"))
panble(tab, caption, panderArgs = list("justify" = justCols),
kableArgs = list(longtable = TRUE),
kable_stylingArgs = list(full_width = TRUE))
```
#### Ecolocation-specific parameters -- minimum relative biomass {#ecolocation-traits}
Minimum relative biomass (`minRelativeB`) is the only ecolocation-specific
parameter used in *Biomass_core*. It is used to determine the shade level in
each pixel (i.e., site shade) with respect to the total potential maximum
biomass for that pixel (i.e., the sum of all `maxB` values in the pixel's
ecolocation). If relative biomass in the stand (with regards to the total
potential maximum biomass) is above the minimum relative biomass thresholds, the
pixel is assigned that threshold's site shade value [@SchellerMiranda2015].
The shade level then influences the germination and regeneration of new cohorts,
depending on their shade tolerance (see [Probabilities of
germination](#prob-germ)).
Site shade varies from X0 (no shade) to X5 (maximum shade). By default,
*Biomass_core* uses the same minimum realtive biomass threshold values across
all ecolocations, adjusted from a [publicly available LANDIS-II
table](https://github.com/dcyr/LANDIS-II_IA_generalUseFiles) to better reflect
Western Canada boreal forest dynamics (see Table \@ref(tab:minRelB)).
*Biomass_borealDataPrep* does the same adjustment by default. As with other
inputs, these values can be adjusted by using other modules or by passing
user-defined tables.
```{r minRelB, echo = FALSE, eval = TRUE, message = FALSE, results = 'asis'}
tab <- read.xlsx("tables/exampleTables.xlsx", sheet = "minRelativeB",
colNames = TRUE, sep.names = " ")
names(tab)[grep("X", names(tab))] <- ""
caption <- paste("Example of a minimum relative biomass table (the `minRelativeB`",
"table object in the module), with two ecolocations (`ecoregionGroups`) sharing",
"the same values")
justCols <- sapply(tab, function(x) ifelse(is.numeric(x), "right", "left"))
panble(tab, caption, panderArgs = list("justify" = justCols),
kable_stylingArgs = list(full_width = TRUE))
```
#### Probabilities of germination {#prob-germ}
A species' probability of germination results from the combination of its shade
tolerance level (an invariant species trait in the `species` table; Table
\@ref(tab:invariantSpptraits)) and the site shade [defined by the amount of
biomass in the pixel -- see [minimum relative biomass
parameter](#ecolocation-traits) and @SchellerMiranda2015,p.14]. By default, both
*Biomass_core* and *Biomass_borealDataPrep* use a publicly available LANDIS-II
table (called `sufficientLight` in the module; Table \@ref(tab:suffLight)).
```{r suffLight, echo = FALSE, eval = TRUE, message = FALSE, results = 'asis'}
tab <- read.xlsx("tables/exampleTables.xlsx", sheet = "probGerm",
colNames = TRUE, sep.names = " ")
tab[, 1] <- as.character(tab[, 1]) ## for alignment
caption <- paste("Default species probability of germination values used by",
"(ref:Biomass-core) and (ref:Biomass-borealdataPrep). Columns X0-X5 are different site",
"shade levels and each line has the probability of germination for each site",
"shade and species shade tolerance combination.")
justCols <- sapply(tab, function(x) ifelse(is.numeric(x), "right", "left"))
panble(tab, caption, panderArgs = list("justify" = justCols),
kable_stylingArgs = list(full_width = TRUE))
```
#### Other module inputs {#other-inputs}
The remaining module input objects either do not directly influence the basic
mechanisms implemented in *Biomass_core* (e.g., `sppColorVect` and
`studyAreaReporting` are only used for plotting purposes), are objects that keep
track of a property/process in the module (e.g., `lastReg` is a counter of the
last year when regeneration occurred), or define the study area for the
simulation (e.g., `studyArea` and `rasterToMatch`).
The next section provides a complete list of all input objects, including those
already mentioned above.
### List of input objects {#inputs-list}
All of *Biomass_core*'s input objects have (theoretical) defaults that are
produced automatically by the module[^biomass_core-2]. We suggest that new users
run *Biomass_core* by itself supplying only a `studyArea` polygon, before
attempting to supply their own or combining *Biomass_core* with other modules.
This will enable them to become familiar with all the input objects in a
theoretical setting.
[^biomass_core-2]: usually, default inputs are made when running the
`.inputObjects` function (inside the module R script) during the `simInit`
call and in the `init` event during the `spades` call -- see
`?SpaDES.core::events` and `SpaDES.core::simInit`
Of the inputs listed in Table \@ref(tab:moduleInputs2-Biomass-core), the
following are particularly important and deserve special attention:
**Spatial layers**
- `ecoregionMap` -- a raster layer with ecolocation IDs. Note that the term
"ecoregion" was inherited from LBSE and kept for consistency with original
LBSE code, but we prefer to call them ecolocations to avoid confusion with
the ecoregion-level classification of the [National Ecological
Classification of Canada
(NECC)](https://open.canada.ca/data/en/dataset/3ef8e8a9-8d05-4fea-a8bf-7f5023d2b6e1).
Ecolocations group pixels with similar biophysical conditions. By default,
we use two levels of grouping in our applications: the first level being an
ecological classification such as ecodistricts from the NECC, and the second
level is a land-cover classification. Hence, these ecolocations contain
relatively coarse scale regional information plus finer scale land cover
information. The `ecoregionMap` layer must be defined as a categorical
raster, with an associated Raster Attribute Table (RAT; see, e.g.,
`raster::ratify`). The RAT must contain the columns: `ID` (the value in the
raster layer), `ecoregion` (the first level of grouping) and
`ecoregionGroup` (the full ecolocation "name" written as
\<firstlevel_secondlevel\>). Note that if creating `ecoregionGroup`'s by
combining two raster layers whose values are numeric (as in
*Biomass_borealDataPrep*), the group label is a character combination of two
numeric grouping levels. For instance, if Natural Ecoregion `2` has
land-cover types `1`, `2` and `3`, the RAT will contain `ID = {1,2,3}`,
`ecoregion = {2}` and `ecoregionGroup = {2_1, 2_2, 2_3}`. However, the user
is free to use any groupings they wish. Finally, note that all ecolocations
(`ecoregionGroup`'s) are should be listed in the `ecoregion` table.
- `rasterToMatch` -- a RasterLayer, with a given resolution and projection
determining the pixels (i.e., non-NA values) where forest dynamics will be
simulated. Needs to match `studyArea`. If not supplied, *Biomass_core*
attempts to produce it from `studyArea`, using `biomassMap` as the template
for spatial resolution and projection.
- `studyArea` -- a `SpatialPolygonsDataFrame` with a single polygon
determining the where the simulation will take place. This is the only input
object that **must be supplied by the user or another module**.
**Species traits and other parameter tables**
- `ecoregion` -- a `data.table` listing all ecolocation "names"
(*ecoregionGroup* column; see `ecoregionMap` above for details) and their
state (active -- `yes` -- or inactive -- `no`)
- `minRelativeB` -- a `data.table` of minimum relative biomass values. See
[Ecolocation-specific parameters -- minimum relative
biomass](#ecolocation-traits).
- `species` -- a `data.table` of [invariant species
traits](#invariant-traits).
- `speciesEcoregion` -- a `data.table` of [spatio-temporally varying species
traits](#varying-traits).
- `sufficientLight` -- a `data.table` defining the probability of germination
for a species, given its `shadetolerance` level (see `species` above) and
the shade level in the pixel (see `minRelativeB` above). See [Probabilities
of germination](#prob-germ).
- `sppEquiv` -- a `data.table` of species name equivalences between various
conventions. It must contain the columns *LandR* (species IDs in the LandR
format), *EN_generic_short* (short generic species names in English -- or
any other language -- used for plotting), *Type* (type of species, *Conifer*
or *Deciduous*, as in "broadleaf") and *Leading* (same as *EN_generic_short*
but with "leading" appended -- e.g., "Poplar
leading")<!-- we should add an assertion that checks whether these columns are present early on!!! -->.
See `?LandR::sppEquivalencies_CA` for more information.
- `sppColorVect` -- character. A named vector of colours used to plot species
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
`pixelGroup` (see `pixelGroupMap` below). This table is updated during the
simulation as cohort dynamics are simulated. It must contain the following
columns:
- *pixelGroup* -- integer. *pixelGroup* ID. See
[Hashing](#biomass-core-vs-lbse-enhan2).
- *ecoregionGroup* -- character. Ecolocation names. See `ecoregionMap` and
`ecoregion` objects above.
- *speciesCode* -- character. Species ID.
- *age* -- integer. Cohort age.
- *B* -- integer. Cohort biomass of the current year in $g/m^2$.
- *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
0s in initial conditions. See "*1.1.3 Cohort growth and ageing*" section
of @SchellerMiranda2015.
- `pixelGroupMap` -- a raster layer with `pixelGroup` IDs per pixel. Pixels
are always grouped based on identical `ecoregionGroup`, `speciesCode`, `age`
and `B` composition, even if the user supplies other initial groupings
(e.g., this is possible in the *Biomass_borealDataPrep* data module).
<!-- may be revised in following versions-->
\newpage
\blandscape
```{r moduleInputs2-Biomass-core, echo = FALSE, eval = TRUE, message = FALSE, results = 'asis'}
df_inputs <- moduleInputs("Biomass_core", "..")
caption <- "List of (ref:Biomass-core) input objects and their description."
## pander's hyphenation doesn't work with URLs and big/strange words (like obj names). split manually
if (knitr::is_latex_output()) {
df_inputs$objectName <- wrapStrFun(df_inputs$objectName, size = 10)
df_inputs$objectClass <- wrapStrFun(df_inputs$objectClass, size = 10)
df_inputs$desc <- wrapStrFun(df_inputs$desc, size = 40)
df_inputs$sourceURL <- wrapStrFun(df_inputs$sourceURL, size = 10)
}
panble(df_inputs, caption, landscape = TRUE,
panderArgs = list("justify" = "left", "split.tables" = Inf, "keep.line.breaks" = TRUE),
kable_stylingArgs = list(full_width = TRUE))
```
\elandscape
### List of parameters {#params-list}
In addition to the above inputs objects, *Biomass_core* uses several
parameters[^biomass_core-3] that control aspects like the simulation length, the
"succession" time step, plotting and saving intervals, amongst others. Note that
a few of these parameters are only relevant when simulating climate effects of
cohort growth and mortality, which require also loading the `LandR.CS` R
package[^biomass_core-4] (or another similar package). These are not discussed
in detail here, since climate effects are calculated externally to
*Biomass_core* in `LandR.CS` functions and thus documented there.
A list of useful parameters and their description is listed below, while the
full set of parameters is in Table \@ref(tab:moduleParams2-Biomass-core). Like
with input objects, default values are supplied for all parameters and we
suggest the user becomes familiarized with them before attempting any changes.
We also note that the `"spin-up"` and `"biomassMap"` options for the
`initialBiomassSource` parameter are currently deactivated, since *Biomass_core*
no longer generates initial cohort biomass conditions using a spin-up based on
initial stand age like LANDIS-II (`"spin-up"`), nor does it attempt to fill
initial cohort biomasses using `biomassMap`.
**Plotting and saving**
- `.plots` -- activates/deactivates plotting and defines
type of plotting (see `?Plots`);
- `.plotInitialTime` -- defines when plotting starts;
- `.plotInterval` -- defines plotting frequency;
- `.plotMaps` -- activates/deactivates map plotting;
- `.saveInitialTime` -- defines when saving starts;
- `.saveInterval` -- defines saving frequency;
**Simulation**
- `seedingAlgorithm` -- dispersal type (see above);
- `successionTimestep` -- defines frequency of dispersal/local recruitment
event (growth and mortality are always yearly);
**Other**
- `mixedType` -- how mixed forest stands are defined;
- `vegLeadingProportion` -- relative biomass threshold to consider a species
"leading" (i.e., dominant);
\newpage
\blandscape
```{r moduleParams2-Biomass-core, echo = FALSE, eval = TRUE, message = FALSE, results = 'asis'}
df_params <- moduleParams("Biomass_core", "..")
caption <- "List of (ref:Biomass-core) parameters and their description."
panble(df_params, caption, landscape = TRUE,
panderArgs = list("justify" = "left", "digits" = 3,
"split.cells" = c(15,15, 5, 5, 5, 40), "split.tables" = Inf),
kable_stylingArgs = list(full_width = TRUE))
```
\elandscape
[^biomass_core-3]: in `SpaDES` lingo parameters are "small" objects, such as an
integer or boolean, that can be controlled via the `parameters` argument in
`simInit`.
[^biomass_core-4]: <https://github.com/ianmseddy/LandR.CS>
### List of outputs {#outputs-list}
The main outputs of *Biomass_core* are the `cohortData` and `pixelGroupMap`
containing cohort information per year (note that they are not saved by
default), visual outputs of species level biomass, age and dominance across the
landscape and the simulation length, and several maps of stand biomass,
mortality and reproductive success (i.e, new biomass) on a yearly basis.
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].
```{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,
panderArgs = list("justify" = "left",
"digits" = 3, "split.cells" = c(15, 15, 40), "split.tables" = Inf),
kable_stylingArgs = list(full_width = TRUE))
```
\elandscape
[^biomass_core-5]: see `?SpaDES.core::outputs`
### Simulation flow and module events {#sim-flow}
*Biomass_core* itself does not simulate disturbances or their effect on
vegetation (i.e., post-disturbance mortality and regeneration). Should
disturbance and post-disturbance mortality/regeneration modules be used (e.g.,
*LandMine* and *Biomass_regeneration*), the user should make sure that
post-disturbance effects occur *after* the disturbance, but *before* dispersal
and background vegetation growth and mortality (simulated in *Biomass_core*).
Hence, the disturbance itself should take place either at the very beginning or
at the very end of each simulation time step to guarantee that it happens
immediately before post-disturbance effects are calculated.
The general flow of *Biomass_core* processes with and without disturbances is:
1. Preparation of necessary objects for the simulation -- either by data and
calibration modules or by *Biomass_core* itself (during `simInit` and the
`init` event[^biomass_core-6]);
2. Disturbances (OPTIONAL) -- simulated by a disturbance module (e.g.,
*LandMine*);
3. Post-disturbance mortality/regeneration (OPTIONAL) -- simulated by a
regeneration module (e.g., *Biomass_regeneration*);
4. Seed dispersal (every `successionTimestep`; `Dispersal` event):
- seed dispersal can be a slow process and has been adapted to occur every
10 years (default `successionTimestep`). The user can set it to occur
more/less often, with the caveat that if using *Biomass_borealDataPrep*
to estimate species establishment probabilities, these values are
integrated over 10 years.
- see @SchellerDomingo2012 for details on dispersal algorithms.
5. Growth and mortality (`mortalityAndGrowth` event):
- unlike dispersal, growth and mortality always occur time step (year).
- see @SchellerMladenoff2004 for further detail.
6. Cohort age binning (every `successionTimestep`; `cohortAgeReclassification`
event):
- follows the same frequency as dispersal, collapsing cohorts (i.e.,
summing their biomass/mortality/aNPP) to ages classes with resolution
equal to `successionTimestep`.
- see @SchellerMiranda2015 for further detail.
7. Summary tables of regeneration (`summaryRegen` event), biomass, age, growth
and mortality (`summaryBGM` event);
8. Plots of maps (`plotMaps` event) and averages (`plotAvgs` and
`plotSummaryBySpecies` events);
9. Save outputs (`save` event).
... (repeat 2-9) ...
[^biomass_core-6]: `simInit` is a `SpaDES` function that initialises the
execution of one or more modules by parsing and checking their code and
executing the `.inputObjects` function(s), where the developer provides
mechanisms to satisfy each module's expected inputs with default values.
### Differences between *Biomass_core* and the LANDIS-II Biomass Succession Extension model (LBSE) {#biomass-core-vs-lbse}
#### Algorithm changes {#biomass-core-vs-lbse-algo}
Upon porting LBSE into R, we made six minor modifications to the original
model's algorithms to better reflect ecological processes. This did not
significantly alter the simulation outputs and we note that these changes might
also have been implemented in more recent versions of LBSE.
First, for each year and community (i.e., 'pixel group' in *Biomass_core*, see
below), LBSE calculates the competition index for a cohort sequentially (i.e.,
one cohort at a time) after updating the growth and mortality of other cohorts
(i.e., their biomass gain and loss, respectively) , and with the calculation
sequence following cohort age in descending order, but no explicit order of
species. This sorting of growth and mortality calculations from oldest to
youngest cohorts in LBSE was aimed at capturing size-asymmetric competition
between cohorts, under the assumption that older cohorts have priority for
growing space given their greater height (Scheller pers. comm.). We felt that
within-year sequential growth, death and recruitment may be not ecologically
accurate, and that the size-asymmetric competition was being accounted for
twice, as the calculation of the competition index already considers the
competitive advantage of older cohorts [as shown in the User's Guide,
@SchellerMiranda2015]. Hence, in *Biomass_core* growth, mortality, recruitment
and the competition index are calculated at the same time across all cohorts and
species.
Second, the unknown species-level sorting mechanism contained within LBSE (which
changed depending on the species order in the input species list file), led to
different simulation results depending on the input species list file (e.g.,
Table \@ref(tab:tableLBSEtest1) and Fig. \@ref(fig:figLBSEtest1)). The
calculation of competition, growth and mortality for all cohorts at the same
time also circumvented this issue.
```{r figLBSEtest1, echo = FALSE, eval = TRUE, out.width = "60%", fig.align = 'center', fig.cap = "Differences in total landscape aboveground biomass when using two different input species orders for the same community. These simulations demonstrate how the sequential calculation of the competition index, combined with a lack of explicit species ordering affect the overall landscape aboveground biomass in time when using different input species orders (see Table \\@ref(tab:tableLBSEtest1)). In order to prevent differences introduced by cohort recruitment, species’ ages at sexual maturity were changed to the species’ longevity values, and the simulation ran for 75 years to prevent any cohorts from reaching sexual maturity. The bottom panel shows the difference between the two simulations in percentage, calculated as $\\frac{Biomass_{order2} - Biomass_{order1}}{Biomass_{order2}} * 100$"}
knitr::include_graphics(normPath("figures/figLBSEtest1.png"))
```
Third, in LBSE the calculation of total pixel biomass for the purpose of
calculating the initial biomass of a new cohort included the (previously
calculated) biomass of other new cohorts when succession time step = 1, but not
when time step was \> 1. This does not reflect the documentation in the User's
Guide, which stated that "*Bsum [total pixel biomass] is the current total
biomass for the site (not including other new cohorts)*"
[@SchellerMiranda2015,p. 4], when the succession time step was set to 1.
Additionally, together with the lack of explicit ordering, this generated
different results in terms of the biomass assigned to each new cohort (e.g.,
Table \@ref(tab:tableLBSEtest2) and Fig. \@ref(fig:figLBSEtest2)). In
*Biomass_core* the initial biomass of new cohorts is no longer calculated
sequentially (as with competition, growth and mortality), and thus the biomass
of new cohorts is never included in the calculation of total pixel biomass.
```{r figLBSEtest2, echo = FALSE, eval = TRUE, out.width = "60%", fig.align = 'center', fig.cap = "Differences in the biomass assigned to new cohorts, summed for each species across pixels, when using two different input species orders for the same community and when the succession time step is 1. These simulations demonstrate how the different summation of total cohort biomass for a succession time step of 1 and the lack of explicit species ordering affect simulation results when changing the species order in the input file (see Table \\@ref(tab:tableLBSEtest2)). Here, initial cohort ages were also set to 1. Values refer to the initial total biomass attributed to each species at the end of year 1."}
knitr::include_graphics(normPath("figures/figLBSEtest2.png"))
```
Fourth, in LBSE, serotiny and resprouting could not occur in the same pixel
following a fire, with serotiny taking precedence if activated. We understand
that this provides an advantage to serotinous species, which could perhaps be
disadvantaged with respect to fast-growing resprouters. However, we feel that it
is ecologically more realistic that serotinous and resprouter species be able to
both regenerate in a given pixel following a fire and allow the competition
between serotinous and resprouting species to arise from species traits. Note
that this change was implemented in the *Biomass_regeneration* and
*Biomass_regenerationPM* modules, since post-disturbance effects were separated
background vegetation dynamics simulated by *Biomass_core*.
Fifth, in *Biomass_core*, species shade tolerance values can have decimal values
to allow for finer adjustments of between-species competition.
Sixth, we added a new parameter called `minCohortBiomass`, that allows the user
to control cohort removal bellow a certain threshold of biomass. In some
simulation set-ups, we noticed that *Biomass_core* (and LBSE) were able to
generate many very small cohorts in the understory that, due to cohort
competition, were not able to gain biomass and grow. However, because
competition decreases growth but does not increase mortality, these cohorts
survived at very low biomass levels until they reached sufficient age to suffer
age-related mortality. We felt this is unlikely to be realistic in many cases.
By default, this parameter is left at 0 to follow LBSE behaviour (i.e., no
cohorts removal based on minimum biomass).
#### Other enhancements {#biomass-core-vs-lbse-enhan}
In addition to the sixth changes in growth, mortality and regeneration mentioned
above, we enhanced modularity by separating the components that govern
vegetation responses to disturbances from *Biomass_core*, and implemented
hashing, caching and testing to improve computational efficiency and insure
performance.
##### Modularity {#biomass-core-vs-lbse-enhan1}
Unlike in LBSE, post-disturbance effects are not part of *Biomass_core* *per
se*, but belong to two separate modules, used interchangeably
([*Biomass_regeneration*](https://github.com/PredictiveEcology/Biomass_regeneration/blob/master/Biomass_regeneration.Rmd)
and
[*Biomass_regenerationPM*](https://github.com/PredictiveEcology/Biomass_regenerationPM/blob/master/Biomass_regenerationPM.Rmd)).
These need to be loaded and added to the "modules folder" of the project in case
the user wants to simulate forest responses to disturbances (only fire
disturbances at the moment). Again, this enables higher flexibility when
swapping between different approaches to regeneration.
Climate effects on growth and mortality were also implemented a modular way. The
effects of climate on biomass increase (growth) and loss (mortality) were
written in functions grouped in two packages. The `LandR` R package contains
default, "non-climate-sensitive" functions, while the `LandR.CS` R package
contains the functions that simulate climate effects (CS stands for "climate
sensitive"). Note that these functions do not simulate actual growth/mortality
processes, but estimate modifiers that increase/decrease cohort biomass on top
of background growth/mortality. *Biomass_core* uses the `LandR` functions by
default (see `growthAndMortalityDrivers` parameter in the [full parameters
list](#params-list)). Should the user wish to change how climate effects on
growth/mortality are calculated, they can provide new compatible functions
(i.e., with the same names, inputs and outputs) via another R package.
##### Hashing {#biomass-core-vs-lbse-enhan2}
Our first strategy to improve simulation efficiency in *Biomass_core* was to use
a hashing mechanism [@YangEtAl2011]. Instead of assigning a key to each pixel in
a raster and tracking the simulation for each pixel in a lookup table, we
indexed pixels using a *pixelGroup* key that contained unique combinations of
ecolocation and community composition (i.e., species, age and biomass
composition), and tracked and stored simulation data for each *pixelGroup* (Fig.
\@ref(fig:figLBSEtest3)). This algorithm was able to ease the computational
burden by significantly reducing the size of the lookup table and speeding-up
the simulation process. After recruitment and disturbance events, pixels are
rehashed into new pixel groups.
```{r figLBSEtest3, echo = FALSE, eval = TRUE, out.width = "75%", fig.align = 'center', fig.cap = "Hashing design for (ref:Biomass-core). In the re-coded (ref:Biomass-core), the pixel group map was hashed based on the unique combination of species composition ('community map') and ecolocation map, and associated with a lookup table. The insert in the top-right corner was the original design that linked the map to the lookup table by pixel key."}
knitr::include_graphics(normPath("figures/figLBSEtest3.png"))
```
##### Caching {#biomass-core-vs-lbse-enhan3}
The second strategy aimed at improving model efficacy was the implementation of
caching during data-driven parametrisation and initialisation. Caching
automatically archives outputs of a given function to disk (or memory) and reads
them back when subsequent calls of this function are given identical inputs. All
caching operations were achieved using the `reproducible` R package
[@McIntireChubaty2020].
In the current version of *Biomass_core*, the spin-up phase was replaced by
data-driven landscape initialisation and many model parameters were derived from
data, using data and calibration modules (e.g., *Biomass_borealDataPrep*). To
avoid having to repeat data downloads and treatment, statistical estimation of
parameters and landscape initialisation every time the simulation is re-run
under the same conditions, many of these pre-simulation steps are automatically
cached. This means that the pre-simulation phase is significantly faster upon a
second call when inputs have not changed (e.g., the input data and
parametrisation methods), and when inputs do change only directly affected steps
are re-run (see main text for examples). When not using data modules,
*Biomass_core* still relies on caching for the preparation of its theoretical
inputs.
##### Testing {#biomass-core-vs-lbse-enhan4}
Finally, we implemented code testing to facilitate bug detection by comparing
the outputs of functions (etc.) to expected outputs [@Wickham2011]. We built and
integrated code tests in *Biomass_core* and across all LandR modules and the
`LandR` R package <!-- package name may change --> in the form of assertions,
unit tests and integration tests. Assertions and unit tests are run
automatically during simulations (but can be turned off) and evaluate individual
code components (e.g., one function or an object's class). Integration tests
evaluate if several coded processes are integrated correctly and are usually run
manually. However, because we embedded assertions within the module code, R
package dependencies of *Biomass_core*, such as the `LandR` R package
<!-- package name may change --> and `SpaDES`, they also provide a means to test
module integration. We also implemented GitHub Actions continuous integration
(CI), which routinely test GitHub hosted packages (e.g., `LandR`) and modules.
CRAN-hosted packages (e.g., `SpaDES`) are also automatically tested and checked
on CRAN.
Finally, because *Biomass_core* (and all other LandR modules) code is hosted in
public GitHub repositories, the module code is subject to the scrutiny of
many users, who can identify issues and contribute to improve module code.
#### Performance and accuracy of *Biomass_core* with respect to LBSE {#biomass-core-vs-lbse-comparisons}
In the recoding of *Biomass_core*, we used integration tests to ensured similar
outputs of each demographic process (namely, growth, mortality and recruitment)
to the outputs from its counterpart in LBSE. Here, we report the
comparisons of the overall simulation (i.e., including all demographic