| title | timeSinceFire Manual | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| subtitle | v.3.0.0 | ||||||||||||||
| date | Last updated: 2026-08-06 | ||||||||||||||
| output |
|
||||||||||||||
| editor_options |
|
||||||||||||||
| citation-style | citations/ecology-letters.csl | ||||||||||||||
| link-citations | true | ||||||||||||||
| always_allow_html | true |
Important
This repository is archived and is no longer maintained.
Archiving makes a repository read-only — it does not remove it. This repository stays public and clonable, and existing pins continue to work: any project that pins a specific commit (e.g. as a git submodule) can fetch and check out that commit exactly as before. No branches or tags have been deleted. If your project tracks a branch rather than a pinned commit, pin it now.
Development ended when this module was retired from LandWeb v3 (July 2026), where its
functionality — deriving the time-since-fire raster (rstTimeSinceFire) — is now provided by
burnSummaries. LandWeb was not the only
user of this module; other projects are unaffected and may continue to use it at their pinned
commit.
Two releases are tagged as convenience reference points:
v-final (f77e0e96) — the final state of this module; and
LandWeb-v2 (1df453ec) — the commit pinned by the
LandWeb v2 branch.
(ref:timeSinceFire) timeSinceFire
:::{.rmdwarning} This documentation is work in progress. Please report any discrepancies or omissions at https://github.com/fRI-Research/timeSinceFire/issues. :::
Steve G Cumming stevec@sbf.ulaval.ca [aut], Alex M. Chubaty achubaty@for-cast.ca [aut, cre]
Yet Another Age Map Maintainer.
ageMap is incremented without bound on all flammable cells;
cells identified as having been burned in the current year are set to 0.
Table @ref(tab:moduleInputs-timeSinceFire) shows the full list of module inputs.
| objectName | objectClass | desc | sourceURL |
|---|---|---|---|
| fireReturnInterval | SpatRaster | A Raster where the pixels represent the fire return interval, in years. | NA |
| rstCurrentBurn | SpatRaster | Binary raster of fires, 1 meaning 'burned', 0 or NA is non-burned | NA |
| rstFlammable | SpatRaster | A binary Raster, where 1 means 'can burn'. | NA |
| rstTimeSinceFire | SpatRaster | A Raster where the pixels represent the number of years since last burn. | NA |
A summary of user-visible parameters is provided in Table @ref(tab:moduleParams-timeSinceFire).
| paramName | paramClass | default | min | max | paramDesc |
|---|---|---|---|---|---|
| fireTimestep | integer | 1 | NA | NA | The number of time units between successive fire events. |
| returnInterval | numeric | 1 | NA | NA | interval between main events |
| startTime | numeric | 0 | NA | NA | time of first burn event |
| .plotInitialTime | numeric | NA | NA | NA | simulation time at which the first plot event should occur |
| .plotInterval | numeric | NA | NA | NA | simulation time at which the first plot event should occur |
| .plots | character | screen | NA | NA | Passed to `types` in `Plots` (see `?Plots`). There are a few plots that are made within this module, if set. Note that plots (or their data) saving will ONLY occur at `end(sim)`. If `NA`, plotting is turned off completely (this includes plot saving). |
| .saveInitialTime | numeric | NA | NA | NA | simulation time at which the first save event should occur |
| .saveInterval | numeric | NA | NA | NA | simulation time at which the first save event should occur |
| .useCache | logical | FALSE | NA | NA | simulation time at which the first save event should occur |
The Init event creates the RasterLayer rstTimeSinceFire.
To do this, it rasterizes the template vegetation map LCC05 using the FireReturnInterval field of the studyAreaReporting polygons.
This procedure retains the NAs which mask the actual study region within the template bounding rectangle.
Then, the rstFlammable raster is used to mask out areas of open water, rock, ice, etc. which can't burn and thus for which timeSinceFire is not applicable.
These become NAs in rstTimeSinceFire.
The results is that all flammable cells within each polygon are set to the fire return interval specified for that polygon. Under the basic van Wagner model being implemented, this is the expected landscape mean age. The polygon age structure will equilibrate to the exponential distribution within a few multiples of the return interval.
No colour ramp or legend is created for this layer.
In the short term, this initial uniform age distribution will result in very high proportions of cells with TSFs greater than the return interval.
If this becomes a problem, one could initialize to the regional median age.
This can be done by multiplying the FireReturnInterval by
Alternatively, a random exponential age structure could be generated for each polygon from the current rstTimeSinceFire, roughly as follows.
See the wiki page for details and possible alternative methods.
U_ <- runif(ncell(rstTimeSinceFire))
T_ <- (-log(U_)) * rstTimeSinceFire[]
rstTimeSinceFire[] <- round(T_)A bare call to terra::plot(sim$rstTimeSinceFire).
If you really want to see this, you'll have to live with the automated colour scheme and legend, or hack Init to your satisfaction.
Nothing is saved at present.
This is the main event: rstFlammable is incremented by one.
Then burned cells, as specified in the burnLoci vector are set to age 0.
Description of the module outputs (Table @ref(tab:moduleOutputs-timeSinceFire)).
| objectName | objectClass | desc |
|---|---|---|
| burnLoci | integer | Cell indices where burns occurred in the latest year. It is derived from `rstCurrentBurn`. |
| rstTimeSinceFire | SpatRaster | A Raster where the pixels represent the number of years since last burn. |
Code available from https://github.com/fRI-Research/timeSinceFire.
Originally developed as part of the LandWeb project.