\documentclass{article}

%\VignetteEngine{knitr::knitr}
%\VignetteIndexEntry{Desirability Index}

\usepackage[backend=bibtex,style=alphabetic,citestyle=authoryear]{biblatex}
\bibliography{vignette}

\begin{document}

\author{David Schindler, Diane Uschner, Thi Mui Pham}
\title{Tutorial: Interplay between functions related to desirability indices within 
\texttt{randomizeR}.}
\maketitle


\section{Introduction}
\texttt{randomizeR} is a user-friendly package that allows the user to assess and compare
randomization procedures according to certain criteria (called issues in this package). This tutorial focuses on the comparison of randomization sequences and procedures on the basis of desirability functions. In this context, there are certain criteria and requirements given which have to be met by a randomization procedure. Desirability scores are a kind of linked optimization criteria that establish the connection between the given requirements and thereby allow a comparison between them. 

Currently, \texttt{randomizeR} encompasses the class of desirability functions introduced by Derringer and Suich (1980) and corresponding functions to evaluate and compare randomization sequences which have been assessed on the basis of desirability indices of specific issues. 

For each value $x$ of the corresponding criterion, a desirability function $d$ assigns numbers between 0 and 1 to
the possible values of $x$ with $d(x) = 0$ representing a completely undesirable value and $d(x)=1$ representing a completely desirable or ideal value. Therefore, values with different domains are mapped to a common scale $[0,1]$, making them comparable. 

The Derringer-Suich approach expects a lower and upper specified border and an optimal desired value
called the target value. There are three different kinds of desirability functions: The 
(left-)one-sided Derringer-Suich desirability function, the (right-)one-sided Derringer-Suich 
desirability function and the two-sided Derringer-Suich desirability function. All three
options are supported within the \texttt{randomizeR} package. Whenever an argument $x$ is 
smaller/greater than  a lower/upper specified border it is mapped to zero by the desirability function. If the value of $x$ corresponds (or even exceeds) 
its target value the desirability function $d(x)$ is one. The upper 
specified border is called upper specification limit (USL) and the lower specified border is called lower specification limit (LSL). 


The functions realizing the idea described above are given by
<<eval=F>>=
derFunc
getDesScores
evaluate
probUnDes
plotDes
plotEv
@
In order to use the functions mentioned above, we have to load the \texttt{randomizeR}
package into the library:
<<message=F>>=
library(randomizeR)
@


\section{Working example}
Assume we would like to assess the full set of randomization sequences of sample size 
\texttt{4} generated by the Random Allocation Rule and based on specific issues. 
The behavior of randomization sequences with respect to these issues can be 
evaluated by the \texttt{assess} function:
<<sequences>>=
sequences <- getAllSeq(rarPar(4))
issue1 <- corGuess("CS")
issue2 <- chronBias("linT", 0.25, "exact")
endp <- normEndp(mu = c(0,0), sigma = c(1,1))
A <- assess(sequences, issue1, issue2, endp = endp)
A
@

 However, the assessment output of different issues 
usually have different domains making the comparison difficult. By using desirability 
functions the assessment output is scaled to $[0,1]$. In this package \texttt{derFunc}
represents both the one and two-sided desirability functions according to Derringer and Suich. 
<<derFunctions>>=
d1 <- derFunc(0.5, 0.75, 1)
d1
d2 <- derFunc(0.05, 0.1, 1)
d2
@
The desirability functions defined above are right- and left-sided respectively. 
By applying the \texttt{getDesScores} function to the assessment output together with the specified desirability functions the behavior of randomization sequences is evaluated and scaled to $[0,1]$. By combining the individual desirabilities values of the issues using the geometric mean, the \textit{overall desirability of a given randomization sequence} is computed. 

<<getDesScores1>>=
D1 <- getDesScores(A, d1, d2)
print(D1$D, digits = 3)
@
Notice that regarding the expected proportion of correct guesses and with respect to the
right-sided desirability function \texttt{d1} only two of six sequences are not mapped to zero. Thus, the values of correct guesses of sequences $2-5$ are undesirable. On the other hand, regarding
linear time trend (chronological bias) and with respect to the desirability function \texttt{d2}
the respective sequences are completely desirable as they are all mapped to 1. The last 
column displays the overall desirability. Notice that if the value of any considered issue is completely undesirable, then the corresponding overall desirability is zero. 

The \texttt{getDesScore} function also allows specifying weights in order to adjust the
computation of the overall desirability, i.e. the geometric mean. If, like in the case above, the weights are not specified, then the issues are equally weighted. 
<<>>=
getDesScores(A, d1, d2, weights = c(5/6, 1/6))
@

By applying the \texttt{summary} function to this object it summarizes the results
by means of statistics like mean, median, min, max etc. Therefore, the third column of the \texttt{summary} output represents the \textit{overall desirability of a given randomization procedure}. 
<<summary1>>=
summary(D1)
@
The \texttt{randomizeR} package also offers the option of visualization by plotting an \texttt{desScore} object. Moreover, by specifying the variable \texttt{quantiles}, the user can decide whether the quantiles should be depicted in the plot or not. This allows a visualization of the summarized results (see above). 
<<>>=
plotDes(D1, quantiles = TRUE)
@

Now, suppose we would like to perform a comparison of sequences from different 
randomization procedures. Then this can be done by using the \texttt{evaluate} function.
It expects a number of objects resulting from \texttt{getDesScores} and summarizes their results according to a given statistic. The user can choose between \texttt{mean, median, min} or \texttt{max}. If no statistic is specified then it is set to \texttt{mean}.
<<>>=
issue1 <- corGuess("CS")
issue2 <- chronBias(type = "linT", theta = 1/4, method = "exact")
RAR <- getAllSeq(rarPar(4))
BSD <- getAllSeq(bsdPar(4, mti = 2))
A1 <- assess(RAR, issue1, issue2, endp = normEndp(c(0,0), c(1,1)))
A2 <- assess(BSD, issue1, issue2, endp = normEndp(c(0,0), c(1,1)))

d1 <- derFunc(TV = 0.5, 0.75, 2)
d2 <- derFunc(0.05, c(0, 0.1), c(1, 1))
DesScore <- getDesScores(A1, d1, d2, weights = c(5/6, 1/6))
DesScore2 <- getDesScores(A2, d1, d2, weights = c(5/6, 1/6))

evaluate(DesScore, DesScore2)
@
Looking at the corresponding output of \texttt{getDesScores}, we recognize that the 
desirability functions map a lot of values to zero, i.e. a lot of undesired sequences 
are among the assessed ones:
<<>>=
print(DesScore$D, digits = 3)
print(DesScore2$D, digits = 3)
@
This observation raises the question which randomization procedure produces more undesired randomization sequences with respect to certain issues and desirability functions? 
The function \texttt{probUnDes} computes the probability of having desirability scores of zero for each desirability function applied to an issue:
<<>>=
probUnDes(DesScore)
probUnDes(DesScore2)
@
Thus, the probability of having undesired sequences is more than twice as high for the
Random Allocation Rule than for the Big Stick design. 
A graphical method of displaying the comparison of randomization procedures is given by the \texttt{plotEv} function. It can be applied to an \texttt{evaluation} object which results from the \texttt{evaluate} function. 
<<>>==
plotEv(evaluate(DesScore, DesScore2))
@


\end{document}
