PRE_FATE.params_globalParameters: Create _Global_parameters_ parameter file for a 'FATE'...

Description Usage Arguments Details Value Author(s) See Also Examples

View source: R/PRE_FATE.params_globalParameters.R

Description

This script is designed to create parameter file(s) containing GLOBAL PARAMETERS used in FATE model.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
PRE_FATE.params_globalParameters(
  name.simulation,
  opt.no_CPU = 1,
  opt.replacePrevious = FALSE,
  required.no_PFG,
  required.no_strata,
  required.simul_duration = 1000,
  required.seeding_duration = 300,
  required.seeding_timestep = 1,
  required.seeding_input = 100,
  required.max_abund_low,
  required.max_abund_medium,
  required.max_abund_high,
  doLight = FALSE,
  LIGHT.thresh_medium,
  LIGHT.thresh_low,
  doSoil = FALSE,
  SOIL.init,
  SOIL.retention,
  doDispersal = FALSE,
  DISPERSAL.mode = 1,
  doHabSuitability = FALSE,
  HABSUIT.mode = 1,
  doDisturbances = FALSE,
  DIST.no,
  DIST.no_sub = 4,
  DIST.freq = 1,
  doDrought = FALSE,
  DROUGHT.no_sub = 4,
  doAliens = FALSE,
  ALIEN.no,
  ALIEN.freq = 1,
  doFire = FALSE,
  FIRE.no,
  FIRE.no_sub = 4,
  FIRE.freq = 1,
  FIRE.ignit_mode = 1,
  FIRE.ignit_no,
  FIRE.ignit_noHist,
  FIRE.ignit_logis = c(0.6, 2.5, 0.05),
  FIRE.ignit_flammMax,
  FIRE.neigh_mode = 1,
  FIRE.neigh_CC = c(2, 2, 2, 2),
  FIRE.prop_mode = 1,
  FIRE.prop_intensity,
  FIRE.prop_logis = c(0.6, 2.5, 0.05),
  FIRE.quota_mode = 4,
  FIRE.quota_max
)

Arguments

name.simulation

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

opt.no_CPU

(optional) default 1.
an integer corresponding to the number of resources that can be used to parallelize the FATE simulation

opt.replacePrevious

(optional) default FALSE.
If TRUE, pre-existing files inside name.simulation/DATA/GLOBAL_PARAMETERS folder will be replaced

required.no_PFG

an integer corresponding to the number of PFG

required.no_strata

an integer corresponding to the number of height strata

required.simul_duration

an integer corresponding to the duration of simulation (in years)

required.seeding_duration

an integer corresponding to the duration of seeding (in years)

required.seeding_timestep

an integer corresponding to the time interval at which occurs the seeding, and until the seeding duration is not over (in years)

required.seeding_input

an integer corresponding to the number of seeds attributed to each PFG at each time step, and until the seeding duration is not over

required.max_abund_low

an integer in the order of 1 000 to rescale abundance values of small PFG

required.max_abund_medium

an integer in the order of 1 000 to rescale abundance values of intermediate PFG

required.max_abund_high

an integer in the order of 1 000 to rescale abundance values of tall PFG

doLight

default FALSE.
If TRUE, light competition is activated in the FATE simulation, and associated parameters are required

LIGHT.thresh_medium

(optional)
an integer in the order of 1 000 to convert PFG abundances in each stratum into light resources. It corresponds to the limit of abundances above which light resources are medium. PFG abundances lower than this threshold imply high amount of light. It is consequently lower than LIGHT.thresh_low.

LIGHT.thresh_low

(optional)
an integer in the order of 1 000 to convert PFG abundances in each strata into light resources. It corresponds to the limit of abundances above which light resources are low. PFG abundances higher than LIGHT.thresh_medium and lower than this threshold imply medium amount of light.

doSoil

default FALSE.
If TRUE, soil competition is activated in the FATE simulation, and associated parameters are required

SOIL.init

(optional)
a double corresponding to the soil value to initialize all pixels when starting the FATE simulation

SOIL.retention

(optional)
a double corresponding to the percentage of soil value of the previous simulation year that will be kept in the calculation of the soil value of the current simulation year

doDispersal

default FALSE.
If TRUE, seed dispersal is activated in the FATE simulation, and associated parameters are required

DISPERSAL.mode

(optional)
an integer corresponding to the way of simulating the seed dispersal for each PFG, either packets kernel (1), exponential kernel (2) or exponential kernel with probability (3)

doHabSuitability

default FALSE.
If TRUE, habitat suitability is activated in the FATE simulation, and associated parameters are required

HABSUIT.mode

(optional)
an integer corresponding to the way of simulating the habitat suitability variation between years for each PFG, either random (1) or PFG specific (2)

doDisturbances

default FALSE.
If TRUE, disturbances are applied in the FATE simulation, and associated parameters are required

DIST.no

(optional)
an integer corresponding to the number of disturbances

DIST.no_sub

(optional)
an integer corresponding to the number of way a PFG could react to a disturbance

DIST.freq

(optional)
a vector of integer corresponding to the frequency of each disturbance (in years)

doDrought

default FALSE.
If TRUE, drought disturbances are applied in the FATE simulation, and associated parameters are required

DROUGHT.no_sub

(optional)
an integer corresponding to the number of way a PFG could react to a drought disturbance

doAliens

default FALSE.
If TRUE, invasive plant introduction is activated in the FATE simulation, and associated parameters are required

ALIEN.no

(optional)
an integer corresponding to the number of introductions

ALIEN.freq

(optional)
a vector of integer corresponding to the frequency of each introduction (in years)

doFire

default FALSE.
If TRUE, fire disturbances are applied in the FATE simulation, and associated parameters are required

FIRE.no

(optional)
an integer corresponding to the number of fire disturbances

FIRE.no_sub

(optional)
an integer corresponding to the number of way a PFG could react to a fire disturbance

FIRE.freq

(optional)
a vector of integer corresponding to the frequency of each fire disturbance (in years)

FIRE.ignit_mode

(optional)
an integer corresponding to the way of simulating the fire(s) ignition each year, either random (1, 2 or 3), according to cell conditions (4) or through a map (5)

FIRE.ignit_no

(optional) (required if FIRE.ignit_mode = 1 or 2)
an integer corresponding to the number of fires starting each year

FIRE.ignit_noHist

(optional) (required if FIRE.ignit_mode = 3)
a vector of integer corresponding to historical number of fires

FIRE.ignit_logis

(optional) (required if FIRE.ignit_mode = 4)
a vector of 3 values to parameterize the logistic probability function :

  1. asymptote of the function curve

  2. time where the slope starts to increase

  3. speed of slope increase

FIRE.ignit_flammMax

(optional) (required if FIRE.ignit_mode = 4)
an integer corresponding to the maximum flammmability of PFG

FIRE.neigh_mode

(optional)
an integer corresponding to the way of finding neighboring cells each year, either 8 adjacent (1) or with cookie cutter (2 or 3)

FIRE.neigh_CC

(optional) (required if FIRE.neigh_mode = 2 or 3)
a vector of 4 values corresponding to the extent of cookie cutter :

  1. number of cells towards north

  2. number of cells towards east

  3. number of cells towards south

  4. number of cells towards west

FIRE.prop_mode

(optional)
an integer corresponding to the way of simulating the fire(s) propagation each year, either fire intensity (1), % of plants consumed (2), maximum amount of resources (3 or 4), or according to cell conditions (5)

FIRE.prop_intensity

(optional) (required if FIRE.prop_mode = 1)
a vector of double corresponding to the intensity or probability of dispersal of each fire disturbance (between 0 and 1)

FIRE.prop_logis

(optional) (required if FIRE.prop_mode = 5)
a vector of 3 values to parameterize the logistic probability function :

  1. asymptote of the function curve

  2. time where the slope starts to increase

  3. speed of slope increase

FIRE.quota_mode

(optional)
an integer corresponding to the way of ending the fire(s) spread each year, either maximum steps (1), maximum amount of resources (2), maximum cells (3), or keep going (4)

FIRE.quota_max

(optional) (required if FIRE.quota_mode = 1, 2 or 3)
an integer corresponding to the maximum quantity limit (either steps, resources, cells)

Details

The core module of FATE requires several parameters to define general characteristics of the simulation :

Studied system


no_PFG

the number of plant functional groups that will be included into the simulation.
This number should match with the number of files that will be given to parameterize the different activated modules with the characteristics of each group (‘SUCC’, ‘DISP’, ...).

no_STRATA

the number of height strata that will be used into the succession module.
This number should match with the maximum number of strata possible defined into the PFG ‘SUCC’ files.

Simulation timing


simul_duration

the duration of simulation (in years)

seeding_duration

the duration of seeding (in years)

seeding_timestep

the time interval at which occurs the seeding, and until the seeding duration is not over (in years)

seeding_input

the number of seeds dispersed for each PFG at each time step, and until the seeding duration is not over

The other modules of FATE can be activated within this file, and if so, some additional parameters will be required :

LIGHT

= to influence seed recruitment and plant mortality according to PFG preferences for light conditions
(see PRE_FATE.params_PFGlight)
= light resources are calculated as a proxy of PFG abundances within each height stratum

To transform PFG abundances into light resources :

abund_{\text{ PFG}_{all}\text{, }\text{Stratum}_k} < \text{LIGHT.thresh_medium} \;\; \Leftrightarrow \;\; light_{\text{ Stratum}_k} = \text{High}

\text{LIGHT.thresh_medium } < abund_{\text{ PFG}_{all}\text{, }\text{Stratum}_k} < \text{LIGHT.thresh_low} \\ \Leftrightarrow \;\; light_{\text{ Stratum}_k} = \text{Medium}

abund_{\text{ PFG}_{all}\text{, }\text{Stratum}_k} > \text{LIGHT.thresh_low} \;\; \Leftrightarrow \;\; light_{\text{ Stratum}_k} = \text{Low}

As light resources are directly obtained from PFG abundances, LIGHT.thresh_medium and LIGHT.thresh_low parameters should be on the same scale than required.max_abund_low, required.max_abund_medium and required.max_abund_high parameters from the core module.

SOIL

= to influence seed recruitment and plant mortality according to PFG preferences for soil conditions
(see PRE_FATE.params_PFGsoil)
= soil composition is calculated as the weighted mean of each PFG's contribution with a possible retention of the soil value of the previous simulation year

Soil_y + \text{SOIL.retention} * (Soil_{y-1} - Soil_y)

with

Soil_y = ∑ abund_{\text{ PFG}_i\text{, }y} * \text{contrib}_{\text{ PFG}_i}



DISPERSAL

= to allow plants to disperse seeds according to 3 user-defined distances
(see PRE_FATE.params_PFGdispersal)

Three modes of dispersal (DISPERSAL.mode) are available :

  1. packets kernel :

    • homogeneous dispersal of 50% of the seeds within the d50 circle

    • dispersal of 49% of the seeds within the d99 - d50 ring with the same concentration as in the first circle but by pairs of pixel (see Boulangeat et al, 2014)

    • dispersal of 1% of the seeds within the ldd - d99 ring into one random pixel

  2. exponential kernel : seeds are dispersed within each concentric circle (d50, d99 and ldd) according to a decreasing exponential density law (lambda = 1)

  3. exponential kernel with probability : seeds are dispersed within each concentric circle (d50, d99 and ldd) according to a decreasing exponential density law (lambda = 1) and a continuous decreasing probability with distance

HABITAT SUITABILITY

= to influence plants fecundity and seed recruitment according to PFG preferences for habitat conditions
= filter based on maps given for each PFG within the Simul_parameters file with the PFG_HAB_MASK flag
(see PRE_FATE.params_simulParameters)

These maps must contain values between 0 and 1 corresponding to the probability of presence of the PFG in each pixel. Each year (timestep), this value will be compared to a reference value, and if superior, the PFG will be able to grow and survive.
Two methods to define this habitat suitability reference value are available (HABSUIT.mode) :

  1. random : for each pixel, the reference value is drawn from a uniform distribution, and the same value is used for each PFG within this pixel.

  2. PFG specific : for each PFG, a mean value and a standard deviation value are drawn from a uniform distribution. For each pixel and for each PFG, the reference value is drawn from a normal distribution of parameters the mean and standard deviation of the PFG.

DISTURBANCES

= to influence plant mortality and / or resprouting according to PFG tolerances to these events
(see PRE_FATE.params_PFGdisturbance)
= defined for events such as mowing, grazing, but also urbanization, crops, etc
= filter based on maps given for each disturbance within the Simul_parameters file with the DIST_MASK flag
(see PRE_FATE.params_simulParameters)

These maps, containing either 0 or 1, define the impact zone of each perturbation, and the user will have to define how each PFG will be impacted depending on age and life stage.

DIST.no

the number of different disturbances

DIST.no_sub

the number of way a PFG could react to a perturbation

DIST.freq

the frequency of each disturbance (in years)

DROUGHT

= to experience extreme events with a direct and a delayed response on PFG
= based on a map given within the Simul_parameters file with the DROUGHT_MASK flag
(see PRE_FATE.params_simulParameters)

This map must contain values representing proxies for drought intensity, like moisture values, in the sense that the lower the values, the higher the chance of experiencing a drought event. Developed canopy closure helps to reduce these values. The intensity of the drought event (moderate or severe) is determined based on thresholds defined for each PFG according to, for example, their moisture preference, as well as the number of cumulated consecutive years during which the PFG experienced a drought (see PRE_FATE.params_PFGdrought).

no drought

if di_y > \text{threshold.MOD}_{\text{ PFG}_i}, the counter of cumulated consecutive years of drought experienced by the PFG will decrease :

\text{counter}_{\text{ PFG}_i} = \text{counter}_{\text{ PFG}_i} - \text{counter.RECOVERY}_{\text{ PFG}_i}

moderate drought
  • if \text{threshold.SEV}_{\text{ PFG}_i} < di_y < \text{threshold.MOD}_{\text{ PFG}_i}

  • if di_y < \text{threshold.SEV}_{\text{ PFG}_i} \;\; \text{ & } \;\; \text{counter}_{\text{ PFG}_i} = 0

then fecundity and recruitment are set to 0 for this year, and counter is incremented : \text{counter}_{\text{ PFG}_i} ++

severe drought
  • if di_y < \text{threshold.SEV}_{\text{ PFG}_i} \;\; \text{ & } \;\; \text{counter.SENS}_{\text{ PFG}_i} ≤q \text{counter}_{\text{ PFG}_i} < \text{counter.CUM}_{\text{ PFG}_i}

  • if \text{counter}_{\text{ PFG}_i} ≥q \text{counter.CUM}_{\text{ PFG}_i}

then PFG experiences immediate drought-related mortality ; and the year after, fecundity and recruitment will be set to 0 and PFG will experience delayed drought-related mortality.

As for the disturbances module, the user will have to define how each PFG will be impacted depending on age and life stage.

(DROUGHT.no)

!not required!
= 2, the immediate and delayed responses

DROUGHT.no_sub

the number of way a PFG could react to each of these two perturbations

(DROUGHT.freq)

!not required!
the map of drought intensity proxy defined within the Simul_parameters file with the DROUGHT_MASK flag, as well as the DROUGHT_CHANGEMASK_YEARS and DROUGHT_CHANGEMASK_FILES flags, make it possible to manage the frequency and the variation of drought values (see PRE_FATE.params_simulParameters)

INVASIVE
INTRODUCTION

= to add new PFG during the simulation
= defined for events such as invasive introduction, colonization, but also new crops development, reintroduction, etc
= filter based on maps given for each PFG within the Simul_parameters file with the PFG_MASK_ALIENS flag
(see PRE_FATE.params_simulParameters)

These maps, containing either 0 or 1, define the introduction areas.
If the habitat suitability filter is on, suitability maps will also be needed for these new groups.

ALIEN.no

the number of different introductions

ALIEN.freq

the frequency of each introduction (in years)

FIRE

= to influence plant mortality and / or resprouting according to PFG tolerances to these events (see PRE_FATE.params_PFGdisturbance)

Fire extreme events are broken down into 4 steps representing their life cycle, so to speak. Each of these steps can be parameterized according to different available options :

Ignition

Five methods to define the cells that are going to burn first, and from which the fire will potentially spread, are available (FIRE.ignit_mode) :

  1. Random (fixed) : FIRE.ignit_no positions are drawn randomly over the area

  2. Random (normal distribution) : ignit_no positions are drawn randomly over the area, with

    \text{ignit_no} \sim N(\text{FIRE.ignit_no}, 1 + \frac{\text{FIRE.ignit_no}}{10})

  3. Random (historic distribution) : ignit_no positions are drawn randomly over the area, with

    \text{ignit_no} \sim \text{FIRE.ignit_noHist} [\;\; U(1, length(\text{FIRE.ignit_noHist})) \;\;]

  4. Probability (Li et al. 1997 Ecology Modelling) : each cell can be a fire start with a probability (probLi) taking into account a baseline probability (BL), the PFG composition and abundances (fuel), and a drought index (DI, only if values between 0 and 1, given within the Simul_parameters file with the DROUGHT_MASK flag (see PRE_FATE.params_simulParameters)) :

    probLi_y = \text{BL}_y * \text{fuel}_y * (-DI)

    with

    \text{BL}_y = \frac{\text{FIRE.ignit_logis}[1]}{1 + e^{\text{FIRE.ignit_logis}[2] - \text{FIRE.ignit_logis}[3] * TSLF_y}}

    \text{fuel}_y = ∑ \frac{\text{FLAMM}_{\text{ PFG}_i}} {\text{FIRE.ignit_flammMax}} * \frac{abund_{\text{ PFG}_i\text{, }y}} {abund_{\text{ PFG}_{all}\text{, }y}}

  5. Map !no neighbours, propagation, quota steps!
    Each cell specified by the map given within the Simul_parameters file with the FIRE_MASK flag and containing either 0 or 1 to define the starting positions (see PRE_FATE.params_simulParameters)

Neighbours / dispersal range

Three methods to define the neighboring cells of the cell currently burning, and to which the fire will potentially spread, are available (FIRE.neigh_mode) :

  1. 8 neighbours : all the 8 adjacent cells can potentially be impacted by fire, and propagation will determine which ones are effectively affected.

  2. Extent (fixed) !no propagation step!
    All cells contained within the rectangle defined by the cookie cutter extent (FIRE.neigh_CC) are impacted by fire

  3. Extent (random) !no propagation step!
    All cells contained within the rectangle defined by the cookie cutter extent (neigh_CC) are impacted by fire, with

    neigh\_CC_y \in ∑ U(1, \text{FIRE.neigh_CC}_i)

Propagation

Five methods to define which cells among the neighboring cells will actually burn are available (FIRE.prop_mode) :

  1. Probability (fire intensity) : a probability is assigned to the cell currently burning corresponding to the concerned fire intensity (FIRE.prop_intensity) and compared to a number drawn randomly for each neighbor cell

  2. Probability (% of plants consumed) : a probability is assigned to the cell currently burning linked to the percentage of PFG killed by the concerned fire (prob) and compared to a number drawn randomly for each neighbor cell

    \text{prob}_y = ∑ \text{KilledIndiv}_{\text{ PFG}_i} * \frac{abund_{\text{ PFG}_i\text{, }y}} {abund_{\text{ PFG}_{all}\text{, }y}}

  3. Maximum amount (PFG) : the cell(s) with the maximum amount of plants weighted by their flammability (fuel) will burn

    \text{fuel}_y = ∑ \text{FLAMM}_{\text{ PFG}_i} * abund_{\text{ PFG}_i\text{, }y}

  4. Maximum amount (soil) : if the soil module was activated, the cell(s) with the maximum amount of soil will burn

  5. Probability (Li et al. 1997 Ecology Modelling) : a probability is assigned to the cell currently burning taking into account a baseline probability (BL), the PFG composition and abundances (fuel), the elevation and slope (given within the Simul_parameters file with the ELEVATION_MASK and SLOPE_MASK flags (see PRE_FATE.params_simulParameters)), and a drought index (DI, only if values between 0 and 1, given within the Simul_parameters file with the DROUGHT_MASK flag (see PRE_FATE.params_simulParameters)) :

    probLi_y = \text{BL}_y * \text{fuel}_y * (-DI) * probSlope

    with

    \text{BL}_y = \frac{\text{FIRE.prop_logis}[1]}{1 + e^{\text{FIRE.prop_logis}[2] - \text{FIRE.prop_logis}[3] * TSLF_y}}

    \text{fuel}_y = ∑ \frac{\text{FLAMM}_{\text{ PFG}_i}} {\text{FIRE.ignit_flammMax}} * \frac{abund_{\text{ PFG}_i\text{, }y}} {abund_{\text{ PFG}_{all}\text{, }y}}

    \text{if going up, } probSlope = 1 + 0.001 * \text{SLOPE}

    \text{if going down, } probSlope = 1 + 0.001 * max(-30.0,-\text{SLOPE})

Quota / spread end

Four methods to define when the fire will stop spreading are available (FIRE.quota_mode) :

  1. Maximum step : after a fixed number of steps (FIRE.quota_max)

  2. Maximum amount : when a fixed amount of PFG is consumed (FIRE.quota_max)

  3. Maximum cells : when a fixed amount of cells is consumed (FIRE.quota_max)

  4. Keep going : as long as it remains a fire that manages to spread

As for the disturbances module, the user will have to define how each PFG will be impacted depending on age and life stage.

FIRE.no

the number of different fire disturbances

FIRE.no_sub

the number of way a PFG could react to a perturbation

FIRE.freq

the frequency of each fire disturbance (in years)

Value

A .txt file into the name.simulation/DATA/GLOBAL_PARAMETERS directory with the following parameters :

If the simulation includes light competition :

If the simulation includes soil competition :

If the simulation includes dispersal :

If the simulation includes habitat suitability :

If the simulation includes disturbances :

If the simulation includes drought disturbance :

If the simulation includes aliens introduction :

If the simulation includes fire disturbance :

Author(s)

Maya Guéguen

See Also

PRE_FATE.skeletonDirectory, PRE_FATE.params_PFGsuccession, PRE_FATE.params_PFGlight, PRE_FATE.params_PFGsoil, PRE_FATE.params_PFGdispersal, PRE_FATE.params_PFGdisturbance, PRE_FATE.params_PFGdrought, PRE_FATE.params_simulParameters

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
## Create a skeleton folder with the default name ('FATE_simulation')
PRE_FATE.skeletonDirectory()

## Create a Global_parameters file
PRE_FATE.params_globalParameters(name.simulation = "FATE_simulation"
                                 , required.no_PFG = 3
                                 , required.no_strata = 5
                                 , required.simul_duration = 100
                                 , required.seeding_duration = 10
                                 , required.seeding_timestep = 1
                                 , required.seeding_input = 100
                                 , required.max_abund_low = 30000
                                 , required.max_abund_medium = 50000
                                 , required.max_abund_high = 90000
                                 , doLight = TRUE
                                 , LIGHT.thresh_medium = 130000
                                 , LIGHT.thresh_low = 190000
                                 , doDispersal = TRUE
                                 , DISPERSAL.mode = 1
                                 , doHabSuitability = TRUE
                                 , HABSUIT.mode = 1
                                 )
                                   
## Create SEVERAL Global_parameters files
PRE_FATE.params_globalParameters(name.simulation = "FATE_simulation"
                                 , required.no_PFG = 3
                                 , required.no_strata = 5
                                 , required.simul_duration = 100
                                 , required.seeding_duration = 10
                                 , required.seeding_timestep = 1
                                 , required.seeding_input = 100
                                 , required.max_abund_low = 30000
                                 , required.max_abund_medium = 50000
                                 , required.max_abund_high = 90000
                                 , doLight = TRUE
                                 , LIGHT.thresh_medium = 130000
                                 , LIGHT.thresh_low = 190000
                                 , doDispersal = TRUE
                                 , DISPERSAL.mode = 1
                                 , doHabSuitability = TRUE
                                 , HABSUIT.mode = c(1,2)
                                 )



## ----------------------------------------------------------------------------------------- ##
                 
## Load example data
                                 

MayaGueguen/RFate documentation built on Oct. 17, 2020, 8:06 a.m.