plotPerformanceSpace: Plots a performance space using the system performance and...
In foreSIGHT: Systems Insights from Generation of Hydroclimatic Timeseries

plotPerformanceSpace

R Documentation

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
)

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.

Value

The plot of the performance space and the ggplot object.

Examples

# 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)

## Not run: 
# 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")
                     
## End(Not run)

foreSIGHT documentation built on Oct. 19, 2023, 9:08 a.m.