Package 'fireSenseUtils'

Description

Utilities for working with the 'fireSense' group of 'SpaDES' modules.

Author(s)

Maintainer: Eliot J B McIntire [email protected] (ORCID)

Authors:

• Jean Marchal [email protected]

• Alex M Chubaty [email protected] (ORCID)

• Ian Eddy [email protected] (ORCID)

See Also

Useful links:

• Report bugs at https://github.com/PredictiveEcology/fireSenseUtils/issues

Description

Internal callback passed to the optimizer (e.g. stats::nlminb()) when the ignition formula contains no pw() terms. Computes the linear predictor mm %*% params + offset, applies linkinv, and returns the negative log-likelihood evaluated in mod_env. A large sentinel (1e20) is returned whenever the link inverse produces invalid values (non-positive, NA, infinite, or empty), preventing the optimizer from wandering into infeasible regions.

Usage

.objFunIgnition(params, linkinv, nll, sm, nx, mm, mod_env, offset)

Arguments

Value

Numeric scalar: the negative log-likelihood, or 1e20 if the inverse-link produces non-finite or non-positive values.

Description

Internal callback for the optimizer when the ignition formula contains pw() terms. Differs from .objFunIgnition in that the model matrix is rebuilt at every call (via stats::model.matrix()) after running updateKnotExpr, which updates the knot values in mod_env. This lets the optimizer jointly fit covariate coefficients and knot positions.

Usage

.objFunIgnitionPW(
  params,
  formula,
  linkinv,
  nll,
  sm,
  updateKnotExpr,
  nx,
  mod_env,
  offset
)

Arguments

Value

Numeric scalar: the negative log-likelihood, or 1e20 if the inverse-link produces negative, NA, or infinite values.

Description

Objective function for fireSense_spreadFit module

Usage

.objfunSpreadFit(
  par,
  landscape,
  annualDTx1000,
  nonAnnualDTx1000,
  formulaToFit,
  historicalFires,
  fireBufferedListDT,
  covMinMax = NULL,
  maxFireSpread = 0.28,
  lowerSpreadProb = 0.13,
  minFireSize = 2,
  tests = "snll_fs",
  Nreps = 10,
  mutuallyExclusive = list(youngAge = c("class", "nf")),
  doAssertions = TRUE,
  plot.it = FALSE,
  objFunCoresInternal = 1,
  lanscape1stQuantileThresh = 0.265,
  thresh = 550,
  weighted = TRUE,
  verbose = 2,
  ...
)

Arguments

Value

Attempting a weighted likelihood, https://stats.stackexchange.com/questions/267464/algorithms-for-weighted-maximum-likelihood-parameter-estimation. With log(fireSize) * likelihood for each fire.

Description

Abbreviate species names for fuel classes

Usage

abbreviateSpNames(df)

Arguments

Value

data.table

Description

Convert list of annual SpatRaster to data.table

Usage

annualStackToDTx1000(x, whNotNA, ...)

## S3 method for class 'SpatRaster'
annualStackToDTx1000(x, whNotNA, ...)

## S3 method for class 'Raster'
annualStackToDTx1000(x, whNotNA, ...)

## S3 method for class 'list'
annualStackToDTx1000(x, whNotNA, ...)

Arguments

Value

data.table of the SpatRaster or the list

Examples

withr::local_package("raster")

r1 <- raster(extent(0, 10, 0, 10), vals = 1:100)
r2 <- raster(extent(0, 10, 0, 10), vals = 100:1)
r3 <- raster(extent(0, 10, 0, 10), vals = 200:101)
r4 <- raster(extent(0, 10, 0, 10), vals = 300:201)

# list of Rasters
lRast <- list(r1, r2, r3)
lRast[[1]][5] <- NA
whNotNA <- setdiff(1:ncell(r1), 5)

# unnamed -- should error
try(out1 <- annualStackToDTx1000(lRast, whNotNA))

# named
names(lRast) <- c("OneToHun", "HunToOne", "TwoHunToOneHun")
out1 <- annualStackToDTx1000(lRast, whNotNA)

# RasterStack
out2 <- annualStackToDTx1000(raster::stack(lRast), whNotNA)

# List of RasterStacks
s1 <- raster::stack(r1, r2)
names(s1) <- names(lRast)[1:2]
s2 <- raster::stack(r4, r3)
names(s2) <- c(names(lRast)[3], "ThreeHunToTwoHun")
out3 <- annualStackToDTx1000(list(s1 = s1, s2 = s2), whNotNA) ## named list required

# With duplicated names -- to remove duplicates;
#  actually, this doesn't make sense: RasterStack can't have duplicated names
names(lRast) <- c("OneToHun", "OneToHun", "TwoHunToOneHun")
out4 <- annualStackToDTx1000(raster::stack(lRast), whNotNA)

## cleanup
withr::deferred_run()

Description

Semi-automated selection of fuel classed based on GLMs

Usage

assessFuelClasses(
  landscape,
  fuelCol,
  sppEquiv,
  sppEquivCol,
  targetNonForestClasses = 2,
  targetFuelClasses = 5,
  nonforestLCC,
  pValue = 0.001
)

Arguments

Value

a list of three objects:

1. modSppEquiv, a data.table with assigned fuel classes for each tree species;

2. nonForestedLCCGroups, a named list of non-forest land cover classes grouped by fuel class;

3. missingLCCgroup, the class in nonForestLCCGroups to assign forested pixels missing from cohortData;

Description

Buffer ignition points to create non-ignitions for model

Usage

bufferIgnitionPoints(ignitionPoints, rtm, bufferSize)

Arguments

Value

a list of data.tables containing indices inside buffered area of each year's ignitions

Description

Create buffers around polygons based on area target for buffer

Usage

bufferToArea(
  poly,
  rasterToMatch,
  areaMultiplier,
  verb = FALSE,
  polyName = NULL,
  field = NULL,
  minSize = 500,
  cores = 1,
  ...
)

## S3 method for class 'list'
bufferToArea(
  poly,
  rasterToMatch,
  areaMultiplier = 10,
  verb = FALSE,
  polyName = NULL,
  field = NULL,
  minSize = 500,
  cores = 1,
  ...
)

## S3 method for class 'SpatialPolygons'
bufferToArea(
  poly,
  rasterToMatch,
  areaMultiplier = 10,
  verb = FALSE,
  polyName = NULL,
  field = NULL,
  minSize = 500,
  cores = 1,
  ...
)

## S3 method for class 'sf'
bufferToArea(
  poly,
  rasterToMatch,
  areaMultiplier = 10,
  verb = FALSE,
  polyName = NULL,
  field = NULL,
  minSize = 500,
  cores = 1,
  ...
)

Arguments

Value

A data.table (or list of data.tables if poly was a list) with 2 columns: buffer and pixelID. buffer is either 1 (the original polygon) or 0 (in the buffer).

Description

Create a variable sized buffer around a set of pixels belonging to the same fire ID

Usage

bufferToAreaRast(fireIDraster, areaMultiplier, minSize, flammableRTM, verb = 1)

Arguments

Value

a data.table with fire ID, buffer status, and pixelID

Description

Modify cohortData with burn column

Usage

buildCohortBurnHistory(cohortData, pixelGroupMap, firePolys, year)

Arguments

Value

cohortData modified with burn status

Description

Generate, Summarize, Predict Burn Classes from Covariates

Usage

burnClassGenerator(df, numClasses = 4:9, AUC = TRUE, plotAUC = FALSE)

burnClassSummary(mod)

burnClassPredict(mod, df)

burnProbFromClass(mod, df)

Arguments

Details

This was inspired by reading https://www.datanovia.com/en/blog/types-of-clustering-methods-overview-and-quick-start-r-code/ and https://www.datanovia.com/en/lessons/model-based-clustering-essentials/, based on Scrucca et al. (2016).

Value

A list with 2 elements, first the model, which comes from mclust::Mclust, and second the Area Under the Curve or AUC as an indicator of the overall goodness of fit.

The algorithm

The basic solution is to take all covariates, including the binary "not burned", "burned" (coded as 0 and 1, respectively), and do model-based clustering with the mclust R package. We can choose a fixed number of burn classes, or a finite range (see numClasses argument. This will make numClasses "homogeneous" groups, including whether they burned or not. From this, we can identify groups by looking at the mean values of "burned" to see what their burn tendency is as a "homogeneous" group.

Categorical data

For now, it is recommended to convert categorical data to dummy variables, 0 and 1. E.g., For land cover, wetland class can be converted to a column "wetland" with 1 for data points that are wetlands and 0 for non-wetland.

How much data to include

This has not been tested yet; however, I believe that having a relatively similar number of "burned" and "unburned" pixels (within ⁠3x⁠ either way), is probably a good idea. In other words, if there are 100,000 burned data points, there should be between 30,000 and 300,000 unburned data points. If there are already buffers around the burned polygons that include unburned pixels, then these buffers can be used as part of the unburned content.

Author(s)

Eliot McIntire

References

Scrucca L., Fop M., Murphy T. B. and Raftery A. E. (2016) mclust 5: clustering, classification and density estimation using Gaussian finite mixture models, The R Journal, 8/1, pp. 205-233. https://journal.r-project.org/archive/2016/RJ-2016-021/RJ-2016-021.pdf

Examples

## Not run: 
#################################
# Use own data; here is a generated set for reprex
withr::local_package("data.table")

N <- 1e5
DT <- list()
for (i in c("train", "test")) {
  DT[[i]] <- data.table(burned = sample(c(0, 0, 0, 1), replace = TRUE, size = N))
  set(DT[[i]], NULL, "jp", rlnorm(N, mean = 4 + 0.5 * DT[[i]]$burned, sd = 0.25))
  set(DT[[i]], NULL, "bs", rlnorm(N, mean = 4 + 0.3 * DT[[i]]$burned, sd = 0.25))
  set(DT[[i]], NULL, "ws", rlnorm(N, mean = 4 + 0.2 * DT[[i]]$burned, sd = 0.25))
  set(DT[[i]], NULL, "age", rlnorm(N, mean = 4 - 0.2 * DT[[i]]$burned, sd = 0.25))
  DT[[i]][, c("jp", "bs", "ws", "age") := lapply(.SD, function(x) x / max(x) * 1000),
    .SDcols = c("jp", "bs", "ws", "age")
  ]
  DT[[i]][, c("age") := lapply(.SD, function(x) x / max(x) * 200), .SDcols = c("age")]
  summary(DT[[i]])
  boxplot(DT[[i]]$age ~ DT[[i]]$burned)
}

bc <- burnClassGenerator(DT[["train"]], 4:8)
# Show if the model is good at predicting burn state
(bc$AUC) # area under the curve

# print summary of mean values of each burn class
(summ <- burnClassSummary(bc$model))

# predict -- add Burn Class to object
set(DT[["test"]], NULL, "burnClass", burnClassPredict(bc$model, df = DT[["test"]]))
prob <- burnProbFromClass(bc$model, DT[["test"]])

## cleanup
withr::deferred_run()

## End(Not run)

Description

Identifies pixels that have any non-forest presence (based on the non-pixelID columns of landcoverDT) and whose age is below cutoffForYoungAge. It then sets those pixels to 0 across all layers of LCCras and appends a new single-layer raster named youngAge with 1 for the affected pixels and 0 elsewhere (preserving NA where present in the template).

Usage

calcNonForestYoungAge(landcoverDT, NFTSD, LCCras, cutoffForYoungAge)

Arguments

Details

The function proceeds as follows:

1. Determines the set of non-forest columns as all columns in landcoverDT except pixelID, and computes a per-row sum (sumRows).

2. Retrieves pixel ages from NFTSD using pixelID as indices.

3. Selects pixels where sumRows > 0 and age < cutoffForYoungAge; these pixels are considered "young non-forest".

4. Sets those pixels to 0 in every layer of LCCras using cell indexing.

5. Builds a new single-layer raster with 1 at those pixel locations and 0 elsewhere (respecting NA from the template), and adds it to LCCras as a layer named youngAge.

Assumptions / requirements

• LCCras is a terra::SpatRaster (possibly multi-layer). Cell indexing with LCCras[pixToChange] <- 0 applies across all layers for the indexed cells.

• landcoverDT is a data.table with:

  • a pixelID column of integer cell indices (1-based) consistent with LCCras cell numbering, and

  • all other columns representing non-forest variables whose row-wise sum indicates presence (sumRows > 0).

• NFTSD is a numeric vector (or similar) indexable by pixelID, providing the age (in the same units as cutoffForYoungAge) for each cell.

• cutoffForYoungAge is a scalar numeric threshold; pixels with age < cutoffForYoungAge are flagged as "young".

Notes

• The function modifies LCCras in place (by reference to the object passed in) and returns the modified raster with an extra youngAge layer.

• NA cells in LCCras remain NA in the created youngAge layer.

• The landcoverDT temporary columns sumRows and age are removed prior to return.

Value

A terra::SpatRaster identical to LCCras but with:

• all "young non-forest" pixels set to 0 across its existing layers, and

• an additional layer named youngAge where flagged pixels are 1, others are 0, and NAs follow the template mask.

References

• Terra package reference manual and vignettes for SpatRaster operations (Hijmans, R.J.).

• data.table reference: .SD, ⁠:=⁠, and efficient grouping/filtering (Dowle, M., & Srinivasan, A.).

See Also

• terra::rast(), terra::values(), terra::setValues() for raster creation and manipulation.

• data.table semantics for .SD, in-place updates (⁠:=⁠), and fast row/column operations.

Examples

## Not run: 
library(terra)
library(data.table)

# Build a small template raster
r <- rast(nrows = 3, ncols = 3)
values(r) <- c(NA, 0, 0,
               0, 0, NA,
               0, 0, 0)

# Make a 2-layer LCC raster (copy template twice)
LCC <- c(r, r)
names(LCC) <- c("LCC1", "LCC2")

# A data.table with pixel indices and two non-forest columns
dt <- data.table(
  pixelID = c(2, 3, 4, 5, 7, 8, 9),
  NF1 = c(1, 0, 0, 2, 0, 0, 1),
  NF2 = c(0, 1, 0, 0, 0, 3, 0)
)

# Age vector indexed by cell ID (length ncell(LCC))
ages <- seq_len(ncell(LCC)) * 5  # toy ages

out <- calcNonForestYoungAge(
  landcoverDT = dt,
  NFTSD = ages,
  LCCras = LCC,
  cutoffForYoungAge = 15
)

out
names(out)     # "LCC1" "LCC2" "youngAge"
plot(out$youngAge)

## End(Not run)

Description

Iteratively calculate youngAge column in FS covariates

Usage

calcYoungAge(
  years,
  annualCovariates,
  standAgeMap,
  fireBufferedListDT,
  cutoffForYoungAge = 15
)

Arguments

Value

a raster layer with unified stand age and time-since-disturbance values

Description

preparing covariates for fitting modules

Usage

castCohortData(
  cohortData,
  pixelGroupMap,
  lcc,
  ageMap = NULL,
  missingLCC,
  year = NULL,
  cutoffForYoungAge = 15
)

Arguments

Value

a trimmed cohortData with wide-layout and rows for every pixel in lcc

Description

chk_duplicatedStartPixels enforces the invariant that no more than one fire can be ignited in a given pixel within a single time interval. When duplicate cells are detected it issues a warning and keeps only the largest fire (by size) for each duplicated pixel.

Usage

chk_duplicatedStartPixels(cells, size)

.doDataChecks(moduleName, envir, attribs, fml)

Arguments

Value

A list with two elements: loci (deduplicated cells) and sizes (corresponding size values).

Called for its side effects. Throws an informative error if any check fails; returns invisibly otherwise.

Description

Ensure fire points are located on flammable pixels inside a fire polygon Intended to be run using Map

Usage

cleanUpSpreadFirePoints(firePoints, bufferDT, flammableRTM, idCol)

Arguments

Value

a list of harmonized points and polygons

Description

Converts stacks of climate rasters to data.table and optionally subsets to index

Usage

climateRasterToDataTable(historicalClimateRasters, Index = NULL)

Arguments

Value

a long-layout data.table of climate values in each pixel and year

Description

Classify pixelGroups by flammability

Usage

cohortsToFuelClasses(
  cohortData,
  pixelGroupMap,
  flammableRTM,
  landcoverDT = NULL,
  sppEquiv,
  sppEquivCol,
  cutoffForYoungAge,
  fuelClassCol = "FuelClass",
  requiredFuelClasses
)

Arguments

Value

a SpatRaster of biomass by fuel class as determined by fuelClassCol and cohortData.

Description

Merging and assignment of fuel classes

Usage

combine_fuel_classes(df, targetFuelClasses = 5, lowThreshold = 0.05)

Arguments

Value

a data.table with assigned fuel classes for each species

Description

Plot the historical and projected climate values for flammable land surface

Usage

compareClimate(
  historicalClimate,
  projectedClimate,
  flammableRTM = NULL,
  Ylimits = NULL,
  firstHistoricalYear = 2001,
  firstProjectedYear = 2011,
  climVar = "climate variable"
)

Arguments

Value

a ggplot object

Examples

## Not run: 
compareClimate(
  historicalClimate = simOutPreamble$historicalClimateRasters$Climate,
  projectedClimate = simOutPreamble$projectedClimateRasters$Climate,
  flammableRTM = fSsimDataPrep$flammableRTM
)

## End(Not run)

Description

Plot the historical and projected MDC for a flammable land surface

Usage

compareMDC(
  historicalMDC,
  projectedMDC,
  flammableRTM = NULL,
  Ylimits = c(80, 220),
  firstHistoricalYear = 2001,
  firstProjectedYear = 2011
)

Arguments

Value

a ggplot object

Examples

## Not run: 
compareMDC(
  historicalMDC = simOutPreamble$historicalClimateRasters$MDC,
  projectedMDC = simOutPreamble$projectedClimateRasters$MDC,
  flammableRTM = fSsimDataPrep$flammableRTM
)

## End(Not run)

Description

Convert covariates to/from integers for smaller footprint; make data.frame

Usage

covsX1000AndSetDF(
  annualList,
  nonAnnualList,
  fireBufferedList,
  fireLociList,
  paramOrder,
  toX1000Integer = TRUE
)

Arguments

Value

a data.table with relevant columns made mutually exclusive

Description

Modifies DT in place: for each column in colsToUse, every NA is overwritten with 0 via data.table::set(). Useful when a covariate table is later passed to a model that does not tolerate NAs.

Usage

dtReplaceNAwith0(DT, colsToUse = NULL)

Arguments

Value

DT, invisibly modified by reference; columns are unchanged where no NAs were present.

Description

Intersects a study area with a set of Ecologically-based Low Fractal-dimensional (ELF) polygons, identifies which ELFs overlap the study area, and constructs a single categorical raster combining each ELF's per-cell classification. The output raster encodes three priority layers: cells classified as 2 in any ELF (highest priority, labelled by ELF ID), cells classified as 1 in two or more ELFs (shared agreement, labelled by ELF ID), and a 0 background for all other in-domain cells.

Usage

ELFsInStudyArea(studyArea, inputPath, ELFsRaster = NULL, ELFsPolygon = NULL)

Arguments

Details

The function assumes that ELFs (a list-like object with rasWhole rasters and an ID field) and rastTemplate are available in the calling environment, along with inputPath. ELF rasters are expected to contain the integer values 0, 1, and 2, where 2 indicates the core area of the ELF and 1 indicates the buffer for that ELF.

The three layers are combined with terra::cover() so that:

• 2 hits override everything else,

• 1 hits appear only where at least two ELFs agree, and

• the 0 background fills remaining in-domain cells.

Value

A categorical SpatRaster with a value/ELFind levels table, where ELFind gives the ELF identifier (or "none" for background).

See Also

makeELFs(), terra::classify(), terra::mosaic(), terra::cover()

Description

Downloads the SCANFI v1.2 Douglas-fir (SW) raster from NRCan, aggregates it by a factor of 8, loads it into memory, and writes it to disk as a reusable template for building Ecologically-based Low Fractal-dimensional (ELF) objects. Both the remote download and the aggregation step are cached via reproducible::Cache(), keyed on the remote file's hash, so the template is only rebuilt when the upstream source changes.

Usage

ELFtemplateRaster(inputPath)

Arguments

Details

The Douglas-fir layer is used purely for its spatial footprint and grid — the cell values themselves are not meaningful for ELF construction. The source layer is fetched from ⁠https://ftp.maps.canada.ca/pub/nrcan_rncan/Forests_Foret/SCANFI/v1/⁠. Remote metadata is checked at most once per week (notOlderThan = Sys.time() - 60*60*24*7) to avoid unnecessary network calls.

Value

A SpatRaster pointing to rastTemplate_Canada.tif inside inputPath. The raster covers Canada at roughly 8× the native SCANFI resolution and is suitable as a template for downstream ELF construction.

See Also

reproducible::prepInputs(), reproducible::Cache(), terra::aggregate(), terra::writeRaster()

Description

Used by the ignition formula machinery to parse a pw(v, k) term and return its components without evaluating them. The variable and knot names are returned as character strings (the captured symbols), or kept as AsIs if v was wrapped with I().

Usage

extractSpecial(v, k)

Arguments

Value

A list with elements variable (character, or AsIs expression) and knot (character form of k). Errors if k is missing.

Description

Download the FireSense parameter object, strip the list columns and convert to a SpatVector or SpatRaster.

Usage

fireSenseCloudParameters(
  url = paste0("https://drive.google.com/file/d/",
    "1oJX7V5wPSj49C6wt59yD9RBplfZ7Cp-f/view?usp=drive_link"),
  targetFile = "fireSenseParams.rds",
  destinationPath = ".",
  useCache = TRUE
)

Arguments

Value

The object and the rds file saved to destinationPath.

See Also

fireSenseCloudParametersMap()

Description

Download the FireSense parameter object, strip the list columns and convert to a SpatVector or SpatRaster. If plot = TRUE, this will also download a map that represents the forested lands of canada, to be plotted on the plot device with the fireSense parameter ELFs that currently have estimated parameters.

Usage

fireSenseCloudParametersMap(rasterize = FALSE, plot = TRUE, res = 5000, ...)

Arguments

Value

The map, either SpatRaster or SpatVector

See Also

fireSenseCloudParameters()

Description

Constructs pixel-level covariates required by FireSense (e.g., mutually exclusive fuel-class indicators, transformed by logMinB, and a youngAge indicator) by combining cohort-derived fuel classes with land cover, flammability, and (optionally) non-forest time-since-disturbance.

Usage

fireSenseCovariatesCreate(
  cohortData,
  pixelGroupMap,
  flammableRTM,
  sppEquiv,
  landcoverDT,
  fuelClassCol,
  requiredFuelClasses = NULL,
  sppEquivCol,
  missingLCCgroup,
  nonForestedLCCGroups,
  nonForest_timeSinceDisturbance,
  cutoffForYoungAge,
  nonForestCanBeYoungAge,
  studyAreaName,
  useCache = TRUE
)

Arguments

Details

The function:

1. Calls cohortsToFuelClasses() to derive fuel-class rasters from cohorts.

2. Converts these to a long data table keyed by pixelID and joins to landcoverDT.

3. Verifies there are no NA values across covariate columns and raises an error otherwise.

4. Marks pixels with all-zero covariates as the provided missingLCCgroup.

5. Enforces mutual exclusivity among the specified fuel/landcover columns.

6. Applies logMinB to all fuel-class columns (excluding youngAge).

7. If nonForestCanBeYoungAge = TRUE, augments youngAge for non-forest pixels using nonForest_timeSinceDisturbance and the cutoffForYoungAge.

• All covariate columns must be non-NA; the function stops with an error if any NA are detected after joining fuelClasses and landcoverDT.

• Pixels where all covariates sum to zero are flagged by setting missingLCCgroup := 1.

• Mutual exclusivity is enforced via makeMutuallyExclusive() using all fuel-class columns and the land-cover columns (excluding pixelID); youngAge is made exclusive to them.

• Fuel-class columns (excluding youngAge) are transformed with logMinB.

• When nonForestCanBeYoungAge = TRUE, youngAge for non-forest is derived using nonForest_timeSinceDisturbance and cutoffForYoungAge. Any existing youngAge from fuel classes is combined with this non-forest contribution.

Value

A data.table named spreadCovariates containing one row per pixelID, with:

• Mutually exclusive fuel-class covariate columns (log-transformed by logMinB).

• Land-cover indicator columns from landcoverDT.

• A youngAge indicator (possibly augmented by non-forest TSD logic).

Expectations/Assumptions

• fuelClasses returned by cohortsToFuelClasses() includes one column per fuel class, plus optionally youngAge, and a cell (renamed to pixelID here).

• landcoverDT must contain a pixelID column aligned to rasters by cell index.

• nonForestedLCCGroups names correspond to column names in landcoverDT.

• nonForest_timeSinceDisturbance is indexable by pixelID (e.g., vector aligned to raster cells).

See Also

cohortsToFuelClasses, makeMutuallyExclusive, logMinB, putBackIntoRaster, calcNonForestYoungAge

Examples

## Not run: 
covs <- fireSenseCovariatesCreate(
  cohortData = cohortsDT,
  pixelGroupMap = pgRas,
  flammableRTM = flammRas,
  sppEquiv = sppEquivDT,
  landcoverDT = landcoverDT,
  fuelClassCol = "fuelClass",
  sppEquivCol = "sppEquivCol",
  missingLCCgroup = "LCC_missing",
  nonForestedLCCGroups = c(NonForest = 1),
  nonForest_timeSinceDisturbance = NF_TSD,
  cutoffForYoungAge = 20,
  nonForestCanBeYoungAge = TRUE,
  studyAreaName = "MyArea",
  useCache = TRUE
)

## End(Not run)

Description

Character (or character-vector) constants used across the package and downstream modules to keep column names, identifiers, and other free-text tokens consistent. All such constants end in Txt.

Format

• polygonIDTxt: character(1). Name of the polygon-ID column (currently "polygonID").

• nonNFColNamesTxt: character vector of bookkeeping column names that are not non-forest landcover classes (currently "pixelID" and polygonIDTxt); used with base::setdiff() to select the non-forest landcover columns when summing/aggregating across rows (see makeTSD()).

• yearTxt: character(1). Token used as a year-column name or as a prefix on year-suffixed layer/column names (currently "year").

• youngAgeTxt: character(1). Name of the "young-age" cohort class (currently "youngAge").

• ignitionsTxt: character(1). Name of the ignitions column (currently "ignitions").

• escapesTxt: character(1). Name of the escapes column (currently "escapes").

• spreadFitAdditionalColNamesTxt: character vector of extra simList-slot/column names attached to spread-fit outputs ("numIterations", "objFunVal", "params", "sppEquiv", "nonForestedLCCGroups", "missingLCCgroup").

Description

Calculate proportional burn of landcover and tree species

Usage

fuelClassPrep(
  pixelGroupMap,
  cohortData,
  rstLCC,
  nonflammableLCC,
  fires,
  nonforestLCC,
  yearRange
)

Arguments

Value

data.table with cell, biomass, tree species or LCC for non-forest, and year of fire

Examples

# fuelClassPrep(
#   sim$pixelGroupMap2011, sim$cohortData2011, sim$rstLCC2011,
#   rstLCC = sim$rstLCC2011, nonForestLCC = sim$nonForestLCCGroups,
#   nonflammableLCC = P(sim)$nonflammableLCC,
#   fires = do.call(rbind, sim$spreadFirePolys),
#   yearRange = c(2012, 2020)
# )

Description

Get Fire SpatialPoints from Canadian Fire Database

Usage

getFirePoints_NFDB(
  url = NULL,
  studyArea = NULL,
  rasterToMatch = NULL,
  redownloadIn = 1,
  years = 1991:2017,
  fireSizeColName = "SIZE_HA",
  NFDB_pointPath
)

Arguments

Value

A sf spatial points object.

Description

Get Fire SpatialPoints from Canadian Fire Database

Usage

getFirePoints_NFDB_V2(
  url = NULL,
  studyArea = NULL,
  redownloadIn = 1,
  years = 1991:2017,
  fireSizeColName = "SIZE_HA",
  NFDB_pointPath = NULL,
  fun = "sf::st_read",
  plot = FALSE
)

Arguments

Value

A sf spatial points object.

Description

Download and prepare fire data from National Fire Database

Usage

getFirePolygons(url, years, useInnerCache = FALSE, ...)

Arguments

Value

list of fire polygons by year

See Also

latestNBACUrl() for the discovery helper used when url is missing.

Description

Mostly this is about 2 things:

1. remove fires that were so small that they take less than 1 pixel so they are not in the buff object but are in the cent object.

2. the centroid cell is in a buffer or otherwise nonburnable cell (e.g., water). For 1) remove these from the centroid data. For 2) this function will search in the neighbourhood for the next closest pixel that has at least 7 available neighbours that can burn. If not, remove these.

Mostly this is about 2 things:

1. remove fires that were so small that they take less than 1 pixel so they are not in the buff object but are in the cent object.

2. the centroid cell is in a buffer or otherwise nonburnable cell (e.g., water). For 1) remove these from the centroid data. For 2) this function will search in the neighbourhood for the next closest pixel that has at least 7 available neighbours that can burn. If not, remove these.

Usage

harmonizeBufferAndPoints(cent, buff, ras, idCol = "FIRE_ID")

harmonizeBufferAndPoints(cent, buff, ras, idCol = "FIRE_ID")

Arguments

Description

Outer wrapper on spread fire polygon data munging that does several things:

1. ensure buffered fires are entirely in studyArea;

2. ensure every fire has a corresponding ignition point, and vice versa;

3. ensure these points are flammable.

Usage

harmonizeFireData(
  firePolys,
  flammableRTM,
  spreadFirePoints,
  areaMultiplier,
  minSize,
  pointsIDcolumn = "FIRE_ID",
  cores = 1
)

Arguments

Description

Creates a standardized name by combining a pre prefix, a normalized igOrEsc token (case-transformed), and a post suffix.

Usage

igOrEscNames(
  igOrEsc,
  pre = "fireSense_",
  post,
  case = c("lower", "camel", "sentence", "title")
)

Arguments

Value

character(1) constructed as paste0(pre, transformed(igOrEsc), post).

Examples

igOrEscNames("ignition", post = "Covariates")
igOrEscNames("escape", pre = "fs_", post = "_Formula", case = "camel")

Description

Parses the Apache directory listing at base and returns the URL of the newest file matching ⁠NBAC_<startYear>to<endYear>_<YYYYMMDD>_shp.zip⁠, selected by the YYYYMMDD stamp embedded in the filename. If the listing cannot be read or no matching file is found, fallback is returned, so callers can rely on getting some URL back.

Usage

latestNBACUrl(
  base = "https://cwfis.cfs.nrcan.gc.ca/downloads/nbac/",
  fallback = paste0(base, "NBAC_1972to2025_20260513_shp.zip")
)

Arguments

Value

A single character URL.

Description

Logistic functions using 2, 3, 4, or 5 parameters; logisticAll dispatches to one of them based on length(logisticPars).

Usage

logistic4p(x, par)

logistic5p(x, par)

logistic3p(x, par, par1 = 0.1)

logistic2p(x, par, par1 = 0.1, par4 = 0.5)

logisticAll(logisticPars, mat, covPars, lowerSpreadProb)

Arguments

Details

The general form is the 5-parameter sigmoid (Richards' curve): par1 + (par2 - par1) / (1 + (exp(x) / par3)^(-par4))^par5. The 4-, 3-, and 2-parameter variants successively fix the lower asymptote (par1), the inflection-point scale (par3 = 1), and the asymmetry factor (par5 = 0.5) to reduce the parameter count.

Value

Numeric vector of logistic values; same length as x (or nrow(mat) for logisticAll).

Description

Logistic parameter names

Usage

logisticParamNames

Format

An object of class list of length 4.

Value

A named list of length 4, with "2p", "3p", "4p", "5p" as names representing the 2-parameter etc. logistic curve.

Description

Used for transforming Biomass to the log scale

Usage

logMinB(x)

Arguments

Value

The original vector, logged with a minimum.

Description

Fires have key features that are different than "normal" ecological zonations. These include: 1) the property that they spread horizontally across a landscape, regardless of human-mapped ecological areas. 2) Furthermore, even when homogeneous fire regions are mapped, the homogeneousness may be because of fuel changes that occupy the average condition for an ecological area, not necessarily the boundary conditions. 3) Small areas that encompass an area that is only "several times larger than the largest fires" will be too small to capture the potential for multiple very large fires. 4) Furthermore, very large ecological regions may encompass too much variation in fire-fuel-climate relationships that any estimates of fire behaviour will not be accurate across the whole region. 5) No matter what area is chosen to Thus, to estimate fire behaviour across a large region like Canada, we need polygons that are not too small (>> largest fires), not too big (<<), are not constrained by ecological zones defined by vegetation, have buffers.

Usage

makeELFs(
  x,
  desiredBuffer = 20000,
  maxArea = 2.4e+11,
  destinationPath = ".",
  singleSpatVector = FALSE,
  useCache = TRUE
)

plotELFs(destinationPath = ".")

Arguments

Details

With these five points in mind, we define *Ecologically-based Low Fractal-dimensional polygons, "ELFs", that are constrained by large ecological zones (Canadian Ecozones), are "larg-ish", more "blobby" (low fractal dimension) than other ecological zonation in mountains (which tend to follow elevation contours), and are each buffered (default 20km).

Value

A list of length 2, with rasWhole and rasCentered. Each of these will have the complete list of ELFs. rasWhole is the whole map of Canada with the individual ELF highlighted, and rasCentered is just the individual ELF centred and reprojected so its projected parameters are: long0 is the x mid, and lat0 = ymin and lat1 = ymax of the individual ELF. This will create ELFs with the least amount of pixel deformation.

See Also

fireSenseCloudParameters()

Description

Identify each year's individual fires and buffer them accordingly

Usage

makeFireIDs(
  year,
  fireRaster,
  flammableRTM,
  bufferForFireRaster,
  areaMultiplier,
  minSize = 5000,
  verb = 1
)

Arguments

Value

a data.table with fire ID, buffer status, and pixelID

Description

Processes NTEMS Land Cover Classification (LCC) data for a specific year, adjusting non-flammable classes based on a flammability threshold during reprojection to a target raster's resolution and extent.

Usage

makeFireSenseLCC(
  neededYear,
  to,
  maskTo = NULL,
  nonflammableLCC = c(20, 31, 32, 33),
  flammabilityThreshold = 0.1,
  writeTo = NULL,
  overwrite = TRUE,
  destinationPath
)

Arguments

Details

This function performs several steps:

1. Downloads and prepares NTEMS LCC data for the specified neededYear using LandR::prepInputs_NTEMS_LCC_FAO, cropping and masking to the target extent.

2. Identifies the dominant flammable land cover class within each pixel of to. This is done by temporarily masking non-flammable classes (defined in nonflammableLCC) to NA in the source raster and then reprojecting using the 'mode' method.

3. Calculates the proportion of flammable cover within each pixel of to by reprojecting a binary (1=flammable, 0=non-flammable) version of the source raster using the 'average' method.

4. Creates the final raster: Pixels where the proportion of flammable cover (calculated in step 3) is below the flammabilityThreshold are assigned a value of 0 (representing non-flammable). Otherwise, pixels retain the dominant flammable LCC code identified in step 2.

Value

A list of two SpatRaster objects:

1. the processed land cover classification at the resolution, extent, and CRS of to with values representing either the modal flammable LCC code or 0 if the pixel is below the flammabilityThreshold, and

2. the proportion of each pixel that is flammable in the native resolution

Examples

## Not run: 
  # Requires terra and potentially LandR installed
  # Need example to and maskTo objects
  library(terra)

  # Create dummy to and maskTo
  ras <- rast(xmin = 0, xmax = 10, ymin = 0, ymax = 10, res = 1)
  values(ras) <- 1
  crs(ras) <- "EPSG:4326" # Example CRS
  sa <- ext(ras) |> as.polygons() |> vect()
  crs(sa) <- crs(ras)

  # Define a destination path (replace with a real path)
  destPath <- tempdir()

  # Run the function (will likely try to download data)
  # Note: prepInputs_NTEMS_LCC_FAO might require specific setup or data sources
  # This example might fail if data download/access isn't configured
  # fireLCC <- makeFireSenseLCC(neededYear = 2011, # Example year
  #                            to = ras,
  #                            maskTo = sa,
  #                            destinationPath = destPath)
  # plot(fireLCC)

## End(Not run)

Description

Wrapper on glm that creates separate GLMs for each item in fuel

Usage

makeGLM(fuel, landscape, form)

Arguments

Description

Create landcoverDT object to classify and track non-forest land cover classes

Usage

makeLandcoverDT(rstLCC, flammableRTM, forestedLCC, nonForestedLCCGroups)

Arguments

Value

a data.table with columns for pixelID and binary presence of landcover

Description

Must supply a raster so that points can be converted to the cells on a raster. It is assumed that the sizeCol is accurate. If not, it should be recalculated before this function call.

Usage

makeLociList(
  ras,
  pts,
  idsCol = "FIRE_ID",
  dateCol = "YEAR",
  sizeCol = "POLY_HA",
  sizeColUnits = "ha",
  yearPrefix = "year"
)

Arguments

Value

A list of data.table objects, each with 4 columns, "size" (in pixels), "date", "ids" from idsCol, and "cells", which are the pixel indices of the pts points.

Description

guarantees mutually exclusive values in a data table

Usage

makeMutuallyExclusive(dt, mutuallyExclusiveCols = list(youngAge = c("vegPC")))

Arguments

Value

a data.table with relevant columns made mutually exclusive

Description

Put cohortData back into a SpatRaster with some extra details

Usage

makeRastersFromCD(class, cohortData, flammableRTM, pixelGroupMap)

Arguments

Value

a SpatRaster with values equal to class biomass (B)

Description

Combines an initial stand age map with disturbance (fire) history to produce a time-since-disturbance (TSD) raster. Stand age is trusted for most pixels, but for pixels whose stand age is unreliable (e.g. non-forest land cover) the fire history is used instead: a recorded recent burn sets the TSD, while the absence of one marks the pixel as old (cutoffForYoungAge + 1).

Usage

makeTSD(
  year,
  firePolys = NULL,
  fireRaster = NULL,
  standAgeMap,
  lcc = NULL,
  cutoffForYoungAge = 15,
  pixToUpdate = NULL,
  flammablePixels = NULL
)

Arguments

Details

Which pixels to update from fire history, and which pixels are flammable, can be supplied in one of two ways:

• directly, via pixToUpdate and flammablePixels (general purpose); or

• via lcc, the landcoverDT produced by fireSense_dataPrepFit, from which both are derived (non-forest pixels are updated, and lcc$pixelID defines the flammable mask). This is retained for backwards compatibility.

Value

a SpatRaster with values representing time since disturbance

Description

For each year (or year period) provided, stacks and extracts covariates from coarse fuel rasters (split into forested vs. non-forested LCC groups) and climate, at ignition point locations, then merges results across years, filters unusable pixels, appends lightning summaries, and orders columns. Results are optionally cached.

Usage

mergePreparedCovs(
  years,
  fuelCovsCoarse,
  ignitionFirePoints,
  nonForestedLCCGroups,
  ignitionClimateCoarse,
  lightningMap,
  digest,
  useCache = TRUE
)

Arguments

Details

Processing steps:

1. Calls stackAndExtract() via Map() for each entry in years, splitting fuelCovsCoarse per year into:

   • fuel: all layers not in names(nonForestedLCCGroups)

   • LCC: layers whose names are in names(nonForestedLCCGroups)

   Additional MoreArgs include climate = ignitionClimateCoarse and fires = ignitionFirePoints.

2. Optionally caches the list of per-year extractions with reproducible::Cache() (function name tagged as "stackAndExtract").

3. Combines the list to a single data.table via data.table::rbindlist().

4. Removes rows for which the sum across all cover-type columns is zero (computed as rowSums(.SD) over all columns except ignitions, yearTxt (from fireSenseUtils), cell, and the climate variable names).

5. Renames the cell column to pixelID, coerces year to numeric, and appends lightning columns by indexing terra::values(terra::rast(lightningMap)) with pixelID.

6. Optionally reorders columns to place pixelID, ignitions, climate columns (i.e., names(ignitionClimateCoarse)), and youngAgeTxt (if it exists) first.

Assumptions / Requirements:

• fireSenseUtils::stackAndExtract() must accept arguments years, fuel, LCC, climate, and fires, and return a data.table-like object with at least cell, ignitions, and year (or yearTxt) columns.

• fireSenseUtils::yearTxt is used as a column name to exclude from cover sums; ensure it exists/aligns with the data produced by stackAndExtract().

• youngAgeTxt is referenced when establishing column order but is not defined in this scope; if unavailable, it is silently omitted.

• pixelID is assumed to be a valid row index into lightningMap raster values.

Lightning layer choice: The code appends all layers provided in lightningMap. If a single best-performing layer is known (e.g., "lightningDays"), subset lightningMap before calling this function.

Caching: Large raster inputs are excluded from the cache key via omitArgs = c("fuel", "LCC"); the caller-supplied digest should capture the salient identity of those omitted objects to avoid cache collisions.

Value

A data.table of ignition covariates with:

• pixelID (formerly cell)

• ignitions

• Climate covariate columns (names derived from ignitionClimateCoarse)

• Cover/class covariates retained from stackAndExtract() (filtered to rows with non-zero cover sum)

• Lightning-derived columns appended from lightningMap

• year coerced to numeric

Potential pitfalls

• If pixelID indexes are not aligned with lightningMap cell indices, appended lightning values will be incorrect; ensure consistent indexing/resolution.

• If fireSenseUtils::yearTxt is absent in the returned data, the exclusion in .SDcols is harmless, but confirm that the intended year column exists for analysis.

• If youngAgeTxt is not defined, it will be ignored when reordering columns.

See Also

fireSenseUtils::stackAndExtract, reproducible::Cache, data.table::rbindlist, terra::rast, terra::values

Examples

## Not run: 
# Pseudocode, assuming you have compatible inputs prepared:
yrs <- list(`2001` = 2001L, `2002` = 2002L)
# fuelCovsCoarse[[year]] is a named list or SpatRaster with LCC class names
# ignitionClimateCoarse[[year]] is a SpatRaster of climate layers
# ignitionFirePoints are point locations (sf/sp/data.frame accepted by stackAndExtract)
# lightningMap is a named SpatRaster (e.g., "lightningDays")

out <- mergePreparedCovs(
  years = yrs,
  fuelCovsCoarse = fuelCovsCoarse,
  ignitionFirePoints = ignitionFirePoints,
  nonForestedLCCGroups = c("Shrub", "Grass", "Bare"),
  ignitionClimateCoarse = ignitionClimateCoarse,
  lightningMap = lightningMap["lightningDays"],
  digest = list(seed = 1L, cfg = "v1"),
  useCache = TRUE
)
data.table::str(out)

## End(Not run)

Description

Returns a per-fire buffer target (in pixels) by scaling size so that small fires get proportionally larger buffers and large fires plateau at baseMultiplier * size. The result is then clamped from below by minSize. Used when generating non-burned "control" pixels around historical fire perimeters.

Usage

multiplier(size, minSize = 1000, baseMultiplier = 5)

Arguments

Value

Integer vector the same length as size, giving the target buffered area in pixels for each fire.

Description

Wrapper around stats::nlminb() that calls one of the ignition objective functions (.objFunIgnition or .objFunIgnitionPW, dispatched by hvPW) and falls back to stats::optim() (L-BFGS-B) when nlminb reports a "false convergence" or similar non-convergence code (codes 7-14).

Usage

objNlminb(x, objective, lower, upper, control, hvPW, ...)

Arguments

Value

The list returned by stats::nlminb() on success, or the result of stats::optim() (with value renamed to objective) on fallback.

Description

Order of Magnitude

Usage

oom(x)

Arguments

Value

the order of magnitude

Description

DEoptim::DEoptim does not differentiate between the logistic parameters and the covariates. This splits the vector into the correct components. The split is based on the number of covariates. Therefore the number of logistic parameters is deduced from length(pars) - parsModel.

Usage

paramsSeparate(par, parsModel)

Arguments

Value

list of 2 numeric vectors covPars and logisticPars, representing the parameters for the covariates and the logistic equation, respectively.

Description

Create plot with subplots showing: a) area burned; b) number of fires; c) mean fire size.

Usage

plotBurnSummary(
  climateScenario,
  studyAreaName,
  outputDir,
  Nreps,
  years,
  pixelSize
)

Arguments

Value

list of file names corresponding to the figures and/or objects written to disk

Description

Plot cumulative burn maps

Usage

plotCumulativeBurns(
  climateScenario,
  studyAreaName,
  outputDir,
  Nreps,
  years,
  rasterToMatch
)

Arguments

Value

list of file names corresponding to the figures and/or objects written to disk

a file path corresponding to the images and/or objects written to disk

Description

Plot historic ignitions, escapes, and area burned

Usage

plotHistoricFires(
  climateScenario,
  studyAreaName,
  outputDir,
  pixelSize,
  firePolys,
  ignitionPoints
)

Arguments

Value

list of file names corresponding to the figures and/or objects written to disk

Description

Predictions from ignition model

Usage

predictIgnition(model, data, rescaleFactor, lambdaRescaleFactor)

Arguments

Value

vector of predicted values.

Description

Creates fuel covariate layers from tabular inputs using fireSenseUtils:::fireSenseCovariatesCreate(), converts the resulting data frame into a raster using SpaDES.tools::rastFromDF(), and aggregates the raster to a coarser spatial resolution with terra::aggregate() using the mean.

Usage

prepare_FuelCovsCoarse(..., rasTemplate, fact)

Arguments

Details

The function performs the following steps:

1. Generates a fuel covariate data frame using fireSenseUtils:::fireSenseCovariatesCreate(...).

2. Converts the data frame to a raster aligned with rasTemplate via SpaDES.tools::rastFromDF().

3. Aggregates the raster to a coarser resolution using terra::aggregate(fact = fact, fun = mean).

The aggregation is applied across all raster layers (if present), computing the mean of contributing cells.

Value

A terra::SpatRaster containing aggregated fuel covariate layers at the coarser spatial resolution defined by fact.

Assumptions and required environment

The function assumes that the following are available:

• fireSenseUtils:::fireSenseCovariatesCreate() (non-exported API),

• SpaDES.tools::rastFromDF(),

• the terra package.

No input validation is performed on the structure of the data returned by fireSenseCovariatesCreate().

Note

This function uses a non-exported function from fireSenseUtils via :::, which may change without notice across package versions.

References

• terra package reference manual: raster aggregation with aggregate().

• SpaDES.tools package reference manual: rastFromDF().

• fireSenseUtils package source code: fireSenseCovariatesCreate() (internal API).

See Also

terra::aggregate(), SpaDES.tools::rastFromDF()

Examples

## Not run: 
fuelCovsCoarse <- prepare_FuelCovsCoarse(
  fuels = fuelTable,
  rasTemplate = templateRaster,
  fact = 4
)

## End(Not run)

Description

Aggregates a list of ignition-relevant climate rasters to a coarser spatial resolution using terra::aggregate() (mean across source cells) and caches the resulting list with reproducible::Cache(). The cache key is augmented with a robust digest of the input rasters and a caller-provided upstream digest.

Usage

prepare_ignitionClimate(
  ignitionClimateList,
  fact,
  digest = NULL,
  useCache = TRUE
)

Arguments

Details

The function:

1. Computes a robust digest of ignitionClimateList using .robustDigest() to capture changes in input rasters.

2. Appends that digest to the user-supplied digest to form a composite cache key (dig3).

3. Aggregates each raster via terra::aggregate(fact = fact, fun = mean).

4. Wraps the aggregated list in reproducible::Cache() with omitArgs = "x" (to exclude the ephemeral list element passed to lapply) and .cacheExtra = dig3 to drive cache invalidation from the composite digest.

All rasters are processed independently via lapply(), preserving list order and names.

Value

A list of aggregated climate rasters (typically terra::SpatRaster), in one-to-one correspondence with ignitionClimateList.

Caching and reproducibility

Cache invalidation is controlled by .cacheExtra = dig3, which combines:

• a robust digest of the input rasters (.robustDigest(ignitionClimateList)), and

• the caller-provided digest (e.g., pipeline/module context).

Assumptions and required environment

The symbols .robustDigest() and reproducible::Cache() must be available. No validation is performed on input types. Aggregation is controlled by the fact parameter.

References

• terra package reference manual: aggregate() (spatial raster aggregation).

• reproducible package reference manual and vignettes: Cache() and .cacheExtra.

See Also

terra::aggregate(), reproducible::Cache()

Examples

## Not run: 
# Example (requires `terra` rasters and `reproducible` cache setup):
upstreamDigest <- .robustDigest(list(module = "Fire", version = "1.0.0"))
ignitionClimateCoarse <- prepare_ignitionClimate(
  ignitionClimateList = sim$historicalClimateRasters[
    sim$climateVariablesForFire$ignition
  ],
  fact = 4,
  digest = upstreamDigest
)

## End(Not run)

Description

Downloads, reads, aggregates, and caches multiple lightning-related rasters (e.g., daily flashes, flash density, positive CG counts) using reproducible::prepInputs(), terra::aggregate(), and reproducible::Cache(). The function builds a cache key that combines local processing context (rasterToMatch, igAggFactor, and the lightning reader) with the remote hashes of the Google Drive files, so cached results are invalidated whenever either local parameters or upstream files change.

Usage

prepare_LightningData(rtm, igAggFactor, dPath)

Arguments

Details

Lightning data is given by the authors of https://www.tandfonline.com/doi/full/10.1080/07055900.2020.1845117 It is currently not hosted by the authors. We therefore host it on Google Drive.

The function maintains an internal mapping of Google Drive file IDs for four lightning products:

• lightningDays

• lightningDensity

• positiveCG

• positiveCGdensity

For each product, it:

1. Resolves the Drive ID to a human URL, obtains remote metadata (hash),

2. Calls reproducible::prepInputs() with a reading function that should return a raster aligned to sim$rasterToMatch,

3. Aggregates the raster with terra::aggregate(fact = P(sim)$igAggFactor),

4. Caches the result with reproducible::Cache() under a product-specific function label, seeding the cache with both local and remote digests.

A final Cache() call wraps the list of per-product results to further stabilize caching across the set.

Value

A named list of aggregated lightning rasters (class list of terra::SpatRaster), with names matching: c("lightningDays", "lightningDensity", "positiveCG", "positiveCGdensity").

Caching and reproducibility

The cache key includes:

• The remote hash of each Google Drive resource (so cloud-side updates bust the cache),

• The local context digest of rasterToMatch, igAggFactor, and the reader, via .robustDigest.

This design minimizes recomputation while remaining sensitive to upstream and local changes.

Note

If prepInputs() expects a function for fun, prefer:

fun = function(...) rld(targetFile, to = sim$rasterToMatch)

instead of calling rld(...) immediately.

References

• User-provided function source (this documentation derives from the code you supplied).

• Reproducible workflows with the reproducible package and raster handling with terra as described in their package manuals and vignettes.

See Also

reproducible::prepInputs(), reproducible::Cache(), terra::aggregate()

Examples

## Not run: 
out <- prepare_LightningData(
  rtm = sim$rasterToMatch,
  igAggFactor = P(sim)$igAggFactor,
  rld = readLightningData
)
out$lightningDensity

## End(Not run)

Description

Wraps rescaleCovariates() to rescale features according to the modeling algorithm, and optionally caches results based on a robust digest of the unscaled input data. Returns a list containing the (possibly) rescaled covariates, the modeling formula (if any), per-variable rescalers (if any), the x-axis variable name(s), and the digest used for caching.

Usage

prepareCovariatesOuter(unscaledData, algorithm, rescaleVars, useCache = TRUE)

Arguments

Details

This function:

• Computes a digest of unscaledData (if useCache = TRUE) using an internal .robustDigest() to form a .cacheExtra key for reproducible::Cache().

• Calls rescaleCovariates() with formula = NULL and family = NULL (non-xgboost code-paths were removed).

• Caches the result while omitting the large arguments "covariates" and "formula" from cache key construction (via omitArgs), relying on the explicit digest instead.

Expected columns:

• ignitions: if present, is preserved through standardization (xgboost path).

• escapes: if present, is preserved through standardization (xgboost path).

• year or yr: used to infer xvar (see rescaleCovariates()).

Value

A list with elements:

covariates

A data.table with rescaled/standardized covariates.

formula

NULL (the non-xgboost formula path is disabled).

ignitionRescalers

Named numeric vector of per-variable 10-based rescalers (non-xgboost path) or NULL for xgboost / no-rescale.

xvar

Character vector indicating which year-like column(s) were found.

digestOfData

The digest used for caching, or NULL if useCache = FALSE.

See Also

rescaleCovariates(), reproducible::Cache()

Examples

## Not run: 
library(data.table)
dt <- data.table(pixelID = 1:3,
                 year = c(2001L, 2002L, 2003L),
                 ignitions = c(0, 1, 0),
                 x1 = c(0.01, 2.3, 15))

out <- prepareCovariatesOuter(unscaledData = dt,
                              algorithm = "xgb_classifier",
                              rescaleVars = TRUE,
                              useCache = FALSE)
str(out)

## End(Not run)

Description

Given a template raster (e.g., a flammability map) and a data.table containing pixel values for one or more land cover classes, this function reconstructs each class as a raster layer and returns a multi-layer SpatRaster whose layer names match the class names supplied in lcc.

Usage

putBackIntoRaster(lcc, landcoverDT, flammableMap)

Arguments

Details

This function:

1. Creates a working copy of the template raster's values (initialized to 0 on all non-NA cells and keeping original NAs).

2. For each class name in lcc, it pulls the corresponding vector from landcoverDT, assigns those values into the working vector at positions indicated by landcoverDT$pixelID, and then writes these values back into a fresh terra::rast(flammableMap) layer.

3. Stacks all layers into a single terra::rast() and sets layer names to lcc.

Assumptions / requirements

• flammableMap is a terra::SpatRaster providing the spatial geometry, extent, resolution, and NA mask.

• landcoverDT is a data.table with a column named pixelID that indexes cell positions in the template raster's value vector (i.e., values returned by terra::values(flammableMap, mat = FALSE)). Indices must be valid and 1-based (R-style).

• Each element of lcc is the name of a numeric column in landcoverDT.

• All layers are created in the same CRS, resolution, and extent as flammableMap.

Notes

• Non-NA cells in the template are initialized to 0 before assignment, so only positions referenced by pixelID will receive class values; other non-NA positions remain 0 in each layer.

• If you want to preserve existing values outside pixelID, modify the initialization step accordingly.

Value

A multi-layer terra::SpatRaster where each layer corresponds to one entry in lcc, with layer names set to lcc.

See Also

terra::rast(), terra::values(), terra::setValues()

Examples

## Not run: 
library(terra)
library(data.table)

# Template raster (5x5 example)
r <- rast(nrows = 5, ncols = 5, vals = NA)
# Mark some cells as valid (non-NA)
values(r) <- rep(NA_real_, ncell(r))
valid_idx <- c(3, 5, 7, 13, 17, 20)
tmp_vals <- values(r, mat = FALSE)
tmp_vals[valid_idx] <- 0
r <- setValues(r, tmp_vals)

# Data table with pixel indices and two classes
dt <- data.table(
  pixelID = valid_idx,
  Conifer  = c(0.6, 0.2, 0.8, 0.1, 0.0, 0.4),
  Deciduous = c(0.1, 0.3, 0.0, 0.4, 0.5, 0.2)
)

# Rebuild layers
out <- putBackIntoRaster(
  lcc = c("Conifer", "Deciduous"),
  landcoverDT = dt,
  flammableMap = r
)

out
names(out)        # "Conifer" "Deciduous"
plot(out)

## End(Not run)

Description

Implements the right-hand half of a piecewise-linear (hinge) term: pmax(variable - knot, 0). Used in formulas passed to the ignition fitting routines so that a covariate can have zero effect below a threshold and a linear effect above it.

Usage

pw(variable, knot)

Arguments

Value

Numeric vector the same length as variable, with each element equal to max(variable[i] - knot, 0).

Description

this is a wrapper to simplify caching of lapply with bufferForFireRaster. Years are iteratively processed by makeFireID.

Usage

rasterFireBufferDT(
  years,
  fireRaster,
  flammableRTM,
  bufferForFireRaster,
  areaMultiplier,
  minSize = 5000,
  verb = 1,
  cores = 1
)

Arguments

Value

a list of data.tables named by year, with cols ids, buffer, and pixelID

Description

Create a list of annual ignition points based on fire raster

Usage

rasterFireSpreadPoints(fireBufferDT, flammableRTM)

Arguments

Value

a list of sf point objects

Description

Generate random beta variates between 2 values and a mean

Usage

rbetaBetween(n, l, u, m, shape1, shape2 = NULL)

Arguments

See Also

stats::rbeta

Description

Data is not publicly available; it is currently stored in a User Access Controlled location. Data comes from William Burrows. Please contact him to obtain data. This function will get the data (which is in a .txt format) and do all the necessary sequence of calculations to create a SpatRaster.

Usage

readLightningData(filename, ...)

Arguments

Value

This will return a SpatRaster object with resolution the same as that supplied by to or projectTo. If no SpatRaster is supplied, it will default to resolution of 10000 m (10 km x 10 km).

References

Kochtubajda, B., & Burrows, W. R. (2020). Cloud-to-Ground Lightning in Canada: 20 Years of CLDN Data. Atmosphere-Ocean, 58(5), 316–332. https://doi.org/10.1080/07055900.2020.1845117

Examples

## Not run: 
# The example fetches from a Google Drive folder that requires
# `drive_auth()` credentials. R CMD check runs examples
# non-interactively where no Drive token is available, so the body
# is gated under \dontrun{} to keep docs complete without breaking
# checks.
if (require(googledrive, quietly = TRUE)) {
  crsToUse <- paste("+proj=lcc +lat_0=0 +lon_0=-95 +lat_1=49 +lat_2=77",
                    "+x_0=0 +y_0=0 +datum=NAD83 +units=m +no_defs")
  ras <- terra::rast(
    terra::ext(-1115000, -376750, 7267000, 7874000),
    resolution = 250,
    vals = 1,
    crs = crsToUse
  )
  ## Google Drive folder:
  ## <https://drive.google.com/drive/folders/1ftpKKUO8BZcJ9ba4LDWcmF5uQkpRGmku>
  data <- list(
    lightningDays = "1jeKJquhVJsesoNk2EPP1QZkttX3Zwp5c",
    lightningDensity = "12fnhfKtER-JXkl06M4_yZ3GvpZWtQlIr",
    positiveCG = "1bn6cQ23tvPicFLHn1tz4Z3AqDzJI4r60",
    positiveCGdensity = "1GNixhXj1Ex1jT0tWXfhmxef-dX3ze1a4"
  )
  lightning <- Map(
    url = data,
    f = function(url) {
      reproducible::prepInputs(
        url = url,
        fun = readLightningData(targetFile, to = ras),
        destinationPath = file.path(tempdir(), "lightning_data")
      )
    }
  )
}

## End(Not run)

Description

Remove buffered fires in fireBufferedListDT that are outside flammableRTM

Usage

removeBufferedFiresOutsideRTM(fireBufferedDT, flammableRTM)

Arguments

Value

fireBufferedDT excluding fires with indices (burned or unburned) outside flammableRTM

Description

Applies either order-of-magnitude rescaling to approximately confine features to the [0, 10] range (non-xgboost) or standardization via base::scale() (xgboost path). Preserves key response columns when present.

Usage

rescaleCovariates(formula, covariates, rescaleVars, modelAlgorithm)

Arguments

Details

Year variable inference: If any of c("year", "yr") match column names (case-insensitive), xvar is set to the intersection. Otherwise, the code references rows (a TODO), which is undefined here. This appears to be a bug or placeholder and will error unless rows exists in scope; consider providing a default (e.g., NULL) or removing.

Non-xgboost path:

• Excludes pixelID, ignitions, escapes, year, and yearChar from rescaling.

• Computes per-variable rescalers <- 10^(floor(log10(abs(max)))) for variables whose maxima fall outside [0, 10].

• Calls rescaleVarsByMagnitude(covariates, ignitionRescalers) (must exist in scope).

xgboost path:

• Standardizes numeric columns except yearChar, ignitions, and escapes.

• Preserves original ignitions and (if present) escapes columns.

• Attaches centering/scaling attributes under attr(covariates, "scaleData").

External references:

• Uses ignitionsTxt and escapesTxt to refer to the expected response column names. If these are not available, ensure compatible strings are provided (see exported constants below).

Value

A list with elements:

covariates

A data.table after rescaling/standardization.

formula

The input formula (often NULL in current usage).

ignitionRescalers

Named numeric vector of per-variable rescalers (non-xgb) or NULL.

xvar

Character vector with detected year-like column(s) or (bug) rows.

See Also

base::scale()

Examples

## Not run: 
library(data.table)
dt <- data.table(ignitions = c(0,1,0),
                 escapes = c(0,0,1),
                 year = 2001:2003,
                 x1 = c(0.05, 12, 100),
                 x2 = c(5, 6, 7))

# XGBoost-like standardization
out_xgb <- rescaleCovariates(NULL, dt, rescaleVars = TRUE, modelAlgorithm = "xgb_tree")
str(out_xgb)

# Non-xgboost magnitude rescaling
out_other <- rescaleCovariates(NULL, dt, rescaleVars = TRUE, modelAlgorithm = "glm")
str(out_other)

## End(Not run)

Description

rescale function no.2

Usage

rescaleKnown2(x, minNew, maxNew, minOrig, maxOrig)

Arguments

Value

the rescaled vector

Description

Rescale a data.table according to a named vector of rescalers

Usage

rescaleVarsByMagnitude(dt, rescalers)

Arguments

Value

the data.table with rescaled values

Description

Provides a wrapper around DEoptim::DEoptim, setting up the multiple cluster connections. This will only work if ssh keys are preconfigured on all machines (if using multiple machines).

Internal function called by runDEoptim. Runs DEoptim::DEoptim in steps, caching results and optionally visualizing progress after each step.

Usage

runDEoptim(
  landscape,
  annualDTx1000,
  nonAnnualDTx1000,
  fireBufferedListDT,
  historicalFires,
  itermax,
  initialpop = NULL,
  NP = NULL,
  trace,
  strategy,
  cores = NULL,
  paths,
  libPath = .libPaths()[1],
  logPath = tempfile(sprintf("fireSense_SpreadFit_%s_", format(Sys.time(),
    "%Y-%m-%d_%H%M%S")), fileext = ".log"),
  doObjFunAssertions = getOption("fireSenseUtils.assertions", TRUE),
  iterStep = 25,
  lower,
  upper,
  mutuallyExclusive,
  formulaToFit,
  objFunCoresInternal,
  covMinMax = covMinMax,
  tests = c("SNLL", "adTest"),
  maxFireSpread,
  Nreps,
  thresh = 550,
  .c = 0.5,
  .verbose,
  visualizeDEoptim = logPath,
  .plots = "screen",
  .plotSize = list(height = 1600, width = 2000),
  rep = 1L,
  runName = ""
)

DEoptimIterative(
  itermax,
  lower,
  upper,
  control,
  formulaToFit,
  covMinMax,
  tests = c("SNLL", "adTest"),
  objFunCoresInternal,
  maxFireSpread,
  Nreps,
  visualizeDEoptim,
  figPath,
  cachePath,
  mutuallyExclusive,
  doObjFunAssertions = getOption("fireSenseUtils.assertions", TRUE),
  iterStep = 25,
  thresh = 550,
  .c = 0.5,
  .verbose,
  .plots = "screen",
  .plotSize = list(height = 1600, width = 2000),
  rep = 1L
)

termsInDEoptim(fireSense_spreadFormula, thresh, numParams)

Arguments

Value

The result of the DEoptimIterative() call. This is typically a list where each element contains the DEoptim::DEoptim object state after a block of iterStep iterations. The final element represents the state after itermax iterations or upon early stopping.

Description

Extracting only the "ELF" module, runs the projectmodule via SpaDES.core::simInitAndSpades2() with caching (optionally updates a Google Drive file if the current user is "emcintir"), and returns the vector of polygon IDs from spreadFitPreRun.

Usage

runELFs(
  preRunSetupProject,
  whatOut = c("fittedNamesOnly", "allNames", "maps"),
  urlELFresults = paste0("https://drive.google.com/file/d/",
    "1tkC944mPzR9-y-qCMDB5o2cAR_1MoDz4/view?usp=drive_link")
)

Arguments

Details

The function:

1. Restricts preRunSetupProject$modules to entries matching "ELFs".

2. Collects all .R source files under each module directory (recursively), excluding any under tests/, and uses these as part of the cache key.

3. Retrieves remote metadata (hash) from a Google Drive file URL and assigns the remote hash to preRunSetupProject$params$fireSense_ELFs$hashSpreadFitRemoteFile.

4. Initializes and runs the simulation with SpaDES.core::simInitAndSpades2(), wrapping the call in Cache() so that the run is skipped unless inputs (source files and remote hash) have changed.

5. If the current SpaDES.project::user() is "emcintir", updates the Google Drive file at the provided URL with any output files whose names contain "ELF", caching the update by cacheId(sim).

6. Returns sim$spreadFitPreRun[[fireSenseUtils::polygonIDTxt]].

Internal Cacheing relies on two extra keys:

• src: paths to module .R files (excluding tests/).

• remoteHash: the remote metadata hash obtained from the URL.

The function expects preRunSetupProject to be a SpaDES project list with at least:

• $modules: character vector of module names.

• $paths$modulePath: base directory containing module folders.

• $params$fireSense_ELFs: a list where hashSpreadFitRemoteFile can be set.

Value

A vector corresponding to sim$spreadFitPreRun[[fireSenseUtils::polygonIDTxt]]. Currently, no high arctic ELFs are returned (e.g., Ecoprovinces starting with either 1. or 2.)

Side Effects

Updates a Google Drive file when the current user is "emcintir" and when the run produces outputs with names containing "ELF".

Notes

• The remote file URL is hard-coded as: "https://drive.google.com/file/d/1tkC944mPzR9-y-qCMDB5o2cAR_1MoDz4/view?usp=drive_link".

• Cache() and cacheId() are assumed to be available (typically from reproducible in SpaDES workflows).

• asPath() is expected to be available in your environment (commonly from reproducible); adjust if your project defines it elsewhere.

Author(s)

Based on the provided code snippet.

See Also

simInitAndSpades2, Cache, drive_update

Examples

## Not run: 
# Assuming 'prj' is a valid SpaDES project list:
# prj <- somePreparationFunction(...)
ids <- runELFs(prj)

## End(Not run)

Description

Convert covariates from their x1000 integer to usable by spread

Usage

spreadProbFromIntegerCovs(
  shortAnnDTx1000 = NULL,
  annDTx1000,
  nonAnnualDTx1000,
  indexNonAnnual,
  yr,
  covMinMax = NULL,
  mutuallyExclusive,
  colsToUse,
  doAssertions,
  logisticPars,
  covPars,
  maxFireSpread,
  lowerSpreadProb
)

Arguments

Value

This returns the full data.table to be used for fireSense, on the original numeric i.e., real scale, with the x1000 reversed.

Description

Prepare covariate table with ignition year, fuel class, climate value, and land cover

Usage

stackAndExtract(years, fuel, LCC, climate, fires = NULL)

Arguments

Value

a data.frame with cell numbers, ignitions, and covariates for each year

Description

This simply converts to integers times 1000 so that the values can be saved more quickly to disk, for example.

Usage

toX1000(lst, omitCols = "pixelID")

Arguments

Value

The same data.frame, but with columns converted to integer and times 1000

Description

Update name of layers in a climate raster stack

Usage

updateStackYearNames(annualDataStack, desiredYears)

Arguments

Description

Make histograms of DEoptim object pars

Usage

visualizeDE(DE, cachePath, titles, lower, upper)

Arguments