title	fireSense_SpreadFit Manual
subtitle	v.1.0.1
date	Last updated: 2025-04-08
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_SpreadFit.bib
link-citations	true
always_allow_html	true

fireSense_SpreadFit Module

(ref:fireSense-SpreadFit) fireSense_SpreadFit

Authors:

Jean Marchal jean.d.marchal@gmail.com [aut], 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], Alex M. Chubaty achubaty@for-cast.ca [ctb]

Module Overview

Module summary

Fit statistical models that can be used to parameterize the fire spread component of simulation models (e.g., fireSense [@Marchal:2017a; @Marchal:2017b; @Marchal:2019]). This module implement a Pattern Oriented Modelling (POM) approach to derive spread probabilities from final fire sizes. Spread probabilities can vary between pixels, and thus reflect local heterogeneity in environmental conditions.

Module inputs and parameters

Describe input data required by the module and how to obtain it (e.g., directly from online sources or supplied by other modules) If sourceURL is specified, downloadData("fireSense_SpreadFit", "..") may be sufficient.

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

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

objectName	objectClass	desc	sourceURL
fireBufferedListDT	list	list of data.tables with fire id, pixelID, and buffer status	NA
rasterToMatch	SpatRaster	RTM without ice/rocks/urban/water. Flammable map with 0 and 1.	NA
fireSense_annualSpreadFitCovariates	data.table	table of climate and/or veg covariates, burn status, polyID, and pixelID	NA
fireSense_nonAnnualSpreadFitCovariates	data.table	table of veg covariates, burn status, polyID, and pixelID	NA
fireSense_spreadFormula	character	a formula that contains the annual and non-annual covariatese.g. `~ 0 + MDC + class2 + class3 + youngAge`.	NA
parsKnown	numeric	Optional vector of known parameters, e.g., from a previous `DEoptim` run.If this is supplied, then 'mode' will be automatically converted to 'debug'	NA
rasterToMatch	SpatRaster	template raster for study area	NA
spreadFirePoints	sf	list of spatial points objects representing annual fire centroids	NA
studyArea	sf	Study area for the prediction. Defaults to NWT.	https://drive.google.com/open?id=1LUxoY2-pgkCmmNH5goagBp3IMpj6YrdU

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

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

paramName	paramClass	default	min	max	paramDesc
.plots	characte....		NA	NA	Should outputs be plotted?
.plotSize	list	1600, 2000	NA	NA	List specifying height and width of plotting device (in pixels) used to plot DEoptim histograms when `visualizeDEoptim` is TRUE.
.runInitialTime	numeric	0	NA	NA	when to start this module? By default, the start time of the simulation.
.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.
.saveInitialTime	numeric	NA	NA	NA	optional. When to start saving output to a file.
.saveInterval	numeric	NA	NA	NA	optional. Interval between save events.
.useCache	logical	init	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.
cacheId_DE	character		NA	NA	An optional character string representing a `cacheId` to recover from the Cache. After `reproducible >= 2.0.10.9016`, this can be set to 'previous', meaning the Cache will get the previous item in the Cache that matches the `P(sim)$rep` (see that param)
cloudFolderID_DE	character		NA	NA	Passed to `cloudFolderID` in the `Cache(DEoptim...)` call.
cores	integer	1	NA	NA	non-negative integer. Defines the number of logical cores to be used for parallel computation. The default value is 1, which disables parallel computing.
DEoptimTests	character	SNLL_FS	NA	NA	Currently either `'SNLL_FS'` or `'adTest'` or a length 2 character vector of both. These are passed to `.objFunSpreadFit`
doObjFunAssertions	logical	TRUE	NA	NA	This is passed to `objFunSpreadProb`; TRUE will do some diagnostics but is slower; FALSE for operational runs
initialpop	numeric		NA	NA	A numeric matrix of dimensions `NCOL = length(lower)` and `NROW = NP`. This will be passed into DEoptim through `control$initialpop = P(sim)$initialpop` if it is not NULL
iterDEoptim	integer	500	NA	NA	integer defining the maximum number of iterations allowed (DEoptim optimizer).
iterStep	integer	25	NA	NA	Passed to runDEoptim
iterThresh	integer	96	NA	NA	Number of iterations for automated threshold calibration.
libPathDEoptim	character	/Users/a....	NA	NA	Absolute path specifying R package directory location to use when running DEotpim. NOTE: this path must be read/write accessible on ALL machines used for fitting (identified in cores). Therefore, it's best use a directory in your user's `~` directory. If the directory does not exist at this path, will attempt to create it.
lower	numeric	NA	NA	NA	see `?DEoptim`. Lower limits for the logistic function parameters (lower bound, upper bound, slope, asymmetry) and the statistical model parameters (named in the order they appear in the formula).
maxFireSpread	numeric	0.28	NA	NA	optional. Maximum fire spread average to be passed to the `.objFun`.This puts an upper limit on `spreadProb` during optimization.
mode	character	fit	NA	NA	Options: debug, fit, visualize. Can use multiples. 'debug' will trigger running of the objective function with visuals; 'fit' will trigger DEoptim; 'visualize' will trigger visualization after DEoptim. For 'visualize', DE object must be findable, either in sim, on disk or a cloud URL. These last 2 can be specified with `urlDEOptimObject` param.
mutuallyExclusiveCols	list	c("class....	NA	NA	a named list of mutually exclusive covariates - see `fireSenseUtils::makeMutuallyExclusive`
NP	integer		NA	NA	Number of Populations. See `?DEoptim.control`.
objFunCoresInternal	integer	1	NA	NA	Integer defining the number of cores to pass to `mcmapply(mc.cores = ...)` This will fork this many to do the years loop internally. This would be in addition to `cores` and is effecively a multiplier. The computer needs to have `cores objFunCoresInternal` threads or it will stall.
objfunFireReps	integer	100	NA	NA	integer defining the number of replicates the objective function will attempt each fire. Since the default approach is using `EnvStats::demp`, it should be at least 100 to get a smooth distribution for a likelihood.
onlyLoadDEOptim	logical	FALSE	NA	NA	optional. If TRUE, the module will skip the fitting altogether and will only load the latest uploaded version of the `DEOptim` object
rep	integer	1	NA	NA	An optional integer indicating which replicate run this represents. This is used to identify unique runs of `runDEoptim`, from a Cache perspective. For example, if this module is run twice with all the same data, Cache will think that the second run should recover the cache result, unless this `rep` is modified
.c	numeric	0.5	NA	NA	the `c` argument passed to DEoptim.control
rescaleAll	logical	TRUE	NA	NA	rescale covariates for `DEOptim`
strategy	integer	3	NA	NA	Passed to `DEoptim.control`
SNLL_FS_thresh	integer		NA	NA	Threshold multiplier used in objective function SNLL fire size test.
trace	numeric	1	NA	NA	non-negative integer. If > 0, tracing information on the progress of the optimization are printed every `trace` iteration. Default is 1, i.e. every iteration. Setting to 0 turns off tracing.
upper	numeric	NA	NA	NA	see `?DEoptim`. Upper limits for the logistic function parameters (lower bound, upper bound, slope, asymmetry) and the statistical model parameters (named in the order they appear in the formula).
urlDEOptimObject	character	https://....	NA	NA	optional. If `onlyLoadDEOptim == TRUE`, you can pass the url to the `DEOptim` object. The default is the object from the run on 11JUN20 from the `logistic2p`
useCache_DE	logical	TRUE	NA	NA	should `DEoptim` use `Cache`? to do multiple independent runs, use FALSE
useCloud_DE	logical	FALSE	NA	NA	Passed to `useCloud` in the `Cache(DEoptim...)` call
verbose	logical	FALSE	NA	NA	optional. Should it calculate and print median of spread Probability during calculations?
visualizeDEoptim	Path	/private....	NA	NA	Passed to runDEoptim. This makes histographs at each iterStep and saves them to this path
upperAndLowerVal	numeric	6	NA	NA	This will be given to the upper and -lower values if not supplied by user

Events

• Module initialization;
• Prepare spread fit;
• debug;
• estimate threshold;
• run spreadFit;
• retrieve DEoptim;
• make makefireSense_SpreadFitted;
• plot;

Plotting

Write what is plotted.

Saving

Write what is saved.

Module outputs

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

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

objectName	objectClass	desc
covMinMax_spread	data.table	`data.table` of covariates min and max
DE	data.table	`DEOptim` object
fireSense_SpreadFitted	fireSense_SpreadFit	DEFUNCT -- A fitted model object of class fireSense_SpreadFit.
studyAreaWithSpreadParams	sf	This is the studyArea, but with 10 duplicated features, each with its own set of parameters from the 10 best DEoptim runs
fsSpreadFit_hists	ggplot	histograms of each parameter used in `DEoptim` fitting.
lociList	list	list of fire locs

Links to other modules

This module can be used in association with fireSense_SpreadPredict to derive fire spread probabilities that are sensitive to environmental conditions.

Getting help

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

References