e2e_optimize_hr {StrathE2E2} | R Documentation |
Launches a StrathE2E simulated annealing process to find the set of fishing fleet model harvest ratio multipliers producing the maximum likelihood of observed target data on the state of the ecosystem, given specified environmental driving data and ecology model parameters.
e2e_optimize_hr( model, nyears = 40, n_iter = 500, start_temperature = 1, cooling = 0.975, quiet = TRUE, csv.output = TRUE, runtime.plot = TRUE )
model |
R-list object generated by the e2e_read() 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 |
quiet |
Logical. If TRUE then suppress informational messages at the start of each iteration (default=TRUE). |
csv.output |
Logical. If FALSE then disable writing of csv output files - useful for testing (default=TRUE). |
runtime.plot |
Logical. If FALSE then disable runtime plotting of the progress of the run - useful for testing (default=TRUE). |
Simulated annealing is is a probabilistic technique for approximating the global optimum of a given function. As implemented here the process 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 e2e_read() function.
NOTE that the user.path argument in the e2e_read() 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 /Param 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 e2e_copy() function to make a copy of the North Sea model in the user workspace.
The coefficient of variation for jiggling the harvest ratio multipliers can be varied in real-time during the run by editing the file "optimize_fishing.csv" in the folder /Param/control/ of the model version. Suggested vaues for the CV are in the range 0.1 to 0.01
The observational data to which the harvest ratio multiplier parameters are optimized are loaded from the folder Modelname/Variantname/Target/annual_observed_*.csv as part of a e2e_read() function call and are built into the R-list object generated by e2e_read(). Column 3 of annual_observed_* (header: "Use1_0") is a flag to set whether any given row is used in calculating the likelihood of the observed data given the model setup and parameters. Un-used rows of data are omitted from calculations.
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 of the target data) range of the real time plot can be varied during the run by editing the setup file "optimize_fishing.csv"
At the end of the procedure a new version of the harvest ratio multipliers file is exported to the folder /Param of the model version, with a user defined identifier specified by the model.ident argument in the e2e_read() function. The histories of proposed and accepted parameter combinations are saved as csv files in the results folder.
To preserve the new harvest ratio multipliers and incorporate them into the fishing fleet model parameterisation the multiplier values need to be applied to the scaling parameters which link the integrated effort by each gear to the harvest ratio value which gets piped into the ecology model. Manually update the values in rows 12-21 (excluding the header row) of the file /Param/fishing_fleet_*.csv, by multiplying the existing values by the new multipliers emerging from the annealing process.
If the edited file 'fishing_fleet_*.csv' is saved with a new identifier (*) then in order to use it in a subsequent run of the StrathE2E model (using the e2e_run() function) it will be necessary to edit the MODEL_SETUP.csv file in the relevant /Models/variant folder to point to the new file.
Also at the end of the procedure the proposed and accepted harvest ratio multipier values and corresponding likleihoods from each iteration of the procedure are saved as CSV files in the results folder and in a list object which is returned by the function. The two csv files generated by the procedure have names: annealing_HRmult_proposalhistory-*, annealing_HRmult_acceptedhistory-*, where * denotes the value of model.ident defined in the preceding e2e_read() function call. The returned list object contains three dataframes: parameter_proposal_history, parameter_accepted_history, new_parameter_data (a list of three). The proposal and accepted histories can be further analysed with the function e2e_plot_opt_diagnostics() to assess the performance of the optimization process.
A list object containing the histories of proposed and accepted parameter values and the final accepted parameter values. Optionally (by default), csv files of the histories and the final accepted parameter values. The latter are returned to the model parameter folder in a format to be read back into the model.
e2e_ls
, e2e_read
, e2e_plot_opt_diagnostics
, e2e_optimize_eco
, e2e_optimize_act
model<-e2e_read(model.name="North_Sea", model.variant="1970-1999", model.ident="test") # This model is already optimized to the observed ecosystem data supplied with the package # Perturb the temperature driving to knock the model away from its maximum likelihood # state relative to the target data: # add 3 degC to upper layer offshore temperatures: model$data$physics.drivers$so_temp <- model$data$physics.drivers$so_temp+3 # add 3 degC to inshore temperatures: model$data$physics.drivers$si_temp <- model$data$physics.drivers$si_temp+3 # add 3 degC to lower layer offshore temperatures: model$data$physics.drivers$d_temp <- model$data$physics.drivers$d_temp+3 test_run <- e2e_optimize_hr(model, nyears=5, n_iter=10, start_temperature=0.4,csv.output=FALSE) # View the structure of the returned list: str(test_run,max.level=1) # View the structure of the returned list element containing parameter objects: str(test_run$new_parameter_data,max.level=1) # View the new, final accepted parameter data: test_run$new_parameter_data ## Not run: # More realistic configuration would be (WARNING - this will take about 26 hours to run) : # Copy the 1970-1999 version of the North Sea model supplied with the package into a # user workspace (Windows OS): e2e_copy("North_Sea", "1970-1999", dest.path="C:/Users/username/Documents/Models") # Load the 1970-1999 version of the North Sea model from the user workspace: model<-e2e_read(model.name="North_Sea", model.variant="1970-1999", model.ident="fittingrun", user.path="C:/Users/username/Documents/Models") # Launch the fitting process e2e_optimize_hr(model, nyears=50, n_iter=1000, start_temperature=1) ## End(Not run)