Summary

  • StrathE2E2 is an R package for modelling the ‘big-picture’, whole ecosystem effects of hydrodynamics, temperature, nutrient additions, and fishing on continental shelf marine food webs.

  • StrathE2E2 has two linked parts - a fishing fleet model and an ecology model. The fishing model integrates harvesting, discarding and seabed disturbance rates across a range of gears and passes the results into the ecology model.

  • The ecology model is a network of coupled ordinary differential equations representing the rates of change in organic detritus, dissolved inorganic nutrient, and coarse guilds of living biomass spanning microbes to megafauna. The equations include representations of feeding, metabolism, reproduction, active migrations, advection and mixing. Environmental driving data include temperature, irradiance, hydrodynamics, and nutrient inputs from rivers, atmosphere and ocean boundaries.

  • The package includes functions for parameter optimization, global sensitivity analysis, and Monte Carlo estimation of credible intervals for model outputs.

  • A fully developed and documented implementation of StrathE2E2 for the North Sea is included with the package.


Documentation

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

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


Reference Manual - compilation of help pages for all the package functions generated by CRAN-check


Cheatsheet - quick-reference guide to StrathE2E2 functions


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


Download the following supporting documents:




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

A repository for contributed implementations of StrathE2E2 is available here. 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. (2020).
  StrathE2E2: an R package for modelling the dynamics of marine food
  webs and fisheries. Methods in Ecology and Evolution, published
  online 11 October 2020. 8pp.

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 = {Published online 11 October 2020},
    year = {2020},
    issn = {2041-210X},
    url = {https://besjournals.onlinelibrary.wiley.com/doi/10.1111/2041-210X.13510},
    keywords = {food web, dynamic model, ecosystem, fisheries, 
                 ordinary differential equations, optimization, 
                 sensitivity analysis, Monte-Carlo, R},
  }


Quick start

library(StrathE2E2)                           # Load the package
model <- e2e_read("North_Sea", "1970-1999")   # Read the 1970-1999 North Sea model
Current working directory is... 
'C:/Users/Public/Documents/StrathE2E2'
No 'results.path' specified so any csv data requested
will be directed to/from the temporary directory...
'C:\Users\ais04103\AppData\Local\Temp\RtmpiySPHQ'

Model setup and parameters gathered from ...
StrathE2E2 package folder
Model results will be directed to/from ...
'C:\Users\ais04103\AppData\Local\Temp\RtmpiySPHQ/North_Sea/1970-1999/'
results <- e2e_run(model,nyears=3)            # Run the model for 3 years
e2e_plot_ts(model,results,"ECO")              # Plot time series of the variables




1 Package structure

The package contains 8 families of functions:

  • Model house-keeping (Table 1)
  • Basic model operations (Table 2)
  • Parameter estimation (Table 3)
  • Sensitivity and Monte Carlo analyses (Table 4)
  • Comparing model runs and observations (Table 5)
  • Fishery yield curves (Table 6)
  • Visualizing model inputs (Table 7)
  • Visualizing model outputs (Table 8)


Table 1. Model house-keeping

Function name Description
e2e_ls() List the available models
e2e_copy() Copy models between workspaces
e2e_get_parmdoc() Download parameter documentation as a dataframe



Table 2. Basic model operations

Function name Description
e2e_read() Read a model setup
e2e_run() Run StrathE2E for a prescribed number of years with a given setup
e2e_extract_start() Create a new initial values file from the end-state of a model run
e2e_extract_hr() Extract the values of harvest ratios generated by the fleet model
e2e_plot_ts() Plot time series of model outputs for the full duration of a model run



Table 3. Parameter estimation

Function name Description
e2e_optimize_eco() Optimize ecology model parameters
e2e_optimize_hr() Optimize harvest ratio scaling parameters
e2e_optimize_act() Optimize fishing gear activity rates
e2e_plot_opt_diagnostics() Plot diagnostic data for optimization runs
e2e_calculate_hrscale() Calculate initial values of parameters linking effort to harvest ratios



Table 4. Senstivity and Monte Carlo analyses

Function name Description
e2e_run_sens() Run a global parameters sensitivity analysis with a given setup
e2e_run_mc() Run a Monte Carlo analysis with a given setup
e2e_merge_sens_mc() Merge parallel processing files from sensitivity or Monte Carlo runs
e2e_process_sens_mc() Post-process raw output data from sensitivity or Monte Carlo runs
e2e_plot_sens_mc() Plot diagnostic results from sensitivity or Monte Carlo runs
e2e_get_senscrit() List the model outputs available as the basis for sensitivity analysis



Table 5. Compare model runs and observations

Function name Description
e2e_compare_obs() Box-plot comparisons between observations and model outputs
e2e_compare_runs_box() Box-plot comparisons between two different model runs
e2e_compare_runs_bar() Tornado bar-plots comparing two different model runs



Table 6. Fishery yield analysis

Function name Description
e2e_run_ycurve() Perform a set of model runs to generate fishery yield curve data
e2e_plot_ycurve() Plot fishery yield curve data



Table 7. Visualize model inputs

Function name Description
e2e_plot_edrivers() Plot a climatological year of environmental driving data
e2e_plot_fdrivers() Plot distributions of fishery-related driving data



Table 8. Visualize model outputs from the final year of a run

Function name Description
e2e_plot_eco() Plot annual cycles of ecology model variables
e2e_plot_catch() Plot annual landings and discards
e2e_plot_migration() Plot annual cycles of active migration fluxes
e2e_plot_trophic() Plot mean trophic level and omnivory indices
e2e_plot_biomass() Plot zonal distributions of annual average biomass densities



2 Getting started and model house-keeping

2.1 Installing the package

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

  • deSolve

  • NetIndices


To start a session, begin by loading the package:

library(StrathE2E2)



2.2 Installing the supplementary data-package

The model package has a supplementary data-package - Strathe2E2examples - which contains example outputs from the more computationally intensive functions in the package. These are provided to illustrate the performance of various post-processing and plotting functions for these analyses that are available.


The first time that example data are called from a StrathE2E2 function, the data-package is downloaded and installed from the GitLab server https://marineresourcemodelling.gitlab.io/sran/index.html. Thereafter the example data are available offline.


Alternatively, users can manually install the package using:

install.packages("StrathE2E2examples", 
                 repos="https://marineresourcemodelling.gitlab.io/sran")


Once the data-package has been installed, documentation on the data sets is available by typing:

library(StrathE2E2examples)
help(StrathE2E2examples)



2.3 Folder structure for model input and output files

All paths for reading model setup and paramater data and writing model results (when requested) are set using the e2e_read() function. This function creates a list object which contains all of the data required to completely define a given model. Read and write paths are defined RELATIVE TO THE CURRENT WORKING DIRECTORY through function arguments. The current working directory can always be obtained by the R command getwd(), or e2e_read() routinely returns the current working directory to the screen as a reminder.


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.


The model folder structure within the model package is read-only, so users developing their own models will need to create an editable folder structure in their own accessible workspace to hold their model configuration data. In addition, users of the North Sea demonstration model wishing to use the more advanced optimization functions in the package will need to create a copy of the demonstration models in their own workspace, because these functions require to write data back into the /Param sub-folders on completion of the optimization. This can be done using using any file manager or the e2e_copy() function provided with the package. The structure expected for any user-defined model folders is shown in Figure 2.