plot.utility.aggregation {utility}

Plot Node Definition or Underlying Objectives Hierarchy

Description

Plot node definition or underlying objective hierarchy.

Usage

## S3 method for class 'utility.aggregation'
plot(x, 
     u           = NA, 
     uref        = NA, 
     par         = NA, 
     type        = c("hierarchy", "table", "node", "nodes"), 
     nodes       = NA, 
     col         = utility.calc.colors(), 
     gridlines   = c(0.2, 0.4, 0.6, 0.8), 
     main        = "", 
     cex.main    = 1, 
     cex.nodes   = 1, 
     cex.attrib  = 1, 
     f.reaches   = 0.2,
     f.nodes     = 0.2,
     with.attrib = TRUE,
     levels      = NA,
     plot.val    = TRUE,
     col.val     = "black",
     lwd.val     = 1,
     print.val   = TRUE,
     two.lines   = FALSE,
     ticks       = c(0,0.2,0.4,0.6,0.8,1),
     ...)

Arguments

x

node to be plotted.

u

(optional) vector or data frame with elements or columns labelled according to the nodes of the hierarchy containing values or utilities. Typically, this will be the complete output or an output row of the function
evaluate.utility.aggregation.
This input is only considered if the argument type is specified to be either "hierarchy" or "table". It is then used to color-code the boxes of the hierarchy representing value nodes or the table. If u is a data frame with more than one row and the argument type is equal to "hierarchy", then the median and quantile boxes are plotted for value nodes or the expected utility for utility nodes unless the argument main contains as many elements as the number of rows of u. In the latter case, separate hierarchies with color-coded boxes for value nodes are produced for all rows of u. For type equals "table", this argument can be a list of data frames to make it possible to plot uncertainty ranges from the samples provided in the list.

uref

(optional) vector or data frame with elements or columns labelled according to the nodes of the hierarchy containing values or utilities. Typically, this will be the complete output or an output row of the function
evaluate.utility.aggregation.
This input is only considered if the argument type is specified to be "hierarchy". It is then used to color-code the upper part of the boxes of the hierarchy to allow for a comparison with the results provided by the argument u which are shown in the lower part of the boxes.

par

(optional) labelled numeric parameter vector providing parameters to modify the value or utility function before plotting the node. Note that this affects only the node definitions plotted if the argument type is specified to be "node" or "nodes". To color-code hierarchies or tables for different parameter values, the parameters have to be passed to
evaluate.utility.aggregation
before passing the results of this function to this plotting routine.

type

(optional) specifies the type of plot to be produced.
Options: "hierarchy", "table", "node" or "nodes".
"hierarchy": produces a plot of the objectives hierarchy including color-coded results for values or utilities if these values are provided by the arguments u and/or uref.
"table": produces a table with color-coded results for values or utilities if these values are provided by the argument u.
"node": produces a plot of the definition of the current node.
"nodes": produces plots of node definitions for all nodes defined by the attribute nodes.

nodes

(optional) character vector specifying the nodes for which the definitions will be plotted or which will be considered in a table. The default value of NA indicates that all nodes will be plotted. This argument only affects the output if the argument type was indicated to be either "table" or "nodes".

col

(optional) character vector of colors to be used to color the interval between zero and unity in equidistant sections (use repetitions of the same color if you want to have a non-equidistant color-coding). This attribute is only used for value nodes and if values are provided by the arguments u and/or uref.

gridlines

(optional) numeric vector of levels at which gridlines are plotted in node definitions. This attribute is only used if the argument type is specified to be either "node" or "nodes".

main

(optional) title(s) of the plot. If the argument type is equal to "hierarchy" and the a vector of titles with the same length as the number of rows of the argument u is provided, a color-coded hierarchy is plotted for each row of u. Otherwise, the medians and colored boxes indicating 90% credibility or occurrence ranges are plotted at all nodes.

cex.main

(optional) scaling factor for title of the plot.

cex.nodes

(optional) scaling factor for node labels used in the plot.

cex.attrib

(optional) scaling factor for attribute labels used in the plot.

f.reaches

(optional) fraction of the width of the plot reserved for the row labels of the table if the argument type is equal to "table".

f.nodes

(optional) fraction of the height of the plot reserved for the column labels of the table if the argument type is equal to "table".

with.attrib

(optional) indicates if attributes should be listed if the argument type is equal to "hierarchy".

levels

(optional) how many levels of the hierarchy should be plotted (NA means to plot all levels).

plot.val

(optional) plot value (for hierarchy without uncertainty) or median (for hierarchy with uncertainty) as a vertical line within the box.

col.val

(optional) color of the vertical line indicating the value or median within the box (default black).

lwd.val

(optional) line width of the vertical line indicating the value or median within the box (default 1).

print.val

(optional) print value as a number when plotting a table of boxes.

two.lines

(optional) choose whether two lines should be used for the labels in the hierarchy plot.

ticks

(optional) positions of tick marks for hierarchy and table plots (NA or numeric(0) avoids tick marks).

...

additional arguments passed to the R plotting routine.

Note

Note that the plotting routines
plot.utility.conversion.intpol
plot.utility.conversion.parfun
are exactly the same so that all hierarchies can be plotted with exactly the same commands irrespective of the type of the top-level node.

Author(s)

Peter Reichert <[e-mail]>

References

Short description of the package:

Reichert, P., Schuwirth, N. and Langhans, S., Constructing, evaluating and visualizing value and utility functions for decision support, Environmental Modelling & Software 46, 283-291, 2013.

Textbooks on the use of utility and value functions in decision analysis:

Keeney, R. L. and Raiffa, H. Decisions with Multiple Objectives - Preferences and Value Tradeoffs. John Wiley & Sons, 1976.

Eisenfuehr, F., Weber, M. and Langer, T., Rational Decision Making, Springer, Berlin, 2010.

See Also

See utility.aggregation.create for how to construct such a node and evaluate.utility.aggregation for how to evaluate the node.

See utility.calc.colors for an example of how to construct color schemes and utility.get.colors for how to get colors for specifed value levels.

Examples

# see
help(utility)
# for examples.