utility.aggregation.create {utility}

Construct an aggregation node

Description

Function to construct an aggregation node for value or utlity functions.

Usage

utility.aggregation.create(name.node, 
                           nodes, 
                           name.fun, 
                           par, 
                           names.par    = rep(NA, length(par)), 
                           required     = FALSE, 
                           num.required = 1, 
                           col          = "black", 
                           shift.levels = 0,
                           add.arg.fun  = NULL)

Arguments

name.node

name of the node to be constructed as a character string.

nodes

list of nodes to be aggregated.

name.fun

name of the function to be used for aggregation. This function must accept the arguments u and par which pass a vector of values or utilities to be aggregated and the parameters of the function, respectively. The function can have an additional argument specified below as add.arg.fun. The function must then return the corresponding aggregated value or utility.
Examples of functions provided by the package are
utility.aggregate.add for additive aggregation (weighted arithmetic mean),
utility.aggregate.min for minimum aggregation,
utility.aggregate.max for maximum aggregation,
utility.aggregate.geo or utility.aggregate.cobbdouglas for geometric or Cobb-Douglas aggregation (weighted geometric mean),
utility.aggregate.geooff for geometric aggregation with offset,
utility.aggregate.revgeo for reverse geometric aggregation,
utility.aggregate.revgeooff for reverse geometric aggregation with offset,
utility.aggregate.harmo for harmonic aggregation (weighted harmonic mean),
utility.aggregate.harmooff for harmonic aggregation with offset,
utility.aggregate.revharmo for reverse harmonic aggregation,
utility.aggregate.revharmooff for reverse harmonic aggregation with offset,
utility.aggregate.mult for multiplicative aggregation,
utility.aggregate.mix for a mixture of additive, minimum, and geometric aggregation,
utility.aggregate.addmin for a mixture of additive and minimum aggregation.
utility.aggregate.addpower for additive power aggregation (weighted power mean),
utility.aggregate.revaddpower for reverse additive power aggregation,
utility.aggregate.addsplitpower for splitted additive power aggregation,
utility.aggregate.revaddsplitpower for reverse splitted additive power aggregation,
utility.aggregate.bonusmalus for an aggregation technique that considers some of the values or utilities of sub-objectives only as bonus or malus.
Follow the links for the aggregation functions for their use, for the underlying mathematical expressions and for graphical illustrations.

par

numeric vector of parameter values to be passed to the function specified unter name.fun.

names.par

(optional) vector of parameter names corresponging to the vector of values specified under par. Only required to provide access to the values through a named parameter vector.

required

(optional) logical variable indicating if the value of this node is required for aggregation at the next higher level. If this variable is TRUE, aggregation at the next higher level is not possible if this node returns NA. Default value is FALSE.

num.required

number of lower-level values or utilities that must at least be available to make the evaluation possible.

col

(optional) color used for plotting the bounding box of the node in the objective hierarchy. Default value is "black".

shift.levels

(optional) number of hierarchical levels by which the node in the objective hierarchy is shifted to make a branch fit better to other branches. Default value is 0.

add.arg.fun

(optional) an additional argument to the aggregation function name.fun. The value(s) given here will alway be passed to the aggregation function.

Value

The function returns the created object of type utility.aggregation with the properties specified in the arguments of the function.

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.

Description of aggregation techniques:

Langhans, S.D., Reichert, P. and Schuwirth, N., The method matters: A guide for indicator aggregation in ecological assessments. Ecological Indicators 45, 494-507, 2014.

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

Print, evaluate and plot the node with

print.utility.aggregation,
summary.utility.aggregation,
evaluate.utility.aggregation and
plot.utility.aggregation.

Create end nodes with

utility.endnode.discrete.create,
utility.endnode.intpol1d.create,
utility.endnode.intpol2d.create,
utility.endnode.parfun1d.create,
utility.endnode.cond.create, or
utility.endnode.firstavail.create.

Create conversion nodes with

utility.conversion.intpol.create, or
utility.conversion.parfun.create.

Examples

  # define discrete end node for width variability
  # (attribute "widthvariability_class" with levels "high", 
  # "moderate" and "none")
  
  widthvar <- 
    utility.endnode.discrete.create(
      name.node     = "width variability",
      attrib.levels = data.frame(widthvariability_class=
                                 c("high","moderate","none")),
      u             = c(1,0.4125,0),
      names.u       = c("u.high","u_moderate","u.none"),
      required      = FALSE,
      utility       = FALSE)

  # define 1d interpolation end node for bed modification with 
  # riprap
  # (attribute "bedmodfract_percent" with levels from 0 to 100)
  
  bedmod_riprap <-
    utility.endnode.intpol1d.create(
      name.node   = "bed modification riprap",
      name.attrib = "bedmodfract_percent",
      range       = c(0,100),
      x           = c(0,10,30,100),
      u           = c(1,0.775,0.5625,0.24),
      required    = FALSE,
      utility     = FALSE)
  
  # define 1d interpolation end node for bed modification with 
  # other material
  # (attribute "bedmodfract_percent" with levels from 0 to 100)
  
  bedmod_other <-
    utility.endnode.intpol1d.create(
      name.node   = "bed modification other",
      name.attrib = "bedmodfract_percent",
      range       = c(0,100),
      x           = c(0,10,30,100),
      u           = c(1,0.775,0.5625,0),
      required    = FALSE,
      utility     = FALSE)
  
  # define combination end node for bed modification
  # (attributes "bedmodtype_class" and "bedmodfract_percent")
  
  bedmod <-
    utility.endnode.cond.create(
      name.node     = "bed modification",
      attrib.levels = data.frame(bedmodtype_class=
                                 c("riprap","other")),
      nodes         = list(bedmod_riprap,bedmod_other),
      required      = FALSE,
      utility       = FALSE)
 
  # define 1d interpolation end node for bank modification with 
  # permeable material
  # (attribute "bankmodfract_percent" with levels from 0 to 100)
  
  bankmod_perm <-
    utility.endnode.intpol1d.create(
      name.node   = "bank modification perm",
      name.attrib = "bankmodfract_percent",
      range       = c(0,100),
      x           = c(0,10,30,60,100),
      u           = c(1,0.8667,0.675,0.4125,0.24),
      required    = FALSE,
      utility     = FALSE)
  
  # define 1d interpolation end node for bank modification with 
  # impermeable material
  # (attribute "bankmodfract_percent" with levels from 0 to 100)
  
  bankmod_imperm <-
    utility.endnode.intpol1d.create(
      name.node   = "bank modification imperm",
      name.attrib = "bankmodfract_percent",
      range       = c(0,100),
      x           = c(0,10,30,60,100),
      u           = c(1,0.775,0.5625,0.24,0),
      required    = FALSE,
      utility     = FALSE)
  
  # define combination end node for bank modification
  # (attributes "bankmodtype_class" and "bankmodfract_percent")
  
  bankmod <-
    utility.endnode.cond.create(
      name.node     = "bank modification",
      attrib.levels = data.frame(bankmodtype_class=
                                 c("perm","imperm")),
      nodes         = list(bankmod_perm,bankmod_imperm),
      required      = FALSE,
      utility       = FALSE)

  # define 2d interpolation end node for riparian zone width
  # (attributes "riparianzonewidth_m" and "riparianzonewidth_m")

  riparzone_width <-
    utility.endnode.intpol2d.create(
      name.node   = "riparian zone width",
      name.attrib = c("riverbedwidth_m","riparianzonewidth_m"),
      ranges      = list(c(0,16),c(0,30)),
      isolines    = list(list(x=c(0,16),y=c(0,0)),
                         list(x=c(0,2,10,16),y=c(5,5,15,15)),
                         list(x=c(0,16),y=c(15,15)),
                         list(x=c(0,16),y=c(30,30))),
      u           = c(0.0,0.6,1.0,1.0),
      lead         = 1,
      utility      = FALSE)

  # define discrete end node for riparian zone vegetation
  # (attriute "riparianzoneveg_class" with levels "natural", 
  # "seminatural" and "artificial")

  riparzone_veg <-
    utility.endnode.discrete.create(
      name.node     = "riparian zone veg.",
      attrib.levels = data.frame(riparianzoneveg_class=
                                 c("natural","seminatural","artificial")),
      u             = c(1,0.5625,0),
      required      = FALSE,
      utility       = FALSE)
  
  # define aggregation node for riparian zone
  
  riparzone <-
    utility.aggregation.create(
      name.node = "riparian zone",
      nodes     = list(riparzone_width,riparzone_veg),
      name.fun  = "utility.aggregate.cobbdouglas",
      par       = c(1,1),
      required  = FALSE)
  
  # define aggregation node for ecomorphological state
  
  morphol <-
    utility.aggregation.create(
      name.node = "ecomorphology",
      nodes     = list(widthvar,bedmod,bankmod,riparzone),
      name.fun  = "utility.aggregate.mix",
      par       = c(0.25,0.25,0.25,0.25,0,0,1),
      names.par = c("w_widthvar","w_bedmod","w_bankmod","w_riparzone",
                    "w_add","w_min","w_cobbdouglas"),
      required  = TRUE)
      
  # print individual definitions
  
  print(widthvar)
  print(bedmod)
      
  # print all definitions
  
  print(morphol)
  
  # plot objectives hierarchy with attributes
  
  plot(morphol)
  
  # plot individual nodes:

  plot(widthvar)
  plot(widthvar,par=c(u_moderate=0.2))
  plot(bedmod_other)
  plot(bankmod)
  #plot(riparzone_width)
  
  # plot selected node definitions of a hierarchy
  
  plot(morphol,type="nodes",nodes=c("width variability",
                                    "bed modification other",
                                    "bank modification"))

  # evaluate value function for data sets and plot colored hierarchies
  # and table
  
  attrib_channelized <- data.frame(widthvariability_class = "none",
                                   bedmodtype_class       = "riprap",
                                   bedmodfract_percent    = 50,
                                   bankmodtype_class      = "imperm",
                                   bankmodfract_percent   = 70,
                                   riverbedwidth_m        = 10,
                                   riparianzonewidth_m    = 5,
                                   riparianzoneveg_class  = "seminatural")
  attrib_rehab       <- data.frame(widthvariability_class = "high",
                                   bedmodtype_class       = "riprap",
                                   bedmodfract_percent    = 50,
                                   bankmodtype_class      = "imperm",
                                   bankmodfract_percent   = 20,
                                   riverbedwidth_m        = 15,
                                   riparianzonewidth_m    = 15,
                                   riparianzoneveg_class  = "natural")
                                   
  res_channelized     <- evaluate(morphol,attrib=attrib_channelized)
  res_channelized_add <- evaluate(morphol,attrib=attrib_channelized,
                                  par=c(w_add=1,w_min=0,w_cobbdouglas=0))
  res_rehab           <- evaluate(morphol,attrib=attrib_rehab)
  res_both            <- rbind(res_channelized,res_rehab)
  rownames(res_both)  <- c("channelized","rehabilitated")
  
  plot(morphol,u=res_channelized)
  plot(morphol,u=res_channelized_add)
  plot(morphol,u=res_rehab)
  plot(morphol,u=res_rehab,uref=res_channelized)
  plot(morphol,u=res_both,type="table")

  # consideration of uncertain attribute levels (higher uncertainty for 
  # predicted state after rehabilitation than for observed channelized state):
  
  sampsize <- 2000
  
  attrib_channelized_unc <- data.frame(
    widthvariability_class = rep("high",sampsize),
    bedmodtype_class       = rep("riprap",sampsize),
    bedmodfract_percent    = rnorm(sampsize,mean=50,sd=5),
    bankmodtype_class      = rep("imperm",sampsize),
    bankmodfract_percent   = rnorm(sampsize,mean=70,sd=5),
    riverbedwidth_m        = rep(10,sampsize),
    riparianzonewidth_m    = rep(5,sampsize),
    riparianzoneveg_class  = c("seminatural","artificial")[rbinom(sampsize,1,0.5)+1])

  attrib_rehab_unc <- data.frame(
    widthvariability_class = c("moderate","high")[rbinom(sampsize,1,0.5)+1],
    bedmodtype_class       = rep("riprap",sampsize),
    bedmodfract_percent    = rnorm(sampsize,mean=50,sd=15),
    bankmodtype_class      = rep("imperm",sampsize),
    bankmodfract_percent   = rnorm(sampsize,mean=20,sd=5),
    riverbedwidth_m        = rnorm(sampsize,mean=10,sd=2),
    riparianzonewidth_m    = rnorm(sampsize,mean=10,sd=2),
    riparianzoneveg_class  = c("natural","seminatural")[rbinom(sampsize,1,0.5)+1])

  res_channelized_unc <- evaluate(morphol,attrib=attrib_channelized_unc)
  res_rehab_unc       <- evaluate(morphol,attrib=attrib_rehab_unc)

  plot(morphol,u=res_channelized_unc)
  plot(morphol,u=res_rehab_unc)
  plot(morphol,u=res_rehab_unc,uref=res_channelized_unc)