fireSense_SizePredict.Rmd

---
title: "fireSense_SizePredict"
author: "Jean Marchal (jean.d.marchal@gmail.com)"
date: "`r format(Sys.time(), '%B %Y')`"
output:
  html_document: default
  pdf_document: default
---

# Overview
Predicts two parameters of the tapered Pareto distribution, $\beta$ and $\theta$, using a model fitted with the fireSense_SizeFit module. $\beta$ controls the rate of frequency decrease as the fire size increases, and $\theta$ governs the location of the exponential taper.

# Download the module
```{r download module, eval = FALSE, echo = TRUE}
library(SpaDES)

moduleName <- "fireSense_SizePredict"

spadesModulesDirectory <- tempdir() # Location where the module will be downloaded

downloadModule(moduleName, path = spadesModulesDirectory)
```

# Usage
## Module parameters
Name|Default|Description
----|:-------|---------------------------------------------------------------------
`modelName`|`"fireSense_SizeFitted"`|name of the object of class fireSense_SizeFit describing the statistical model used for predictions.
`data`|`"dataFireSense_SizePredict"`|a character vector indicating the names of objects in the `simList` environment in which to look for variables present in the model formula. `data` objects can be data.frames, RasterStacks or RasterLayers. However, data.frames cannot be mixed with objects of other classes.
`mapping`|`NULL`|optional named vector or list of character strings mapping one or more variables in the model formula to those in `data` objects.
`.runInitialTime`|`start(simList)`|when to start this module? By default, the start time of the simulation.
`.runInterval`|`1`|optional. Interval between two runs of this module, expressed in units of simulation time. By default, 1 year.
`.saveInitialTime`|`NA`|optional. When to start saving output to a file.
`.saveInterval`|`NA`|optional. Interval between save events.

## Usage example
```{r module usage example, eval = FALSE}
library(magrittr)
library(PtProcess)
library(raster)
library(SpaDES)

set.seed(123)

spadesModulesDirectory <- ".."

# Define simulation parameters
times <- list(start = 1, end = 1, timeunit = "year")
modules <- list("fireSense_SizePredict")
paths <- list(
  modulePath = spadesModulesDirectory
)

# Create random weather and fire size data
  # data.frame
  dataObject <- data.frame(
    weather = rnorm(1000, 150, 30),
    size_ha = rtappareto(1000, .3, 1e4, a = 1)
  )
  
  # raster
  nx <- ny <- 100L
  size_ha <- raster(nrows = ny, ncols = nx, xmn = -nx/2, xmx = nx/2, ymn = -ny/2, ymx = ny/2) %>%
    setValues(rtappareto(ncell(.), .3, 1e4, a = 1))
  weather <- gaussMap(size_ha, scale = 300, var = 0.03, speedup = nx/5e2, inMemory = TRUE)
  dataObject <- stack(weather, size_ha) %>% setNames(c("weather", "size_ha"))

# Create a typical output of fireSense_SizeFit
fireSense_SizeFitted <- list(
  formula = list(beta = size_ha ~ weather2,
                 theta = size_ha ~ weather),
  link = list(beta = make.link("log"),
              theta = make.link("identity")),
  coef = list(beta = setNames(c(1, 0.01), c("intercept", "weather2")),
              theta = setNames(c(1, 0.001), c("intercept", "weather")))
)
class(fireSense_SizeFitted) <- "fireSense_SizeFit"

# Define module parameters
parameters <- list(
  fireSense_SizePredict = list(
    mapping = list(weather2 = "weather"), # One can use mapping to map variables
                                          # in the formula of the fitted object
                                          # to those in data. Here weather2 
                                          # (formula) is mapped to weather (data).
    data = "dataObject"
  )
)

# Objects to pass from the global environment to the simList environment
objects <- c("dataObject", "fireSense_SizeFitted")

# Create the simList
sim <- simInit(
  times = times, 
  params = parameters, 
  modules = modules, 
  objects = objects, 
  paths = paths
)

sim <- spades(sim)
sim$fireSense_SizePredicted_Beta
sim$fireSense_SizePredicted_Theta
```

# Events
Events are scheduled as follows:

- Module initialisation
- Make predictions

# Data dependencies
## Input data
- **fireSense_SizeFitted**: an object of class `fireSense_SizeFit` created with the fireSense_SizeFit module.
- **dataFireSense_SizePredict**: One or more data.frames, RasterLayers or RasterStacks in which to look for variables with which to predict.

## Output data
- **fireSense_FrequencyPredicted_Beta** and **fireSense_FrequencyPredicted_Theta**: two objects whose class depends on those in input:

Input object class | Output object class
:-:|:-:
`data.frame` | `numeric`
`RasterLayer`<br>`RasterStack`<br>`RasterBrick` | `RasterLayer`
||

# Links to other modules
Predictions made with this module reflect the temporal and spatial heterogeneity found in environmental controls of fire spread. These can be used in simulation models sampling final fire sizes from a tapered Pareto distribution, or to derive probability surfaces of spread probabilities (e.g. fireSense_SpreadPredict in association with fireSense_SpreadFit).