Create multiple set(s) of parameter files for a FATE simulation

Source: R/PRE_FATE.params_multipleSet.R

This script is designed to create multiple sets of parameters using Latin Hypercube Sampling to help find best combination of parameters (see Details)

PRE_FATE.params_multipleSet(
  name.simulation.1,
  name.simulation.2 = NULL,
  file.simulParam.1,
  file.simulParam.2 = NULL,
  no_simulations,
  opt.folder.name = "FATE_simulation_MULTIPLE_SET",
  opt.seed = NULL,
  opt.percent_maxAbund = 0.5,
  opt.percent_seeding = 0.5,
  opt.percent_light = 0.5,
  opt.percent_soil = 0.5,
  do.max_abund_low = TRUE,
  do.max_abund_medium = TRUE,
  do.max_abund_high = TRUE,
  do.seeding_duration = TRUE,
  do.seeding_timestep = TRUE,
  do.seeding_input = TRUE,
  do.potential_fecundity = TRUE,
  do.no_strata = TRUE,
  do.LIGHT.thresh_medium = TRUE,
  do.LIGHT.thresh_low = TRUE,
  do.SOIL.init = TRUE,
  do.SOIL.retention = TRUE,
  do.DISPERSAL.mode = TRUE,
  do.HABSUIT.mode = TRUE
)

Arguments

name.simulation.1

a string corresponding to the main directory or simulation name of the FATE simulation from which to retrieve the first parameter simulation file (file.simulParam.1), and the second if given (file.simulParam.2) and no other directory provided (name.simulation.2 = NULL)

name.simulation.2

(optional) default NULL.
A string corresponding to the main directory or simulation name of the FATE simulation from which to retrieve the second parameter simulation file (file.simulParam.2)

file.simulParam.1

a string corresponding to the name of the simulation parameter file from which to retrieve parameter values that will be used to build the multiple set of new parameters

file.simulParam.2

(optional) default NULL.
A string corresponding to the name of the second simulation parameter file from which to retrieve parameter values that will be used to build parameter ranges in comparison with values from file.simulParam.1

no_simulations

an integer corresponding to the number of set of parameters that will be produced according to Latin Hypercube Sampling (LHS)

opt.folder.name

(optional) default FATE_simulation_MULTIPLE_SET.
A string corresponding to the name of the folder that will be created to store the results

opt.seed

(optional) default NULL.
An integer to be given to set.seed function, in order to fix the produced results if needed, as designLHD is also a random value generator

opt.percent_maxAbund

default 0.5. Amount of variation (between 0 and 1) around the original value of MAX_ABUND_LOW, MAX_ABUND_MEDIUM, MAX_ABUND_HIGH if selected

opt.percent_seeding

default 0.5. Amount of variation (between 0 and 1) around the original value of SEEDING_DURATION, SEEDING_TIMESTEP, SEEDING_INPUT, POTENTIAL_FECUNDITY if selected

opt.percent_light

default 0.5. Amount of variation (between 0 and 1) around the original value of LIGHT_THRESH_MEDIUM, LIGHT_THRESH_LOW if selected

opt.percent_soil

default 0.5. Amount of variation (between 0 and 1) around the original value of SOIL_INIT, SOIL_RETENTION if selected

do.max_abund_low

default TRUE. If TRUE, MAX_ABUND_LOW parameter within Global_parameters file will be declined into a range of values

do.max_abund_medium

default TRUE. If TRUE, MAX_ABUND_MEDIUM parameter within Global_parameters file will be declined into a range of values

do.max_abund_high

default TRUE. If TRUE, MAX_ABUND_HIGH parameter within Global_parameters file will be declined into a range of values

do.seeding_duration

default TRUE. If TRUE, SEEDING_DURATION parameter within Global_parameters file will be declined into a range of values

do.seeding_timestep

default TRUE. If TRUE, SEEDING_TIMESTEP parameter within Global_parameters file will be declined into a range of values

do.seeding_input

default TRUE. If TRUE, SEEDING_INPUT parameter within Global_parameters file will be declined into a range of values

do.potential_fecundity

default TRUE. If TRUE, POTENTIAL_FECUNDITY parameter within Global_parameters file will be declined into a range of values

do.no_strata

default TRUE. If TRUE, NO_STRATA parameter within Global_parameters file will be declined into a range of values, with potential impact on some parameters within PFG succession (and light) files (parameters STRATA, MAX_ABUNDANCE, IMM_SIZE, CHANG_STR_AGES (and LIGHT_TOL), see PRE_FATE.params_PFGsuccession (and PRE_FATE.params_PFGlight))

do.LIGHT.thresh_medium

default TRUE. If TRUE, LIGHT_THRESH_MEDIUM parameter within Global_parameters file will be declined into a range of values

do.LIGHT.thresh_low

default TRUE. If TRUE, LIGHT_THRESH_LOW parameter within Global_parameters file will be declined into a range of values

do.SOIL.init

default TRUE. If TRUE, SOIL_INIT parameter within Global_parameters file will be declined into a range of values

do.SOIL.retention

default TRUE. If TRUE, SOIL_RETENTION parameter within Global_parameters file will be declined into a range of values

do.DISPERSAL.mode

default TRUE. If TRUE, DISPERSAL_MODE parameter within Global_parameters file will be declined into its three possible values (either either packets kernel (1), exponential kernel (2) or exponential kernel with probability (3), see PRE_FATE.params_globalParameters)

do.HABSUIT.mode

default TRUE. If TRUE, HABSUIT_MODE parameter within Global_parameters file will be declined into its two possible values (either random (1) or PFG specific (2), see PRE_FATE.params_globalParameters)

Value

A new folder containing the different sets of parameters asked.

Depending on what elements have been asked to be varied, three types of files can have been modified :

  1. the global parameter file

  2. the PFG succession files

  3. the PFG light succession files

Below are listed the parameters that can change (if selected) within each file :

  • Into the name.simulation/DATA/GLOBAL_PARAMETERS folder :

    • NO_STRATA

    • SEEDING_DURATION

    • SEEDING_TIMESTEP

    • SEEDING_INPUT

    • POTENTIAL_FECUNDITY

    • MAX_ABUND_LOW

    • MAX_ABUND_MEDIUM

    • MAX_ABUND_HIGH

    If the simulation includes light interaction :

    • LIGHT_THRESH_MEDIUM

    • LIGHT_THRESH_LOW

    If the simulation includes soil interaction :

    • SOIL_INIT

    • SOIL_RETENTION

    If the simulation includes dispersal :

    • DISPERSAL_MODE

    If the simulation includes habitat suitability :

    • HABSUIT_MODE

  • Into the name.simulation/DATA/PFGS/SUCC folder :

    • STRATA

    • MAX_ABUNDANCE

    • IMM_SIZE

    • CHANG_STR_AGES

  • Into the name.simulation/DATA/PFGS/LIGHT folder :

    • LIGHT_TOL

Details

A FATE simulation requires several parameters to define general characteristics of the simulation : they are saved within a Global_parameters file (see PRE_FATE.params_globalParameters). To fit the model to a particular area and set of Plant Functional Groups (PFG), these are the parameters that should be optimized, since they are not data-dependant, unlike, for example, parameters related to PFG (height, maturity, dispersal distances, soil tolerance, etc).

(Note : this is true, except when varying the number of strata, which will have an impact on some parameters within SUCC and LIGHT PFG parameter files.)

The main idea is to start from a complete simulation folder, to select the parameters that should vary, and to create new parameter files with new parameter values based on pre-existing values.

Three possible scenarios are available :

1 folder -
1 simulation file

  • requested parameter values are extracted from the given simulation file

  • ranges are assigned to each parameter according to the specified value
    e.g. : if opt.percent_seeding = 0.5, and do.seeding_duration is asked, values will be generated for this parameter between : $$\text{SEEDING_DURATION} \pm \text{SEEDING_DURATION} * \frac{50}{100}$$

  • according to the required number of parameter sets to be produced (no_simulations), Latin Hypercube Sampling is applied to select each new parameter values

  • parameter files are created for these new parameter values

1 folder -
2 simulation files

  • same as 1st scenario

  • ranges assigned to each parameter correspond to the extracted values (e.g. : if do.seeding_duration is asked, values will be generated for this parameter between : SEEDING_DURATION (file_simulation.1) and SEEDING_DURATION (file_simulation.2)

2 folders -
2 simulation files

  • same as 2nd scenario, except that the two given simulation files come from two different simulation folders

Latin Hypercube Sampling is a statistical method to generate a sampling of parameter values from a multidimensional space, while ensuring a good representation of the real variability. The range of each parameter is known, and depending on the number of set of parameters asked to be obtained at the end, each range is more or less finely cut and values are drawn in order to explore the whole space of combinations.

Author

Billur Bektas, Maya Guéguen