Skip to main content

LandWeb Manual: v. 3.0.0

2 Running LandWeb

  1. Launch Rstudio and open the LandWeb Rstudio project (LandWeb.Rproj);

Be sure to use R 4.2.3 when running the model!

If using rig to manage multiple R versions, use the following to launch Rstudio with the correct version of R:

cd ~/GitHub/LandWeb
rig rstudio renv.lock
  1. Open the file 00-global.R and run each line in sequence, responding to any prompts as required.

Before you can run the model, ensure that all necessary package versions are installed by restoring from the project’s snapshot file.

options(
  renv.config.mran.enabled = FALSE,
  renv.config.pak.enabled = FALSE
)
renv::restore()

2.1 Model setup and configuration

The default settings for study area, model version, and scenario are defined in 01a-globalvars.R. These defaults are defined as ‘dot-variables’ (e.g., .studyAreaName) and can be set externally to the main script (e.g., if .studyAreaName is defined before running 01a-globalvars.R, then the user-set value will be used, rather than the default defined in that script).

Advanced setup and model run customization is described in Advanced setup.

2.1.1 Select a study area

The model can be run over the entire study area, for certain individual provinces (currently only AB, SK, MB, NWT), or groups of predefined FMAs (see Fig. 1 and Table 1).

2.1.1.1 FMA boundaries

Currently, only a subset of the FMAs within the LandWeb study area are predefined to be run on their own (i.e., without needing to run the model over the entire study area; see Table 2).

Table 2.1: FMA polygon IDs (from Figure 1) and their corresponding FMA names.
ID Name
1 Cranbrook
2 Fort Nelson
3 Mackenzie
4 Prince George
5 Fort St. John
6 Dawson Creek
7 Island Forests
8 Turtleford
9 Prince Albert
10 Kelvington
11 Island Forests
12 Northern Reconnaisance
13 Turnor East
14 Turnor West
15 Mistik
16 Mee-Toos
17 Kitsaki Zelensky
18 Nemeiben
19 Meadow Lake Fringe
20 Suggi Lowlands
21 Pasquia-Porcupine
22 Meadow Lake OSB
23 L M Wood Products
24 North West
25 Prince Albert FMA
26 Island Forests
27 Island Forests
28 Island Forests
29 Island Forests
30 Spiritwood
31 INTERLAKE
32 Mountain
33 SASKATCHEWAN RIVER
34 Cranbrook
35 Cranbrook
36 Cranbrook
37 Cranbrook
38 ALPAC Forest Products Incorporated
39 ANC Timber Ltd.
40 Blue Ridge Lumber Inc.
41 Canadian Forest Products Ltd.
42 Daishowa-Marubeni International Ltd. (East)
43 Daishowa-Marubeni International Ltd. (West)
44 West Fraser Mills Ltd. and Tolko Industries Ltd.
45 Manning Diversified Forest Products Ltd.
46 Millar Western Forest Products Ltd.
47 Spray Lake Sawmills (1980) Ltd.
48 Sundre Forest Products Inc.
49 Tolko Industries Ltd. (High Prairie)
50 Tolko Industries Ltd., Footner Forest Products Ltd. and La Crete Sawmills Ltd.
51 Tolko Industries Ltd., Vanderwell Contractors (1971) Ltd. and West Fraser Mills Ltd. (Slave Lake)
52 Vanderwell Contractors (1971) Ltd.
53 West Fraser Mills Ltd. (Edson)
54 West Fraser Mills Ltd. (Hinton)
55 West Fraser Mills Ltd. (Slave Lake)
56 Weyerhaeuser Company Limited (Grande Prairie)
57 Weyerhaeuser Company Limited (Pembina Timberland)
58 Fort Providence
59 Fort Resolution

2.1.1.2 Choosing a study area

The model can be run on any of several pre-defined study areas summarized in the table below. To select one of these predefined study areas, set .studyAreaName to use one of the following, corresponding to the polygon IDs in the map above.

Table 2.2: Model study areas with corresponding FMA polygon IDs (from Figure 1).
studyAreaName ID Description
ANC 39 ANC Timber Ltd.
Blueridge 40 Blueridge Lumber Inc.
DMI 42, 43 Mercer Peace River Pulp Ltd. (formerly DMI)
Edson 53 West Fraser Mills Ltd. (Edson)
FMANWT 59 Fort Resolution
FMANWT2 58 Fort Providence
LP_BC 5, 6 Lousiana Pacific (British Columbia)
LP_MB 32 Lousiana Pacific (Manitoba)
Manning 45 Manning Diversified Forest Products Ltd.
MillarWestern 46 Millar Western Forest Products Ltd.
Mistik 15 Mistik
MPR 42, 43 Mercer Peace River Pulp Ltd. (formerly DMI)
Sundre 48 Sundre Forest Products Inc.
Tolko_AB_N 50 Tolko Industries Ltd. (Alberta North)
Tolko_AB_S 44, 49, 51 Tolko Industries Ltd. (Alberta South)
Tolko_SK 22 Tolko (Saskatchewan)
Vanderwell 51, 52 Vanderwell Contractors (1971) Ltd.
WestFraser_N 44, 51, 55 West Fraser Mills Ltd. (Slave Lake)
WestFraser_S 53, 54 West Fraser Mills Ltd. (Edson + Hinton)
WeyCo_GP 56 Weyerhauser Company Ltd. (Grand Prairie)
WeyCo_PT 57 Weyerhauser Company Ltd. (Pembina Timberland)
WeyCo_SK 21 Weyerhauser Company Ltd. (Pasquia-Porcupine)

To run an entire province use one of "provAB", "provMB", "provNWT", or "provSK".

To run the entire LandWeb study area, use "LandWeb_full".

To run on a small test area use "random".

2.1.2 Select a scenario

In version 2.0.0 of the LandWeb model, seed dispersal distances needed to be adjusted to ensure sufficient regeneration following fire. These adjustments cause the model to behave more like a state-transition model, rather than a process-based one.

Version 3.0.0 relaxes these parameter forcings to behave like the standard LANDIS-II model.

The dispersal scenario is principally set via .version but can be overridden is set via .dispersalType:

Dispersal Scenario Description
default (v3) default LANDIS-II dispersal
aspen limit seed dispersal to deciduous only
high (v2) high seed dispersal of all species (used for v2.0.0 runs)
none no seed dispersal (all species)

Additionally, v2.0.0 of the model uses adjusted fire return intervals (FRI) and log-adjusted rates of spread (ROS). Version 3.0.0 uses the LandMine defaults.

The fire scenario is principally set via .version but can be overridden by specifying .ROStype:

Fire Scenario Description
default (v3) default rate of spread values
burny Increases the flammability of non-forest types to facilitate fire spread in landscapes with discontinuous fuels.
equal Set all rates of fire spread equal to each other (no vegetation differences)
log (v2) Reduce the rates of spread but keep the magnitude of vegetation differences

To define a scenario to run, select one dispersal scenario and one fire scenario from the tables above. All LandWeb v2.0.0 runs from 2019 were run using .dispersalType = "high" and .ROStype = "log". Using v3.0.0 of the model, .dispersalType = "default" and .ROStype = "default".

2.1.3 Replication

To run multiple replicates of a given run, set .rep to an integer corresponding to the replicate id. All replicate runs use a different random seed, and this seed is saved as on output for reuse in the event that a replicate needs to be rerun. To rerun a replicate using a different seed, be sure to delete that run’s seed.rds file. The seed used is also saved in human-readable seed.txt file.

2.2 Running the model

NOTE: The first time the model is run, it will automatically download additional data and install additional R packages, which can take some time to complete.

Due to a server configuration problem, the following national ecolocation polygons should be downloaded manually to the inputs/ directory:

2.2.1 Interactive R session

When working in an R session, be sure to set the working directory to the LandWeb project directory. The first time running the model, open the file 00-global.R, and step through each line to ensure any prompts etc. are answered correctly.

.mode <- "development"
.studyAreaName <- "random"
.rep <- 1L
.version <- 2

source("00-global.R")

When authenticating with Google Drive, be sure to check the box to allow access to files.

2.2.2 Commandline interface

In addition to running the model in an interactive R session, we provide a command line interface to run replicates of the model for the study areas defined above (i.e., batch mode).

For example, to run replicate number 7 of the model at \(250 m\) resolution using FRI multiple of \(1\) for Alberta FMU L11, use:

cd ~/GitHub/LandWeb

## ./run_fmu.sh <FMU> <FRI> <RES> <REP>
./run_fmu.sh L11 1 250 7

FMU command line runs do not use modified dispersal nor fire scenarios, and thus only require the study area, replicate, and FRI multiple to be defined.

To run replicate number 7 of the model for the entire province of Alberta, use:

cd ~/GitHub/LandWeb

## ./run_fma.sh <FMU> <REP>
./run_fma.sh provAB 7
# ./run_fma_win.sh provAB 7 ## if on Windows!

FMA command line runs use highDispersal_logROS scenarios at \(250 m\) resolution, and thus only require the study area and replicate to be defined.

To run the entire LandWeb study area, only a replicate number needs to be passed. For example:

## ./run_landweb.sh <REP>
./run_landweb.sh 7

LandWeb command line run set the dispersal and fire scenarios as above, and the pixel resolution (.pixelSize) at \(250 m\), and thus only require the study area and replicate to be defined.

2.3 Post-processing analyses

After having run several reps of the model on a given study area, results are combined in subsequent post-processing analyses to generate the following outputs for each set of reporting polygons within the study area:

  • boxplots of leading vegetation cover;
  • histograms of leading vegetation cover;
  • histograms of large patches.

To run processing, use .mode = "postprocess" and be sure to set the number of replicates run in the config.

2.4 Advanced setup

2.4.1 Customizing model run configuration

See box/landweb.R file, and 02a-user-config.R.

(TODO)

2.4.2 Cache backend

Simulation caching is provided by the reproducible and SpaDES.core packages, and is enabled by default.

The default cache uses a SQLite database backend and stores cache files in cache/. However, other database backends can also be used, and advanced users running multiple parallel simulations may wish to set up and use a PostgreSQL database for this cache.

See https://github.com/PredictiveEcology/SpaDES/wiki/Using-alternate-database-backends-for-Cache and ensure the following options are added to your user-specific config in 02a-user-config.R:

reproducible.cacheSaveFormat = "qs",
reproducible.conn = SpaDES.config::dbConnCache("postgresql"),

2.4.3 Speeding up disk-based operations

Caching and other disk-based file operations benefit from using an solid state drive (SSD) instead of a conventional spinning hard drive. Advanced users can move their cache/ directory to an SSD mountpoint and create a symlink to this location in the project directory. Likewise, users can configure a scratch path for temporary raster file operations to point to an SSD location.

2.5 Additional Resources

Debugging in R and Rstudio:

Resources for (re)learning R and spatial data: