plotPerformanceSpace: Plots a performance space using the system performance and scenarios as input

Description

plotPerformanceSpace uses the system model performance calculated using the function runSystemModel and the summary of the simulation generated using the functions generateScenarios & getSimSummary as input to plot the performance space of the system. The user may specify the attributes to be used as the axes of the performance space.

Usage

plotPerformanceSpace(
  performance,
  sim,
  metric = NULL,
  attX = NULL,
  attY = NULL,
  topReps = NULL,
  perfThresh = NULL,
  perfThreshLabel = "Threshold",
  attSlices = NULL,
  climData = NULL,
  colMap = NULL,
  colLim = NULL,
  contourBreaks = NULL,
  axesPercentLabel = FALSE,
  type = "heat.plot",
  noPlot = F
)

Value

The plot of the performance space and the ggplot object.

Arguments

performance: a named list; contains the system model performance calculated using runSystemModel. If the list contains more than one performance metric, the argument metric can be used to specify the metric to be used.
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.
metric: a string; the name of the performance metric to be plotted. The argument can be used to select a metric from performance for plotting. If NULL (the default), the first metric in the list will be used.
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.
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.
perfThresh: a number; the minimum or maximum threshold value of the performance metric. A line will be drawn to mark this threshold value in the performance space.
perfThreshLabel: a string; the text to label perfThresh.
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.
climData: data.frame; the values of attX and attY from other sources like climate models. This data will be plotted as points in the performance space. The data frame may contain columns with values of the performance metric to be plotted and the "Name" of the dataset. If the performance metric is available in the data.frame, the points will be coloured based on the performance colMap scale. 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.
colMap: a vector of colours; to specify the colourmap to be used. If NULL, the default foreSIGHT colourmap is used.
colLim: a vector of 2 values; the minimum and maximum limits of the colour scale.
contourBreaks: a vector; specifies breaks in the performance metric
axesPercentLabel: a logical flag; if TRUE x and y axes to be displayed in terms of percentage change instead of fraction
type: a string; indicates type of plot as "heat.plot" (default) or "filled.contour"
noPlot: logical; indicates whether plots will be printed (TRUE) or not printed (FALSE) and only saved as an object.

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. If the input performance list contains multiple performance metrics, the function plots the first metric. The function may be called with performance argument specifying the metric to be plotted plotPerformanceSpace(performance[2], sim) to plot other metrics.

Examples

Run this code

# load example datasets
data("egSimSummary")       # summary of stochastic simulation
data("egSimPerformance")   # system performance calculated using the stochastic simulation
data("egClimData")         # alternate climate data and system performance

plotPerformanceSpace(performance=egSimPerformance[2], sim=egSimSummary)

if (FALSE) {
# change plot style to "filled.contour" and specify contours - show contours from
# 0.76 to 0.9 in increments of 0.02
plotPerformanceSpace(type="filled.contour",performance=egSimPerformance[2],
                     sim=egSimSummary,contourBreaks=seq(0.76,0.9,0.02))


# adding climate data, using top 10 replicates
plotPerformanceSpace(performance=egSimPerformance[1], sim=egSimSummary,
                     topReps = 10, climData = egClimData)

# adding a threshold
plotPerformanceSpace(performance=egSimPerformance, sim=egSimSummary, metric = "Avg. Deficit (L)",
                     climData = egClimData, perfThresh = 27.5, perfThreshLabel = "Max Avg. Deficit")

# user specified colMap
plotPerformanceSpace(performance=egSimPerformance[1], sim=egSimSummary,
                     climData = egClimData, perfThresh = 27.5,
                     perfThreshLabel = "Max Avg. Deficit",
                     colMap = viridisLite::inferno(100))

#modify theme to change axes positioning to stacked vertically and left aligned
plotPerformanceSpace(performance=egSimPerformance[1], sim=egSimSummary,
                     climData = egClimData, perfThresh = 27.5,
                     perfThreshLabel = "Max Avg. Deficit",
                     colMap = viridisLite::inferno(100))+
ggplot2::theme(legend.box="vertical",
               legend.position="bottom",
               legend.box.just = "left",
               legend.margin = ggplot2::margin(t=0.01, r=0.1, b=0.01, l=0.1, "cm"),
               legend.justification=c(0.01,0.01))

# display fractional changes axes as percentage change
plotPerformanceSpace(performance=egSimPerformance, sim=egSimSummary,
                     metric = "Avg. Deficit (L)",
                     climData = egClimData, perfThresh = 27.5,
                     perfThreshLabel = "Max Avg. Deficit",
                     axesPercentLabel=TRUE)

# change displayed contours on performance space - show contours from 18 to 34 in increments of 2 L
plotPerformanceSpace(performance=egSimPerformance, sim=egSimSummary,
                     metric = "Avg. Deficit (L)",
                     climData = egClimData, perfThresh = 27.5,
                     perfThreshLabel = "Max Avg. Deficit",axesPercentLabel=TRUE,
                     contourBreaks=seq(18,34,2))

# change plot type to filled.contour style
plotPerformanceSpace(type="filled.contour",performance=egSimPerformance,
                     sim=egSimSummary, metric = "Avg. Deficit (L)",
                     climData = egClimData, perfThresh = 27.5,
                     perfThreshLabel = "Max Avg. Deficit",axesPercentLabel=TRUE,
                     contourBreaks=seq(18,34,2))

#example overlay points manually from a dataset in a similar style to egClimData
ptStyle= c(21,22, 24)  #select set of pt styles (e.g. hollow circle, square, triangle)
plotPerformanceSpace(performance=egSimPerformance[1], sim=egSimSummary,axesPercentLabel=TRUE)+
ggplot2::geom_point(data = egClimData,
                    mapping = ggplot2::aes(x = .data[["P_ann_tot_m"]],
                    y = .data[["P_ann_seasRatio"]],
                    shape = .data[["Name"]]),
                    show.legend = TRUE, size = 5, colour = "black", fill = "lightgray") +
ggplot2::scale_shape_manual(name = NULL, values = ptStyle,
                            guide = ggplot2::guide_legend(order = 2, nrow = 1))+
                   #one row of legend for specified ptStyle types
ggplot2::theme(legend.box="vertical", # vertical arrangement of items in legends
               legend.position="bottom", # position legends base of figure
               legend.justification=c(0,0)) # justification according to the plot area

# example of performance generated using simple scaled simulation
data("egScalPerformance")
data("egScalSummary")
data("egClimData")
plotPerformanceSpace(performance=egScalPerformance[1], sim=egScalSummary, climData = egClimData,
                     perfThresh = 28.25, perfThreshLabel = "Max Avg. Deficit")
                     }