Optimize StrathE2E ecology model parameters to maximise the likelihood of observed ecosystem target data.
e2e_optimize_eco.RdLaunches 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
e2e_optimize_eco(
model,
nyears = 40,
n_iter = 500,
start_temperature = 1,
cooling = 0.975,
toppredlock = TRUE,
quiet = TRUE,
csv.output = FALSE,
runtime.plot = TRUE
)Arguments
- 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
- toppredlock
Logical. If TRUE then locks-down the uptake parameters of the birds pinnipeds and cetaceans as these are hard to fit alongside the other parameters (default=TRUE).
- quiet
Logical. If TRUE then suppress informational messages at the start of each iteration (default=TRUE).
- csv.output
Logical. If TRUE then enable writing of csv output files (default=FALSE).
- runtime.plot
Logical. If FALSE then disable runtime plotting of the progress of the run - useful for testing (default=TRUE)
Value
A list object containing the histories of proposed and accepted parameters 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.
Details
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 models.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 observational data to which the ecology 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 coefficients of variation for jiggling the ecology parameter can be varied in real-time during the run by editing the file "optimize_ecology.csv" in the folder /Param/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 of the target data) range of the real time plot can be varied during the run by editing the setup file "optimize_ecology.csv"
At the end of the procedure, provided that csv.output=TRUE, new versions of the three ecology model 'fitted_parameters..' files are 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. These data are also saved in the list object returned by the function.
In order to use the new fitted parameter values 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 files.
Also at the end of the procedure the histories of proposed and accepted ecology model parameter values and corresponding likleihoods from each iteration of the procedure are saved as CSV files in the results folder (provided that the argument csv.output=TRUE), and in a list object which is returned by the function. The two csv files generated by the procedure have names: annealing_par_proposalhistory-*, annealing_par_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.
Examples
# \donttest{
# Load the 1970-1999 version of the North Sea model supplied with the package and generate a
# quick test data object with only 8 itereations and running the model for only 3 years.
# Also, the final parameter values are not saved back to the model Param folder.
# More realistic would be at least 500 iterations and running for 50 years.
# Even so this example will take a few minutes to run:
model<-e2e_read(model.name="North_Sea",
model.variant="1970-1999",
model.ident="test")
#> Current working directory is...
#> 'C:/Users/jackl/OneDrive - University of Strathclyde/Documents/Research/Packages/StrathE2E/strathe2e2/docs/reference'
#> No 'results.path' specified so any csv data requested
#> will be directed to/from the temporary directory...
#> 'C:\Users\jackl\AppData\Local\Temp\RtmpC42d8N'
#>
#> Model setup and parameters gathered from ...
#> StrathE2E2 package folder
#> Model results will be directed to/from ...
#> 'C:\Users\jackl\AppData\Local\Temp\RtmpC42d8N/North_Sea/1970-1999/'
# This model is already optimized to the observed ecosystem data supplied with the package
# so to illustrate the performance of the process we 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_eco(model, nyears=3, n_iter=8, start_temperature=0.4,
csv.output=FALSE)
#> [1] "Fri Mar 13 14:13:12 2026"
#> Iteration: 1; proposal likelihood: 0.1275625; accepted: YES
#> Iteration: 2; proposal likelihood: 0.1482656; accepted: YES
#> Iteration: 3; proposal likelihood: 0.0665700; accepted: NO
#> Iteration: 4; proposal likelihood: 0.0961250; accepted: NO
#> Iteration: 5; proposal likelihood: 0.1219375; accepted: YES
#> Iteration: 6; proposal likelihood: 0.1826460; accepted: YES
#> Iteration: 7; proposal likelihood: 0.2678180; accepted: YES
#> Iteration: 8; proposal likelihood: 0.2549592; accepted: YES
# View the structure of the returned list:
str(test_run,max.level=1)
#> List of 3
#> $ parameter_proposal_history:'data.frame': 8 obs. of 172 variables:
#> $ parameter_accepted_history:'data.frame': 8 obs. of 172 variables:
#> $ new_parameter_data :List of 3
# View the structure of the returned list element containing parameter objects:
str(test_run$new_parameter_data,max.level=1)
#> List of 3
#> $ new_preference_matrix :'data.frame': 23 obs. of 16 variables:
#> $ new_uptake_mort_rate_parameters:'data.frame': 17 obs. of 9 variables:
#> $ new_microbiology_parameters :'data.frame': 22 obs. of 2 variables:
# View the new preference matrix:
test_run$new_parameter_data$new_preference_matrix
#> kelp phyt omnivzoo carnzoo fishplar fishdlar
#> ammonia 0.2649943 0.2712913 NA NA NA NA
#> nitrate 0.7350057 0.7287087 NA NA NA NA
#> suspdet NA NA 0.0006554538 NA NA NA
#> seddet NA NA NA NA NA NA
#> kelpdebris NA NA NA NA NA NA
#> corpses NA NA NA NA NA NA
#> discards NA NA NA NA NA NA
#> kelp NA NA NA NA NA NA
#> phyt NA NA 0.9064117544 NA NA NA
#> omnivzoo NA NA NA 0.65083836 0.1459325 0.94695055
#> carnzoo NA NA NA NA NA NA
#> fishplar NA NA NA 0.01728045 NA NA
#> fishdlar NA NA NA 0.04134518 NA NA
#> fishp NA NA NA NA NA NA
#> fishm NA NA NA NA NA NA
#> fishd NA NA NA NA NA NA
#> benthslar NA NA 0.0015793716 0.19551374 0.5860957 0.04379505
#> benthclar NA NA 0.0913534202 0.09502226 0.2679718 0.00925440
#> benths NA NA NA NA NA NA
#> benthc NA NA NA NA NA NA
#> bird NA NA NA NA NA NA
#> seal NA NA NA NA NA NA
#> ceta NA NA NA NA NA NA
#> fishp fishm fishd benthslar benthclar benths
#> ammonia NA NA NA NA NA NA
#> nitrate NA NA NA NA NA NA
#> suspdet NA NA NA 0.97489776 0.3194097 0.2994866
#> seddet NA NA NA NA NA 0.4731953
#> kelpdebris NA NA NA NA NA NA
#> corpses NA NA 0.010285062 NA NA NA
#> discards NA NA 0.099212038 NA NA NA
#> kelp NA NA NA NA NA NA
#> phyt NA NA NA 0.02510224 0.6805903 0.2273181
#> omnivzoo 0.36520578 0.37062792 NA NA NA NA
#> carnzoo 0.15371590 0.01406015 0.077304663 NA NA NA
#> fishplar 0.12475679 0.05140494 0.117795807 NA NA NA
#> fishdlar 0.17922545 0.05679119 0.109965371 NA NA NA
#> fishp NA NA 0.106676891 NA NA NA
#> fishm NA NA 0.017333306 NA NA NA
#> fishd NA NA 0.005795267 NA NA NA
#> benthslar 0.08684140 0.28617803 NA NA NA NA
#> benthclar 0.09025468 0.22093776 NA NA NA NA
#> benths NA NA 0.382645627 NA NA NA
#> benthc NA NA 0.072985968 NA NA NA
#> bird NA NA NA NA NA NA
#> seal NA NA NA NA NA NA
#> ceta NA NA NA NA NA NA
#> benthc bird seal ceta
#> ammonia NA NA NA NA
#> nitrate NA NA NA NA
#> suspdet NA NA NA NA
#> seddet NA NA NA NA
#> kelpdebris 0.006672942 NA NA NA
#> corpses 0.424104664 0.08833120 0.05273427 NA
#> discards NA 0.25938988 0.05926399 0.131854550
#> kelp 0.012904102 NA NA NA
#> phyt NA NA NA NA
#> omnivzoo NA NA NA 0.009576065
#> carnzoo NA 0.09088022 0.00000000 0.018363997
#> fishplar NA NA NA NA
#> fishdlar NA NA NA NA
#> fishp NA 0.23255981 0.13524077 0.310495675
#> fishm NA 0.18374424 0.04815169 0.389615837
#> fishd NA 0.14509463 0.70460929 0.135575480
#> benthslar NA NA NA NA
#> benthclar NA NA NA NA
#> benths 0.556318293 0.00000000 0.00000000 0.000000000
#> benthc NA 0.00000000 0.00000000 0.000000000
#> bird NA NA 0.00000000 0.000000000
#> seal NA NA NA 0.004518397
#> ceta NA NA NA NA
# }
# --------------------------------------------------------------------------
# This is a dummy example to illustrate a realistic run in which optimised
# parameters are written back to the model Param folder. To try it out substitute
# your own relative folder path in place of \Folder in the e2e_copy() function...
# 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 relative to the current working directory (../Folder):
# e2e_copy("North_Sea", "1970-1999",
# dest.path="Folder")
# Load the copied version of the North Sea/1970-1999 model from the user workspace
# and assign a path for results data:
# (REPLACE "Folder/Models" and "Folder/results" with your own paths before running)
# model<-e2e_read(model.name="North_Sea",
# model.variant="1970-1999",
# models.path="Folder/Models",
# results.path="Folder/results",
# model.ident="fittingrun")
# Launch the fitting process
# fitting_data <- e2e_optimize_eco(model, nyears=50, n_iter=500, start_temperature=1,
# csv.output=TRUE)
# --------------------------------------------------------------------------