6 fireSense_dataPrepPredict Module
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_Covariatesfor fireSense_ignitionPredict (ignition and escape): fuel classes, non-forest landcover,youngAge, ignition climate and lightning days, aggregated byigAggFactor. -
fireSense_SpreadCovariatesfor fireSense_spreadPredict: the same fuel, landcover andyoungAgecolumns plus spread climate, at the resolution offlammableRTM.
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.
| 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<year>) 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_<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 (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)
| 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 <= 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: alignsstandAgeMapandrstLCC_RTMtorasterToMatch; buildslandcoverDTif absent; buildsnonForest_timeSinceDisturbanceif absent, from the fire polygons of thecutoffForYoungAgeyears up todataYear. -
getClimateRasters(from.runInitialTime): a suppliedcurrentClimateRasters(e.g. from theclimateYearmodule) is left alone. If it is absent, or this module built it for another year, takes layeryear<Y>of each element ofprojectedClimateRasters, whereYisclimateYearif supplied, elsetime(sim). Stops if it does not matchpixelGroupMap. -
prepIgAndEscPredictData(from.runInitialTime): buildsfireSense_igAndEscapePred_Covariates. Scheduled ifwhichModulesToPreparehasfireSense_ignitionPredict; the modulefireSense_EscapePredictno longer exists and is rejected. -
prepSpreadPredictData(from.runInitialTime): buildsfireSense_SpreadCovariates. Scheduled ifwhichModulesToPreparehasfireSense_spreadPredict. -
ageNonForest(fromtime(sim) + 1): adds 1 tononForest_timeSinceDisturbanceand resets pixels burned inrstCurrentBurnto 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).
| 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.1.5 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.