title	fireSense_ignitionPredict Manual
subtitle	v.1.2.0
date	Last updated: 2026-10-07
output	bookdown::html_document2 toc toc_float theme number_sections df_print keep_md true true sandstone false paged true
editor_options	chunk_output_type console
bibliography	citations/references_fireSense_ignitionPredict.bib
link-citations	true
always_allow_html	true

fireSense_ignitionPredict Module

(ref:fireSense-ignitionPredict) fireSense_ignitionPredict

Authors:

Eliot McIntire eliot.mcintire@nrcan-rncan.gc.ca [aut, cre], 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]

Module Overview

Module summary

Each year, predicts ignitions and escapes from the models fitted by fireSense_ignitionFit and fireSense_EscapeFit, for the ignition component of fireSense [@Marchal:2017a; @Marchal:2017b; @Marchal:2019].

1. The covariates in fireSense_igAndEscapePred_Covariates are rescaled with fireSenseUtils::prepareCovariatesOuter(), the function used for fitting (rescaleVars, modelAlgorithm).
2. Expected ignitions per coarse pixel are the mean of the predictions of the per-fold ignition models; the number of ignitions is drawn from a Poisson.
3. For coarse pixels with ignitions, the escape probability is the mean of the per-fold escape models, clamped to [0, 1]; escapes are drawn from a binomial with size = ignitions.
4. Each ignition is placed in a randomly chosen flammable pixel of flammableRTM inside its coarse pixel.

Only xgboost models are supported.

Module inputs and parameters

ignitionFitRTM (the coarse raster used for fitting, from fireSense_dataPrepFit) is also read from the simList, though it is not declared as an input. modelAlgorithm and rescaleVars must have the same value in every module that defines them.

Table @ref(tab:moduleInputs-fireSense-ignitionPredict) shows the full list of module inputs.

(\#tab:moduleInputs-fireSense-ignitionPredict)(\#tab:moduleInputs-fireSense-ignitionPredict)List of (ref:fireSense-ignitionPredict) input objects and their description.

objectName	objectClass	desc	sourceURL
fireSense_EscapeFitted	fireSense_EscapeFit	Fitted escape models (`$modelList$model`, one per fold), from `fireSense_EscapeFit`.	NA
fireSense_IgnitionFittedList	list	Only with several fitted ELFs: one `fireSense_IgnitionFitted` per ELF, named by `ELFind`. Each ELF's model predicts the coarse pixels of that ELF.	NA
fireSense_EscapeFittedList	list	Only with several fitted ELFs: one `fireSense_EscapeFitted` per ELF, named as `fireSense_IgnitionFittedList`.	NA
rasterToMatchLargeELF	SpatRaster	Only with several fitted ELFs: each pixel's ELF (`ELFind`), from `fireSense_ELFs` with a `studyAreaLarge`.	NA
fireSense_IgnitionFitted	fireSense_IgnitionFit	Fitted ignition models (`$modelList$model`, one per fold) and `$modelList$fittingRes`, from `fireSense_ignitionFit`.	NA
fireSense_igAndEscapePred_Covariates	data.table	This year's covariates, from `fireSense_dataPrepPredict`. `pixelID` is the cell index of `ignitionFitRTM`.	NA
flammableRTM	SpatRaster	Binary raster, 1 where the pixel is flammable.	NA

Summary of user-visible parameters (Table @ref(tab:moduleParams-fireSense-ignitionPredict))

(\#tab:moduleParams-fireSense-ignitionPredict)(\#tab:moduleParams-fireSense-ignitionPredict)List of (ref:fireSense-ignitionPredict) parameters and their description.

paramName	paramClass	default	min	max	paramDesc
modelAlgorithm	character	xgboost	NA	NA	Algorithm used to fit the models; only `xgboost` is supported. Must agree with the value in the other fireSense modules.
rescaleVars	logical	TRUE	NA	NA	Rescale the covariates before predicting? With `xgboost` they are standardized with `scale()`. Must agree with the value in the other fireSense modules.
.runInitialTime	numeric	0	NA	NA	Time of the first prediction.
.runInterval	numeric	1	NA	NA	Interval between predictions, in years. `NA` predicts once.
.saveInitialTime	numeric	NA	NA	NA	Time of the `save` event, which does nothing. `NA` means never.
.saveInterval	numeric	NA	NA	NA	If not `NA`, the ignition probability raster is plotted each year.
.studyAreaName	character	NA	NA	NA	Human-readable name for the study area used.
.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

Events

• init: schedules run at .runInitialTime, and save at .saveInitialTime if that is not NA.
• run: makes the predictions and draws described above; repeats every .runInterval.
• save: does nothing but say so. To save the predicted raster, name fireSense_IgAndEscapeProbRas in outputs(sim).

Plotting

If .saveInterval is not NA, the ignition probability raster is plotted each year with Plots().

Module outputs

Description of the module outputs (Table @ref(tab:moduleOutputs-fireSense-ignitionPredict)).

(\#tab:moduleOutputs-fireSense-ignitionPredict)(\#tab:moduleOutputs-fireSense-ignitionPredict)List of (ref:fireSense-ignitionPredict) outputs and their description.

objectName	objectClass	desc
fireSense_IgAndEscapeProbRas	SpatRaster	Two layers, `ignitionProb` (expected ignitions per pixel) and `escapeProb`, at the resolution of `ignitionFitRTM`.
ignitionsAndEscapes	data.table	One row per ignited pixel, in random order: `pixelID` (cell index of `flammableRTM`), `igProb`, `ignitions`, `escapeProb`, `escapes` of the coarse pixel it was drawn from, and `escaped`, whether this ignition escaped: exactly `escapes` of a coarse pixel's rows are TRUE.

Links to other modules

Runs after fireSense_dataPrepPredict, which supplies the covariates. ignitionsAndEscapes is used by fireSense to start fires. It is normally run as part of the fireSense module group.

Getting help

• https://github.com/PredictiveEcology/fireSense_ignitionPredict/issues

References