Skip to content

New parameter spreadClimateSplit: the spread climate as a between-year and a within-year term - #108

Open
eliotmcintire wants to merge 2 commits into
developmentfrom
climateSplit
Open

eliotmcintire wants to merge 2 commits into
developmentfrom
climateSplit

Conversation

@eliotmcintire

@eliotmcintire eliotmcintire commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

The fire spread model uses one climate coefficient for both how dry a year is overall and how one place differs from the rest of the region within a year. This adds an option, off by default, that gives each its own coefficient, so a run can test whether year-to-year climate then explains more of the variation in fire size.

Affects: nothing changes unless a run sets spreadClimateSplit = TRUE; then the spread model has two climate terms in place of one, and the fit data are rebuilt.

Depends-on: PredictiveEcology/fireSenseUtils#244

Technical details

Part of one change with PredictiveEcology/fireSenseUtils#244, fireSense_spreadFit (PredictiveEcology/fireSense_spreadFit#132) and fireSense_spreadPredict (PredictiveEcology/fireSense_spreadPredict#44). Motivation: in ELF 6.6.2 the l_pow05 fit gives climate 2% of the between-year variance of the spread linear predictor (the random year effect takes the rest), although annual climate correlates 0.47-0.60 with annual fire size and area. The single coefficient is also pulled by the spatial gradient, which is confounded with fuel.

New parameter spreadClimateSplit (default FALSE). FALSE gives the same formula string as before (spreadFormula(RHS) is unchanged, so cache keys that hold it do not move; the parameter itself is in the prepSpreadFitData key, so that event re-runs once). TRUE:

  • the formula has <C>_yr + <C>_dev where it had <C> (fireSenseUtils::climateSplitCols()), for example ~ 1 + CMD_yr + CMD_dev + youngAge + ...;
  • annualSpreadCovariates(climateSplit = TRUE) replaces C in each year's table by C_yr, the year's median of C over that year's burnable pixels (burnablePixels, the ELF's flammable pixels: the pixels a prediction has), and C_dev = C - C_yr, with fireSenseUtils::splitSpreadClimate().

Design choice to confirm: the median is taken over the ELF's burnable pixels (the data year's landcoverDTs: flammable, land cover not 0; chosen with fireSenseUtils::climateSplitRefPixels(), the same function the prediction uses), not over the fitted fire-buffer pixels. A buffer median would be biased toward where fires occurred and a prediction cannot reproduce it, so the fit and the prediction would use different between-year values. The cost is one more climateRasterToDataTable() call (cached) over the burnable pixels, only when the option is on. With wholeLandscapeSpreadCovariates the two pixel sets are the same.

Sign rule and ranges: see fireSense_spreadFit#132 (names with CMD/MDC keep the lower bound 0 on both terms; Tmaxsm terms stay free; fixed ranges for both).

Checked, no change: fireSense_dataPrepPredict (its covariate table has the base climate; the ledger row's names carry the split). mod$spreadFormulaClimate and the hindcast path read the climate variable from the ledger through spreadFitLedgerInputs(), fixed in fireSenseUtils#244. A prediction needs no spreadClimateSplit setting. A fit reused from the ledger (doFit FALSE, e.g. a predict-only or hindcast job) keeps its own split: Init() sets mod$spreadClimateSplit from the ledger row's coefficient names (isClimateSplitCol()), and useClimateSplit(mod, Par) makes that win over the parameter when building the formula and the tables. A reused unsplit fit stays unsplit even with the parameter TRUE; a refit follows the parameter.

Overlap with the spreadInteractions work: that one also edits the formula builder (RHS, about line 1070) and the fit tables. This diff changes only the climate part of RHS: paste0(<climate terms>, collapse = " + "). It also adds climateSplitCols and splitSpreadClimate to the prepSpreadFitData .cacheExtra.

Merge order with the interaction PRs (PredictiveEcology/fireSenseUtils#242, #107, PredictiveEcology/fireSense_spreadFit#131, PredictiveEcology/fireSense_spreadPredict#43), whichever merges first: interaction terms must use fireSenseUtils::climateSplitCols(spreadVars), so CMD_yr:fuel and CMD_dev:fuel; and in fireSense_spreadPredict the interaction PR's needed <- spreadSourceCols(fitted) must come after the split block of spreadProbOneELF(), which makes CMD_yr and CMD_dev from CMD.

Reuses: fireSenseUtils::climateSplitCols(), splitSpreadClimate(), climateSplitRefPixels(), isClimateSplitCol(), climateRasterToDataTable() (the call is now a small local function climateAt() used for the fitted pixels and the burnable pixels), burnablePixelsByFireYear() output; new: nothing in this module (the shared logic is in fireSenseUtils).

Tests (in test-wholeLandscapeSpreadCovariates.R, which has the annual-table fixture): with the split, the tables have CMD_yr (the median over burnable pixels 1:16, not over the buffer pixels), constant within a year, CMD_dev = CMD - CMD_yr, no CMD, and the same rows; the default formula string ~ 1 + CMD + youngAge + class1 + class2 is unchanged and TRUE gives ~ 1 + CMD_yr + CMD_dev + youngAge + ...; the parameter defaults to FALSE. test-metadata.R has the new parameter name. Reuse tests in test-spreadClimateOwnELF.R (a ledger fit with CMD_yr/CMD_dev and the parameter FALSE gets the split; an unsplit fit with TRUE stays unsplit; a refit follows the parameter) and the formula test with mod$spreadClimateSplit. Full suite on the branch: 0 failures, 0 errors, 1 skip (dataPrepBuild cold/warm cache, as on base), 563 passed. On base (origin/development with the new tests copied in): 2 failures and 5 errors, all in the new tests, 1 skip, 526 passed. Ran against the fireSenseUtils branch loaded with pkgload::load_all(), in a SpaDES.core::convertToPackage() copy.

No version bump. The reqdPkgs floor on fireSenseUtils is set after #244 merges and its version is bumped.

🤖 Generated with Claude Code

https://claude.ai/code/session_014G18Mik3fH4z5M5CyMSUS6

…etween-year and a within-year term

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014G18Mik3fH4z5M5CyMSUS6
@eliotmcintire eliotmcintire added enhancement New feature or request backwards compatible Existing code and results keep working unchanged labels Nov 17, 2026
…me from fireSenseUtils::climateSplitRefPixels(); cell labels from elfCellLabels()

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014G18Mik3fH4z5M5CyMSUS6

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

backwards compatible Existing code and results keep working unchanged enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant