Author: Pedro Guarderas
Date: 2023-10-25

# Running a MAUT Model

#### Pedro Guarderas

#### October 25, 2023

## Introduction

The decision models based in Multi Attribute Utility Theory (MAUT) are defined with aid of utility functions \(u_1,\ldots,u_n\) which are evaluated over indexes \(x_1,\ldots,x_n\) and those utilities are aggregated considering additional weights \(w_1,\ldots,w_n\), the whole final utility is given by the sum \[u(x_1,\ldots,x_n) = \sum_{i=1}^n\, w_i\, u_i\ ( x_i )\] every utility \(u_i\) can be normalized to take values only between \(0\) and \(1\).

A model based in MAUT additionally has a decision tree that represents the relations between subsets of utilities, given an ordered and conceptual development of the decision model.

This mau package is designed to implement and test decision models based in (MAUT).

## Utility definition

The utility functions for a MAUT model could be defined in a practical format when the utilities are piecewise defined like Constant Risk Averse Utilities (CRAU for short), satisfying the equation: \[ \frac{u''}{u'} = \lambda \] being \(\lambda\) a constant. The previous equation only admits two kind of solutions, \(u(x) = a \cdot x + b\) or \(u(x) = a \cdot e^{b \cdot x} + c\). To completely determine an utility, it is only necessary to know the three parameters \(a,b,c\). Additionally, the following convention is assumed, if \(c\) is \(0\) then the utility is linear otherwise is an exponential function.

For piecewise CRAU, it is only necessary to define the parameters \(a,b,c\) of the function for each part of the domain of definition. The mau package could load the utilities from an standardized text file with the following internal structure.

The capabilities of mau are not only restricted to work with CRAU class, you can define any utility by employing the correct R script.

> 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
> …

Here an example of the structure of the standardized file for utility definitions

    library( mau )
    file <- system.file( "extdata", "utilities.txt", package = "mau" )
    lines <- readLines( file )
    for ( i in 1:length( lines ) ) {
      cat( lines[i], '\n' )
    }

    ## Utilities
    ##
    ## Project
    ##  1   2   1.5 -0.5    0
    ##  2   3   1.5 -0.5    0
    ##
    ## Self implementation
    ##  1   2   1.5 -0.5    0
    ##  2   3   1.5 -0.5    0
    ##
    ## External and local relations
    ##  1   10  1   0   0
    ##  0   1   0   1   0
    ##
    ## Scope of capabilities
    ##  6   15  1   0   0
    ##  0   6   1.225   -1.225  0.2824

## Main example

In the sources below is developed a complete example of a MAUT model, the package mau is employed to load utilities defined in the file `utilities.txt`, automatically the script with utilities is built and saved in the local working directory, after that with `eval_utilities` every function is evaluated over the columns of the index table, the names for utilities were previously standardized with `stand_string`. With another file `tree.csv` the decision tree associated to the MAUT model is built and every weight and relative weight assigned with the `make_decision_tree` function, in addition the whole model with utilities of every criteria is obtained with `compute_model`. The simulation of constrained weights is made with `sim_const_weights`, the result could be employed for a sensitivity test of the decision model regarding concentrated weights variation.

1. Loading necessary packages

    library( mau )
    library( data.table )
    library( igraph )
    library( ggplot2 )

2. Index definition

    index <- data.table( cod = paste( 'A', 1:10, sep = '' ),
                         i1 = c( 0.34, 1, 1, 1, 1, 0.2, 0.7, 0.5, 0.11, 0.8 ),
                         i2 = c( 0.5, 0.5, 1, 0.5, 0.3, 0.1, 0.4, 0.13, 1, 0.74 ),
                         i3 = c( 0.5, 1.0, 0.75, 0.25, 0.1, 0.38, 0.57, 0.97, 0.3, 0.76 ),
                         i4 = c( 0, 0.26, 0.67, 0.74, 0.84, 0.85, 0.74, 0.65, 0.37, 0.92 ) )

cod | i1 | i2 | i3 | i4
--- | --- | --- | --- | ---
A1 | 0.34 | 0.50 | 0.50 | 0.00
A2 | 1.00 | 0.50 | 1.00 | 0.26
A3 | 1.00 | 1.00 | 0.75 | 0.67
A4 | 1.00 | 0.50 | 0.25 | 0.74
A5 | 1.00 | 0.30 | 0.10 | 0.84
A6 | 0.20 | 0.10 | 0.38 | 0.85
A7 | 0.70 | 0.40 | 0.57 | 0.74
A8 | 0.50 | 0.13 | 0.97 | 0.65
A9 | 0.11 | 1.00 | 0.30 | 0.37
A10 | 0.80 | 0.74 | 0.76 | 0.92

3. Loading file with utilities

    file <- system.file( "extdata", "utilities.txt", package = "mau" )
    lines <- 17
    skip <- 2
    encoding <- 'utf-8'
    functions <- read_utilities( file, lines, skip, encoding )
    # script <- 'utilities.R'
    # write( functions[[ 2 ]], script )
    functions <- functions[[ 1 ]]

The `functions` data.table has the following structure with the piecewise definition of CRAU’s

nom | min | max | a | b | c | fun
--- | --- | --- | --- | --- | --- | ---
External and local relations | 0 | 1 | 0.000 | 1.000 | 0.0000 | external_local_relations
External and local relations | 1 | 10 | 1.000 | 0.000 | 0.0000 | external_local_relations
Project | 1 | 2 | 1.500 | -0.500 | 0.0000 | project
Project | 2 | 3 | 1.500 | -0.500 | 0.0000 | project
Scope of capabilities | 0 | 6 | 1.225 | -1.225 | 0.2824 | scope_capabilities
Scope of capabilities | 6 | 15 | 1.000 | 0.000 | 0.0000 | scope_capabilities
Self implementation | 1 | 2 | 1.500 | -0.500 | 0.0000 | self_implementation
Self implementation | 2 | 3 | 1.500 | -0.500 | 0.0000 | self_implementation

3. Evaluation of utilities over every index

    # Index positions
    columns <- c( 2, 3, 4, 5 )

    # Function names
    functions <- sapply( c( 'Project',
                            'Self implementation',
                            'External and local relations',
                            'Scope of capabilities' ),
                         FUN = stand_string )
    names( functions ) <- NULL

    # Evaluation of utilities
    utilities <- eval_utilities( index, columns, functions )

The `utilities` data.table has the following structure

cod | u1 | u2 | u3 | u4
--- | --- | --- | --- | ---
A1 | 0 | 0 | 0.50 | 0.0000000
A2 | 1 | 0 | 1.00 | 0.0867217
A3 | 1 | 1 | 0.75 | 0.2111724
A4 | 1 | 0 | 0.25 | 0.2310170
A5 | 1 | 0 | 0.10 | 0.2586944
A6 | 0 | 0 | 0.38 | 0.2614194
A7 | 0 | 0 | 0.57 | 0.2310170
A8 | 0 | 0 | 0.97 | 0.2054301
A9 | 0 | 1 | 0.30 | 0.1215376
A10 | 0 | 0 | 0.76 | 0.2802804

4. Construction of the decision tree

    file <- system.file("extdata", "tree.csv", package = "mau" )
    tree.data <- read_tree( file, skip = 0, nrow = 8 )
    tree <- make_decision_tree( tree.data )
    utilities <- eval_utilities( index, columns, functions )

    plot( tree, layout = layout_as_tree )

5. Computing the decision model

    weights <- tree.data[ !is.na( weight ) ]$weight
    model <- compute_model( tree, utilities, weights )

id | name | cod | index | deep | utility | relative.utility | weight | relative.weight
--- | --- | --- | --- | --- | --- | --- | --- | ---
1 | Performance | A1 | NA | 0 | 0.0500000 | 0.0500000 | 1.0 | 1.0000000
1 | Performance | A2 | NA | 0 | 0.3173443 | 0.3173443 | 1.0 | 1.0000000
1 | Performance | A3 | NA | 0 | 0.8172345 | 0.8172345 | 1.0 | 1.0000000
1 | Performance | A4 | NA | 0 | 0.2712034 | 0.2712034 | 1.0 | 1.0000000
1 | Performance | A5 | NA | 0 | 0.2617389 | 0.2617389 | 1.0 | 1.0000000
1 | Performance | A6 | NA | 0 | 0.0902839 | 0.0902839 | 1.0 | 1.0000000
1 | Performance | A7 | NA | 0 | 0.1032034 | 0.1032034 | 1.0 | 1.0000000
1 | Performance | A8 | NA | 0 | 0.1380860 | 0.1380860 | 1.0 | 1.0000000
1 | Performance | A9 | NA | 0 | 0.5543075 | 0.5543075 | 1.0 | 1.0000000
1 | Performance | A10 | NA | 0 | 0.1320561 | 0.1320561 | 1.0 | 1.0000000
2 | Planing | A1 | NA | 1 | 0.0000000 | 0.0000000 | 0.7 | 0.7000000
2 | Planing | A2 | NA | 1 | 0.2000000 | 0.2857143 | 0.7 | 0.7000000
2 | Planing | A3 | NA | 1 | 0.7000000 | 1.0000000 | 0.7 | 0.7000000
2 | Planing | A4 | NA | 1 | 0.2000000 | 0.2857143 | 0.7 | 0.7000000
2 | Planing | A5 | NA | 1 | 0.2000000 | 0.2857143 | 0.7 | 0.7000000
2 | Planing | A6 | NA | 1 | 0.0000000 | 0.0000000 | 0.7 | 0.7000000
2 | Planing | A7 | NA | 1 | 0.0000000 | 0.0000000 | 0.7 | 0.7000000
2 | Planing | A8 | NA | 1 | 0.0000000 | 0.0000000 | 0.7 | 0.7000000
2 | Planing | A9 | NA | 1 | 0.5000000 | 0.7142857 | 0.7 | 0.7000000
2 | Planing | A10 | NA | 1 | 0.0000000 | 0.0000000 | 0.7 | 0.7000000
3 | Capabilities | A1 | NA | 1 | 0.0500000 | 0.1666667 | 0.3 | 0.3000000
3 | Capabilities | A2 | NA | 1 | 0.1173443 | 0.3911478 | 0.3 | 0.3000000
3 | Capabilities | A3 | NA | 1 | 0.1172345 | 0.3907816 | 0.3 | 0.3000000
3 | Capabilities | A4 | NA | 1 | 0.0712034 | 0.2373447 | 0.3 | 0.3000000
3 | Capabilities | A5 | NA | 1 | 0.0617389 | 0.2057963 | 0.3 | 0.3000000
3 | Capabilities | A6 | NA | 1 | 0.0902839 | 0.3009463 | 0.3 | 0.3000000
3 | Capabilities | A7 | NA | 1 | 0.1032034 | 0.3440113 | 0.3 | 0.3000000
3 | Capabilities | A8 | NA | 1 | 0.1380860 | 0.4602868 | 0.3 | 0.3000000
3 | Capabilities | A9 | NA | 1 | 0.0543075 | 0.1810251 | 0.3 | 0.3000000
3 | Capabilities | A10 | NA | 1 | 0.1320561 | 0.4401870 | 0.3 | 0.3000000
4 | Project | A1 | 1 | 2 | 0.0000000 | 0.0000000 | 0.2 | 0.2857143
4 | Project | A2 | 1 | 2 | 0.2000000 | 1.0000000 | 0.2 | 0.2857143
4 | Project | A3 | 1 | 2 | 0.2000000 | 1.0000000 | 0.2 | 0.2857143
4 | Project | A4 | 1 | 2 | 0.2000000 | 1.0000000 | 0.2 | 0.2857143
4 | Project | A5 | 1 | 2 | 0.2000000 | 1.0000000 | 0.2 | 0.2857143
4 | Project | A6 | 1 | 2 | 0.0000000 | 0.0000000 | 0.2 | 0.2857143
4 | Project | A7 | 1 | 2 | 0.0000000 | 0.0000000 | 0.2 | 0.2857143
4 | Project | A8 | 1 | 2 | 0.0000000 | 0.0000000 | 0.2 | 0.2857143
4 | Project | A9 | 1 | 2 | 0.0000000 | 0.0000000 | 0.2 | 0.2857143
4 | Project | A10 | 1 | 2 | 0.0000000 | 0.0000000 | 0.2 | 0.2857143
5 | Self implementation | A1 | 2 | 2 | 0.0000000 | 0.0000000 | 0.5 | 0.7142857
5 | Self implementation | A2 | 2 | 2 | 0.0000000 | 0.0000000 | 0.5 | 0.7142857
5 | Self implementation | A3 | 2 | 2 | 0.5000000 | 1.0000000 | 0.5 | 0.7142857
5 | Self implementation | A4 | 2 | 2 | 0.0000000 | 0.0000000 | 0.5 | 0.7142857
5 | Self implementation | A5 | 2 | 2 | 0.0000000 | 0.0000000 | 0.5 | 0.7142857
5 | Self implementation | A6 | 2 | 2 | 0.0000000 | 0.0000000 | 0.5 | 0.7142857
5 | Self implementation | A7 | 2 | 2 | 0.0000000 | 0.0000000 | 0.5 | 0.7142857
5 | Self implementation | A8 | 2 | 2 | 0.0000000 | 0.0000000 | 0.5 | 0.7142857
5 | Self implementation | A9 | 2 | 2 | 0.5000000 | 1.0000000 | 0.5 | 0.7142857
5 | Self implementation | A10 | 2 | 2 | 0.0000000 | 0.0000000 | 0.5 | 0.7142857
6 | External and local relations | A1 | 3 | 2 | 0.0500000 | 0.5000000 | 0.1 | 0.3333333
6 | External and local relations | A2 | 3 | 2 | 0.1000000 | 1.0000000 | 0.1 | 0.3333333
6 | External and local relations | A3 | 3 | 2 | 0.0750000 | 0.7500000 | 0.1 | 0.3333333
6 | External and local relations | A4 | 3 | 2 | 0.0250000 | 0.2500000 | 0.1 | 0.3333333
6 | External and local relations | A5 | 3 | 2 | 0.0100000 | 0.1000000 | 0.1 | 0.3333333
6 | External and local relations | A6 | 3 | 2 | 0.0380000 | 0.3800000 | 0.1 | 0.3333333
6 | External and local relations | A7 | 3 | 2 | 0.0570000 | 0.5700000 | 0.1 | 0.3333333
6 | External and local relations | A8 | 3 | 2 | 0.0970000 | 0.9700000 | 0.1 | 0.3333333
6 | External and local relations | A9 | 3 | 2 | 0.0300000 | 0.3000000 | 0.1 | 0.3333333
6 | External and local relations | A10 | 3 | 2 | 0.0760000 | 0.7600000 | 0.1 | 0.3333333
7 | Scope of capabilities | A1 | 4 | 2 | 0.0000000 | 0.0000000 | 0.2 | 0.6666667
7 | Scope of capabilities | A2 | 4 | 2 | 0.0173443 | 0.0867217 | 0.2 | 0.6666667
7 | Scope of capabilities | A3 | 4 | 2 | 0.0422345 | 0.2111724 | 0.2 | 0.6666667
7 | Scope of capabilities | A4 | 4 | 2 | 0.0462034 | 0.2310170 | 0.2 | 0.6666667
7 | Scope of capabilities | A5 | 4 | 2 | 0.0517389 | 0.2586944 | 0.2 | 0.6666667
7 | Scope of capabilities | A6 | 4 | 2 | 0.0522839 | 0.2614194 | 0.2 | 0.6666667
7 | Scope of capabilities | A7 | 4 | 2 | 0.0462034 | 0.2310170 | 0.2 | 0.6666667
7 | Scope of capabilities | A8 | 4 | 2 | 0.0410860 | 0.2054301 | 0.2 | 0.6666667
7 | Scope of capabilities | A9 | 4 | 2 | 0.0243075 | 0.1215376 | 0.2 | 0.6666667
7 | Scope of capabilities | A10 | 4 | 2 | 0.0560561 | 0.2802804 | 0.2 | 0.6666667

6. Bar plot for every utility

    xlab <- 'Utility'
    ylab <- 'Institutions'
    title <- 'Criteria utilities'

    colors <- c( 'dodgerblue4', 'orange', 'gold', 'red3' )
    deep <- 2
    bar <- bar_plot( model, deep, colors, title, xlab, ylab )
    plot( bar )

7. Sensitivity analysis under weights change. The weights are simulated employing a Dirichlet distribution.

    n <- 800
    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_sim_weight( S$simulation, title = 'Simulations',
                               xlab = 'ID', ylab = 'Utility' )

    ## Warning: Using `size` aesthetic for lines was deprecated in ggplot2 3.4.0.
    ## ℹ Please use `linewidth` instead.
    ## ℹ The deprecated feature was likely used in the mau package.
    ##   Please report the issue to the authors.
    ## This warning is displayed once every 8 hours.
    ## Call `lifecycle::last_lifecycle_warnings()` to see where this warning was
    ## generated.

    plot( plot.S )