2 fireSense_ELFs Module
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.*LargeELFobjects include its 20 km buffer;*ELFobjects 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.
| 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.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.6 Module outputs
Description of the module outputs (Table 2.5).
| 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.8 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.