PRE_FATE.params_multipleSet: Create multiple set(s) of parameter files for a 'FATE'...
In MayaGueguen/RFate: Vegetation modelling with the FATE model

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

View 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.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.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
)

`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.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` 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.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`)

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.

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 :

the global parameter file
the PFG succession files
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
- MAX_ABUND_LOW
- MAX_ABUND_MEDIUM
- MAX_ABUND_HIGH
If the simulation includes light competition :
- LIGHT_THRESH_MEDIUM
- LIGHT_THRESH_LOW
If the simulation includes soil competition :
- 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