landisutils

Tools and utilities for preparing data for and running LANDIS-II simulations, and post-processing their outputs.

1. prepare data in R and convert to LANDIS-II-compatible formats;
2. programmatically create and write LANDIS-II extension input files;
3. programmatically create and write LANDIS-II scenario and other simulation files;
4. extraction of data from output logs;
5. other post-processing tools;

[!NOTE] This package is a work in progress. Testing, feedback and help are greatly appreciated!

The list of supported LANDIS-II extensions tracks the official v8 extension list. Tables below are grouped by extension type and sorted alphabetically; use the file outline (top-right on github.com) to jump between sections.

Succession extensions

LANDIS-II extension name	landisutils class
🌳 Biomass Succession	BiomassSuccession
🌱 DGS Succession	DGSSuccession
♻️ Forest Carbon Succession (ForCS)	ForCS
🍂 NECN Succession	NECNSuccession
☀️ PnET Succession	PnETSuccession

Disturbance extensions

LANDIS-II extension name	landisutils class
🔥 BFOLDS Fire	coming soon
🦌 Biomass Browse	BiomassBrowse 1
🪓 Biomass Harvest	BiomassHarvest
🪲 Climate Biological Disturbance Agents	ClimateBDA
🪵 Dynamic Biomass Fuel System	DynamicFuels
🔥 Dynamic Fire System	DynamicFire
🦠 Epidemiological Disturbance Agents	EDA
🌀 Hurricanes	Hurricane
🗺️ Land Use Plus	LandUsePlus
🌪️ Linear Wind

Other extensions

LANDIS-II extension name	landisutils class
🌐 Biomass Community Output	OutputBiomassCommunity
📊 Biomass Output	OutputBiomass
🗂️ Biomass Reclassification Output	OutputBiomassReclass
📅 Biomass-by-Age Output	OutputBiomassByAge
📈 Cohort Statistics Output	OutputCohortStats
📦 Forest Product Sector	coming soon
🛣️ Forest Road Simulator	ForestRoadsSimulation
🏞️ Landscape Habitat Output	OutputLandscapeHabitat
🐿️ Local Habitat Suitability Output	OutputLocalHabitat
🕰️ Maximum Species Age Output

Installation

You can install the development version of landisutils like so:

remotes::install_github("FOR-CAST/landisutils")

Preparing data

Use prep*() functions to convert input data to LANDIS-II data formats or auxiliary config files.

## e.g., to prepare the initial communities .csv and raster files
init_comm_files <- prepInitialCommunities(cohortData, pixelGroupMap, tmp_pth)

Creating LANDIS-II input files

For any of the supported extensions, use new() method to create an object which can be used to produce configuration files. The configuration can be defined all at once, or built up in sequence, or modified to produce alternate configurations. If producing several configurations, be sure to update the path for each configuration to ensure they will not be overwritten.

## e.g., to prepare Biomass Succession inputs
ext_biomass_succession <- BiomassSuccession$new(
  path = tmp_pth,
  Timestep = 10,
  SeedingAlgorithm = "WardSeedDispersal",
  InitialCommunitiesFiles = init_comm_files,
  ClimateConfigFile = clim_file,
  CalibrateMode = NULL, ## optional
  SpinupCohorts = FALSE, ## optional; v7.1
  SpinupMortalityFraction = 0.05, ## v7.1
  MinRelativeBiomass = min_rel_b,
  SufficientLight = suff_light,
  SpeciesDataFile = spp_file,
  EcoregionParameters = erp_df,
  SpeciesEcoregionDataFile = spperd_file,
  FireReductionParameters = frp_df,
  HarvestReductionParameters = hrp_df
)

Once your configuration is ready to write to disk for use with LANDIS-II:

## show files associated with this configuration
ext_biomass_succession$files

## write the main extension configuration / input file
ext_biomass_succession$write()

Manual file creation (advanced use)

Use insert*() functions when generating LANDIS-II input text files manually.

insertInitialCommunities(init_comm_files)

Creating LANDIS-II scenario files

Use scenario() to construct scenario files:

## other extensions can be added to be run once created per above
scenario(
  cell_length = 250,
  duration = 200,
  extensions = list(
    succession = list(ext_biomass_succession),
    disturbance = list(),
    other = list()
  ),
  name = "my_scenario_a",
  path = file.path("path", "to", "project")
)

Working with simulation outputs

Coming soon!

Footnotes

1. Not yet updated by the LANDIS-II developers for LANDIS-II v8; the most recent upstream release targets the v7 core only. The landisutils R6 class tracks the latest published input-file schema (Biomass Browse v2.0, Root Rot v1.0), but $write()-produced files cannot currently be run through a LANDIS-II v8 console. Constructing one of these objects emits a one-time warning() to make this explicit. ↩ ↩²