R/e2e_compare_runs_box.R

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

#
# e2e_compare_runs_box.R
#
#' Box and whisker plots comparing annual or monthly outputs from single or Monte Carlo baseline and scenario model runs.
#'
#' Generate a multi-panel set of box and whisker diagrams comparing annual or monthly averaged or integrated model outputs
#' from single or Monte Carlo baseline (black) and scenario (red) model runs. Each panel of annual data displays a different category of model data; each panel of monthly data shows a different nutrient or plankton guild.
#'
#' Arguments determine the source of model data for comparison. These can be outputs from 
#' a Monte Carlo simulations (using the function e2e_run_mc()) to estimate credible intervals of model outputs, or from single model runs using e2e_run(). Generation of credible interval data is a long computing task, so 
#' example data for the North Sea model provided with the package are available as an illustration.
#'
#' In each plot panel, where credible intervals of model outputs (from Monte Carlo analysis) have been selected 
#' the box spans 50% of the lielihood distribution of data, whiskers span 99%, and the median is indicated by tick mark). Baseline model results are 
#' always shown in black, scenario results in red. 
#'
#' @param selection Text string from a list to select comparison with annual or monthly observations. Select from: "ANNUAL", "MONTHLY". Remember to include the phrase within "" quotes.
#' @param model1 R-list object defining the baseline model configuration compiled by the e2e_read() function.
#' @param ci.data1 Logical. If TRUE plot credible intervals around baseline model results based on Monte Carlo simulation with the e2e_run_mc() function (default=FALSE).
#' @param use.saved1 Logical. If TRUE use baseline data from a prior user-defined run held as csv files data in the current results folder (default=FALSE).
#' @param use.example1 Logical. If TRUE use pre-computed example data from the internal North Sea model as the baseline rather than user-generated data (default=FALSE).
#' @param results1 R-list object of baseline model output generated by the e2e_run() function. Only needed if ci.data1=FALSE, use.saved1=FALSE and use.example1=FALSE. (Default=NULL).
#' @param model2 R-list object defining the scenario model configuration compiled by the e2e_read() function.
#' @param ci.data2 Logical. If TRUE plot credible intervals around scenario model results based on Monte Carlo simulation with the e2e_run_mc() function (default=FALSE).
#' @param use.saved2 Logical. If TRUE use scenario data from a prior user-defined run held as csv files data in the current results folder (default=FALSE).
#' @param use.example2 Logical. If TRUE use pre-computed example data from the internal North Sea model as the scenario rather than user-generated data (default=FALSE).
#' @param results2 R-list object of baseline model output generated by the e2e_run() function. Only needed if ci.data2=FALSE, use.saved2=FALSE and use.example2=FALSE. (Default=NULL).
#'
#' @return Graphical display in a new graphics window.
#'
#' @seealso \code{\link{e2e_read}}, \code{\link{e2e_run}}, \code{\link{e2e_run_mc}}, \code{\link{e2e_compare_runs_bar}}, \code{\link{e2e_compare_obs}}
#'
#' @importFrom graphics text
#'
#' @export
#'
#' @examples
#' # Load the 1970-1999 version of the internal North Sea model and run for 1 year
#'     m1 <- e2e_read("North_Sea", "1970-1999")
#'     r1 <-e2e_run(m1,nyears=1)
#' 
#' # Load the 2003-2013 version of the internal North Sea model and run for 1 year
#'     m2 <- e2e_read("North_Sea", "2003-2013")
#'     r2 <-e2e_run(m2,nyears=1)
#' 
#' # Compare annual results from 1970-1999 as baseline with 2003-2013 as scenario:
#'     e2e_compare_runs_box(selection="ANNUAL", model1=m1, ci.data1=FALSE, results1=r1,
#'                                              model2=m2, ci.data2=FALSE, results2=r2)
#' # Compare monthly results from 1970-1999 as baseline with 2003-2013 as scenario:
#'     dev.new()
#'     e2e_compare_runs_box(selection="MONTHLY", model1=m1, ci.data1=FALSE, results1=r1,
#'                                           model2=m2, ci.data2=FALSE, results2=r2)
#'
#' # This example requires the StrathE2E2examples supplementrary data package.
#' # Compare 1970-1999 as baseline (from single model run), with 2003-2013
#' # as scenario (from example data with credible interval results):
#' if(require(StrathE2E2examples)){
#'     e2e_compare_runs_box(selection="ANNUAL", model1=m1, ci.data1=FALSE, results1=r1,
#'                                              model2=m2, ci.data2=TRUE, use.example2=TRUE)
#'     dev.new()
#'     e2e_compare_runs_box(selection="MONTHLY", model1=m1, ci.data1=FALSE, results1=r1,
#'                                              model2=m2, ci.data2=TRUE, use.example2=TRUE)
#' }
#'
#' # This example requires the StrathE2E2examples supplementrary data package.
#' # Compare 1970-1999 as baseline (from example data with cred.int.), with 2003-2013
#' # as scenario (from example data with credible interval results):
#' if(require(StrathE2E2examples)){
#'     e2e_compare_runs_box(selection="ANNUAL", model1=m1, ci.data1=TRUE, use.example1=TRUE,
#'                                              model2=m2, ci.data2=TRUE, use.example2=TRUE)
#'     dev.new()
#'     e2e_compare_runs_box(selection="MONTHLY", model1=m1, ci.data1=TRUE, use.example1=TRUE,
#'                                               model2=m2, ci.data2=TRUE, use.example2=TRUE)
#' }
#'
#
# ---------------------------------------------------------------------
# |                                                                   |
# | Author: Mike Heath                                                |
# | Department of Mathematics and Statistics                          |
# | University of Strathclyde, Glasgow                                |
# |                                                                   |
# | Date of this version: May 2020                                    |
# |                                                                   |
# ---------------------------------------------------------------------

e2e_compare_runs_box <- function(selection="ANNUAL", 
                                    model1, ci.data1=FALSE, use.saved1=FALSE, use.example1=FALSE, results1=NULL,
                                    model2, ci.data2=FALSE, use.saved2=FALSE, use.example2=FALSE, results2=NULL ) {

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

	if ((use.example1 == TRUE) || (use.example2 == TRUE)) hasExamples()

start_par = par()$mfrow
on.exit(par(mfrow = start_par))


# .....................................................


if(use.saved1==TRUE & use.example1==TRUE){
        stop("Baseline data (1): use.saved1 and use.example1 cannot both be TRUE ! \n")
}

if(use.saved1==TRUE & is.list(results1)==TRUE){
        stop("Baseline data (1): use.saved1 is TRUE but a dataframe object has also been specified ! \n")
}

if(use.example1==TRUE & is.list(results1)==TRUE){
        stop("Baseline data (1): use.example1 is TRUE but a dataframe object has also been specified ! \n")
}

if(use.saved1==FALSE & use.example1==FALSE & is.list(results1)==FALSE){
        stop("Baseline data (1): no source of data has been specified ! \n")
}

if(ci.data1==FALSE & use.example1==TRUE){
        stop("Baseline data (1): no example data available for a single model run - run the model to generate some data ! \n")
}

if(ci.data1==TRUE & use.saved1==FALSE & use.example1==FALSE & is.list(results1)==TRUE){
        stop("Baseline data (1): credible intervals available only from saved or example data ! \n")
}


# .............................................


if(use.saved2==TRUE & use.example2==TRUE){
        stop("Scenario data (2): use.saved2 and use.example2 cannot both be TRUE ! \n")
}

if(use.saved2==TRUE & is.list(results2)==TRUE){
        stop("Scenario data (2): use.saved2 is TRUE but a dataframe object has also been specified ! \n")
}

if(use.example2==TRUE & is.list(results2)==TRUE){
        stop("Scenario data (2): use.example2 is TRUE but a dataframe object has also been specified ! \n")
}

if(use.saved2==FALSE & use.example2==FALSE & is.list(results2)==FALSE){
        stop("Scenario data (2): no source of data has been specified ! \n")
}

if(ci.data2==FALSE & use.example2==TRUE){
        stop("Scenario data (2): no example data available for a single model run - run the model to generate some data ! \n")
}

if(ci.data2==TRUE & use.saved2==FALSE & use.example2==FALSE & is.list(results2)==TRUE){
        stop("Scenario data (2): credible intervals available only from saved or example data ! \n")
}



#.........................................................................

if(selection=="ANNUAL"){



	boxplot_annual_compare_runs(model1=model1, ci.data1=ci.data1, use.saved1=use.saved1, use.example1=use.example1, results1=results1,
                             	    model2=model2, ci.data2=ci.data2, use.saved2=use.saved2, use.example2=use.example2, results2=results2 )


#.........................................................................

} else if(selection=="MONTHLY"){

	boxplot_monthly_compare_runs(model1=model1, ci.data1=ci.data1, use.saved1=use.saved1, use.example1=use.example1, results1=results1,
                                     model2=model2, ci.data2=ci.data2, use.saved2=use.saved2, use.example2=use.example2, results2=results2 )

#.........................................................................

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

#.........................................................................

}

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