5 fireSense_SpreadFit Module
5.1 Module Overview
5.1.1 Module summary
Fit statistical models that can be used to parameterize the fire spread component of simulation models (e.g., fireSense (Marchal et al. 2017b, a; 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.
5.1.2 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 5.1 shows the full list of module inputs.
| 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 5.3)
| 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 | /home/ru…. | 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 | /tmp/Rtm…. | 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 |
5.1.3 Events
- Module initialization;
- Prepare spread fit;
- debug;
- estimate threshold;
- run spreadFit;
- retrieve DEoptim;
- make
makefireSense_SpreadFitted; - plot;
5.1.6 Module outputs
Description of the module outputs (Table 5.5).
| 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 |
5.1.7 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.