Read all the configuration, driving and parameter files for a designated model and compile the data into a list object.
e2ep_read.RdThis function is the key point of entry to the package. It reads all the csv files containing the configuration, driving and parameter values which define a model for a particular region and compiles them into a single R-list object. This data object forms the basis for almost all other functions in the package.
Usage
e2ep_read(
model.name,
model.variant,
models.path = NULL,
results.path = NULL,
results.subdir = "",
model.ident = "base",
quiet = TRUE,
silent = FALSE
)Arguments
- model.name
Name of model to read (no default).
- model.variant
Variant of the model to be read (no default).
- models.path
Relative path from the current working directory to a folder containing a library of model configurations (typically "Folder/Models"). Setting models.path="" is valid. Default models.path=NULL, meaning read a Barents Sea model setup from the package folder extdata/Models.
- results.path
Relative path from the current working directory to a folder for writing and reading model output files (e.g. "E2E_results"). Setting results.path="" is valid. Model-specific sub-folders will be assigned and if necessary auto-created according to the model name and variant. Default results.path=NULL, meaning write/read to/from a temporary directory.
- results.subdir
Subdirectory of "working_directory/results.path/model_name/model_variant" to be created if required. (Default="", meaning no subdirectory will be created).
- model.ident
Identifier text appended to output file names (e.g. OFFSHORE_model_annualresults-TEXT.csv instead of just OFFSHORE_model_annualresults.csv). (Default="base").
- quiet
Logical. If FALSE then see on-screen information on indvidual parameter files as they are read (default=TRUE).
- silent
Logical. If FALSE then see on-screen information on model and results paths (default=FALSE). If set TRUE then this over-rides any quiet=FALSE setting and forces quiet=TRUE.
Details
The input csv files are specified in the MODEL_SETUP.csv file located in the Model/variant folder specified by the argument models.path in a e2ep_read() call, or from the extdata/Models folder in the package installation. The model supplied with the package has the variant named 2011-2019 and is a fully parameterised and documented model of the Barents Sea.
Starting from a baseline model configuration defined in the MODEL_SETUP.csv file, any of the terms in the R-list objcet created by e2ep_read() can be modified by coding to produce an unlimited range of scenario configurations representing, for example, changes in the physical environment, changes in the composition or activity of the fishing fleets, or any combination of these. The power of this approach is that large numbers of scenarios can be coded in standard R and simulated without any need for manual editing of input files.
Examples
# Load the 2011-2019 version of the Barents Sea model supplied with the package; outputs go
# to a temporary results folder; default model.ident setting.
# Default screen information settings - on-screen parameter file information suppressed but
# path information enabled:
model <- e2ep_read("Barents_Sea", "2011-2019")
#> Current working directory is...
#> 'C:/Users/jackl/OneDrive - University of Strathclyde/Documents/StrathE2E/strath-e-2-e-polar-webdev/docs/reference'
#> No 'results.path' specified so any csv data requested
#> will be directed to/from the temporary directory...
#> 'C:\Users\jackl\AppData\Local\Temp\RtmpSgdWsc'
#>
#> Model setup and parameters gathered from ...
#> StrathE2E2 package folder
#> Model results will be directed to/from ...
#> 'C:\Users\jackl\AppData\Local\Temp\RtmpSgdWsc/Barents_Sea/2011-2019/'
# User-specified model.ident; on-screen parameter file and path information enabaled:
model <- e2ep_read("Barents_Sea", "2011-2019",model.ident="baseline",quiet=FALSE)
#> Current working directory is...
#> 'C:/Users/jackl/OneDrive - University of Strathclyde/Documents/StrathE2E/strath-e-2-e-polar-webdev/docs/reference'
#> No 'results.path' specified so any csv data requested
#> will be directed to/from the temporary directory...
#> 'C:\Users\jackl\AppData\Local\Temp\RtmpSgdWsc'
#>
#> Loading model : C:/Users/jackl/Documents/R/win-library/4.1/StrathE2EPolar/extdata/Models/Barents_Sea/2011-2019
#> Reading CSV file: MODEL_SETUP.csv
#> Reading CSV file: physical_parameters_BS.csv
#> Reading CSV file: fixed_miscellaneous.csv
#> Reading CSV file: fixed_consumers_BS_2011-2019.csv
#> Reading CSV file: physics_BS_2011-2019.csv
#> Reading CSV file: chemistry_BS_2011-2019.csv
#> Reading CSV file: event_timing_BS_2011-2019.csv
#> Reading CSV file: fitted_preference_matrix_BS.csv
#> Reading CSV file: fitted_uptake_mort_rates_BS.csv
#> Reading CSV file: fitted_microbiology_others_BS.csv
#> Reading CSV file: initial_values_BS_2011-2019.csv
#> Reading CSV file: fishing_activity_BS_2011-2019.csv
#> Reading CSV file: fishing_power_BS_2011-2019.csv
#> Reading CSV file: fishing_discards_BS_2011-2019.csv
#> Reading CSV file: fishing_distribution_BS_2011-2019.csv
#> Reading CSV file: fishing_fleet_BS_2011-2019.csv
#> Reading CSV file: fishing_processing_BS.csv
#> Reading CSV file: fishing_gear_multiplier.csv
#> Reading CSV file: harvest_ratio_multiplier.csv
#> Model setup and parameters gathered from ...
#> StrathE2E2 package folder
#> Model results will be directed to/from ...
#> 'C:\Users\jackl\AppData\Local\Temp\RtmpSgdWsc/Barents_Sea/2011-2019/'
# All on-screen information suppressed even though quiet=FALSE:
model <- e2ep_read("Barents_Sea", "2011-2019",model.ident="baseline",quiet=FALSE,silent=TRUE)
# View details of the structure and contents of the model list-object:
str(model,max.level=1)
#> List of 2
#> $ setup:List of 7
#> $ data :List of 8
str(model,max.level=2)
#> List of 2
#> $ setup:List of 7
#> ..$ read.only : logi TRUE
#> ..$ model.name : chr "Barents_Sea"
#> ..$ model.variant: chr "2011-2019"
#> ..$ model.ident : chr "baseline"
#> ..$ model.subdir : chr ""
#> ..$ model.path : chr "C:/Users/jackl/Documents/R/win-library/4.1/StrathE2EPolar/extdata/Models/Barents_Sea/2011-2019"
#> ..$ resultsdir : chr "C:\\Users\\jackl\\AppData\\Local\\Temp\\RtmpSgdWsc/Barents_Sea/2011-2019/"
#> $ data :List of 8
#> ..$ fixed.parameters :List of 63
#> ..$ fitted.parameters :List of 191
#> ..$ physical.parameters:List of 70
#> ..$ physics.drivers :'data.frame': 12 obs. of 33 variables:
#> ..$ chemistry.drivers :'data.frame': 12 obs. of 22 variables:
#> ..$ biological.events :'data.frame': 50 obs. of 2 variables:
#> ..$ fleet.model :List of 19
#> ..$ initial.state :List of 499
# Dummy example to illustrate loading a user defined model from a user workspace
# ... substitute your own path details for e.g. "Folder/Models":
# model<-e2ep_read("Modelname", "Variantname",
# models.path="Folder/Models",
# model.ident="demo")
# Dummy example to illustrate loading a user defined model from a user workspace and
# sending the model outputs to a specified folder ... substitute your own path details
# for the dummy paths shown here
# for "Folder/Models" and "Folder/results":
# model<-e2ep_read("Modelname", "Variantname",
# models.path="Folder/Models",
# results.path="Folder/results",
# model.ident="demo")
# Create a new scenario version of the Barents Sea/2011-2019 model by increasing the
# activity rate of gear 1 (pelagic trawls and seines) by a factor of 2:
model <- e2ep_read("Barents_Sea", "2011-2019")
#> Current working directory is...
#> 'C:/Users/jackl/OneDrive - University of Strathclyde/Documents/StrathE2E/strath-e-2-e-polar-webdev/docs/reference'
#> No 'results.path' specified so any csv data requested
#> will be directed to/from the temporary directory...
#> 'C:\Users\jackl\AppData\Local\Temp\RtmpSgdWsc'
#>
#> Model setup and parameters gathered from ...
#> StrathE2E2 package folder
#> Model results will be directed to/from ...
#> 'C:\Users\jackl\AppData\Local\Temp\RtmpSgdWsc/Barents_Sea/2011-2019/'
scenario_model <- model
scenario_model$data$fleet.model$gear_mult[1] <- 2
# Set a new identifier for any csv outputs:
scenario_model$setup$model.ident <- "gear1x2"
# Run the baseline model for 2 years:
results<-e2ep_run(model,nyears=2)
# Visualise the time series of output from the baseline model run:
e2ep_plot_ts(model,results,selection="ECO")
# \donttest{
# Run the scenario model for 20 years:
scenario_results<-e2ep_run(scenario_model,nyears=20)
# Visualise the time series of output from the scenario model run
# in a new graphics window:
dev.new()
e2ep_plot_ts(scenario_model,scenario_results,selection="ECO")
# }