# Package overview

#### Miquel De Caceres

#### 2020-05-17

## Introduction

Being able to anticipate the impact of global change on forest ecosystems is one of the major environmental challenges in contemporary societies. However, uncertainties in how forests function and practical constraints in how to integrate available information prevent the development of robust and reliable predictive models. Despite the amount of knowledge accumulated about the functioning and dynamics of Mediterranean forests, scientists should make coordinate their efforts to address the challenge of integrating the different global change drivers in a modelling framework useful for research and applications.

The R package `medfate` has been designed to study the characteristics and simulate functioning and dynamics of Mediterranean forests. Fire and drought impacts are the main environmental drivers covered by the package. Representation of vegetation is not spatially-explicit (i.e. trees or shrubs do not have explicit coordinates within forest stands). This simplified representation is chosen so that package functions can be easily applied to forest plot data from national forest inventories. Since the package intends to facilitate predictions of not only forest functioning but also forest structure and composition, the taxonomic identity of plants is stored, and parameter values need to be provided for each taxonomic entity (but the package could be used with functional groups).

Package vignettes only cover how to run models using the package functions. Complete documentation on the design and formulation of medfate models can be found in the medfate reference book at https://vegmod.ctfc.cat/software/medfate.

## Data structures

### Forest objects

Models included in `medfate` were primarily designed to be ran on forest inventory plots. In this kind of data, the vegetation of a sampled area is primarily described in terms of woody plants (trees and shrubs) along with their size and species identity. Forest plots in `medfate` are assumed to be in a format that follows closely the Spanish national forest inventory. Each forest plot is represented in an object of class `forest`, a list that contains several elements. Among them, the most important items are two data frames, `treeData` (for trees) and `shrubData` for shrubs:

    data(exampleforestMED)
    exampleforestMED

    ## $ID
    ## [1] "1"
    ##
    ## $patchsize
    ## [1] 10000
    ##
    ## $treeData
    ##   Species   N   DBH Height Z50  Z95
    ## 1      54 168 37.55    800 750 3000
    ## 2      68 384 14.60    660 750 3000
    ##
    ## $shrubData
    ##   Species Cover Height Z50  Z95
    ## 1      65  3.75     30 300 1500
    ##
    ## $herbCover
    ## [1] 10
    ##
    ## $herbHeight
    ## [1] 20
    ##
    ## attr(,"class")
    ## [1] "forest" "list"

Trees are expected to be primarily described in terms of species, diameter (DBH) and height, whereas shrubs are described in terms of species, percent cover and mean height. Functions are provided to map variables in user data frames into tables `treeData` and `shrubData` (see function `forest_mapWoodyTables()`).

### Soil objects

Simulation models in `medfate` require information on the physical attributes of soil, namely soil depth, texture, bulk density and rock fragment content. Soil physical attributes can be initialized to default values, for a given number of layers, using function `defaultSoilParams()`:

    spar = defaultSoilParams(2)
    print(spar)

    ##   widths clay sand om  bd rfc
    ## 1    300   25   25 NA 1.5  20
    ## 2    700   25   25 NA 1.5  40

where `widths` are soil layer widths in mm; `clay` and `sand` are the percentage of clay and sand, in percent of dry weight, `om` stands for organic matter, `bd` is bulk density (in \(g \cdot cm^{-3}\)) and `rfc` the percentage of rock fragments. Because soil properties vary strongly at fine spatial scales, ideally soil physical attributes should be measured on samples taken at the forest stand to be simulated. For those users lacking such data, soil properties modelled at larger scales are available via soilgrids.org (see function `soilgridsParams()`).

The soil input for simulations is an object of class `soil` (a list) that is created using a function with the same name:

    examplesoil = soil(spar)
    names(examplesoil)

    ##  [1] "SoilDepth"    "W"            "SWE"          "Temp"         "Ksoil"
    ##  [6] "Gsoil"        "dVec"         "sand"         "clay"         "om"
    ## [11] "usda_Type"    "VG_alpha"     "VG_n"         "VG_theta_res" "VG_theta_sat"
    ## [16] "macro"        "rfc"

In addition to the physical soil description, this object contains soil parameters needed for soil water balance simulations.

## Dynamic simulation functions

### Water balance and plant drought stress

Eco-hydrological processes are fundamental for the simulation models included in the `medfate` package. In particular, the package allows the simulation of water balance of soils and plants within forest stands. Processes affecting soil water content include rainfall, canopy interception, infiltration and runoff, percolation and deep drainage, soil evaporation and plant transpiration. In `medfate`, the soil water balance of a forest is primarily used to predict drought stress for living plants in it. Soil water balance can be studied for a single forest stand using function `spwb()`. Function `spwb()` may be used to:

1. Monitor or forecast temporal variation in soil water content in particular stands (for example to estimate mushroom yield).
2. Monitor or forecast temporal variation of plant drought stress in particular stands (for example to anticipate mortality events).
3. Monitor or forecast temporal variation of fuel moisture in particular stands (for example to monitor wildfire risk).

### Forest growth

Changes in leaf area and plant growth are key to evaluate the influence of climatic conditions on forest structure and function. Processes affecting annual changes leaf area and plant size are those involved water and carbon balances, as well as those affecting growth directly. Processes influencing plant water balance include those affecting soil water content, such as rainfall, canopy interception, infiltration and runoff, percolation and deep drainage, soil evaporation and plant transpiration. Carbon balance arises from the relationship between plant photosynthesis and respiration, although carbon reserves play a role in the availabity of carbon for growth. Water and carbon balances are coupled through the regulation of transpiration done by stomata. Plant growth is affected by the availability of carbon (source limitation), but also by temperature and water status (sink limitation).

Package `medfate` allows simulating plant growth of a set of cohorts (competing for light and water) in a single forest stand using function `growth()`. Leaf area of plants can be severely decreased by drought stress, causing an increase in dead leaf area and affecting carbon and water fluxes. Function `growth()` may be used to:

1. Monitor or forecast temporal variation in water fluxes and soil water content in particular stands (for example to estimate regulation ecosystem services) taking into account processes determining plant growth.
2. Monitor or forecast temporal variation of plant drought stress in particular stands(for example to anticipate mortality events) taking into account processes determining plant growth.
3. Monitor or forecast temporal variation of live fuel moisture and the amount of standing dead and live fuels in particular stands (for example to monitor wildfire risk).

### Sub-model functions

Many of the functions included in `medfate` are internally called by simulation functions. Some of them are made available to the user, to facilitate understanding the different sub-models and to facilitate a more creative use of the package. Sub-model functions are grouped by subject, which is included in the name of the function. The different sub-model functions are (by subject):

- `biophysics_*`: Physical and biophysical utility functions.
- `hydraulics_*`: Plant hydraulics.
- `hydrology_*`: Canopy and soil hydrology (rainfall interception, soil evaporation, soil infiltration).
- `light_*`: Light extinction and absortion.
- `moisture_*`: Live tissue moisture.
- `pheno_*`: Leaf phenology.
- `photo_*`: Leaf photosynthesis.
- `root_*`: Root distribution and conductance calculations.
- `soil_*`: Soil hydraulics and thermodynamics.
- `spwb_*`: Soil water balance parameter optimization/calibration routines.
- `transp_*`: Stomatal regulation and resulting transpiration/photosynthesis.

## Static functions

### Plant, species and stand attributes

Package `medfate` include a number of functions to examine properties of the plants conforming the `forest` object, summary functions at the stand level or vertical profiles of several physical properties:

- `plant_*`: Cohort-level information (species name, id, leaf area, height…).
- `species_*`: Cohort-level attributes aggregated by species (e.g. basal area).
- `stand_*`: Stand-level attributes (e.g. basal area).
- `vprofile_*`: Vertical profiles (light, wind, fuel density, leaf area density).

### Fuel properties and fire hazard

Vegetation functioning and dynamics have strong, but complex, effects on fire hazard. On one hand, growth and death of organs and individuals changes the amount of standing live and dead fuels, as well as downed dead fuels. On the other, day-to-day changes in soil and plant water content changes the physical properties of fuel, notably fuel moisture content. Package `medfate` provides functions to estimate fuel properties and potential fire behaviour in forest inventory plots. Specifically, function `fuel_stratification()` provides a stratification of the stand into understory and canopy strata; and `fuel_FCCS()` calculates fuel characteristics from a `forest` object following an adaptation of the protocols described for the Fuel Characteristics Classification System (Prichard et al. 2013). Function `fuel_cohortFineFMC()` allows obtaining daily fuel moisture content estimates corresponding to the water status of plants, as returned by function `spwb()`.

In FCCS, fuelbed is divided into six strata, including canopy, shrub, herbaceous vegetation, dead woody materials, leaf litter and ground fuels. All except ground fuels are considered here. The intensity of burning depends on several factors, including topography, wind conditions, fuel structure and its moisture content, which is determined from antecedent and current meteorological conditions. A modification of the Rothermel’s (1972) model is used in function `fire_FCCS()` to calculate the intensity of surface fire reaction and the rate of fire spread of surface fires assuming a steady-state fire. Both quantities are dependent on fuel characteristics, windspeed and direction, and topographic slope and aspect. Fuel and fire behaviour functions allow obtaining the following:

1. Fuel characteristics by stratum.
2. Surface fire behavior (i.e. reaction intensity, rate of spread, fireline intensity and flame length).
3. Crown fire behavior.
4. Fire potential ratings of surface fire behavior and crown fire behavior.