StrathE2E2 User Manual

Michael R. Heath () and Ian Thurlbeck ()
University of Strathclyde, Department of Mathematics and Statistics,
Glasgow, Scotland, UK

June 12, 2020


Summary


Documentation

To see an overview of the package, launch an R-session and then:

library("StrathE2E2")   # Load the package
?StrathE2E2     # Launch the overview document in a browser window
# or...
help(StrathE2E2)


Technical Manual - documentation on the structure of input and output R-objects and files


See also the following supporting documents:

Origin of the model (previous versions)
Overview of the model concepts and design
Ecology model description
Fishing fleet model description
Parameter optimisation, sensitivity and Monte Carlo methodology
StrathE2E implementation for the North Sea


Funding

Development of the StrathE2E2 package was supported by the UK NERC Marine Ecosystems Research Programme (NE/L003120/1)
Other projects which have supported aspects of the model development are:
EU-Horizon 2020 (DISCARDLESS project)
Fisheries Innovation Scotland (project FIS003).


User community

We plan to develop a repository of open access implementations of StrathE2E for shelf sea regions. Users developing implementations which they are willing to share are encouraged to contact us to discuss inclusion in the repository.


How to cite the package:

citation("StrathE2E2")

To cite package 'StrathE2E2' in publications use:

  Heath, M.R., Speirs, D.C., Thurlbeck, I. and Wilson, R. (2019).
  StrathE2E2: an R package for modelling the dynamics of marine food
  webs and fisheries. Methods in Ecology and Evolution, submitted
  (check online for updates).

A BibTeX entry for LaTeX users is

  @Article{,
    title = {StrathE2E2: an R package for modelling the dynamics of marine food webs and fisheries},
    author = {Michael R. Heath and Douglas C. Speirs and Ian Thurlbeck and Robert Wilson},
    journal = {Methods in Ecology and Evolution},
    volume = {submitted},
    year = {2019},
    issn = {2041-210X},
    url = {https://besjournals.onlinelibrary.wiley.com/journal/2041210X},
    keywords = {food web, dynamic model, ecosystem, fisheries, ordinary differential equations, optimization, sensitivity analysis, Monte-Carlo, R},
  }



Contents

Quick start

1 Package structure

2 Getting started

2.1 Installing the package

2.2 Folder structure for model input and output files

2.3 Running one of the North Sea model versions

2.3.1 Setting initial conditions for the state variables

2.3.2 Plotting functions for visualizing model output

3 More advanced use of the model

3.1 Writing your own code to create model scenarios

3.2 Comparing scenario model results with a baseline model.

3.3 Writing your own code to work with the model output

4 Parameter estimation

4.1 Background

4.2 Implementation of the Metropolis-Hastings algorithm

4.3 Target data for optimisation

4.4 Versions of parameter estimation

4.4.1 Ecology model parameter estimation

4.4.1.1 Using the function annealing_find_ecology_parameters()

4.4.2 Estimation of scaling parameters linking fishing effort to harvest ratio

4.4.2.1 Using the function annealing_find_harvest_ratio_mult()

4.4.2.2 Using the function calculate_hr_scale_values()

4.4.3 Estimation of fishing activity rates

4.4.3.1 Using the function annealing_find_gear_activity_mult_ecosystem_target()

4.4.3.2 Using the function annealing_find_gear_activity_mult_HR_target()

5 Sensitivity analysis

5.1 Background

5.2 Using the function Sensitivity_analysis_StrathE2E()

5.2.1 Using the function concatenate_raw_sensitivity_analysis_results()

5.2.2 Using the function process_sensitivity_analysis_results_offline()

5.2.3 Using the function plot_sensitivity_analysis_results()

6 Monte Carlo simulations of credible interval for model outputs

6.1 Background

6.2 Using the function Monte_Carlo_StrathE2E()

6.2.1 Using the function plot_Monte_Carlo_parameter_distributions()

6.2.2 Using the function plot_final_year_time_series_data_with_credible_intervals()

6.2.3 Using the function plot_final_year_migration_data_with_credible_intervals()

6.2.4 Using the function plot_final_year_trophic_data_with_credible_intervals()

6.2.5 Using the function plot_inshore_vs_offshore_anavmass_with_credible_intervals()

6.2.6 Using the function box_and_whisker_annual_plots_with_credible_intervals()

6.2.7 Using the function box_and_whisker_monthly_plots_with_credible_intervals()

References



Quick start

library("StrathE2E2")               # Load the package
model<-read_model("North_Sea", "1970-1999") # Read the input data for the 1970-1999 version of the North Sea model
results <- StrathE2E(model,nyears=5)        # Run the model for 5 years
plot_full_length_timeseries(model,results)  # Plot time series of the masses of the state variables


1 Package structure

The package contains 5 families of functions:


Table 1. Model management family of functions

Function name Description
list_models() List the models available within the package or in a user workspace
copy_model() Copy models between workspaces
read_model() Read a model setup from a given workspace - this is a core function in the package



Table 2. Basic model run family of functions

Function name Description
StrathE2E() Run the model for a prescribed number of years
extract_new_initial_cond_from_end_of_run() Create a new initial values file from the end-state of a model run
plot_full_length_timeseries() Plot time series of state variables for the full duration of a model run
plot_final_year() Plot whole domain data for the final year of a run
plot_final_year_LTL_inshore_vs_offshore() Plot inshore and offshore lower trophic level data for the final year
plot_final_year_HTL_inshore_vs_offshore() Plot inshore and offshore upper trophic level data for the final year
plot_sediment_habitats_final_year() Plot sediment nutrients and detritus for the final year
box_and_whisker_annual_plots() Plot comparison of observed annual data and derived model results
box_and_whisker_monthly_plots() Plot comparison of observed monthly data with derived model results
plot_time_series_annual_land_disc() Plot time series of annual landings and discards for a full run
plot_for_each_gear_catch_by_guild() Plot annual catch composition of each gear for the final year of a run
plot_for_each_guild_catch_by_gear() Plot distribution of catches across gear for each guild in the final year



Table 3. Model comparison family of functions

Function name Description
compare_two_runs_aam() Plot a tornado diagram comparing annual average mass data from two model runs
compare_two_runs_catch() Plot a tornado diagram comparing landings and discards from two model runs



Table 4. Parameter estimation family of functions

Function name Description
annealing_find_ecology_parameters() Find ecology model parameters maximising the likelihood of observed ecosystem data
annealing_find_harvest_ratio_mult() Find harvest ratio multipliers maximising the likelihood of observed ecosystem data
calculate_hr_scale_values Calculate fishing fleet model parameters which link effort to harvest ratios
annealing_find_gear_activity_mult_ecosystem_target() Find gear activity multipliers maximising the likelihood of observed ecosystem data
annealing_find_gear_activity_mult_HR_target() Find gear activity multipliers maximising the likelihood of known harvest ratios



Table 5. Sensitivity analysis family of functions

Function name Description
Sensitivity_analysis_StrathE2E() Run a Morris Method global sensitivity analysis
concatenate_raw_sensitivity_analysis_results() Merge raw analysis data from parallel runs into a single file
process_sensitivity_analysis_results_offline() Process raw data offline to create final outputs
plot_sensitivity_analysis_results() Plot sensitivity analysis results



Table 6. Monte Carlo analysis family of functions

Function name Description
Monte_Carlo_StrathE2E() Monte Carlo simulation to generate credible intervals of model outputs
plot_Monte_Carlo_parameter_distributions() Plot credible intervals of model parameters
plot_final_year_time_series_data_with_credible_intervals() Plot time series of state variables for the final year of a model run
plot_final_year_migration_data_with_credible_intervals() Plot migration fluxes between offshore and inshore zones
plot_final_year_trophic_data_with_credible_intervals() Plot annual mean trophic level and omnivory indices for model guilds
plot_inshore_vs_offshore_anavmass_with_credible_intervals() Plot inshore and offshore annual average mass densities for the final year
box_and_whisker_annual_plots_with_credible_intervals() Plot comparison of observed ecosystem data with equivalent model outputs
box_and_whisker_monthly_plots_with_credible_intervals() Plot comparison of observed nutrient and plankton data with model outputs



2 Getting started

2.1 Installing the package

Download the installation zip file for your operating system and install into your R version. Note that Strathe2E2 requires installation of the following additional packages which are available from any CRAN site:


To start a session, begin by loading the package:

library("StrathE2E2")


2.2 Folder structure for model input and output files

The data which define a model (parameters and driving data) are held in a specific folder structure for each implementation. The location of the North Sea demonstration model data within the folder structure of the R-package is shown in Figure 1.


Figure 1. Locations of the definition data folders for the North Sea demonstration model and its two variants in the structure of the R-package.


To view the installed models, use the list_models() function

library("StrathE2E2")
list_models()
List of models in system folder, with helpful commands to load them:

 Model: "North_Sea"
  Variant: "1970-1999"  model <- read_model("North_Sea", "1970-1999")
  Variant: "2003-2013"  model <- read_model("North_Sea", "2003-2013")


The North Sea demonstration model is read-only within the folder structure of the R-package. The basic functions of the package will operate perfectly well from these folders, but the more advanced optimisation functions require to write data back into the /Parameters sub-folders. To use these function it wil be necessary to create an editable copy of the demonstration models in a local work-space. Copies of the North Sea model can also be used as a template for development of new models. This can be done using using any file manager or the copy_model() function provided with the package:

library("StrathE2E2")
copy_model (" North_Sea ", " mymodels ", overwrite = TRUE )

The above example would the default NorthSea model and its two variants (“1970-1999” and “2003-2013”) provided within the package to the local folder “mymodels”, creating the folder if necessary and overwriting any existing copy if desired. The structure expected for any user-defined models is shown in Figure 2.


Figure 2. Organisation of model definition data folders in any user-defined work-space. Italicised folder names are free for user specification.


The model outputs R-list objects which are held in memory and available for user-analysis. In addition, many of the contents of the list objects are output to comma-separated-variable (CSV) files in a folder structure in the current user workspace (Figure 3). If a results folder does not exists the package will auto-create one:


Figure 3. Organisation of model results folders.



2.3 Running one of the North Sea model versions

The read_model() function is the foundation for all StrathE2E2 model runs. This function loads all the data required to configure a model into an R-list object. The function is pointed to each of the required input files by the file MODEL_SETUP.csv which resides in the /ModelName/VariantName folder for the relevant model. MODEL_SETUP.csv points to specific files in the /Parameters, /Target_data and /Driving_data subfolders. The read_model() function has 6 arguments (Table 7).


Table 7. Arguments of the read_model() function

Argument Description
model.name Name of model to read (no default)
model.variant Variant of the model to be read (no default)
model.ident Text appended to output csv file names (e.g. OFFSHORE_model_annualresults-TEXT.csv instead of just OFFSHORE_model_annualresults.csv) (default=“base”)
model.subdir Sub directory of the main results folder for storing results (default = a folder which will be auto-created using the model name)
user.path Path to users top level model folder from where the model setup will be loaded (default = load from the package folder extdata/Models)
quiet Set to FALSE to see on-screen information on where model is loaded from and what files are read (default=TRUE)


The default user.path for read_model() is to load one of the variants of the North Sea model supplied with the package. The North Sea models are configured so that the initial conditions which are loaded for a default run launch the system in a stationary state - that is, the model produces repeating annual cycles of output given repeating annual cycles of the time-dependent driving data (e.g. temperature, hydrodynamics etc).


library("StrathE2E2")
model <- read_model("North_Sea", "1970-1999")

The object model is a list containing all of the input data and parameters gathered from the CSV files in the folder structure:

str(model,max.level=2)                    # View the top 2 levels of input list object
List of 2
 $ setup:List of 7
  ..$ read.only    : logi TRUE
  ..$ model.name   : chr "North_Sea"
  ..$ model.variant: chr "1970-1999"
  ..$ model.ident  : chr "base"
  ..$ model.subdir : chr ""
  ..$ model.path   : chr "/tmp/RtmpE6845k/Rinst69163ac8ac79/StrathE2E2/extdata/Models/North_Sea/1970-1999"
  ..$ resultsdir   : chr "results/North_Sea/1970-1999/"
 $ data :List of 8
  ..$ fixed.parameters   :List of 51
  ..$ fitted.parameters  :List of 171
  ..$ physical.parameters:List of 63
  ..$ physics.drivers    :'data.frame': 12 obs. of  23 variables:
  ..$ chemistry.drivers  :'data.frame': 12 obs. of  22 variables:
  ..$ biological.events  :'data.frame': 26 obs. of  2 variables:
  ..$ fleet.model        :List of 19
  ..$ initial.state      :List of 403


Full documentation of the input CSV files and the contents of the list object produced by read_model() is provided in the Technical Manual.


The function StrathE2E() runs the model in simple deterministic mode, and generates another list object containing all of the outputs. In addition a range of derived outputs for the final year of the run are exported as CSV files to a /results folder in the users local workspace. The StrathE2E() function has 4 arguments (Table 8).


Table 8. Arguments of the StrathE2E() function

Argument Description
model R-list object defining the model configuration compiled by the read_model() function
nyears Number of years (integer) to run the model (default=20)
quiet Set to TRUE to quieten status outputs during the model run (default=TRUE)
csv.output Set to FALSE to disable writing of CSV output files (default=TRUE)


results <- StrathE2E(model, nyears=5)       # Run the model for 5 years
str(results,max.level=1)                    # View the high-level contents of the output list object
List of 7
 $ build               :List of 4
 $ output              :'data.frame':   1801 obs. of  404 variables:
 $ aggregates          :List of 130
 $ fleet.output        :List of 7
 $ total.annual.catch  :List of 2
 $ annual.catch.by.gear:List of 2
 $ final.year.outputs  :List of 27


Full documentation of the output CSV files and the contents of the list object produced by StrathE2E() is provided in the Technical Manual.

2.3.1 Setting initial conditions for the state variables

The basic model is deterministic, which means that the stationary state (i.e. repeating annual cycles of state variable with repeating annual cycles of driving data) is independent of the initial values of the state variables (provided that these are all > 0). However, as the initial conditions become further away that the values at 00:00 on 1st January of a stationary year, the longer the model will take to reach equilibrium.


A useful facility to reduce the run-time between start and stationary state is to ‘hot-start’ the model with initial conditions extrcated from the end of a prior run. The package includes a function extract_new_initial_cond_from_end_of_run() to extract the end state of a model and format the data as required for initial conditions of a subsequent run. The default setting is that the extracted data are written back to the /ModelName/VariantName/Parameters folder of the original model setup with a file name having the text identifier model.ident as set in the read_model() function. However, in the event the this is attempted for one of the two variants of the North Sea model supplied with the package then the new initial conditons file wil be directed to the current /results folder, since the internal folders in the package are read-only.


The internal North Sea models are both supplied with initial conditions which are consistent with a stationary state, so they should both show repeating annual cycles of output from time = 0, unless the parameters or driving conditions are altered to create some new environmental scenario.

model<-read_model("North_Sea", "2003-2013")              # Read the 2003-2013 internal model
results <- StrathE2E(model, nyears=5)                    # Run the model for 5 years
extract_new_initial_cond_from_end_of_run(model,results)  # Extract the model endstate as new initial conditions file
# This should revert to the results folder since the internal moldel folder is read-only
#
#
# 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")
results <- StrathE2E(model, nyears=5)                    # Run the model for 5 years
extract_new_initial_cond_from_end_of_run(model,results)  # Extract the model endstate as new initial conditions file
# This should write to the user model /Parameters folder)


2.3.2 Plotting functions for visualizing model output

There are a number of plotting functions available to view the outputs extracted from the results list object (Table 9).


Table 9. Plotting functions for visualising outputs from StrathE2E() model runs.

Function name Description
plot_full_length_timeseries() Time series of state variables for the full duration of a model run
plot_final_year() Whole domian data for the final year of a run
plot_final_year_LTL_inshore_vs_offshore() Inshore and offshore lower trophic level data for the final year
plot_final_year_HTL_inshore_vs_offshore() Inshore and offshore upper trophic level data for the final year
plot_sediment_habitats_final_year() Sediment nutrients and detritus for the final year
box_and_whisker_annual_plots() Comparison of observed annual data and derived model results
box_and_whisker_monthly_plots() Comparison of observed monthly data with derived model results
plot_time_series_annual_land_disc() Time series of annual landings and discards for a full run
plot_for_each_gear_catch_by_guild() Annual catch composition of each gear for the final year of a run
plot_for_each_guild_catch_by_gear() Distribution of catches across gear for each guild in the final year
compare_two_runs_AAM() Tornado diagram to compare annual average mass results from two runs


The most basic is a time-series plot of the state variables aggregated over the whole model domain. This is not intended as a publication quality output, rather for diagnostic checking of model runs, e.g. to assess whether a run has attained a stationary state of repeating annual cycles of output. In the case of the example run, we expect a stationary state since the model was launched with initial values of the state variable conditioned to represent a stationary state.


plot_full_length_timeseries(model, results)

Figure 4. Plot of time series for full model run, units mMN in the model domain as a whole (1m-2 sea surface).


All of the plotting functions provide with the package produce output to a screen window. To divert output to a graphic file wrap the plotting function call inside graphics device open and close statememts as follows:

pdf("plot.pdf",width=7,height=6)                    # or jpeg("plot.jpg"), png("plot.PNG")
plot_full_length_timeseries(model, results)
dev.off()



Final year plots of ecology model outputs:


plot_final_year(model, results)

Figure 5. Plot of final year time series aggregated over the the whole model domain.



plot_final_year_LTL_inshore_vs_offshore(model, results)

Figure 6. Plot inshore vs offshore model data for low trophic levels.



plot_final_year_HTL_inshore_vs_offshore(model, results)

Figure 7. Plot inshore vs offshore model data for high trophic levels.



plot_sediment_habitats_final_year(model, results)

Figure 8. Plot of porewater nutrients and detritus concentrations in sedient habitats during the final year.



box_and_whisker_annual_plots(model, results)

Figure 9. Plot comparing a range of observed annual data on the state of the whole ecosystem (black box and whiskers (quartiles)) with equivalent measures derived from the final year of model output (red symbols).



box_and_whisker_monthly_plots(model, results)

Figure 10. Plot comparing observed monthly data on nutrients and plankton in the whole ecosystem (black box and whiskers (quartiles)) with equivalent measures derived from the final year of model output (black symbols).



Final year plots of fishing fleet model outputs:


plot_time_series_annual_land_disc(model, results)

Figure 11. Plot of the time series of annual integrated catches of each guild broken down by landings (green: offshore, blue: inshore) and discards (black: offshore, grey: inshore).


plot_for_each_gear_catch_by_guild(model, results)

Figure 12. Plot of the final year annual integrated catch composition of each gear broken down by landings (green: offshore, blue: inshore) and discards (black: offshore, grey: inshore). PF=planktivorous fish, DFq=demersal fish (quota limited), DFnq= demersal fish (non quota), MF= migratory fish, Bsd=Benthos (susp/deposit), Bcs=Benthos (carn/scav), CZ=Carn zooplankton, BD=birds, PIN=pinnipeds, CT=cetaceans, MP=macrophytes.


plot_for_each_guild_catch_by_gear(model, results)

Figure 13. Plot of the final year distribution of annual integrated catch of each guild across gears broken down by landings (green: offshore, blue: inshore) and discards (black: offshore, grey: inshore). PTS=pelagic trawl and seine, SST=sandeel and sprat tarwl, LLm=long line mackerel, BTf=beam trawl fish, DS=demersal seine, OT=otter trawl, LLd=long lines and gill nets demersal, BTs=beam trawl shrimp, NT=Nephrops trawl, CR=creels, MD=mollusc dredge, Wh=whalers.



3 More advanced use of the model

3.1 Writing your own code to create model scenarios

Typical use of the model might involve


Users have two options for configuring such experiments


The scope for developing fishing and/or environmemtal scenarios by coding to modify a default model object loaded by read_model() is limitless, but requires and understanding of the structure and content of the list object produced by the read_model() function. Use the str() function in R to explore the list and its sub-components, and consult the Technical Manual.


model<-read_model("North_Sea", "2003-2013")
str(model,max.level=2)                    # View the top 2 levels of input list object
List of 2
 $ setup:List of 7
  ..$ read.only    : logi TRUE
  ..$ model.name   : chr "North_Sea"
  ..$ model.variant: chr "2003-2013"
  ..$ model.ident  : chr "base"
  ..$ model.subdir : chr ""
  ..$ model.path   : chr "/tmp/RtmpE6845k/Rinst69163ac8ac79/StrathE2E2/extdata/Models/North_Sea/2003-2013"
  ..$ resultsdir   : chr "results/North_Sea/2003-2013/"
 $ data :List of 8
  ..$ fixed.parameters   :List of 51
  ..$ fitted.parameters  :List of 171
  ..$ physical.parameters:List of 63
  ..$ physics.drivers    :'data.frame': 12 obs. of  23 variables:
  ..$ chemistry.drivers  :'data.frame': 12 obs. of  22 variables:
  ..$ biological.events  :'data.frame': 26 obs. of  2 variables:
  ..$ fleet.model        :List of 19
  ..$ initial.state      :List of 403


To mine deeper into the model object, for example, to show the fleet model inputs:

model<-read_model("North_Sea", "2003-2013")
model$data$fleet.model
$gear_labels
 [1] Pelagic_Trawl+Seine                   Sandeel+sprat_trawl(Otter30-70mm+TR3)
 [3] Longline_mackerel                     Beam_Trawl_BT1+BT2                   
 [5] Demersal_Seine                        Demersal_Otter_Trawl_TR1             
 [7] Gill_Nets+Longline_demersal           Beam_Trawl_shrimp                    
 [9] Nephrops_Trawl_TR2                    Creels                               
[11] Mollusc_Dredge                        Whaler                               
12 Levels: Beam_Trawl_BT1+BT2 Beam_Trawl_shrimp ... Whaler

$gear_codes
 [1] PTS SST LLm BTf DS  OT  LLd BTs NT  CR  MD  Wh 
Levels: BTf BTs CR DS LLd LLm MD NT OT PTS SST Wh

$gear_activity
 [1] 2.17e-06 4.23e-06 1.68e-06 1.15e-05 1.72e-08 2.16e-05 7.92e-06 1.27e-05
 [9] 1.72e-05 2.40e-05 3.11e-06 1.98e-08

$gear_group_rel_power
        pelagic    demersal    migratory     filtben      carnben  carnzoo
1  1.932115e+03  0.89347662 1.077415e+03 0.000000000  0.002671044 0.000000
2  1.013869e+03  2.12168553 3.843438e+01 0.000884645  0.767630355 0.000000
3  1.218981e-02  0.04958782 7.381184e+00 0.000049300  0.025221014 0.000000
4  1.209108e-03 80.89547724 1.613851e-01 0.001074415  0.389642624 0.000000
5  0.000000e+00 10.64039678 1.094104e+01 0.000000000  0.015250346 5.090975
6  8.489664e-01 77.63191616 9.424984e+00 0.001409053  0.699460502 1.496856
7  2.615744e-01  8.66490093 5.601849e-02 0.000892911  0.069121787 0.000000
8  2.478026e-01  5.17516220 2.046550e-02 0.000009520 27.908549830 0.000000
9  6.521403e-03 16.06754050 1.646958e-01 0.000232275  5.723924492 0.137040
10 3.902940e-04  0.02007798 3.983892e-02 0.001443302  1.676332703 0.000000
11 1.231062e-01  0.04814089 7.589362e-03 5.800854733  0.005832199 0.000000
12 0.000000e+00  0.00000000 0.000000e+00 0.000000000  0.000000000 0.000000
       bird     seal        ceta kelp
1  0.175037 0.000000   0.3514017    0
2  0.000000 0.000000   0.0000000    0
3  0.085223 0.000000   0.0000000    0
4  0.000000 0.000000   0.0000000    0
5  0.000000 0.000000   0.0000000    0
6  0.000000 0.000000   0.0000000    0
7  0.010659 0.749952   1.8122620    0
8  0.000000 0.000000   0.0000000    0
9  0.000000 0.000000   0.0000000    0
10 0.000000 0.000000   0.0326668    0
11 0.000000 0.000000   0.0000000    0
12 0.000000 0.000000 127.4624000    0

$gear_group_discard
       pelagic    demersal   migratory     filtben    carnben carnzoo bird seal
1  0.002940862 0.111955218 0.052261365 0.000000000 0.00000000       0    1    1
2  0.000117639 0.537722720 0.008721464 0.000409807 0.17253984       0    1    1
3  0.000000000 0.004905382 0.000000000 0.000000000 0.00002210       0    1    1
4  0.000000000 0.544527877 0.670642427 0.013789586 0.14986397       0    1    1
5  0.000000000 0.000000000 0.000000000 0.000000000 0.00000000       0    1    1
6  0.125586035 0.473864510 0.769790851 0.021689801 0.31255895       0    1    1
7  0.000013000 0.027499596 0.231375133 0.000488107 0.49755816       0    1    1
8  0.422012971 0.970253908 0.365643786 0.000000000 0.57604018       0    1    1
9  0.379740296 0.684241519 0.439291664 0.000000000 0.06020828       0    1    1
10 0.056057846 0.008395374 0.000584674 0.000000000 0.00000177       0    1    1
11 0.000000000 0.476891130 0.000000000 0.005634317 0.00000000       0    1    1
12 0.000000000 0.000000000 0.000000000 0.000000000 0.00000000       0    0    0
   ceta kelp
1     1    0
2     1    0
3     1    0
4     1    0
5     1    0
6     1    0
7     1    0
8     1    0
9     1    0
10    1    0
11    1    0
12    0    0

$gear_group_gutting
   pelagic demersal migratory filtben carnben carnzoo bird seal ceta kelp
1        0      0.0         0       0     0.0       0    0    0    0    0
2        0      0.0         0       0     0.0       0    0    0    0    0
3        0      0.0         0       0     0.0       0    0    0    0    0
4        0      0.5         0       0     0.0       0    0    0    0    0
5        0      0.5         0       0     0.0       0    0    0    0    0
6        0      0.5         0       0     0.0       0    0    0    0    0
7        0      0.0         0       0     0.0       0    0    0    0    0
8        0      0.0         0       0     0.0       0    0    0    0    0
9        0      0.0         0       0     0.8       0    0    0    0    0
10       0      0.0         0       0     0.0       0    0    0    0    0
11       0      0.0         0       0     0.0       0    0    0    0    0
12       0      0.0         0       0     0.0       0    0    0    0    0

$gear_ploughing_rate
 [1]  0.0  8.8  0.0 54.1 22.4 17.1  0.0 13.5 78.9  0.0 22.4  0.0

$gear_habitat_activity
            s0          s1         s2          s3          d0         d1
1  0.002306225 0.022318976 0.18565659 0.056603194 0.004080129 0.36177475
2  0.001633992 0.041936670 0.18845895 0.099262077 0.003321046 0.22028780
3  0.002585154 0.019179084 0.13339978 0.004641906 0.002198504 0.04811572
4  0.000000000 0.010312589 0.55581385 0.051585249 0.000000000 0.15791381
5  0.010771788 0.041737583 0.24808350 0.039262834 0.015696502 0.23161262
6  0.003831778 0.005541356 0.07911069 0.086768094 0.009586108 0.30495406
7  0.017572358 0.011517676 0.38187595 0.306710860 0.009678597 0.05754839
8  0.000000000 0.041352126 0.86793552 0.061227227 0.000000000 0.01897104
9  0.000000000 0.113741270 0.00000000 0.000000000 0.000000000 0.88625873
10 0.014753902 0.048364874 0.18995648 0.166975262 0.023811479 0.05029062
11 0.000000000 0.011387932 0.25645298 0.092935228 0.000000000 0.05084907
12 0.000000000 0.000000000 0.00000000 0.000000000 0.000000000 0.20000000
           d2          d3
1  0.33238459 0.034875556
2  0.42221147 0.022887992
3  0.78622360 0.003656248
4  0.21831786 0.006056644
5  0.36953715 0.043298018
6  0.47351519 0.036692729
7  0.20548174 0.009614425
8  0.01021216 0.000301922
9  0.00000000 0.000000000
10 0.42136843 0.084478943
11 0.49148021 0.096894590
12 0.80000000 0.000000000

$HRscale_vector
PF_HR_scale DF_HR_scale MF_HR_scale SB_HR_scale CB_HR_Scale CZ_HR_Scale 
 0.06674195  0.07595488  0.36735046 12.34854140  0.64383594 15.88002233 
BD_HR_Scale SL_HR_Scale CT_HR_Scale KP_HR_Scale 
 2.53000000  2.69772000  4.50450000  1.00000000 

$HRscale_vector_multiplier
 [1] 1 1 1 1 1 1 1 1 1 1

$offal_prop_live_weight
[1] 0.1

$gear_mult
 [1] 1 1 1 1 1 1 1 1 1 1 1 1

$quota_nonquota_parms_vector
[1] 0.16 0.07 0.67 0.02 0.40 0.02

$DFsize_SWITCH
[1] 0

$DFdiscard_SWITCH
[1] 1

$plough_thickness
[1] 0.05

$plough_depth_vector
[1] 0.00000000 0.43160013 0.05820558 0.04545455 0.00000000 0.50000000 0.07243667
[8] 0.04545455

$BSmort_gear
[1] 0.2

$BCmort_gear
[1] 0.2


Below are two examples of code to configure and run scenario cases of the the 2003-2013 North Sea model provided with the package. The first example runs 2003-2013 North Sea model as a baseline, and then adds 2 deg-C to the temperatures in all spatial zones and reruns the model. The second example iterates through seven levels of demersal fish harvest ratio ranging from 0 to 3-times the value in the 2003-2013 model (in steps of 0.5-times). Note that the changes in harvest ratio are not accompanied by any changes in fishing gear activity.


NOTE - The model is run for only 10 years in Example 1 to create the output shown here - in an actual working example it would be recommended to run for at least 40 years in each case to ensure that the model is close to a stationary state by the end of each run.


Model scenario Example 1

# Example of code to run a baseline case of the North Sea model with 2003-2013 conditions, and then edit the
# model list object to create a scenario run with the temperature in all zones increased by 2 deg-C
#--------------------------------------------------------
# Read the embedded North Sea 2003-2013 model and assign an identifier for the results
baseTemp_model<-read_model("North_Sea", "2003-2013",model.ident="baseTemp")
# Run the model for 10 years and save the results to a named list object
baseTemp_results<-StrathE2E(baseTemp_model,nyears=10)
# Visualise the output from the run (should show a repeating annual cycle with no trend)
plot_full_length_timeseries(baseTemp_model,baseTemp_results)

Figure 14. Baseline model run for Example 1 - 2003-2013 conditions in the North Sea

T_rise<-2    # temperature increase to add to all temperatures in the model drivers
# copy the baseline model list object to a new model list
baseTemp_plusTC_model<-baseTemp_model
# add temperature increase to upper layer offshore temperatures
baseTemp_plusTC_model$data$physics.drivers$so_temp <- baseTemp_model$data$physics.drivers$so_temp+T_rise
# add temperature increase to inshore temperatures
baseTemp_plusTC_model$data$physics.drivers$si_temp <- baseTemp_model$data$physics.drivers$si_temp+T_rise
# add temperature increase to lower layer offshore temperatures
baseTemp_plusTC_model$data$physics.drivers$d_temp  <- baseTemp_model$data$physics.drivers$d_temp+T_rise
# Assign a unique identifier for the .csv outputs
baseTemp_plusTC_model$setup$model.ident <- "baseTemp_plusTC"
# Run the model for 10 years and save the results to a named list object
baseTemp_plusTC_results<-StrathE2E(baseTemp_plusTC_model,nyears=10)
# Visualise the output from the run (should show trends in outputs due to change in T)
plot_full_length_timeseries(baseTemp_plusTC_model,baseTemp_plusTC_results)

Figure 15. Scenario model run for Example 1 - 2003-2013 plus 2oC conditions in the North Sea.


Model scenario Example 2

# Example of code to loop through a set of seven levels of demersal fish harvest ratio ranging from 0 to 3-times
# the baseline value for the 2003-2013 North Sea model. The .csv outputs for each level are saved to unique
# filenames but the results list-object is discarded. The baseline case is the third level (HScale=1). Each level
# is run for 40 years. 
#--------------------------------------------------------
model<-read_model("North_Sea", "2003-2013")         # Read the embedded North Sea 2003-2013 model
for(i in 1:7) {                                     # Start loop through seven model scenarios
  HScale <- (i-1)*0.5                               # HScale becomes 0 to 3 in steps of 0.5
      # Assign a unique identifier for each set of .csv outputs
  model$setup$model.ident <- paste("Dem_HR_scale_",HScale,sep="")
      # Set the demersal fish harvest ratio multipler to HScale
  model$data$fleet.model$HRscale_vector_multiplier[2] <- HScale
  results<-StrathE2E(model,nyears=40)            # Run the model, save the .csv results, overwrite any previous list-object
  print(paste("Harvest Ratio scaling = ",HScale,sep="")) # Print a screen message to monitor progress
  print("-----------------------------------")       # Print a screen message to monitor progress
  plot_full_length_timeseries(model,results)         # Visualise the output from each run
}                            # End loop through scenarios




3.2 Comparing scenario model results with a baseline model.

Two functions are provided to visualize comparisons of scenario and baseline versions of a model using tornado plots. The functions compare_two_runs_aam() and compare_two_runs_catch() compare annual average mass results, and landings and discards results, from the final years of a scenario run and a baseline run.


Both of the function compare_two_runs_aam() and compare_two_runs_catch() have the same arguments:

Argument Description
model1 R-list model object for the first (baseline) model run (set to NA if from.csv1=FALSE (default))
results1 R-list results object for the first (baseline) model run (set to NA if from.csv1=TRUE)
from.csv1 Flag to determine whether baseline data are read from a previously saved csv file of from a results object held in memory (default = FALSE)
model2 R-list Model object for the second (scenario) model run (set to NA if from.csv2=FALSE (default))
results2 R-list results object for the second (scenario) model run (set to NA if from.csv1=TRUE)
from.csv2 Flag to determine whether scenario data are read from a previously saved csv file of from a results object held in memory (default = FALSE)
log.pc Flag to determine whether data are plotted on a log10 scale (value = “LG”) or a percentage scale (value=“PC” (default))
zone Value = “O” for offshore, “I” for inshore, or “W” for whole model domain (all upper case). Default = “W”
bpmin Axis minimum for plot - i.e. the maximum NEGATIVE value of (scenario-baseline). Default = -50, given log.pc=“PC” (percentage differences). Needs to be reset to e.g. -0.3 if log.pc=“LG” (log scale)
bpmax Axis maximum for plot - i.e. the maximum POSITIVE value of (scenario-baseline). Default = +50, given log.pc=“PC” (percentage differences). Needs to be reset to e.g. +0.3 if log.pc=“LG” (log scale)
maintitle A descriptive text field (in quotes) to be added above the plot. Default=""


In addition to plotting a tornado graph, both functions return a list object containing the data plotted in the graph as both log10 units (column “LG”) and percentage units (column “PC”).


Function compare_two_runs_aam()


base_model<-read_model("North_Sea", "1970-1999", model.ident="baseline")  #Read the embedded North Sea 1970-1999 model
base_results <- StrathE2E(base_model,nyears=5)                            # Run the baseline model
# Create a scenario run from the baseline:
scen1_model   <- base_model              # Copy the existing baseline configuration into a new model object
# Edit the model object...
scen1_model$setup$model.ident <- "scenario1"
scen1_model$data$fleet.model$gear_mult[4] <- 0.5        # Gear 4 (Beam_Trawl_BT1+BT2) activity rate rescaled to 0.5*baseline
scen1_results <- StrathE2E(scen1_model,nyears=30)       # Run for 30 years to allow the new model to reach a stationary state
#
# Compare the scenario with the baseline
mdiff_results <- compare_two_runs_aam(model1=NA,results1=base_results,from.csv1=FALSE,
                              model2=NA,results2=scen1_results,from.csv2=FALSE,
                                  log.pc="PC", zone="W",
                                  bpmin=(-50),bpmax=(+50),
                                      maintitle="Beam Trawl activity reduced by half")
[1] "Using baseline data held in memory from an existing model run"
[1] "Using scenario data held in memory from an existing model run"

Figure 16. Tornado plot comparing whole domain annual average masses of state variables in the North Sea 1970-1999 model (as a baseline) with a scenario in which Beam Trawl activity rate is reduced by half. Red bars to the left indicate values in the scenario run are less than in the baseline. Green bars to the right indicate that values in the scenario run are greater than in the baseline.

# View the list object containing the proportional difference data shown in the plot
# (column LG = log10 values, column PC = percentage values).
# First dataframe in the list = water column components, second = seabed components.  
mdiff_results 
$changewater
                                           LG          PC
Suspended bacteria & detritus    0.0035847751   0.8288410
Water column ammonia             0.0021381633   0.4935442
Water column nitrate            -0.0013266442  -0.3050050
Macrophytes                     -0.0006219224  -0.1431004
Phytoplankton                    0.0043162912   0.9988180
Benthic susp/dep feeder larvae  -0.0025401236  -0.5831779
Omnivorous zooplankton          -0.0090004803  -2.0511098
Benthic carn/scav feeder larvae  0.0509937759  12.4588857
Carnivorous zooplankton          0.0314686337   7.5148947
Plantiv. fish adults+larvae     -0.0520709431 -11.2988895
Migratory fish                  -0.0006647157  -0.1529394
Demersal fish adults+larvae      0.1320809396  35.5442003
Birds                            0.0191548559   4.5092800
Pinnipeds                        0.1113877302  29.2372565
Cetaceans                       -0.0121200724  -2.7521681

$changeseabed
                                        LG           PC
Fishery discards & offal      3.046158e-02  7.265874324
Corpses                      -2.988307e-03 -0.685721327
Sediment bacteria & detritus  1.208522e-05  0.002782764
Macrophyte debris            -8.389075e-04 -0.192979135
Porewater ammonia             3.014600e-03  0.696552036
Porewater nitrate            -1.330401e-03 -0.305867510
Benthic susp/dep feeders     -1.502469e-04 -0.034589646
Benthic carn/scav feeders     3.973429e-02  9.580756275
#


Function compare_two_runs_catch()


# For the previous example, compare the scenario landings and discards with the baseline
cdiff_results <- compare_two_runs_catch(model1=NA,results1=base_results,from.csv1=FALSE,
                            model2=NA,results2=scen1_results,from.csv2=FALSE,
                                log.pc="PC", zone="W",
                                bpmin=(-30),bpmax=(+60),
                                maintitle="Beam Trawl activity reduced by half")
[1] "Using baseline data held in memory from an existing model run"
[1] "Using scenario data held in memory from an existing model run"

Figure 17. Tornado plot comparing whole domain annual landings and discards in the North Sea 1970-1999 model (as a baseline) with a scenario in which Beam Trawl activity rate is reduced by half. Upper panel: landings data, red bars to the left indicate values in the scenario run are less than in the baseline. Green bars to the right indicate that values in the scenario run are greater than in the baseline. Lower panel: discards data, grey bars to the left indicate values in the scenario run are less than in the baseline. Black bars to the right indicate that values in the scenario run are greater than in the baseline.


# View the list object containing the proportional difference data shown in the plot
# (column LG = log10 values, column PC = percentage values).
# First dataframe in the list = landings, second = discards. 
cdiff_results 
$changeland
                                         LG          PC
Macrophytes                              NA          NA
Susp/dep feeding benthos       0.0004895919   0.1127963
Carn/scav feeding benthos      0.0476154012  11.5874623
Pelagic invertebrates          0.1664870390  46.7192300
Planktivorous fish            -0.0528600736 -11.4599167
Migratory fish                -0.0007717833  -0.1775519
Non-quota demersal fish        0.0082816042   1.9252075
Quota-limited demersal fish    0.0828534055  21.0189569
Birds                                    NA          NA
Pinnipeds                                NA          NA
LANDINGS            Cetaceans -0.0283776478  -6.3252911

$changedisc
                                         LG           PC
Macrophytes                              NA           NA
Susp/dep feeding benthos      -0.0003722283  -0.08567202
Carn/scav feeding benthos      0.0857453142  21.82749496
Pelagic invertebrates                    NA           NA
Planktivorous fish            -0.0526922526 -11.42569620
Migratory fish                -0.0012812123  -0.29457530
Non-quota demersal fish       -0.0458651179 -10.02230114
Quota-limited demersal fish    0.0468438188  11.38938825
Birds                          0.0254044849   6.02407322
Pinnipeds                      0.1455096330  39.80079239
DISCARDS            Cetaceans -0.0070725978  -1.61533704
#


3.3 Writing your own code to work with the model output

The first step to working with the model outputs is understanding their structure. This is described in the following section, but more details are available in a Technical Manual.


The outputs from running the basic model are an R list object (results in the examples above) and a set of CSV files. The list object contains 7 primary data structures. The CSV file outputs are generated in the /results folder, either in the user home workspace by default, or in a workspace defined by the arguments of the read_model() function. Each csv file has a generic file name plus an alpha-numeric identifier (model.ident) assigned by the user as an argument of the read_model() function (default = “base”). In the following descriptions this is represented by “TEXT”. The CSV files replicate elements of the data contained in the R list object generated by StrathE2E(). Their purpose is to preserve the most useful outputs for future use e.g. in comparisons of baseline and scenario model runs.


An abbreviated view of the contents of the results list object is shown below.

model<-read_model("North_Sea", "2003-2013")
results <- StrathE2E(model, nyears=5)       # Run the model for 5 years
str(results,max.level=1)                    # View the high-level contents of the output list object
List of 7
 $ build               :List of 4
 $ output              :'data.frame':   1801 obs. of  404 variables:
 $ aggregates          :List of 130
 $ fleet.output        :List of 7
 $ total.annual.catch  :List of 2
 $ annual.catch.by.gear:List of 2
 $ final.year.outputs  :List of 27



A brief description of the contents of each of the elements of the results object, and correspondence with csv output files is shown below. Full details are provided in the Technical Manual.


The object build is a list containing a copy of the model input data imported from the model object created by read_model(). This is included in the results object since some of these data are required for post-processing of results, e.g. to convert state variable mass to area or volume densities (see examples later):

str(results$build,max.level=1) 
List of 4
 $ model.parameters: Named num [1:585] 30 50.04 24.16 1 0.25 ...
  ..- attr(*, "names")= chr [1:585] "thik_so" "thik_d" "thik_si" "thik_b" ...
 $ run             :List of 7
 $ drivers         :List of 51
 $ forcings        :List of 53


The object output is a dataframe containing the raw daily-interval output from the ODE solving computations on the masses of all of the state varaiables. This dataframe is the raw material for all subsequent post-processing of the model results. The example below views just the top and bottom few rows, and the first 6 columns of the dataframe. The prefix x_ in front of the detritus and other terms signifies a sediment property, with the extension _s1, _s2, or _s3 indicating inshore sediment habitat, and _d1, _d2, or _d3 indicating offshore sediment habitat. For water column components the extension _so, _d, and _si indicate offshore upper and lower, and inshore zones/layers.

head(results$output[,1:6])
  time detritus_so detritus_d x_detritus_s1 x_detritus_s2 x_detritus_s3
1    0    5.214787   9.611170     1.0170944      16.91283      4.644934
2    1    5.146009   9.453170     1.0091077      16.76698      4.607493
3    2    5.073661   9.315542     1.0011553      16.62177      4.570188
4    3    5.003884   9.190763     0.9932390      16.47727      4.533032
5    4    4.938369   9.076087     0.9853605      16.33351      4.496037
6    5    4.877430   8.970285     0.9775215      16.19053      4.459217
tail(results$output[,1:6])
     time detritus_so detritus_d x_detritus_s1 x_detritus_s2 x_detritus_s3
1796 1795    5.223114   9.605005      1.062605      17.74735      4.853299
1797 1796    5.219127   9.602296      1.053357      17.57749      4.810998
1798 1797    5.216378   9.601691      1.044181      17.40910      4.769007
1799 1798    5.214788   9.603051      1.035079      17.24219      4.727331
1800 1799    5.214280   9.606250      1.026051      17.07678      4.685976
1801 1800    5.214785   9.611167      1.017097      16.91288      4.644946


The object aggregates is a list containing vectors of 124 derived model variable which are aggregations of selected columns in the raw model output in the output object. Aggregations are created by summing, for example, across inshore and offshore values of the same food web component to produce a whole-domain value. Each numeric vector has the same length as the number of rows in dataframe results$output, in other words a value for each daily output step. In addition, the aggregates list contains six single numeric values of zonal layer thicknesses and sediment porosities needed to convert aggregated masses into mass densities (m-2 or m-3).


The example below views the names of just the first few variables in the aggregates list, extracts two variables and makes plot of their time-series. More details are provided in the Technical Manual.

# List the names of the first 40 vectors in the results$aggregates list:
names(results$aggregates[1:40])
 [1] "totalN"         "totalN_o"       "totalN_i"       "x_detritus"    
 [5] "x_detritus_o"   "x_detritus_i"   "corpse"         "corpse_o"      
 [9] "corpse_i"       "x_ammonia"      "x_ammonia_o"    "x_ammonia_i"   
[13] "x_nitrate"      "x_nitrate_o"    "x_nitrate_i"    "s_detritus"    
[17] "s_ammonia"      "s_nitrate"      "s_phyt"         "benthslar"     
[21] "benthclar"      "benths"         "benthc"         "discard"       
[25] "herb"           "carn"           "fishp"          "fishd"         
[29] "fishm"          "bird"           "seal"           "ceta"          
[33] "fishplar"       "fishdlar"       "PNP"            "netpprod"      
[37] "fluxwcamm_phyt" "fluxwcnit_phyt" "phytgrossprod"  "herbgrossprod" 
# Plot the time series of the sedient nitrate mass in the inshore and offshore zones
# i.e. aggregated across the sediment types in each zone.
# Note that this is the mass not the porewater concentration so uncorrected for
# zonal area or sediment porosity or layer thickness.
plot(seq(1,nrow(results$output)), results$aggregates$x_nitrate_o, type="l",col="black",
     ylim=( c( 0,(1.5*max(results$aggregates$x_nitrate_o)) ) ),
     xlab="Days", ylab="Sediment nitrate mass (mMN)")
lines(seq(1,nrow(results$output)), results$aggregates$x_nitrate_i, type="l",col="red")
legend("topleft",  bg="transparent", c("offshore","inshore"), lty=c(1,1),col=c("black","red"))

Figure 18. Plot of the time series of sediment nitrate mass aggregated over the offshore and inshore zones.


The object fleet.output is a list of dataframes containing outputs from the fleet model which are either piped into the ecology model, or saved internally for use in post-processing the model outputrs - in particular for disaggregating the total catch of each good web guild into the fractions attributable to each fishing gear. This post processing is carried out automatically by the StrathE2E() function (see below) so under most circumatances the user would not require access to these internal data:

str(results$fleet.output,max.level=1)
List of 7
 $ fleet_vector                              : Named num [1:250] 0.000681 0.00053 0.000309 0.000204 0.001057 ...
  ..- attr(*, "names")= chr [1:250] "F_inshore_pelagic" "F_offshore_pelagic" "F_inshore_demersal" "F_offshore_demersal" ...
 $ offshore_gear_group_prop_effort           :'data.frame': 12 obs. of  10 variables:
 $ inshore_gear_group_prop_effort            :'data.frame': 12 obs. of  10 variables:
 $ offshore_gear_to_region_discard_rate_ratio:'data.frame': 12 obs. of  10 variables:
 $ inshore_gear_to_region_discard_rate_ratio :'data.frame': 12 obs. of  10 variables:
 $ offshore_gear_group_props                 :'data.frame': 5 obs. of  241 variables:
 $ inshore_gear_group_props                  :'data.frame': 5 obs. of  241 variables:


The object total.annual.catch is a list comprising two dataframes - offshore_annual_group_gear_land_disc and inshore_annual_group_gear_land_disc. These dataframes contain the annual landings and discards of each harvestable guild in the model for each year of the model run (units mMN.y-1, from a model domain of 1m2 sea surface area). These data correspond to the files model_offshore_annual_landings_discards-TEXT.csv and model_inshore_annual_landings_discards-TEXT.csv which are generated in the /results folder.

str(results$total.annual.catch,max.level=1)
List of 2
 $ offshore_annual_group_land_disc:'data.frame':    5 obs. of  23 variables:
 $ inshore_annual_group_land_disc :'data.frame':    5 obs. of  23 variables:


The object annual.catch.by.gear is a list comprising two dataframes - offshore_annual_group_land_disc and inshore_annual_group_land_disc. These dataframes contain the same data as in total.annual.catch but disaggregataed into the fractions attributable to the (up to) 12 gears. The data are not output to CSV files.

str(results$annual.catch.by.gear,max.level=1)
List of 2
 $ offshore_annual_group_gear_land_disc:'data.frame':   5 obs. of  265 variables:
 $ inshore_annual_group_gear_land_disc :'data.frame':   5 obs. of  265 variables:


The object final.year.output is a list of arrays and dataframes containing a wide range of properties derived from the final year of the model run. The majority of these are also output as csv files in the /results folder.

str(results$final.year.output,max.level=1)
List of 27
 $ inshore_catchmat               : num [1:11, 1:12] 1.37e-01 2.66e-04 8.64e-06 1.59e-02 0.00 ...
  ..- attr(*, "dimnames")=List of 2
 $ inshore_discmat                : num [1:11, 1:12] 4.04e-04 3.00e-05 7.90e-07 8.32e-04 0.00 ...
  ..- attr(*, "dimnames")=List of 2
 $ inshore_landmat                : num [1:11, 1:12] 1.37e-01 2.36e-04 7.85e-06 1.51e-02 0.00 ...
  ..- attr(*, "dimnames")=List of 2
 $ offshore_catchmat              : num [1:11, 1:12] 1.03 7.82e-04 2.54e-05 9.42e-01 0.00 ...
  ..- attr(*, "dimnames")=List of 2
 $ offshore_landmat               : num [1:11, 1:12] 1.03 6.94e-04 2.31e-05 8.92e-01 0.00 ...
  ..- attr(*, "dimnames")=List of 2
 $ offshore_discmat               : num [1:11, 1:12] 3.04e-03 8.81e-05 2.32e-06 4.92e-02 0.00 ...
  ..- attr(*, "dimnames")=List of 2
 $ monthly.averages               :'data.frame':    12 obs. of  9 variables:
 $ mass_results_inshore           :'data.frame':    55 obs. of  3 variables:
 $ maxmass_results_inshore        :'data.frame':    55 obs. of  3 variables:
 $ minmass_results_inshore        :'data.frame':    55 obs. of  3 variables:
 $ annual_flux_results_inshore    :'data.frame':    240 obs. of  3 variables:
 $ mass_results_offshore          :'data.frame':    55 obs. of  3 variables:
 $ maxmass_results_offshore       :'data.frame':    55 obs. of  3 variables:
 $ minmass_results_offshore       :'data.frame':    55 obs. of  3 variables:
 $ annual_flux_results_offshore   :'data.frame':    240 obs. of  3 variables:
 $ mass_results_wholedomain       :'data.frame':    55 obs. of  3 variables:
 $ maxmass_results_wholedomain    :'data.frame':    55 obs. of  3 variables:
 $ minmass_results_wholedomain    :'data.frame':    55 obs. of  3 variables:
 $ annual_flux_results_wholedomain:'data.frame':    240 obs. of  3 variables:
 $ flow_matrix_all_fluxes         :'data.frame':    30 obs. of  32 variables:
 $ flow_matrix_excl_spawn_recruit :'data.frame':    30 obs. of  32 variables:
 $ NetworkIndexResults            :'data.frame':    99 obs. of  1 variable:
 $ annual.target.data             :'data.frame':    84 obs. of  9 variables:
 $ monthly.target.data            :'data.frame':    108 obs. of  9 variables:
 $ annual_obj                     : num 0.511
 $ partial_chi                    :'data.frame':    85 obs. of  1 variable:
 $ opt_results                    :'data.frame':    84 obs. of  8 variables:


The first six entries in the final.year.output list object are arrays which all have the same format - the catch, landings or discard mass of each guild (rows) by each gear (columns) in a given spatial zone, over the final year (mMN.y-1 from a model domain of 1m2 surface area). These data correspond with csv files in the /results folder, for example: final.year.output$inshore_catchmat becomes INSHORE_catchcomposition_by_gear-TEXT.csv. For example, the first two columns of the array containing inshore catch data are given by:

# List the first six entries
str(results$final.year.output[1:6],max.level=1)
List of 6
 $ inshore_catchmat : num [1:11, 1:12] 1.37e-01 2.66e-04 8.64e-06 1.59e-02 0.00 ...
  ..- attr(*, "dimnames")=List of 2
 $ inshore_discmat  : num [1:11, 1:12] 4.04e-04 3.00e-05 7.90e-07 8.32e-04 0.00 ...
  ..- attr(*, "dimnames")=List of 2
 $ inshore_landmat  : num [1:11, 1:12] 1.37e-01 2.36e-04 7.85e-06 1.51e-02 0.00 ...
  ..- attr(*, "dimnames")=List of 2
 $ offshore_catchmat: num [1:11, 1:12] 1.03 7.82e-04 2.54e-05 9.42e-01 0.00 ...
  ..- attr(*, "dimnames")=List of 2
 $ offshore_landmat : num [1:11, 1:12] 1.03 6.94e-04 2.31e-05 8.92e-01 0.00 ...
  ..- attr(*, "dimnames")=List of 2
 $ offshore_discmat : num [1:11, 1:12] 3.04e-03 8.81e-05 2.32e-06 4.92e-02 0.00 ...
  ..- attr(*, "dimnames")=List of 2
#
# View the first two column of the inshore_catchmat array
results$final.year.output$inshore_catchmat[,1:2]
                              Pelagic_Trawl+Seine
Planktivorous fish                   1.372099e-01
Quota-limited demersal fish          2.660990e-04
Non-quota demersal fish              8.635678e-06
Migratory fish                       1.591609e-02
Susp/deposit feeding benthos         0.000000e+00
Carn/scavenge feeding benthos        5.547607e-07
Pelagic invertebrates                0.000000e+00
Birds                                7.422397e-08
Pinnipeds                            0.000000e+00
Cetaceans                            1.430427e-06
Macrophytes                          0.000000e+00
                              Sandeel+sprat_trawl(Otter30-70mm+TR3)
Planktivorous fish                                     1.742213e-01
Quota-limited demersal fish                            1.529002e-03
Non-quota demersal fish                                4.962052e-05
Migratory fish                                         1.373853e-03
Susp/deposit feeding benthos                           5.324246e-06
Carn/scavenge feeding benthos                          3.857837e-04
Pelagic invertebrates                                  0.000000e+00
Birds                                                  0.000000e+00
Pinnipeds                                              0.000000e+00
Cetaceans                                              0.000000e+00
Macrophytes                                            0.000000e+00


The object final.year.output$monthly_averages is a dataframe of monthly averaged nutrient and plankton data (units: mMN.m-3, except for chlorophyll: mg.m-3) corresponding to the observational data available in the /Target_data folder of model stup data. Chlorophyll is estimated assuming Redfield C:N (molar ratio 106:16), and a carbon:chlorophyll weight ratio of 40. The data correspnd to the csv output file model_monthlyresults-TEXT.csv. For example, the first two columns of the array are given by:

results$final.year.output$monthly.averages[,1:2]
   surfnitratemMm3 deepnitratemMm3
1        10.307251       10.215046
2        10.426346       10.340521
3         7.612095        8.725894
4         3.042989        5.429079
5         2.460538        5.023081
6         2.891553        5.519409
7         3.077796        5.940273
8         3.331949        6.022470
9         4.033438        5.841896
10        4.920083        5.983520
11        7.269590        7.715930
12        9.336161        9.436724


The next four entries in the final.year.output list object are dataframes containing annual averages, maxima and minima of each state variable in the inshore zone (mMN), and a set of annually integratred flux terms (mMN.y-1) during the final year. The fluxes include both physical flows due to advection, mixing, and inflows and outflows, and ecological fluxes between state variables. The food web fluxes are not calculated for the inshore zone, but are provided in other data frames for the model domain as a whole. In addition the dataframe contains the zonal area proportions and layer thicknesses needed to convert the data to mass or flux densities (m-2 or m-3). The formats of the average, maxima and minima files are the same. The data correspond to csv files output to the /results folder with names: INSHORE_model_anav_biomass-TEXT.csv, INSHORE_model_maximum_biomass-TEXT.csv, INSHORE_model_minimum_biomass-TEXT.csv, INSHORE_model_annualresults-TEXT.csv. The dataframes contain 3 columns: the numeric values, units and a descriptive text field. For example, list these dataframes in the list, and view the top few rows of the annual average dataframe, and the annual fluxes dataframe:

str(results$final.year.output[8:11],max.level=1)
List of 4
 $ mass_results_inshore       :'data.frame':    55 obs. of  3 variables:
 $ maxmass_results_inshore    :'data.frame':    55 obs. of  3 variables:
 $ minmass_results_inshore    :'data.frame':    55 obs. of  3 variables:
 $ annual_flux_results_inshore:'data.frame':    240 obs. of  3 variables:
#
head(results$final.year.output$mass_results_inshore)
  Model_annual_mean                               Units
1      4.470692e+00 mMN_in_the_whole model_domain_(1m2)
2                NA mMN_in_the_whole model_domain_(1m2)
3      1.221639e+04 mMN_in_the_whole model_domain_(1m2)
4      1.218173e+04 mMN_in_the_whole model_domain_(1m2)
5      5.084450e-02 mMN_in_the_whole model_domain_(1m2)
6      1.252813e+00 mMN_in_the_whole model_domain_(1m2)
                               Description
1                   Surface_layer_detritus
2                      Deep_layer_detritus
3 Sediment_labile_plus_refractory_detritus
4             Sediment_refractory_detritus
5                         Fishery_discards
6                                  Corpses
#
head(results$final.year.output$annual_flux_results_inshore)
  Model_annual_flux                          Units          Description
1        137.637467 mMN/whole_model_domain_(1m2)/y           DIN_inflow
2         95.149077 mMN/whole_model_domain_(1m2)/y          DIN_outflow
3         69.075867 mMN/whole_model_domain_(1m2)/y   Particulate_inflow
4          9.781907 mMN/whole_model_domain_(1m2)/y  Particulate_outflow
5         17.644459 mMN/whole_model_domain_(1m2)/y Atmosphere_DIN_input
6        104.700816 mMN/whole_model_domain_(1m2)/y     River_DIN_inflow


The next four entries in the final.year.output list object are dataframes containing annual averages, maxima and minima of each state variable, and annual fluxes in the offshore zone (mMN) during the final year, exactly corresponding to the previous four entries for the inshore zone. As for the inshore zone, the data are output to corresponding CSV files.

str(results$final.year.output[12:15],max.level=1)
List of 4
 $ mass_results_offshore       :'data.frame':   55 obs. of  3 variables:
 $ maxmass_results_offshore    :'data.frame':   55 obs. of  3 variables:
 $ minmass_results_offshore    :'data.frame':   55 obs. of  3 variables:
 $ annual_flux_results_offshore:'data.frame':   240 obs. of  3 variables:


The next four entries in the final.year.output list object are dataframes containing annual averages, maxima and minima of each state variable, and annual fluxes for the model domain as a whole (mMN) during the final year, exactly corresponding to the previous four entries for the offshore zone, except that in this case all of the flows between state variables in the food web are evaluated. In following outputs these flows are assembled into the flow matrix format required by the NetIndices package to calculate network indices. As for the offshore zone, the data are output to corresponding CSV files.

str(results$final.year.output[16:19],max.level=1)
List of 4
 $ mass_results_wholedomain       :'data.frame':    55 obs. of  3 variables:
 $ maxmass_results_wholedomain    :'data.frame':    55 obs. of  3 variables:
 $ minmass_results_wholedomain    :'data.frame':    55 obs. of  3 variables:
 $ annual_flux_results_wholedomain:'data.frame':    240 obs. of  3 variables:


The next three entries in the final.year.output list object are dataframes containing the flow matrices required for input to the NetIndices package, and the outputs from NetIndices. Two version of the flow matrix are included - one which includes spawning and recruitment flows - from adults to larvae and larvae to adults, and one in which these flows are excluded. In each case the rows names of the matrix indicate the “flow-from”, and the columns indicatethe “flow-to”. All three of these data sets are exported to csv files in the /results folder: flow_matrix_all_fluxes-TEXT.csv, flow_matrix_excl_spawn_recruit-TEXT.csv, and Network_indices_output-TEXT.csv.

str(results$final.year.output[20:22],max.level=1)
List of 3
 $ flow_matrix_all_fluxes        :'data.frame': 30 obs. of  32 variables:
 $ flow_matrix_excl_spawn_recruit:'data.frame': 30 obs. of  32 variables:
 $ NetworkIndexResults           :'data.frame': 99 obs. of  1 variable:
#
#Show the first 5 rows and columns of the matrix of all flows:
results$final.year.output$flow_matrix_all_fluxes[1:5,1:5]
             wcammonia sedammonia wcnitrate   sednitrate wcdetritus
wcammonia    0.0000000          0  1087.485   0.00000000          0
sedammonia 379.7536227          0     0.000   0.03731479          0
wcnitrate    0.0000000          0     0.000 205.49634776          0
sednitrate   0.0000000          0     0.000   0.00000000          0
wcdetritus   0.3582839          0     0.000   0.00000000          0
#
#Show the first few rows of the dataframe containing outputs from the NetIndices package:
head(results$final.year.output$NetworkIndexResults)
                         NetworkData
wcammonia_trophiclevel             1
sedammonia_trophiclevel            1
wcnitrate_trophiclevel             1
sednitrate_trophiclevel            1
wcdetritus_trophiclevel            1
seddetritus_trophiclevel           1


The next two entries in the final.year.output list object are dataframes containing annual observational data on the state of the ecosystem, and the monthly observational data. These are exact copies of the input data from the /Target_data folder of input files, and are included in the results object merely for convenience so that they are easily available for comparison with model outputs:

str(results$final.year.output[23:24],max.level=1)
List of 2
 $ annual.target.data :'data.frame':    84 obs. of  9 variables:
 $ monthly.target.data:'data.frame':    108 obs. of  9 variables:


The final three elements of the final.year.output list object are associated with the calulation of the likelihood of the observed annual target data on the state of the ecosystem, given the model drivers and parameters. The first is a single numeric value - the overall likelihood of the observed target data. The second is a dataframe of the partial likelihoods for each aspect of the observational dataset. Finally, a dataframe of the derived model outouts for the final year of the run, exactly corresponding to the set of observational measures. The two dataframes are also output as CSV files to the /results folder with names model_likelihood_results-TEXT.csv and model_target_annualresults_plus_chi-TEXT.csv.

str(results$final.year.output[25:27],max.level=1)
List of 3
 $ annual_obj : num 0.511
 $ partial_chi:'data.frame':    85 obs. of  1 variable:
 $ opt_results:'data.frame':    84 obs. of  8 variables:
#
#Show the overall likelihood value:
results$final.year.output$annual_obj
[1] 0.5105364
#
#Show the first few rows of the partial likelihood data:
head(results$final.year.output$partial_chi)
             Likelihood
Obs_TAPP      0.1675435
Obs_NP        0.3294170
Obs_KelpP     0.9999014
Obs_OmnizooP  0.7491700
Obs_CarnzooP         NA
Obs_PFishP           NA
#
#Show the first few rows of the dataframe containing the model outputs corresponding to the annual observational target data:
head(results$final.year.output$opt_results)
  Annual_measure SD_of_measure Model_data Use1_0          Chi         Name
1         1522.0       150.940 1236.68650      1 1.786512e+00     Obs_TAPP
2          687.2        67.396  787.63727      1 1.110431e+00       Obs_NP
3          600.0       100.000  601.40402      1 9.856425e-05    Obs_KelpP
4          339.6        25.157  320.48103      1 2.887894e-01 Obs_OmnizooP
5             NA            NA   44.89116      0           NA Obs_CarnzooP
6             NA            NA   14.58603      0           NA   Obs_PFishP
     Units                                         Description
1 mMN/m2/y                     Annual_total_primary_production
2 mMN/m2/y Annual_new_production_from_depth_integrated_nitrate
3  gC/m2/y  Annual_WITHIN_FOREST_NET_production_of_macrophytes
4 mMN/m2/y          Annual_ominiv_zooplankton_gross_production
5 mMN/m2/y     Annual_carnivorous_zooplankton_gross_production
6 mMN/m2/y          Annual_planktivorous_fish_gross_production




While the results object generated by the StrathE2E() function contains a wide range of derived model outputs, users may also need to generate their own. The following examples illustrate how to extract and process the raw output held in the results$output dataframe.


For a set of results created using the read_model() and StrathE2E() functions, the raw data from the model run are contained in the object dataframe results$output. The first row of the output dataframe corresponds to time=0, i.e. the initial conditions passed to the differential equation solver at the start of the run. A calendar year of output corresponds to a time interval of 360 days, i.e. 361 rows of output data (time = 0:360), so the total number of rows of output will be ((360 * nyears)+1), where nyears is the specified length of the model run in years.

Assuming that the output dataframe has been extracted from the results object into a new dataframe out as follows:

out <- results$output

Data for any one year specified by Y (Y <= nyears) can be extracted by the R statement:

# All the output corresponding to year Y
Y <- 3                    # select year 3
yearY_data <- out[(((Y-1)*360)+1) : ((Y*360)+1),]
#
#List the first few rows and columns of these extracted data
head(yearY_data[,1:6])
    time detritus_so detritus_d x_detritus_s1 x_detritus_s2 x_detritus_s3
721  720    4.984489   9.172866     1.0201296      16.96836      4.655573
722  721    4.958413   9.128401     1.0116078      16.81241      4.616085
723  722    4.932172   9.083547     1.0031744      16.65819      4.576965
724  723    4.905755   9.038290     0.9948290      16.50570      4.538212
725  724    4.879150   8.992616     0.9865710      16.35493      4.499824
726  725    4.852351   8.946512     0.9783997      16.20585      4.461802


# All the output for a given state variable (denoted by "column_name") in year Y:
Y <- 3                    # select year 3
column_name<- "herb_o"    # Select offshore omnivorous zooplankton
col2get <- which(colnames(out)==column_name)
column_data_yearY <- out[(((Y-1)*360)+1) : ((Y*360)+1),col2get]


# Calculate the annual average in year Y of the variable extracted in the previous step:
    mean(column_data_yearY)
[1] 24.67018


The flux terms in the output dataframe are cumulative over the duration of the model run, beginning at 0 at time = 0. Hence, the time-series of instantaneous flux rates (d-1) is the sequence of increments between successive rows of output. In R this can be generated by, for example:

column_name<- "phytgrossprod_o"            # Select for example offshore gross production by phytoplankton
col2get <- which(colnames(out)==column_name)
J <- nrow(out)                     # number of rows of data in the "out" dataframe
temp <- rep(0,J)                   # creates a vector to hold temporary data
temp[1: (J-1)] <- out[2 : J, col2get]          # copies data from the "out" into "temp" offset by 1 time increment
temp[J] <- 2*(out[J,col2get]) - out[J-1,col2get]   # fills in the terminal value of the "temp" vector by extrapolation
rate <- temp - out[,col2get]               # "rate" is a vector of the increments between successive time steps
#
#Plot the original cumulative data and the derived rate
par(mfrow=c(2,1))
par(mar=c(4,4,1,1))
plot(seq(1,length(out[,col2get])),out[,col2get],type="l",xlab="Days",ylab="Cumulative flux")
plot(seq(1,length(rate)),rate,type="l",xlab="Days",ylab="Daily flux")

Figure 19. Upper panel: time series of the cumulative phytoplankton gross production as output from the model. Lower panel: same data converted into daily gross production rates.


To obtain the annual integral of a flux variable over a given year, the R statement would be:

Y <- 3                                                  # select year 3
column_name<- "phytgrossprod_o"                 # Select for example offshore gross production by phytoplankton
col2get <- which(colnames(out)==column_name)
out[((Y*360)+1),col2get] - out[(((Y-1)*360)+1),col2get] # integrated flux of the variable denoted by "column_name" over year Y
[1] 1755.582


All of the terms in the output dataframe are in mass units (mMN or mMC) in the model domain which is is scaled to a sea-surface area of 1 m2. To express the outputs as area densities in the inshore or offshore zones (e.g. mMN.m-2) or layer concentrations (e.g. mMN.m-3), the mass values need to be re-scaled to the area-proportion of the relevant zone and/or layer thickness. In addition, terms relating to sediment or sediment porewater require to be scaled by the area-proportions of seabed habitats, sediment layer thicknesses and sediment porosity. These scaling parameters are accessible to the user as elements of the object build$model.parameters which forms part of the list-object generated by a model run. Examples of R statements for converting mass outputs into area-densities and layer concentrations are shown below.


# Extract the relevant area and volumetric parameters from the $build$model.parameters object
inshore_area         <- as.numeric(results$build$model.parameters["shallowprop"])
offshore_upper_thick <- as.numeric(results$build$model.parameters["thik_so"])
offshore_lower_thick <- as.numeric(results$build$model.parameters["thik_d"])
inshore_sed1_area    <- as.numeric(results$build$model.parameters["area_s1"])
inshore_sed1_thick   <- as.numeric(results$build$model.parameters["thik_x_s1"])
inshore_sed1_poros   <- as.numeric(results$build$model.parameters["porosity_s1"])
#
# Time series of suspended detritus and bacteria concentration in the offshore upper layer (mMN.m-3)
detr_bact_conc_so<- out$detritus_so/((1-inshore_area)*offshore_upper_thick)
#
# Time series of the area-density of omnivorous zooplankton in the inshore zone (mMN.m-2)
oz_dens_i<- out$herb_i/inshore_area     
#
# Time series of the depth averaged concentration of omnivorous zooplankton in the offshore zone (mMN.m-3)
oz_conc_o<- out$herb_o /((1-inshore_area)*(offshore_upper_thick+offshore_lower_thick))
#
# Time series of the porewater concentration of ammonia in inshore sediment habitat 1 (mMN.m-3):
xamm_conc_s1<- out$x_ammonia_s1/(inshore_sed1_area*inshore_sed1_thick*inshore_sed1_poros)
#
# Time series of labile detritus & bacterial in inshore sediment habitat 1 as a % of sediment dry weight (%gN.g-1):
xdet_conc_s1<- 100*(out$xR_detritus_s1*(14/1000))/(inshore_sed1_area*inshore_sed1_thick*(1-inshore_sed1_poros)*2650000 )
# (nitrogen atomic weight = 14 g.mole-1; dry sediment density = quartz density = 2.65 x 1e6 g.m-3)  




4 Parameter estimation

4.1 Background

Three groups of parameters in the combined ecology and fishing fleet model system might be considered as candidates for estimation, depending on the availability of external data:


It is clearly unrealistic to expect to be able to optimise all of these sets of parameters concurrently since there is a risk that some may be confounded. So, the R package provides several options for parameter estimation, each of which optimises one of these groups of parameters, given knowledge on the other two.


The parameter estimation schemes are configured as a stationary state fitting method, though there is no intrinsic reason why they could not be adapted for time-series fitting. For the most part, the methodology involves likelihood estimation and a simulated annealing scheme using the Metropolis-Hastings iterative algorithm (Bertsimas & Tsitsiklis, 1993; Cerny, 1985; Kirkpatrick et al., 1983).


4.2 Implementation of the Metropolis-Hastings algorithm

The Metropolis-Hastings algorithm implemented with StrathE2E2 automates the acceptance or rejection of proposed new randomly generated sets of model parameters (Figure 20). The objective is to maximize the likelihood of the set of observed (target) indices given a vector of model parameter values. Starting with an initial informed-guess parameter vector, the procedure iterates through model runs, and at each iteration the parameters are independently ‘jiggled’ by proposing new values drawn from gaussian distributions of fixed coefficient of variation (standard deviation divided by the mean) around the current accepted values. There are some special-case parameters in StrathE2E2 which are bounded by known limits, and the preference parameters which require to be renormalized to sum to 1.0 for each predator after the addition of random ‘jiggles’.


Figure 20. Flow diagram illustrating the operation of the simulated annealing scheme for parameter optimization.


After running the model to a stationary state with the new parameter vector, and extracting simulated versions of the (\(i\)) observed ecosystem state indices (\(1 < i < I\)) (where the observed indices each have a standard deviation \(\sigma_i\)), an overall error term (\(\chi_{\theta^*}^{2}\)) is calculated for the model as follows:

\[\chi_{\theta^*}^{2} = \frac{\sum_{i=1}^{i=I} \frac{(observed_{i} - simulated_{\theta^{*},i} )^{2}}{2\sigma_{i}^{2} }}{I} \]


The likelihood of the overall set of indices \(P(observation|\theta^{*})\) is then \(exp(-\chi_{\theta^*}^{2}\)).


The change in performance of the model due to the jiggling of the proposed parameter set is measured by (\(\chi_{\theta^*}^{2} - \chi_{\theta_{current}}^{2}\)). A simple ‘hill-climbing’ scheme would accept the proposed parameter set \(\theta^*\) as a new version of the parameter set \(\theta_{current}\) for the next iteration only if the likelihood ratio \(LR = exp(\chi_{\theta^*}^{2} - \chi_{\theta_{current}}^{2}) > 1\). Over many iterations the accepted parameter set should then migrate towards a maximum likelihood fit. However, such schemes are notorious for becoming trapped in local optima. Simulated annealing attempts to mitigate this risk by accepting a proportion of instances of proposed sets which produce worse results than current accepted (i.e. \(LR < 1\)), thereby exploring a wider range of the parameter space. The process is an analogy of the way in which crystals form in a liquid metal as it cools. Taking \(T[k]\) to represent the ‘temperature’ of the system at iteration \(k\), the probability of accepting a proposal as the new current is equal to the modified likelihood ratio: \[LR_m = exp((\chi_{\theta^*}^{2} - \chi_{\theta_{current}}^{2})/T[k])\]


The value of \(T[k]\) is allowed to ‘cool’ as the iterations progress (increasing \(k\)). As \(T[k]\) decreases towards 0 the system assumes a simple hill-climbing mode (i.e. only vectors \(\theta^*\) producing likelihood ratios > 1 are accepted). In the early stages, when \(T(k) > 0\), a proportion of \(\theta^*\) producing likelihood ratios < 1 are accepted. Practically, after each model run \(\theta[k]\) = \(\theta^*\) only if \(LR_m \ge \lambda\), where \(\lambda\) is drawn from a uniform random distribution between 0 and 1, otherwise \(\theta[k]\) = \(\theta[k-1]\) for the next iteration. At each iteration, both the currently accepted and the proposed parameter vectors are saved, along with the resulting likelihood of the observations given the parameters.


The sequence of (P(observation|\(\theta^*\))[k]) should converge to a maximum value representing the best attainable fit between the model and the observations given the model structure and driving data. However, the rate at which convergence is achieved, and potentially the converged vector itself, are dependent on the cooling schedule and the magnitude of the jiggling coefficient of variation (cv) used to generate \(\theta[k]\). A geometrically decreasing temperature is applied (\(T[k] = r.T[k-1]\)), and after experimentation with the value of r and cv, the finally adopted values for fitting StrathE2E2 models to achieve consistency of convergence within a sensible number of iterations (<10000) are: r = 0.975, cv = 0.005. The best-fit value of \(\theta[k]\) is regarded as being that remaining when no new parameter vectors are accepted within 200 iterations.


4.3 Target data for optimisation

The target data for optimizing a particular model should all be located in the /Models/Variant/Target_data folder of the model definition. The individual files names must all contain a standard text string plus a free text string for identification of different versions. The particular version required to be loaded for a given optimisation run should be identified inthe MODEL_SETUP.csv file in the /ModelName/VariantName folder.


In most instances, the target data to which the model is optimised during the simulated annealing process are a set of up to 84 indices of the real-world state of the ecosystem and their associated uncertainties (standard deviations). This file is named annual_target_data*.csv (where * is a free text field for identification). The ecosystem state indices include annual average biomasses or concentrations, annual integrated production rates of food web components, annual integrated dietary intakes, fishery landings and discards, denitrification rate, and other properties. The file also contains text fields including a description, units, geographic region and time period of applicability, and the origins of the data that were used to generate the index. For each index, the code calculates an equivalent value for the final year of each model run as the basis for the likelihood estimation. Individual indices can be included or excluded from the likelihood calculation by means of a switch (value 1 or 0) in the input file.


One of the availble methods for estimating fishing gear activity rates where these are unknown relies on target data concerning the harvest ratios on each guild in each zone of the model. These are contained in a file fishing_fleet_target_harvest_ratios*.csv (where * is a free text field for identification).


Finally, calculation of effort to harvest ratio scaling parameter values when activity, fishing power and harvest ratios are all known, requires the target data on harvest ratios. to be located in the file known_regional_harvest_ratios*.csv (where * is a free text field for identification).


4.4 Versions of parameter estimation

5.4.1 Ecology model parameter estimation

Optimising the parameters of the ecology model requires that fishing gear activity rates and the parameters linking effort to harvest ratios are know.


Certain parameters of the ecology model are excluded from the optimisation process because they are either confounded with other parameters in some way or there is a clear route to establishing values from external evidence (Table 10). All other parameters, defining the prey preferences of all the living components of the model, the uptake and mortality rate coefficients, and the rate coefficients for the biogeochemical processes, are eligible for optimisation. A subset of the feeding rate parameters for the top-predators can be optionally excluded from the optimisation process if reasonable values can be independently estimated. Separate coefficients of variation can be set for different classes of parameters (preference parameters, maximum uptake rates, half saturation coefficients, microbial rates, density dependent mortality rates) via a setup text file.


Parameters elligible for fitting are contained in the files fitted_parameters_preference_matrix*.csv, fitted_parameters_uptake_and_mortality_rates*.csv, and fitted_parameters_microbiology_and_others*.csv (where * is a free text identifier) in the /Parameters folder of each model definition. At the end of an optimization run the code exports a new set of these three files containing the accepted values for the maximum likelihood model, back to the /Parameters folder with a new text identifier which is set by the model.ident argument in the read_model() function.


The coefficients of variation for ‘jiggling’ the parameter values during an optimisation run are held in the file annealing_SD_ecology*.csv in the /Parameters/Parameter_SD_control folder of each model definition. These can be changed in real-time during a run, to enable exploration of the effects of parameter search patterns.


Table 10. Background to the parameters of the ecological model which require to be fixed from external evidence and are excluded from the simulated annealing process. These parameters are contained in two files fixed_parameters_for_consumer_groups*.csv and fixed_parameters_miscellaneous*.csv (where * is a free text identifier) in the /Parameters folder of each model definition.

Parameter type Description
Assimilation efficiencies for each living guild in the model Proportion of the ingested mass of food that contributes to new body tissue after subtracting defecation and the metabolic costs of digestion and synthesis
Biomass loss rates due to temperature-dependent metabolism for each living resource guild Proportion of biomass lost to ammonia per day due to non-feeding related metabolism at a given Q10 reference temperature
Q10 values for temperature dependent processes and the Q10 reference temperature Separate Q10 values for autotrophic uptake of nutrient, heterotrophic feeding, and heterotrophic metabolism based on literature data
Light intensity required to saturate autotrophic nutrient uptake Light saturation intensity for nutrient uptake, estimated from survey of field and laboratory experiments
Annual weight specific fecundities of fish and benthos guilds Guild-level values of the annual proportion of biomass which is shed as eggs
Spawning start and end dates for fish and benthos guilds Day-number (assuming 360-day year) of the onset and end of spawning to be based on such empirical data as are available
Recruitment start and end dates for fish and benthos guilds Day-number (assuming a 360-day year) of the onset and end of recruitment from the larval stage to the main guild biomass
Extra-domain biomass of migratory fish and the proportion invading the domain each year Biomass of the wider stock contributing to the transient population in the model domain, extracted from fisheries stock assessments
Start and end dates for the annual invasion and emigration of migratory fish Day-number (assuming a 360-day year) of the onset and end of immigration and emigration phases
Harvestable biomass density threshold for each resource guild A limit for each guild below which the harvestable species are assumed to be exhausted. Values based on data from surveys, fisheries and stock assessments
Minimum inedible biomass of carnivorous zooplankton A minimum edible threshold is set to ensure that the guild as a whole cannot be extirpated by predation



4.4.1.1 Using the function annealing_find_ecology_parameters()

Table 11. Arguments of the function annealing_find_ecology_parameters().

Argument Description
model R-list object generated by the read_model() function which defines 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=0.5). 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)


Configuration of a simulated annealing run to estimate ecology model parameters must be preceded by a read_model() function call to load the model setup which includes the initial values for all of the parameters to be fitted.


It is important to 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. The Y-axis (likelihood) range of the real time plot can be varied during the run by editing the setup file annealing_SD_ecology.csv at any time during the run.


At the end of the procedure new versions of the three ecology model fitted_parameter*.csv 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 StrathE2E2 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.


# 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 demonstration 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 as follows :
annealing_find_ecology_parameters(model, nyears=50, n_iter=1000, start_temperature=1)
# (WARNING - this will take about 26 hours to run)
#



4.4.2 Estimation of scaling parameters linking fishing effort to harvest ratio

Two methods are provided for estimating the scaling parameters linking fishing effort to harvest ratios. The first involves optimising the combined fleet and ecology model system to the database of observational indices on the state of the ecosystem, equivalant to the method for finding ecology moldel parameters. This requires that all of the ecology model parameters are known, and likewise that the activity rates and distribution of each fishing gear are known. This is a situation which might apply when the coupled fishing and ecology model system has been comprehensively fitted for a data-rich period of time, and is then being applied to a different data-poor period where at least the gear activity rates are known.


Proposed values of the scaling parameters are contained in the configuration file for the fishing fleet model. In addition, the model setup includes a separate CSV file (harvest_ratio_multiplier.csv) containing multipliers to be applied to each of these scaling parameters. These are useful when conducting scenario experiments, but would ordinarily be set to 1.0. The simulated annealing code for optimising the scaling values iterates the multiplier values to seek the combination producing the best fit of the overall model to the set of target data. At the end of the process, the code saves the history of proposed and accepted multiplier values to the current /results folder, and the final accepted version of the multipliers back to the /ModelName/VariantName/Parameters folder with the model.itent text identifier assigned in the read_model() function call which must precede the run. If deemed worthy, these multipliers can then be manually applied to the corresponding parameter values in the fishing fleet configuration to produce an updated version. The effort-harvest ratio multipliers associated with birds, pinnipeds and cetaceans are likely to be poorly constrained by observational data and may need to be set independently. Nevertheless thay are included in the process here.


The second method for estimating the scaling parameters is much simpler and involves only the fishing fleet model. Given an independent estimate of the actual harvest ratios on each guilkd during a period when the activity rates of each gear is also known, it is a simple calculation to derive the effort scaling parameters. This approach would typically be employed in the early stages of parameterising a new model, go obtain first-cut values for these parameters which could be refined later using the full optimization procedure.


4.4.2.1 Using the function annealing_find_harvest_ratio_mult()

Table 12. Arguments of the function annealing_find_harvest_ratio_mult().

Argument Description
model R-list object generated by the read_model() function which defines 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=0.5). 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 (TRUE or FALSE) Suppress informational messages at the start of each iteration (default=TRUE)


Configuration of a simulated annealing run to estimate the effort to harvest ratio scaling parameters by optimising to the ecosystem state target data must be preceded by a read_model() function call to load the model setup. This will include the initial values for the harvest ratio multipliers which should ideally (though not necessarily be all set to 1.0 from the start.


It is important to 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 harvest ratio parameters can be varied in real-time during the run by editing the file annealing_SD_fishing.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. The Y-axis (likelihood) range of the real time plot can be varied during the run by editing the setup file annealing_SD_fishing.csv at any time during the run.


At the end of the procedure new versions of the harvest ratio multiplier file is 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 StrathE2E2 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 harvest ratio multiplier file. Or, to preserve the new harvest ratio multipliers and incorporate them into the fishing fleet model parameterisation, manually update the values in rows 12-21 (excluding the header row) of the file /Parameters/fishing_fleet_parameters_*.csv, by multiplying the existing values by the new multipliers emerging from the annealing process. Then make sure to use a version of the multiplier file with all values set to 1.0 for all future runs.


# 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 demonstration of the annealing function in operation:
annealing_find_harvest_ratio_mult(model, nyears=5, n_iter=10, start_temperature=0.5)
#
# More realistic configuration would be as follows :
annealing_find_harvest_ratio_mult(model, nyears=50, n_iter=1000, start_temperature=1)
# (WARNING - this will take about 26 hours to run)
#


4.4.2.2 Using the function calculate_hr_scale_values()

Table 13. Arguments of the function calculate_hr_scale_values().

Argument Description
model R-list object generated by the read_model() function which defines the model configuration


Given known gear activity rates, selectivity patterns (i.e. fishing power data), and corresponding harvest ratios it is straightforward to calculate the values of the parameters of the fleet model which link effort (activity x power) to harvest ratio.


The model argument for the calculate_hr_scale_values() function represents an R list object created by the read_model() function, which should contain the required activity and power data for the designated model. The corresponding known harvest ratios need to be located in the file known_regional_harvest_ratios*.csv (where * is a text identifier) in the **_data** folder of the model definition, and listed in the setup file MODEL_SETUP.csv.


The function returns a dataframe of calculated parameter values. It is up to the user to scrutinize these and if accepted manually edit them into rows 12-21 (excluding the header row) of the file /Parameters/fishing_fleet_parameters_*.csv.


# Load the 2003-2013 version of the North Sea model supplied with the package and calculate scaling parameter values:
model <- read_model("North_Sea", "2003-2013")
#
scale_values <- calculate_hr_scale_values(model)
[1] "Manually edit these values into the 'fishing_fleet_parameters_*.csv' file in the 'Parameters' folder"
scale_values
                Guild     HRscale
1  Planktivorous_fish  0.03102313
2       Demersal_fish  0.10674489
3      Migratory_fish  0.05912854
4    Benthos_susp-dep  5.86628271
5   Benthos_carn-scav  0.78986760
6    Zooplankton_carn 14.22221473
7               Birds  2.71513873
8           Pinnipeds  4.38631271
9           Cetaceans  6.54318961
10        Macrophytes  0.00000000
#



4.4.3 Estimation of fishing activity rates

Usually, the fishing gear activity rates are a known input to the model. Sometimes, however, it may be necessary to use the model to hindcast the likely rates of activity given established values for the ecology model parameters, the scaling parameters linking effort to harvest ratios, and the relative spatial distribution of fioshing. This is a situation that might apply when the coupled fishing and ecology model system has been comprehensively fitted for a data-rich period of time, and is then being applied to a different data-poor period where the fishing gear activity rates are unknown or only approximately known.


Proposed values of the gear activity rates need to be contained in the standard fishing_activity_parameters*.csv input file for the fishing fleet model. In addition, the model setup includes a separate csv file (fishing_activity_multiplier.csv) containing multipliers to be applied to each of these rates. These are useful when conducting scenario experiments, but would ordinarily be set to 1.0. In the same way as for the effort-harvest ratio scaling value fitting, the simulated annealing code for optimising the gear activity rates iterates the multiplier values to seek the combination producing the best fit of the overall model to the set of target data. At the end of the process, the code saves the history of proposed and accepted multiplier values. If deemed reasonable, the final accepted version of the multipliers can then be manually applied to the corresponding rates in the initial input file to produce an updated version.


There are two alternative functions for optimising fishing activity rates. The first is conceptually equivalent to the simulated annealing functions for optimizing the ecology model parameters, in that the target for fitting is the same database of observational indices of ecosystem status. This uses the fully coupled fishing fleet and ecology model system and hence is costly to run.


The alternative function for estimating the activity rate of gears is much faster and relies only on the fishing fleet model, but here the target for optimization is a set of known harvest ratios. The circumstances under which the past harvest ratios for each guild are sufficiently well known to enable this fitting approach are likely to be rather restricted, but this method is probably the more robust. In both approaches the chief problem is that the selectivity patterns of the fishing gears are likely to be highly overlapping so that it will be difficult to identify a realistic maximum likelihood set of activity rates. For this reason the functions make use of a table of ‘gear linkage’ parameters which constrain the extent to which groups of gears can vary independently during the parameter searching process. This makes since management measures which may have restricted the activities of e.g. demersal trawlers, will also have been applicable to e.g. beam trawlers. However, the linkage table is populated partly by judgement rather than by hard data.


The target data for the second method for estimating activity rates are contained in the file fishing_fleet_target_harvest_ratios*.csv (where * is a free text identifier) located in the /ModelName/VariantName/Target_data folder of the model definition data.


4.4.3.1 Using the function annealing_find_gear_activity_mult_ecosystem_target()

Table 14. Arguments of the function annealing_find_gear_activity_mult_ecosystem_target().

Argument Description
model R-list object generated by the read_model() function which defines 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=0.5). 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 (TRUE or FALSE) Suppress informational messages at the start of each iteration (default=TRUE)


The function launches a simulated annealing process to find the set of fishing fleet model gear activity multipliers producing the maximum likelihood of observed target data on the state of the ecosystem, given specified environmental driving data and ecology model parameters, and effort-harvest ratio scaling parameters.


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


It is important to 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 coefficient of variation for jiggling the activity multipliers can be varied in real-time during the run by editing the file annealing_SD_fishing.csv in the folder Parameters/Parameter_SD_control of the model version. Suggested vaues for the SD are in the range 0.1 to 0.01


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) range of the real time plot can be varied during the run by editing the setup file annealing_SD_fishing.csv


At the end of the procedure a new version of the gear activity multipliers file is 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 StrathE2E2 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 harvest ratio multiplier file. Or, to preserve the new activity rate multipliers and incorporate them into the fishing fleet model parameterisation, manually update the values in the file /Parameters/fishing_activity_parameters*.csv, by multiplying the existing values by the new multipliers emerging from the annealing process.


If the edited file fishing_activity_parameters*.csv is saved with a new identifier (*) then in order to use it in a subsequent run of the StrathE2E2 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 file. Then make sure to use a version of the multiplier file with all values set to 1.0 for all future runs.


# 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 Demonstration of the annealing function in operation:
annealing_find_gear_activity_mult_ecosystem_target(model, nyears=5, n_iter=10, start_temperature=0.5)
#
# More realistic configuration would be:
annealing_find_gear_activity_mult_ecosystem_target(model, nyears=50, n_iter=1000, start_temperature=1)
#  (WARNING - this will take about 26 hours to run)


4.4.3.2 Using the function annealing_find_gear_activity_mult_HR_target()

Table 15. Arguments of the function annealing_find_gear_activity_mult_HR_target().

Argument Description
model R-list object generated by the read_model() function which defines the model configuration
nchains Number of repeats (chains) of the simulated annealing process (default=100)
n_iter Number of iterations of the fishing fleet model per chain (default=3000)
start_temperature Initial value of the simulated annealing temperature parameter (default=0.5). 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.985). Suggested values in the range 0.9 - 0.985
deltaHi Initial coefficient of variation for jiggling the activity multiplier values (default=0.2)
attenuationstep Number of itereations between down-steps of the jiggling factor applied to the multiplier values. The jiggling rate is attenuated by a factor of 2 every xx iterations (default=500)
deltaGrat Coefficient of variation for jiggling the gear linkage values (default=0.25)

The function launches a simulated annealing process to find the set of fishing fleet model gear activity multipliers producing the maximum likelihood of a set of known harvest ratios using only the fishing fleet model, given specified effort-harvest ratio scaling parameters.


The known harvest ratios which act as the target for the optimization process are located in the file ../Modelname/Variantname/Target_data/fishing_fleet_target_harvest_ratios.csv, where is an identifier.


It is important to 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 implementation of simulated annealing in this function is slightly different to the other optimisation functions in the package. In this case, because the problem of local maxima in the likelihood response surface is particularly acute (due to the potential overlap in the selectivities of different gears), so the annealing process is replicated many times from different randomly selected initial conditions. We refer to these replicates as ‘chains’. Each chain follows a different pathway through the parameter space. At the end of the process, the best-fit set of activity multipliers is selected from across all the chains. In addition, the coefficient for jiggling the parameters is systematically attenuated with increasing iterations rather than remaining constant or potentailly being manually attenuated during the run my the user. Because the process uses only the fishing fleet model it is relatively fast so many chains can be run in a moderate time span.


To cope with the overlap in selectivity of the fishing gears, the function uses a set of linkage parameters specified in the the file /Parameters/fishing_fleet_gear_linkages.csv These parameters force selected gears activities to vary in concert \(\pm\) some variation, rather than independently. The parameters for the gear linkages are located in the file ../Modelname/Variantname/Parameters/fishing_fleet_gear_linkages.csv. The table of linkages specifies which gear activity rates are forced to vary in concert during the fitting process, as opposed to varying independently. The value of the linkage coefficient defines the scaling of changes in the activity rate of a dependent gear relative to its linked independent gear. For example, if gear 8 is permitted to vary independently (value in column “Gear to which linked” = NA and “Linkage coefficient” = NA). If gear 9 is dependent on gear 8 then the activity rate of gear 9 this would be specified by e.g. “Gear to which linked” = 8 and “Linkage coefficient” = 0.645. This would force the activity of gear 9 to be set at gear8_activity * (0.645 \(\pm\) a random variation defined by the function argument deltaGrat).


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) range of the real time plot can be varied during the run by editing the setup file annealing_SD_fishing.csv


Once all the chains have been completed the function produces some diagnostic box and whisker plots showing the uncertainty in the estimated activity rate multipliers and in the estimated harvest ratios across the end-points of all the chains. In each diagnostic plot the maximum likelihood model results are shown by a red bar, and the distribution of all results by black box and whiskers.


Also at the end of the procedure a new version of the gear activity multipliers file is 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 distributional statistics of the likelihood-weighted activity multipliers at the end of each chain, and the emergent harvest ratios relative to the target values are saved as CSV files in the results folder (file names fitting_to_knownHR_gearmult_stats-*.csv and fitting_to_knownHR_HR_rel_target_stats*.csv, where * is the model.ident set by the read_model() function.


In order to use the new fitted parameter values in a subsequent run of the StrathE2E2 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 harvest ratio multiplier file. Or, to preserve the new activity rate multipliers and incorporate them into the fishing fleet model parameterisation, manually update the values in the file /Parameters/fishing_activity_parameters*.csv, by multiplying the existing values by the new multipliers emerging from the annealing process.


If the edited file fishing_activity_parameters*.csv is saved with a new identifier (*) then in order to use it in a subsequent run of the StrathE2E2 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 file. Then make sure to use a version of the multiplier file with all values set to 1.0 for all future runs.


# Copy the 1970-1999 version of the North Sea model supplied with the package into a user workspace (Windows OS):
copy_model("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<-read_model(model.name="North_Sea",
                  model.variant="1970-1999",
                  model.ident="TEST",
                  user.path="C:/Users/username/Documents/Models")
#
# Quick Demonstration of the annealing function in operation:
annealing_find_gear_activity_mult_HR_target(model, nchains=5, n_iter=100, start_temperature=0.5)
#
# More realistic configuration would be :
annealing_find_gear_activity_mult_HR_target(model, nchains=100, n_iter=3000, start_temperature=0.5)
# (WARNING - this will an hour or so to run)
#



5 Sensitivity analysis

5.1 Background

Sensitivity analysis helps to highlight the parameters which have the most influence in the simulated annealing optimisation process. In addition the analysis can help to identify parameters for which constraint by external information would be most beneficial.


Simple one-at-a-time sensitivity analysis of parameters in a model is a straightforward process when there are few parameters and relatively little interaction between parameters. However, StrathE2E2 include many parameters and there is a strong possibility of interactions, so a more sophisticated scheme is required.


The R package includes a function to perform global analysis of parameter sensitivity using the Morris method (Morris, 1991). This involves a factorial sampling scheme to generate parameter values for replicate model runs and generate values for the ‘elementary effect’ (EE) of each parameter. The mean and standard deviation of EE values over many runs allows ranking of the parameters in terms of the sensitivity of their effects on the model, and the strength of interactions with other parameters.


The parent parameter set for the sensitivity analysis (\(\theta\)) incorporates all of the parameters and inputs to the model, i.e. the maximum-likelihood set of fitted ecology model parameters produced by the simulated annealing scheme, plus the fixed ecological parameters, the physical configuration parameters of the model (layer thicknesses, inshore/offshore areas), the parameters passed to the ecology model from the fishing fleet model, and the fishing activity rates and environmental driving data . The sensitivity to the environmental driving data is investigated by applying a scaling factor uniformly to the annual cycle of environmental data values.


From this parent set, a series of child-sets (\(\theta_{k}^{*}\) where \(1 \ge k \ge r\)) is generated by applying a separate random increment to each parameter; \(\theta_{k}^{*} = \theta + \delta[k]\) where \(\delta[k]\) is a vector of random values from a gaussian distribution of mean 0 and standard deviation given by a fixed coefficient of variation applied to the parent-set value of each parameter. This process is equivalent to that for generating parameter proposals in the simulated annealing scheme, except that all of the parameters and model inputs are varied in the sensitivity analysis, rather than just the subset of parameters to be fitted.


For each of the child-sets of parameters, the likelihood of the suite of observed data indices \(P(observations|\theta_{k,0}^{*})\) is calculated following runs of the model to stationary state, exactly as in simulated annealing scheme. We refer to these as trajectories.


Then, for each trajectory, the parameters (\(1 \ge i \ge n\)) are varied in turn, one at a time, by adding a fixed proportionality increment, the model re-run, and the likelihood computed \((P(observations|\theta_{k,i}^{*}))\). The proportionality increment for a given trajectory is drawn at random from a set of four fixed levels in the range \(\pm 10\%\) of the child parameter set (-10%, -5%, +5%, +10%, i.e. \(\Delta\) = 0.9, 0.95, 1.05, 1.10), so that:

\[\theta[i]_{k,i}^{*} = \theta[i]_{k,0}^{*} . \Delta[z]\]

where \(\theta[i]^{*}\) is the ith element of \(\theta^{*}\), \(\Delta[z]\) is the zth element of \(\Delta\), and z is drawn at random from the series (1, 2, 3, 4) for each value of \(k\). Hence, for each trajectory the model runs are repeated \(n+1\) times, where i=0 corresponds to the baseline run for each trajectory. The total number of nested runs to support the sensitivity analysis is thus \(r*(n+1)\).


From each level-run of the model (in which a single parameter is perturbed), and its corresponding likelihood, the elementary effect of the parameter is calculated as

\[EE_{k,i} = \frac{(P(observations|\theta_{k,i}^{*}) - P(observations|\theta_{k,0}^{*}))}{\sqrt{(\Delta[z]-1)^{2}}}\]


On completion of the runs for all trajectories, the mean (\(\mu_{i}\)) and standard deviation (\(S_i\)) of the r elementary effects for each parameter (i) are calculated. For the mean,

\[\mu_{i} = \frac{1}{r} \sum_{k=1}^{r} EE_{k,i}\]


The magnitude of the mean represents the sensitivity of each parameter, and the corresponding standard deviation indicates the degree of non-linearity in the response or interaction with other parameters. The standard error of the mean for each parameter (\(SEM_i\)) is given by:

\[SEM_i = \frac{S_i}{\sqrt{r}}\]


If \(S_i > |\mu_i | . \frac{\sqrt{r}}{2}\) then we can approximately conclude that \(\mu_i\) is significantly greater than zero.



5.2 Using the function Sensitivity_analysis_StrathE2E()

Table 16. Arguments of the function Sensitivity_analysis_StrathE2E().

Argument Description
model R-list object generated by the read_model() function which defines the model configuration
nyears Number of years to run the model in each iteration (default=50)
n_iter Number of trajectories of parameter sets (default=15)
trajsd Coefficient of variation used to set the standard deviation for the gaussian distribution from which new paramater values are drawn to create each trajectoy baseline from the initial parent values (default=0.0075)
n_setoflevels Number of fixed levels of coefficient of variation used to generate the individual parameter values in each level-run. Must be an even number (default=4)
v_setoflevels Maximum coefficient of variation for the set of levels (default=0.1, i.e. -10 percent to +10 percent)
coldstart (TRUE or FALSE, default=TRUE) Set to TRUE if the run is starting from cold, set to FALSE if the run is a continuation of a previous run. This is to enable the task to be divided up across multiple processors and the results concatenated afterwards - set coldstart=TRUE for only one of the runs, and coldstart=FALSE for all the others
quiet (TRUE or FALSE, default=TRUE) Suppress informational messages at the start of each iteration
postprocess (TRUE or FALSE, default=TRUE) Process the results through to a final sorted list of parameter sensitivies for plotting, or just produce the raw results. The reason for NOT processing would be if the job has been shared across multiple machines/processors and several raw result files need to be concatenated before processing


The function performs a one-at-a-time parameter sensitivity analysis on the StrathE2E2 model using the Morris Method (Morris, 1991) for factorial sampling of the physical configuration parameters, ecology model parameters, the fishing fleet model parameters, and the environmental forcings.


WARNING - The total number of model runs required to support the analysis is \(r*(n+1)\) where \(r\) is the number of trajectories and \(n\) is the number of parameters. The function incorporates all of the physical configuration parameters, ecology model parameters, the fishing fleet model parameters, and the environmental forcings into the analysis, and \(r = 453\). The mininimum recommended number of trajectories is 16, and each model run needs to be sufficiently long to achieve a stationary state. Hence run-times for this function are several days (around 200 hours with the default settings). However, it is possible to spread the load over multiple processor/machines and concatenate the results at the end into a single results file for post-processing.


The process requires an initial set of parameters for the model. We refer to this as the ‘parent’ parameter set. It is recommended that this should be the parameters producing the maximum likelihood of the observational target data (as estimated by e.g. the annealing_find_ecology_parameters() function). The MODEL_SETUP.csv file in the folder /ModelName/VariantName/ should be configured to point to the relevant files, and then loaded with the read_model() function.


On completion of all the trajectories in the run, the raw resuts are (optionally) post-processed to generate the mean and standard deviations of all the EE values for each parameter is calculated. EE_mean is an index of the magnitude of the sensitivity, and EE_sd is an index of the extent of interaction with other parameters.


During the run process the function produces a real-time plot for each trajectory, in which the x-axis represents the parameter sequence, and the y-axis is the likelihood of the target data. A horizontal red line indicates the likelihood of the parent parameter set, horizontal grey line indicates the likelihood for each trajectory baseline and each level-run likelihood is shown by a symbol. The y-axis range can be changed in real-time by editing the setup file /ModelName/VariantName/Parameters/Parameter_SD_Control/OATsensitivity_SD.csv


The outputs from the function are directed to CSV files in the current /results folder. The outputs are: a) Table of parameter values applied in each run of the model (OAT_parameter_values-*.csv, where * = model.ident as defined by read_model()) b) Table of the likelihood and EE value for each trajectory/level run (OAT_results-*.csv) c) (Optionally, and also as a dataframe) Table of Mean EE and standard deviatiion of EE for each parameter, sorted by the absolute value of EE_mean (sorted_parameter_elemental_effects-*.csv)


Arguments available here in Sensitivity_analysis_StrathE2E() to allow for management of sharing the computational load across multiple processors. Afterwards, the raw results files can then be be combined into a single data set using the concatenate_raw_sensitivity_analysis_results() function.


A separate function plot_sensitivity_analysis_results() produces a graphical representation of the EE_mean and EE_sd results.


Example results data for both variants of the North Sea model generated with the default function settings are included in the package and can be plotted by setting an argument in the plot_sensitivity_analysis_results() function.


# Load the 2003-2013 version of the North Sea model supplied with the package:
model <- read_model("North_Sea", "1970-1999")
#
# Run the sensitivity analysis process:
# WARNING - Running a full sensitivity analysis takes days of computer time on a single machine/processor because it involves a huge number of model runs.
# The example below is just a (relatively) quick minimalist demonstration and should NOT be taken as the basis for any analysis or conclusions.
# Even so, this minimalist demo could take 45 min to run to completion because it involves 1359 model runs.
sens_results <- Sensitivity_analysis_StrathE2E(model, nyears=1, n_iter=3)
head(sens_results)
#
# A more realistic sensitivity analysis would be something like:
sens_results <- Sensitivity_analysis_StrathE2E(model, nyears=50, n_iter=16, postprocess=TRUE)
# DO NOT launch this configuration unless you are prepared to wait many days for the results
#
# To share the computational load across two (or more) machines/processors, launch separately on each machine...
model1 <- read_model("North_Sea", "1970-1999", model.ident="TEST1")
Sensitivity_analysis_StrathE2E(model1, nyears=50, n_iter=10, coldstart=TRUE, postprocess=FALSE)   # On machine 1
#
model2 <- read_model("North_Sea", "1970-1999", model.ident="TEST2")
Sensitivity_analysis_StrathE2E(model2, nyears=50, n_iter=10, coldstart=FALSE, postprocess=FALSE)  # On machine 2
# In these cases the function returns a NULL object since postprocess=FALSE but the raw data are still output to CSV
#
# Then concatenate the two raw results files with text-tags TEST1 and TEST2 afterwards, and post process
# the combined file, using the function concatenate_raw_sensitivity_analysis_results()
#


5.2.1 Using the function concatenate_raw_sensitivity_analysis_results()

Table 17. Arguments of the function concatenate_raw_sensitivity_analysis_results().

Argument Description
model R-list Model object for the first set of raw data to be combined
ident.list A vector of text variables corresponding to the “model.ident” identifiers for each of the files to concatenated (list must be length 2 or greater)
combined.ident Identifier for the combined set of data, equivalent to the model.ident argument in read_model(). Default =“COMBINED”
postprocess (TRUE or FALSE, default=TRUE) Process the results through to a final sorted list of parameter sensitivies for plotting, or just produce the combined raw results. The reason for NOT processing would be if there are further run results stil to be combined with the set produced by this function

Combines two or more sets of raw output data from sensitivity analysis runs performed on separate machine/processors


The function Sensitivity_analysis_StrathE2E() is extremely time consuming so it makes sense to share the load across multiple processors and combine the results afterwards. This function concatenates the raw outputs from two or more separate runs of Sensitivity_analysis_StrathE2E() into a single file.


Sensitivity_analysis_StrathE2E() generates two output files per run - OAT_results-*.csv, and OAT_parameter_values-*.csv, where * is an identifying text string set by an argument of the read_model() function, This concatenation function combines both of these types of files.


The files to be combined must be transferred into the same folder, and this is where the new combined file will be placed. The path to locate the files is set in the read_model() function. If not specified it is assumed that the files are located in the default /results/Modelname/Variantname folder in the current user workspace.


The list of files to be combined (any number > 1) is defined by a vector of their “model.ident” identifiers (“ident.list” argument). The first-named set of files should correspond to a run of the Sensitivity_analysis_StrathE2E() function with the argument coldstart=TRUE. Thus forces the first trajectory of sensitivity test to be performed on the maximum-likelihood parameter set loaded with the read_model() function. Thus is important for the post-processing stage of the analysis which needs to be performed on the combined results.


When combining the files, the function creates a seamless sequence of trajectory identifiers through the combined data, beginning from 1 for the first trajectory of the first set.


If for any reason there are more than two separate sets of Sensitivity_analysis_StrathE2E() run results to be combined, then post-processing of the final combined file can be delayed with the postprocess argument until the last concatenation when all the data have been gathered together - using the function process_sensitivity_analysis_results_offline().


A separate function plot_sensitivity_analysis_results() produces a graphical representation of the post-processed results of the combined data.


# The example here assumes that three sets of raw results data have been previously
# generated by runs of the Sensitivity_analysis_StrathE2E() function, with the model.ident values
# assigned as "RUN1", "RUN2" and "RUN3", and that these have been gathered together in the same
# /results/Modelname/Variantname folder.
# Then... load the model name and version for the data to be combined :
# E.g. ... model <- read_model("North_Sea", "2003-2013")
#    sens_results <- concatenate_raw_sensitivity_analysis_results(model, ident.list=c("RUN1","RUN2","RUN3"), combined.ident="TESTCOMB", postprocess=TRUE)
#    head(sens_results)


5.2.2 Using the function process_sensitivity_analysis_results_offline()

Table 18. Arguments of the function process_sensitivity_analysis_results_offline().

Argument Description
model R-list object defining the model configuration compiled by the read_model() function
use.example (TRUE or FALSE, default = FALSE). Plot pre-computed example data from either of the North Sea model variants rather than user-generated data


The function reads the file of raw sensitivity analysis data (OAT_results-*.csv, where * refers to the identifier model.ident set in the read_moldel() function) from a /results folder and performs the post-processing that would ordinarily be done automatically within the Sensitivity_analysis_StrathE2E() or concatenate_raw_sensitivity_analysis_results() functions. The function is provided as a backup to mitigate against data loss in the event of some interruption to the normal automatic data processing since running a sensitivity analysis represents a significant investment of computer time.


The raw data input is a table of Elementary Effect values for each run of the model. Model runs are organised by trajectories which consist of a baseline run in which all parameters are perturbed from an initial state by the addition of terms drawn from a random normal of mean zero, plus a set of runs in which each parameter in turn is perturbed by a fixed amount.


The function returns a dataframe and a CSV output file of post-processed data containing the mean Elementary Effect (EE_mean) and the standard deviation of EE (EE_sd) for each parameter, sorted by the absolute value of EE_mean. EE_mean is an index of the magnitude of the sensitivity of a parameter, and EE_sd is an index of the extent of interaction with other parameters.


Example raw results data for both variants of the North Sea model generated with the default function settings are included in the package and can be processed by setting the use.example argument to TRUE.


# Load the pre-computed data for the 1970-1999 version of the North Sea model supplied with the package:
model <- read_model("North_Sea", "1970-1999")
sens_results <- process_sensitivity_analysis_results_offline(model, use.example=TRUE)
[1] "Reading internally stored example results for the North_Sea 1970-1999 model"
[1] "Output wil be directed to the folder  results/North_Sea/1970-1999/"
head(sens_results)
      parametername parameterid fixfit    EEmean     EEsd EEmean_non_0
357             aFp         488      1 -3.178710 1.196653          sig
204     uherb_carnt         335      0 -3.147686 1.597756          sig
350              aC         481      1 -2.921506 1.618917          sig
356          aFdlar         487      1 -2.790875 1.311492          sig
244 uherb_fishdlart         375      0 -2.579706 1.293787          sig
220    uherb_fishpt         351      0 -2.450371 1.246475          sig
    Ntrajectories      Parameter.class   Parameter.description
357            16  Ecology model fixed Assimilation efficiency
204            16 Ecology model fitted     Maximum uptake rate
350            16  Ecology model fixed Assimilation efficiency
356            16  Ecology model fixed Assimilation efficiency
244            16 Ecology model fitted     Maximum uptake rate
220            16 Ecology model fitted     Maximum uptake rate
                               Model.guild.or.feature
357                                Planktivorous fish
204 Omnivorous zooplankton by carnivorous zooplankton
350                           Carnivorous zooplankton
356                               Demersal fish lavae
244    Omnivorous zooplankton by demersal fish larvae
220      Omnivorous zooplankton by planktivorous fish


5.2.3 Using the function plot_sensitivity_analysis_results()

Table 19. Arguments of the function plot_sensitivity_analysis_results().

Argument Description
model R-list object defining the model configuration compiled by the read_model() function
use.example (TRUE or FALSE, default = FALSE). Plot pre-computed example data from either of the North Sea model variants rather than user-generated data


Reads results generated by the function Sensitivity_analysis_StrathE2E() and plots the Elementary Effect mean (x-axis; magnitude of sensitivity) against Elementary Effect standard deviation (y-axis; strength of interactions between parameters).


Results from the Sensitivity_analysis_StrathE2E() function are stored in the CSV file /results/ModelName/VariantName/sorted_parameter_elementary_effects-*.csv where * represents the model run identifier (model.ident) text embedded in the R-list object created by the read_model() function.


Each symbol in the plot represents a single parameter in the model. The parameters are colour-coded to indicate 6 different types - fitted and fixed parameters of the ecology model, fishing fleet model parameters, fishery harvest ratios, environmental drivers, and physical configuration parameters.


The plot also shows a wedge formed by the two dashed lines. These correspond to \(\pm\) 2 standard errors of the mean, so for points falling outside of the wedge there is a significant expectation that the distribution of elementary effects is non-zero. For points falling within the wedge the distribution of elementary effects is not significantly different from zero


Example data for both variants of the North Sea model are provided with the package and can be plotted using the use.example argument.


# Load the 1970-1999 version of the North Sea model supplied with the package:
# model <- read_model("North_Sea", "1970-1999")
# Run the Sensitivity analysis and generate the results files
# e.g.   Sensitivity_analysis_StrathE2E(model,nyears=50,n_iter=16)
#
# ..or
#
# Read the example data provided with the package :
model <- read_model("North_Sea", "1970-1999")
plot_sensitivity_analysis_results(model, use.example=TRUE)
[1] "Reading internally stored example results for the North_Sea 1970-1999 model"

Figure 21. Results from a sensitivity analysis of the 1970-1999 North Sea model with default analysis settings.


# To direct the graph output to a file rather than the screen, wrap the plot_sensitivity_analysis_results() function call in a graphical device call:
pdf("C:/Users/username/Documents/Foldername/plot.pdf",width=6,height=6)      # or jpeg("plot.jpg"), png("plot.PNG")
    plot_sensitivity_analysis_results(model)
dev.off()



6 Monte Carlo simulations of credible interval for model outputs

6.1 Background

Computation of credible intervals involves a Monte Carlo simulation in which the initial (baseline) parameters are the maximum-likelihood set produced by the simulated annealing parameter optimization scheme. From this baseline, a series of new parameter sets is generated by adding increments to each parameter drawn from uniform distributions of mean 0 and a and symetrical ranges corresponding to a given coefficient of variation.


For each of the new parameter sets, the likelihood of the suite of observed data indices \(P(observation|\theta_{k}^{*})\) is calculated following a run of the model to stationary state (as described in section 5 on simulated annealing), and all the output from the final, stationary year of each run is saved (\(k\) = 0 to \(r\), where \(k\) = 0 corresponds to the maximum likelihood (baseline) parameter set).


To calculate the credible interval for any direct or derived model output variable (e.g. annual average mass density of a state variable, or the mass density on a given day in the final year), the values from the individual model runs (\(V_k\)) and the associated likelihoods (\(P_k\)) are assembled as a list of (\(r + 1\); \(k\) = 0 to \(r\)) pairs (\(a_k\) = (\(V_k\),\(P_k\))). The list for each variable is then sorted by ascending values \(V\) (\(a_j\) ; \(j = 1\) to (\(r + 1\)) such that \(V_{j} \ge V_{(j-1)}\)). Then, the cumulative likelihood and the cumulative likelihood with increasing variable value is calculated as follows

\[C_j = (P_{j=1}, \sum_{j=1}^{j=2} P_{j}, \sum_{j=1}^{j=3} P_{j}, \sum_{j=1}^{j=4} P_{j} ... \sum_{j=1}^{j=(r+1)} P_{j} )\]

Proportions of the maximum cumulative likelihood are then caclulated as \(Q_{j} = C_{j} / C_{(r+1)}\)


Finally, values of \(V\) corresponding to discrete values of \(Q\) = (0.005, 0.25, 0.5, 0.75, 0.995) are extracted by interpolation. These values span the 0.5% and 99.5% credible intervals of the model output given the observed target data and uncertainty in the fitted ecology parameters. Note that uncertainties in the fixed ecology parameters, fishing fleet parameters, and environmental driving data are not reflected in these credible intervals.



6.2 Using the function Monte_Carlo_StrathE2E()

Table 20. Arguments of the function Monte_Carlo_StrathE2E().

Argument Description
model R-list object generated by the read_model() function which defines the model configuration
nyears Number of years to run each instance of the model. Needs to be long enough to allow the model to attain a stationary state (default=50)
n_iter Number of iterations of the model (default=500, roughly the minimum needed to provide a stable set of credible intervals)


Runs a Monte Carlo simulation with StrathE2E and derives centiles of credible values of model outputs


The Monte Carlo scheme generates an ensemble of model runs by sampling the ecology model parameters from uniform distibutions centred on a maximum likelihood parameter set. The latter needs to be arrived at by prior application the various simulated annealing functions in the package to ‘fit’ the model to a suite of observational data on the state of ecosystem (target data for fitting are in /ModelName/VariantName/Target_data/annual_target_data_*.csv). Each iteration in the Monte Carlo scheme then generates a unique time series of model outputs at daily intervals, together with the overall likelihood of the obervational target data.


The process needs to be loaded by a prior call of the read_model() function. This represents the baseline for sampling of the ecology model parameters.


The coefficients of variation for jiggling the ecology parameters can be varied in real-time during the run by editing the file CredIntSim_SD.csv in the folder /Parameters/Parameter_SD_control of the model version. However, it is recommended to leave the setting constant, and the same for each parameter type, for the duration of a run. Sensible values for the coefficient of variation are in the range 0.1 to 0.15.


On completion of all the iterations of the model, for each model output variable in turn, values from the individual runs and their associated model likelihoods are assembled as a list of paired values. The list is then sorted by ascending values of the model variable, and the cumulative likelihoods with increasing value of model variable is calculated. Values for the model variable at standard proportions (0.005, 0.25, 0.5, 0.75, 0.995) of the maximum cumulative likelhood are then extracted by interpolation. These represent the credible intervals of model output given uncertainty in the ecology model parameters.


Outputs from the Monte_Carlo_StrathE2E() function are stored in CSV files in the folder /results/ModelName/VariantName/CredInt with an identifier for the simulation (model.ident) created by the read_model() function. There are two types of output. First is simply an accumulation of all the standard outputs from StrathE2E2 on a run-by-run basis. The output of these data is updated every 10 iterations for security to mitigate against data loss in the event of an unforseen interruption of a simulation. The second type of output is the results of post-processing the raw data to generate the centile of the distribution of credible values.


The function displays various real-time graphics to show the progress of the simulation. During the StrathE2E2-running phase of the process an x-y graph is updated after each iteration (x-axis=iterations, y-axis=Likelihood), with a horizontal grey line showing the maximum liklihood result, and symbols showing each iteration. The y-axis limits for the graph can be varied in real-time during the run by editing the file CredIntSim_SD.csv in the folder /Parameters/Parameter_SD_control of the model version.


During the post-processing phase, an x-y graph of the cumulative likelihood (y-axis) vs output variable values, is displayed as the code works through all of the output variables.


WARNING - the scheme can take a long time to run (about 14 hours with the default settings), and generate large output files. The estimated run-time (hours) is given by (nyears * n_iter * 2) / 60 / 60 (i.e. around 2 sec per yer of simulation). Withe the default setting this represents about 14 hours.


Example CSV outputs from the Monte Carlo function with default settings for both versions of the in-built North Sea model are provided in the package. The files are stored in the package folders /extdata/Example.results/North_Sea/Variantname/Credint with the text identifiers -Variantname-example. These can be accessed from all of the credible interval plotting functions by means of an argument setting.


# Load the 1970-1999 version of the North Sea model supplied with the package and assign an identifier text string:
model <- read_model("North_Sea", "1970-1999", model.ident="demo")
#Run the Monte Carlo process with demonstration settings and generate the results files
Monte_Carlo_StrathE2E(model, nyears=30, n_iter=50)
# WARNING - this demonstration run will take about 1 hour. 


6.2.1 Using the function plot_Monte_Carlo_parameter_distributions()

Table 21. Arguments of the function plot_Monte_Carlo_parameter_distributions().

Argument Description
model R-list object defining the model configuration compiled by the read_model() function
use.example (TRUE or FALSE, default = FALSE). Plot pre-computed example data from either of the North Sea model variants rather than user-generated data


Create a plot showing the credible distributions of ecology model parameters based on the results from the Monte_Carlo_StrathE2E() function. These distributions are formed from the input distributions to the Monte Carlo process, weighted by the likelihood of observed target data on the state of the ecosystem given each combination of parameter values.


Post-processed data from the Monte_Carlo_StrathE2E() function are stored in the file /results/Modelname/Variantname/CredInt/CredInt_processed_parameters-*.csv, where * represents the model run identifier (model.ident) text embedded in the R-list object created by the read_model() function.


Each parameter in the plot is scaled to its maximum likelihood value as \(frac{(value - max.likelihood.value)}{max.likelihood.value}\). Each parameter is then represented by a box and whisker plot which shows the distribution of credible parameter values around zero, i.e. around the maximum likelihood value. The median of the credible values distribution for each parameter is shown my a black tick-mark. The box spans the 50% credible interval (quartiles of the cumulative likelihood of simulated values). Whisker lines span the 99% credible interval.


The individual parameters are identified by numbers (rather than text names). These numnbers correspond to the column numnbers in the file /results/Modelname/Variantname/CredInt/CredInt_processed_parameters-*.csv


The input distribution of parameter values to the Monte Carlo process is drawn from a random uniform distribution with limits specified in the CredINtSim_SD control file for the model setup (located in a sub-folder of the /Parameters folder). This distribution is shown by a red box and whisker at the bottom of the plot. Given the random uniform input we expect the quartiles (limits of the box) to be symetrical and located mid-way between zero and the upper and lower extremes. Vertical red lines show the expected limits of the quartiles boxes if model results were completely insensitive to individual parameter values.


The extent to which individual parameter distributions deviate from the random uniform input is an indication of their sensitivity in the model. Parameters whose distributions are tightly confined around zero (the maximum likelihood value) are highly sensitive.


For some parameters, in particular the preference parameters, their credible distributions may span a wider range than the inputs. This may seem unexpected, but arises because within each feeding guild the preference parameters are not independent of each other. The preferences within each guild must sum to 1. Hence, during the Monte Carlo process, after drawing new values of the preference values they are all rescaled to sum to 1, which may mean that some of them will have been varied by more than the original coefficient of variation of the input random uniform.


Example data for both variants of the North Sea model are provided with the package and can be plotted using the use.example argument.


# Load the 1970-1999 version of the North Sea model supplied with the package:
model <- read_model("North_Sea", "1970-1999")
# Run the Monte Carlo process and generate the results files
# e.g.   Monte_Carlo_StrathE2E(model,nyears=50,n_iter=500)
#
# ..or
#
# Read the example data provided with the package:
plot_Monte_Carlo_parameter_distributions(model, use.example=TRUE)
Reading internally stored example results for the North_Sea 1970-1999 model

Figure 22. Plot of the output distribution of parameter values in the Monte Carlo simulation for the 1970-1999 North Sea model, i.e. the input values weighted by the likelihood of the observed target data for each combination. The box and whisker plot for each parameter is centred on the baseline maximum likelihood value. The red box and whisker shows the input distribution


6.2.2 Using the function plot_final_year_time_series_data_with_credible_intervals()

Table 22. Arguments of the function plot_final_year_time_series_data_with_credible_intervals().

Argument Description
model R-list object defining the model configuration compiled by the read_model() function
selection Text string from a list identifying the group of model output variables to be plotted. Select from: “NUT_PHYT”, “SEDIMENT”, “ZOOPLANKTON”, “FISH”, “BENTHOS”, “PREDATORS”, “CORP_DISC”, “MACROPHYTE”, Remember to include the phrase within "" quotes
use.example (TRUE or FALSE, default = FALSE). Plot pre-computed example data from either of the North Sea model variants rather than user-generated data


Create multi-panel plots showing the credible intervals of state variable densities over the final year of a simulation generated by the Monte_Carlo_StrathE2E() function


Each panel of the plot shows a time-series of the densities (per unit sea surface area or layer volume) of a state variable over the final year of a run. The data displayed are the solution to the maximum likelihood model, together with centiles of the distribution of credible values. The distribution of credible values is derived from a Monte Carlo simulation scheme performed by the Monte_Carlo_StrathE2E() function.


Post-processed daily interval state variable data from the Monte_Carlo_StrathE2E() function are stored in the file /results/ModelName/VariantName/CredInt/CredInt_processed_daily_mass-*.csv, where * represents the model run identifier (model.ident) text embedded in the R-list object created by the read_model() function. Depending on the value set for the selection argument in the function, different groups of variables are extracted for plotting in each multi-panel page.


In each plot the x-axis represents day of the year over an annual cycle. The y-axis represents mass density of a state variable (mMN.m-2 or mMN.m-3). Results from the maximum likelihood model are shown by a red line. The median of the credible values distribution is shown my a solid black line. A grey-shaded area indicates the 50% credible interval (spanning quartiles of the cumulative likelihood of simulated values). Black dashed lines span the 99% credible interval.


Example data for both variants of the North Sea model are provided with the package and can be plotted using the use.example argument.


In each of the plots that follows, the maximum likelihood model is shown by a red line. The median of the credible values distribution is shown my a solid black line. A grey-shaded area indicates the 50% credible interval (spanning quartiles of the cumulative likelihood of simulated values). Black dashed lines span the 99% credible interval.


# Load the 1970-1999 version of the North Sea model supplied with the package:
# model <- read_model("North_Sea", "1970-1999")
# Run the Monte Carlo process and generate the results files
# e.g.   Monte_Carlo_StrathE2E(model,nyears=50,n_iter=500)
#
# ..or
#
# Read the example data provided with the package :
model <- read_model("North_Sea", "1970-1999")
plot_final_year_time_series_data_with_credible_intervals(model, "NUT_PHYT", use.example=TRUE)   # plot nutrient and phytoplankton data
Reading internally stored example results for the North_Sea 1970-1999 model
Plot Offshore zone upper layer and Suspended bact & detritus 
Plot Offshore zone upper layer and Ammonia 
Plot Offshore zone upper layer and Nitrate 
Plot Offshore zone upper layer and Phytoplankton 
Plot Offshore zone lower layer and Suspended bact & detritus 
Plot Offshore zone lower layer and Ammonia 
Plot Offshore zone lower layer and Nitrate 
Plot Offshore zone lower layer and Phytoplankton 
Plot Inshore zone and Suspended bact & detritus 
Plot Inshore zone and  Ammonia 
Plot Inshore zone and Nitrate 
Plot Inshore zone and Phytoplankton 

Figure 23. Final year time series of nutrient and phytoplankton concentrations (mMN.m-3) in each zone and layer.


model <- read_model("North_Sea", "1970-1999")
plot_final_year_time_series_data_with_credible_intervals(model, "SEDIMENT", use.example=TRUE)   # plot sediment chemisty data
Reading internally stored example results for the North_Sea 1970-1999 model
Plot Offshore mud and Sediment bact. & detritus 
Plot Offshore mud and Porewater nitrate 
Plot Offshore mud and Porewater ammonia 
Plot Offshore sand and Sediment bact. & detritus 
Plot Offshore sand and Porewater nitrate 
Plot Offshore sand and Porewater ammonia 
Plot Inshore mud and Sediment bact. & detritus 
Plot Inshore mud and Porewater nitrate 
Plot Inshore mud and Porewater ammonia 
Plot Inshore sand and Sediment bact. & detritus 
Plot Inshore sand and Porewater nitrate 
Plot Inshore sand and Porewater ammonia 

Figure 24. Final year time series of sediment detritus and nutrient concentrations (N % dry weight or mMN.m-3) in each zone and sedient type.


model <- read_model("North_Sea", "1970-1999")
plot_final_year_time_series_data_with_credible_intervals(model, "ZOOPLANKTON", use.example=TRUE)    # plot zooplankton data
Reading internally stored example results for the North_Sea 1970-1999 model
Plot Offshore zone  and Omnivorous zooplankton 
Plot Offshore zone and Carnivorous zooplankton 
Plot Inshore zone and Omnivorous zooplankton 
Plot Inshore zone  and Carnivorous zooplankton 

Figure 25. Final year time series of zooplankton concentrations (mMN.m-2) in each zone.


model <- read_model("North_Sea", "1970-1999")
plot_final_year_time_series_data_with_credible_intervals(model, "FISH", use.example=TRUE)       # plot fish and fish larvae data
Reading internally stored example results for the North_Sea 1970-1999 model
Plot Offshore zone and Planktivorous fish 
Plot Offshore zone and Planktivorous fish larvae 
Plot Offshore zone and Demersal fish 
Plot Offshore zone and Demersal fish larvae 
Plot Inshore zone and Planktivorous fish 
Plot Inshore zone and Planktivorous fish larvae 
Plot Inshore zone and Demersal fish 
Plot Inshore zone and Demersal fish larvae 

Figure 26. Final year time series of fish and fish larvae concentrations (mMN.m-2) in each zone.


model <- read_model("North_Sea", "1970-1999")
plot_final_year_time_series_data_with_credible_intervals(model, "BENTHOS", use.example=TRUE)    # plot benthos and benthos larvae data
Reading internally stored example results for the North_Sea 1970-1999 model
Plot Offshore zone and Susp./dep. benthos 
Plot Offshore zone and Susp./dep. benthos larvae 
Plot Offshore zone and Carn./scav. benthos 
Plot Offshore zone and Carn./scav. benthos larvae 
Plot Inshore zone and Susp./dep. benthos 
Plot Inshore zone and Susp./dep. benthos larvae 
Plot Inshore zone and Carn./scav. benthos 
Plot Inshore zone and Carn./scav. benthos larvae 

Figure 27. Final year time series of benthos and benthos larvae concentrations (mMN.m-2) in each zone.


model <- read_model("North_Sea", "1970-1999")
plot_final_year_time_series_data_with_credible_intervals(model, "PREDATORS", use.example=TRUE)  # plot bird, pinniped and cetacean data
Reading internally stored example results for the North_Sea 1970-1999 model
Plot Offshore zone and Birds 
Plot Offshore zone and Pinnipeds 
Plot Offshore zone and Cetaceans 
Plot Offshore zone and Migratory fish 
Plot Inshore zone and Birds 
Plot Inshore zone and Pinnipeds 
Plot Inshore zone and Cetaceans 
Plot Offshore zone and Migratory fish 

Figure 28. Final year time series of bird, pinniped, cetacean and migratory fish concentrations (mMN.m-2) in each zone.


model <- read_model("North_Sea", "1970-1999")
plot_final_year_time_series_data_with_credible_intervals(model, "CORP_DISC", use.example=TRUE)  # plot corpse and discard data
Reading internally stored example results for the North_Sea 1970-1999 model
Plot Offshore zone and Seabed corpses 
Plot Offshore zone and Fishery discards 
Plot Inshore zone and Seabed corpses 
Plot Inshore zone and Fishery discards 

Figure 29. Final year time series of corpse and discard concentrations (mMN.m-2) in each zone.


model <- read_model("North_Sea", "1970-1999")
plot_final_year_time_series_data_with_credible_intervals(model, "MACROPHYTE", use.example=TRUE) # plot macrophyte data
Reading internally stored example results for the North_Sea 1970-1999 model
Plot Inshore zone and Macrophytes 
Plot Inshore zone and Macrophyte debris 

Figure 30. Final year time series of macrophyte and macrophyte debris concentrations (mMN.m-2) in the inshore zone.


# To direct the graph output to a file rather than the screen, wrap the plot_final_year_data_with_credible_intervals() function call in a graphical device call:
# Since the plot pages contain different numbers of panels the recommended width:height ratios are as follows:
#   NUT_PHYT    1.5  : 1,  e.g. width=7,height=4.667
#   SEDIMENT    0.67 : 1,  e.g. width=4,height=6
#   ZOOPLANKTON     1    : 1,  e.g. width=4,height=4
#   FISH        2    : 1,  e.g. width=6,height=3
#   BENTHOS     2    : 1,  e.g. width=6,height=3
#   PREDATORS   2    : 1,  e.g. width=6,height=3
#   CORP_DISC   1    : 1,  e.g. width=4,height=4
#   MACROPHYTE  2    : 1,  e.g. width=4,height=2
# For example:
pdf("C:/Users/username/Documents/Foldername/plot.pdf",width=7,height=4.667)      # or jpeg("plot.jpg"), png("plot.PNG")
    plot_final_year_time_series_data_with_credible_intervals(model, "NUT_PHYT")
dev.off()


6.2.3 Using the function plot_final_year_migration_data_with_credible_intervals()

Table 23. Arguments of the function plot_final_year_migration_data_with_credible_intervals().

Argument Description
model R-list object defining the model configuration compiled by the read_model() function
use.example (TRUE or FALSE, default = FALSE). Plot pre-computed example data from either of the North Sea model variants rather than user-generated data


Create a multi-panel plot showing the credible intervals of inshore-offshore net active migration fluxes over the final year of a simulation generated by the Monte_Carlo_StrathE2E() function.


Daily interval post-processed data from the Monte_Carlo_StrathE2E() function are stored in the file /results/ModelName/VariantName/CredInt/CredInt_processed_daily_migrations-*.csv, where * represents the model run identifier (model.ident) text embedded in the R-list object created by the read_model() function.


Each panel of the plot shows a time-series of the net flux densities (mMN.m-2.d-1 sea surface area) of one of the migratory guilds in the model (all three guilds of fish, birds, pinnipeds and cetaceans) between the inshore and offshore zones, over the final year of a run. These migration fluxes are the dynamic product of gradients in the ratio of food concentration to predator concentration across the inshore-offshore boundary. Results from the maximum likelihood model are shown by a red line. The median of the credible values distribution is shown my a solid black line. A grey-shaded area indicates the 50% credible interval (spanning quartiles of the cumulative likelihood of simulated values). Black dashed lines span the 99% credible interval.


Positive values of the net migration flux indicate net movement from the offshore to inshore zone. Negative values indicate net movement from inshore to offshore.


Example data for both variants of the North Sea model are provided with the package and can be plotted using the use.example argument.


# Load the 2003-2013 version of the North Sea model supplied with the package:
# model <- read_model("North_Sea", "1970-1999")
# Run the Monte Carlo process and generate the results files
# e.g.   Monte_Carlo_StrathE2E(model,nyears=50,n_iter=500)
#
# ..or
#
# Read the example data provided with the package :
model <- read_model("North_Sea", "2003-2013")
plot_final_year_migration_data_with_credible_intervals(model, use.example=TRUE)
Reading internally stored example results for the North_Sea 2003-2013 model

Figure 31. Final year time series of active migration fluxes between the offshore and inshore zones (mMN.m-2.d-1).


# To direct the graph output to a file rather than the screen, wrap the plot_final_year_migration_data_with_credible_intervals() function call in a graphical device call:
pdf("C:/Users/username/Documents/Foldername/plot.pdf",width=6,height=4)      # or jpeg("plot.jpg"), png("plot.PNG")
    plot_final_year_migration_data_with_credible_intervals(model)
dev.off()


6.2.4 Using the function plot_final_year_trophic_data_with_credible_intervals()

Table 24. Arguments of the function plot_final_year_trophic_data_with_credible_intervals().

Argument Description
model R-list object defining the model configuration compiled by the read_model() function
use.example (TRUE or FALSE, default = FALSE). Plot pre-computed example data from either of the North Sea model variants rather than user-generated data


Create a two-panel box and whisker plot showing the credible intervals of whole domain mean trophic level and omnivory index of each food web component over the final year of a simulation generated by the Monte_Carlo_StrathE2E() function. The trophic indices originate from the NetIndices R-package.


Post-processed data from the Monte_Carlo_StrathE2E() function are stored in the file /results/ModelName/VariantName/CredInt/CredInt_processed_networkresults-*.csv, where * represents the model run identifier (model.ident) text embedded in the R-list object created by the read_model() function.


In each plot the maximum likelihood model is shown by a red bar. The median of the credible values distribution is shown by a black bar. The box indicates the 50% credible interval (spanning quartiles of the cumulative likelihood of simulated values). Whiskers span the 99% credible interval.


Within each panel the box and whisker plots for each food web component are ordered by the maximum likelihood mean trophic level.


NOTE that the NetIndices package assigns detritis and dissolved nutrients as trophic level 1, so that the phytoplankton and macrophytes are assigned trophic level 2.


Example data for both variants of the North Sea model are provided with the package and can be plotted using the use.example argument.


# Load the 2003-2013 version of the North Sea model supplied with the package:
# model <- read_model("North_Sea", "1970-1999")
# Run the Monte Carlo process and generate the results files
# e.g.   Monte_Carlo_StrathE2E(model,nyears=50,n_iter=500)
#
# ..or
#
# Read the example data provided with the package :
model <- read_model("North_Sea", "2003-2013")
plot_final_year_trophic_data_with_credible_intervals(model, use.example=TRUE)
Reading internally stored example results for the North_Sea 2003-2013 model

Figure 32. Final year indices of mean trophic level and omnivory for each guild in the model, ordered by the maximum likelihood mean trophic level.


# To direct the graph output to a file rather than the screen, wrap the final_year_trophic_data_with_credible_intervals() function call in a graphical device call:
pdf("C:/Users/username/Documents/Foldername/plot.pdf",width=4,height=6)      # or jpeg("plot.jpg"), png("plot.PNG")
    plot_final_year_trophic_data_with_credible_intervals(model)
dev.off()


6.2.5 Using the function plot_inshore_vs_offshore_anavmass_with_credible_intervals()

Table 25. Arguments of the function plot_inshore_vs_offshore_anavmass_with_credible_intervals().

Argument Description
model R-list object defining the model configuration compiled by the read_model() function
use.example (TRUE or FALSE, default = FALSE). Plot pre-computed example data from either of the North Sea model variants rather than user-generated data


Create a plot showing the distribution of credible values of annual average inshore and offshore mass densities over the final year of a simulation generated by the Monte_Carlo_StrathE2E() function.


Daily interval post-processed data from the Monte_Carlo_StrathE2E() function are stored in the files /results/ModelName/VariantName/CredInt/CredInt_processed_AAMresults_offshore-*.csv and CredInt_processed_AAMresults_inshore-*.csv, where * represents the model run identifier (model.ident) text embedded in the R-list object created by the read_model() function.


The format of the output is a single panel with rows of horizintally orientated box-and-whisker plots. Each row represents a different guild in the model (bacteria and detritus, phytoplankton etc etc). Each row consists of two box-and-whiskers, one (red) for the offshore zone and the other (blue) for the inshore zone. The data represented are distributions of credible values of the mass densities (mMn.m-2) of each variable, averaged over the final year of a model run.


In each plot the central tick mark of the box-and-whisker represents the median mass density, the box represents the 50% credible interval (spanning quartiles of the cumulative likelihood of simulated values) and the whiskers represent the 99% credible intervals.


# Load the 2003-2013 version of the North Sea model supplied with the package:
# model <- read_model("North_Sea", "2003-2013")
# Run the Monte Carlo process and generate the results files
# e.g.   Monte_Carlo_StrathE2E(model,nyears=50,n_iter=500)
#
# ..or
#
# Read the example data provided with the package :
model <- read_model("North_Sea", "2003-2013")
plot_inshore_vs_offshore_anavmass_with_credible_intervals(model, use.example=TRUE)
Reading internally stored example results for the North_Sea 2003-2013 model

Figure 33. Final year annual average mass density (mMN.m-2) of each guild in the offshore (red) and inshore (blue) zones.


# To direct the graph output to a file rather than the screen, wrap the plot_inshore_vs_offshore_anavmass_with_credible_intervals() function call in a graphical device call:
pdf("C:/Users/username/Documents/Foldername/plot.pdf",width=6,height=4)      # or jpeg("plot.jpg"), png("plot.PNG")
    plot_inshore_vs_offshore_anavmass_with_credible_intervals(model)
dev.off()


6.2.6 Using the function box_and_whisker_annual_plots_with_credible_intervals()

Table 26. Arguments of the function box_and_whisker_annual_plots_with_credible_intervals().

Argument Description
model R-list object defining the model configuration compiled by the read_model() function
use.example (TRUE or FALSE, default = FALSE). Plot pre-computed example data from either of the North Sea model variants rather than user-generated data


Create a multi-panel page of box-and-whisker plots showing the medians and variability ranges (quartiles as box-and-whisker) of a range of observational data on properties of the ecosystem (shown in black), alongside comparable box-and-whisker plots (shown in red) of equivalent measures derived from the final years of an ensemble of model runs generted by the Monte Carlo methodology (Monte_Carlo_StrathE2E() function)


Individual panels of the plot represent groups of similar or related ecosystem properties - annual productions, annual fishery landings, annual P:B ratios, annual food consumtion and diet compositions, nutrient concentrations, and inshore : offshore abundanace ratios.


The observational data to be plotted are loaded from the folder /ModelName/VariantName/Target_data/annual_target_data-*.csv as part of a read_model() function call. Column 3 of the data file (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. Un-used rows of data are omitted from the box and whisker plotting panels.


The corresponding measures derived from the final year of a model run generated by the Monte_Carlo_StrathE2E() function call are located in /results/ModelName/VariantName/CredInt_processed_targetresults-*.csv


Example data for both variants of the North Sea model are provided with the package and can be plotted using the use.example argument.


# Load the 1970-1999 version of the North Sea model supplied with the package:
# model <- read_model("North_Sea", "1970-1999")
# Run the Monte Carlo process and generate the results files
# e.g.   Monte_Carlo_StrathE2E(model,nyears=50,n_iter=500)
#
# ..or
#
# Read the example data provided with the package :
model <- read_model("North_Sea", "1970-1999")
box_and_whisker_annual_plots_with_credible_intervals(model, use.example=TRUE)
Reading internally stored example results for the North_Sea 1970-1999 model

Figure 34. Box and whisker plots comparing the observational target data used for model parameter optimisation, and distributions of credible values of the corresponding outputs from the model.


# To direct the graph output to a file rather than the screen, wrap the box_and_whisker_annual_plots_with_credible_intervals() function call in a graphical device call:
pdf("C:/Users/username/Documents/Foldername/plot.pdf",width=6,height=6)      # or jpeg("plot.jpg"), png("plot.PNG")
    box_and_whisker_annual_plots_with_credible_intervals(model)
dev.off()


6.2.7 Using the function box_and_whisker_monthly_plots_with_credible_intervals()

Table 27. Arguments of the function box_and_whisker_monthly_plots_with_credible_intervals().

Argument Description
model R-list object defining the model configuration compiled by the read_model() function
use.example (TRUE or FALSE, default = FALSE). Plot pre-computed example data from either of the North Sea model variants rather than user-generated data


Create a multi-panel page of box-and-whisker plots showing the medians and variability ranges (quartiles as box-and-whisker) of monthly aggregared observational data on nutrients nd plankton concentrations (nitrate, ammonia, chlorophyll, omnivorous and carnivorous zooplankton, and benthos larvae concentrations; shown in black), alongside comparable box-and-whisker plots (shown in red) of equivalent measures derived from the final years of an ensemble of model runs generted by the Monte Carlo methodology (Monte_Carlo_StrathE2E() function)


The observational data to be plotted are loaded from the folder /ModelName/VariantName/Target_data/monthly_target_data-*.csv


The corresponding measures derived from the final year of a model run generated by the Monte_Carlo_StrathE2E() function call are located in /results/ModelName/VariantName/CredInt_processed_monthly_mass-*.csv


Example data for both variants of the North Sea model are provided with the package and can be plotted using the use.example argument.


# Load the 1970-1999 version of the North Sea model supplied with the package:
# model <- read_model("North_Sea", "1970-1999")
# Run the Monte Carlo process and generate the results files
# e.g.   Monte_Carlo_StrathE2E(model,nyears=50,n_iter=500)
#
# ..or
#
# Read the example data provided with the package :
model <- read_model("North_Sea", "1970-1999")
box_and_whisker_monthly_plots_with_credible_intervals(model, use.example=TRUE)
Reading internally stored example results for the North_Sea 1970-1999 model

Figure 35. Box and whisker plots comparing the monthly aggregated observational data, and distributions of credible values of the corresponding outputs from the model.


# To direct the graph output to a file rather than the screen, wrap the box_and_whisker_monthly_plots_with_credible_intervals() function call in a graphical device call:
pdf("C:/Users/username/Documents/Foldername/plot.pdf",width=6,height=5)      # or jpeg("plot.jpg"), png("plot.PNG")
    box_and_whisker_monthly_plots_with_credible_intervals(model)
dev.off()



References

Beddington, J.R. (1975). Mutual interference between parasites or predators and its effect on searching efficiency. Journal of Animal Ecology, 51, 331-340.

Bertsimas, D. & Tsitsiklis, J. (1993). Simulated annealing. Statistical Science, 8, 10-15.

Cerny, V. (1985). A thermodynamic approach to the travelling salesman problem: An efficient simulation. Journal of Optimization Theory and Applications, 54, 41-51.

DeAngelis, D.L., Goldstein, R.A.. & O’Neill, R.V. (1975). A model for trophic interaction. Ecology, 56, 881-892.

Heath, M.R., Speirs, D.C. & Steele, J.H. (2014). Understanding patterns and processes in models of trophic cascades. Ecology Letters, 17, 101-114.

Kirkpatrick, S., Gelett, C.D. & Vecchi, M.P. (1983). Optimisation by simulated annealing. Science, 220, 621-630.

Morris, M.D. (1991). Factorial sampling plans for preliminary computational experiments. Technometrics, 33, 161-174.

Pace, M.L., Cole, J.J., Carpenter, S.R. & Kitchell, J.F. (1999) Trophic cascades revealed in diverse ecosystems. Trends in Ecology and Evolution, 14, 483-488.