PRE_FATE.params_multipleSet: Create multiple set(s) of parameter files for a 'FATE'...

In leca-dev/RFate: FATE with R

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

Description

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

Usage

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)

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.

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

Author(s)

Billur Bektas, Maya Guéguen

See Also

designLHD, PRE_FATE.skeletonDirectory, PRE_FATE.params_globalParameters, PRE_FATE.params_PFGsuccession, PRE_FATE.params_PFGlight,

leca-dev/RFate documentation built on Sept. 19, 2024, 6:09 a.m.