mau

Description

Provides functions for the creation, evaluation and test of decision models based in Multi Attribute Utility Theory (MAUT).

Details

MAUT models are defined employing a decision tree where similarity relations between different index utilities are defined, this helps to group utilities following a criteria of similarity. Each final node has an utility and weight associated, the utility of any internal node in the decision tree is computed by adding the weighted sum of eaf of its final nodes. In a model with n indexes, a criteria is composed by C \subset \{1,\ldots,n\}, the respective utility is given by:

\sum_{i \in C}^n w_i u_i( x_i )

Currently, each utility is defined like a piecewise risk aversion utility, those functions are of the following form:

a x + b

or

a e^{cx} + b

The current capabilities of mau are:

1. Read a list of risk aversion utilities defined in a standardized format.

2. Evaluate utilities of a table of indexes.

3. Load decision trees defined in column standard format.

4. Compute criteria utilities and weights for any internal node of the decision tree.

5. Simulate weights employing Dirichlet distributions under addition constraints in weights.

Author(s)

Maintainer: Pedro Guarderas pedro.felipe.guarderas@gmail.com

Other contributors:

• Felipe Aguirre [contributor]

• Julio Andrade [contributor]

• Daniel Lagos [contributor]

• Andrés Lopez [contributor]

• Nelson Recalde [contributor]

• Edison Salazar [contributor]

References

Bell D., Raiffa H. and Tversky A. (1988). Decision Making: Descriptive, normative and prescriptive interactions. Cambridge University Press.

Clement R. (1991). Marking Hard Decision: An introduction to decision analysis. PWS-Kent Publishing Co.

Ward E. (1992). Utility Theories: Measurements and Applications. Kluwer Academic Publishers.

Barron FH and Barrett BE (1996). “Decision Quality Using Ranked Attribute Weights.” Manage. Sci., 42(11), pp. 1515–1523. ISSN 0025-1909, doi: 10.1287/mnsc.42.11.1515.

Bodily SE (1992). “Introduction: The Practice of Decision and Risk Analysis.” Interfaces, 22(6), pp. 1-4. doi: 10.1287/inte.22.6.1.

See Also

Useful links:

• https://github.com/pedroguarderas/mau

Examples

library( mau )
vignette( topic = 'Running_MAUT', package = 'mau' ) 

Bar plot of utilities

Description

Create ggplot2 bar plots of the utilities at any level of the decision model

Usage

Bar.Plot(model, deep, colors, title, xlab, ylab)

Arguments

Value

ggplot2 object.

Author(s)

Pedro Guarderas pedro.felipe.guarderas@gmail.com

Examples

vignette( topic = 'Running_MAUT', package = 'mau' ) 

Evaluation of decision tree nodes

Description

Evaluation of decision tree nodes. All the MAUT model is computed at every level the utilities are computed considering the given weights.

Usage

Compute.Model(tree, utilities, weights)

Arguments

Details

The whole decision model can be computed a any level and represented in a table format.

Value

data.table structure containing the utilities of the model for every level the decision tree.

Author(s)

Pedro Guarderas, Andrés Lopez pedro.felipe.guarderas@gmail.com

See Also

Stand.String, Read.Utilities, Eval.Utilities, Read.Tree, Make.Decision.Tree, Sim.Const.Weights.

Examples

vignette( topic = 'Running_MAUT', package = 'mau' )

Compute the deep position of every node

Description

For the computation of the complete decision model is necessary to establish the deep position of every node.

Usage

Deep.Compute(tree)

Arguments

Value

igraph object updated

Author(s)

Pedro Guarderas, Andrés Lopez

See Also

Read.Tree

Divide weights of internal nodes

Description

After the addition of weights for internal nodes the final weights have to be computed dividing by the total weight of each parent.

Usage

Divide.Weights(tree)

Arguments

Value

igraph object updated

Author(s)

Pedro Guarderas, Andrés Lopez

See Also

Read.Tree

Evaluate utilities

Description

Evaluation of utilities for a data.table of indexes, the utilities functions are computed over every index represented by each column of the input table.

Usage

Eval.Utilities(index, columns, functions)

Arguments

Details

Every index has associated an utility function, inside mau is possible to employ any functions, the only special requirement is that the utility has to be normalized, this means that the utility is bounded between 0 and 1.

Also is possible to consider utilities with constant risk aversion CRA, in the sense of Arrow, for such case there is only two types of functions u(x) = a x + b or u(x) = a e^{bx} + c, to determine these functions, it is only necessary to specify the parameters a, b and c. For a decision model only elaborated with CRA utilities, mau could read a text file where every utility is piecewise defined.

The format for the text file containing the definition of utility functions is given by is:

[Header]

[Function name]
[min1 max1 a1 b1 c1]
[min2 max2 a2 b2 c2]
[min3 max3 a3 b3 c3]
...
[Function name]
[min1 max1 a1 b1 c1]
[min2 max2 a2 b2 c2]
[min3 max3 a3 b3 c3]
...

If the coefficient c is non zero the function is interpreted as an exponential type.

Value

data.table with utilities evaluated for every index.

Author(s)

Pedro Guarderas, pedro.felipe.guarderas@gmail.com, Andrés Lopez.

See Also

Read.Utilities, Stand.String

Examples

library( mau )
vignette( topic = 'Running_MAUT', package = 'mau' ) 

Compute leaves weights

Description

The computation of weights could be determined in an inverse processes given the internal weights.

Usage

Index.Weights(tree)

Arguments

Value

igraph object updated

Author(s)

Pedro Guarderas, Andrés Lopez

See Also

Read.Tree

Evaluate utilities

Description

Create decision tree for MAUT models exporting to an igraph object.

Usage

Make.Decision.Tree(tree.data)

Arguments

Details

With the tree information loaded by the Read.Tree the decision tree could be represented like an igraph object.

Value

igraph object containing the graph of the decision tree.

Author(s)

Pedro Guarderas, Andrés Lopez pedro.felipe.guarderas@gmail.com

See Also

Read.Tree

Examples

library( data.table )
library( igraph )
file<-system.file("extdata", "tree.csv", package = "mau" )
tree.data<-Read.Tree( file, skip = 0, nrows = 8 )
tree<-Make.Decision.Tree( tree.data )
plot( tree )

Plot decision MAUT model with weights simulations

Description

Spider plot for the decision model considering the weights simulated with a Dirichlet distributions, every simulation is represented with lines, a box plot is included to account the behavior of every global utility.

Usage

Plot.Simulation.Weight(S, title = "Simulations", xlab = "ID",
  ylab = "Utility", lines.cols = "blue", box.col = "gold",
  box.outlier.col = "darkred", utility.col = "darkgreen",
  utility.point.col = "darkgreen", text.col = "black")

Arguments

Value

ggplot object with the plot of simulations.

Author(s)

Pedro Guarderas

See Also

Sim.Const.Weights Sim.Weights

Evaluate utilities

Description

Read a csv file where the decision tree is defined.

Usage

Read.Tree(file, skip, nrows)

Arguments

Value

data.table with utilities.

Author(s)

Pedro Guarderas, Andrés Lopez

See Also

Read.Utilities, Make.Decision.Tree

Examples

library( data.table )
library( igraph )
file<-system.file("extdata", "tree.csv", package = "mau" )
sheetIndex<-1
tree.data<-Read.Tree( file, skip = 0, nrows = 8 )

Read utilities

Description

Builds utility functions from definition standard.

Usage

Read.Utilities(file, script, lines, skip = 2, encoding = "utf-8")

Arguments

Details

The basic MAUT models are built with functions of constant absolute risk aversion, this functions could be defined with simple parameters, only is necessary a function name and the domain of definition of every function and more important is necessary no more than three coefficients for the function definition.

Value

Returns data table with definition of utility functions by range.

Author(s)

Pedro Guarderas, Andrés Lopez

See Also

Stand.String

Examples

library( data.table )
file<-system.file("extdata", "utilities.txt", package = "mau" )
script<-'utilities.R'
lines<-17
skip<-2
encoding<-'utf-8'
functions<-Read.Utilities( file, script, lines, skip, encoding )

Simulation of constrained weights

Description

Simulation of weights employing the Dirichlet distribution. The concentration parameters for the Dirichlet distribution are tentative weights, additionally constraints over partial sums of weights are introduced by a list ordered structure.

Usage

Sim.Const.Weights(n, utilities, alpha, constraints)

Arguments

Details

Employing the properties of the Dirichlet distribution, weights could be simulated with a given concentration, additionally this simulation can be carry out by subsets of weights only to meet specific constraints.

Value

List with data.frames {simulation, weights} with total utilities and simulated weights

Author(s)

Pedro Guarderas pedro.felipe.guarderas@gmail.com

See Also

Eval.Utilities

Examples

library( data.table )
N<-10
utilities<-data.table( id = 1:N, 
                       u1 = runif( N, 0, 1 ), 
                       u2 = runif( N, 0, 1 ), 
                       u3 = runif( N, 0, 1 ),
                       u4 = runif( N, 0, 1 ) )
n<-100
alpha<-c( 0.2, 0.5, 0.1, 0.2 )
constraints<-list( list( c(1,2), 0.7 ), 
                   list( c(3,4), 0.3 ) )
S<-Sim.Const.Weights( n, utilities, alpha, constraints )
plot.S<-Plot.Simulation.Weight( S$simulation, title = 'Simulations', 
                                xlab = 'ID', ylab = 'Utility' ) 
plot( plot.S )

Simulation of weights

Description

Simulation of weights employing the Dirichlet distribution. The concentration parameters for the Dirichlet distribution are tentative weights.

Usage

Sim.Weights(n, utilities, alpha)

Arguments

Details

Taking advantage of the Dirichlet distribution properties, the weights could be simulated with a concentration around given weights.

Value

List with data.frames {simulation, weights} with total utilities and simulated weights

Author(s)

Pedro Guarderas pedro.felipe.guarderas@gmail.com

See Also

Eval.Utilities

Examples

library( data.table )
N<-10
utilities<-data.table( id = 1:N, 
                       u1 = runif( N, 0, 1 ), 
                       u2 = runif( N, 0, 1 ), 
                       u3 = runif( N, 0, 1 ),
                       u4 = runif( N, 0, 1 ) )
n<-100
alpha<-c( 0.2, 0.5, 0.1, 0.2 )
S<-Sim.Weights( n, utilities, alpha )

Spider plot

Description

Generates an spider plot for a decision model

Usage

Spider.Plot(data, data.label, data.fill, data.color, data.linetype, data.alpha,
  data.size, data.label.color, data.label.size, group, criteria, valor, title,
  title.color, title.size, label.size, label.color, label.angle, label.position,
  theta, grid, grid.color, grid.radius.color, grid.linetype, grid.size,
  grid.radius.linetype, grid.radius.size, axis, axis.label, axis.color,
  axis.size, axis.linetype, axis.angle, axis.label.color, axis.label.size,
  axis.label.displace, axis.label.angle, legend.position, legend.size,
  legend.text.color, plot.margin)

Arguments

Value

ggplot2 object with the spider plot

Author(s)

Pedro Guarderas, Andrés Lopez pedro.felipe.guarderas@gmail.com

Examples

# Preparing data
library( data.table )
library( ggplot2 )
n<-10
m<-7
cols<-sample( colors()[ grepl('(red|blue|olive|darkgree)', colors() ) ], m, replace = TRUE )

data<-data.frame( grp = paste( 'A', sort( rep( 1:m, n ) ), sep = '' ),
                  cri = factor( rep( paste( 'c', 1:n, sep = '' ), m ), 
                                levels = paste( 'c', 1:n, sep = '' ), ordered = TRUE ),
                  val = runif( m * n ) )

data.label<-paste( 'A', 1:m,  ' class', sep = '' )
data.fill<-cols
data.color<-cols
data.linetype<-rep( 'solid', m )
data.alpha<-rep( 0.05, m )
data.size<-rep( 0.7, m )
data.label.color<-'black'
data.label.size<-15

# Spider plot parameters
title<-'Spider'
title.color<-'red3'
title.size<-20

label.size<-rep( 8, n )
label.color<-rep( 'steelblue4', n )
label.angle<-rep( 0, n )
label.position<-rep( 1.1, n )

theta<-pi/2

grid<-sort( c( 0.1, 0.25, 0.5, 0.75, 1.0 ) )
grid.color<-'grey'
grid.radius.color<-'dodgerblue3'
grid.linetype<-'dashed'
grid.size<-0.5
grid.radius.linetype<-'solid'
grid.radius.size<-0.5

axis<-grid # Same as grid
axis.label<-paste( 100 * axis, '%', sep = '' )
axis.color<-'black'
axis.size<-0.7
axis.linetype<-'solid'
axis.angle<-0.4*pi
axis.label.color<-'darkgreen'
axis.label.size<-5
axis.label.displace<- -0.07
axis.label.angle<-0

legend.position<-c(0.9, 0.9)
legend.size<-0.5
legend.text.color<-'black'

plot.margin<-unit( c( 1.0, 1.0, 1.0, 1.0 ),"cm")


p<-Spider.Plot( data,
                data.label,
                data.fill,
                data.color,
                data.linetype,
                data.alpha,
                data.size,
                data.label.color, 
                data.label.size,
                grp,
                cri,
                val, 
                title,
                title.color,
                title.size,
                label.size, 
                label.color,
                label.angle,
                label.position,
                theta, 
                grid, 
                grid.color, 
                grid.radius.color,
                grid.linetype, 
                grid.size, 
                grid.radius.linetype, 
                grid.radius.size, 
                axis, 
                axis.label,
                axis.color,
                axis.size, 
                axis.linetype, 
                axis.angle, 
                axis.label.color,
                axis.label.size, 
                axis.label.displace,
                axis.label.angle,
                legend.position,
                legend.size,
                legend.text.color,
                plot.margin )

plot(p)

Standardize strings

Description

Function to correct and standardize names, designed to eliminate special characters, spaces and other characters.

Usage

Stand.String(x, chr = NULL, rep = NULL)

Arguments

Value

Returns data table with definition of utility functions by range

Author(s)

Julio Andrade, Pedro Guarderas, Andrés Lopez pedro.felipe.guarderas@gmail.com

Examples

 x<-c( "H?\u00da\u00e0n with C@1_ad1", 
       "M\u00a1a/\u00ac\u00b0r&\u00eca *_the#-rot", 
       "ju%LI\u00d6 a P\u00e9rs", 
       "(S)tev\n\u00e9n\t los cat%$" )
 y<-sapply( x, FUN = Stand.String )
 names( y )<-NULL

Sum weights for internal nodes

Description

The weights of the internal nodes has to be computed first is necessary to add each weights of the leaves.

Usage

Sum.Weights(tree)

Arguments

Value

igraph object updated

Author(s)

Pedro Guarderas, Andrés Lopez

See Also

Read.Tree