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.
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:
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).
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.
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},
}
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
The package contains 8 families of functions:
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 |
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)
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)
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.