title	fireSense_spreadPredict 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_spreadPredict.bib
link-citations	true
always_allow_html	true

fireSense_spreadPredict Module

(ref:fireSense-spreadPredict) fireSense_spreadPredict

Authors:

Eliot 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]

Module Overview

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:2017a; @Marchal:2017b; @Marchal:2019].

1. The covariates in fireSense_SpreadCovariates are rescaled to [0, 1] using covMinMax_spread, the range of the fitting data.
2. With the one parameter set (row of studyAreaWithSpreadParams$params[[i]]) chosen by .rep, 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.
3. fireSense_SpreadPredicted is that single set's prediction (sets are not averaged), and fireSense_SpreadSD its yearSpreadSD, on the flammableRTM grid.

Module inputs and parameters

Two objects from fireSense_spreadFit are read from the simList though they are not declared as inputs: studyAreaWithSpreadParams (the fitted parameters) and fireSense_spreadFormula (every term 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 @ref(tab:moduleInputs-fireSense-spreadPredict) shows the full list of module inputs.

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

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 @ref(tab:moduleParams-fireSense-spreadPredict))

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

paramName	paramClass	default	min	max	paramDesc
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.
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.
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.
.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.
.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.
.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: 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.

Module outputs

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

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

objectName	objectClass	desc
fireSense_SpreadPredicted	SpatRaster	Spread probability of each flammable pixel, this year.
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`.

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.

Getting help

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

References