timeSinceFire.Rmd

---
title: "timeSinceFire Manual"
subtitle: "v.`r SpaDES.core::moduleVersion(module = 'timeSinceFire', path = '..')`"
date: "Last updated: `r Sys.Date()`"
output:
  bookdown::html_document2:
    toc: true
    toc_float: true
    theme: sandstone
    number_sections: false
    df_print: paged
    keep_md: yes
editor_options:
  chunk_output_type: console
  bibliography: citations/references_timeSinceFire.bib
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](https://github.com/PredictiveEcology/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](https://github.com/PredictiveEcology/LandWeb/tree/v2).

# timeSinceFire Module

<!-- the following are text references used in captions for LaTeX compatibility -->
(ref:timeSinceFire) *timeSinceFire*

```{r setup-timeSinceFire, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, eval = FALSE, results = "hold") ## change to eval = TRUE if all chunks are to be evaluated

## get citation style
if (!file.exists("citations/ecology-letters.csl")) {
  dir.create("citations", showWarnings = FALSE)
  download.file("https://www.zotero.org/styles/ecology-letters", destfile = "citations/ecology-letters.csl")
}

if (!require(dplyr)) {
  install.packages("dplyr")
  library(dplyr)
}
```

:::{.rmdwarning}
This documentation is work in progress.
Please report any discrepancies or omissions at <https://github.com/fRI-Research/timeSinceFire/issues>.
:::

#### Authors:

`r paste(as.character(SpaDES.core::moduleMetadata(module = "timeSinceFire", path = '..')$authors), sep = ', ')`
<!-- ideally separate authors with new lines, '\n' not working -->

## Module Overview

### Module summary

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.

### Module inputs and parameters

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

```{r moduleInputs-timeSinceFire, echo = FALSE, eval = TRUE, message = FALSE, warning = FALSE}
df_inputs <- SpaDES.core::moduleInputs("timeSinceFire", "..")
knitr::kable(df_inputs,
             caption = "List of (ref:timeSinceFire) input objects and their description.") |>
  kableExtra::kable_styling(latex_options = "scale_down", full_width = FALSE)
```

A summary of user-visible parameters is provided in Table \@ref(tab:moduleParams-timeSinceFire).

```{r moduleParams-timeSinceFire, echo = FALSE, eval = TRUE, message = FALSE, warning = FALSE}
df_params <- SpaDES.core::moduleParams("timeSinceFire", "..")
knitr::kable(df_params, caption = "List of (ref:timeSinceFire) parameters and their description.") |>
  kableExtra::kable_styling(latex_options = "scale_down", full_width = FALSE)
```

### Events

#### Init

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 `NA`s 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 `NA`s 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 $log(2)$ and then rounding; or some other lower quantile could be chosen: see the [wikipedia page](https://en.wikipedia.org/wiki/Exponential_distribution) for the general quantile function.

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.

```{r}
U_ <- runif(ncell(rstTimeSinceFire))
T_ <- (-log(U_)) * rstTimeSinceFire[]
rstTimeSinceFire[] <- round(T_)
```

#### Plotting

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.

#### Saving

Nothing is saved at present. 

#### Age

This is the main event: `rstFlammable` is incremented by one.
Then burned cells, as specified in the `burnLoci` vector are set to age 0.

### Module outputs

Description of the module outputs (Table \@ref(tab:moduleOutputs-timeSinceFire)).

```{r moduleOutputs-timeSinceFire, echo = FALSE, eval = TRUE, message = FALSE, warning = FALSE}
df_outputs <- SpaDES.core::moduleOutputs("timeSinceFire", "..")
knitr::kable(df_outputs, caption = "List of (ref:timeSinceFire) outputs and their description.") |>
  kableExtra::kable_styling(latex_options = "scale_down", full_width = FALSE)
```

### Code and data availability

Code available from <https://github.com/fRI-Research/timeSinceFire>.

### Links to other modules

Originally developed as part of the [LandWeb](https://github.com/PredictiveEcology/LandWeb) project.