[v1.0.2] update landmine_burn1() for use with 'burny' scenarios

- allow fires to spread through non-flammable pixels but w/o counting as burned pixels for fire size calcs;

DESCRIPTION

@@ -5,8 +5,8 @@ Description: Additional utilities for LandWeb analyses.
 URL: 
     http://LandWebUtils.predictiveecology.org,
     https://github.com/PredictiveEcology/LandWebUtils
-Date: 2024-09-06
-Version: 1.0.1
+Date: 2024-10-28
+Version: 1.0.2
 Authors@R: c(
     person("Eliot J B", "McIntire", email = "eliot.mcintire@NRCan-RNCan.gc.ca",
     role = c("aut"), comment=c(ORCID = "0000-0002-6914-8316")),

R/landmine.R

@@ -1,5 +1,6 @@
 utils::globalVariables(c(
-  "active", "id", "initialPixels", "numActive", "pSpawnNewActive", "size", "spreadProb", "state"
+  "active", "id", "initialPixels", "numActive", "pixels", "pSpawnNewActive",
+  "size", "spreadProb", "state"
 ))
 
 #' Core Burn function for Andison's LandMine Fire Module
@@ -36,6 +37,13 @@ utils::globalVariables(c(
 #'
 #' @param spreadProb     A raster layer of spread probabilities, with non-flammable pixels `NA`.
 #'
+#' @param omitPixels     An optional vector of pixel IDs to omit from fire size calculations.
+#'                       Can be used if `spreadProb` or `spreadProbRel` do not designate
+#'                       non-flammable pixels as `NA`, to allow fires to move through these pixels,
+#'                       while excluding these pixels from burn area calculations.
+#'                       Useful in study areas with discontinuous fuels, which would otherwise
+#'                       result in fires getting 'stuck' too often, and not reach their target size.
+#'
 #' @details
 #' This algorithm is a modified contagious cellular automaton.
 #'
@@ -53,10 +61,10 @@ utils::globalVariables(c(
 #' large and very small fires, so over time has been adjusted to vary depending on:
 #' a) number of active "firelets" (NF); and b) fire size (FS), such that:
 #' ```
-#'   - If 10 <= NF < 36 and FS < 20,000 ha then P = 20%
-#'   - If NF > 36 and FS < 8,000 ha, P = 11%
-#'   - If NF < 36 and FS > 20,000 ha, P = 26%
-#'   - If NF < 10 then P = 46%
+#'   - If 10 <= NF < 36 and FS < 20,000 ha then P = 20%;
+#'   - If NF > 36 and FS < 8,000 ha, P = 11%;
+#'   - If NF < 36 and FS > 20,000 ha, P = 26%;
+#'   - If NF < 10 then P = 46%;
 #' ````
 #' These rule create more heterogeneity in the pattern of burning.
 #' }
@@ -69,7 +77,7 @@ utils::globalVariables(c(
 #' then it will stop, unable to achieve the desired `fireSize`.
 #' }
 #'
-#' @return A `data.table` with 4 columns
+#' @return A `data.table` with 4 columns (`initialPixels`, `pixels`, `state`, `order`).
 #'
 #' @export
 #' @importFrom data.table set
@@ -80,7 +88,7 @@ utils::globalVariables(c(
 landmine_burn1 <- function(landscape, startCells, fireSizes = 5, nActiveCells1 = c(10, 36),
                            spawnNewActive = c(0.46, 0.2, 0.26, 0.11), maxRetriesPerID = 10L,
                            sizeCutoffs = c(8e3, 2e4), spreadProbRel = spreadProbRel,
-                           spreadProb = 0.77) {
+                           spreadProb = 0.77, omitPixels = NULL) {
   stopifnot(is.integer(maxRetriesPerID))
 
   ## convert to pixels
@@ -99,6 +107,14 @@ landmine_burn1 <- function(landscape, startCells, fireSizes = 5, nActiveCells1 =
     neighProbs = c(1 - spawnNewActive[1], spawnNewActive[1])
     # skipChecks = FALSE
   )
+
+  if (!is.null(omitPixels)) {
+    ## ensure non-flammable pixels omitted from fire size calculations
+    for (i in a[pixels %in% omitPixels, ]$initialPixels) {
+      attr(a, "spreadState")$clusterDT[initialPixels == i, size := size - 1L]
+    }
+  }
+
   whActive <- attr(a, "spreadState")$whActive
   while (any(whActive)) {
     set(a, NULL, "numActive", 0L)
@@ -133,6 +149,13 @@ landmine_burn1 <- function(landscape, startCells, fireSizes = 5, nActiveCells1 =
       skipChecks = TRUE
     )
 
+    if (!is.null(omitPixels)) {
+      ## ensure non-flammable pixels omitted from fire size calculations
+      for (i in a[pixels %in% omitPixels, ]$initialPixels) {
+        attr(a, "spreadState")$clusterDT[initialPixels == i, size := size - 1L]
+      }
+    }
+
     set(a, NULL, "order", seq_len(NROW(a)))
     whActive <- attr(a, "spreadState")$whActive
   }