fireSense_spreadFit.RmdEliot 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]
Fit statistical models that can be used to parameterize the fire spread component of simulation models (e.g., fireSense (Marchal, Steve G. Cumming, et al. 2017b; Marchal, Steve G. Cumming, et al. 2017a; Marchal et al. 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.
The fit is a differential evolution search (DEoptim, run by fireSenseUtils::runDEoptim() on a cluster built by the clusters package).
Each candidate parameter set is scored by simulating the historical fires and comparing simulated with observed fire sizes (fireSenseUtils::.objfunSpreadFit()).
The 5 best parameter sets, and the covariate ranges used to rescale the covariates, are written as one row per polygon to a shared “fit ledger” on Google Drive (spreadFitFilename in spreadFitGoogleDriveFolder), keyed by .ELFind.
If the ledger already holds a row for the polygon, the module uses it; otherwise it fits.
The parameter doFit changes that: NA (default) does whatever is needed, as just described; TRUE always fits; FALSE never fits and stops with an error if the ledger has no row for the polygon.
doFit
doFit = TRUE forces a fit for this polygon even when the ledger already holds a row for it.
Use it when the fit’s INPUTS have changed – new land cover, new vegetation parameters, a new objective
function – so the stored row is stale and the polygon must be fitted again.
It is intended for developers who have access to at least 40 cores: it triggers a
full DEoptim run (see cores and nCoresNeeded), which is not practical on a small machine.
refitExisting and stopIfNoPreRunFit are deprecated: refitExisting = TRUE is doFit = TRUE and
stopIfNoPreRunFit = TRUE is doFit = FALSE. Setting either prints a message naming doFit.
The covariate tables, fire buffers, fire points and formula are made by fireSense_dataPrepFit.
fireSense_spreadFormula must be supplied; .ELFind defaults to .runName.
Table 1 shows the full list of module inputs.
| 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 (spreadFitFilename in spreadFitGoogleDriveFolder), which fireSense_dataPrepFit matches against the polygon ids carried by rasterToMatchELF. It must therefore be the polygon’s identity, not a run label: .runName encodes the whole scenario (climate period, GCM, SSP, rep) in some projects, and keying the ledger on it writes rows no other run can find and trips dataPrepFit’s id match. Defaults to the .runName parameter.
|
NA |
| fireBufferedListDT | list | list of data.tables with fire id, pixelID, and buffer status | 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 |
| spreadFitAdditionalColNames | character |
Names of the list-columns of the ledger row. Reset to fireSenseUtils::spreadFitAdditionalColNamesTxt if different.
|
NA |
| fireSense_spreadFormula | character |
a formula that contains the annual and non-annual covariates e.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 |
| flammableRTM | SpatRaster |
Flammable (1) land of rasterToMatch in the latest vegetation year, from fireSense_dataPrepFit. The "powerLaw" link is calibrated on it. Not used with the other links.
|
NA |
| spreadFirePoints | sf |
list of sf points, one element per year, of fire ignition locations, with each fire’s area on burnable pixels (column fireSenseUtils::burnableHaTxt), its target size.
|
NA |
| studyAreaWithSpreadParams | sf |
Rows of the shared fit ledger, set by fireSense_dataPrepFit; init checks them for a fit of this polygon. Declared as an input so the event’s cache key includes it, otherwise a cache hit restores an older copy over the current rows.
|
NA |
| studyArea | sf | Polygon being fit; its geometry and crs go in the ledger row. Defaults to NWT. | https://drive.google.com/open?id=1LUxoY2-pgkCmmNH5goagBp3IMpj6YrdU |
Summary of user-visible parameters (Table 3)
| paramName | paramClass | default | min | max | paramDesc | cacheKey |
|---|---|---|---|---|---|---|
| .plots | characte…. | NA | NA |
Plot types passed to Plots(), e.g. ‘png’ or ‘screen’; NULL or NA for none.
|
TRUE | |
| .plotInterval | numeric | 25 | NA | NA |
DEoptim generations between DEoptim progress figures; the final figures are always drawn. Passed to fireSenseUtils::runDEoptim() as plotEvery.
|
TRUE |
| convergence | list | NA | NA |
When DEoptim stops early, a list with any of window, minGenerations, se, sdChange (see clusters::deoptimConvergence()). What is missing comes from options(clusters.deoptimConvergenceWindow, clusters.deoptimMinGenerations, clusters.deoptimConvergenceSE, clusters.deoptimConvergenceSDChange), then clusters’ defaults (300, 350, 1, 0.1). The resolved list is part of the fit’s cache key, and clusters keeps it out of the cache of each generation: a fit that stopped early continues from its cached generations when rerun with a stricter rule.
|
TRUE | |
| .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.
|
TRUE |
| .runInitialTime | numeric | 0 | NA | NA | when to start this module? By default, the start time of the simulation. | TRUE |
| .studyAreaName | character | NA | NA | NA | Human-readable name for the study area used. | TRUE |
| .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. | TRUE |
| cores | integer | 1 | NA | NA |
Passed to cores in fireSenseUtils::runDEoptim(): a number of local cores, or a character vector of machine names, one element per core wanted on that machine. Not part of this module’s cache keys: it changes where the work is done, not the result.
|
FALSE |
| DEoptimTests | character | crps | NA | NA |
'crps' (default): an objective of proper scores (per-fire CRPS on log size, adTest, areaDist, CRPS of the log total area, CRPS of the 10 largest fires; weights in crpsWeights; no annual-area term). Or any of 'adTest' (pooled Anderson-Darling on fire sizes) and 'pitAD' (rank-based Anderson-Darling: each fire’s observed size ranked among its replicates; does not depend on the fit buffers). The 2026-10-28 profile used 'crps' alone, with gateRefusal = 'simulate' and objfunFireReps = 100L. 'SNLL_FS' was removed and stops the fit. Passed to tests in fireSenseUtils::.objfunSpreadFit().
|
TRUE |
| crpsWeights | list | NA | NA |
Named list of the multipliers of the 'crps' objective’s terms: fire, adTest, areaDist, totalArea, top10. Names left out take fireSenseUtils::crpsWeightsDefault() (1, 0.34, 2.6, 164, 16.5: set by the 2026-10-28 profile on ELFs 6.6.2, 14.3 and 11.3). NULL (default) is all defaults. Passed to fireSenseUtils::runDEoptim(); unused without 'crps' in DEoptimTests.
|
TRUE | |
| gateRefusal | character | minLik | NA | NA |
What a year that fails the spread-probability gates gets in the objective: ‘minLik’ (default) is not simulated and scores the floor; ‘simulate’ simulates and scores it like any other year. Passed to fireSenseUtils::runDEoptim(), for any DEoptimTests.
|
TRUE |
| doFit | logical | FALSE | NA | NA |
Whether to fit this polygon. FALSE (default): never fit – use the ledger’s fit, 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 fit if it holds one for this polygon, otherwise fit. TRUE: always fit, replacing any ledger fit (a re-fit is a full DEoptim run, practical only with at least 40 cores; use it when the fit’s INPUTS changed – new land cover, vegetation parameters, objective).
|
TRUE |
| skipUnusedFitPrep | logical | TRUE | NA | NA |
TRUE (default): a job that uses the ledger’s fit and does not validate or hold out a fold (fireSenseUtils::fitDataNeeded(): not fitting, mode without “validate” or “profile”, no heldOutFold) does not schedule spreadFitPrepare, whose covariates only a fit, crossValidate and a profile read. A prediction reads the ledger row’s covMinMax_spread, covCentre_spread and climateRef_spread; only a ledger row without ranges (written before covMinMax_spread) falls back on sim$covMinMax_spread. FALSE: always schedule spreadFitPrepare, as before this parameter existed. The same parameter of fireSense_dataPrepFit: set it for both with .globals = list(skipUnusedFitPrep = FALSE). Not part of the cache keys. The modules must agree on it and on doFit.
|
FALSE |
| doObjFunAssertions | logical | FALSE | NA | NA |
Passed to fireSenseUtils::.objfunSpreadFit(); TRUE runs diagnostics but is slower; FALSE for operational runs. The default follows options(fireSenseUtils.assertions = ).
|
TRUE |
| 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
|
TRUE | |
| initialPopMethod | character | calibration | NA | NA |
Where DEoptim’s starting population comes from. ‘calibration’ (default; the name is historical): DEoptim’s own draw, or, when no member of it passes the objective’s spreadProb gates, a start of gate-passing draws. ‘emulator’: nCoresNeeded good, spread-out points evaluated by a Gaussian-process emulator search of the fit’s objective (~1,000-1,600 real evaluations on the fit’s cores, between lower and upper, wide one-sided parameters on a log1p scale; a global phase, then trust-region rounds; see emulatorControl). The search is cached. The fit then stops by the same rule as any other (convergence). The initialpop parameter, when set, wins over both.
|
TRUE |
| emulatorControl | list | NA | NA |
Settings of the emulator search (initialPopMethod = 'emulator'), by name; what is missing comes from emulatorDefaults(): the design size (designPerParam, 20), the budget (globalMaxEvals 1000, maxEvals 1600, minEvals 600), the global phase’s stopping rule (globalWindow, relTol), the response caps (globalCapRatio, localCapRatio), the log1p rule (logSpanMin), the trust-region rounds (trustRoundBatches, localTopFrac, localWiden, trustTolSD, trustShrink, trustExpand, trustSuccessTol, trustFailureTol, trustMinWidth), the starting population’s pool and spacing (popPoolFrac, popMinDist) and the most evaluations the GP is fitted to (gpMaxPoints, 400: the best points and the most spread out of the rest; Inf fits all of them, slower with the workers idle). Part of the search’s cache key.
|
TRUE | |
| emulatorMaxParams | integer | 18 | 1 | NA |
With more fitted parameters than this, initialPopMethod = 'emulator' falls back to ‘calibration’, with a message: a GP in that many dimensions needs more evaluations than the search saves.
|
TRUE |
| iterDEoptim | integer | 5000 | NA | NA | integer defining the maximum number of iterations allowed (DEoptim optimizer). A ceiling: clusters (>= 0.0.46) stops the fit earlier, once the population’s median value has stopped improving. | TRUE |
| libPathDEoptim | character | NA | 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. A vector is allowed (a dev library, then a stable one); all are shipped to the workers, in order. NA (default) means .libPaths() when the fit runs (clusters ships the user libraries, not R’s own), so the default is not a path of one machine or one install. Not part of this module’s cache keys, nor of the fit’s: it says where the workers load packages from, not what they compute.
|
FALSE |
| lower | numeric | NA | NA | NA |
see ?DEoptim. Lower limits for the logistic function parameters (maxAsymptote, then upperTail1 if link is ‘logistic3pUpper’) and the statistical model parameters (named in the order they appear in the formula). Do not include hillSlope1 or inflectionPoint1: they are fixed at 1, not fitted (see estimateSpreadParams()); supplying either is an error.
|
TRUE |
| maxFireSpread | numeric | 0.276 | NA | NA |
optional. Maximum fire spread average to be passed to the .objFun; default fireSenseUtils::spreadProbCeiling, also the upper bound of maxAsymptote. maxAsymptote is the spread-probability ceiling in a typical year. The year random effect (yearSpreadSD) is added on the logit of the final spread probability, after the link, so in a given year p can exceed maxAsymptote or fall below lowerSpreadProb; that is intended, and there is no absolute cap because spreadCpp does not need one. maxAsymptote is bounded because runaway fires are slow to simulate and wasted if the parameters are wrong.
|
TRUE |
| link | character | logistic3p | NA | NA |
The spread link. ‘logistic3p’, or ‘logistic3pUpper’: the same curve with Stukel’s upper tail, one more parameter upperTail1 that changes only how the curve approaches its ceiling (fireSenseUtils::logistic3pUpper()). Its default bounds are upperTailBounds.
|
TRUE |
| spreadLink | character | powerLaw | NA | NA |
Where climate enters the spread probability (fireSenseUtils::spreadProbFromCovs()). ‘powerLaw’ (default): see below. ‘ceiling’: climate is a covariate inside the logistic, under the maxAsymptote ceiling, the link before ‘powerLaw’ became the default – its fits and cache keys are unchanged. ‘climateOutside’: the logistic, with its ceiling, is fitted to the other covariates only (intercept, fuels, youngAge, non-forest), giving p0; the climate term is added on the logit after it, p = plogis(qlogis(p0) + beta_clim (climate - climateRef)), uncapped, and the year effect yearSpreadSD (eps_Y) on the same logit. Where fuel put a pixel near the ceiling, climate could add almost nothing under ‘ceiling’ (2026-10 hindcasts: 59-77% of pixels within 0.01 of the ceiling every year, spread nearly the same in every year). climateRef is the mean of each climate covariate over the fit’s pixel-years (fireSenseUtils::spreadClimateRef(), sim$climateRef_spread), stored in the ledger row with this choice (fireSenseUtils::spreadFitClimateRefTxt, spreadLinkTxt) so fireSense_spreadPredict applies the same link; a row without them is ‘ceiling’. The objective’s gates and saturation summary then look at p0. The sign constraint on the climate coefficient is unchanged. Needs a climate covariate in the formula (fireSenseUtils::spreadClimateCols()). ‘powerLaw’: the link from a percolation calibration, p = p_c - (p_c - lowerSpreadProb) exp(-x / powerLawGamma), with x the linear predictor and p below 0 set to 0 (fireSenseUtils::powerLawLink()). The calibration (fireSenseUtils::calibratePowerLaw(), on flammableRTM, once per ELF) runs when the job fits or validates, not when it uses the ledger row: its p_c50, the spread probability at which half the fires burn a quarter of the largest flammable patch, sets the bounds of p_c (fireSenseUtils::powerLawPcBounds(): lowerSpreadProb + 0.01 to p_c50 + powerLawPcMargin), so a fit never tries thresholds far above the ELF’s own. maxAsymptote is p_c, fitted; the year effect yearSpreadSD is added to x, not to the logit of p, so no year takes p past p_c. Stored in the ledger row with powerLawGamma (fireSenseUtils::spreadLinkTxt, spreadFitPowerLawGammaTxt) so fireSense_spreadPredict applies the same link. Not with link = 'logistic3pUpper'. ‘powerLaw’ treats lowerSpreadProb as p at x = 0, not as a lower asymptote: p falls to 0 for a low enough x, so such cells cannot burn and escaped fires stop early in low-spread years. ‘powerLawSmooth’: the same curve for x >= 0 (so the same calibration, powerLawGamma, powerLawShape and bounds of p_c), and for x < 0 p falls from lowerSpreadProb towards the lower asymptote lowerAsymptote, never below it (fireSenseUtils::powerLawSmoothLink()). ‘richards’: a generalized logistic between lowerAsymptote and p_c with the fixed shape richardsNu (0 is Gompertz) and the fixed scale 1 / fireSenseUtils::spreadPowerLawGamma (fireSenseUtils::richardsLink()). It does not use the calibration (not run, powerLawGamma ignored and not written to the ledger), and bounds p_c by fireSenseUtils::spreadPowerLawPcBounds. Both are fitted like ‘powerLaw’: maxAsymptote is p_c and yearSpreadSD is added to x; the ledger row records the link, lowerAsymptote and (with ‘richards’) richardsNu (fireSenseUtils::spreadFitLowerAsymptoteTxt, spreadFitRichardsNuTxt).
|
TRUE |
| powerLawGamma | numeric | NA | NA | NA |
The exponent gamma of spreadLink = 'powerLaw'. NA (default): the calibrated value for the ELF’s flammable map. A number overrides gamma only (the bounds of p_c still come from the calibration). It is fixed, not fitted: it is exactly confounded with the scale of the coefficients. Ignored with the other links.
|
TRUE |
| powerLawShape | numeric | 1 | NA | NA |
The curvature exponent shape of spreadLink = 'powerLaw': p = p_c - (p_c - lowerSpreadProb) exp(-sign(x) abs(x / powerLawGamma)^shape) (fireSenseUtils::powerLawLink()). 1 (default) is the original exponential approach to p_c. A shape above 1 gives a lower p for a moderate x and a p closer to p_c for a large x, so extreme pixels and years can burn large without the medium ones burning too much. Fixed, not fitted. At 1 it is left out of the cache keys; the ledger row gets fireSenseUtils::spreadFitPowerLawShapeTxt with a powerLaw fit. Ignored with the other links.
|
TRUE |
| lowerAsymptote | numeric | 0.13 | NA | NA |
The lower asymptote L of spreadLink = 'powerLawSmooth' or ‘richards’, from fireSenseUtils::spreadLowerAsymptoteMin (0.001) to fireSenseUtils::spreadProbFloor (0.13, the default), checked by fireSenseUtils::checkLinkParams(). Never 0: a fire under its minSize keeps trying to spread until it has reached it, which with a probability near 0 takes an unbounded number of generations. Fixed, not fitted. Ignored with the other links. The spread-probability gates use it as their lower bound with these links.
|
TRUE |
| richardsNu | numeric | 0.5 | NA | NA |
The shape nu of spreadLink = 'richards', 0 or more: p = L + (p_c - L) / (1 + nu exp(-x / fireSenseUtils::spreadPowerLawGamma))^(1 / nu); 0 is the Gompertz curve, 1 the logistic. Fixed, not fitted. Ignored with the other links.
|
TRUE |
| powerLawPcMargin | numeric | 0.005 | NA | NA |
With spreadLink = 'powerLaw' or ‘powerLawSmooth’, the upper bound of p_c is the calibrated p_c50 plus this (fireSenseUtils::powerLawPcBounds()). Written to the ledger row.
|
TRUE |
| powerLawFires | integer | 400 | NA | NA |
Fires per spread probability in the calibration (fireSenseUtils::calibratePowerLaw()). 400 took 5-10 minutes on 16 cores.
|
TRUE |
| powerLawPGrid | numeric | 0.15, 0….. | NA | NA | The spread probabilities the calibration simulates; the default brackets p_c50 of 0.22-0.32. | TRUE |
| mode | character | fit | NA | NA |
Options: debug, fit, visualize, validate, profile. Can use multiples. ‘debug’ runs the objective function with visuals instead of DEoptim; ‘fit’ runs DEoptim; ‘visualize’ adds the debug and plot events after the fit; ‘validate’ adds crossValidate, two more fits, each on half the years, predicting the other half (sim$spreadFitHeldOut). Validation never writes the ledger, but does write sim$spreadFitHeldOut to outputPath(sim), since a batch run typically stops after crossValidate and the simList is discarded. See heldOutFold to run a single fold as its own job instead of both folds together. ‘profile’ replaces everything else: no fit, only spreadFitPrepare and profileFromLedger, which profiles this ELF’s ledger fit at profileAt (profileLedgerFit(), sim$spreadFitProfile, also written to outputPath(sim)); doFit is not consulted and the ledger is not written.
|
TRUE |
| heldOutFold | integer | NA | NA | NA |
NA (default): unchanged behaviour, governed by mode. 1 or 2: run ONLY that cross-validation fold, as its own job. init then schedules spreadFitPrepare and crossValidate – never run, so the full fit and the ledger write never happen, and the ledger (doFit) is not consulted. crossValidate fits on the OTHER fold’s years and scores this fold’s held-out years (cvFolds() in R/fitSpread.R), and writes spreadFitHeldOut_<.runName>_fold<heldOutFold>.rds instead of spreadFitHeldOut_<.runName>.rds. A run script stops after crossValidate: events = list(.stopAfter = list(fireSense_spreadFit = "crossValidate")). Any other value is an error.
|
TRUE |
| profileReps | integer | 10 | NA | NA |
After the fit, each covariate coefficient in turn is set to 0 and to 5 values across the final population, the others held at the best member, and each point is evaluated this many times (fireSenseUtils::profileCoefficients()). About 6 nCoefficients profileReps evaluations, on the fit’s workers. It decides which coefficients are identified in isolation (sim$spreadFitIdentifiability). 0 skips it.
|
TRUE |
| profileAt | numeric | NA | NA | NA |
Mode ‘profile’: the values each coefficient of profileCoefs is set to in turn, the others held at the ledger fit’s best set, e.g. c(-20, -10, -5, -2, -1, 0, 1, 2, 5, 10, 20). They may lie outside the fit’s bounds. Each is evaluated profileReps times.
|
TRUE |
| profileCoefs | character | NA | NA | NA |
Mode ‘profile’: the covariate coefficients to profile. NA: all of them; “fuel”: the fuel biomass coefficients.
|
TRUE |
| mutuallyExclusiveCols | list | c(“class…. | NA | NA |
a named list of mutually exclusive covariates - see fireSenseUtils::makeMutuallyExclusive
|
TRUE |
| nCoresNeeded | integer | NA | NA |
How many workers to request for the DEoptim cluster. This IS the population size: clusters::clusterSetup() sets NP to the workers it builds. NULL takes fireSenseUtils::deoptimPopulationSize() of the number of parameters: 30 for 4-7, 40 for 8-12, 50 for 13-15 (40 was a good middle in tests of 10 per parameter against other sizes, with little gain above it; current ledgers have 10-12 parameters). A generation costs the slowest of NP evaluations and that barely falls as NP falls, so a smaller NP buys throughput by allowing more fits at once rather than by shortening generations (measured 2026-09-16).
|
TRUE | |
| simulateMembers | integer | 10 | NA | NA |
After the fit, this many best members simulate the observed fires, for sim$spreadFitSizes and sim$spreadFitLinkSaturation; also the members each crossValidate fold predicts with. 0 skips it after the fit.
|
TRUE |
| sizeLik | character | t | NA | NA |
Likelihood of fire size in the objective, ‘kde’ or ‘t’ (or ‘kernel’, the kernel log score on the log scale, fireSenseUtils::kernelLogScore()), passed to fireSenseUtils::runDEoptim(). ‘t’ with weighted = FALSE predicted held-out years best in the 2026-09-21 cross-validation.
|
TRUE |
| escapeSizeHa | numeric | 50 | NA | NA |
Size (ha) a fire must reach to count as escaped. The spread model is fitted to escaped fires only, and each simulated fire first grows to this size with its own spread probabilities (its burning cells stay active until it gets there), then spreads normally. NULL or NA gives the old fit (any fire over 1 pixel). Passed to fireSenseUtils::runDEoptim(). Written to the ledger row with fireCauses (fireSenseUtils::escapeDefinition()); it must equal the same parameter of the other fireSense modules (SpaDES.core::paramCheckOtherMods(), an error if it does not).
|
TRUE |
| fireCauses | character | natural,…. | NA | NA |
Cause groups of the fires the fit’s escape definition counts (fireSenseUtils::escapeDefinition()). Written to the ledger row; it must equal the same parameter of the other fireSense modules (SpaDES.core::paramCheckOtherMods(), an error if it does not).
|
TRUE |
| sizeLikDf | numeric | 5 | NA | NA | Degrees of freedom of the ‘t’ size likelihood. | TRUE |
| weighted | logical|…. | FALSE | NA | NA |
Weight of each fire in the size likelihood: FALSE (none), TRUE (log size) or ‘sqrt’. Passed to fireSenseUtils::runDEoptim().
|
TRUE |
| adWeight | characte…. | auto | NA | NA |
Weight of the Anderson-Darling term against the size likelihood; ‘auto’ is fireSenseUtils::adWeightAuto().
|
TRUE |
| yearAreaWeight | numeric|…. | auto | NA | NA |
Weight of the annual-area term in the objective: each fit year’s observed area burned is scored against that year’s simulated totals (one per replicate) with the size likelihood. 0 leaves it out; ‘auto’ (default) is (number of fitted fires) / (number of fit years), so the year view and the per-fire view weigh the same. Passed to fireSenseUtils::runDEoptim().
|
TRUE |
| areaDistWeight | numeric|…. | auto | NA | NA |
Weight of the area-weighted size-distribution term: simulated and observed fires compared by the share of area burned that fires up to each size make up (fireSenseUtils::areaWeightedCvM()). 0 leaves it out; ‘auto’ (default) uses the Anderson-Darling term’s weight (fireSenseUtils::adWeightAuto()).
|
TRUE |
| penaliseRunaways | logical | FALSE | NA | NA |
A simulated fire that burns an open edge pixel of its year’s buffers (one next to flammable land outside every buffer, fireSenseUtils::bufferOpen()) is cut: it has no density at the observed size in the size likelihood, and the other terms score the size it reached. TRUE also stops such a fire at the first open pixel of its own buffer, which saves time. Passed to fireSenseUtils::runDEoptim().
|
TRUE |
| wholeLandscapeSpread | logical | FALSE | NA | NA |
TRUE spreads every fire of the fit on all pixels of the covariate tables, with no buffer edge, so no fire is cut and every fire is scored at the size it burns. For tables of the whole ELF (fireSense_dataPrepFit, parameter wholeLandscapeSpreadCovariates); the spread probability is computed only on the cells a fire reaches, so an evaluation costs about what a buffered one does. Needs spreadLink “powerLaw”, “powerLawSmooth” or “richards” and penaliseRunaways = FALSE. Passed to fireSenseUtils::runDEoptim() and .objfunSpreadFit() as wholeLandscape. FALSE changes nothing, including the fit’s cache key. Refits need a new fitFileSuffix.
|
TRUE |
| runawayBufferMultiple | numeric | NA | NA | NA | Retired: a cut fire is scored at the size it reached. It set the size a runaway counted as in the Anderson-Darling, annual-area and area-distribution terms. fireSenseUtils ignores it, with a warning unless NA. | TRUE |
| runawayEdgeFrac | numeric | 0.01 | NA | NA |
Retired: fireSenseUtils (>= 0.2.3.9123) ignores it. A fire was a runaway when it burned at least max(runawayEdgeMin, ceiling(runawayEdgeFrac n)) of the n edge pixels of its own buffer; it is now cut at the first open edge pixel. Not part of the DEoptim cache key.
|
TRUE |
| runawayEdgeMin | integer | 3 | NA | NA |
Retired: fireSenseUtils (>= 0.2.3.9123) ignores it; see runawayEdgeFrac.
|
TRUE |
| jumpTries | numeric | 20 | NA | NA |
With escapeSizeHa: how many attempts a simulated fire that is still below the escape size, with no burnable neighbour left, may make to jump to burnable land nearby (SpaDES.tools::spreadCpp()). Default 20; 0 is off.
|
TRUE |
| jumpMeanDist | numeric | 3 | NA | NA |
Mean jump distance (pixels) for jumpTries; distances are exponential, truncated to 1.5-20 pixels. No effect while jumpTries is 0.
|
TRUE |
| 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. Not part of this module’s cache keys: it sets how many forks the objective uses, not its result.
|
FALSE |
| objfunFireReps | integer | 50 | NA | NA | integer defining the number of replicates the objective function will attempt each fire. | TRUE |
| .runName | character | NA | NA | NA | A short name for this fit, e.g. “4.3_NRV_370_1”. It labels the DEoptim run, its progress file and cache entries. | TRUE |
| .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. A SpaDES-aware parameter: SpaDES.project::setupProject() sets .globals$.rep from the experiment’s .rep.
|
TRUE |
| .c | numeric | 0 | NA | NA |
the c argument passed to DEoptim.control. iterStep is hard-coded to 1, so DEoptim’s adaptation restarts every generation, and c has no effect either way.
|
TRUE |
| DEoptimControl | list | 0.1 | NA | NA |
Further DEoptim.control() settings, e.g. list(CR = 0.7, F = 0.6), passed through fireSenseUtils::runDEoptim() to DEoptim. Names must be DEoptim.control() arguments. strategy, trace, initialpop and .c have their own parameters; NP is the number of workers the cluster gets. The default p = 0.1 is for strategy = 6.
|
TRUE |
| rescaleAll | logical | TRUE | NA | NA |
rescale covariates for DEOptim
|
TRUE |
| spreadFitGoogleDriveFolder | character | https://…. | NA | NA |
Google Drive folder url holding the shared fit ledger (spreadFitFilename).
|
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 "latest" readers read) only its own files and 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_ignitionFit, fireSense_dataPrepFit and fireSense_ELFs; set it for all with .globals = list(fitFileSuffix = ...). Ignored when spreadFitFilename names a file.
|
TRUE | |
| spreadFitFilename | character | latest | NA | NA |
File name of the shared fit ledger: an sf object with one row of fitted parameters per polygon. "latest" (the default) writes to the file named for this fit’s fire years and model, fireSenseUtils::spreadFitFilenameFor(), e.g. fireSenseParams_1985-2024_linearFuel.rds; readers then find it with fireSenseUtils::latestSpreadFits().
|
TRUE |
| sppEquivCol | character | LandR | NA | NA |
Column of each ledger row’s sppEquiv naming the species; used to rebuild the per-ELF lists after the fit writes its row. The same parameter of fireSense_dataPrepFit.
|
TRUE |
| fuelClassCol | character | FuelClass | NA | NA |
Column of each ledger row’s sppEquiv naming the fuel classes; used as sppEquivCol is. The same parameter of fireSense_dataPrepFit.
|
TRUE |
| strategy | integer | 6 | NA | NA |
Passed to DEoptim.control. 6 (DE/current-to-p-best/1) with p = 0.1 did best in a settings study (see NEWS).
|
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 |
| stopIfNoPreRunFit | logical | NA | NA | NA |
DEPRECATED, use doFit. TRUE is doFit = FALSE; FALSE (allow a fit) is doFit = NA. Overrides doFit = FALSE (the default), not doFit = NA or TRUE. Ignored when refitExisting is TRUE.
|
TRUE |
| 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.
|
TRUE |
| upper | numeric | NA | NA | NA |
see ?DEoptim. Upper limits for the logistic function parameters (maxAsymptote, then upperTail1 if link is ‘logistic3pUpper’) and the statistical model parameters (named in the order they appear in the formula). Do not include hillSlope1 or inflectionPoint1: they are fixed at 1, not fitted (see estimateSpreadParams()); supplying either is an error.
|
TRUE |
| useCache_DE | logical | TRUE | NA | NA |
should DEoptim use Cache? to do multiple independent runs, use FALSE
|
TRUE |
| verbose | numeric | 1 | NA | NA | optional. With increasing number, more verbosity. Level 1 is normal reproducible (e.g., Cache), level 2 includes objective function e.g., print median of spreadProb during calculations | TRUE |
| visualizeDEoptim | Path | /tmp/Rtm…. | NA | NA |
Directory where runDEoptim saves parameter plots every .plotInterval generations. Reset to figurePath(sim) unless its last folder is the module name.
|
TRUE |
| covFixedRange | list | c(0, 100…. | NA | NA |
Named list of c(min, max): the FIXED range every climate covariate is rescaled with, not the range of this polygon’s data. Default fireSenseUtils::climateCovRanges, the one table of climate ranges, which documents each variable’s units and says its values are provisional. CMDsm = c(0, 100) makes the covariate CMDsm / 100 in every polygon. With the data’s range, 1 meant a CMDsm of 104 in one polygon and 297 in another, so the coefficient could not be compared across polygons, and a polygon that never gets dry stretched its small range over [0, 1]. A climate covariate with no entry stops the fit; there is no fallback to the data’s range. youngAge, the nfLCC_ groups and the treedWetland indicator are always c(0, 1) (fireSenseUtils::spreadIndicatorRanges()). fireSense_spreadPredict rescales with the stored covMinMax_spread, so it follows.
|
TRUE |
| fireSpreadSDBounds | numeric | 0, 10 | NA | NA |
Bounds of fireSpreadSD, the sd of a per-fire random effect on spread (added to the linear predictor like yearSpreadSD; each fire draws its own eps), when lower/upper are not supplied. It comes just before yearSpreadSD in the bounds. Only a fit with wholeLandscapeSpread = TRUE can fit it (fireSenseUtils::runDEoptim() stops otherwise): with FALSE it is left out of the bounds, with a message, and the fit is what it was. NA turns it off.
|
TRUE |
| yearSpreadSDBounds | numeric | 0, 10 | NA | NA |
Bounds of yearSpreadSD, the sd of a per-year random effect on spread (fireSenseUtils::.objfunSpreadFit()), when lower/upper are not supplied. It is added to the linear predictor with spreadLink = 'powerLaw' (one unit there scales a year’s mean fire size by about e) and to the logit of spread probability with the other links. A seasonal departure: each year draws one eps, so all of a year’s fires burn hotter or cooler together, which widens the simulated fire-size distribution. The upper bound is wide so it never binds: power-law fits reached the former bounds of 1 and then 5 (6.6.1, 6.1.3, 6.2.3). NA turns it off.
|
TRUE |
| upperTailBounds | numeric | -1, 1 | NA | NA |
Bounds of upperTail1 when link is ‘logistic3pUpper’ and lower/upper are not supplied.
|
TRUE |
| upperAndLowerVal | numeric | 50 | NA | NA |
Bound given to each covariate coefficient (upper = this, lower = minus this) when upper or lower is not supplied. Bounds should be wide enough that they do not influence the fitted value; only the sign of drought-index, youngAge and fuel biomass terms is constrained (see estimateSpreadParams()). A held-out experiment (7 ELFs x 2 folds) found estimates up to 25.7 and youngAge medians down to -23.0 with the previous default of 9.
|
TRUE |
| upperAndLowerValFuel | numeric | 100 | NA | NA |
As upperAndLowerVal, for the fuel biomass covariates. They are biomass / 1e4, so their coefficients are larger than those of covariates rescaled to [0, 1]. The same held-out experiment found fuel estimates up to 54.5 (29 of 82 above 25) with the previous default of 60.
|
TRUE |
init: schedules spreadFitPrepare and, if the polygon needs a fit, run (or debug when mode includes "debug"; debug and plot after run when it includes "visualize");spreadFitPrepare: sets default lower/upper, computes covMinMax_spread and lociList, converts covariates to integers (x 1000);run: runs DEoptim (cached per generation) and writes the polygon’s row to the ledger;debug: evaluates the objective function without DEoptim;plot: histograms of the final population;With .plots set, histograms of the annual and non-annual covariates.
During the fit, runDEoptim() saves parameter histograms and trace plots to visualizeDEoptim after each generation.
Description of the module outputs (Table 5).
| objectName | objectClass | desc |
|---|---|---|
| covMinMax_spread | data.table |
data.table of covariates min and max
|
| climateRef_spread | list |
With spreadLink = 'climateOutside', the reference value of each climate covariate of the formula, on the rescaled (and, with an intercept, centred) scale: its mean over the fit’s pixel-years (fireSenseUtils::spreadClimateRef()), the climate at which the spread probability is the fuel ceiling’s p0. Given to the fit, the validation and the ledger row. NULL with spreadLink = 'ceiling'.
|
| powerLawCalibration | list |
With spreadLink = 'powerLaw', the result of fireSenseUtils::calibratePowerLaw() on flammableRTM: p50, gamma, R2 and the per-p table. p50 bounds p_c, gamma is the link’s unless powerLawGamma is a number; p50, R2 and the margin go to the ledger row (fireSenseUtils::spreadFitPowerLawPc50Txt, spreadFitPowerLawR2Txt, spreadFitPowerLawPcMarginTxt).
|
| covCentre_spread | list |
Named list, the mean of each rescaled covariate over the fitting data (fireSenseUtils::spreadCovCentre()), subtracted from it in the fit; NULL unless the formula has an intercept. Stored in the ledger row as fireSenseUtils::spreadFitCovCentreTxt, so fireSense_spreadPredict centres alike.
|
| DE | data.table |
list of DEoptim objects, one per generation, ordered by best objective value
|
| studyAreaWithSpreadParams | sf |
Rows of the shared fit ledger that intersect studyArea, including the row this fit writes: studyArea geometry, polygonID, and list-columns named by spreadFitAdditionalColNames (the 5 best parameter sets are in params).
|
| missingLCCgroupList | list |
Per ledger row of studyAreaWithSpreadParams (named by polygonID), its missingLCCgroup. Rebuilt by the run event after it writes this fit’s row, with fireSenseUtils::spreadFitLedgerInputLists(), so prediction in the same run finds this ELF. fireSense_dataPrepFit sets it, and the next four, from the ledger before the fit.
|
| nonForestedLCCGroupsList | list |
As missingLCCgroupList, each row’s nonForestedLCCGroups.
|
| sppColorVects | list |
As missingLCCgroupList, each row’s species colours.
|
| sppEquivs | list |
As missingLCCgroupList, each row’s sppEquiv, harmonized (LandR::sppHarmonize()).
|
| sppNameVectors | list |
As missingLCCgroupList, each row’s species names.
|
| fsSpreadFit_hists | ggplot |
histograms of each parameter used in DEoptim fitting.
|
| lociList | list |
per-year data.tables of fire start cells and sizes (area on burnable pixels), of the fires in fireBufferedListDT, from fireSenseUtils::makeLociList()
|
| spreadFitConvergence | data.table |
The objective across the fit’s generations (fireSenseUtils::fitConvergence()).
|
| spreadFitRescore | data.table |
The final population, one row per member, with the mean and sd of its replicated re-scores (reMean, reSD). The ledger’s parameter sets are the best of these.
|
| spreadFitIdentifiability | data.table |
One row per covariate coefficient: how tightly the population pins it (fireSenseUtils::coefIdentifiability()) and, with profileReps > 0, whether dropping it worsens the fit; identified = identified in isolation (fireSenseUtils::identifiedInIsolation()).
|
| spreadFitProfile | data.table |
The one-at-a-time profile around the best member (fireSenseUtils::profileCoefficients()): after a fit, or in mode ‘profile’ of the ledger fit at profileAt (profileLedgerFit()).
|
| spreadFitSizes | data.table |
Observed against simulated fire sizes of the fitted years (fireSenseUtils::scoreFireSizes()): bias, error, quantiles.
|
| spreadFitLinkSaturation | data.table |
Per member, the share of pixel-years at the spread-probability ceiling and the quantiles of spread probability (fireSenseUtils::linkSaturation()).
|
| spreadFitHeldOut | list |
mode ‘validate’, or heldOutFold in 1:2: sims, the held-out years simulated from the fit to the other years (column fold), and score, from fireSenseUtils::scoreFireSizes(). With heldOutFold, sims holds only that fold, and the list also has fit (the fold’s fitted parameters as a one-row ledger sf object, the same columns the run event writes, with all simulateMembers members in params), heldOutFold, fitYears, heldOutYears, formula (fireSense_spreadFormula) and link, so fireSense_spreadPredict can predict with the fold’s fit. Also written to file.path(outputPath(sim), currentModule(sim), "spreadFitHeldOut_<.runName>.rds") (mode ‘validate’) or "...spreadFitHeldOut_<.runName>_fold<heldOutFold>.rds" (heldOutFold).
|
Inputs come from fireSense_dataPrepFit. fireSense_spreadPredict uses studyAreaWithSpreadParams (the ledger rows) to predict spread probabilities.
## in a project that also runs fireSense_dataPrepFit
params <- list(fireSense_spreadFit = list(
cores = rep(c("hostA", "hostB"), each = 20), # host name repeated once per worker; or a number for localhost
nCoresNeeded = 40, # = DEoptim population size (NP)
iterDEoptim = 500,
mode = "fit"
))
objects <- list(.ELFind = "6.1.1") # polygon id used as the ledger key