fireSense_spreadPredict Module

Authors:

Eliot McIntire [aut, cre], Tati Micheletti [aut], Ian Eddy [aut], Jean Marchal [aut], Alex M. Chubaty [ctb]

Module Overview

Module summary

Each year, predicts a raster of fire spread probabilities from the parameters fitted by fireSense_spreadFit, for the spread component of fireSense (Marchal, Steve G. Cumming, et al. 2017b; Marchal, Steve G. Cumming, et al. 2017a; Marchal et al. 2019).

  1. The covariates in fireSense_SpreadCovariates are rescaled to [0, 1] using covMinMax_spread, the range of the fitting data.
  2. With the one parameter set (row of studyAreaWithSpreadParams$params[[i]]) chosen by .rep (or, with paramSetByReplicate = TRUE, by the replicate within the job), i.e. row ((rep - 1) %% number of sets) + 1 of each ELF, the spread probability is a 2- or 3-parameter logistic of the linear combination of the covariates, with lower asymptote lowerSpreadProb.
  3. fireSense_SpreadPredicted is that single set’s prediction (sets are not averaged), and fireSense_SpreadSD its yearSpreadSD, on the flammableRTM grid.

Module inputs and parameters

studyAreaWithSpreadParams (the fitted parameters, from fireSense_spreadFit) is read from the simList though it is not declared as an input. Prediction uses the covariates the fit has coefficients for, not the terms of fireSense_spreadFormula; each must be a column of fireSense_SpreadCovariates. The module stops if studyAreaWithSpreadParams has no parameters. maxFireSpread must have the same value in every module that defines it.

Table 1 shows the full list of module inputs.

Table 1: Table 2: List of fireSense_spreadPredict input objects and their description.
objectName objectClass desc sourceURL
covMinMax_spread data.table Minimum and maximum (2 rows) of each covariate in the fitting data, used to rescale the covariates as in fireSense_spreadFit. NA
fireSense_SpreadCovariates data.table This year’s covariates, from fireSense_dataPrepPredict. pixelID is the cell index of flammableRTM. NA
rasterToMatchLargeELF SpatRaster Only with several fitted ELFs: each pixel’s ELF (ELFind), on the grid of flammableRTM, from fireSense_ELFs with a studyArea_fireSense. NA
.ELFind character The simulated ELF, as in fireSense_dataPrepPredict. Only used with paramSets and several fitted ELFs, to find the simulated ELF’s row. NA
flammableRTM SpatRaster Binary raster, 1 where the pixel is flammable. Template for fireSense_SpreadPredicted. NA

Summary of user-visible parameters (Table 3)

Table 3: Table 4: List of fireSense_spreadPredict parameters and their description.
paramName paramClass default min max paramDesc cacheKey
lowerSpreadProb numeric 0.13 NA NA Lower asymptote of the 2- and 3-parameter logistic. Default fireSenseUtils::spreadProbFloor, the same constant fireSense_spreadFit fits with. TRUE
ELFblendWidth numeric 20000 NA NA With several ELFs: each ELF’s model also predicts this far (m) outside its own pixels, and where predictions overlap they are averaged with weights that fall linearly from 1 inside the ELF to 0 at this distance outside it. 50/50 at a boundary. The default is the buffer fireSenseUtils::makeELFs() puts around ELFs. TRUE
escapeSizeHa numeric 50 NA NA Size (ha) at and above which a fire counts as an escape. The ledger rows must have been fitted with this definition, else the module stops (fireSenseUtils::checkEscapeDefinition()). Checked to be the same in every module that defines it. TRUE
fireCauses character natural,…. NA NA Cause groups of the fires that count as escapes (fireSenseUtils::fireCauseCodes()); part of the escape definition, checked like escapeSizeHa. TRUE
maxFireSpread numeric 0.276 NA NA Upper limit on spreadProb used when fitting (default fireSenseUtils::spreadProbCeiling). Here it is only checked to be the same in every module that defines it. TRUE
paramSets character NA NA NA Path to an .rds or .csv of spread parameter vectors, one per row, for the simulated ELF (sim$.ELFind; the only row with one ELF): e.g. a DEoptim population, or the params of ledger rows of another fitFileSuffix (a table with a params list column, its rows for this ELF). They replace the simulated ELF’s rows of the ledger; neighbour ELFs keep theirs, so blending is unchanged. The link, lower asymptote, gamma and covariate centres still come from the ledger row. A set must have every coefficient the ledger row has, else the module stops. NA uses the ledger rows. Replicate r uses set ceiling(r / repsPerSet) (cycling through the sets), and calls set.seed(k) with k the replicate’s number within its set, so every set gets the same random numbers in fireSense_burn (common random numbers). TRUE
repsPerSet integer 1 1 NA With paramSets: the number of replicates that use each set. Not used otherwise. TRUE
.rep integer 1 1 NA Which replicate this prediction is. It selects parameter set ((rep - 1) %% number of sets) + 1 of each ELF, so replicates cycle through the fitted sets, each used whole (with its own yearSpreadSD), never averaged. Ignored if paramSetByReplicate is TRUE. TRUE
paramSetByReplicate logical FALSE NA NA If TRUE, the replicate is the run event within the job, not .rep: round((time - .runInitialTime) / .runInterval) + 1 (as fireSense_summary numbers hindcast replicates), so one job cycles through all the fitted parameter sets. With FALSE the set follows .rep. TRUE
.runInitialTime numeric 0 NA NA Time of the first prediction. TRUE
.runInterval numeric 1 NA NA Interval between predictions, in years. NA predicts once. TRUE
.saveInitialTime numeric NA NA NA Time of the save event, which does nothing. NA means never. 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

Events

  • init: checks maxFireSpread against the other modules; schedules run at .runInitialTime, and save at .saveInitialTime if that is not NA.
  • run: makes the prediction described above; repeats every .runInterval.
  • save: does nothing, and says so in a message.

The module does not plot anything.

Module outputs

Description of the module outputs (Table 5).

Table 5: Table 6: List of fireSense_spreadPredict outputs and their description.
objectName objectClass desc
fireSense_SpreadPredicted SpatRaster Spread probability of each flammable pixel, this year.
fireSense_SpreadParamSet integer Row of the fitted parameter sets used by this prediction, named by ELF with several ELFs, for fireSense_summary.
fireSense_SpreadSD SpatRaster|numeric The fitted sd of the per-year random effect on logit spread probability (yearSpreadSD of the parameter set chosen by .rep; 0 if the fit has none), for fireSense_burn. One number with one fitted ELF; with several, a raster blended across ELFs with the weights of fireSense_SpreadPredicted.
fireSense_SpreadFireSD SpatRaster|numeric The fitted sd of the per-fire random effect on spread probability (fireSpreadSD of the parameter set chosen by .rep; 0 for a ledger row without it), for fireSense_burn. Shaped like fireSense_SpreadSD: one number with one fitted ELF; with several, a raster of each ELF’s value blended with the weights of fireSense_SpreadPredicted.
fireSense_EscapeDefinition data.frame The escape definition the ledger rows were fitted with (escapeSizeHa, fireCauses; fireSenseUtils::escapeDefinition()), one row per fitted ELF (with its polygonID); NA for a row fitted before the definition was recorded. Each row has been checked against this run’s escapeSizeHa and fireCauses.
fireSense_SpreadLink character Only for a fit made with spreadLink = "powerLaw", "powerLawSmooth" or "richards" (else NULL): the link the ledger row records, for fireSense_burn. The names of fireSense_SpreadPowerLaw are those of this link (fireSenseUtils::spreadLinkParNames). Fitted ELFs with different such links cannot be blended: an error.
fireSense_SpreadPowerLaw SpatRaster|numeric Only for a fit made with spreadLink = "powerLaw", "powerLawSmooth" or "richards" (else NULL): the parameters of its link, named as fireSenseUtils::spreadLinkParNames says for fireSense_SpreadLink, for fireSense_burn, which adds the year effect to the linear predictor, as the fit does. “powerLaw”: pc (the row’s maxAsymptote), gamma, floor (lowerSpreadProb) and shape of fireSenseUtils::powerLawLink(); “powerLawSmooth” also lower (the row’s lowerAsymptote, at least fireSenseUtils::spreadLowerAsymptoteMin, 0.001: fireSenseUtils::checkLinkParams()); “richards”: pc, lower, nu (the row’s richardsNu) and B. A numeric vector with one fitted ELF; with several, a raster with one layer per name, blended like fireSense_SpreadSD.
fireSense_SpreadLinear SpatRaster Only for a fit made with a link of fireSenseUtils::spreadLinearLinks (else NULL): the linear predictor x of each flammable pixel (covariates % % coefficients), the step before the link (fireSenseUtils::linearLinkProb()) turns it into fireSense_SpreadPredicted; NA where that is. With "powerLaw" a pixel with a negative x has a spread probability of 0, so fireSense_burn needs x itself to add the year effect there. With several ELFs, blended like fireSense_SpreadPowerLaw.

Runs after fireSense_dataPrepPredict (covariates) and fireSense_spreadFit (parameters). fireSense_SpreadPredicted is used by fireSense_burn to spread fires. It is normally run as part of the fireSense module group.

References

Marchal, Jean, Steve G. Cumming, and Eliot J. B. McIntire. 2017a. “Exploiting Poisson Additivity to Predict Fire Frequency from Maps of Fire Weather and Land Cover in Boreal Forests of Québec, Canada.” Ecography 40 (1): 200–209. https://doi.org/10.1111/ecog.01849.
Marchal, Jean, Steve G Cumming, and Eliot J B McIntire. 2017b. “Land Cover, More Than Monthly Fire Weather, Drives Fire-Size Distribution in Southern Québec Forests: Implications for Fire Risk Management.” PLoS ONE 12 (6): 1–17. https://doi.org/10.1371/journal.pone.0179294.
Marchal, Jean, Steven G. Cumming, and Eliot J. B. McIntire. 2019. “Turning Down the Heat: Vegetation Feedbacks Limit Fire Regime Responses to Global Warming.” Ecosystems, ahead of print, May. https://doi.org/10.1007/s10021-019-00398-2.