annealing_find_ecology_parameters {StrathE2E2}R Documentation

Optimise StrathE2E ecology model parameters to maximise the likelihood of observed ecosystem target data

Description

Launches a StrathE2E simulated annealing process to find the set of ecology model parameters producing the maximum likelihood of observed target data on the state of the ecosystem, given specified environmental driving data and fishing fleet parameters.

Usage

annealing_find_ecology_parameters(model, nyears = 40, n_iter = 500,
  start_temperature = 1, cooling = 0.975, toppredlock = TRUE,
  quiet = TRUE)

Arguments

model

R-list object generated by the read_model() function which defined the model configuration

nyears

Number of years to run the model in each iteration (default=40)

n_iter

Number of iterations of the model (default=500)

start_temperature

Initial value of the simulated annealing temperature parameter (default=1). Suggested values in the range 0.0005 - 5. Higher values increase the probability of rejecting parameter combinations producing an improvement in likelihood

cooling

Rate at which the simulated annealing temperature declines with iterations (default=0.975). Suggested values in the range 0.9 - 0.985

toppredlock

(TRUE or FALSE) Locks-down the uptake parameters of the birds pinnipeds and cetaceans as these are hard to fit alongside the other parameters (default=TRUE)

quiet

(TRUE or FALSE) Suppress informational messages at the start of each iteration (default=TRUE)

Details

Simulated annealing is an iterative random-walk type process which searches the parameter space of a model to locate the combination which maximises the likelihood of a set of observed data corresponding to a suite of derived outputs. Parameter combinations which result in an improved likelihood may be rejected according to a probability ('temperature') which decreases as the iterations progress. This is to avoid becoming stuck at local likelihood-maxima. The rate at which the 'temperature' decreases is set by a 'cooling' parameter (fraction of previous temperature at each iteration, 0<value<1)

Model configuration and initial values of the ecology model parameters need to be assembled by a prior call of the read_model() function.

NOTE that the user.path argument in the read_model() function call needs to point to a user workspace folder, not the default North Sea model provided with the package. This is because the annealing function needs write-access to the model /Parameters folder, but the /extdata/Models folder in the package installation is read-only. To use the annealing function on the North Sea model, use the copy_model() function to make a copy of the North Sea model in the user workspace.

The coefficients of variation for jiggling the ecology parameter can be varied in real-time during the run by editing the file "annealing_SD_ecology.csv" in the folder /Parameters/Parameter_SD_control/ of the model version.

The function produces a real-time graphical summary of the progress of the fitting procedure, displaying the likelihoods of the proposed and accepted parameter sets at each iteration. Y-axis (likelihood o fthe target data) range of the real time plot can be varied during the run by editing the setup file "annealing_SD_ecology.csv"

At the end of the procedure new versions of the three ecology model fitted_parameters.. files are exported to the folder /Parameters of the model version, with a user defined identifier specified by the model.ident argument in the read_model() function. The histories of proposed and accepted parameter combinations are saved as CSV files in the results folder.

In order to use the new fitted parameter values in a subsequent run of the StrathE2E model (using the StrathE2E() function) it will be necessary to edit the MODEL_SETUP.csv file in the relevant /Models/variant folder to point to the new files.

Value

CSV files of fitted parameters and the histories of the proposed and accepted parameter values

See Also

list_models , read_model , StrathE2E , annealing_find_harvest_ratio_mult , annealing_find_gear_activity_mult_ecosystem_target , annealing_find_gear_activity_mult_HR_target

Examples

#Copy the 2003-2013 version of the North Sea model supplied with the package into a user workspace (Windows OS):
copy_model("North_Sea", "2003-2013",
           dest.path="C:/Users/username/Documents/Models")

# Load the 2003-2013 version of the North Sea model from the user workspace:
model<-read_model(model.name="North_Sea",
                  model.variant="2003-2013",
                  model.ident="TEST",
                  user.path="C:/Users/username/Documents/Models")

# Quick Demo of the annealing function in operation:
annealing_find_ecology_parameters(model, nyears=5, n_iter=10, start_temperature=0.5)
# More realistic configuration would be (WARNING - this will take about 26 hours to run) :
annealing_find_ecology_parameters(model, nyears=50, n_iter=1000, start_temperature=1)


[Package StrathE2E2 version 2.0.0 Index]