#+TITLE: BuyseTest: Assessing a treatment effect based on multiple outcomes using generalized pairwise comparisons
#+Author: Brice Ozenne, Julien Peron, ..., Marc Buyse

#+BEGIN_SRC R :exports both :results output :session *R* :cache no
library(BuyseTest)
#+END_SRC

#+RESULTS:

* Functionalities

| Function      | effect                                                              |
|---------------+---------------------------------------------------------------------|
| simulBT       | simulate outcomes for two groups of observations.                   |
| powerBT       | power analysis using GPC.                                           |
| constStrata   | create a single strata variable from several categorical variables. |
| BuyseTest     | perform GPC computations.                                           |
| summary       | display the output from GPC.                                        |
| sensitivityBT | sensitivity analysis on choice of the thresholds of the GPC.        |


* The formula interface

The =BuyseTest= function enable to specify the sequence of endpoints
to be considered, their type and the associated threshold of clinical
relevance using a formula interface. The left hand side of the formula
specifies the binary variable identifying the two treatment
groups. The right hand side of the formula specifies the endpoints by
order of priority, separated by a =+=. Each endpoint is wrap by a
character string indicating its type:
- =Binary(Toxicity)= indicates that the endpoint Toxicity is binary. Binary can be abreviated into B or Bin.
- =Continuous(Score)= indicates that the endpoint Score is continuous. Continuous can be abreviated into C or Cont.
- =TimeToEvent(time)= indicates that the endpoint Toxicity is a time to event. TimeToEvent can be abreviated into T or TTE.
Additional arguments like the threshold of clinical relevance or the
type of event (1 for observed event, 0 for censoring) can be added using a comma as a separtor:
- =TTE(time,1,status)= indicates that time is the endpoint, the
  threshold of clinical relevance is 1 (with the same unit as time),
  and that status indicates the type of event. 
Finally, a single additional variable can be added in the formula (unwrapped) to specify the strata. 

\bigskip

The =initFormula= function extract all the necessary 
#+BEGIN_SRC R :exports both :results output :session *R* :cache no
BuyseTest:::initFormula(Treatment ~ B(var1) + C(var2, 10) + TTE(var3, 15, exa) + Gender)
#+END_SRC

#+RESULTS:
#+begin_example
$treatment
[1] "Treatment"

$type
[1] 1 2 3

$endpoint
[1] "var1" "var2" "var3"

$threshold
[1] NA 10 15

$censoring
[1] NA    NA    "exa"

$strata
[1] "Gender"
#+end_example

* Thresholds of clinical relevance

** Binary endpoints

Thresholds are not relevant for binary variables. This is why it is
not possible to specify them through the formula interface. 

\bigskip

Internally, since binary endpoints are treated as continuous endpoints,
any threshold strictly small than 1 and strictly greater than 0 would
be valid. However to avoid confusion with the continuous case, only
thresholds equaling 1/2 are accepted. Specifying =NA= is also possible;
in such case the threshold will be automatically converted to \(1/2\).

#+BEGIN_SRC R :exports both :results output :session *R* :cache no
BuyseTest:::initThreshold(threshold = NA, type = 1, D = 1, endpoint = c("Y1"))
#+END_SRC

#+RESULTS:
: [1] 0.5

This is because if \(Y=1\) and \(X=0\) then \(|Y-X| \geq 1/2\) 
while if \(Y=X\) then \(|Y-X| \leq 1/2\).

** Continuous and time to event endpoints

Threshold for continuous endpoints must be strictly positive. Whenever
a threshold is set to 0, it will be automatically reassigned to \(10^{-12}\):
#+BEGIN_SRC R :exports both :results output :session *R* :cache no
BuyseTest:::initThreshold(threshold = 0, type = 2, D = 1, endpoint = c("Y1"))
#+END_SRC

#+RESULTS:
: [1] 1e-12

This ensure that when \(Y=1\) and \(X=1.01\) then
\(|Y-X| \geq \tau=10^{-12}\) while whenever \(Y=X\) then \(|Y-X| \leq \tau=10^{-12}\)

\bigskip

In addition, thresholds corresponding to the same endpoints must be
strictly decreasing. In particular, the software will not accept a
redondant pair (endpoint, threshold).


* Diagram

#+BEGIN_SRC ditaa :file hello-world-round.png :cmdline -r
+--------------+
|              |
| Hello World! |
|              |
+--------------+
#+END_SRC

#+RESULTS:
[[file:hello-world-round.png]]


* CONFIG :noexport:
# #+LaTeX_HEADER:\affil{Department of Biostatistics, University of Copenhagen, Copenhagen, Denmark}
#+LANGUAGE:  en
#+LaTeX_CLASS: org-article
#+OPTIONS:   title:t author:t toc:nil todo:t 
#+OPTIONS:   H:3 num:t 
#+OPTIONS:   TeX:t LaTeX:t

** Additional commands
#+LaTeX_HEADER: %
#+LaTeX_HEADER: %%%% additional latex commands %%%%
#+LaTeX_HEADER: %

** Additional packages
#+LaTeX_HEADER: %
#+LaTeX_HEADER: %%%% additional packages %%%%
#+LaTeX_HEADER: %
#+LaTeX_HEADER:\usepackage{authblk}

** Algorithm
#+LATEX_HEADER: \RequirePackage{amsmath}
#+LATEX_HEADER: \RequirePackage{algorithm}
#+LATEX_HEADER: \RequirePackage[noend]{algpseudocode}

** Code
#+PROPERTY: header-args :session *R*
#+PROPERTY: header-args :tange yes % extract source code: http://orgmode.org/manual/Extracting-source-code.html
#+PROPERTY: header-args :eval yes :cache no
#+LATEX_HEADER: \RequirePackage{fancyvrb}
#+LATEX_HEADER: \DefineVerbatimEnvironment{verbatim}{Verbatim}{fontsize=\small,formatcom = {\color[rgb]{0.5,0,0}}}

** Display 
#+LATEX_HEADER: \RequirePackage{colortbl} % arrayrulecolor to mix colors
#+LATEX_HEADER: %% \input{0_Display.tex}

** Image
#+LATEX_HEADER: \RequirePackage{epstopdf} % to be able to convert .eps to .pdf image files

** Math
#+LATEX_HEADER: \RequirePackage{ifthen}
#+LATEX_HEADER: \RequirePackage{xspace} % space for newcommand macro
#+LATEX_HEADER: \RequirePackage{xifthen}
#+LATEX_HEADER: \RequirePackage{xargs}
#+LATEX_HEADER: \RequirePackage{dsfont}
#+LATEX_HEADER: \RequirePackage{amsmath,stmaryrd,graphicx}
#+LATEX_HEADER: \RequirePackage{prodint} % product integral symbol (\PRODI)

*** Template for shortcut
#+LATEX_HEADER: \newcommand\defOperator[7]{%
#+LATEX_HEADER:	\ifthenelse{\isempty{#2}}{
#+LATEX_HEADER:		\ifthenelse{\isempty{#1}}{#7{#3}#4}{#7{#3}#4 \left#5 #1 \right#6}
#+LATEX_HEADER:	}{
#+LATEX_HEADER:	\ifthenelse{\isempty{#1}}{#7{#3}#4_{#2}}{#7{#3}#4_{#1}\left#5 #2 \right#6}
#+LATEX_HEADER: }
#+LATEX_HEADER: }

#+LATEX_HEADER: \newcommand\defUOperator[5]{%
#+LATEX_HEADER: \ifthenelse{\isempty{#1}}{
#+LATEX_HEADER:		#5\left#3 #2 \right#4
#+LATEX_HEADER: }{
#+LATEX_HEADER:	\ifthenelse{\isempty{#2}}{\underset{#1}{\operatornamewithlimits{#5}}}{
#+LATEX_HEADER:		\underset{#1}{\operatornamewithlimits{#5}}\left#3 #2 \right#4}
#+LATEX_HEADER: }
#+LATEX_HEADER: }

#+LATEX_HEADER: \newcommand{\defBoldVar}[2]{	
#+LATEX_HEADER:	\ifthenelse{\equal{#2}{T}}{\boldsymbol{#1}}{\mathbf{#1}}
#+LATEX_HEADER: }

*** Shortcuts
#+LATEX_HEADER: \newcommandx\Cov[2][1=,2=]{\defOperator{#1}{#2}{C}{ov}{[}{]}{\mathbb}}
#+LATEX_HEADER: \newcommandx\Esp[2][1=,2=]{\defOperator{#1}{#2}{E}{}{[}{]}{\mathbb}}
#+LATEX_HEADER: \newcommandx\Prob[2][1=,2=]{\defOperator{#1}{#2}{P}{}{[}{]}{\mathbb}}
#+LATEX_HEADER: \newcommandx\Qrob[2][1=,2=]{\defOperator{#1}{#2}{Q}{}{[}{]}{\mathbb}}
#+LATEX_HEADER: \newcommandx\Var[2][1=,2=]{\defOperator{#1}{#2}{V}{ar}{[}{]}{\mathbb}}

#+LATEX_HEADER: \newcommandx\Binom[2][1=,2=]{\defOperator{#1}{#2}{B}{}{(}{)}{\mathcal}}
#+LATEX_HEADER: \newcommandx\Gaus[2][1=,2=]{\defOperator{#1}{#2}{N}{}{(}{)}{\mathcal}}
#+LATEX_HEADER: \newcommandx\Wishart[2][1=,2=]{\defOperator{#1}{#2}{W}{ishart}{(}{)}{\mathcal}}
#+LATEX_HEADER: \newcommandx\Likelihood[2][1=,2=]{\defOperator{#1}{#2}{L}{}{(}{)}{\mathcal}}
#+LATEX_HEADER: \newcommandx\Information[2][1=,2=]{\defOperator{#1}{#2}{I}{}{(}{)}{\mathcal}}
#+LATEX_HEADER: \newcommandx\Score[2][1=,2=]{\defOperator{#1}{#2}{S}{}{(}{)}{\mathcal}}

#+LATEX_HEADER: \newcommandx\Vois[2][1=,2=]{\defOperator{#1}{#2}{V}{}{(}{)}{\mathcal}}
#+LATEX_HEADER: \newcommandx\IF[2][1=,2=]{\defOperator{#1}{#2}{IF}{}{(}{)}{\mathcal}}
#+LATEX_HEADER: \newcommandx\Ind[1][1=]{\defOperator{}{#1}{1}{}{(}{)}{\mathds}}

#+LATEX_HEADER: \newcommandx\Max[2][1=,2=]{\defUOperator{#1}{#2}{(}{)}{min}}
#+LATEX_HEADER: \newcommandx\Min[2][1=,2=]{\defUOperator{#1}{#2}{(}{)}{max}}
#+LATEX_HEADER: \newcommandx\argMax[2][1=,2=]{\defUOperator{#1}{#2}{(}{)}{argmax}}
#+LATEX_HEADER: \newcommandx\argMin[2][1=,2=]{\defUOperator{#1}{#2}{(}{)}{argmin}}
#+LATEX_HEADER: \newcommandx\cvD[2][1=D,2=n \rightarrow \infty]{\xrightarrow[#2]{#1}}

#+LATEX_HEADER: \newcommandx\Hypothesis[2][1=,2=]{
#+LATEX_HEADER:         \ifthenelse{\isempty{#1}}{
#+LATEX_HEADER:         \mathcal{H}
#+LATEX_HEADER:         }{
#+LATEX_HEADER: 	\ifthenelse{\isempty{#2}}{
#+LATEX_HEADER: 		\mathcal{H}_{#1}
#+LATEX_HEADER: 	}{
#+LATEX_HEADER: 	\mathcal{H}^{(#2)}_{#1}
#+LATEX_HEADER:         }
#+LATEX_HEADER:         }
#+LATEX_HEADER: }

#+LATEX_HEADER: \newcommandx\dpartiel[4][1=,2=,3=,4=\partial]{
#+LATEX_HEADER: 	\ifthenelse{\isempty{#3}}{
#+LATEX_HEADER: 		\frac{#4 #1}{#4 #2}
#+LATEX_HEADER: 	}{
#+LATEX_HEADER: 	\left.\frac{#4 #1}{#4 #2}\right|_{#3}
#+LATEX_HEADER: }
#+LATEX_HEADER: }

#+LATEX_HEADER: \newcommandx\dTpartiel[3][1=,2=,3=]{\dpartiel[#1][#2][#3][d]}

#+LATEX_HEADER: \newcommandx\ddpartiel[3][1=,2=,3=]{
#+LATEX_HEADER: 	\ifthenelse{\isempty{#3}}{
#+LATEX_HEADER: 		\frac{\partial^{2} #1}{\left( \partial #2\right)^2}
#+LATEX_HEADER: 	}{
#+LATEX_HEADER: 	\frac{\partial^2 #1}{\partial #2\partial #3}
#+LATEX_HEADER: }
#+LATEX_HEADER: } 

#+LATEX_HEADER: \newcommand\Real{\mathbb{R}}
#+LATEX_HEADER: \newcommand\Rational{\mathbb{Q}}
#+LATEX_HEADER: \newcommand\Natural{\mathbb{N}}
#+LATEX_HEADER: \newcommand\trans[1]{{#1}^\intercal}%\newcommand\trans[1]{{\vphantom{#1}}^\top{#1}}
#+LATEX_HEADER: \newcommand{\independent}{\mathrel{\text{\scalebox{1.5}{$\perp\mkern-10mu\perp$}}}}
