% Created 2018-10-17 on 10:46
% Intended LaTeX compiler: pdflatex
\documentclass[12pt]{article}

%%%% settings when exporting code %%%% 

\usepackage{listings}
\lstset{
backgroundcolor=\color{white},
basewidth={0.5em,0.4em},
basicstyle=\ttfamily\small,
breakatwhitespace=false,
breaklines=true,
columns=fullflexible,
commentstyle=\color[rgb]{0.5,0,0.5},
frame=single,
keepspaces=true,
keywordstyle=\color{black},
literate={~}{$\sim$}{1},
numbers=left,
numbersep=10pt,
numberstyle=\ttfamily\tiny\color{gray},
showspaces=false,
showstringspaces=false,
stepnumber=1,
stringstyle=\color[rgb]{0,.5,0},
tabsize=4,
xleftmargin=.23in,
emph={anova,apply,class,coef,colnames,colNames,colSums,dim,dcast,for,ggplot,head,if,ifelse,is.na,lapply,list.files,library,logLik,melt,plot,require,rowSums,sapply,setcolorder,setkey,str,summary,tapply},
emphstyle=\color{blue}
}

%%%% packages %%%%%

\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
\usepackage{textcomp}
\usepackage{color}
\usepackage{enumerate}
\usepackage{graphicx}
\usepackage{grffile}
\usepackage{wrapfig}
\usepackage{rotating}
\usepackage{longtable}
\usepackage{multirow}
\usepackage{multicol}
\usepackage{changes}
\usepackage{pdflscape}
\usepackage{geometry}
\usepackage[normalem]{ulem}
\usepackage{amssymb}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{dsfont}
\usepackage{textcomp}
\usepackage{array}
\usepackage{ifthen}
\usepackage{hyperref}
\usepackage{natbib}
%\VignetteIndexEntry{overview}
%\VignetteEngine{R.rsp::tex}
%\VignetteKeyword{R}
\RequirePackage{fancyvrb}
\DefineVerbatimEnvironment{verbatim}{Verbatim}{fontsize=\small,formatcom = {\color[rgb]{0.5,0,0}}}
\geometry{a4paper, left=15mm, right=15mm}
\RequirePackage{colortbl} % arrayrulecolor to mix colors
\RequirePackage{setspace} % to modify the space between lines - incompatible with footnote in beamer
\usepackage{authblk} % enable several affiliations (clash with beamer)
\renewcommand{\baselinestretch}{1.1}
\geometry{top=1cm}
\usepackage{enumitem}
\RequirePackage{xspace} %
\newcommand\Rlogo{\textbf{\textsf{R}}\xspace} %
\RequirePackage{epstopdf} % to be able to convert .eps to .pdf image files
\author{Brice Ozenne}
\date{\today}
\title{Overview of the package BuyseTest}
\hypersetup{
 colorlinks=true,
 citecolor=[rgb]{0,0.5,0},
 urlcolor=[rgb]{0,0,0.5},
 linkcolor=[rgb]{0,0,0.5},
 pdfauthor={Brice Ozenne},
 pdftitle={Overview of the package BuyseTest},
 pdfkeywords={},
 pdfsubject={},
 pdfcreator={Emacs 25.2.1 (Org mode 9.0.4)},
 pdflang={English}
 }
\begin{document}

\maketitle
The \textbf{BuyseTest} package contains five functions that are relevant for the user:
\begin{itemize}
\item the \texttt{BuyseTest} function to compute the net benefit/win ratio. It is
the main function of the package.
\item a \texttt{summary} function to display the results computed by the \texttt{BuyseTest} function.
\item a \texttt{confint} function to extract estimates, confidence intervals, and p.values.
\item the \texttt{getPairScore} method to extract the contribution of each pair to the net benefit/win ratio.
\item the \texttt{BuyseTest.options} function the contain the default values for
the argument of the \texttt{BuyseTest} function. These default values can
be changed to better match the user needs.
\end{itemize}

Two additional function are presented in this document: \texttt{simBuyseTest}
that can be used to quickly simulate data and \texttt{getSurvival} that is
useful to reproduce the results output by \texttt{BuyseTest}.

\vfill

Before going further we need to load the \textbf{BuyseTest} package in the R
session:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
library(BuyseTest)
\end{lstlisting}

\bigskip

The \textbf{BuyseTest} package is under active development. Newer package
versions may include additional functionalities and fix previous
bugs. To get the current version of the package use
\texttt{utils::packageVersion}:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
utils::packageVersion("BuyseTest")
\end{lstlisting}

\begin{verbatim}
[1] ‘1.6’
\end{verbatim}

\vfill


\clearpage

\section{Example data}
\label{sec:org42e6a9e}
For this overview we will used the \texttt{veteran} dataset from the
\textbf{survival} package:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
data(veteran,package="survival")
head(veteran)
\end{lstlisting}

\begin{verbatim}
  trt celltype time status karno diagtime age prior
1   1 squamous   72      1    60        7  69     0
2   1 squamous  411      1    70        5  64    10
3   1 squamous  228      1    60        3  38     0
4   1 squamous  126      1    60        9  63    10
5   1 squamous  118      1    70       11  65    10
6   1 squamous   10      1    20        5  49     0
\end{verbatim}

See \texttt{?veteran} for a presentation of the database.

\clearpage

\section{Performing generalized pairwise comparisons (GPC) using the \texttt{BuyseTest} function}
\label{sec:orgaa4998b}

To perform generalized pairwise comparisons, the \texttt{BuyseTest} function needs:
\begin{itemize}
\item an where the data are stored \hfill - argument \texttt{data}
\item the name of the endpoints \hfill - argument \texttt{endpoint}
\item the type of each endpoint \hfill - argument \texttt{type}
\item the variable defining the two treatment groups \hfill - argument
\texttt{treatment}
\end{itemize}
The \texttt{BuyseTest} function has many optional arguments to specify for example:
\begin{itemize}
\item the threshold associated to each endpoint (default\(=10^{-12}\))  \hfill - argument \texttt{threshold}
\item the censoring associated to each endpoint (for time to event endpoint) \hfill - argument \texttt{censoring}
\item how to compute the distribution of the statistic of interest \hfill - argument \texttt{method.inference}
\end{itemize}

\bigskip

There are two equivalent ways to define the GPC: 
\begin{itemize}
\item using a separate argument for each element\footnote{we set the argument \texttt{method.inference} to "none" to diseable
the computation of p-values and confidence intervals. This makes the
execution of \texttt{BuyseTest} much faster.}:
\end{itemize}


\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
BT <- BuyseTest(data = veteran, 
				endpoint = "time", 
				type = "timeToEvent", 
				treatment = "trt", 
				censoring = "status", 
				threshold = 20,
				method.inference = "none")
\end{lstlisting}

\begin{verbatim}
         Generalized Pairwise Comparisons

Settings 
   - treatment groups: Control = 1 and Treatment = 2
   - 1 endpoint: 
       priority endpoint type           operator             threshold censoring
       1        time     time to event  higher is favorable  20        status   
   - management of neutral pairs: re-analyzed using endpoints of lower priority (if any) 
   - management of censored survival pairs: use Kaplan Meier survival curves to compute the score 

Point estimation

Gather the results in a BuyseRes object
\end{verbatim}

\clearpage

\begin{itemize}
\item or via a formula interface. In the formula interface endpoint are
wrapped by parentheses. The parentheses must be preceded by their
type: 
\begin{itemize}[label={-}]
\item binary (\texttt{b}, \texttt{bin}, or \texttt{binary})
\item continuous (\texttt{c}, \texttt{cont}, or  \texttt{continuous})
\item time to event (\texttt{t}, \texttt{tte}, or \texttt{timetoevent})
\end{itemize}
\end{itemize}

\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
BT.f <- BuyseTest(trt ~ tte(time, threshold = 20, censoring = "status"),
				  data = veteran, trace = 0, method.inference = "none")
\end{lstlisting}

Here we set in addition the argument \texttt{trace} to 0 to force the
function to be silent (i.e. no display in the terminal). We can check
that the two approaches are equivalent:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
testthat::expect_equal(BT.f,BT)
\end{lstlisting}

\subsection{Displaying the results}
\label{sec:orgaa69fca}

The results of the GPC can be displayed using the \texttt{summary} method:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
summary(BT)
\end{lstlisting}

\begin{verbatim}
       Generalized pairwise comparison with 1 prioritized endpoint

> statistic       : net benefit (delta: endpoint specific, Delta: global) 
> null hypothesis : Delta == 0 
> treatment groups: 1 (control) vs. 2 (treatment) 
> censored pairs  : use Kaplan Meier survival curves to compute the score
> results
endpoint threshold total favorable unfavorable neutral uninf   delta   Delta
    time        20   100     37.78       46.54   15.68     0 -0.0877 -0.0877
\end{verbatim}

 To display the number of pairs instead of the percentage of pairs
that are favorable/unfavorable/neutral/uniformative, set the argument
\texttt{percentage} to \texttt{FALSE}:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
summary(BT, percentage = FALSE)
\end{lstlisting}

\begin{verbatim}
       Generalized pairwise comparison with 1 prioritized endpoint

> statistic       : net benefit (delta: endpoint specific, Delta: global) 
> null hypothesis : Delta == 0 
> treatment groups: 1 (control) vs. 2 (treatment) 
> censored pairs  : use Kaplan Meier survival curves to compute the score
> results
endpoint threshold total favorable unfavorable neutral uninf   delta   Delta
    time        20  4692   1772.59     2183.89  735.52     0 -0.0877 -0.0877
\end{verbatim}

By default \texttt{summary} displays results relative to the net benefit. To
get results for the win ratio set the argument \texttt{statistic} to
"winRatio":
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
summary(BT, statistic = "winRatio")
\end{lstlisting}

\begin{verbatim}
       Generalized pairwise comparison with 1 prioritized endpoint

> statistic       : win ratio (delta: endpoint specific, Delta: global) 
> null hypothesis : Delta == 1 
> treatment groups: 1 (control) vs. 2 (treatment) 
> censored pairs  : use Kaplan Meier survival curves to compute the score
> results
endpoint threshold total favorable unfavorable neutral uninf  delta  Delta
    time        20   100     37.78       46.54   15.68     0 0.8117 0.8117
\end{verbatim}

Since we have set the argument \texttt{n.permutation} to 0 (i.e. no
permutation test) in the stratified analysis, we do not get confidence
intervals or p.values when calling the \texttt{summary} method.

\subsection{Using multiple endpoints}
\label{sec:orgd48c4a5}
More than one endpoint can be considered by indicating a vector of
endpoints, types, and thresholds. In the formula interface, just add
another endpoint at then end of the formula:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
BT.multi <- BuyseTest(trt ~ tte(time, threshold = 20, censoring = "status",) + cont(karno, threshold = 0),
					  data = veteran, method.inference = "none", trace = 0)
\end{lstlisting}

The hierarchy of the endpoint is defined from left (most important
endpoint, here \texttt{time}) to right (least important endpoint, here
\texttt{karno}).

\subsection{What if smaller is better?}
\label{sec:orge398c9f}
By default \texttt{BuyseTest} will always assume that higher values of an
endpoint are favorable. This behavior can be changed by specifying \texttt{operator = "<0"}
for an endpoint:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
BTinv <- BuyseTest(trt ~ tte(time, threshold = 20, censoring = "status", operator = "<0"),
				   data = veteran, method.inference = "none", trace = 0)
BTinv
\end{lstlisting}

\begin{verbatim}
endpoint threshold  delta  Delta
    time        20 0.0844 0.0844
\end{verbatim}

Internally \texttt{BuyseTest} will multiply by -1 the values of the endpoint
to ensure that lower values are considered as favorable. A direct
consequence is that \texttt{BuyseTest} will not accept an endpoint with
different operators:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
try(BuyseTest(trt ~ tte(time, threshold = 20, censoring = "status", operator = "<0") + tte(time, 10, "status", ">0"),
			  data = veteran, method.inference = "none", trace = 0))
\end{lstlisting}

\begin{verbatim}
Error in (function (alternative, name.call, censoring, correction.uninf,  : 
  Cannot have different operator for the same endpoint used at different priorities
\end{verbatim}


\subsection{Stratified GPC}
\label{sec:orgc34dfb9}

GPC can be performed for subgroups of a categorical variable \hfill -
argument \texttt{strata}

\bigskip

 For instance, the celltype may have huge influence on the survival
time and the investigator would like to only compare patients that
have the same celltype. In the formula interface this is achieved by
adding a single variable in the right hand side of the formula:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
BT2 <- BuyseTest(trt ~ tte(time, threshold = 20, censoring = "status") + cont(karno, threshold = 0) + celltype,
				 data = veteran, trace = 0, method.inference = "none")
\end{lstlisting}

The fact the it is not wrapped by \texttt{bin}, \texttt{cont} or \texttt{tte} indicates
differentiate it from endpoint variables. When doing a stratified
analysis, the summary method displays the global results as well as
the results within each strata:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
summary(BT2)
\end{lstlisting}

\begin{verbatim}
       Generalized pairwise comparison with 2 prioritized endpoints and 4 strata

> statistic       : net benefit (delta: endpoint specific, Delta: global) 
> null hypothesis : Delta == 0 
> treatment groups: 1 (control) vs. 2 (treatment) 
> censored pairs  : use Kaplan Meier survival curves to compute the score
> results
endpoint threshold    strata  total favorable unfavorable neutral uninf   delta   Delta
    time        20    global 100.00     36.06       45.77   17.50  0.68 -0.0971 -0.0971
                    squamous  25.38     14.33        8.77    2.28  0.00  0.2193        
                   smallcell  45.69     12.69       20.88   11.44  0.68 -0.1792        
                       adeno  13.71      4.74        6.15    2.81  0.00 -0.1034        
                       large  15.23      4.30        9.97    0.96  0.00 -0.3722        
   karno     1e-12    global  18.17      6.72        8.07    3.38  0.00 -0.0135 -0.1106
                    squamous   2.28      0.76        0.94    0.59  0.00 -0.0071        
                   smallcell  12.12      4.33        5.75    2.03  0.00 -0.0311        
                       adeno   2.81      1.46        0.85    0.51  0.00  0.0448        
                       large   0.96      0.17        0.54    0.25  0.00 -0.0241
\end{verbatim}

Note that here the numbers in the
favorable/unfavorable/neutral/uniformative columns are relative to the
overall sample while the delta is only relative to the strata. The
global delta is a sum of the strata specific delta weighted by the
empirical proportion of pairs for each strata.

\clearpage

\subsection{Stopping comparison for neutral pairs}
\label{sec:orgb8c5a6a}
In presence of neutral pairs, \texttt{BuyseTest} will, by default, continue
the comparison on the endpoints with lower priority. For instance let
consider a dataset with one observation in each treatment arm:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
dt.sim <- data.table(Id = 1:2,
					 treatment = c("Yes","No"),
					 tumor = c("Yes","Yes"),
					 size = c(15,20))
dt.sim
\end{lstlisting}

\begin{verbatim}
   Id treatment tumor size
1:  1       Yes   Yes   15
2:  2        No   Yes   20
\end{verbatim}

If we perform we GPC with tumor as the first endpoint and size as the
second endpoint:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
BT.pair <- BuyseTest(treatment ~ bin(tumor) + cont(size, operator = "<0"), data = dt.sim,
					 trace = 0, method.inference = "none")
summary(BT.pair)
\end{lstlisting}

\begin{verbatim}
Warning message:
In `[.data.table`(data, , `:=`(c("..rowIndex.."), 1:.N)) :
  Invalid .internal.selfref detected and fixed by taking a (shallow) copy of the data.table so that := can add this new column by reference. At an earlier point, this data.table has been copied by R (or was created manually using structure() or similar). Avoid key<-, names<- and attr<- which in R currently (and oddly) may copy the whole data.table. Use set* syntax instead to avoid copying: ?set, ?setnames and ?setattr. If this message doesn't help, please report your use case to the data.table issue tracker so the root cause can be fixed or this message improved.
        Generalized pairwise comparison with 2 prioritized endpoints

 > statistic       : net benefit (delta: endpoint specific, Delta: global) 
 > null hypothesis : Delta == 0 
 > treatment groups: No (control) vs. Yes (treatment) 
 > results
 endpoint threshold total favorable unfavorable neutral uninf delta Delta
    tumor       0.5   100         0           0     100     0     0     0
     size     1e-12   100       100           0       0     0     1     1
\end{verbatim}

the outcome of the comparison is neutral for the first priority, but
favorable for the second priority. If we set the argument
\texttt{neutral.as.uninf} to \texttt{FALSE}, \texttt{BuyseTest} will stop the comparison
when a pair is classified as neutral:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
BT.pair2 <- BuyseTest(treatment ~ bin(tumor) + cont(size, operator = "<0"), data = dt.sim,
					 trace = 0, method.inference = "none", neutral.as.uninf = FALSE)
summary(BT.pair2)
\end{lstlisting}

\begin{verbatim}
Warning message:
In `[.data.table`(data, , `:=`(c("..rowIndex.."), 1:.N)) :
  Invalid .internal.selfref detected and fixed by taking a (shallow) copy of the data.table so that := can add this new column by reference. At an earlier point, this data.table has been copied by R (or was created manually using structure() or similar). Avoid key<-, names<- and attr<- which in R currently (and oddly) may copy the whole data.table. Use set* syntax instead to avoid copying: ?set, ?setnames and ?setattr. If this message doesn't help, please report your use case to the data.table issue tracker so the root cause can be fixed or this message improved.
        Generalized pairwise comparison with 2 prioritized endpoints

 > statistic       : net benefit (delta: endpoint specific, Delta: global) 
 > null hypothesis : Delta == 0 
 > treatment groups: No (control) vs. Yes (treatment) 
 > results
 endpoint threshold total favorable unfavorable neutral uninf delta Delta
    tumor       0.5   100         0           0     100     0     0     0
     size     1e-12     0         0           0       0     0     0     0
\end{verbatim}

So in this case no pair is analyzed at second priority.

\subsection{What about p-value and confidence intervals?}
\label{sec:org63a96dc}

P-values can be estimated via a permutation test:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
BT.perm <- BuyseTest(trt ~ tte(time, threshold = 20, censoring = "status"),
					 data = veteran, trace = 0, method.inference = "permutation",
					 n.resampling = 10) 
summary(BT.perm)
\end{lstlisting}

\begin{verbatim}
        Generalized pairwise comparison with 1 prioritized endpoint

 > statistic       : net benefit (delta: endpoint specific, Delta: global) 
 > null hypothesis : Delta == 0 
 > permutation test: 10 samples, confidence level 0.95 
 > treatment groups: 1 (control) vs. 2 (treatment) 
 > censored pairs  : use Kaplan Meier survival curves to compute the score
 > results
 endpoint threshold total favorable unfavorable neutral uninf   delta   Delta
     time        20   100     37.78       46.54   15.68     0 -0.0877 -0.0877
  CI [2.5 ; 97.5] p.value 
 [-0.2412;0.1946]     0.4 
NOTE: confidence intervals computed under the null hypothesis
\end{verbatim}

The argument \texttt{n.resampling} indicates the permutation that will be
performed. We set it to 10 to save computation time but to obtain
reliable p-value/confidence intervals, \texttt{n.resampling} should be at
least 1000. The validity of the confidence intervals obtained via a
permutation test is questionable and we recommend instead to use a
bootstrap approach for estimating confidence intervals. To do so, set
the argument \texttt{method.inference} to \texttt{"bootstrap"} when calling
\texttt{BuyseTest}:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
BT.boot <- BuyseTest(trt ~ tte(time, threshold = 20, censoring = "status"),
					 data = veteran, trace = 0, method.inference = "bootstrap",
					 n.resampling = 10) 
summary(BT.boot)
\end{lstlisting}

\begin{verbatim}
       Generalized pairwise comparison with 1 prioritized endpoint

> statistic       : net benefit (delta: endpoint specific, Delta: global) 
> null hypothesis : Delta == 0 
> bootstrap resampling: 10 samples, confidence level 0.95 
> treatment groups: 1 (control) vs. 2 (treatment) 
> censored pairs  : use Kaplan Meier survival curves to compute the score
> results
endpoint threshold total favorable unfavorable neutral uninf   delta   Delta
    time        20   100     37.78       46.54   15.68     0 -0.0877 -0.0877
 CI [2.5 ; 97.5] p.value 
[-0.1794;0.0302]     0.5
\end{verbatim}


\clearpage

\section{Getting additional inside: looking at the pair level}
\label{sec:org9a21195}

So far we have looked at the overall score and probabilities. But it
is also possible to extract the score relative to each pair, as well
as to "manually" compute this score. This can give further inside on
what the software is actually doing and what is the contribution of
each individual on the evaluation of the treatment.

\subsection{Extracting the contribution of each pair to the statistic}
\label{sec:org97033f8}
The net benefit or the win ratio statistics can be expressed as a sum
of a score over all pairs of patients. The argument \texttt{keep.pairScore}
enables to export the score relative to each pair in the output of
BuyseTest:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
form <- trt ~ tte(time, threshold = 20, censoring = "status") + cont(karno)
BT.keep <- BuyseTest(form,
					 data = veteran, keep.pairScore = TRUE, 
					 trace = 0, method.inference = "none")
\end{lstlisting}

The method \texttt{getPairScore} can then be used to extract the contribution
of each pair. For instance the following code extracts the
contribution for the first endpoint:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
getPairScore(BT.keep, endpoint = 1)
\end{lstlisting}

\begin{verbatim}
      strata index.1 index.2 favorable unfavorable neutral uninf weight favorableC
   1:      1       1      70         1           0       0     0      1          1
   2:      1       2      70         1           0       0     0      1          1
   3:      1       3      70         1           0       0     0      1          1
   4:      1       4      70         1           0       0     0      1          1
   5:      1       5      70         1           0       0     0      1          1
  ---                                                                             
4688:      1      65     137         0           1       0     0      1          0
4689:      1      66     137         0           1       0     0      1          0
4690:      1      67     137         0           1       0     0      1          0
4691:      1      68     137         0           1       0     0      1          0
4692:      1      69     137         0           1       0     0      1          0
      unfavorableC neutralC uninfC
   1:            0        0      0
   2:            0        0      0
   3:            0        0      0
   4:            0        0      0
   5:            0        0      0
  ---                             
4688:            1        0      0
4689:            1        0      0
4690:            1        0      0
4691:            1        0      0
4692:            1        0      0
\end{verbatim}

Each line corresponds to different comparison between a pair from the
control arm and the treatment arm. The column \texttt{strata} store to which
strata the pair belongs (first, second, \ldots{}). The columns favorable,
unfavorable, neutral, uninformative contains the result of the
comparison, e.g. the first pair was classified as favorable while the
last was classified as favorable with a weight of 1. The second and
third columns indicates the rows in the original dataset corresponding
to the pair:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
veteran[c(70,1),]
\end{lstlisting}

\begin{verbatim}
   trt celltype time status karno diagtime age prior
70   2 squamous  999      1    90       12  54    10
1    1 squamous   72      1    60        7  69     0
\end{verbatim}


For the first pair, the event was observed for both observations and
since 999 > 72 + 20 the pair is rated favorable. Substracting the
average probability of the pair being favorable minus the average
probability of the pair being unfavorable:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
getPairScore(BT.keep, endpoint = 1)[, mean(favorable) - mean(unfavorable)]
\end{lstlisting}

\begin{verbatim}
[1] -0.08765836
\end{verbatim}

gives the net benefit in favor of the treatment for the first
endpoint:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
BT.keep
\end{lstlisting}

\begin{verbatim}
endpoint threshold   delta   Delta
    time        20 -0.0877 -0.0877
   karno     1e-12 -0.0133 -0.1009
\end{verbatim}

More examples and explanation can be found in the documentation of
the method \texttt{getPairScore}.

\subsection{Extracting the survival probabilities}
\label{sec:org4eb5c87}
When using \texttt{method.tte} equals \texttt{"Peron"}, survival probabilities at
event time, and event times +/- threshold in the control and treatment
arms are used to score the pair. Setting \texttt{keep.survival} to \texttt{TRUE} in
BuyseTest.options enables to export the survival probabilities in the
output of BuyseTest:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
BuyseTest.options(keep.survival = TRUE)
BT.keep2 <- BuyseTest(trt ~ tte(time, threshold = 20, censoring = "status") + cont(karno),
					  data = veteran, keep.pairScore = TRUE, method.tte = "Peron",
					  trace = 0, method.inference = "none")
\end{lstlisting}

The method \texttt{getSurvival} can then be used to extract these survival
probabilities. For instance the following code extracts the survival
for the first endpoint:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
outSurv <- getSurvival(BT.keep2, endpoint = 1, strata = 1)
str(outSurv)
\end{lstlisting}

\begin{verbatim}
List of 5
 $ survTimeC: num [1:69, 1:7] 72 411 228 126 118 10 82 110 314 100 ...
  ..- attr(*, "dimnames")=List of 2
  .. ..$ : NULL
  .. ..$ : chr [1:7] "time" "SurvivalC-threshold" "SurvivalC_0" "SurvivalC+threshold" ...
 $ survTimeT: num [1:68, 1:7] 999 112 87 231 242 991 111 1 587 389 ...
  ..- attr(*, "dimnames")=List of 2
  .. ..$ : NULL
  .. ..$ : chr [1:7] "time" "SurvivalC-threshold" "SurvivalC_0" "SurvivalC+threshold" ...
 $ survJumpC: num [1:57, 1:3] 3 4 7 8 10 11 12 13 16 18 ...
  ..- attr(*, "dimnames")=List of 2
  .. ..$ : NULL
  .. ..$ : chr [1:3] "time" "survival" "dSurvival"
 $ survJumpT: num [1:51, 1:3] 1 2 7 8 13 15 18 19 20 21 ...
  ..- attr(*, "dimnames")=List of 2
  .. ..$ : NULL
  .. ..$ : chr [1:3] "time" "survival" "dSurvival"
 $ lastSurv : num [1:2] 0 0
\end{verbatim}

\subsubsection{Computation of the score with only one censored event}
\label{sec:orgf2fcbe8}

Let's look at pair 91:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
getPairScore(BT.keep2, endpoint = 1, rm.withinStrata = FALSE)[91]
\end{lstlisting}

\begin{verbatim}
   strata index.1 index.2 indexWithinStrata.1 indexWithinStrata.2 favorable unfavorable
1:      1      22      71                  22                   2         0   0.6950827
     neutral uninf weight favorableC unfavorableC  neutralC uninfC
1: 0.3049173     0      1          0    0.6950827 0.3049173      0
\end{verbatim}

In the dataset this corresponds to:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
veteran[c(22,71),]
\end{lstlisting}

\begin{verbatim}
   trt  celltype time status karno diagtime age prior
22   1 smallcell   97      0    60        5  67     0
71   2  squamous  112      1    80        6  60     0
\end{verbatim}

The observation from the control group is censored at 97 while the
observation from the treatment group has an event at 112. Since the
threshold is 20, and (112-20)<97, we know that the pair is not in
favor of the treatment. The formula for probability in favor of the
control is \(\frac{S_c(97)}{S_c(112+20)}\). The survival at the event
time in the censoring group is stored in survTimeC. Since observation
22 is the 22th observation in the control group:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
iSurv <- outSurv$survTimeC[22,] 
iSurv
\end{lstlisting}

\begin{verbatim}
               time SurvivalC-threshold         SurvivalC_0 SurvivalC+threshold 
         97.0000000           0.5615232           0.5171924           0.4235463 
SurvivalT-threshold         SurvivalT_0 SurvivalT+threshold 
          0.4558824           0.3643277           0.2827500
\end{verbatim}

Since we are interested in the survival in the control arm exactly at the event time:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
Sc97 <- iSurv["SurvivalC_0"] 
Sc97
\end{lstlisting}

\begin{verbatim}
SurvivalC_0 
  0.5171924
\end{verbatim}

The survival at the event time in the treatment group is stored in
survTimeC. Since observation 71 is the 2nd observation in the treatment
group:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
iSurv <- outSurv$survTimeT[2,] ## survival at time 112+20
iSurv
\end{lstlisting}

\begin{verbatim}
               time SurvivalC-threshold         SurvivalC_0 SurvivalC+threshold 
        112.0000000           0.5319693           0.4549201           0.3594915 
SurvivalT-threshold         SurvivalT_0 SurvivalT+threshold 
          0.3801681           0.2827500           0.2827500
\end{verbatim}

Since we are interested in the survival in the control arm at the event time plus threshold:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
Sc132 <- iSurv["SurvivalC+threshold"] 
Sc132
\end{lstlisting}

\begin{verbatim}
SurvivalC+threshold 
          0.3594915
\end{verbatim}

The probability in favor of the control is then:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
Sc132/Sc97
\end{lstlisting}

\begin{verbatim}
SurvivalC+threshold 
          0.6950827
\end{verbatim}

\subsubsection{Computation of the score with two censored events}
\label{sec:org7778859}

When both observations are censored, the formula for computing the
probability in favor of treatment or control involves an
integral. This integral can be computed using the function
\texttt{calcIntegralScore\textbackslash{}\_cpp} that takes as argument a matrix containing the
survival and the jumps in survival, e.g.:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
head(outSurv$survJumpT)
\end{lstlisting}

\begin{verbatim}
     time  survival   dSurvival
[1,]    1 0.7681159 -0.02941176
[2,]    2 0.7536232 -0.01470588
[3,]    7 0.7388463 -0.02941176
[4,]    8 0.7388463 -0.02941176
[5,]   13 0.7092924 -0.01470588
[6,]   15 0.6945155 -0.02941176
\end{verbatim}

and the starting time of the integration time. For instance, let's
look at pair 148:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
getPairScore(BT.keep2, endpoint = 1, rm.withinStrata = FALSE)[148]
\end{lstlisting}

\begin{verbatim}
   strata index.1 index.2 indexWithinStrata.1 indexWithinStrata.2 favorable unfavorable
1:      1      10      72                  10                   3 0.5058685   0.3770426
     neutral uninf weight favorableC unfavorableC  neutralC uninfC
1: 0.1170889     0      1  0.5058685    0.3770426 0.1170889      0
\end{verbatim}

which corresponds to the observations:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
veteran[c(10,72),]
\end{lstlisting}

\begin{verbatim}
   trt celltype time status karno diagtime age prior
10   1 squamous  100      0    70        6  70     0
72   2 squamous   87      0    80        3  48     0
\end{verbatim}

The probability in favor of the treatment (\(p_F\)) and control (\(p_{UF}\)) can be computed
as:
\begin{align*}
p_F &= -\frac{1}{S_T(x)S_C(y)}\int_{t>y} S_T(t+\tau) dS_C(t) \\
p_{UF} &= -\frac{1}{S_T(x)S_C(y)}\int_{t>x} S_C(t+\tau) dS_T(t)
\end{align*}
where \(x=87\) and \(y=100\). We obtain:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
denom <- as.double(outSurv$survTimeT[3,"SurvivalT_0"] * outSurv$survTimeC[10,"SurvivalC_0"])
c("favorable" = -calcIntegralScore_cpp(outSurv$survJumpC, start = 100)/denom,
  "unfavorable" = -calcIntegralScore_cpp(outSurv$survJumpT, start = 87)/denom)
\end{lstlisting}

\begin{verbatim}
favorable unfavorable 
0.5058685   0.3770426
\end{verbatim}

\clearpage

\section{Dealing with missing values or/and right censoring}
\label{sec:orgaef6b4e}

In presence of censoring or missing values, some pairs may be
classified as uninformative. This may bias the estimate of the net net
benefit. Two corrections are currently proposed to correct this bias.

\bigskip

To illustrate the effect of these correction, we will use the
following dataset:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
set.seed(10)
dt <- simBuyseTest(5e2, latent = TRUE, argsCont = NULL,
				   argsTTE = list(rates.T = 2, rates.C = 1, rates.Censoring = 3))
dt[, status1 := 1]
head(dt)
\end{lstlisting}

\begin{verbatim}
   Treatment toxicity eventtimeUncensored eventtimeCensoring eventtime status status1
1:         C        0           0.1588268          2.6268101 0.1588268      1       1
2:         C        1           1.7204676          0.2000192 0.2000192      0       1
3:         C        1           0.4900490          0.5747995 0.4900490      1       1
4:         C        0           0.1138545          1.5188001 0.1138545      1       1
5:         C        1           0.5191035          3.8340048 0.5191035      1       1
6:         C        0           0.9405830          1.9078657 0.9405830      1       1
\end{verbatim}

where we have the uncensored event times as well as the censored event
times. The percentage of censored observations is:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
dt[,mean(status==0)]
\end{lstlisting}

\begin{verbatim}
[1] 0.317
\end{verbatim}

We would like to be able to recover the net benefit estimated with the uncensored event times:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
BuyseTest(Treatment ~ tte(eventtimeUncensored, status1, threshold = 1),
		  data = dt,
		  method.tte = "Gehan", method.inference = "none", trace = 0)
\end{lstlisting}

\begin{verbatim}
           endpoint threshold  delta  Delta
eventtimeUncensored         1 0.2401 0.2401
\end{verbatim}

using the censored survival times:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
BuyseTest(Treatment ~ tte(eventtime, status, threshold = 1),
		  data = dt,
		  method.tte = "Gehan", method.inference = "none", trace = 0)
\end{lstlisting}

\begin{verbatim}
 endpoint threshold  delta  Delta
eventtime         1 0.1363 0.1363
\end{verbatim}

As we can see on this example, the net benefit is shrunk toward 0.

\subsubsection{Inverse probability-of-censoring weights (IPCW)}
\label{sec:org5207020}

With IPCW the weights of the non-informative pairs is redistributed to
the informative pairs. This is only a good strategy when there are no
neutral pairs or there are no lower priority endpoints. This gives an
estimate much closer to the true net benefit:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
BT <- BuyseTest(Treatment ~ tte(eventtime, status, threshold = 1),
				data = dt, keep.pairScore = TRUE, trace = 0,
				method.tte = "Gehan", method.inference = "none", correction.uninf = 2)
summary(BT)
\end{lstlisting}

\begin{verbatim}
       Generalized pairwise comparison with 1 prioritized endpoint

> statistic       : net benefit (delta: endpoint specific, Delta: global) 
> null hypothesis : Delta == 0 
> treatment groups: C (control) vs. T (treatment) 
> censored pairs  : uninformative pairs
> uninformative pairs: no contribution, their weight is passed to the informative pairs using IPCW
> results
 endpoint threshold total favorable unfavorable neutral uninf  delta  Delta
eventtime         1   100     37.11       12.34   50.54     0 0.2477 0.2477
\end{verbatim}


We can also see that no pair is finally classified as non
informative. To get some inside about the correction we can look at
the scores of the pairs:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
iScore <- getPairScore(BT, endpoint = 1)
\end{lstlisting}

To get a synthetic view, we only look at the unique
favorable/unfavorable/neutral/uniformative results:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
iScore[,.SD[1], 
	   .SDcols = c("favorableC","unfavorableC","neutralC","uninfC"),
	   by = c("favorable","unfavorable","neutral","uninf")]
\end{lstlisting}

\begin{verbatim}
   favorable unfavorable neutral uninf favorableC unfavorableC neutralC uninfC
1:         0           0       1     0    0.00000      0.00000  1.81657      0
2:         0           0       0     1    0.00000      0.00000  0.00000      0
3:         0           1       0     0    0.00000      1.81657  0.00000      0
4:         1           0       0     0    1.81657      0.00000  0.00000      0
\end{verbatim}

We can see that the favorable/unfavorable/neutral pairs have seen
their contribution multiplied by:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
iScore[,1/mean(favorable + unfavorable + neutral)]
\end{lstlisting}

\begin{verbatim}
[1] 1.81657
\end{verbatim}

i.e. the inverse probability of being informative. 

\subsubsection{Correction at the pair level}
\label{sec:org709160f}

Another possible correction is to distribute the non-informative
weight of a pair to the average favorable/unfavorable/neutral
probability observed on the sample:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
BT <- BuyseTest(Treatment ~ tte(eventtime, status, threshold = 1),
				data = dt, keep.pairScore = TRUE, trace = 0,
				method.tte = "Gehan", method.inference = "none", correction.uninf = TRUE)
summary(BT)
\end{lstlisting}

\begin{verbatim}
       Generalized pairwise comparison with 1 prioritized endpoint

> statistic       : net benefit (delta: endpoint specific, Delta: global) 
> null hypothesis : Delta == 0 
> treatment groups: C (control) vs. T (treatment) 
> censored pairs  : uninformative pairs
> uninformative pairs: score equals the averaged score of all informative pairs
> results
 endpoint threshold total favorable unfavorable neutral uninf  delta  Delta
eventtime         1   100     37.11       12.34   50.54     0 0.2477 0.2477
\end{verbatim}


Looking at the scores of the pairs:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
iScore <- getPairScore(BT, endpoint = 1)
iScore[,.SD[1], 
	   .SDcols = c("favorableC","unfavorableC","neutralC","uninfC"),
	   by = c("favorable","unfavorable","neutral","uninf")]
\end{lstlisting}

\begin{verbatim}
   favorable unfavorable neutral uninf favorableC unfavorableC  neutralC uninfC
1:         0           0       1     0   0.000000    0.0000000 1.0000000      0
2:         0           0       0     1   0.371118    0.1234396 0.5054424      0
3:         0           1       0     0   0.000000    1.0000000 0.0000000      0
4:         1           0       0     0   1.000000    0.0000000 0.0000000      0
\end{verbatim}

we can see that the corrected probability have not changed for the
informative pairs, but for the non-informative they have been set to:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
iScore[, .(favorable = weighted.mean(favorable, w = 1-uninf), 
		   unfavorable = weighted.mean(unfavorable, w = 1-uninf), 
		   neutral = weighted.mean(neutral, w = 1-uninf))]
\end{lstlisting}

\begin{verbatim}
   favorable unfavorable   neutral
1:  0.371118   0.1234396 0.5054424
\end{verbatim}

\clearpage
\section{Simulating data using \texttt{simBuyseTest}}
\label{sec:org584bc6d}
You can simulate data with the \texttt{simBuyseTest} function. For instance
the following code simulates data for 5 individuals in the treatment
arm and 5 individuals in the control arm:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
set.seed(10)
simBuyseTest(n.T = 5, n.C = 5)
\end{lstlisting}

\begin{verbatim}
    Treatment toxicity       score eventtime status
 1:         C        1  0.54361539 1.8252132      0
 2:         C        1 -0.70762484 2.9489056      1
 3:         C        1 -0.36944577 0.7213402      0
 4:         C        1 -1.32197565 0.6322603      1
 5:         C        1  1.28059746 0.2212117      0
 6:         T        1  0.01874617 0.1453481      0
 7:         T        1 -0.18425254 0.4855601      0
 8:         T        0 -1.37133055 0.2547505      0
 9:         T        1 -0.59916772 1.0340368      0
10:         T        0  0.29454513 0.3579324      1
\end{verbatim}

By default a categorical, continuous and time to event outcome are
generated independently. You can modify their distribution via the
arguments \texttt{argsBin}, \texttt{argsCont}, \texttt{argsTTE}. For instance the following
code simulates two continuous variables with mean 5 in the treatment
arm and 10 in the control arm all with variance 1:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
set.seed(10)
argsCont <- list(mu.T = c(5,5), mu.C = c(10,10), 
				 sigma.T = c(1,1), sigma.C = c(1,1),
				 name = c("tumorSize","score"))
dt <- simBuyseTest(n.T = 5, n.C = 5,
				   argsCont = argsCont)
dt
\end{lstlisting}

\begin{verbatim}
    Treatment toxicity tumorSize     score eventtime status
 1:         C        1  9.010394 10.667415 0.2729620      0
 2:         C        0  9.965152 11.691755 0.5562477      0
 3:         C        0 10.847160 10.001261 0.8040608      0
 4:         C        0 11.525498  9.257539 1.8477048      1
 5:         C        1  9.932625 10.609684 0.3639572      1
 6:         T        1  5.389794  5.018746 0.6243732      0
 7:         T        1  3.791924  4.815747 0.3527879      1
 8:         T        1  4.636324  3.628669 1.7731161      0
 9:         T        0  3.373327  4.400832 0.1055467      0
10:         T        0  4.743522  5.294545 0.8612402      0
\end{verbatim}

This functionality is based on the \texttt{sim} function of the \textbf{lava}
package (\url{https://github.com/kkholst/lava})

\clearpage
\section{Modifying default options}
\label{sec:orgf674e92}
The \texttt{BuyseTest.options} method enable to get and set the default
options of the \texttt{BuyseTest} function. For instance, the default option
for trace is:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
BuyseTest.options("trace")
\end{lstlisting}

\begin{verbatim}
$trace
[1] 2
\end{verbatim}

To change the default option to 0 (i.e. no output) use:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
BuyseTest.options(trace = 0)
\end{lstlisting}

To restore the original default options do:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
BuyseTest.options(reinitialise = TRUE)
\end{lstlisting}

\clearpage

\section{Information about the R session used for this document}
\label{sec:org572a36f}

\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
sessionInfo()
\end{lstlisting}

\begin{verbatim}
R version 3.5.1 (2018-07-02)
Platform: x86_64-pc-linux-gnu (64-bit)
Running under: Ubuntu 16.04.5 LTS

Matrix products: default
BLAS: /usr/lib/libblas/libblas.so.3.6.0
LAPACK: /usr/lib/lapack/liblapack.so.3.6.0

locale:
 [1] LC_CTYPE=fr_FR.UTF-8       LC_NUMERIC=C               LC_TIME=da_DK.UTF-8       
 [4] LC_COLLATE=fr_FR.UTF-8     LC_MONETARY=da_DK.UTF-8    LC_MESSAGES=fr_FR.UTF-8   
 [7] LC_PAPER=da_DK.UTF-8       LC_NAME=C                  LC_ADDRESS=C              
[10] LC_TELEPHONE=C             LC_MEASUREMENT=da_DK.UTF-8 LC_IDENTIFICATION=C       

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base     

other attached packages:
[1] BuyseTest_1.6      testthat_2.0.0     data.table_1.11.8  Rcpp_0.12.19      
[5] prodlim_2018.04.18 butils.base_1.1    XML_3.98-1.16      selectr_0.4-1     
[9] devtools_1.13.6   

loaded via a namespace (and not attached):
 [1] compiler_3.5.1            pipeR_0.6.1.3             iterators_1.0.10         
 [4] base64enc_0.1-3           tools_3.5.1               digest_0.6.17            
 [7] pkgbuild_1.0.1            pkgload_1.0.0             memoise_1.1.0            
[10] lattice_0.20-35           rlang_0.2.2               foreach_1.4.4            
[13] Matrix_1.2-14             cli_1.0.1                 commonmark_1.6           
[16] parallel_3.5.1            RcppArmadillo_0.9.100.5.0 withr_2.1.2              
[19] httr_1.3.1                stringr_1.3.1             roxygen2_6.1.0.9000      
[22] xml2_1.2.0                desc_1.2.0                stats4_3.5.1             
[25] rprojroot_1.3-2           grid_3.5.1                R6_2.3.0                 
[28] processx_3.2.0            pbapply_1.3-4             survival_2.42-6          
[31] lava_1.6.3                purrr_0.2.5               callr_3.0.0              
[34] magrittr_1.5              codetools_0.2-15          splines_3.5.1            
[37] backports_1.1.2           ps_1.1.0                  assertthat_0.2.0         
[40] rvest_0.3.2               KernSmooth_2.23-15        stringi_1.2.4            
[43] doParallel_1.0.14         crayon_1.3.4              zoo_1.8-4
\end{verbatim}
\end{document}