title	fireSense_ELFs Manual
subtitle	v.1.2.0
date	Last updated: 2026-10-07
output	bookdown::html_document2 toc toc_float theme number_sections df_print keep_md true true sandstone false paged true
editor_options	chunk_output_type console
bibliography	citations/references_fireSense_ELFs.bib
link-citations	true
always_allow_html	true

fireSense_ELFs Module

(ref:fireSense-ELFs) fireSense_ELFs

Authors:

Eliot McIntire eliot.mcintire@nrcan-rncan.gc.ca [aut, cre]

Module Overview

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.

If fireYears is set, ELFs with too few natural ignitions (minNaturalIgnitions) or fire polygons (minFirePolygons) over those years are merged with a neighbour that shares their base, or listed in ELFsExcluded (fireSenseUtils::ELFmergePlan()).

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.

Module inputs and parameters

Table @ref(tab:moduleInputs-fireSense-ELFs) shows the full list of module inputs.

(\#tab:moduleInputs-fireSense-ELFs)(\#tab:moduleInputs-fireSense-ELFs)List of (ref: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).	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

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 @ref(tab:moduleParams-fireSense-ELFs))

(\#tab:moduleParams-fireSense-ELFs)(\#tab:moduleParams-fireSense-ELFs)List of (ref:fireSense-ELFs) parameters and their description.

paramName	paramClass	default	min	max	paramDesc
sppEquivCol	character	LandR	NA	NA	The column in `sim$speciesEquivalency` data.table to use as a naming convention.
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()`).
spreadFitGoogleDriveFolder	character	https://....	NA	NA	Google Drive folder URL that holds `spreadFitFilename` and, with `.useCloud`, the shared ELF maps.
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()`).
ignitionFitGoogleDriveFolder	character	https://....	NA	NA	Google Drive folder URL that holds `ignitionFitFilename`. `NULL` reads a named ledger file from `inputPath(sim)`, with no Google Drive access.
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.
queue_path	character		NA	NA	A character scalar indicating what the filename of the queue.rds file is from experimentTmux; if NULL, then this can't determine which ELFs are being run (no 'yellow' on the map)
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.
fireYears	integer		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()`). `NULL`: no counting and no merging.
minNaturalIgnitions	numeric	50	0	NA	An ELF with fewer natural-cause ignitions than this over `fireYears` has too few fires.
minFirePolygons	numeric	50	0	NA	An ELF with fewer fire polygons than this over `fireYears` has too few fires.
.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.
.plotInitialTime	numeric	0	NA	NA	`NA` turns off screen plots in `Plots()`. No plot event is scheduled.
.studyAreaName	character	NA	NA	NA	Human-readable name for the study area; used in the filename of the single-ELF raster.
.useCache	logical	init	NA	NA	Events to cache. The default caches `init`; see `.useCloud`.
.useCloud	logical,....	TRUE	NA	NA	Share the ELF maps built in the `init` event through Google Drive, in the fireSense folder named by `spreadFitGoogleDriveFolder` (the same folder that holds the fitted-parameter file). `TRUE`: download the maps if someone has already built them with the same inputs, otherwise build and upload them. `"pull"`: download only, never upload (for read-only access). `FALSE`: build locally without Google Drive. Needs Google Drive access to that folder.
.useCacheArgs	list	list(use....	NA	NA	Extra `Cache()` arguments for each event. By default the `init` event uses `.useCloud` and caches to `spreadFitGoogleDriveFolder`; see `.useCloud`. Its key also includes a digest of `LandR::sppEquivalencies_CA`, which `init` reads, so a change to that table rebuilds the ELF maps instead of reusing old ones.

Events

init only; it does everything above.

Plotting

Unless .plots is NA, init plots a map of all ELFs (green: already fitted; yellow: running now, if queue_path is given) and the study areas of this run. Plot files go to inputPath.

Saving

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

Module outputs

Description of the module outputs (Table @ref(tab:moduleOutputs-fireSense-ELFs)).

(\#tab:moduleOutputs-fireSense-ELFs)(\#tab:moduleOutputs-fireSense-ELFs)List of (ref: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, 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()). 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`.

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)

Links to other modules

All other fireSense modules, and the LandR modules run with them, take their study area, rasterToMatch and sppEquiv from this module.

Getting help

• https://github.com/PredictiveEcology/fireSense_ELFs/issues

References