6 fireSense_dataPrepPredict Module

6.0.0.1 Authors:

Ian Eddy [aut, cre], Eliot McIntire [aut], Alex M Chubaty [ctb]

6.1 Module Overview

6.1.1 Module summary

Prepares, each year, the covariate tables that the fireSense (Marchal et al. 2017b, a; 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.

6.1.2 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 6.1 shows the full list of module inputs.

Table 6.1: Table 6.2: List of 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
climateVariables list The climate layers canClimateData prepares (climateData::climateLayers()). Unsupplied (no fireSense_dataPrepFit), .inputObjects asks for the stored fits’ variables: historical climate for the simulated years up to climateData::latestHistoricalYear(), projected for canClimateData’s projectedClimateYears. 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. Unsupplied: the stored fits’ variables when .inputObjects reads the SpreadFit ledger (no fireSense_dataPrepFit), else ‘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
cohortDatas list Optional: the real per-year datasets of cohortData, a named list (year&lt;year&gt;) from fireSense_dataPrepFit. Used only when no module simulates cohortData (a hindcast): Init takes the latest data year before the start year (see createsOutput). NA
flammableRTMs list Optional: as cohortDatas, for flammableRTM. NA
landcoverDTs list Optional: as cohortDatas, for landcoverDT. NA
nonForest_timeSinceDisturbances list Optional: as cohortDatas, for nonForest_timeSinceDisturbance. NA
pixelGroupMaps list Optional: as cohortDatas, for pixelGroupMap. NA
standAgeMaps list Optional: as cohortDatas, for standAgeMap. 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. Unsupplied: fireSenseUtils::prepare_LightningData(), as fireSense_dataPrepFit makes it. NA
pixelGroupMap SpatRaster Map of the pixelGroups 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 SpatRasters, one per data year, as produced by fireSense_dataPrepFit: as cohortDatas, for rstLCC_RTM (.inputObjects takes the last element when rstLCC_RTM is not supplied). 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_dataPrepFit, else read by .inputObjects; 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_&lt;class&gt;/sec_agb_&lt;class&gt; 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 (a run without fireSense_dataPrepFit), .inputObjects reads it from the SpreadFit ledger (predictInputsFromLedger()). Supplied as NULL: no stored fits, and 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 6.3)

Table 6.3: Table 6.4: List of fireSense_dataPrepPredict parameters and their description.
paramName paramClass default min max paramDesc cacheKey
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, and says so in one message instead of a warning per neighbour. TRUE
cutoffForYoungAge numeric 15 NA NA Age at and below which pixels are considered ‘young’ (i.e., age &lt;= cutoffForYoungAge). TRUE
dataYear numeric 2020 1985 2025 Year of the default landcover and stand age maps, and last year of the fires used to initialise nonForest_timeSinceDisturbance, when those inputs are not supplied (as in a run without fireSense_dataPrepFit). The same parameter as in Biomass_core, Biomass_borealDataPrep, Biomass_speciesData and burnSummaries (2020); a module with another value is an error. Set it for all with .globals = list(dataYear = ). TRUE
fireTimeStep numeric 1 NA NA Interval between events of this module, in years. TRUE
fitFileSuffix character NA NA The ledger to predict from, in a run without fireSense_dataPrepFit (.inputObjects then reads the stored fits itself): the text after the model tag in the ledger file names. The same parameter of fireSense_ELFs, fireSense_dataPrepFit, fireSense_spreadFit and fireSense_ignitionFit; set it for all with .globals = list(fitFileSuffix = ...). TRUE
forestedLCC numeric 81, 210,…. NA NA Forested landcover classes in rstLCC_RTM. Only used if landcoverDT is not supplied. TRUE
flammabilityThreshold numeric 0.1 0 1 Minimum proportion of flammable pixels for an upscaled pixel to be flammable, when building the default landcover. TRUE
fuelClassCol character FuelClass NA NA Column of sppEquiv that defines the fuel classes, for both ignition and spread. TRUE
igAggFactor numeric 4 1 NA Aggregation factor for the ignition and escape covariates. Overwritten in init by the value set in other modules. TRUE
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. TRUE
nonForestCanBeYoungAge logical TRUE NA NA Should burned non-forest pixels be youngAge until cutoffForYoungAge? TRUE
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). TRUE
sppEquivCol character LandR NA NA Column of sppEquiv with the species names used in cohortData. TRUE
spreadFitFilename character latest NA NA As in fireSense_dataPrepFit: the SpreadFit ledger file in spreadFitGoogleDriveFolder; "latest" takes each ELF’s fit from the most recent file that has it. Read only in a run without fireSense_dataPrepFit. TRUE
spreadFitGoogleDriveFolder character https://…. NA NA As in fireSense_dataPrepFit: the Google Drive folder of the SpreadFit ledger (fireSenseUtils::spreadFitLedgerFolder()). Read only in a run without fireSense_dataPrepFit. TRUE
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. TRUE
.runInitialTime numeric 0 NA NA Time of the first climate and covariate preparation events. TRUE
.studyAreaName character NA NA NA Human-readable name for the study area used. TRUE
.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 TRUE

6.1.3 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.

6.1.4 Module outputs

Description of the module outputs (Table 6.5).

Table 6.5: Table 6.6: List of fireSense_dataPrepPredict outputs and their description.
objectName objectClass desc
climateVariablesForFire list As the input; a single entry is expanded in init to ignition and spread.
cohortData data.table The latest vegetation available. When another module simulates it (declares it as an output, e.g. Biomass_core in a forecast), it is that module’s current state, read by every covariate event, and this module never replaces it. Otherwise (a hindcast: no vegetation module, times in a past year) Init sets it to the element of cohortDatas of the latest data year strictly before the start year, as the fit pairs a fire year with its vegetation (fireSenseUtils::dataYearElement(before = TRUE)): SCANFI of year Y already shows Y’s burns. In a forecast, objects no module simulates take the latest data year not after the start year, so an NRV run from 2020 uses 2020’s land cover. If cohortDatas is not supplied, the input stands. The same rule for the other objects below, from their per-year lists.
flammableRTM SpatRaster As cohortData, from flammableRTMs.
landcoverDT data.table As cohortData, from landcoverDTs; built in init if neither is supplied.
pixelGroupMap SpatRaster As cohortData, from pixelGroupMaps.
rstLCC_RTM SpatRaster As cohortData, from rstLCCs.
standAgeMap SpatRaster As cohortData, from standAgeMaps.
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. At init as cohortData, from nonForest_timeSinceDisturbances; then aged by ageNonForest.
climateVariables list Set by .inputObjects when unsupplied (see expectsInput), for canClimateData.
ignitionFitRTM SpatRaster Unless fireSense_dataPrepFit (or a user) supplies it: the coarse grid (igAggFactor) of fireSense_igAndEscapePred_Covariates, whose pixelIDs are its cells; fireSense_ignitionPredict predicts on it. Set with those covariates.
lightningMaps SpatRaster Set by .inputObjects when unsupplied (see expectsInput).
sppEquivs list Set by .inputObjects from the SpreadFit ledger in a run without fireSense_dataPrepFit.
nonForestedLCCGroupsList list Set by .inputObjects from the SpreadFit ledger in a run without fireSense_dataPrepFit.
missingLCCgroupList list Set by .inputObjects from the SpreadFit ledger in a run without fireSense_dataPrepFit.
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. In a run without fireSense_dataPrepFit (prediction only), .inputObjects reads it from the SpreadFit ledger first: the rows whose polygons intersect studyArea (fireSenseUtils::readSpreadFitLedger()).

6.2 References