9 fireSense_burn Module

(ref:fireSense_burn) fireSense_burn

made-with-Markdown

9.0.0.1 Authors:

Eliot McIntire [aut, cre], Jean Marchal [aut], Alex M. Chubaty [ctb]

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.

(#tab:moduleInputs-fireSense_burn)(#tab:moduleInputs-fireSense_burn)List of (ref:fireSense_burn) input objects and their description.
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))

(#tab:moduleParams-fireSense_burn)(#tab:moduleParams-fireSense_burn)List of (ref:fireSense_burn) parameters and their description.
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: creates burnMap (0 where flammable, NA elsewhere) and schedules the first burn at .runInitialTime.
  • burn: draws the year’s ignitions and escapes, then spreads fires from every pixel with escaped, updates the outputs, and reschedules itself every .runInterval years. Nothing burns in a year with no escapes, or if whichModulesToPrepare does not include fireSense_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)).

(#tab:moduleOutputs-fireSense_burn)(#tab:moduleOutputs-fireSense_burn)List of (ref:fireSense_burn) outputs and their description.
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.2 References