R/e2e_process_sens_mc.R

In StrathE2E2: End-to-End Marine Food Web Model

#
# e2e_process_sens_mc.R
#
#' Post-process already-created data from sensitivity or Monte Carlo analysis runs.
#'
#' The functions e2e_run_sens() and e2e_run_mc() are extremely time consuming so it makes sense to share the 
#' load across multiple processors in parallel and combine the results afterwards using the function e2e_merge_sens_mc(). Both the original
#' run functions and the merging function have post-processing options in their workflow. Nevertheless, there may be occasions where it is
#' necessary to simply post-process an already created raw data set. Hence the need for this function.
#'
#' The model.ident identifier and folder path for input files must be set in a e2e_read() function call. If enabled, output files will be directed to the same folder.
#'
#' \strong{Details relating to sensitivity analysis processing:}
#'
#' The function reads a file of raw sensitivity analysis data (OAT_results-*.csv, where * refers to the identifier model.ident set in the e2e_read() function) from a /results folder
#' and performs the post-processing that would ordinarily be done automatically within the e2e_run_sens() or e2e_merge_sens_mc() functions. 
#' The output of the processing is a dataframe (and optionaly a csv file) 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.
#'
#' csv output from the function (if the argument csv.output=TRUE) is a file named sorted_parameter_elementary_effects-*.csv in the results folder specified in an e2e_read() function call.
#'
#' Optionally, the function can read example raw sensitivity data for one of the two North Sea model variants supplied with the package.
#'
#' For details of how the Elementary Effect values are derived for each parameter see help(e2e_run_sens)
#'
#' \strong{Details relating to Monte Carlo analysis processing:}
#'
#' The function e2e_run_mc() generates 11 different output files covering the range of data generated by StrathE2E. The post processing reads all of these and generates quantiles of the 
#' likelihood weighted distributions of all of the outputs and saves these as credible interval files.
#'
#' If the argument csv.output=TRUE then the function writes output to csv files. The function always returns all of the processed data as
#' a list object. The function takes a few minutes to run as it has a lot of work to do, especially in processing all of the daily output variables.
#'
#' Although the e2e_run_mc() function generates large raw data files (11 files total 3.2 Mb per iteration), the processed data are much smaller (13 files total ~4 Mb regardless of
#' the number of iterations.
#'
#' @param model R-list object defining the model configuration and compiled by the e2e_read() function
#' @param selection Text string from a list identifying source of data to bed merged. Select from: "SENS", "MC", referring to sensitivity analysis or Monte Carlo analysis. Remember to include the phrase within "" quotes.
#' @param use.example Logical. If TRUE use pre-computed example data from the internal North Sea model rather than user-generated data (default=FALSE).
#' @param csv.output Logical. If TRUE then enable writing of csv output files (default=FALSE).
#'
#' @return Dataframe (sensitivity analayis) or list object (Monte Carlo analysis) of the processed data. If csv.output=TRUE then CSV files of the processed data. 
#'
#' @seealso \code{\link{e2e_read}}, \code{\link{e2e_run_sens}}, \code{\link{e2e_run_mc}}, \code{\link{e2e_merge_sens_mc}} , \code{\link{e2e_plot_sens_mc}}
#'
#' @export
#'
#' @examples
#' # The examples provided here are illustration of how to process data from sensitivity
#' # and Monte Carlo analyses. They are commented-out because they cannot be run in isolation;
#' # they need to have existing data objects or files on which to operate.
#'
#' # --------------------------------------------------------------------------
#'
#' # Sensitivity analysis processing:
#' # This example requires the Strathe2E2examples supplementary data package.
#' # Load details of the 1970-1999 version of the North Sea model supplied with the package:
#'     model <- e2e_read("North_Sea", "1970-1999")
#' # Process the example data for this model variant provided with the package
#' if(require(StrathE2E2examples)){
#'     sens_results <- e2e_process_sens_mc(model, selection="SENS", use.example=TRUE)
#' # View the first few rows of the results dataframe
#'     head(sens_results)
#' }
#'
#' # --------------------------------------------------------------------------
#'
#' # Monte Carlo analysis processing:
#' # This dummy example here assumes that raw results data have been previously
#' # generated by a of the e2e_run_mc() function, with the model.ident value
#' # assigned as "testdata", or that data from parallel runs have been gathered
#' # together in the same folder with model.ident="testdata".
#' # Load the model name and version for the data to be processed :
#' # (REPLACE "Folder/results" your own results.path before running)
#' # e.g. ... model <- e2e_read("North_Sea", "2003-2013", results.path="Folder/results", 
#' #                             model.ident="testdata")
#' #          mc_results <- e2e_process_sens_mc(model, selection="MC", csv.output=TRUE)
#' #          str(mc_results,max.level=1)
#'
#' # --------------------------------------------------------------------------
#'
#
# ---------------------------------------------------------------------
# |                                                                   |
# | Author: Mike Heath                                                |
# | Department of Mathematics and Statistics                          |
# | University of Strathclyde, Glasgow                                |
# |                                                                   |
# | Date of this version: May 2020                                    |
# |                                                                   |
# ---------------------------------------------------------------------

e2e_process_sens_mc <- function(model, selection="", use.example=FALSE, csv.output=FALSE) {

   oo <- options()
   on.exit(options(oo))

	if (use.example == TRUE) hasExamples()

processed_data<-NULL

if(selection=="MC" & use.example==TRUE){
	message("Warning: use.example=TRUE not available for MC processing. Looking for csv files as defined by 'model' !")
}

if(selection=="SENS"){
	processed_data <- postprocess_sens_data(model=model, use.example=use.example, csv.output=csv.output)

} else if(selection=="MC"){
	processed_data <- postprocess_mc_data(model=model, csv.output=csv.output)

} else {
	stop("Error: unknown selection '", selection, "' !\n")
}

return(processed_data)

}

#-----------------------------------------------------------------