FATE tutorial 3 - Use a module

Source: vignettes/fate_tutorial_3_MODULES.Rmd



FATE model is built like a LEGO tool : it has a core module, which corresponds to the fundamental succession, and then can be complemented with other modules. Some of these modules can be regarded as equally important as the core module (from an ecological likelihood point of view, like light, dispersal, soil, etc), and some others are more specific (drought, aliens, fire, etc).


All of these modules require 
mandatory parameters
and sometimes, some others that are 
optional

that can all be created with RFate functions.



CORE module (succession)

“Based on the ‘FATE’ model (Moore & Noble, 1990), it describes the within-pixel succession dynamics in an annual time step. […] Five processes describe PFG demography (germination, recruitment, growth, survival and fecundity, see Table 1).” (Boulangeat, 2014)

Required parameters 
NO_PFG 16
NO_STRATA 6
SIMULATION_DURATION 950
SEEDING_DURATION 300
SEEDING_TIMESTEP 1
SEEDING_INPUT 100
POTENTIAL_FECUNDITY 10
The number of computer resources can also be given : 
NO_CPU 6

If so, some parts of the main loop of the code will be parallelized on the amount of indicated resources.

Finally, several parameters are available to select which outputs should be saved on when running the simulation : 
SAVING_ABUND_PFG_STRATUM 1
SAVING_ABUND_PFG 1
SAVING_ABUND_STRATUM 0

--GLOBAL_PARAMS--
FATE_simulation/DATA/GLOBAL_PARAMETERS/Global_parameters_V1.txt
--SAVING_DIR--
FATE_simulation/RESULTS/SIMUL_1/
--MASK--
FATE_simulation/DATA/MASK/mask.tif
--PFG_PARAMS_LIFE_HISTORY--
FATE_simulation/DATA/PFGS/SUCC/SUCC_PFG1.txt
FATE_simulation/DATA/PFGS/SUCC/SUCC_PFG2.txt
--END_OF_FILE--

The years for which outputs must be saved can also be indicated,
as well as years to save a copy of the simulation object :

--SAVING_YEARS_ARRAYS--
FATE_simulation/DATA/SAVE/SAVE_YEARS_maps.txt
--SAVING_YEARS_OBJECTS--
FATE_simulation/DATA/SAVE/SAVE_YEARS_objects.txt
  • In SUCCESSION files (given with the --PFG_PARAMS_LIFE_HISTORY-- flag in SimulParameters file) :
NAME PFG1
TYPE P
HEIGHT 1200
MATURITY 45
LONGEVITY 451
MAX_ABUNDANCE 100
IMM_SIZE 10
CHANG_STR_AGES 0 14 38 110 344
SEED_POOL_LIFE 0 0
SEED_DORMANCY 0
The maximum number of seeds produced each year can also be specified per PFG : 
MAX_STRATUM 5
POTENTIAL_FECUNDITY 50


LIGHT module (interaction)

“Vegetation height is represented by a limited number of strata to incorporate the shading process (Fig. 1a). Within a pixel, the light resource for each stratum is calculated from the total abundance of all PFGs across all the upper strata. Within-pixel spatial heterogeneity in light resources is not taken into consideration” (Boulangeat, 2014)

Required parameters 
DO_LIGHT_INTERACTION 1
LIGHT_THRESH_MEDIUM 4000
LIGHT_THRESH_LOW 7000

LIGHT_RECRUITMENT 1
LIGHT_SAVING 1

--PFG_PARAMS_LIGHT--
FATE_simulation/DATA/PFGS/LIGHT/LIGHT_PFG1.txt
FATE_simulation/DATA/PFGS/LIGHT/LIGHT_PFG2.txt
  • In LIGHT files (given with the --PFG_PARAMS_LIGHT-- flag in SimulParameters file) :
NAME PFG1
LIGHT 4
SHADE_FACTOR 20
ACTIVE_GERM 90 90 90
LIGHT_TOL 100 100 100 100 100 100 100 100 100


SOIL module (interaction)

“To be written” ()

Required parameters 
DO_SOIL_INTERACTION 1
SOIL_INIT 2.5
SOIL_RETENTION 0.8

SOIL_FILL_MAP 1
SOIL_RECRUITMENT 1
SOIL_SAVING 1

--PFG_PARAMS_SOIL--
FATE_simulation/DATA/PFGS/SOIL/SOIL_PFG1.txt
FATE_simulation/DATA/PFGS/SOIL/SOIL_PFG2.txt

--SOIL_MASK--
FATE_simulation/DATA/MASK/mask_soil.tif
  • In SOIL files (given with the --PFG_PARAMS_SOIL-- flag in SimulParameters file) :
NAME PFG1
ACTIVE_GERM 80 100 50
SOIL_CONTRIB 2.4
SOIL_LOW 1
SOIL_HIGH 4
SOIL_TOL 10 100 0 50 100 40 90 100 80


DISPERSAL module

“The quantity of produced seeds depends on the abundances of mature PFGs and their habitat suitability. A seed dispersal model determines seed inflow in each pixel (Fig. 1c). From the source, three circles of influence are defined using distance parameters. In the first circle, 50% of the seeds are distributed uniformly. In the second circle, 49% of the seeds are distributed with the same concentration as in the first circle but by pairs of pixels, simulating the spatial autocorrelation of dispersed seeds. In the third circle, 1% of the seeds fall into a random pixel. This seed dispersal model behaves similar to a continuous kernel function (see Fig.S1a) but is very effective and requires only a few parameters (Vittoz & Engler, 2007).” (Boulangeat, 2014)

Required parameters 
DO_DISPERSAL 1
DISPERSAL_MODE 1

DISPERSAL_SAVING 0

--PFG_PARAMS_DISPERSAL--
FATE_simulation/DATA/PFGS/DISP/DISP_PFG1.txt
FATE_simulation/DATA/PFGS/DISP/DISP_PFG2.txt
  • In DISPERSAL files (given with the --PFG_PARAMS_DISPERSAL-- flag in SimulParameters file) :
NAME PFG1
DISPERS_DIST 100 500 79000


HABITAT SUITABILITY module

“Modelling how habitat suitability affects species population dynamics is tricky given the limited knowledge on the type and form of this relationship. Gallien et al. (2010) suggested a parsimonious approach using only presence-absences or a linear link. In FATE-HD, the probability for recruitment and seed production occurring is calculated every year according to the habitat suitability of the PFG in the pixel in question. Over time, the probability of presence is thus linearly related to fecundity and establishment. Accounting for interannual variability allows species coexistence via temporal niches. Mortality does not depend on habitat suitability, as the immediate effects of annual abiotic conditions on plant mortality are not clear in the literature. Habitat suitability for each PFG can be obtained from various sources such as correlative species distribution models (Guisan & Thuiller, 2005) or mechanistic niche models (Chuine & Beaubien, 2001).” (Boulangeat, 2014)

Required parameters 
DO_HAB_SUITABILITY 1
HABSUIT_MODE 1

--PFG_MASK_HABSUIT--
FATE_simulation/DATA/PFGS/HABSUIT/HS_CA/HS_PFG1_0.tif
FATE_simulation/DATA/PFGS/HABSUIT/HS_CA/HS_PFG2_0.tif

Habitat suitability maps can be changed through simulation time.
Two supplementary type of files are then needed :

  1. a file with each row indicating each simulation year of change
  2. as many files as the number of years indicated in the previous file,
    and inside them, as many lines as PFG, with a path for a new habitat suitability for each of them
--HABSUIT_CHANGEMASK_YEARS--
FATE_simulation/DATA/SCENARIO/HABSUIT/HABSUIT_changingmask_years.txt
--HABSUIT_CHANGEMASK_FILES--
FATE_simulation/DATA/SCENARIO/HABSUIT/HABSUIT_changingmask_files_t20.txt
FATE_simulation/DATA/SCENARIO/HABSUIT/HABSUIT_changingmask_files_t30.txt
FATE_simulation/DATA/SCENARIO/HABSUIT/HABSUIT_changingmask_files_t50.txt
FATE_simulation/DATA/SCENARIO/HABSUIT/HABSUIT_changingmask_files_t100.txt


DISTURBANCES module

“Several disturbance models can be parameterized to remove vegetation, affect fecundity, kill seeds or activate dormant seeds according to each PFG’s tolerance or sensitivity to the given disturbance. (Fig. 1d).” (Boulangeat, 2014)

Required parameters 
DO_DISTURBANCES 1
DIST_NO 4
DIST_NOSUB 4
DIST_FREQ 1 1 1 1

DIST_PROB 1 1 0.6 0.6
DIST_PAIR 1 1 2 2

--PFG_PARAMS_DISTURBANCES--
FATE_simulation/DATA/PFGS/DIST/DIST_PFG1.txt
FATE_simulation/DATA/PFGS/DIST/DIST_PFG2.txt
--DIST_MASK--
FATE_simulation/DATA/MASK/mask_noPerturb.tif
FATE_simulation/DATA/MASK/mask_mowing.tif
FATE_simulation/DATA/MASK/mask_grazing_level1.tif
FATE_simulation/DATA/MASK/mask_grazing_level2.tif

Like habitat suitability maps, disturbances maps can be changed through simulation time.
Two supplementary type of files are then needed :

  1. a file with each row indicating each simulation year of change
  2. as many files as the number of years indicated in the previous file,
    and inside them, as many lines as disturbances, with a path for a new mask for each of them
--DIST_CHANGEMASK_YEARS--
FATE_simulation/DATA/SCENARIO/DIST_scenario1/DIST_changingmask_years.txt
--DIST_CHANGEMASK_FILES--
FATE_simulation/DATA/SCENARIO/DIST_scenario1/DIST_changingmask_files_t50.txt
FATE_simulation/DATA/SCENARIO/DIST_scenario1/DIST_changingmask_files_t100.txt
FATE_simulation/DATA/SCENARIO/DIST_scenario1/DIST_changingmask_files_t150.txt
  • In DISTURBANCE files (given with the --PFG_PARAMS_DISTURBANCES-- flag in SimulParameters file) :
NAME PFG1
BREAK_AGE 2 4 10 2 4 10 2 4 10 2 4 10
RESPR_AGE 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
FATES 0 0 0 0 50 20 40 0 0 0 0 0 0 0 0 0 0 0 0 0 0 10 0 0 0 0 0 0 0 20 0 10
PROP_KILLED 0 0 0 0
ACTIVATED_SEED 0 0 0 0


DROUGHT module

“Fig. 1. Drought simulation scheme. For each year i, a PFG’s habitat suitability (HS; step 1) and drought effects (step 2) are evaluated within a pixel j. If HS ij or Din ij are below reference values, PFG fecundity and recruitment are set to 0. Additionally, if Din ij crosses the reference value, one drought year is added to the PFG’s cumulative drought effects counter. Severe drought effects occur if conditions 2.3.1 ii or 2.3.2 are met, consisting in immediate and post-drought effects. Otherwise, only moderate drought effects are caused (2.1 and 2.3.1 i). Drought recovery is simulated by subtracting one or two drought events from the cumulative drought effects counter. […] See Table S3 in Appendix S2 for full parameter list and refer to main text for further details.” (Barros, 2017)

Required parameters 
DO_DROUGHT_DISTURBANCE 1
DROUGHT_NOSUB 4

--PFG_PARAMS_DROUGHT--
FATE_simulation/DATA/PFGS/DROUGHT/DROUGHT_PFG1.txt
FATE_simulation/DATA/PFGS/DROUGHT/DROUGHT_PFG2.txt
--DROUGHT_MASK--
FATE_simulation/DATA/MASK/DROUGHT_init.tif

Like habitat suitability or disturbances maps, the drought index map can be changed through simulation time.
Two supplementary type of files are then needed :

  1. a file with each row indicating each simulation year of change
  2. as many files as the number of years indicated in the previous file,
    and inside them, one line with a path for a new map of drought index
--DROUGHT_CHANGEMASK_YEARS--
FATE_simulation/DATA/SCENARIO/DROUGHT_changingmask_years.txt
--DROUGHT_CHANGEMASK_FILES--
FATE_simulation/DATA/SCENARIO/DROUGHT_changingmask_files_t15.txt
FATE_simulation/DATA/SCENARIO/DROUGHT_changingmask_files_t30.txt
FATE_simulation/DATA/SCENARIO/DROUGHT_changingmask_files_t45.txt
  • In DROUGHT files (given with the --PFG_PARAMS_DROUGHT-- flag in SimulParameters file) :
NAME PFG1
BREAK_AGE 1 5 26 1 5 26
RESPR_AGE 0 0 3 26 0 0 3 26
FATES 60 0 20 0 50 0 60 0 20 0 50 0 10 0 20 0
PROP_KILLED 0 0
ACTIVATED_SEED 0 0
DROUGHT_THRESH_MOD -11.50406848
DROUGHT_THRESH_SEV -12.3335733
COUNTER_RECOVERY 1
COUNTER_SENS 3
COUNTER_CUM 3


ALIENS module

“We then simulated the introduction of the alien PFGs through annual seeding. The sites of simulated introduction were based on a map of the Human Footprint […] an index combining information on land-use, population density and transportation network (including mountain footpaths). As such it represents an excellent proxy of potential local propagule pressure for introduced species […] In the current propagule pressure scenario, introductions were a proportion of a set maximum number of seeds depending on the human footprint value in each pixel (i.e. highest introduction intensity in the most densely populated centres, and lowest introduction intensity along mountain footpaths; see Appendix S2 for maps and for details). In the increased propagule pressure scenario, the maximum introduction level was applied in all areas that had a non-zero human footprint (simulating a maximum exploitation of all areas suitable to humans).” (Carboni, 2017)

Required parameters 
DO_ALIENS_INTRODUCTION 1
ALIENS_NO 4
ALIENS_FREQ 2 2 2 2

--PFG_MASK_ALIENS--
FATE_simulation/DATA/PFGS/ALIENS/NoIntroduction.tif
FATE_simulation/DATA/PFGS/ALIENS/Introduction_ALIEN2.tif
FATE_simulation/DATA/PFGS/ALIENS/Introduction_ALIEN3.tif
FATE_simulation/DATA/PFGS/ALIENS/Introduction_ALIEN4.tif

Like habitat suitability or disturbances maps, aliens introduction masks can be changed through simulation time.
Two supplementary type of files are then needed :

  1. a file with each row indicating each simulation year of change
  2. as many files as the number of years indicated in the previous file,
    and inside them, as many lines as PFG, with a path for a new mask for each of them
--ALIENS_CHANGEMASK_YEARS--
FATE_simulation/DATA/SCENARIO/ALIENS_changingmask_years.txt
--ALIENS_CHANGEMASK_FILES--
FATE_simulation/DATA/SCENARIO/ALIENS_changingmask_files_t20.txt
FATE_simulation/DATA/SCENARIO/ALIENS_changingmask_files_t25.txt

Once introduction maps have been set, frequency of introduction can also be changed through simulation time.
Two supplementary type of files are then needed :

  1. a file with each row indicating each simulation year of change
  2. as many files as the number of years indicated in the previous file,
    and inside them, as many lines as PFG, with a number for each of them representing its introduction frequency
--ALIENS_CHANGEFREQ_YEARS--
FATE_simulation/DATA/SCENARIO/ALIENS_changingfreq_years.txt
--ALIENS_CHANGEFREQ_FILES--
FATE_simulation/DATA/SCENARIO/ALIENS_changingfreq_files_t20.txt
FATE_simulation/DATA/SCENARIO/ALIENS_changingfreq_files_t25.txt
  • In SUCCESSION files (given with the --PFG_PARAMS_LIFE_HISTORY-- flag in SimulParameters file) :
IS_ALIEN 1


FIRE module

“To be written” ()

Required parameters 
DO_FIRE_DISTURBANCE 1
FIRE_NO 1
FIRE_NOSUB 4
FIRE_FREQ 2
FIRE_IGNIT_MODE 1
FIRE_NEIGH_MODE 2
FIRE_PROP_MODE 4
FIRE_QUOTA_MODE 2
Depending on the values given for the FIRE_IGNIT_MODE, FIRE_NEIGH_MODE, FIRE_PROP_MODE and FIRE_QUOTA_MODE parameters,
more information might be needed : 
FIRE_IGNIT_NO 12

FIRE_IGNIT_NOHIST 5 8 12 5 9 0 3 11 5 7 4

FIRE_IGNIT_LOGIS 0.6 2.5 0.05
FIRE_IGNIT_FLAMMMAX 10

FIRE_NEIGH_CC 4 3 4 3

FIRE_PROP_INTENSITY 0.5

FIRE_PROP_LOGIS 0.6 2.5 0.05

FIRE_QUOTA_MAX 1000

--PFG_PARAMS_FIRE--
FATE_simulation/DATA/PFGS/FIRE/FIRE_PFG1.txt
FATE_simulation/DATA/PFGS/FIRE/FIRE_PFG2.txt
--FIRE_MASK--
FATE_simulation/DATA/MASK/FIRE_init.tif

Like habitat suitability or disturbances maps, fire masks can be changed through simulation time.
Two supplementary type of files are then needed :

  1. a file with each row indicating each simulation year of change
  2. as many files as the number of years indicated in the previous file,
    and inside them, as many lines as fire disturbances, with a path for a new mask for each of them
--FIRE_CHANGEMASK_YEARS--
FATE_simulation/DATA/SCENARIO/FIRE_changingmask_years.txt
--FIRE_CHANGEMASK_FILES--
FATE_simulation/DATA/SCENARIO/FIRE_changingmask_files_t20.txt
FATE_simulation/DATA/SCENARIO/FIRE_changingmask_files_t25.txt

Once introduction maps have been set, frequency of fires can also be changed through simulation time.
Two supplementary type of files are then needed :

  1. a file with each row indicating each simulation year of change
  2. as many files as the number of years indicated in the previous file,
    and inside them, as many lines as fire disturbances, with a number for each of them representing its occuring frequency
--FIRE_CHANGEFREQ_YEARS--
FATE_simulation/DATA/SCENARIO/FIRE_changingfreq_years.txt
--FIRE_CHANGEFREQ_FILES--
FATE_simulation/DATA/SCENARIO/FIRE_changingfreq_files_t20.txt
FATE_simulation/DATA/SCENARIO/FIRE_changingfreq_files_t25.txt
Depending on the value given for the FIRE_PROP_MODE parameter, more information might be needed : 
--ELEVATION_MASK--
FATE_simulation/DATA/MASK/elevation.tif
--SLOPE_MASK--
FATE_simulation/DATA/MASK/slope.tif
  • In SUCCESSION files (given with the --PFG_PARAMS_LIFE_HISTORY-- flag in SimulParameters file) :
FLAMMABILITY 6
  • In FIRE files (given with the --PFG_PARAMS_FIRE-- flag in SimulParameters file) :
NAME PFG1
BREAK_AGE 1 4 20
RESPR_AGE 0 1 3 12
FATES 80 0 60 40 50 50 40 60
PROP_KILLED 0 0
ACTIVATED_SEED 0 0