This script is designed to create parameter files containing response to drought disturbance parameters for each PFG (one file for each of them) used in the drought disturbance module of FATE.

PRE_FATE.params_PFGdrought(
  name.simulation,
  mat.PFG.dist = NULL,
  mat.PFG.tol,
  mat.PFG.drought,
  opt.folder.name = NULL
)

Arguments

name.simulation

a string corresponding to the main directory or simulation name of the FATE simulation

mat.PFG.dist

(optional)
a data.frame with 5 columns :
PFG, type, maturity, longevity, age_above_150cm (see Details)

mat.PFG.tol

a data.frame with 3 to 7 columns :

  • nameDist,

  • PFG,

  • (responseStage, breakAge, resproutAge),

  • responseStage, killedIndiv, resproutIndiv (or strategy_tol)

(see Details)

mat.PFG.drought

a data.frame with 4 or 6 columns :

  • PFG,

  • threshold_moderate, threshold_severe,

  • counter_recovery, counter_sens, counter_cum (or strategy_drou)

opt.folder.name

(optional)
a string corresponding to the name of the folder that will be created into the name.simulation/DATA/PFGS/DROUGHT/ directory to store the results

Value

A .txt file per PFG into the name.simulation/DATA/PFGS/DROUGHT/ directory with the following parameters :

BREAK_AGE

ages at which the PFG changes of response stage (in years)

RESPR_AGE

resprouting age table (in a single row)
This is a vector of no.DIST (=2) * no.responseStages numbers corresponding
to the age at which the PFG can be rejuvenated (younger than the actual one) :

  • at different response stages (RS)

  • for each disturbance (DI).

These parameters should be given in this order (e.g. with 3 response stages) :
DI1_RS1, DI1_RS2, DI1_RS3, DI2_RS1... (in years).

FATES

disturbance response table (in a single row)
This is a vector of no.DIST (=2) * no.responseStages * 2 numbers corresponding
to the proportion of individuals :

  • that will be killed (Ki) or resprout (Re)

  • at different response stages (RS)

  • for each disturbance (DI).

These parameters should be given in this order (e.g. with 3 response stages) :
DI1_RS1_Ki, DI1_RS1_Re, DI1_RS2_Ki, DI1_RS2_Re, DI1_RS3_Ki, DI1_RS3_Re, DI2_RS1_Ki...
(from 0 to 10, corresponding to 0 to 100%).

PROP_KILLED

proportion of propagules killed by each disturbance
(from 0 to 10, corresponding to 0 to 100%)

ACTIVATED_SEED

proportion of seeds activated by each disturbance
(from 0 to 10, corresponding to 0 to 100%)

THRESHOLD_MOD

threshold below which the PFG will experience moderate drought
(same unit as that of the map given with the DROUGHT_MASK flag in PRE_FATE.params_globalParameters)

THRESHOLD_SEV

threshold below which the PFG will experience severe drought
(same unit as that of the map given with the DROUGHT_MASK flag in PRE_FATE.params_globalParameters)

COUNTER_RECOVERY

number of years removed from the PFG counter of cumulated consecutive years of drought events, during non-drought years

COUNTER_SENS

number of consecutive years of drought the PFG must experience before suffering severe effects due to a severe drought
(sensitivity to severe drought)

COUNTER_CUM

number of consecutive years of drought the PFG must experience before any subsequent drought event start having severe effects
(cumulative drought response)

A DROUGHT_COMPLETE_TABLE.csv file summarizing information for all groups into the name.simulation/DATA/PFGS/ directory.

If the opt.folder.name has been used, the files will be into the folder name.simulation/DATA/PFGS/DROUGHT/opt.folder.name/.

Details

The drought disturbance module is a specific case of the disturbance module. It also allows the user to simulate spatial perturbation(s) that will impact each PFG in terms of resprouting and mortality at different response stages, but with specific rules to determine when the PFG is affected (see PRE_FATE.params_globalParameters).

Several parameters, given within mat.PFG.dist or mat.PFG.tol, are required for each PFG in order to set up these responses. The explanations are the same than those that can be found in PRE_FATE.params_PFGdisturbance function. Therefore, only parameters whose values or descriptions change are detailed below :

nameDist

a string to choose the concerned drought disturbance :
immediate or delayed

(strategy_tol)

a string to choose the response to drought strategy :
herbs_cham_1, herbs_cham_2, herbs_cham_3, trees_1, trees_2, trees_3

These values will allow to calculate or define a set of characteristics for each PFG :

FATES

= proportion of killed and resprouting individuals
= for each disturbance and for each response stage

Two methods to define these tolerances are available :

  • from predefined scenarios (using strategy_tol) :

    • the values give the percentage of killed or resprouting individuals

    • with 1, 2, 3, 4: response classes

    • with K: killed individuals, R: resprouting individuals

    | ___1___ | ___2___ | ___3___ | ___4___ |
    | _K_ _R_ | _K_ _R_ | _K_ _R_ | _K_ _R_ |
    ________________IMMEDIATE________________
    | 10% _0_ | _0_ _0_ | _0_ _0_ | _0_ _0_ | herbs_cham_1
    | 20% _0_ | _0_ _0_ | _0_ _0_ | 10% _0_ | herbs_cham_2
    | 40% _0_ | 10% _0_ | 10% _0_ | 20% _0_ | herbs_cham_3
    | 10% _0_ | _0_ _0_ | _0_ 40% | _0_ 40% | trees_1
    | 20% _0_ | _0_ 10% | _0_ 50% | 10% 50% | trees_2
    | 40% _0_ | 10% 40% | 10% 80% | 20% 80% | trees_3
    _________________DELAYED_________________
    | _0_ _0_ | _0_ 10% | _0_ 10% | _0_ 10% | herbs_cham_1
    | _0_ _0_ | _0_ 10% | _0_ 10% | _0_ 10% | herbs_cham_2
    | _0_ _0_ | _0_ 10% | _0_ 10% | _0_ 10% | herbs_cham_3
    | _0_ _0_ | _0_ 10% | _0_ 40% | _0_ 40% | trees_1
    | 10% _0_ | _0_ 40% | _0_ 40% | _0_ 40% | trees_2
    | 20% _0_ | 10% 40% | 10% 50% | 10% 50% | trees_3

  • from user data :
    with the values contained within the responseStage, killedIndiv and resproutIndiv columns, if provided
    The PFG column can contain either the life form (H, C or P) or the PFG name. Both methods can be combined (but are applied in the order given by the PFG column).

Supplementary parameters related to drought, given within mat.PFG.drought, are required for each PFG :

threshold_moderate

a value corresponding to the threshold below which the PFG will experience moderate drought (on the same scale than threshold_severe and the map given with the DROUGHT_MASK flag in PRE_FATE.params_globalParameters)

threshold_severe

a value corresponding to the threshold below which the PFG will experience severe drought (on the same scale than threshold_moderate and the map given with the DROUGHT_MASK flag in PRE_FATE.params_globalParameters). It should be inferior or equal to threshold_moderate.

counter_recovery

an integer corresponding to the number of years removed from the PFG counter of cumulated consecutive years of drought events, during non-drought years

counter_sens

an integer corresponding to the number of consecutive years of drought the PFG must experience before suffering severe effects due to a severe drought (sensitivity to severe drought)

counter_cum

an integer corresponding to the number of consecutive years of drought the PFG must experience before any subsequent drought event start having severe effects (cumulative drought response). It should be superior or equal to counter_sens.

(strategy_drou)

a string to choose the "counter" strategy :
herbs, chamaephytes, trees_shrubs

These values will allow to define a set of characteristics for each PFG :

sensitivity to values

with the THRESHOLD_MODERATE and THRESHOLD_SEVERE parameters

sensitivity through time

with the COUNTER_RECOVERY, COUNTER_SENS and COUNTER_CUM parameters

Author

Maya Guéguen

Examples


## Create a skeleton folder with the default name ('FATE_simulation')
PRE_FATE.skeletonDirectory()


mat.char = data.frame(PFG = paste0('PFG', 1:6)
                      , type = c('C', 'C', 'H', 'H', 'P', 'P')
                      , maturity = c(5, 5, 3, 3, 8, 9)
                      , longevity = c(12, 200, 25, 4, 110, 70)
                      , age_above_150cm = c(1000, 100, 1000, 1000, 10, 12))

mat.tol = data.frame(nameDist = 'immediate'
                     , PFG = paste0('PFG', 1:6)
                     , strategy_tol = c('herbs_cham_1', 'herbs_cham_2'
                                        , 'herbs_cham_2', 'herbs_cham_3'
                                        , 'trees_1', 'trees_3'))

mat.drought = data.frame(PFG = paste0('PFG', 1:6)
                         , threshold_moderate = c(0.5, 0.2, 1, 1, 0.8, 0.5)
                         , threshold_severe = c(0.1, 0.1, 0.8, 0.9, 0.4, 0.2)
                         , strategy_drou = c('chamaephytes', 'trees_shrubs', 'herbs'
                                             , 'herbs', 'trees_shrubs', 'trees_shrubs'))

## Create PFG response to drought parameter files (with PFG characteristics) -----------------
PRE_FATE.params_PFGdrought(name.simulation = 'FATE_simulation'
                           , mat.PFG.dist = mat.char
                           , mat.PFG.tol = mat.tol
                           , mat.PFG.drought = mat.drought)


## Create PFG response to drought parameter files (with all values) --------------------------
mat.tol = expand.grid(responseStage = 1:3
                      , PFG = paste0('PFG', 1:6)
                      , nameDist = 'delayed')
mat.tol$breakAge = c(1, 4, 10
                     , 1, 4, 10
                     , 1, 2, 50
                     , 1, 2, 20
                     , 2, 6, 95
                     , 3, 8, 55)
mat.tol$resproutAge = c(0, 0, 4
                        , 0, 0, 4
                        , 0, 0, 2
                        , 0, 0, 2
                        , 0, 2, 5
                        , 0, 4, 7)
mat.tol$killedIndiv = c(10, 10, 5
                        , 10, 10, 5
                        , 10, 10, 5
                        , 10, 10, 5
                        , 10, 7, 4
                        , 10, 6, 3)
mat.tol$resproutIndiv = c(0, 0, 5
                          , 0, 0, 5
                          , 0, 0, 3
                          , 0, 0, 3
                          , 0, 1, 4
                          , 0, 2, 5)
str(mat.tol)

PRE_FATE.params_PFGdrought(name.simulation = 'FATE_simulation'
                           , mat.PFG.tol = mat.tol
                           , mat.PFG.drought = mat.drought)