8 fireSense_spreadPredict Module

8.0.0.1 Authors:

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

8.1 Module Overview

8.1.1 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 et al. 2017b, a; 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.

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

Table 8.1: Table 8.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 studyAreaLarge. NA
flammableRTM SpatRaster Binary raster, 1 where the pixel is flammable. Template for fireSense_SpreadPredicted. NA

Summary of user-visible parameters (Table 8.3)

Table 8.3: Table 8.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
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
.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

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

8.1.4 Module outputs

Description of the module outputs (Table 8.5).

Table 8.5: Table 8.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_SpreadPowerLaw SpatRaster|numeric Only for a fit made with spreadLink = "powerLaw" (else NULL): pc (the row’s maxAsymptote), gamma, floor (lowerSpreadProb) and shape of fireSenseUtils::powerLawLink(), for fireSense_burn, which adds the year effect to the linear predictor, as the fit does. A numeric vector with one fitted ELF; with several, a 4-layer raster blended like fireSense_SpreadSD.
fireSense_SpreadLinear SpatRaster Only for a fit made with spreadLink = "powerLaw" (else NULL): the linear predictor x of each flammable pixel (covariates % % coefficients), the step before fireSenseUtils::powerLawLink() turns it into fireSense_SpreadPredicted; NA where that is. 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.

8.2 References