fireSense_IgnitionPredict.Rmd

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

# Overview
Predicts fire frequency or rates of fire counts using a model fitted with the fireSense_IgnitionFit module. Use them to feed the ignition component of a landscape fire model (e.g fireSense).

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

moduleName <- "fireSense_IgnitionPredict"

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

downloadModule(moduleName, path = spadesModulesDirectory)
```

# Usage
## Module parameters
Name|Default|Description
----|:-------|---------------------------------------------------------------------
`modelObjName`|`"fireSense_IgnitionFitted"`|name of the object of class fireSense_IgnitionFit describing the statistical model used for predictions.
`data`|`"dataFireSense_IgnitionPredict"`|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.
`rescalFactor`|`1`|rescale predicted rates of fire counts at any given temporal and spatial resolutions by a factor $rescalFactor = new\_res / old\_res$. `rescalFactor` is the ratio between the data aggregation scale used for model fitting and the scale at which predictions are to be made.
`.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 outputs to a file.
`.saveInterval`|`NA`|optional. Interval between save events.
|||

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

set.seed(123)

spadesModulesDirectory <- ".."

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

# Create random weather and fire frequency data
  # data.frame
  dataFireSense_IgnitionPredict <- data.frame(
    weather = rnorm(1000, 150, 30),
    fireFrequency = rpois(1000, .5)
  )
  
  nx <- ny <- 100
  
  # raster
  dataFireSense_IgnitionPredict <- 
    raster(nrows = ny, ncols = nx, xmn = -nx/2, xmx = nx/2, ymn = -ny/2, ymx = ny/2) %>%
      gaussMap(scale = 300, var = 0.03, speedup = nx/5e2, inMemory = TRUE) %>%
      stack %>% setNames("weather")

# Create a typical output of fireSense_IgnitionFit
fireSense_IgnitionFitted <- list(
  formula = fireFrequency ~ weather2,
  family = poisson(),
  coef = setNames(c(0.1, 0.01), c("intercept", "weather2"))
)
class(fireSense_IgnitionFitted) <- "fireSense_IgnitionFit"

# Define module parameters
parameters <- list(
  fireSense_IgnitionPredict = list(
    modelName = "fireSense_IgnitionFitted",
    data = "dataFireSense_IgnitionPredict",
    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).
    rescalFactor = 10
  )
)

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

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

sim <- spades(sim)
sim$fireSense_IgnitionPredicted
```

# Events
Events are scheduled as follows:

- Module initialisation
- Make predictions

# Data dependencies
## Input data
- **fireSense_IgnitionFitted**: an object of class `fireSense_IgnitionFit` created with the fireSense_IgnitionFit module.
- **dataFireSense_IgnitionPredict**: one or more data.frames, RasterLayers, RasterStacks or RasterBricks in which to look for variables with which to predict.

## Output data
- **fireSense_IgnitionPredicted**: an object whose class depends on those in input:

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

# Links to other modules
Predictions made with this module can be used to feed the ignition component of a landscape fire model (e.g fireSense).