4 fireSense_ignitionFit Module
4.1 Module Overview
Fits models of fire ignition and, optionally, fire escape from climate and fuel covariates. The fitted models are used by fireSense_ignitionPredict and fireSense_dataPrepPredict. The module does not prepare data; fireSense_dataPrepFit supplies its inputs. Earlier versions fitted the piecewise regression models of Marchal et al. (2017b), Marchal et al. (2017a) and Marchal et al. (2019).
4.1.1 What it does
For each process in whichProcessesToFit ("ignition", "escape"):
- Covariates are centred and scaled (
fireSenseUtils::prepareCovariatesOuter()), ifrescaleVars = TRUE. Ignition usesfireSense_ignitionCovariates; escape usesfireSense_escapeCovariatesand only its rows with at least one ignition. - Rows are split into 5 cross-validation folds, stratified on whether the response is positive. The fit stops if any fold would train without a positive observation.
- One
xgboostmodel (Poisson objective) is fitted per fold, with the fold as the evaluation set. The AUC of each fold is calculated on its held-out rows and the mean is printed. - The per-fold models are returned together with the values needed to predict from them (see outputs).
Only modelAlgorithm = "xgboost" works: the non-xgboost modelling path was removed, and buildModel() now stops for any other algorithm.
crossValType does not change the fit; it is only used in the plot filename.
Fits are cached with reproducible::Cache().
4.1.2 Events
-
init: schedulescheckDataandrunat.runInitialTime. -
checkData: stops ifignitionFitRTMlacks thenonNAsattribute, or ifwhichProcessesToFitnames neither process. -
run: fits and, if.plotsis set, plots. Repeats every.runIntervalif that is notNA.
4.1.3 Module inputs and parameters
Table 4.1 lists the declared inputs.
Fitting escape also needs fireSense_escapeCovariates (from fireSense_dataPrepFit), which is not declared in the metadata.
| objectName | objectClass | desc | sourceURL |
|---|---|---|---|
| .ELFind | character |
Identifier of the polygon being fit, e.g. ‘6.1.1’. This becomes the polygonID of the row this module writes to the shared cloud fit ledger (ignitionFitFilename in ignitionFitGoogleDriveFolder). Only used, and only required, when studyArea is supplied.
|
NA |
| studyArea | SpatVector | Polygon being fit; its geometry and crs go in the ledger row. Optional: without it, this module fits every time and never reads or writes the shared ledger, as before this parameter existed. | NA |
| fireSense_ignitionCovariates | data.frame |
Table of aggregated ignition covariates with annual ignitions counts, one row per pixelID and year.
|
NA |
| ignitionFitRTM | SpatRaster |
Template raster at the resolution and extent of fireSense_ignitionCovariates. Its resolution and its number of non-NA cells, which must be in the attribute nonNAs (attributes(ignitionFitRTM)$nonNAs), are stored in the fitted objects.
|
NA |
Parameters are in Table 4.3.
| paramName | paramClass | default | min | max | paramDesc | cacheKey |
|---|---|---|---|---|---|---|
| crossValType | character | time-ord…. | NA | NA |
Has no effect on the fit: runXGBOOST() always uses k-fold cross validation. The first element is only used in the plot filename.
|
TRUE |
| rescaleVars | logical | TRUE | NA | NA |
If TRUE, covariates are centred and scaled with scale() before fitting. The centring and scaling values are returned in the scaleData element of the outputs.
|
TRUE |
| whichProcessesToFit | character | ignition…. | NA | NA | which processes to fit: ignition, escape, or both (the default) | TRUE |
| modelAlgorithm | character | xgboost | NA | NA |
Model type. Only xgboost (any value containing ‘xgb’) works.
|
TRUE |
| .plots | character | screen | NA | NA |
See ?Plots. If set, plots the predicted response against each covariate, for climate and fuel covariates separately, and saves it as png in figurePath(sim).
|
TRUE |
| .runInitialTime | numeric | 0 | NA | NA | when to start this module? By default, the start time of the simulation. | TRUE |
| .runInterval | numeric | NA | NA | NA | optional. Interval between two runs of this module, expressed in units of simulation time. By default, NA, which means that this module only runs once per simulation. | TRUE |
| .seed | list | NA | NA |
Named list of seeds to use for each event (names). E.g., list('init' = 123) will set.seed(123) at the start of the init event and unset it at the end. Defaults to NULL, meaning that no seeds will be set.
|
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 |
| .neverCache | character | checkData | NA | NA |
Events that are never cached, whatever .useCache says (read by SpaDES.core, 3.2.1.9037 or later): checkData reads the ignition-fit ledger on Google Drive, which is not in the event’s cache key, so a cached checkData would replay a stale answer to whether this polygon already has a fit.
|
TRUE |
| ignitionFitGoogleDriveFolder | character | https://…. | NA | NA |
Google Drive folder url holding the shared ignition/escape fit ledger (ignitionFitFilename). NULL keeps the ledger purely local, in inputPath(sim), with no Google Drive access at all (e.g. for tests).
|
TRUE |
| fitFileSuffix | character | NA | NA |
Text put after the model tag in the ledger file names, e.g. "_boundfix_rep81", so a test run writes and reads ("latest") only its own files, never the production ones. "" (the default) writes the unsuffixed file and reads ("latest") every file of the model tag, newest by the date in its suffix (fireSenseUtils::ledgerFileOrder()); experiment fits belong in spreadFitLedgerFolder(testing = TRUE). The same parameter of fireSense_spreadFit, fireSense_dataPrepFit and fireSense_ELFs; set it for all with .globals = list(fitFileSuffix = ...); modules that disagree stop (SpaDES.core::paramCheckOtherMods()). Ignored when a file name is given.
|
TRUE | |
| ignitionFitFilename | character | latest | NA | NA |
File name of the shared fit ledger: an sf object with one row per polygon, holding its fitted fireSense_IgnitionFitted and fireSense_EscapeFitted. "latest" (the default) reads and writes the file named for this fit’s fire years and model, fireSenseUtils::ignitionFitFilenameFor(), e.g. fireSenseIgnitionParams_1985-2024_xgboostPoisson_20261013.rds.
|
TRUE |
| doFit | logical | FALSE | NA | NA |
Whether to fit this polygon. FALSE (default): never fit – use the ledger’s fits, and stop with an error if it holds none for this polygon (fitFileSuffix picks the ledger), so a run that only predicts can never start a fit by accident. NA: do whatever is needed – use the ledger’s ignition and escape fits if it holds them for this polygon (and they fit the current covariates), otherwise fit. TRUE: always fit, replacing the ledger row (FOR DEVELOPERS ONLY: set it when the fit’s INPUTS have changed, so the stored row is stale).
|
TRUE |
| refitExisting | logical | NA | NA | NA |
DEPRECATED, use doFit. TRUE is doFit = TRUE; NA (unset) and FALSE do nothing. Overrides doFit = FALSE (the default), not doFit = NA or TRUE.
|
TRUE |
4.1.4 Plotting
If .plots is set, one figure per process: the predicted response against each covariate, with all other covariates at their mean, for climate and fuel covariates in separate panels.
It is saved as png in figurePath(sim).
4.1.6 Module outputs
Outputs are in Table 4.5.
fireSense_IgnitionFitted$modelList$model is the list of per-fold models (Fold1, …) plus rocs, the ROC curve of each fold.
lambdaRescaleFactor is the number of rows in the covariates divided by the number of non-NA cells in ignitionFitRTM.
| objectName | objectClass | desc |
|---|---|---|
| fireSense_EscapeFitted | fireSense_EscapeFit |
List of modelList and scaleData, as fireSense_IgnitionFitted, with modelList of class fireSense_EscapeFit. Either freshly fitted, or, when studyArea matches a row of the shared ledger, read from it.
|
| fireSense_IgnitionFitted | fireSense_IgnitionFit |
List of modelList (class fireSense_IgnitionFit: model, the per-fold xgboost models and their ROC curves and out-of-fold yearTotals, fittingRes, lambdaRescaleFactor, rescales, yearSD: the sd of the year effect that fireSense_burn draws; absent in fits stored before it existed, which means 0) and scaleData (centre and scale used to standardise the covariates). Either freshly fitted, or, when studyArea matches a row of the shared ledger, read from it.
|
| ignitionFitPreRun | data.frame |
Only when studyArea is supplied: ledger rows that overlap it, from CacheGeo (NULL if there is no previous fit): a geometry column, polygonID, and fireSense_IgnitionFitted/fireSense_EscapeFitted list-columns.
|
4.1.7 Usage
## in the same `simInit()` call as fireSense_dataPrepFit,
## which creates the inputs
modules <- c("fireSense_dataPrepFit", "fireSense_ignitionFit")
params <- list(fireSense_ignitionFit = list(whichProcessesToFit = c("ignition",
"escape"), .plots = "png"))
## after `spades()`
sim$fireSense_IgnitionFitted$modelList$model$Fold14.1.8 Links to other modules
- fireSense_dataPrepFit creates the inputs.
- fireSense_dataPrepPredict and fireSense_ignitionPredict use the outputs.