9 fireSense_burn Module
(ref:fireSense_burn) fireSense_burn
9.1 Module Overview
A landscape fire model sensitive to environmental changes (e.g., weather and land cover) (Marchal et al. 2017b, a; 2019).
9.1.1 Module summary
Each year, fireSense_burn spreads fires from the pixels where fires escaped, using SpaDES.tools::spread2() with the per-pixel spread probabilities in fireSense_SpreadPredicted.
Ignitions and escapes are drawn here, each year, from the expected counts fireSense_ignitionPredict predicts (fireSense_IgAndEscapeProbRas), using the objective of the fitted models (fireSense_IgAndEscapeDistribution, only count:poisson); each ignition escapes with a probability that keeps the mean escapes of an ignited pixel at the predicted escapeProb, so escapes never exceed ignitions. The result is ignitionsAndEscapes.
The module records the pixels burned that year, a cumulative burn map, and a per-fire summary of area burned.
9.1.2 Module inputs and parameters
Table @ref(tab:moduleInputs-fireSense_burn) shows the full list of module inputs.
| objectName | objectClass | desc | sourceURL |
|---|---|---|---|
| fireSense_SpreadPredicted | SpatRaster | Per-pixel spread probability for the current year. | NA |
| fireSense_SpreadSD | SpatRaster|numeric |
Sd of the per-year random effect (on logit spread probability; on x with fireSense_SpreadPowerLaw), as fitted by fireSense_spreadFit (yearSpreadSD): a raster aligned with fireSense_SpreadPredicted (from fireSense_spreadPredict, per ELF) or one number. Each year draws one z ~ N(0, 1), independent of the z that scales that year’s ignitions and escapes (fireSense_IgAndEscapeProbRas); all of that year’s fires spread with plogis(qlogis(p) + z sd). NULL or 0: no effect.
|
NA |
| fireSense_SpreadPowerLaw | SpatRaster|numeric |
From fireSense_spreadPredict, only for a fit made with spreadLink = "powerLaw": pc, gamma and floor (and shape, 1 if absent) of fireSenseUtils::powerLawLink(), as a numeric vector with these names (one ELF) or a raster aligned with fireSense_SpreadPredicted. The year effect is then added to the linear predictor x, as in the fit: p = powerLawLink(x + z sd), with x from fireSense_SpreadLinear. NULL: the effect is added on the logit.
|
NA |
| fireSense_SpreadLinear | SpatRaster |
From fireSense_spreadPredict, only for a fit made with spreadLink = "powerLaw": the linear predictor x of each flammable pixel, aligned with fireSense_SpreadPredicted. Required whenever fireSense_SpreadPowerLaw is set and the year effect is above 0: the link clips a pixel with a low x to p = 0, so x cannot be recovered from p, yet the fit adds the year effect to x of every pixel.
|
NA |
| flammableRTM | SpatRaster |
Binary SpatRaster (1 = flammable, 0 = not). Non-flammable pixels are NA in burnMap.
|
NA |
| fireSense_IgAndEscapeProbRas | SpatRaster |
Two layers at the resolution of ignitionFitRTM, from fireSense_ignitionPredict: ignitionProb, the expected ignitions per pixel and year, and escapeProb, the expected escapes per pixel and year given an ignition. Ignitions and escapes are drawn from these each year. Optional layers ignitionYearSD and escapeYearSD: the sd of the year effect of each; a year multiplies the means by exp(sd z - sd^2 / 2), with the year’s z, which spread does not share. Absent or 0: no year effect.
|
NA |
| fireSense_IgAndEscapeDistribution | list |
list(ignition = , escape = ), from fireSense_ignitionPredict: the objective the ignition and escape models were fitted with. Only "count:poisson" can be drawn from.
|
NA |
| ignitionFirePoints | SpatVector |
Only with ignitionSource = "observedEscapes": observed fire points with columns YEAR and SIZE_HA, in the CRS of rasterToMatch (from fireSense_dataPrepFit: the NFDB natural-cause points).
|
NA |
| ignitionFitRTM | SpatRaster | The coarse raster the ignition and escape models were fitted on (from fireSense_dataPrepFit). | NA |
| nonEscapedFireSizesHa | numeric |
Sizes (ha) of the study area’s observed fires below escapeSizeHa, from fireSense_dataPrepFit. Each ignition that did not escape burns a patch of a size drawn from these. Unsupplied, with a studyArea (a run without fireSense_dataPrepFit), .inputObjects makes them the same way, from the NFDB fires of fireCauses in fireYears. NULL: ignitions that did not escape burn nothing.
|
NA |
| studyArea | SpatVector |
Only for making nonEscapedFireSizesHa: the study area whose NFDB fires give the sizes.
|
NA |
| rasterToMatch | SpatRaster | Template raster for the study area, ideally buffered to limit fire edge effects. | NA |
Summary of user-visible parameters (Table @ref(tab:moduleParams-fireSense_burn))
| paramName | paramClass | default | min | max | paramDesc | cacheKey |
|---|---|---|---|---|---|---|
| .plots | characte…. | NA | NA |
Passed to types in Plots(), e.g. “screen”, “png”. NULL or NA for no plots.
|
TRUE | |
| .plotInterval | numeric | 10 | NA | NA | Years between plots of annual fire IDs, cumulative burns and spread probability. | TRUE |
| .runInitialTime | numeric | 0 | NA | NA |
Time of the first burn event.
|
TRUE |
| .runInterval | numeric | 1 | NA | NA |
Years between burn events. NA burns once only.
|
TRUE |
| .studyAreaName | character | NA | NA | NA | Human-readable name for the study area used. | TRUE |
| escapeSizeHa | numeric | 50 | 0 | NA |
Size (ha) a fire must reach to count as escaped, as in the spread fit: each escaped fire burns this area first, whatever its spread probability, then spreads normally. NA spreads escaped fires from their ignition pixel only.
|
TRUE |
| fireCauses | character | natural,…. | NA | NA |
As in fireSense_dataPrepFit: the fire causes whose observed sizes the ignitions that do not escape draw from, when .inputObjects makes nonEscapedFireSizesHa.
|
TRUE |
| fireYears | integer | 1986, 19…. | NA | NA |
As in fireSense_dataPrepFit: the years of those observed fires, when .inputObjects makes nonEscapedFireSizesHa.
|
TRUE |
| ignitionSource | character | predicted | NA | NA |
Where each year’s fires start. "predicted": ignitions and escapes are drawn from fireSense_IgAndEscapeProbRas. "observedEscapes" (for hindcasts that test spread alone): the year’s observed escapes in ignitionFirePoints (fires of at least escapeSizeHa and larger than a pixel, of year floor(time(sim))) are spread from the pixels of their points, and nothing is drawn from the predicted surfaces. Observed fires that did not escape are left out.
|
TRUE |
| jumpTries | integer | 20 | 0 | NA |
Passed to SpaDES.tools::spreadCpp() for escaped fires: attempts to jump for a fire still under escapeSizeHa that has nowhere left to spread. Default 20, as fireSense_spreadFit fits with; 0 is off.
|
TRUE |
| jumpMeanDist | numeric | 3 | 0 | NA |
Passed to SpaDES.tools::spreadCpp(): mean jump distance, in cells.
|
TRUE |
| whichModulesToPrepare | character | fireSens…. | NA | NA |
Fires spread only if this includes fireSense_spreadPredict. Other values are ignored.
|
TRUE |
9.1.3 Events
-
init: createsburnMap(0 where flammable,NAelsewhere) and schedules the firstburnat.runInitialTime. -
burn: draws the year’s ignitions and escapes, then spreads fires from every pixel withescaped, updates the outputs, and reschedules itself every.runIntervalyears. Nothing burns in a year with no escapes, or ifwhichModulesToPreparedoes not includefireSense_spreadPredict.
9.1.4 Plotting
Every .plotInterval years the burn event plots annual fire IDs, the cumulative burn map and the spread probability map, to the devices named in .plots.
9.1.5 Saving
The module saves nothing itself; use the outputs argument of simInit().
9.1.6 Module outputs
Description of the module outputs (Table @ref(tab:moduleOutputs-fireSense_burn)).
| objectName | objectClass | desc |
|---|---|---|
| ignitionsAndEscapes | data.table |
This year’s ignitions, one row per ignited pixel, in random order: pixelID (cell index of flammableRTM), igProb, ignitions, escapeProb, escapes of the coarse pixel it was drawn from, and escaped, whether this ignition escaped: exactly escapes of a coarse pixel’s rows are TRUE. Drawn each year from fireSense_IgAndEscapeProbRas; without that raster a supplied ignitionsAndEscapes is used as it is. With ignitionSource = "observedEscapes": the year’s observed escapes, with only pixelID and escaped (all TRUE).
|
| burnDT | data.table |
The most recent fire year’s burned pixels: initialPixels (the fire’s ignition pixel), pixels, and fire_id.
|
| burnMap | SpatRaster |
Number of times each pixel has burned. NA where not flammable.
|
| burnSummary | data.table |
One row per fire: igLoc (ignition pixel), N (pixels burned), year, areaBurnedHa.
|
| rstAnnualBurnID | SpatRaster |
Fire ID of each pixel burned this year; NA elsewhere.
|
| rstCurrentBurn | SpatRaster |
1 where burned this year; NA elsewhere.
|
9.1.7 Usage
fireSense_burn needs the objects made by the predict modules, so run it with them:
library(SpaDES.core)
modules <- list("fireSense_dataPrepPredict", "fireSense_ignitionPredict",
"fireSense_spreadPredict", "fireSense_burn")
mySim <- simInit(times = list(start = 2011, end = 2100),
params = list(fireSense_burn = list(.plots = "png", .plotInterval = 10)),
modules = modules,
objects = objects, ## fitted fireSense models, rasterToMatch, flammableRTM, etc.
paths = list(modulePath = ".."))
spades(mySim)9.1.8 Links to other modules
-
fireSense_ignitionPredictsuppliesfireSense_IgAndEscapeProbRasandfireSense_IgAndEscapeDistribution. -
fireSense_spreadPredictsuppliesfireSense_SpreadPredicted. - Vegetation modules (e.g.
Biomass_regeneration) userstCurrentBurn.
