fireSense_spreadPredict.RmdEliot McIntire eliot.mcintire@nrcan-rncan.gc.ca [aut, cre], Tati Micheletti tati.micheletti@gmail.com [aut], Ian Eddy ian.eddy@nrcan-rncan.gc.ca [aut], Jean Marchal jean.d.marchal@gmail.com [aut], Alex M. Chubaty achubaty@for-cast.ca [ctb]
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).
fireSense_SpreadCovariates are rescaled to [0, 1] using covMinMax_spread, the range of the fitting data.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.fireSense_SpreadPredicted is that single set’s prediction (sets are not averaged), and fireSense_SpreadSD its yearSpreadSD, on the flammableRTM grid.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.
| 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)
| 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 |
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.
Description of the module outputs (Table 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_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.