plotPerformanceSpaceMulti: Plots contours of the number of performance thresholds exceeded in the perturbation space

Description

plotPerformanceSpaceMulti uses multiple system model performances calculated using the function runSystemModel and the summary of the simulation generated using the functions generateScenarios & getSimSummary as input to plot filled contours showing the number of performance thresholds exceeded in the perturbation space. The user may specify the attributes to be used as the axes of the perturbation space.

Usage

plotPerformanceSpaceMulti(
  performance,
  sim,
  perfThreshMin,
  perfThreshMax,
  attX = NULL,
  attY = NULL,
  attSlices = NULL,
  topReps = NULL,
  climData = NULL,
  col = NULL,
  axesPercentLabel = FALSE
)

Value

The plot showing the number of thresholds exceeded and the ggplot object.

Arguments

performance: a list; each element of the list should be a performance metric. May be calculated using the function runSystemModel
sim: a list; summary of the simulation containing the scenarios generated using the function generateScenarios that is used to run the system model using runSystemModel. The summary of the simulation may be obtained by using the function getSimSummary on the full simulation. The summary object is much smaller in size for ease of storage and use with the performance plotting functions like plotPerformanceSpace.
perfThreshMin: a vector; the minimum threshold value of each performance metric. The length of the vector should be equal to length(performance). If the metric does not have a minimum threshold, specify the corresponding element in perfThreshMin as NA.
perfThreshMax: a vector; the maximum threshold value of each performance metric. The length of the vector should be equal to length(performance). If the metric does not have a maximum threshold, specify the corresponding element in perfThreshMax as NA.
attX: a string; the tag of the perturbed attribute to plot on the xaxis. The attribute must be one of the perturbed attributes of sim. Type sim$expSpace$attPerturb to view all perturbed attributes of sim. If NULL (default), the first perturbed attribute of sim will be used.
attY: a string; the tag of the perturbed attribute to plot on the yaxis. The attribute must be another perturbed attribute of sim. If NULL, the second perturbed attribute of sim will be used.
attSlices: a list; used to subset perturbed attributes in sim for the plot. This argument would typically be used in cases where there are more than two perturbed attributes. The elements of the list correspond to the perturbed attributes to be subsetted and must be named using the attribute tag. Each element may contain a single value or a two-element vector specifying the minimum-maximum values. If the element is a single value, the exposure space is sliced on this single value of the attribute. If minimum-maximum values are specified, the exposure space will be sliced to subset this range. If attSlices includes attX or attY, these attributes will be sliced and the resulting plot will be a "zoomed-in" space.
topReps: an integer (default is NULL); the number of "top" replicates in terms of simulation fitness to be used. If topReps is specified, topReps number of replicates will be identified for each target and the average performance across these replicates will be plotted. If NULL, the average performance across all the replicates will be plotted.
climData: data.frame; the values of attX and attY from other sources like climate models. This data will be plotted as points in the perturbation space. If the Name of the data is available in the data.frame, the points will be identified using the Name. Please refer data provided with the package that may be loaded using data("egClimData") for an example of the expected format of climData.
col: a vector of colours; The length of the vector should at least be sufficient to assign unique colours to all the different values in the generated plot. If NULL, the default foreSIGHT colours is used.
axesPercentLabel: a logical flag; if TRUE x and y axes to be displayed in terms of percentage change instead of fraction

Details

If the space contains more than two perturbed attributes, the performance values are averaged across the perturbations in the attributes other than attX and attY. The user may specify argument attSlices to slice the performance space at specific values of the other perturbed attributes. If attSlices are used to specify minimum-maximum values to subset other perturbed attributes, the performance values are averaged across the subsetted perturbations in these attributes. This function cannot be used with sim perturbed on an "OAT" grid since contours of the number of performance thresholds exceeded cannot be calculated for an irregular perturbation space.

Examples

Run this code

# load example datasets
data("egSimPerformance")
data("egSimSummary")
data("egClimData")

plotPerformanceSpaceMulti(performance=egSimPerformance, sim=egSimSummary, 
perfThreshMin = c(NA, 0.80), perfThreshMax = c(30, NA))

#replot with axes as percentage changes
plotPerformanceSpaceMulti(performance=egSimPerformance, sim=egSimSummary, 
perfThreshMin = c(NA, 0.80), perfThreshMax = c(30, NA),axesPercentLabel=TRUE)

# add alternate climate data and specify different colours for the plot
plotPerformanceSpaceMulti(performance=egSimPerformance, sim=egSimSummary, 
                          perfThreshMin = c(NA, 0.80),perfThreshMax = c(30, NA), 
                          climData = egClimData, col = viridisLite::magma(3))

# example using simple scaled simulations
data("egScalPerformance")
data("egScalSummary")
data("egClimData")
plotPerformanceSpaceMulti(performance=egScalPerformance, sim=egScalSummary, 
                          perfThreshMin = c(NA, 0.80),perfThreshMax = c(30, NA), 
                          climData = egClimData)

# replot with axes as percentage changes (Note: modifies fractional change attributes only)
plotPerformanceSpaceMulti(performance=egScalPerformance, sim=egScalSummary, 
                          perfThreshMin = c(NA, 0.80),perfThreshMax = c(30, NA), 
                          climData = egClimData,axesPercentLabel=TRUE)