timeSinceFire.Rmd

---
title: "timeSinceFire Manual"
subtitle: "v.`r SpaDES.core::moduleMetadata(module = 'timeSinceFire', path = '..')$version`"
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
---

# 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.
This one is peculiar to the LandWeb application.

`ageMap` is incremented without bound on all flammable cells;
cells identified as having been burned in the current year are set to 0.

Any statistics on age structure are to be calculated here, but none are yet implemented...because with the current fire model they would be pretty boring. 

### 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 SpatialPoygonDataFrame `shpStudyRegion`.
This procedure retains the `NA`s which mask the actual study region within the template bounding rectangle. 

Then, the RasterLayer `rstFlammable` is used to mask out areas of open water, rock, 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 in the shapefile are set to the fire return interval specified for that polygon / ecoregion.
Under the basic van Wagner model being implemented, this is the expected landscape mean age.
The ecoregion 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 ecoregion 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 `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 input vector `burnLoci` 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.