Skip to content

Latest commit

 

History

History
428 lines (395 loc) · 21.7 KB

fireSense_dataPrepPredict.md

File metadata and controls

428 lines (395 loc) · 21.7 KB
title fireSense_dataPrepPredict Manual
subtitle v.1.1.0
date Last updated: 2026-10-07
output
bookdown::html_document2
toc toc_float theme number_sections df_print keep_md
true
true
sandstone
false
paged
true
editor_options
chunk_output_type
console
bibliography citations/references_fireSense_dataPrepPredict.bib
link-citations true
always_allow_html true

fireSense_dataPrepPredict Module

(ref:fireSense-dataPrepPredict) fireSense_dataPrepPredict

made-with-Markdown

Authors:

Ian Eddy ian.eddy@nrcan-rncan.gc.ca [aut, cre], Eliot McIntire eliot.mcintire@nrcan-rncan.gc.ca [aut], Alex M Chubaty achubaty@for-cast.ca [ctb]

Module Overview

Module summary

Prepares, each year, the covariate tables that the fireSense [@Marchal:2017a; @Marchal:2017b; @Marchal:2019] predict modules use:

  • fireSense_igAndEscapePred_Covariates for fireSense_ignitionPredict (ignition and escape): fuel classes, non-forest landcover, youngAge, ignition climate and lightning days, aggregated by igAggFactor.
  • fireSense_SpreadCovariates for fireSense_spreadPredict: the same fuel, landcover and youngAge columns plus spread climate, at the resolution of flammableRTM.

Fuel classes come from cohortData and pixelGroupMap, grouped by the fuelClassCol column of sppEquiv. The covariates are built by the same fireSenseUtils functions that fireSense_dataPrepFit uses, so they match the fitted models.

Module inputs and parameters

cohortData, pixelGroupMap and rstCurrentBurn come from the vegetation and fire modules during the simulation. sppEquiv, nonForestedLCCGroups, missingLCCgroup, lightningMaps, flammableRTM and landcoverDT should be the ones used by fireSense_dataPrepFit. Climate is either currentClimateRasters, or projectedClimateRasters with layers named year<year>. igAggFactor is overwritten in init with the value set in the other modules.

Table @ref(tab:moduleInputs-fireSense-dataPrepPredict) shows the full list of module inputs.

(\#tab:moduleInputs-fireSense-dataPrepPredict)(\#tab:moduleInputs-fireSense-dataPrepPredict)List of (ref:fireSense-dataPrepPredict) input objects and their description.
objectName objectClass desc sourceURL
.ELFind character The simulated ELF (from `fireSense_ELFs`), the `polygonID` of its row in `studyAreaWithSpreadParams`. Unsupplied: the rows are used as they are. NA
climateVariablesForFire list Named list (`ignition`, `spread`) of the layer names in `currentClimateRasters` used by each process. A length-one list is used for both. Default is 'MDC' for both. NA
climateYear numeric Optional year (e.g. 2009) used instead of `time(sim)` to build `currentClimateRasters`. See PredictiveEcology/climateYear. NA
currentClimateRasters SpatRaster Climate layers for the current year, one layer per climate variable. If absent, built from `projectedClimateRasters`. NA
cohortData data.table Cohorts by `pixelGroup` (LandR). NA
missingLCCgroup character Forested pixels that are absent from `cohortData` are assigned to this class. Must be one of the names of `nonForestedLCCGroups`. NA
flammableRTM SpatRaster Binary raster of flammable pixels at `start(sim)`. If absent, derived from the default landcover and `nonflammableLCC`. NA
nonForestedLCCGroups list Named list of non-forested landcover groups, e.g. `list('wetland' = c(19, 23, 32))`. Only used if `landcoverDT` is not supplied. NA
lightningMaps SpatRaster Lightning layers: lightningDays, lightningDensity, positiveCG, positiveCGdensity. Only `lightningDays` is used. NA
pixelGroupMap SpatRaster Map of the `pixelGroup`s in `cohortData`. NA
projectedClimateRasters list Named list (one element per climate variable) of SpatRasters whose layers are named 'year<year>'. Only used if `currentClimateRasters` is not supplied. NA
rasterToMatch SpatRaster Template raster for the study area. NA
rasterToMatchLargeELF SpatRaster From `fireSense_ELFs`. A neighbour ELF is blended (`blendNeighbourELFs`) only if this raster labels its pixels, which is how `fireSense_spreadPredict` weights each ELF. NA
rstCurrentBurn SpatRaster Binary raster with 1 where the pixel burned this year. NA
rstLCC_RTM SpatRaster Landcover raster, only used if `landcoverDT` is not supplied. Defaults to the last layer of `rstLCCs`, else NTEMS landcover for `dataYear`. NA
rstLCCs list Optional named list of landcover `SpatRaster`s, one per data year, as produced by `fireSense_dataPrepFit`. If supplied, the last element is used as `rstLCC_RTM`. NA
sppEquivs list Only with several fitted ELFs: one `sppEquiv` per ELF, from `fireSense_dataPrepFit`. Each ELF's fuel covariates are made with its own, for every pixel. NA
nonForestedLCCGroupsList list Only with several fitted ELFs: one `nonForestedLCCGroups` per ELF, in the order of `sppEquivs`. NA
missingLCCgroupList list Only with several fitted ELFs: one `missingLCCgroup` per ELF, in the order of `sppEquivs`. NA
sppEquiv data.table Table of LandR species equivalencies; must have columns `sppEquivCol` and `fuelClassCol`. NA
studyAreaWithSpreadParams sf The fitted SpreadFit ledger rows (from `fireSense_ELFs`; also read, undeclared, by `fireSense_spreadPredict`), one row per fitted ELF, matched to `sppEquivs` by `polygonID` when `sppEquivs` is named (as `fireSense_dataPrepFit` makes it), else by order. With `.ELFind`, reduced to the simulated ELF's row and the neighbours `blendNeighbourELFs` keeps (see `createsOutput`). Each row's `params[[1]]` column names are the fitted formula's terms: an ELF whose terms include `dom_agb_<class>`/`sec_agb_<class>` predicts with those classes' AGB columns, matching what that ELF was fitted with; otherwise (an older, per-species fit) with the previous one-column-per-fuel-class covariates. Unsupplied: every ELF predicts per-fuel-class, as before this was read. NA
standAgeMap SpatRaster Stand age (years) at `start(sim)`. NA
studyArea SpatVector Polygon of the study area. The fire polygons, land cover and stand age made in `.inputObjects` are masked to it. NA
landcoverDT data.table `pixelID` plus one binary column per non-forest landcover group, for flammable pixels, at `start(sim)`. NA

Summary of user-visible parameters (Table @ref(tab:moduleParams-fireSense-dataPrepPredict))

(\#tab:moduleParams-fireSense-dataPrepPredict)(\#tab:moduleParams-fireSense-dataPrepPredict)List of (ref:fireSense-dataPrepPredict) parameters and their description.
paramName paramClass default min max paramDesc
blendNeighbourELFs logical TRUE NA NA `sim$studyAreaWithSpreadParams` holds every ledger row whose polygon touches the study area: the simulated ELF (`sim$.ELFind`) and its neighbours. `FALSE` keeps only the simulated ELF's row. `TRUE` also keeps each neighbour that `fireSense_spreadPredict` can blend: fitted with the current fuel covariates, labelled in `sim$rasterToMatchLargeELF` and with its own `sppEquivs`, `nonForestedLCCGroupsList` and `missingLCCgroupList` entries; any other neighbour is dropped with a warning. A single-ELF run's `rasterToMatchLargeELF` labels no neighbour, so there `TRUE` keeps only the simulated ELF's row too.
cutoffForYoungAge numeric 15 NA NA Age at and below which pixels are considered 'young' (i.e., `age <= cutoffForYoungAge`).
dataYear numeric 2011 1985 2022 Year of the default landcover and stand age maps, and last year of the fires used to initialise `nonForest_timeSinceDisturbance`.
fireTimeStep numeric 1 NA NA Interval between events of this module, in years.
forestedLCC numeric 81, 210,.... NA NA Forested landcover classes in `rstLCC_RTM`. Only used if `landcoverDT` is not supplied.
flammabilityThreshold numeric 0.1 0 1 Minimum proportion of flammable pixels for an upscaled pixel to be flammable, when building the default landcover.
fuelClassCol character FuelClass NA NA Column of `sppEquiv` that defines the fuel classes, for both ignition and spread.
igAggFactor numeric 4 1 NA Aggregation factor for the ignition and escape covariates. Overwritten in `init` by the value set in other modules.
nonflammableLCC numeric 0, 20, 3.... NA NA Non-flammable landcover classes, used to create `flammableRTM` and the default landcover if not supplied. The default, `fireSenseUtils::fireSenseNonflammableLCC`, is no data, water, rock, snow/ice and barren land.
nonForestCanBeYoungAge logical TRUE NA NA Should burned non-forest pixels be `youngAge` until `cutoffForYoungAge`?
scanfiVersion character V3 NA NA SCANFI land-cover version for non-forest land cover, when this module builds its own landcover (only used if `rstLCC_RTM`/`rstLCCs` is not supplied).
sppEquivCol character LandR NA NA Column of `sppEquiv` with the species names used in `cohortData`.
whichModulesToPrepare character fireSens.... NA NA Predict modules to prepare covariates for: `fireSense_ignitionPredict` for the ignition/escape table, `fireSense_spreadPredict` for the spread table. Defaults to both.
.runInitialTime numeric 0 NA NA Time of the first climate and covariate preparation events.
.studyAreaName character NA NA NA Human-readable name for the study area used.
.useCache logical FALSE NA NA Should this entire module be run with caching activated? This is generally intended for data-type modules, where stochasticity and time are not relevant

Events

All events after init, except save, repeat every fireTimeStep years.

  • init: aligns standAgeMap and rstLCC_RTM to rasterToMatch; builds landcoverDT if absent; builds nonForest_timeSinceDisturbance if absent, from the fire polygons of the cutoffForYoungAge years up to dataYear.
  • getClimateRasters (from .runInitialTime): a supplied currentClimateRasters (e.g. from the climateYear module) is left alone. If it is absent, or this module built it for another year, takes layer year<Y> of each element of projectedClimateRasters, where Y is climateYear if supplied, else time(sim). Stops if it does not match pixelGroupMap.
  • prepIgAndEscPredictData (from .runInitialTime): builds fireSense_igAndEscapePred_Covariates. Scheduled if whichModulesToPrepare has fireSense_ignitionPredict; the module fireSense_EscapePredict no longer exists and is rejected.
  • prepSpreadPredictData (from .runInitialTime): builds fireSense_SpreadCovariates. Scheduled if whichModulesToPrepare has fireSense_spreadPredict.
  • ageNonForest (from time(sim) + 1): adds 1 to nonForest_timeSinceDisturbance and resets pixels burned in rstCurrentBurn to 0.
  • save: does nothing except emit a message. The module never schedules it.

The module does not plot or save anything.

Module outputs

Description of the module outputs (Table @ref(tab:moduleOutputs-fireSense-dataPrepPredict)).

(\#tab:moduleOutputs-fireSense-dataPrepPredict)(\#tab:moduleOutputs-fireSense-dataPrepPredict)List of (ref:fireSense-dataPrepPredict) outputs and their description.
objectName objectClass desc
currentClimateRasters SpatRaster Climate layers for the current year, one layer per climate variable. Built from `projectedClimateRasters` if not supplied.
fireSense_igAndEscapePred_Covariates data.table Ignition and escape covariates at the aggregated (`igAggFactor`) resolution; `pixelID` is the cell index of the aggregated raster.
fireSense_SpreadCovariates data.table Spread covariates; `pixelID` is the cell index of `flammableRTM`.
nonForest_timeSinceDisturbance SpatRaster Years since last burn, used to set `youngAge` in non-forest pixels.
studyAreaWithSpreadParams sf With `.ELFind`: the simulated ELF's row first, then the neighbours `blendNeighbourELFs` keeps; set by the covariate events, before `fireSense_spreadPredict` reads it.

Links to other modules

Runs after Biomass_borealDataPrep, fireSense_dataPrepFit, fireSense_ignitionFit and fireSense_spreadFit, and supplies fireSense_ignitionPredict (ignition and escape) and fireSense_spreadPredict. It is normally run as part of the fireSense module group.

Getting help

References