diff --git a/NEWS.md b/NEWS.md index 6b1de7c..5cbfc5b 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,7 @@ # fireSense_spreadPredict (development version) +- A ledger row with an interaction coefficient (`a:b`, e.g. `CMD:dom_agb_Pice_mar`, from a `fireSense_spreadFit` fitted with `fireSense_dataPrepFit`'s `spreadInteractions = "climate:fuel"`) predicts with it: `spreadProbOneELF()` needs the covariates `a` and `b` (and their ranges in `covMinMax_spread`), and `fireSenseUtils::spreadProbFromIntegerCovs()` forms their product after each is rescaled and centred with the row's `covCentre_spread` entry for it (0 where `youngAge` cleared the fuel), and multiplies it by the coefficient, as the fit does. A row without interactions predicts exactly as before. Needs the fireSenseUtils version after the PR that adds `spreadSourceCols()` merges; the `reqdPkgs` floor is set after that merge. + - With `paramSets`: the cache of a parameter set's surface no longer reads all the values of `flammableRTM` and `rasterToMatchLargeELF` every replicate (a new raster object or a change at 1000 sampled cells is a change) and returns the stored surface without copying it (a changed stored surface is recomputed). On a 20-million-cell raster a replicate that reuses a surface takes 0.35 s instead of 0.9 s, most of it SpaDES. `paramSets` stops if the ledger rows have the simulated ELF twice, or if a file of ledger rows has none for it. - New parameters `paramSets` (path to an `.rds` or `.csv` of spread parameter vectors for the simulated ELF; default `NA`, behaviour unchanged) and `repsPerSet`. The sets replace the simulated ELF's ledger rows (neighbour ELFs keep theirs); replicate r uses set `ceiling(r / repsPerSet)`, calls `set.seed(k)` with k its number within the set (common random numbers across sets), and the surface is recomputed only when the set changes. The link, lower asymptote, `gamma` and covariate centres come from the ledger row; a set lacking a coefficient of the row stops. The set index is output in `fireSense_SpreadParamSet`. New input `.ELFind`, as in `fireSense_dataPrepPredict`. diff --git a/fireSense_spreadPredict.R b/fireSense_spreadPredict.R index 49a6ff8..ffc5d96 100644 --- a/fireSense_spreadPredict.R +++ b/fireSense_spreadPredict.R @@ -472,7 +472,9 @@ ELFblendWeights <- function(elfRas, template, pixelID, ids, width) { #' @param covCentre the ELF's `covCentre_spread` (`ledgerCovCentre()`): the covariate means the fit subtracted #' from the rescaled covariates; `NULL` (a fit without an intercept, or an older ledger row) centres nothing. #' A parameter set with `fireSenseUtils::spreadInterceptTxt` has an intercept, added as a column of 1s after -#' the covariates are rescaled and centred, as in the fit. +#' the covariates are rescaled and centred, as in the fit. A coefficient named `a:b` is an interaction: `covs` must +#' have `a` and `b`, and `fireSenseUtils::spreadProbFromIntegerCovs()` multiplies them after each is +#' rescaled and centred (0 where `youngAge` cleared the fuel), exactly as in the fit. #' @param climateRef the ELF's `climateRef_spread` (`ledgerClimateRef()`): with a fit made with climate outside the #' `maxAsymptote` ceiling (`fireSense_spreadFit`'s `spreadLink = "climateOutside"`), the reference value of each #' climate covariate; `fireSenseUtils::spreadProbFromCovs()` then applies that link, exactly as the fit did. @@ -522,7 +524,9 @@ spreadProbOneELF <- function(covs, params, covMinMax, yr, maxFireSpread, lowerSp ## the intercept, if the fit has one, is a coefficient with no covariate: it multiplies a column of 1s hasIntercept <- fireSenseUtils::spreadInterceptTxt %in% names(params) fitted <- setdiff(names(params), c(unlist(fireSenseUtils::logisticParamNames), fireSenseUtils::spreadInterceptTxt)) - noCov <- setdiff(fitted, names(covs)) + ## an interaction (`CMD:fuel`) is made from its two covariates by spreadProbFromIntegerCovs(), as in the fit + needed <- fireSenseUtils::spreadSourceCols(fitted) + noCov <- setdiff(needed, names(covs)) if (length(noCov)) { stop( moduleName, "> the fitted coefficients ", paste(noCov, collapse = ", "), @@ -534,10 +538,10 @@ spreadProbOneELF <- function(covs, params, covMinMax, yr, maxFireSpread, lowerSp ## the covariates this ELF was fitted with, not the spread formula's terms: they can differ (a hindcast ## rebuilds the formula from another year's land cover), and `covs` can hold more than this ELF's - covs <- covs[, c("pixelID", fitted), with = FALSE] + covs <- covs[, c("pixelID", needed), with = FALSE] ## spreadProbFromIntegerCovs() rescales only the columns of covMinMax: a fitted covariate it lacks would ## silently stay on its raw scale (x1000) - noRange <- setdiff(fitted, names(covMinMax)) + noRange <- setdiff(needed, names(covMinMax)) if (length(noRange)) stop(moduleName, "> covMinMax_spread has no range for the fitted covariate(s) ", paste(noRange, collapse = ", "), "; it has ", paste(names(covMinMax), collapse = ", "), @@ -547,7 +551,7 @@ spreadProbOneELF <- function(covs, params, covMinMax, yr, maxFireSpread, lowerSp shortAnnDTx1000 <- toX1000(list(covs))[[1]] |> setDT() colsToUse <- setdiff(names(covs), "pixelID") ## what the coefficients multiply: the intercept first, as in the fit (fireSenseUtils::spreadDesignCols()) - designCols <- c(if (hasIntercept) fireSenseUtils::spreadInterceptTxt, colsToUse) + designCols <- c(if (hasIntercept) fireSenseUtils::spreadInterceptTxt, fitted) ## youngAge is mutually exclusive with every other non-climate covariate, exactly as in the fit ## (fireSense_spreadFit::spreadFitPrep()): wherever youngAge is non-zero, fuel biomass, nfLCC_* diff --git a/tests/testthat/test-spreadInteractions.R b/tests/testthat/test-spreadInteractions.R new file mode 100644 index 0000000..0f6ef4d --- /dev/null +++ b/tests/testthat/test-spreadInteractions.R @@ -0,0 +1,77 @@ +## Fuel x climate interactions: a fitted coefficient named "MDC:fuelA" multiplies the product of the two +## centred covariates (0 where youngAge cleared the fuel), formed by the +## function the fit uses (fireSenseUtils::spreadProbFromIntegerCovs()). Toy covariates as in setup-toySpread.R: +## MDC / 200, youngAge, fuelA / 8 (fuelA / 8 uses the toy range 0..8, as in test-spreadProb-values.R). + +icptI <- fireSenseUtils::spreadInterceptTxt +paramsX <- function(intercept = NULL) { + p <- data.frame(maxAsymptote = 0.25, hillSlope1 = 2, inflectionPoint1 = 1, + MDC = 1.5, youngAge = -0.5, fuelA = 1, `MDC:fuelA` = -2, check.names = FALSE) + if (!is.null(intercept)) p <- cbind(p[1:3], stats::setNames(data.frame(intercept), icptI), p[4:7]) + p +} +insX <- function(...) toyInputs(params = paramsX(...), formula = "~ MDC + youngAge + fuelA + MDC:fuelA - 1") + +test_that("the interaction's coefficient multiplies the product of the rescaled covariates", { + cv <- toyCovariates() + o <- order(cv$pixelID) + mdc <- cv$MDC[o] / 200; ya <- cv$youngAge[o]; fuel <- cv$fuelA[o] / 8 + x <- 1.5 * mdc - 0.5 * ya + 1 * fuel - 2 * mdc * fuel + expect_equal(predVals(toyRun(insX()))[c(1, 2, 3, 4, 6, 7, 8)], handLogistic3(x), tolerance = 1e-7) + ## and it matters: without the term the prediction is another one + ref <- predVals(toyRun(toyInputs())) + expect_gt(max(abs(predVals(toyRun(insX())) - ref), na.rm = TRUE), 0.01) +}) + +test_that("with an intercept and centres, the interaction is the product of the centred covariates", { + centre <- list(MDC = 0.4, youngAge = 0.2, fuelA = 0.3) + ins <- insX(intercept = 0.4) + ins$studyAreaWithSpreadParams[[fireSenseUtils::spreadFitCovCentreTxt]] <- list(centre) + ins$fireSense_spreadFormula <- "~ 1 + MDC + youngAge + fuelA + MDC:fuelA" + cv <- toyCovariates() + o <- order(cv$pixelID) + mdc <- cv$MDC[o] / 200; ya <- cv$youngAge[o]; fuel <- cv$fuelA[o] / 8 + x <- 0.4 + 1.5 * (mdc - 0.4) - 0.5 * (ya - 0.2) + (fuel - 0.3) - 2 * (mdc - 0.4) * (fuel - 0.3) + expect_equal(predVals(toyRun(ins))[c(1, 2, 3, 4, 6, 7, 8)], handLogistic3(x), tolerance = 1e-7) +}) + +test_that("a fitted interaction whose covariate is missing stops, naming it", { + covs <- toyCovariates() + data.table::set(covs, j = "fuelA", value = NULL) + ins <- insX() + ins$fireSense_SpreadCovariates <- covs + expect_error(toyRun(ins), "fuelA") +}) + +test_that("the prediction is the fit's spreadProb for the same covariates, with fuel cleared where youngAge is 1", { + ## fuel arrives logged, with the fit's linear range; the fit takes it linear, per fire year, from the annual + ## (climate, youngAge) and non-annual (fuel) tables, as the objective does through spreadProbFromIntegerCovs() + covs <- toyCovariates() + biomass <- c(0, 0, 4000, 0, 8000, 8000, 2000) + data.table::set(covs, j = "fuelA", value = fireSenseUtils::logMinB(biomass)) + ins <- insX(intercept = -0.3) + ins$fireSense_SpreadCovariates <- covs + rng <- fireSenseUtils::fuelLinearRange + ins$covMinMax_spread <- data.table::data.table(MDC = c(0, 200), youngAge = c(0, 1), fuelA = rng) + centre <- list(MDC = 0.4, youngAge = 0.2, fuelA = 0.3) + ins$studyAreaWithSpreadParams[[fireSenseUtils::spreadFitCovCentreTxt]] <- list(centre) + v <- predVals(toyRun(ins)) + + lin <- data.table::copy(covs) + data.table::set(lin, j = "fuelA", value = fireSenseUtils::fuelLogToLinear(lin$fuelA)) + x1000 <- fireSenseUtils::toX1000(list(lin))[[1]] |> data.table::setDT() + ann <- x1000[, c("pixelID", "MDC", "youngAge"), with = FALSE] + nonAnn <- list(`2000` = x1000[, c("pixelID", "fuelA"), with = FALSE]) + cols <- fireSenseUtils::spreadDesignCols("~ 1 + MDC + youngAge + fuelA + MDC:fuelA") + used <- fireSenseUtils::spreadProbFromIntegerCovs( + NULL, ann, nonAnn, fireSenseUtils::nonAnnualIndex(nonAnn), 2001, ins$covMinMax_spread, + list(youngAge = "fuelA"), cols, FALSE, NULL, NULL, NULL, NULL, covCentre = centre) + p <- paramsX(intercept = -0.3) + covPars <- unlist(p[cols]) + fit <- fireSenseUtils::spreadProbFromCovs(as.matrix(used[, cols, with = FALSE]), unlist(p[1:3]), covPars, 0.13) + expect_equal(unname(v[used$pixelID]), as.numeric(fit), tolerance = 1e-9) + ## the fuel of the young pixels (cells 2 and 8) is cleared: centred it is -0.3, but its interaction is 0 + expect_equal(used$fuelA[used$pixelID == 8], -0.3) + expect_equal(used[["MDC:fuelA"]][used$pixelID == 8], 0) + expect_equal(used[["MDC:fuelA"]][used$pixelID == 3], (used$MDC[used$pixelID == 3]) * (0.4 - 0.3)) +})