estim_options

Sets options for estim.pars

Contents

Syntax

estim_options (key, val)

Description

Sets options for estimation one by one, some apply to methods nm and mmea, others to mmea only

Input

  'default': sets options at default values
   any other key (see below): print value to screen

  'loss_function':
    'sb': multiplicative symmetric bounded (default)
    'su': multiplicative symmetric unbounded
    're': relative error (not recommanded)
    'SMAE': symmetric mean absolute error

  'filter':
    0: do not use filters;
    1: use filters (default)

  'pars_init_method':
    0: get initial estimates from automatized computation
    1: read initial estimates from .mat file (for continuation)
    2: read initial estimates from pars_init file (default)
    3: get initial estimates from DEBInitNet

  'results_output':
    0     - only saves data to .mat (no printing to html or screen and no figures) - use this for (automatic) continuations
    1, -1 - no saving to .mat file, prints results to html (1) or screen (-1), shows figures but does not save them
    2, -2 - saves to .mat file, prints results to html (2) or screen (-2), shows figures but does not save them
    3, -3 - like 2 (or -2), but also prints graphs to .png files (default is 3)
    4, -4 - like 3 (or -3), but also prints html with implied traits
    5, -5 - like 4 (or -4), but includes related species in the implied traits
    6     - like 5, but also prints html with population traits

  'method':
    'no': do not estimate
    'nm': Nelder-Mead simplex method (default)
    'mmea': multimodal evolutionary algorithm

  'max_fun_evals': maximum number of function evaluations (default 10000)

  'report':
     0 - do not report
     1 - report steps to screen (default)

  'max_step_number': maximum number of steps (default 500)

  'tol_simplex': tolerance for how close the simplex points must be together to call them the same (default 1e-4)

  'tol_fun': tolerance for how close the loss-function values must be together to call them the same (default 1e-4)

  'simplex_size': fraction added (subtracted if negative) to the free parameters when building the simplex (default 0.05)

  'search_method' (method mmea only):
    'mm_shade' - use mm_shade method (default)

  'num_results' (method mmea only): The size for the multimodal algorithm's population. The author recommended
     50 for mm_shade ('search_method mm_shade', default)
     18 * number of free parameters for L-mm_shade ('search method l-mm_shade')

  'gen_factor' (method mmea only): percentage to build the ranges for initializing the first population of individuals (default 0.5)

  'bounds_from_ind' (method mmea only):
    0: use ranges from pseudodata if exist (these ranges not existing will be taken from data)
    1: use ranges from data (default)

  'max_calibration_time' (method mmea only): maximum calibration time in minutes (default 30)
  'min_convergence_threshold' (method mmea only): the minimum improvement the mmea needs to reach
                                                  to continue the calibration process (default 1e-4)
  'max_pop_dist': the maximum distance allowed between the solutions of the MMEA population to
                   continue the calibration process (default 0.2).
  'num_runs' (method mmea only): the number of independent runs to perform (default 1)

  'add_initial' (method mmea only): if the initial individual is added in the first  population.
    1: activated
    0: not activated (default)

  'refine_best'  (method mmea only): if the best individual found is refined using Nelder-Mead.
    0: not activated (default)
    1: activated

  'verbose_options' (method mmea only): The number of solutions to show from the set of optimal solutions found by the algorithm through the calibration process (default 10)

  'verbose' (method mmea only): prints some information while the calibration  process is running
     0: not activated (default)
     1: activated

  'seed_index' (method mmea only): index of vector with values for the seeds used to generate random values
     each one is used in a single run of the algorithm (default 1, must be between 1 and 30)

  'ranges' (method mmea only): Structure with ranges for the parameters to be calibrated (default empty)
     one value (factor between [0, 1], if not: 0.01 is set) to increase and decrease the original parameter values.
     two values (min, max) for the  minimum and maximum range values. Consider:
       (1) Use min < max for each variable in ranges. If it is not, then the range will be not used
       (2) Do not take max/min too high, use the likely ranges of the problem
       (3) Only the free parameters (see 'pars_init_my_pet' file) are considered
     Set range with cell string of name of parameter and value for range, e.g. estim_options('ranges',{'kap', [0.3 1]}}
     Remove range-specification with e.g. estim_options('ranges', {'kap'}} or estim_options('ranges', 'kap'}

  'results_display (method mmea only)':
     Basic - Does not show results in screen (default)
     Best  - Plots the best solution results in DEBtool style
     Set   - Plots all the solutions remarking the best one
             html with pars (best pars and a measure of the variance of each parameter in the solutions obtained for example)
     Complete - Joins all options with zero variate data with input and a measure of the variance of all the solutions considered

  'results_filename (method mmea only)': The name for the results file (solutionSet_my_pet_time)

  'save_results' (method mmea only): If the results output images are going to be saved
     0: no saving (default)
     1: saving

  'mat_file' (method mmea only): The name of the .mat-file with results from where to initialize the calibration parameters
     (only useful if pars_init_method option is equal to 1 and if there is a result file)
     This file is outputted as results_my_pet.mat ("my pet" replaced by name of species) using method nm, results_output 0, 2-6.

  'sigma_share': The value of the sigma share parameter (that is used
     into the fitness sharing niching method if it is activated)

Output

Remarks

See estim_pars for application of the option settings. Initial estimates are controlled by option 'pars_init_method', but the free-setting is always taken from the pars_init file. A typical estimation procedure is

If results_output equals 5 or higher, the comparison species can be specified by declaring variable refPets as global and fill it with a cell-string of AmP species names.

The default setting for max_step_number on 500 in method nm is on purpose not enough to reach convergence. Continuation (using arrow-up + 'enter' after 'pars_init_method' set on 1) is important to restore simplex size.

Typical simplex options are also used in the evolutionary algorithm via local_search in mm_shade and lmm_shade

Example of use

estim_options('default'); estim_options('filter', 0); estim_options('method', 'no')

warnings

Published with MATLAB® R2021a