---
title: "Running a MAUT Model"
author: "Pedro Guarderas"
date: "`January 15, 2018"
output: html_vignette
vignette: >
  %\VignetteIndexEntry{Running a MAUT Model}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
## Introduction
The MAUT decision models 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 *Multi Attribute Utility Theory* (MAUT) additionally has a decision tree that 
represents the relations between subsets of utilities, given an ordered and conceptual development
of the decision model.

With **mau** you can build 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 Adverse 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 determine and utility, it is only
necesarry to know the parameter $a,b,c$. Additionally the following convention is assumed, iff 
$c_i$ 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 utilies from an standarized 
text file, with the following internal structure.

**mau** is not only restricted to CRAU class, you can define any utility with the appropiated 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 scructure of the standarized 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 
utilies 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
standarized 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 utilies 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 sensitivy 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 )
```

2. 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 picewise 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 )
```

6. Bar plot for every utility
```{r,eval=TRUE, fig.show='hold', fig.align="center", fig.width=7, fig.height=4}
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. Global utility sensitivity 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.Simulation.Weight( S$simulation, title = 'Simulations', 
                                xlab = 'ID', ylab = 'Utility' ) 

plot( plot.S )
```