2 fireSense_ELFs Module

2.0.0.1 Authors:

Eliot McIntire [aut, cre]

2.1 Module Overview

2.1.1 Module summary

ELFs (Ecologically-based Low Fractal-dimensional polygons) are the buffered regions of Canada that the fireSense models are fitted in, one at a time (fireSenseUtils::makeELFs()). This module makes the national ELF maps and the study area objects every other fireSense module uses: studyArea, studyAreaLarge, rasterToMatch, their *ELF versions and sppEquiv. It is scheduled before the other fireSense modules.

The study area is chosen in one of two ways. Supplying both is an error unless they agree.

  • .ELFind (e.g. "4.3"): that single ELF. *LargeELF objects include its 20 km buffer; *ELF objects do not. This is what fitting uses.
  • studyAreaLarge: the ELFs the polygon overlaps that already have fitted SpreadFit parameters. This is what prediction uses.

By default (fireYears is fireSenseUtils::defaultFireYears(), the fit’s years; NULL turns this off), ELFs with too few natural ignitions (minNaturalIgnitions) fire polygons (minFirePolygons) or escaped natural fires (minEscapes; a fire escapes at escapeSizeHa) over those years are merged with a neighbour that shares their base, or listed in ELFsExcluded (fireSenseUtils::ELFmergePlan()). Afterwards an ELF whose core is smaller than minRegionAreaKm2 is merged with a similar neighbour of the same base (land-cover distance at most maxLandCoverDist, burn-rate ratio at most maxBurnRatio), taking the merge that leaves the fewest small ELFs without a partner (fireSenseUtils::ELFsizePlan()); minRegionAreaKm2 = NA turns this off.

The module also reads the previously fitted SpreadFit parameters (spreadFitFilename in spreadFitGoogleDriveFolder) into spreadFitPreRun; a missing file means nothing has been fitted yet. It needs Google Drive access to that folder.

2.1.2 Module inputs and parameters

Table 2.1 shows the full list of module inputs.

Table 2.1: Table 2.2: List of fireSense_ELFs input objects and their description.
objectName objectClass desc sourceURL
.ELFind character Name of the ELF to use as the study area, e.g. “4.3” (the default when studyAreaLarge is not supplied either). NA
studyAreaLarge SpatVector Optional. If supplied, the study area is the ELFs it overlaps that have fitted SpreadFit parameters, instead of .ELFind. Supply one or the other, not both. NA

2.1.2.1 Sharing the ELF maps: .useCloud

Building the ELF maps in the init event is slow, so its results are shared with everyone through Google Drive. They are saved to the same fireSense folder that holds the fitted-parameter file (fireSenseParams*.rds): the folder named by spreadFitGoogleDriveFolder. Everyone reads from and writes to this one folder.

  • .useCloud = TRUE (the default): if someone has already built the maps with the same inputs, download them; otherwise build them and upload them for the next person.
  • .useCloud = "pull": download if available, but never upload. Use this if you can read the folder but not write to it. Uploads that fail are not fatal in any case; the run carries on with the local copy.
  • .useCloud = FALSE: do not use Google Drive for this; build locally.

This needs Google Drive access to that folder, which the module already needs: init reads the fitted-parameter file from it. Pass the folder as its bare ID, or as a link that has something after the ID (e.g. ending in ?usp=drive_link); until reproducible’s link handling is fixed, a link that ends exactly at the ID is not recognised, and the results go to a folder that is not shared.

Summary of user-visible parameters (Table 2.3)

Table 2.3: Table 2.4: List of fireSense_ELFs parameters and their description.
paramName paramClass default min max paramDesc cacheKey
sppEquivCol character LandR NA NA The column in sim$speciesEquivalency data.table to use as a naming convention. TRUE
fitFileSuffix character NA NA Text put after the model tag in the ledger file names, e.g. "_boundfix_rep81", so a test run writes and reads ("latest") only its own files, never the production ones. "" (the default) writes the unsuffixed file and reads ("latest") every file of the model tag, newest by the date in its suffix (fireSenseUtils::ledgerFileOrder()); experiment fits belong in spreadFitLedgerFolder(testing = TRUE). The same parameter of fireSense_spreadFit, fireSense_ignitionFit and fireSense_dataPrepFit; set it for all with .globals = list(fitFileSuffix = ...); modules that disagree stop (SpaDES.core::paramCheckOtherMods()). Ignored when a file name is given. TRUE
spreadFitFilename character latest NA NA Name of the file in spreadFitGoogleDriveFolder that holds previously fitted SpreadFit parameters. "latest" (the default) takes each ELF’s fit from the most recent file that has it (fireSenseUtils::latestSpreadFits()). TRUE
spreadFitGoogleDriveFolder character https://…. NA NA Google Drive folder URL that holds spreadFitFilename and, with .useCloud, the shared ELF maps. The default is fireSenseUtils::spreadFitLedgerFolder(), which follows options(fireSenseUtils.spreadFitLedgerFolder = ). TRUE
ignitionFitFilename character latest NA NA Name of the file in ignitionFitGoogleDriveFolder that holds the ignition/escape fits of fireSense_ignitionFit. "latest" (the default) takes each ELF’s fit from the most recent file that has it (fireSenseUtils::latestIgnitionFits()). TRUE
ignitionFitGoogleDriveFolder character https://…. NA NA Google Drive folder URL that holds ignitionFitFilename. The default is fireSenseUtils::ignitionFitLedgerFolder() (options(fireSenseUtils.ignitionFitLedgerFolder = )). NULL reads a named ledger file from inputPath(sim), with no Google Drive access. TRUE
heldOutFold integer NA NA NA NA (default): unchanged. 1 or 2: a cross-validation fold is being fitted (the same parameter as in fireSense_spreadFit), so the SpreadFit ledger is not relevant and is not read: spreadFitPreRun is NULL, no ELF counts as fitted, and studyAreaLarge is not masked to fitted ELFs. Set it for every fireSense module at once with .globals = list(heldOutFold = 1L); init stops if fireSense_spreadFit has a different value. Any other value is an error. TRUE
borderBuffer numeric 5000 0 NA Metres. Cells within this distance of the Canada-United States land border (49th parallel, Great Lakes and St Lawrence, Alaska-Yukon/BC; not the coast) are removed from every ELF (NA in rasterToMatchLargeELF, rasterToMatchELF, and out of studyAreaLarge, studyAreaLargeELF, studyAreaELF). ClimateNA’s DEM is invalid in the United States, which contaminates interpolated climate in Canadian cells ~2 km from the border; the fire data are Canada-only. The line is Natural Earth 10 m admin_0_boundary_lines_land. 0 or NA removes nothing. TRUE
fireYears integer 1986, 19…. NA NA Fire years over which each ELF’s natural ignitions and fire polygons are counted. An ELF with too few is merged with a neighbour that shares its base, or not fitted (see fireSenseUtils::ELFmergePlan()). The default is fireSenseUtils::defaultFireYears(), the default of fireSense_dataPrepFit’s fireYears, so the ELFs are merged over the years the fit uses; init warns if another module in the simList has different fireYears. NULL: no counting and no merging. TRUE
minNaturalIgnitions numeric 50 0 NA An ELF with fewer natural-cause ignitions than this over fireYears has too few fires. TRUE
minFirePolygons numeric 50 0 NA An ELF with fewer fire polygons than this over fireYears has too few fires. TRUE
escapeSizeHa numeric 50 0 NA Size (ha) a fire must reach to count as escaped, as in fireSense_dataPrepFit’s escapeSizeHa. The escape and spread fits use only escaped fires; init warns if another module in the simList has a different escapeSizeHa. TRUE
minEscapes numeric 5 0 NA An ELF with fewer escaped natural fires than this over fireYears has too few fires. 5 is the minimum the escape fit’s 5-fold cross-validation needs. TRUE
minRegionAreaKm2 numeric 35000 0 NA After the fire-count merging, an ELF whose core is smaller than this (km2) is merged with a similar neighbour that shares its base (fireSenseUtils::ELFsizePlan()), choosing the merge that leaves the fewest small ELFs without a partner. Land cover is SCANFI v2 2020. NULL or NA turns the rule off; so does fireYears = NULL. TRUE
maxLandCoverDist numeric 0.35 0 1 Size rule: largest Bray-Curtis distance between the land-cover shares of two ELFs that may merge. TRUE
maxBurnRatio numeric 6 1 NA Size rule: largest ratio (larger over smaller) of the burn rates (%/yr over fireYears) of two ELFs that may merge. TRUE
.plots character screen NA NA Passed to types in Plots(). If any, init plots the map of all ELFs and this run’s study areas. TRUE
.plotInitialTime numeric 0 NA NA NA turns off screen plots in Plots(). No plot event is scheduled. TRUE
.studyAreaName character NA NA NA Human-readable name for the study area; used in the filename of the single-ELF raster. TRUE
ELFversion character 2026-10-26 NA NA The only thing that decides whether the national ELF list is rebuilt. The list is built once, kept in the cache and, with .useCloud, shared through Google Drive. Change this by hand to rebuild it. Changing other parameters (fireYears, minNaturalIgnitions, …) or the code does NOT rebuild it unless this changes. TRUE
.useCache logical FALSE NA NA Events to cache. The default caches no event: the national ELF list has its own cache, keyed on ELFversion alone, which an event cache (keyed on parameters and module version) would undo. TRUE
.useCloud logical,…. TRUE NA NA Share the national ELF list (see ELFversion) through Google Drive, in the fireSense folder named by spreadFitGoogleDriveFolder (the same folder that holds the fitted-parameter file). TRUE: download the list if someone has already built it for this ELFversion, otherwise build and upload it. "pull": download only, never upload (for read-only access). FALSE: build locally without Google Drive. Needs Google Drive access to that folder. TRUE
.useCacheArgs list NA NA Extra Cache() arguments for each event, by event name. None by default; see .useCache. TRUE

2.1.3 Events

init only; it does everything above.

2.1.4 Plotting

Unless .plots is NA, init plots a map of all ELFs (green: already fitted; yellow: this run’s ELF, .ELFind) and the study areas of this run. Plot files go to inputPath.

2.1.5 Saving

Nothing is saved apart from the rasters and downloads written to inputPath.

2.1.6 Module outputs

Description of the module outputs (Table 2.5).

Table 2.5: Table 2.6: List of fireSense_ELFs outputs and their description.
objectName objectClass desc
ELFs SpatRaster All ELFs, from fireSenseUtils::makeELFs(): a list with rasWhole and rasCentered (one SpatRaster per ELF), plus poly when studyAreaLarge is supplied.
rasterToMatchLargeELF SpatRaster Raster of the ELF(s) in the study area, including the ELF buffer when a single ELF is used.
rasterToMatchELF SpatRaster rasterToMatchLargeELF without the buffer when a single ELF is used; identical to it when studyAreaLarge is supplied.
rasterToMatch SpatRaster Only if not already in the simList: the national template raster cropped and masked to studyAreaLarge; 1 inside, NA outside.
studyArea SpatVector Only if not already in the simList: same as studyAreaLarge.
studyAreaLarge SpatVector Single ELF: the buffered ELF. studyAreaLarge supplied: the supplied polygon intersected with the ELFs that have fitted SpreadFit parameters, dissolved.
studyAreaLargeELF SpatVector Polygons of rasterToMatchLargeELF.
studyAreaELF SpatVector Polygons of rasterToMatchELF.
sppEquiv data.table Species table for studyAreaELF from LandR::speciesInStudyArea(). Zero rows for a few non-forested ELFs.
ELFsExcluded character ELFs with too few fires over fireYears that could not be merged; fireSenseUtils::runELFs() leaves them out of the queue. NULL when fireYears is NULL.
ELFfireStatus data.table Natural ignitions, escaped natural ignitions, fire polygons and zero/few/ok status of every ELF over fireYears (fireSenseUtils::ELFfitStatus()). NULL when fireYears is NULL.
ELFmerges data.table The merges and skips decided for ELFs with too few fires (fireSenseUtils::ELFmergePlan()), and the merges of ELFs smaller than minRegionAreaKm2 (fireSenseUtils::ELFsizePlan()). NULL when fireYears is NULL.
spreadFitPreRun data.frame This is a data.frame that has a geometry list column, so it can be converted to a sf or SpatVector (e.g., terra::vect(sf::st_as_sf(sim$spreadFitPreRun)) , plus other mostly list columns: numIterations, objFunVal (not list), params, sppEquiv, nonForestedLCCGroups, missingLCCgroup, and polygonID. These are from previously fitted SpreadFit. If no pre-existing object exists from CacheGeo, this will be NULL
fireSense_IgnitionFittedList list One fireSense_IgnitionFitted per ELF the study area touches, named by ELFind, read from the ledger of fireSense_ignitionFit. With studyAreaLarge an ELF without a fit is an error. With one ELF, NULL when it has no fit yet (fireSense_ignitionFit is about to fit it), and always NULL when heldOutFold is not NA.
fireSense_EscapeFittedList list As fireSense_IgnitionFittedList, for fireSense_EscapeFitted.

2.1.7 Usage

library(SpaDES.core)

mySim <- simInit(times = list(start = 2011, end = 2011), modules = list("fireSense_ELFs"),
    objects = list(.ELFind = "4.3"), params = list(fireSense_ELFs = list(.useCloud = "pull")),
    paths = list(modulePath = ".."))
mySim <- spades(mySim)

2.2 References