Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions NEWS.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# fireSense_spreadPredict (development version)

- 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`.

- 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.
Expand Down
101 changes: 101 additions & 0 deletions fireSense_spreadPredict.R
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,19 @@ defineModule(sim, list(
desc = paste("Upper limit on `spreadProb` used when fitting (default",
"`fireSenseUtils::spreadProbCeiling`). Here it is only checked",
"to be the same in every module that defines it.")),
defineParameter("paramSets", "character", default = NA, min = NA, max = NA,
desc = paste("Path to an `.rds` or `.csv` of spread parameter vectors, one per row, for the simulated ELF",
"(`sim$.ELFind`; the only row with one ELF): e.g. a DEoptim population, or the `params` of",
"ledger rows of another `fitFileSuffix` (a table with a `params` list column, its rows",
"for this ELF). They replace the simulated ELF's rows of the ledger; neighbour ELFs keep",
"theirs, so blending is unchanged. The link, lower asymptote, `gamma` and covariate",
"centres still come from the ledger row. A set must have every coefficient the ledger",
"row has, else the module stops. `NA` uses the ledger rows. Replicate r uses set",
"`ceiling(r / repsPerSet)` (cycling through the sets), and calls `set.seed(k)`",
"with k the replicate's number within its set, so every set gets the same random numbers",
"in `fireSense_burn` (common random numbers).")),
defineParameter("repsPerSet", "integer", default = 1L, min = 1L, max = NA,
desc = "With `paramSets`: the number of replicates that use each set. Not used otherwise."),
defineParameter(".rep", "integer", default = 1L, min = 1L, max = NA,
desc = paste("Which replicate this prediction is. It selects parameter set",
"((rep - 1) %% number of sets) + 1 of each ELF, so replicates cycle through the",
Expand Down Expand Up @@ -71,6 +84,9 @@ defineModule(sim, list(
expectsInput(objectName = "rasterToMatchLargeELF", objectClass = "SpatRaster", sourceURL = NA,
desc = paste("Only with several fitted ELFs: each pixel's ELF (`ELFind`), on the grid of",
"`flammableRTM`, from `fireSense_ELFs` with a `studyArea_fireSense`.")),
expectsInput(objectName = ".ELFind", objectClass = "character", sourceURL = NA,
desc = paste("The simulated ELF, as in `fireSense_dataPrepPredict`. Only used with `paramSets` and",
"several fitted ELFs, to find the simulated ELF's row.")),
expectsInput(objectName = "flammableRTM", objectClass = "SpatRaster", sourceURL = NA,
desc = "Binary raster, 1 where the pixel is flammable. Template for `fireSense_SpreadPredicted`.")
),
Expand Down Expand Up @@ -206,6 +222,24 @@ spreadPredictRun <- function(sim) {
sim$fireSense_SpreadParamSet <- stats::setNames(vapply(sa$params, function(p) paramSetIndex(NROW(p), rep), integer(1)),
if (NROW(sa) > 1L) as.character(sa[[fireSenseUtils::polygonIDTxt]]))

## paramSets: the simulated ELF's rows become the chosen set; the surface only changes when the set does
if (!is.na(P(sim)$paramSets)) {
ps <- paramSetsForRep(sim, sa, rep)
sa$params[[ps$own]] <- ps$params
sim$fireSense_SpreadParamSet[[ps$own]] <- ps$set
## the same random numbers for every set (not in the seed), but not for every year, for fireSense_burn
set.seed(paramSetsSeed(P(sim)$.runInitialTime, ps$k, ps$id))
## everything the outputs depend on; `time(sim)` is not in it: with one covariate table it does not change them
key <- list(P(sim)$paramSets, ps$set, sim$fireSense_SpreadParamSet, covs, sa[setdiff(names(sa), "params")],
ps$params, terra::values(sim$flammableRTM, mat = FALSE),
if (!is.null(sim$rasterToMatchLargeELF)) terra::values(sim$rasterToMatchLargeELF, mat = FALSE),
P(sim)$ELFblendWidth, P(sim)$lowerSpreadProb, P(sim)$maxFireSpread)
if (identical(mod$surface$key, key)) {
for (nm in surfaceOutputs) sim[[nm]] <- unwrapIfRaster(mod$surface$outputs[[nm]])
return(invisible(sim))
}
}

if (NROW(sa) == 1L) {
params1 <- paramSetForRep(sa$params[[1]], rep)
lk1 <- ledgerLinkArgs(sa, 1L)
Expand Down Expand Up @@ -280,9 +314,72 @@ spreadPredictRun <- function(sim) {
sim$fireSense_SpreadPredicted <- rast(sim$flammableRTM) ## use flammableRTM as template
sim$fireSense_SpreadPredicted[pred$pixelID] <- pred$spreadProb

if (!is.na(P(sim)$paramSets))
mod$surface <- list(key = key, outputs = lapply(stats::setNames(surfaceOutputs, surfaceOutputs), function(nm) wrapIfRaster(sim[[nm]])))

invisible(sim)
}

#' The parameter set of the `paramSets` file that a replicate uses
#'
#' Replicate `rep` uses set `ceiling(rep / repsPerSet)` (`paramSetIndex()` cycles through the sets), and is
#' replicate `((rep - 1) %% repsPerSet) + 1` within it. The set keeps the columns of the simulated ELF's ledger
#' row (`sa$params`), and the random-effect sds it has.
#'
#' @param sim A `simList`; parameters `paramSets`, `repsPerSet`.
#' @param sa `sim$studyAreaWithSpreadParams`, one row per ELF.
#' @param rep integer; the replicate (`.rep`, or `replicateOf()`).
#' @return A list: `own` (the simulated ELF's row of `sa`), `set` (its index in the file), `k` (the replicate
#' within the set) and `params` (the one-row `data.frame`).
paramSetsForRep <- function(sim, sa, rep) {
idCol <- fireSenseUtils::polygonIDTxt
own <- if (NROW(sa) == 1L) 1L else match(as.character(sim$.ELFind), as.character(sa[[idCol]]))
if (length(own) != 1L || is.na(own))
stop("fireSense_spreadPredict: paramSets with several fitted ELFs needs sim$.ELFind to be ONE of the ELFs of ",
"sim$studyAreaWithSpreadParams (", paste(sa[[idCol]], collapse = ", "), "); it is ",
if (is.null(sim$.ELFind)) "missing" else paste(sim$.ELFind, collapse = ", "), call. = FALSE)
path <- P(sim)$paramSets
if (!identical(mod$paramSetsFile$path, path)) {
sets <- if (grepl("[.]csv$", path, ignore.case = TRUE)) data.table::fread(path, data.table = FALSE) else readRDS(path)
if (is.data.frame(sets) && "params" %in% names(sets)) { ## ledger rows
if (idCol %in% names(sets)) sets <- sets[as.character(sets[[idCol]]) %in% as.character(sa[[idCol]][own]), , drop = FALSE]
sets <- do.call(rbind, lapply(sets$params, as.data.frame))
}
mod$paramSetsFile <- list(path = path, sets = as.data.frame(sets))
}
sets <- mod$paramSetsFile$sets
per <- P(sim)$repsPerSet
set <- paramSetIndex(NROW(sets), ceiling(rep / per))
ledgerPars <- names(sa$params[[own]])
lacks <- setdiff(ledgerPars, names(sets))
if (length(lacks))
stop("fireSense_spreadPredict: the paramSets file ", path, " lacks the column(s) ",
paste(lacks, collapse = ", "), " that the ledger row of ELF ", own, " has (a coefficient the spread formula uses, ",
"or a random-effect sd the run needs)",
call. = FALSE)
keep <- intersect(names(sets), c(ledgerPars, fireSenseUtils::spreadRandomEffectTxt))
list(own = own, set = set, k = as.integer(((rep - 1L) %% per) + 1L), params = sets[set, keep, drop = FALSE],
id = if (idCol %in% names(sa)) as.character(sa[[idCol]][own]) else "")
}

#' The random seed of replicate `k` of a year and ELF
#'
#' Not a function of the parameter set, so every set gets the same random numbers (common random numbers);
#' it is of the year and the ELF, so a hindcast's years and ELFs do not repeat each other's draws.
#'
#' @param year numeric; the job's year (`.runInitialTime`).
#' @param k integer; the replicate within its set.
#' @param id character; the simulated ELF (`""` if unknown).
#' @return An integer for `set.seed()`.
paramSetsSeed <- function(year, k, id) {
idHash <- sum(utf8ToInt(id) * seq_len(nchar(id)))
as.integer((round(year) * 1000003 + k * 7919 + idHash * 104729) %% .Machine$integer.max)
}

## a SpatRaster is held by a pointer, so what `mod$surface` keeps is a copy
wrapIfRaster <- function(x) if (inherits(x, "SpatRaster")) terra::wrap(x) else x
unwrapIfRaster <- function(x) if (inherits(x, "PackedSpatRaster")) terra::unwrap(x) else x

#' Each ELF's weight at each pixel
#'
#' An ELF's raw weight is 1 on its own pixels and falls linearly to 0 at `width` metres from them (distance
Expand Down Expand Up @@ -472,6 +569,10 @@ linearPredictorRas <- function(template, dt) {
randomEffectOutputs <- list(fireSense_SpreadFireSD = fireSenseUtils::fireSpreadSDTxt,
fireSense_SpreadSD = fireSenseUtils::yearSpreadSDTxt)

## the outputs that depend on the parameter set and the covariates only (`mod$surface`)
surfaceOutputs <- c("fireSense_SpreadPredicted", names(randomEffectOutputs), "fireSense_SpreadLink",
"fireSense_SpreadPowerLaw", "fireSense_SpreadLinear")

#' 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"`, `"powerLawSmooth"` or `"richards"` adds its year effect (`yearSpreadSD`)
Expand Down
11 changes: 6 additions & 5 deletions tests/testthat/test-metadata.R
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,9 @@ test_that("inputs are the expected names and classes", {
md <- SpaDES.core::moduleMetadata(module = moduleName, path = modulePath)
inputs <- stats::setNames(md$inputObjects$objectClass, md$inputObjects$objectName)
expect_identical(
inputs[order(names(inputs))],
c(covMinMax_spread = "data.table",
inputs[order(names(inputs), method = "radix")],
c(.ELFind = "character",
covMinMax_spread = "data.table",
fireSense_SpreadCovariates = "data.table",
flammableRTM = "SpatRaster",
rasterToMatchLargeELF = "SpatRaster")
Expand Down Expand Up @@ -49,11 +50,11 @@ paramTable <- function(md) {
test_that("parameters have the expected names, classes and defaults", {
md <- SpaDES.core::moduleMetadata(module = moduleName, path = modulePath)
expected <- data.frame(
class = c("integer", "numeric", "numeric", "numeric", "character", "logical", "numeric", "numeric", "character", "numeric", "numeric", "logical"),
class = c("integer", "numeric", "numeric", "numeric", "character", "logical", "numeric", "numeric", "character", "numeric", "numeric", "logical", "character", "integer"),
## .runInitialTime defaults to start(sim), which is 0 when only metadata is parsed
default = c("1L", "0", "1", "NA", "NA", "FALSE", "20000", "50", "c(\"natural\", \"unknown\")", "0.13", "0.276", "FALSE"),
default = c("1L", "0", "1", "NA", "NA", "FALSE", "20000", "50", "c(\"natural\", \"unknown\")", "0.13", "0.276", "FALSE", "NA", "1L"),
row.names = c(".rep", ".runInitialTime", ".runInterval", ".saveInitialTime", ".studyAreaName", ".useCache",
"ELFblendWidth", "escapeSizeHa", "fireCauses", "lowerSpreadProb", "maxFireSpread", "paramSetByReplicate")
"ELFblendWidth", "escapeSizeHa", "fireCauses", "lowerSpreadProb", "maxFireSpread", "paramSetByReplicate", "paramSets", "repsPerSet")
)
expect_identical(paramTable(md), expected)
})
Expand Down
138 changes: 138 additions & 0 deletions tests/testthat/test-paramSets.R
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
## paramSets / repsPerSet: the simulated ELF's parameter sets come from a file; replicate r uses set
## ceiling(r / repsPerSet); a set's surface is computed once.

twoSets <- function() {
p <- rbind(toyParams(), toyParams())
p$maxAsymptote <- c(0.20, 0.35)
p$MDC <- c(1.5, 3)
p$yearSpreadSD <- c(0.1, 0.2)
p
}

setsFile <- function(p, ext = "rds") {
f <- tempfile(fileext = paste0(".", ext))
if (ext == "rds") saveRDS(p, f) else utils::write.csv(p, f, row.names = FALSE)
f
}

## one job with `n` replicates, as the hindcast runs them
runReps <- function(ins, params, n) {
sim <- toySim(ins, params = c(params, list(paramSetByReplicate = TRUE)), times = list(start = 1, end = 1))
sets <- integer(0); vals <- list()
for (r in seq_len(n)) {
end(sim) <- r
sim <- SpaDES.core::spades(sim, debug = FALSE)
sets <- c(sets, unname(sim$fireSense_SpreadParamSet)); vals[[r]] <- predVals(sim)
}
list(sets = sets, vals = vals)
}

test_that("default: paramSets NA gives the same output as before", {
p <- twoSets()
expect_equal(predVals(toyRun(toyInputs(params = p), params = list(.rep = 2L))),
predVals(toyRun(toyInputs(params = p), params = list(.rep = 2L, paramSets = NA_character_, repsPerSet = 5L))))
})

test_that("2 sets x 2 reps: reps 1-2 use set 1, reps 3-4 set 2, each with its own surface and sd", {
p <- twoSets()
ledger <- toyParams() ## the ledger row is not one of the sets
for (ext in c("rds", "csv")) {
res <- runReps(toyInputs(params = ledger), list(paramSets = setsFile(p, ext), repsPerSet = 2L), 4)
expect_identical(res$sets, c(1L, 1L, 2L, 2L))
for (r in 1:4)
expect_equal(res$vals[[r]], predVals(toyRun(toyInputs(params = p[(r - 1) %/% 2 + 1, , drop = FALSE]))),
tolerance = 1e-12, info = paste(ext, "rep", r))
}
expect_gt(max(abs(res$vals[[1]] - res$vals[[3]]), na.rm = TRUE), 1e-3)
sd <- vapply(c(1, 3), function(r) toyRun(toyInputs(params = ledger),
params = list(.rep = r, paramSets = setsFile(p), repsPerSet = 2L))$fireSense_SpreadSD, numeric(1))
expect_equal(sd, c(0.1, 0.2))
})

test_that("reps of one set reuse its surface: it is computed once per set", {
sim <- toySim(toyInputs(), params = list(paramSets = setsFile(twoSets()), repsPerSet = 2L, paramSetByReplicate = TRUE))
sim <- SpaDES.core::spades(sim, debug = FALSE)
v1 <- predVals(sim)
## plant a marker in the stored surface of set 1: a rep of the same set returns it, a rep of set 2 does not
surf <- sim@.xData$.modObjs[[moduleName]]$surface
expect_identical(surf$key[[2]], 1L)
mo <- sim@.xData$.modObjs[[moduleName]]
r <- terra::unwrap(mo$surface$outputs$fireSense_SpreadPredicted); r[1] <- 99
mo$surface$outputs$fireSense_SpreadPredicted <- terra::wrap(r)
end(sim) <- 2
sim <- SpaDES.core::spades(sim, debug = FALSE)
expect_identical(predVals(sim)[1], 99)
expect_identical(unname(sim$fireSense_SpreadParamSet), 1L)
end(sim) <- 3
sim <- SpaDES.core::spades(sim, debug = FALSE)
expect_identical(unname(sim$fireSense_SpreadParamSet), 2L)
expect_false(identical(predVals(sim)[1], 99))
expect_false(isTRUE(all.equal(predVals(sim), v1)))
})

test_that("the seed is the same for every set, differs by year and ELF, and paramSets NA leaves the RNG alone", {
f <- setsFile(twoSets())
draw <- function(r, year = 1) {
toyRun(toyInputs(), params = list(.rep = r, paramSets = f, repsPerSet = 2L, .runInitialTime = year),
times = list(start = year, end = year))
stats::runif(1)
}
d <- vapply(1:4, draw, numeric(1))
expect_equal(d[1], d[3]); expect_equal(d[2], d[4]); expect_false(d[1] == d[2]) ## same k, different sets
expect_false(draw(1, year = 2) == d[1]) ## same k, different year
expect_false(paramSetsSeed(1, 1L, "A") == paramSetsSeed(1, 1L, "B"))
## no paramSets: the module does not seed, so the stream after a run is the caller's, whatever .rep is
after <- function(...) { set.seed(42); toyRun(toyInputs(), params = list(...)); stats::runif(1) }
expect_equal(after(.rep = 1L), after(.rep = 2L))
expect_false(isTRUE(all.equal(after(.rep = 1L), after(.rep = 1L, paramSets = f))))
})

test_that("a set equal to the ledger row reproduces the ledger surface identically", {
led <- toyParams(yearSpreadSD = 0.3)
expect_identical(predVals(toyRun(toyInputs(params = led), params = list(paramSets = setsFile(led)))),
predVals(toyRun(toyInputs(params = led))))
})

test_that("a set lacking a coefficient of the ledger row stops with a clear error", {
p <- twoSets(); p$fuelA <- NULL
expect_error(toyRun(toyInputs(), params = list(paramSets = setsFile(p))), "lacks the column.*fuelA")
})

test_that("with several ELFs only the simulated ELF's rows are replaced; the set index is reported by ELF", {
ins <- multiInputs()
ins$.ELFind <- "B"
p <- ins$studyAreaWithSpreadParams$params[[2]][c(1, 1), ]
p$maxAsymptote <- c(0.21, 0.31)
sim <- toyRun(ins, params = list(.rep = 2L, ELFblendWidth = 6000, paramSets = setsFile(p), repsPerSet = 1L))
expect_identical(unname(sim$fireSense_SpreadParamSet), c(1L, 2L))
expect_equal(predVals(sim)[1], 0.13 + (0.25 - 0.13) / 2, tolerance = 1e-9) ## A unchanged
expect_equal(predVals(sim)[10], 0.13 + (0.31 - 0.13) / 2, tolerance = 1e-9) ## B is set 2
})

test_that("paramSets with several ELFs needs one .ELFind, and a set must have the ledger row's random-effect sd", {
ins <- multiInputs()
p <- ins$studyAreaWithSpreadParams$params[[2]]
expect_error(toyRun(ins, params = list(ELFblendWidth = 6000, paramSets = setsFile(p))), "ONE of the ELFs")
ins$.ELFind <- c("A", "B")
expect_error(toyRun(ins, params = list(ELFblendWidth = 6000, paramSets = setsFile(p))), "ONE of the ELFs")
ins$.ELFind <- "B"; ins$studyAreaWithSpreadParams$params[[2]]$yearSpreadSD <- 0.1
expect_error(toyRun(ins, params = list(ELFblendWidth = 6000, paramSets = setsFile(p))), "lacks the column.*yearSpreadSD")
})

test_that("a neighbour ELF with 2 rows still cycles with the replicate: the cached surface is not reused across it", {
ins <- multiInputs(); ins$.ELFind <- "B"
sa <- ins$studyAreaWithSpreadParams
a <- sa$params[[1]][c(1, 1), ]; a$maxAsymptote <- c(0.25, 0.35); sa$params[[1]] <- a
ins$studyAreaWithSpreadParams <- sa
pB <- sa$params[[2]]
sim <- toySim(ins, params = list(paramSetByReplicate = TRUE, ELFblendWidth = 6000, paramSets = setsFile(pB), repsPerSet = 2L),
times = list(start = 1, end = 1))
vals <- list(); sets <- list()
for (r in 1:3) {
end(sim) <- r; sim <- SpaDES.core::spades(sim, debug = FALSE)
vals[[r]] <- predVals(sim)[1]; sets[[r]] <- unname(sim$fireSense_SpreadParamSet)
}
expect_identical(sets, list(c(1L, 1L), c(2L, 1L), c(1L, 1L)))
expect_equal(vals[[1]], 0.13 + (0.25 - 0.13) / 2, tolerance = 1e-9)
expect_equal(vals[[2]], 0.13 + (0.35 - 0.13) / 2, tolerance = 1e-9) ## ELF A's row 2, not rep 1's surface
})
Loading