8 fireSense_spreadPredict Module
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).
- The covariates in
fireSense_SpreadCovariatesare rescaled to [0, 1] usingcovMinMax_spread, the range of the fitting data. - With the one parameter set (row of
studyAreaWithSpreadParams$params[[i]]) chosen by.rep(or, withparamSetByReplicate = TRUE, by the replicate within the job), i.e. row((rep - 1) %% number of sets) + 1of each ELF, the spread probability is a 2- or 3-parameter logistic of the linear combination of the covariates, with lower asymptotelowerSpreadProb. -
fireSense_SpreadPredictedis that single set’s prediction (sets are not averaged), andfireSense_SpreadSDitsyearSpreadSD, on theflammableRTMgrid.
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.
| 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)
| 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: checksmaxFireSpreadagainst the other modules; schedulesrunat.runInitialTime, andsaveat.saveInitialTimeif that is notNA. -
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).
| 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.1.5 Links to other modules
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.