From 80e83fc4e34316ae35e32a0d418aaf6638598737 Mon Sep 17 00:00:00 2001 From: Eliot McIntire Date: Fri, 13 Nov 2026 15:23:31 -0700 Subject: [PATCH 1/2] Predict from ledger rows with spreadLink "powerLawSmooth" and "richards" The row's link, lowerAsymptote_spread and richardsNu_spread are read and applied with fireSenseUtils::spreadProbFromCovs(). New output fireSense_SpreadLink names the link; fireSense_SpreadPowerLaw and fireSense_SpreadLinear are given for all three linear-predictor links, with the link's own parameter names. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_014G18Mik3fH4z5M5CyMSUS6 --- NEWS.md | 2 + fireSense_spreadPredict.R | 197 +++++++++++++++++++++--------- tests/testthat/test-metadata.R | 2 +- tests/testthat/test-smoothLinks.R | 110 +++++++++++++++++ 4 files changed, 255 insertions(+), 56 deletions(-) create mode 100644 tests/testthat/test-smoothLinks.R diff --git a/NEWS.md b/NEWS.md index 9b30c95..a9a928d 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,7 @@ # fireSense_spreadPredict (development version) +- A ledger row with `spreadLink` `"powerLawSmooth"` or `"richards"` (and its `lowerAsymptote_spread`, `richardsNu_spread`) is predicted with that link (`fireSenseUtils::spreadProbFromCovs()`); `"richards"` has no `gamma`. New output `fireSense_SpreadLink` names the link, and `fireSense_SpreadPowerLaw` and `fireSense_SpreadLinear` are given for all three linear-predictor links, with the link's own parameter names (`fireSenseUtils::spreadLinkParNames`). Fitted ELFs with different such links cannot be blended (an error). Needs fireSenseUtils with the links. + - The ledger's escape definition is checked with `fireSenseUtils::checkEscapeDefinition()` on the whole one-row-per-ELF table (the error names the ELF, not the row number), this run's definition is `fireSenseUtils::escapeDefinitionOf()`, and the random-effect names are `fireSenseUtils::fireSpreadSDTxt` and `yearSpreadSDTxt` (PredictiveEcology/fireSenseUtils#222), instead of local copies. Needs fireSenseUtils with that PR. - A ledger row with the new fitted parameter `fireSpreadSD` (the per-fire random-effect sd of `fireSense_spreadFit`) no longer stops with "have no covariate": `spreadProbOneELF()` drops every name in `fireSenseUtils::spreadRandomEffectTxt` from the fitted coefficients, so spread probabilities are unchanged. The value is a new output `fireSense_SpreadFireSD` for `fireSense_burn`, shaped like `fireSense_SpreadSD` (one number with one ELF, a blended raster with several; 0 for a row without it). New output `fireSense_EscapeDefinition` (one row per ELF) holds the escape definition recorded in the ledger (`fireSenseUtils::escapeDefinition()`), and each row is checked against this run's new parameters `escapeSizeHa` and `fireCauses` (shared with the other fireSense modules) with `fireSenseUtils::checkEscapeDefinition()`: a mismatch stops. A row without a recorded definition is not checked. Merge this before any fit writes `fireSpreadSD`. Needs fireSenseUtils#221. diff --git a/fireSense_spreadPredict.R b/fireSense_spreadPredict.R index 163c99c..3d7bd60 100644 --- a/fireSense_spreadPredict.R +++ b/fireSense_spreadPredict.R @@ -96,17 +96,26 @@ defineModule(sim, list( "`fireSenseUtils::escapeDefinition()`), one row per fitted ELF (with its `polygonID`);", "`NA` for a row fitted before the definition was recorded. Each row has been checked", "against this run's `escapeSizeHa` and `fireCauses`.")), + createsOutput(objectName = "fireSense_SpreadLink", objectClass = "character", + desc = paste("Only for a fit made with `spreadLink = \"powerLaw\"`, `\"powerLawSmooth\"` or `\"richards\"` (else", + "NULL): the link the ledger row records, for `fireSense_burn`. The names of", + "`fireSense_SpreadPowerLaw` are those of this link (`fireSenseUtils::spreadLinkParNames`). Fitted ELFs", + "with different such links cannot be blended: an error.")), createsOutput(objectName = "fireSense_SpreadPowerLaw", objectClass = "SpatRaster|numeric", - desc = paste("Only for a fit made with `spreadLink = \"powerLaw\"` (else NULL): `pc` (the row's", + desc = paste("Only for a fit made with `spreadLink = \"powerLaw\"`, `\"powerLawSmooth\"` or `\"richards\"` (else NULL):", + "the parameters of its link, named as `fireSenseUtils::spreadLinkParNames` says for", + "`fireSense_SpreadLink`, for `fireSense_burn`, which adds the year effect to the", + "linear predictor, as the fit does. \"powerLaw\": `pc` (the row's", "`maxAsymptote`), `gamma`, `floor` (`lowerSpreadProb`) and `shape` of", - "`fireSenseUtils::powerLawLink()`, for `fireSense_burn`, which adds the year effect to the", - "linear predictor, as the fit does. A numeric vector with one fitted ELF; with several, a", - "4-layer raster blended like `fireSense_SpreadSD`.")), + "`fireSenseUtils::powerLawLink()`; \"powerLawSmooth\" also `lower` (the row's", + "`lowerAsymptote`); \"richards\": `pc`, `lower`, `nu` (the row's `richardsNu`) and `B`.", + "A numeric vector with one fitted ELF; with several, a raster with one layer per name,", + "blended like `fireSense_SpreadSD`.")), createsOutput(objectName = "fireSense_SpreadLinear", objectClass = "SpatRaster", - desc = paste("Only for a fit made with `spreadLink = \"powerLaw\"` (else NULL): the linear predictor x of", + desc = paste("Only for a fit made with a link of `fireSenseUtils::spreadLinearLinks` (else NULL): the linear predictor x of", "each flammable pixel (covariates %*% coefficients), the step before", - "`fireSenseUtils::powerLawLink()` turns it into `fireSense_SpreadPredicted`; `NA` where that is.", - "A pixel with a negative x has a spread probability of 0, so `fireSense_burn` needs x itself to", + "the link (`fireSenseUtils::linearLinkProb()`) turns it into `fireSense_SpreadPredicted`; `NA` where that is.", + "With `\"powerLaw\"` a pixel with a negative x has a spread probability of 0, so `fireSense_burn` needs x itself to", "add the year effect there. With several ELFs, blended like `fireSense_SpreadPowerLaw`.")) )) ) @@ -199,16 +208,15 @@ spreadPredictRun <- function(sim) { if (NROW(sa) == 1L) { params1 <- paramSetForRep(sa$params[[1]], rep) - gamma1 <- ledgerPowerLawGamma(sa, 1L) - shape1 <- ledgerPowerLawShape(sa, 1L) - pred <- spreadProbOneELF(covs, params = params1, covMinMax = ledgerCovMinMax(sa, 1L, sim$covMinMax_spread), + lk1 <- ledgerLinkArgs(sa, 1L) + pred <- do.call(spreadProbOneELF, c(list(covs, params = params1, covMinMax = ledgerCovMinMax(sa, 1L, sim$covMinMax_spread), yr = time(sim), maxFireSpread = P(sim)$maxFireSpread, lowerSpreadProb = P(sim)$lowerSpreadProb, - covCentre = ledgerCovCentre(sa, 1L), climateRef = ledgerClimateRef(sa, 1L), - powerLawGamma = gamma1, powerLawShape = shape1) + covCentre = ledgerCovCentre(sa, 1L), climateRef = ledgerClimateRef(sa, 1L)), lk1)) for (nm in names(randomEffectOutputs)) sim[[nm]] <- randomEffectSDOf(params1, randomEffectOutputs[[nm]]) - sim$fireSense_SpreadPowerLaw <- powerLawParsOf(params1, gamma1, P(sim)$lowerSpreadProb, shape1) - if (!is.null(gamma1)) sim$fireSense_SpreadLinear <- linearPredictorRas(sim$flammableRTM, pred) + sim$fireSense_SpreadLink <- lk1$link + sim$fireSense_SpreadPowerLaw <- do.call(powerLawParsOf, c(list(params1, lowerSpreadProb = P(sim)$lowerSpreadProb), lk1)) + if (!is.null(lk1$link)) sim$fireSense_SpreadLinear <- linearPredictorRas(sim$flammableRTM, pred) } else { ids <- as.character(sa[[fireSenseUtils::polygonIDTxt]]) ## each ELF's weight at each pixel: static, so computed once @@ -221,26 +229,29 @@ spreadPredictRun <- function(sim) { warning("fireSense_spreadPredict: ", sum(none), " flammable pixels are more than ", P(sim)$ELFblendWidth, " m from every fitted ELF; they get no spread probability", call. = FALSE) acc <- numeric(NROW(covs)); wsum <- numeric(NROW(covs)); accSD <- matrix(0, NROW(covs), length(randomEffectOutputs), dimnames = list(NULL, names(randomEffectOutputs))) - accPL <- matrix(0, NROW(covs), length(powerLawParNames), dimnames = list(NULL, powerLawParNames)) + lks <- lapply(seq_along(ids), function(i) ledgerLinkArgs(sa, i)) + links <- unique(unlist(lapply(lks, `[[`, "link"))) + if (length(links) > 1L) + stop("fireSense_spreadPredict: the fitted ELFs have different spread links (", paste(links, collapse = ", "), + "), whose parameters cannot be blended", call. = FALSE) + sim$fireSense_SpreadLink <- links + linkParNames <- if (length(links)) fireSenseUtils::spreadLinkParNames[[links]] else character() + accPL <- matrix(0, NROW(covs), length(linkParNames), dimnames = list(NULL, linkParNames)) accX <- numeric(NROW(covs)) - gammas <- lapply(seq_along(ids), function(i) ledgerPowerLawGamma(sa, i)) - shapes <- lapply(seq_along(ids), function(i) ledgerPowerLawShape(sa, i)) - wsumPL <- numeric(NROW(covs)) ## weight of the power-law ELFs only + wsumPL <- numeric(NROW(covs)) ## weight of the ELFs with a linear-predictor link only for (i in seq_along(ids)) { these <- which(w[, i] > 0) if (!length(these)) next parsI <- paramSetForRep(sa$params[[i]], rep) - gammaI <- gammas[[i]] - p <- spreadProbOneELF(covs[these], params = parsI, covMinMax = sa$covMinMax_spread[[i]], + p <- do.call(spreadProbOneELF, c(list(covs[these], params = parsI, covMinMax = sa$covMinMax_spread[[i]], yr = time(sim), maxFireSpread = P(sim)$maxFireSpread, lowerSpreadProb = P(sim)$lowerSpreadProb, - covCentre = ledgerCovCentre(sa, i), climateRef = ledgerClimateRef(sa, i), - powerLawGamma = gammaI, powerLawShape = shapes[[i]]) + covCentre = ledgerCovCentre(sa, i), climateRef = ledgerClimateRef(sa, i)), lks[[i]])) rows <- these[match(p$pixelID, covs$pixelID[these])] acc[rows] <- acc[rows] + w[rows, i] * p$spreadProb accSD[rows, ] <- accSD[rows, ] + w[rows, i] * rep(vapply(randomEffectOutputs, function(txt) randomEffectSDOf(parsI, txt), numeric(1)), each = length(rows)) - if (!is.null(gammas[[i]])) { - accPL[rows, ] <- accPL[rows, ] + w[rows, i] * rep(powerLawParsOf(parsI, gammas[[i]], P(sim)$lowerSpreadProb, shapes[[i]]), each = length(rows)) + if (!is.null(lks[[i]]$link)) { + accPL[rows, ] <- accPL[rows, ] + w[rows, i] * rep(do.call(powerLawParsOf, c(list(parsI, lowerSpreadProb = P(sim)$lowerSpreadProb), lks[[i]])), each = length(rows)) accX[rows] <- accX[rows] + w[rows, i] * p$linearPredictor wsumPL[rows] <- wsumPL[rows] + w[rows, i] } @@ -253,11 +264,11 @@ spreadPredictRun <- function(sim) { sim[[nm]] <- rast(sim$flammableRTM) sim[[nm]][covs$pixelID[ok]] <- accSD[ok, nm] / wsum[ok] } - if (any(wsumPL > 0)) { ## a power-law fit: pc, gamma, floor and shape blended over the power-law ELFs; NA where there is none - sim$fireSense_SpreadPowerLaw <- rast(sim$flammableRTM, nlyrs = length(powerLawParNames)) - names(sim$fireSense_SpreadPowerLaw) <- powerLawParNames + if (any(wsumPL > 0)) { ## a power-law or Richards fit: the link's parameters blended over those ELFs; NA where there is none + sim$fireSense_SpreadPowerLaw <- rast(sim$flammableRTM, nlyrs = length(linkParNames)) + names(sim$fireSense_SpreadPowerLaw) <- linkParNames okPL <- ok & wsumPL > 0 - for (nm in powerLawParNames) + for (nm in linkParNames) sim$fireSense_SpreadPowerLaw[[nm]][covs$pixelID[okPL]] <- accPL[okPL, nm] / wsumPL[okPL] sim$fireSense_SpreadLinear <- linearPredictorRas(sim$flammableRTM, data.table(pixelID = covs$pixelID[okPL], @@ -334,11 +345,19 @@ ELFblendWeights <- function(elfRas, template, pixelID, ids, width) { #' `NULL` (any other link) is the link as it always was. #' @param powerLawShape the ELF's `powerLawShape_spread` (`ledgerPowerLawShape()`): the `shape` of the link, with #' `powerLawGamma`; 1 (the original link) by default. -#' @return `data.table` with `pixelID` and `spreadProb`, from the one parameter set in `params`; with -#' `powerLawGamma` also `linearPredictor`, the `x` that `spreadProb` is the power-law link of. +#' @param link the ELF's link when it is one of `fireSenseUtils::spreadLinearLinks` (`ledgerLinkArgs()`); `NULL` (any +#' other link). By default `"powerLaw"` when `powerLawGamma` is given, the link of a row written before the +#' others existed. +#' @param lowerAsymptote,richardsNu the ELF's `lowerAsymptote_spread` and `richardsNu_spread` (`ledgerLowerAsymptote()`, +#' `ledgerRichardsNu()`): with `"powerLawSmooth"` and `"richards"`, the lower asymptote, and `nu` of `"richards"`. +#' @return `data.table` with `pixelID` and `spreadProb`, from the one parameter set in `params`; with a `link` +#' also `linearPredictor`, the `x` that `spreadProb` is the link of. spreadProbOneELF <- function(covs, params, covMinMax, yr, maxFireSpread, lowerSpreadProb, covCentre = NULL, climateRef = NULL, powerLawGamma = NULL, - powerLawShape = fireSenseUtils::spreadPowerLawShape) { + powerLawShape = fireSenseUtils::spreadPowerLawShape, + link = if (!is.null(powerLawGamma)) "powerLaw", + lowerAsymptote = fireSenseUtils::spreadProbFloor, + richardsNu = fireSenseUtils::spreadRichardsNu) { moduleName <- "fireSense_spreadPredict" covs <- copy(covs) ## the random effects are not covariate coefficients: fireSense_burn applies them (randomEffectOutputs) @@ -426,11 +445,12 @@ spreadProbOneELF <- function(covs, params, covMinMax, yr, maxFireSpread, lowerSp ## the one function the fit computes its spread probability with, so the prediction cannot differ from it out <- data.table(pixelID = shortAnnDT$pixelID, spreadProb = spreadProbFromCovs(mat[, matching, drop = FALSE], logisticPars, covPars, lowerSpreadProb, - link = if (!is.null(powerLawGamma)) "powerLaw", + link = link, climateRef = climateRef, powerLawGamma = powerLawGamma, - powerLawShape = powerLawShape)) - ## the power-law link's input, which that link clips at 0 and so cannot be recovered from spreadProb - if (!is.null(powerLawGamma)) + powerLawShape = powerLawShape, lowerAsymptote = lowerAsymptote, + richardsNu = richardsNu)) + ## the link's input: the power law clips it at 0, so it cannot be recovered from spreadProb + if (!is.null(link)) set(out, NULL, "linearPredictor", as.vector(mat[, matching, drop = FALSE] %*% covPars)) out } @@ -452,24 +472,28 @@ linearPredictorRas <- function(template, dt) { randomEffectOutputs <- list(fireSense_SpreadFireSD = fireSenseUtils::fireSpreadSDTxt, fireSense_SpreadSD = fireSenseUtils::yearSpreadSDTxt) -#' The names of `fireSense_SpreadPowerLaw` -powerLawParNames <- c("pc", "gamma", "floor", "shape") - -#' What `fireSense_burn` needs to add the year effect on the linear predictor of a power-law fit +#' What `fireSense_burn` needs to add the year effect on the linear predictor of a power-law or Richards fit #' -#' A fit made with `spreadLink = "powerLaw"` adds its year effect (`yearSpreadSD`) to the linear predictor `x`, not to -#' the logit of `p`. `fireSense_burn` recovers `x` from `p` with the link's `pc`, `gamma`, `floor` and `shape`, adds the effect, -#' and maps back with `fireSenseUtils::powerLawLink()`. +#' A fit made with `spreadLink = "powerLaw"`, `"powerLawSmooth"` or `"richards"` adds its year effect (`yearSpreadSD`) +#' to the linear predictor `x`, not to the logit of `p`. `fireSense_burn` adds the effect to `x` and maps back with the +#' link (`fireSenseUtils::linearLinkProb()`), with these parameters. #' #' @param params one-row `data.frame`: the parameter set in use (`paramSetForRep()`); `maxAsymptote` is `pc`. -#' @param powerLawGamma the row's `gamma` (`ledgerPowerLawGamma()`); `NULL` for another link. +#' @param powerLawGamma the row's `gamma` (`ledgerPowerLawGamma()`); `NULL` for a link without one. #' @param lowerSpreadProb the `floor`. #' @param powerLawShape the row's `shape` (`ledgerPowerLawShape()`). -#' @return A named numeric vector (`powerLawParNames`), or `NULL` for another link. -powerLawParsOf <- function(params, powerLawGamma, lowerSpreadProb, powerLawShape = fireSenseUtils::spreadPowerLawShape) { - if (is.null(powerLawGamma)) return(NULL) - c(pc = params[["maxAsymptote"]][1L], gamma = powerLawGamma, floor = lowerSpreadProb, - shape = powerLawShape)[powerLawParNames] +#' @param link the row's link (`ledgerLinkArgs()`); by default `"powerLaw"` when `powerLawGamma` is given. +#' @param lowerAsymptote,richardsNu the row's `lowerAsymptote` and `richardsNu`. +#' @return A named numeric vector (`fireSenseUtils::spreadLinkParNames` of the link; `fireSenseUtils::linearLinkPars()`), +#' or `NULL` for another link. +powerLawParsOf <- function(params, powerLawGamma = NULL, lowerSpreadProb, powerLawShape = fireSenseUtils::spreadPowerLawShape, + link = if (!is.null(powerLawGamma)) "powerLaw", lowerAsymptote = fireSenseUtils::spreadProbFloor, + richardsNu = fireSenseUtils::spreadRichardsNu) { + if (is.null(link)) return(NULL) + ## "richards" has no gamma, and does not use one + if (is.null(powerLawGamma)) powerLawGamma <- fireSenseUtils::spreadPowerLawGamma + fireSenseUtils::linearLinkPars(link, params[["maxAsymptote"]][1L], powerLawGamma, lowerSpreadProb, powerLawShape, + lowerAsymptote, richardsNu) } #' The covariate ranges of one ledger row @@ -510,24 +534,87 @@ ledgerClimateRef <- function(sa, i) { #' The power-law exponent of one ledger row #' -#' A fit made with `fireSense_spreadFit`'s `spreadLink = "powerLaw"` stores its `gamma` in the ledger row -#' (`fireSenseUtils::spreadFitPowerLawGammaTxt`), with `"powerLaw"` in `fireSenseUtils::spreadLinkTxt`. Prediction +#' A fit made with `fireSense_spreadFit`'s `spreadLink = "powerLaw"` or `"powerLawSmooth"` stores its `gamma` in the ledger row +#' (`fireSenseUtils::spreadFitPowerLawGammaTxt`), with the link in `fireSenseUtils::spreadLinkTxt`. Prediction #' applies the same link with the same `gamma` (`fireSenseUtils::spreadProbFromCovs()`). #' #' @param sa `sim$studyAreaWithSpreadParams`, one row per ELF. #' @param i integer; the row. -#' @return `gamma`, or `NULL` for a row of any other link, such as every row written before the link existed. Such -#' a row predicts exactly as it always did. A `"powerLaw"` row without a valid `gamma` stops. +#' @return `gamma`, or `NULL` for a row of any other link (`"richards"` has none), such as every row written before the +#' link existed. Such a row predicts exactly as it always did. A `"powerLaw"` or `"powerLawSmooth"` row without a valid +#' `gamma` stops. ledgerPowerLawGamma <- function(sa, i) { - linkCol <- fireSenseUtils::spreadLinkTxt - if (!linkCol %in% names(sa) || !identical(as.character(sa[[linkCol]][[i]]), "powerLaw")) return(NULL) + link <- ledgerSpreadLink(sa, i) + if (!any(link %in% fireSenseUtils::spreadPowerLawLinks)) return(NULL) gamma <- sa[[fireSenseUtils::spreadFitPowerLawGammaTxt]][[i]] if (!(is.numeric(gamma) && length(gamma) == 1L && is.finite(gamma) && gamma > 0)) - stop("fireSense_spreadPredict: ledger row ", i, " has spreadLink 'powerLaw' but no valid '", + stop("fireSense_spreadPredict: ledger row ", i, " has spreadLink '", link, "' but no valid '", fireSenseUtils::spreadFitPowerLawGammaTxt, "' (", format(gamma), ")", call. = FALSE) gamma } +#' The spread link of one ledger row +#' +#' @param sa `sim$studyAreaWithSpreadParams`, one row per ELF. +#' @param i integer; the row. +#' @return The row's `fireSenseUtils::spreadLinkTxt`, or `NULL` for a row without one (the default link, and every row +#' written before the column existed). +ledgerSpreadLink <- function(sa, i) { + linkCol <- fireSenseUtils::spreadLinkTxt + if (linkCol %in% names(sa)) as.character(sa[[linkCol]][[i]]) +} + +#' A number of one ledger row, for the links that record it +#' +#' @param sa `sim$studyAreaWithSpreadParams`, one row per ELF. +#' @param i integer; the row. +#' @param col the ledger column. +#' @param links the links that write `col`; any other row gives `NULL`. +#' @param ok a function of the value: `TRUE` when it is valid. An invalid value stops. +#' @return The value, or `NULL` for a row of another link. +ledgerLinkNumber <- function(sa, i, col, links, ok) { + if (!any(ledgerSpreadLink(sa, i) %in% links)) return(NULL) + v <- if (col %in% names(sa)) sa[[col]][[i]] + if (!(is.numeric(v) && length(v) == 1L && is.finite(v) && ok(v))) + stop("fireSense_spreadPredict: ledger row ", i, " has spreadLink '", ledgerSpreadLink(sa, i), "' but no valid '", col, + "' (", format(v), ")", call. = FALSE) + v +} + +#' The lower asymptote of one ledger row +#' +#' `fireSense_spreadFit`'s `lowerAsymptote` of a `"powerLawSmooth"` or `"richards"` fit, in +#' `fireSenseUtils::spreadFitLowerAsymptoteTxt`. +#' +#' @inheritParams ledgerLinkNumber +#' @return A number from 0 to `fireSenseUtils::spreadProbFloor`; `NULL` for a row of another link. +ledgerLowerAsymptote <- function(sa, i) + ledgerLinkNumber(sa, i, fireSenseUtils::spreadFitLowerAsymptoteTxt, fireSenseUtils::spreadAsymptoteLinks, + function(v) v >= 0 && v <= fireSenseUtils::spreadProbFloor) + +#' The `nu` of one ledger row +#' +#' `fireSense_spreadFit`'s `richardsNu` of a `"richards"` fit, in `fireSenseUtils::spreadFitRichardsNuTxt`. +#' +#' @inheritParams ledgerLinkNumber +#' @return A number, 0 or more; `NULL` for a row of another link. +ledgerRichardsNu <- function(sa, i) + ledgerLinkNumber(sa, i, fireSenseUtils::spreadFitRichardsNuTxt, "richards", function(v) v >= 0) + +#' The link of one ledger row and its parameters, as the arguments of `spreadProbOneELF()` +#' +#' @inheritParams ledgerLinkNumber +#' @return A list of `link` (only for a link of `fireSenseUtils::spreadLinearLinks`), `powerLawGamma` (not `"richards"`), +#' `powerLawShape`, `lowerAsymptote` and `richardsNu` (the links that have them); the others are left out, so they +#' take `spreadProbOneELF()`'s defaults. A row of any other link, or without one, has `powerLawShape` only. +ledgerLinkArgs <- function(sa, i) { + link <- ledgerSpreadLink(sa, i) + if (!any(link %in% fireSenseUtils::spreadLinearLinks)) link <- NULL + Filter(Negate(is.null), list(link = link, powerLawGamma = ledgerPowerLawGamma(sa, i), + powerLawShape = ledgerPowerLawShape(sa, i), + lowerAsymptote = ledgerLowerAsymptote(sa, i), richardsNu = ledgerRichardsNu(sa, i))) +} + #' The power-law curvature exponent of one ledger row #' #' `fireSense_spreadFit`'s `powerLawShape` is stored in the ledger row (`fireSenseUtils::spreadFitPowerLawShapeTxt`). diff --git a/tests/testthat/test-metadata.R b/tests/testthat/test-metadata.R index d4bdd7a..5924067 100644 --- a/tests/testthat/test-metadata.R +++ b/tests/testthat/test-metadata.R @@ -30,7 +30,7 @@ test_that("outputs are the expected names and classes", { expect_identical( outputs[order(names(outputs))], c(fireSense_EscapeDefinition = "data.frame", fireSense_SpreadFireSD = "SpatRaster|numeric", - fireSense_SpreadLinear = "SpatRaster", fireSense_SpreadParamSet = "integer", fireSense_SpreadPowerLaw = "SpatRaster|numeric", fireSense_SpreadPredicted = "SpatRaster", + fireSense_SpreadLinear = "SpatRaster", fireSense_SpreadLink = "character", fireSense_SpreadParamSet = "integer", fireSense_SpreadPowerLaw = "SpatRaster|numeric", fireSense_SpreadPredicted = "SpatRaster", fireSense_SpreadSD = "SpatRaster|numeric") ) }) diff --git a/tests/testthat/test-smoothLinks.R b/tests/testthat/test-smoothLinks.R new file mode 100644 index 0000000..ff7eb5c --- /dev/null +++ b/tests/testthat/test-smoothLinks.R @@ -0,0 +1,110 @@ +## Ledger rows of fireSense_spreadFit's spreadLink = "powerLawSmooth" and "richards": the link in +## fireSenseUtils::spreadLinkTxt, the lower asymptote in spreadFitLowerAsymptoteTxt, nu in spreadFitRichardsNuTxt (and gamma +## and shape for "powerLawSmooth" only). Prediction applies the same link through fireSenseUtils::spreadProbFromCovs(), and +## hands fireSense_burn the link (fireSense_SpreadLink) with its parameters (fireSense_SpreadPowerLaw) and x. +## Same toy covariates as test-powerLaw.R. + +linkColSL <- fireSenseUtils::spreadLinkTxt +lowerColSL <- fireSenseUtils::spreadFitLowerAsymptoteTxt +nuColSL <- fireSenseUtils::spreadFitRichardsNuTxt +gammaColSL <- fireSenseUtils::spreadFitPowerLawGammaTxt +cellsSL <- c(1, 2, 3, 4, 6, 7, 8) + +## a ledger row as the fit writes it; `gamma` and `nu` only for the links that have them +inputsSL <- function(link, lower = 0.05, gamma = 1.9, nu = 0.5) { + ins <- toyInputs() + sa <- ins$studyAreaWithSpreadParams + sa[[linkColSL]] <- link + sa[[lowerColSL]] <- lower + if (link == "powerLawSmooth") sa[[gammaColSL]] <- gamma + if (link == "richards") sa[[nuColSL]] <- nu + ins$studyAreaWithSpreadParams <- sa + ins +} + +## the linear predictor of the toy covariates, in cell order +xSL <- function() { + cv <- toyCovariates(); o <- order(cv$pixelID) + 1.5 * cv$MDC[o] / 200 - 0.5 * cv$youngAge[o] + 1 * cv$fuelA[o] / 8 +} + +test_that("a powerLawSmooth row predicts the smooth link with its gamma and lower asymptote", { + for (L in c(0, 0.05, 0.13)) { + sim <- toyRun(inputsSL("powerLawSmooth", lower = L, gamma = 3)) + v <- predVals(sim) + expect_equal(v[cellsSL], fireSenseUtils::powerLawSmoothLink(xSL(), 0.25, 3, 0.13, 1, L), tolerance = 1e-9) + expect_true(all(is.na(v[c(5, 9)]))) + expect_true(all(v[cellsSL] >= L)) + expect_gt(min(v[cellsSL]), 0 - 1e-12) + ## the x < 0 cell (2) is the power law's 0 only without a lower asymptote + expect_equal(v[2] >= L, TRUE) + expect_identical(sim$fireSense_SpreadLink, "powerLawSmooth") + expect_identical(sim$fireSense_SpreadPowerLaw, c(pc = 0.25, gamma = 3, floor = 0.13, shape = 1, lower = L)) + expect_equal(terra::values(sim$fireSense_SpreadLinear, mat = FALSE)[cellsSL], xSL(), tolerance = 1e-9) + } + ## the same x on a "powerLaw" row is below the floor and, once the link clips it, 0 on a low enough x + expect_equal(fireSenseUtils::powerLawLink(-50, 0.25, 3, 0.13), 0) +}) + +test_that("a richards row predicts the Richards link with no gamma in the ledger row, and hands burn pc, lower, nu, B", { + ins <- inputsSL("richards", lower = 0.02, nu = 2) + expect_false(gammaColSL %in% names(ins$studyAreaWithSpreadParams)) + sim <- toyRun(ins) + v <- predVals(sim) + expect_equal(v[cellsSL], fireSenseUtils::richardsLink(xSL(), 0.25, 0.02, 2), tolerance = 1e-9) + expect_true(all(v[cellsSL] >= 0.02)) + expect_identical(sim$fireSense_SpreadLink, "richards") + expect_identical(sim$fireSense_SpreadPowerLaw, + c(pc = 0.25, lower = 0.02, nu = 2, B = 1 / fireSenseUtils::spreadPowerLawGamma)) + expect_equal(terra::values(sim$fireSense_SpreadLinear, mat = FALSE)[cellsSL], xSL(), tolerance = 1e-9) + expect_null(ledgerPowerLawGamma(ins$studyAreaWithSpreadParams, 1L)) + ## nu = 0 is Gompertz + g <- predVals(toyRun(inputsSL("richards", lower = 0.13, nu = 0))) + expect_equal(g[cellsSL], 0.13 + (0.25 - 0.13) * exp(-exp(-xSL() / fireSenseUtils::spreadPowerLawGamma)), tolerance = 1e-9) +}) + +test_that("with L = 0.13 a low-x pixel keeps 0.13 on both new links, and the old links leave nothing for burn to read", { + for (lk in c("powerLawSmooth", "richards")) { + ins <- inputsSL(lk, lower = 0.13) + ins$studyAreaWithSpreadParams$params <- lapply(ins$studyAreaWithSpreadParams$params, function(p) { p$youngAge <- -40; p }) + v <- predVals(toyRun(ins)) + expect_equal(v[2], 0.13, tolerance = 1e-9) # cell 2: youngAge 1 + } + expect_null(toyRun()$fireSense_SpreadLink) +}) + +test_that("rows without the columns their link needs stop; the helpers read the columns", { + sa <- inputsSL("richards")$studyAreaWithSpreadParams + expect_identical(ledgerLowerAsymptote(sa, 1L), 0.05) + expect_identical(ledgerRichardsNu(sa, 1L), 0.5) + expect_identical(ledgerLinkArgs(sa, 1L)$link, "richards") + expect_false("powerLawGamma" %in% names(ledgerLinkArgs(sa, 1L))) + sa[[nuColSL]] <- NULL + expect_error(ledgerRichardsNu(sa, 1L), "richardsNu_spread") + sa <- inputsSL("powerLawSmooth")$studyAreaWithSpreadParams + sa[[lowerColSL]] <- 0.5 + expect_error(ledgerLowerAsymptote(sa, 1L), "lowerAsymptote_spread") + sa[[lowerColSL]] <- NULL + expect_error(ledgerLowerAsymptote(sa, 1L), "lowerAsymptote_spread") + expect_null(ledgerRichardsNu(inputsSL("powerLawSmooth")$studyAreaWithSpreadParams, 1L)) + ## the other links have none + expect_null(ledgerLowerAsymptote(toyInputs()$studyAreaWithSpreadParams, 1L)) + expect_identical(ledgerLinkArgs(toyInputs()$studyAreaWithSpreadParams, 1L), list(powerLawShape = 1)) +}) + +test_that("with several ELFs of one new link the parameters blend; with different links it stops", { + ins <- multiInputs() + ins$studyAreaWithSpreadParams$params <- lapply(ins$studyAreaWithSpreadParams$params, function(p) { p$MDC <- 1; p }) + ins$studyAreaWithSpreadParams[[linkColSL]] <- c("richards", "richards") + ins$studyAreaWithSpreadParams[[lowerColSL]] <- c(0, 0.1) + ins$studyAreaWithSpreadParams[[nuColSL]] <- c(0.5, 2) + sim <- toyRun(ins, params = list(ELFblendWidth = 20000)) + pl <- sim$fireSense_SpreadPowerLaw + expect_identical(names(pl), c("pc", "lower", "nu", "B")) + lo <- terra::values(pl[["lower"]], mat = FALSE) + expect_equal(lo[1], 0); expect_equal(lo[10], 0.1) + expect_identical(sim$fireSense_SpreadLink, "richards") + ins$studyAreaWithSpreadParams[[linkColSL]] <- c("richards", "powerLawSmooth") + ins$studyAreaWithSpreadParams[[gammaColSL]] <- c(NA, 2) + expect_error(toyRun(ins, params = list(ELFblendWidth = 20000)), "different spread links") +}) From 7ed64ff2699f78eb59f15e74f79cb1e402c92206 Mon Sep 17 00:00:00 2001 From: Eliot McIntire Date: Fri, 13 Nov 2026 16:07:46 -0700 Subject: [PATCH 2/2] Check the ledger row's lowerAsymptote and richardsNu with fireSenseUtils::checkLinkParams() Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_014G18Mik3fH4z5M5CyMSUS6 --- fireSense_spreadPredict.R | 27 ++++++++++++++++----------- tests/testthat/test-smoothLinks.R | 6 +++--- 2 files changed, 19 insertions(+), 14 deletions(-) diff --git a/fireSense_spreadPredict.R b/fireSense_spreadPredict.R index 3d7bd60..5c9e2b6 100644 --- a/fireSense_spreadPredict.R +++ b/fireSense_spreadPredict.R @@ -566,19 +566,25 @@ ledgerSpreadLink <- function(sa, i) { #' A number of one ledger row, for the links that record it #' +#' The row's `lowerAsymptote_spread` and `richardsNu_spread` are checked together by +#' `fireSenseUtils::checkLinkParams()`, the check `fireSense_spreadFit` makes of its parameters; an invalid or missing +#' value stops, naming the row. +#' #' @param sa `sim$studyAreaWithSpreadParams`, one row per ELF. #' @param i integer; the row. #' @param col the ledger column. #' @param links the links that write `col`; any other row gives `NULL`. -#' @param ok a function of the value: `TRUE` when it is valid. An invalid value stops. #' @return The value, or `NULL` for a row of another link. -ledgerLinkNumber <- function(sa, i, col, links, ok) { - if (!any(ledgerSpreadLink(sa, i) %in% links)) return(NULL) - v <- if (col %in% names(sa)) sa[[col]][[i]] - if (!(is.numeric(v) && length(v) == 1L && is.finite(v) && ok(v))) - stop("fireSense_spreadPredict: ledger row ", i, " has spreadLink '", ledgerSpreadLink(sa, i), "' but no valid '", col, - "' (", format(v), ")", call. = FALSE) - v +ledgerLinkNumber <- function(sa, i, col, links) { + link <- ledgerSpreadLink(sa, i) + if (!any(link %in% links)) return(NULL) + num <- function(cn) if (cn %in% names(sa)) sa[[cn]][[i]] + tryCatch(fireSenseUtils::checkLinkParams(link, num(fireSenseUtils::spreadFitLowerAsymptoteTxt), + num(fireSenseUtils::spreadFitRichardsNuTxt)), + error = function(e) stop("fireSense_spreadPredict: ledger row ", i, " has spreadLink '", link, "': ", + conditionMessage(e), " (columns '", fireSenseUtils::spreadFitLowerAsymptoteTxt, "', '", + fireSenseUtils::spreadFitRichardsNuTxt, "')", call. = FALSE)) + num(col) } #' The lower asymptote of one ledger row @@ -589,8 +595,7 @@ ledgerLinkNumber <- function(sa, i, col, links, ok) { #' @inheritParams ledgerLinkNumber #' @return A number from 0 to `fireSenseUtils::spreadProbFloor`; `NULL` for a row of another link. ledgerLowerAsymptote <- function(sa, i) - ledgerLinkNumber(sa, i, fireSenseUtils::spreadFitLowerAsymptoteTxt, fireSenseUtils::spreadAsymptoteLinks, - function(v) v >= 0 && v <= fireSenseUtils::spreadProbFloor) + ledgerLinkNumber(sa, i, fireSenseUtils::spreadFitLowerAsymptoteTxt, fireSenseUtils::spreadAsymptoteLinks) #' The `nu` of one ledger row #' @@ -599,7 +604,7 @@ ledgerLowerAsymptote <- function(sa, i) #' @inheritParams ledgerLinkNumber #' @return A number, 0 or more; `NULL` for a row of another link. ledgerRichardsNu <- function(sa, i) - ledgerLinkNumber(sa, i, fireSenseUtils::spreadFitRichardsNuTxt, "richards", function(v) v >= 0) + ledgerLinkNumber(sa, i, fireSenseUtils::spreadFitRichardsNuTxt, "richards") #' The link of one ledger row and its parameters, as the arguments of `spreadProbOneELF()` #' diff --git a/tests/testthat/test-smoothLinks.R b/tests/testthat/test-smoothLinks.R index ff7eb5c..905dcd3 100644 --- a/tests/testthat/test-smoothLinks.R +++ b/tests/testthat/test-smoothLinks.R @@ -80,12 +80,12 @@ test_that("rows without the columns their link needs stop; the helpers read the expect_identical(ledgerLinkArgs(sa, 1L)$link, "richards") expect_false("powerLawGamma" %in% names(ledgerLinkArgs(sa, 1L))) sa[[nuColSL]] <- NULL - expect_error(ledgerRichardsNu(sa, 1L), "richardsNu_spread") + expect_error(ledgerRichardsNu(sa, 1L), "richardsNu must be") sa <- inputsSL("powerLawSmooth")$studyAreaWithSpreadParams sa[[lowerColSL]] <- 0.5 - expect_error(ledgerLowerAsymptote(sa, 1L), "lowerAsymptote_spread") + expect_error(ledgerLowerAsymptote(sa, 1L), "lowerAsymptote must be") sa[[lowerColSL]] <- NULL - expect_error(ledgerLowerAsymptote(sa, 1L), "lowerAsymptote_spread") + expect_error(ledgerLowerAsymptote(sa, 1L), "lowerAsymptote must be") expect_null(ledgerRichardsNu(inputsSL("powerLawSmooth")$studyAreaWithSpreadParams, 1L)) ## the other links have none expect_null(ledgerLowerAsymptote(toyInputs()$studyAreaWithSpreadParams, 1L))