4 fireSense_ignitionFit Module

4.0.0.1 Authors:

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

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"):

  1. Covariates are centred and scaled (fireSenseUtils::prepareCovariatesOuter()), if rescaleVars = TRUE. Ignition uses fireSense_ignitionCovariates; escape uses fireSense_escapeCovariates and only its rows with at least one ignition.
  2. 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.
  3. One xgboost model (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.
  4. 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: schedules checkData and run at .runInitialTime.
  • checkData: stops if ignitionFitRTM lacks the nonNAs attribute, or if whichProcessesToFit names neither process.
  • run: fits and, if .plots is set, plots. Repeats every .runInterval if that is not NA.

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.

Table 4.1: Table 4.2: List of fireSense_ignitionFit input objects and their description.
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.

Table 4.3: Table 4.4: List of fireSense_ignitionFit parameters and their description.
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.5 Saving

Nothing is saved apart from the figure.

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.

Table 4.5: Table 4.6: List of fireSense_ignitionFit outputs and their description.
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$Fold1

4.2 References