---
title: "Running a MAUT Model"
author: "Pedro Guarderas"
date: "October 25, 2023"
output: html_vignette
vignette: >
  %\VignetteIndexEntry{Running a MAUT Model}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
## 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
```{r, eval=TRUE}
library( mau )
file <- system.file( "extdata", "utilities.txt", package = "mau" )
lines <- readLines( file )
for ( i in 1:length( lines ) ) { 
  cat( lines[i], '\n' )
}
```

## 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
```{r,eval=TRUE,message=FALSE, warning=FALSE}
library( mau )
library( data.table )
library( igraph )
library( ggplot2 )
```

2. Index definition
```{r,eval=TRUE}
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 ) )
```
```{r, echo=FALSE, results='asis'}
knitr::kable( index )
```

3. Loading file with utilities
```{r,eval=TRUE}
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 )
source( 'utilities.R' )
```
The `functions` data.table has the following structure with the piecewise definition of CRAU's
```{r, echo=FALSE, results='asis'}
knitr::kable( functions )
```

3. Evaluation of utilities over every index
```{r,eval=TRUE}
# 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
```{r, echo=FALSE, results='asis'}
knitr::kable( utilities )
```

4. Construction of the decision tree
```{r,eval=TRUE, fig.show='hold', fig.align="center", fig.width=7, fig.height=6}
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
```{r,eval=TRUE}
weights <- tree.data[ !is.na( weight ) ]$weight
model <- compute_model( tree, utilities, weights )
```
```{r, echo=FALSE, results='asis'}
knitr::kable( model )
```

6. Bar plot for every utility
```{r,eval=TRUE, fig.show='hold', fig.align="center", fig.width=7, fig.height=5}
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.
```{r,eval=TRUE, fig.show='hold', fig.show='hold', fig.align="center", fig.width=7, fig.height=4}
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' ) 

plot( plot.S )
```