% \VignetteEngine{knitr::knitr}
% \VignetteIndexEntry{tmle.npvi}
% \VignetteDepends{tmle.npvi}
% \VignetteKeywords{Targeted minimum loss estimation}
% \VignettePackage{tmle.npvi}

\documentclass[a4paper]{article}
\usepackage{amsmath,amssymb,manfnt}
\usepackage[textwidth=15cm, textheight=23cm]{geometry}
\graphicspath{{fig/}}

<<include=FALSE>>=
library(knitr)
opts_chunk$set(
fig.path='fig/'
)
@


\addtolength{\parskip}{\baselineskip}

\newcommand{\Robject}[1]{{\texttt{#1}}}
\newcommand{\Rfunction}[1]{{\texttt{#1}}}
\newcommand{\Rpackage}[1]{{\textit{#1}}}
\newcommand{\Rclass}[1]{{\textit{#1}}}
\newcommand{\Rfunarg}[1]{{\textit{#1}}}
\sloppy

\newcommand{\xR}{\mathbb{R}}
\newcommand{\xW}{{\cal W}}

\title{Using the \Rpackage{tmle.npvi} \texttt{R} package}

\author{Antoine Chambaz \and Pierre Neuvial}

\date{Package version \Sexpr{packageDescription("tmle.npvi")$Version}\\Date \Sexpr{packageDescription("tmle.npvi")$Date}}


\begin{document}

\maketitle 
\tableofcontents 

The caution symbol \textdbend marks important details.



\section{Citing \Rpackage{tmle.npvi}}

If    you    use     the    \Rpackage{tmle.npvi}    package,    please    cite
\cite{chambaz12estimation}.

\section{The non-parametric variable importance parameter}

Consider the following statistical problem. We observe the data structure $O =
(W,X,Y)$ on an  experimental unit of interest, where $W \in  \xW$ stands for a
vector  of baseline  covariates,  $X \in  \xR$  and $Y  \in \xR$  respectively
quantify  an  exposure  and  a  response,  and  we  wish  to  investigate  the
relationship between $X$  on $Y$, accounting for~$W$. Taking  $W$ into account
is desirable  because we  know (or  cannot rule out  the possibility)  that it
contains  confounding  factors, {\em  i.e.},  common  factors  upon which  the
exposure $X$ and the response $Y$ may simultaneously depend.  Furthermore, the
exposure features  a reference  level $x_{0}$ with  positive mass (there  is a
positive probability that $X = x_{0}$) and a {\em continuum} of other levels.

This motivates the definition of the non-parametric variable importance (NPVI)
parameter introduced in~\cite{chambaz12estimation}:  for all distributions $P$
of $O$ compatible  with the above description of $O$,  for $f$ a user-supplied
function such that $f(0)=0$,
\begin{equation*}
  \Psi_{f}(P) = \frac{E_{P} \{f(X - x_{0}) [E_{P} (Y|X, W)) - E_{P} (Y|X=x_{0},
    W)]\}}{E_{P}\{f(X-x_{0})^{2}\}}. 
\end{equation*}
In contrast, the parameter $\Phi_{f}$ characterized by
\begin{equation*}
  \Phi_{f}(P) = \frac{E_{P} \{f(X - x_{0})Y\}}{E_{P}\{f(X-x_{0})^{2}\}}
\end{equation*}
neglects the information conveyed by $W$.


The  \Rpackage{tmle.npvi}  \texttt{R}  package  implements  the  inference  of
$\Psi_{f}(P)$ (and $\Phi_{f}  (P)$) based on independent draws  from $P$ based
on the  targeted minimum  loss estimation (TMLE)  principle, as  described and
studied in~\cite{chambaz12estimation}.


\section{Using the \Rpackage{tmle.npvi} \texttt{R} package on simulated data} 

\subsection{Set up}

We first set the verbosity parameter and random seed.

<<>>=
library("tmle.npvi")
library("R.utils")
log <- Arguments$getVerbose(-8, timestamp=TRUE)
set.seed(12345)
@


\subsection{Generating a simulated data set}

The   package  includes   a  function,   \Rfunction{getSample},   to  generate
independent copies  of $O=(W,X,Y)  \in [0,1] \times  \xR \times \xR$  from the
distribution        $P^{s}$         characterized        in        Section~6.4
of~\cite{chambaz12estimation}.  The distribution  $P^{s}$ is inspired by real
data   from  The   Cancer  Genome   Atlas  (TCGA)   project~\cite{TCGA08},  a
collaborative initiative  to better understand several types  of cancers using
existing large-scale whole-genome technologies.  Given the \texttt{EGFR} gene,
known  to be  altered in  glioblastoma  multiforme (GBM)  cancers, the  random
variables $W$, $X$ and $Y$ can be interpreted as follows:
\begin{itemize}
\item[-] $W$: a measure of DNA methylation of \texttt{EGFR}, the proportion of
  ``methylated''  signal   at  a   CpG  locus  in   the  promoter   region  of
  \texttt{EGFR},
\item[-]  $X$:  a measure  of  DNA copy  number  of  \texttt{EGFR}, a  locally
  smoothed total copy number relative to a set of reference samples,
\item[-] $Y$: a measure of the expression of \texttt{EGFR}, a ``unified'' gene
  expression level across three microarray platforms,
\end{itemize}
all  evaluated in  GBM cancer  cells of  a patient.   The  simulation strategy
implements three constraints:
\begin{itemize}
\item[-] there are generally up  to three copy number classes: normal regions,
  and regions of copy number gains and losses;
\item[-]  in   normal  regions,  expression  is   negatively  correlated  with
  methylation;
\item[-] in regions of copy  number alteration, copy number and expression are
  positively correlated.
\end{itemize}

We set parameters for the simulation.

<<>>=
O <- cbind(W=c(0.05218652, 0.01113460),
           X=c(2.722713, 9.362432),
           Y=c(-0.4569579, 1.2470822))
O <- rbind(NA, O)

lambda0 <- function(W) {-W}

p <- c(0, 1/2, 1/2)
omega <- c(0, 3, 3)
S <- matrix(c(10, 1, 1, 0.5), 2 ,2)
n <- 200
@

We simulate  a data set  of \Sexpr{n} independent and  identically distributed
observations.

<<>>=
sim <- getSample(n, O, lambda0, p=p, omega=omega, sigma2=1, Sigma3=S)
obs <- sim$obs
head(obs)
@

At this  stage, the baseline  covariate $W$ takes  its values in  $[0,1]$. The
\Rpackage{tmle.npvi} \texttt{R}  package can deal  with multi-dimensional $W$,
so we may add other baseline covariates for the sake of the presentation. Note
that this  alters the definition of  $P^{s}$.  However, the value  of the NPVI
parameter is preserved.

<<>>=
V <- matrix(runif(3*nrow(obs)), ncol=3)
colnames(V) <- paste("V", 1:3, sep="")
obs <- cbind(V, obs)
head(obs)
@

Baseline  covariates are  identified in  the matrix  of observations  as those
numbers  stored  in  the  columns  which are  not  labelled  \texttt{"X"}  nor
\texttt{"Y"}.   The  \texttt{"X"}   and   \texttt{"Y"}  columns   respectively
correspond to  the exposure and response.  

\textdbend  At this  stage, the  reference  value for  $X$ is  \Rfunction{O[2,
  "X"]}.

\subsection{True value of the NPVI parameter}

The function \Rfunction{getSample} also  computes an approximation to the true
value of the NPVI parameter  $\Psi_{f}(P^{s})$, as well as an approximation to
the  true  variance  of  the   efficient  influence  curve  of  $\Psi_{f}$  at
$P^{s}$. The approximated variance can be used together with the user-supplied
sample size \verb|nrow(sim$obs)| to  assert how accurate is the approximation.
Used together with the number of observations in \Rfunction{obs}, we obtain an
interval  (approximately)  centered   at  $\Psi_{f}(P^{s})$  whose  length  is
(approximately) the smallest possible length of a confidence interval based on
\verb|nrow(obs)| observations.

<<>>=
sim <- getSample(1e4, O, lambda0, p=p, omega=omega, 
                 sigma2=1, Sigma3=S, verbose=log)
truePsi <- sim$psi

confInt0 <- truePsi + c(-1, 1)*qnorm(.975)*sqrt(sim$varIC/nrow(sim$obs))
confInt <- truePsi + c(-1, 1)*qnorm(.975)*sqrt(sim$varIC/nrow(obs))

msg <- "\nCase f=identity:\n"
msg <- c(msg, "\ttrue psi is: ", paste(signif(truePsi, 3)), "\n")
msg <- c(msg, "\t95%-confidence interval for the approximation is: ", 
         paste(signif(confInt0, 3)), "\n")
msg <- c(msg, "\toptimal 95%-confidence interval is: ", 
         paste(signif(confInt, 3)), "\n")
cat(msg)
@ 

\textdbend By default, $f$ is taken equal to the identity. We could choose any
function $f$ such that $f(0)=0$, say, for example, $f = \arctan$.

<<>>=
sim2 <- getSample(1e4, O, lambda0, p=p, omega=omega, 
                  sigma2=1, Sigma3=S, f=atan, verbose=log)
truePsi2 <- sim2$psi

confInt02 <- truePsi2 + c(-1, 1)*qnorm(.975)*sqrt(sim2$varIC/nrow(sim2$obs))
confInt2 <- truePsi2 + c(-1, 1)*qnorm(.975)*sqrt(sim2$varIC/nrow(obs))

msg <- "\nCase f=atan:\n"
msg <- c(msg, "\ttrue psi is: ", paste(signif(truePsi2, 3)), "\n")
msg <- c(msg, "\t95%-confidence interval for the approximation is: ", 
         paste(signif(confInt02, 3)), "\n")
msg <- c(msg, "\toptimal 95%-confidence interval is: ", 
         paste(signif(confInt2, 3)), "\n")
cat(msg)
@ 


\subsection{TMLE procedure}

The function  \Rfunction{tmle.npvi} implements the  inference of $\Psi_{f}(P)$
(and of $\Phi_{f} (P)$) based on  independent draws from $P$ based on the TMLE
principle.

\textdbend The function \Rfunction{tmle.npvi} assumes that the reference value
$x_{0}=0$. So it is necessary here to shift the values of $X$.

<<>>=
X0 <- O[2,2]
obsC <- obs
obsC[, "X"] <- obsC[, "X"] - X0
obs <- obsC
head(obs)
@ 

We now run the TMLE procedure,  with $f = \text{identity}$ (default value) and
relying on  parametric models  to estimate some  relevant infinite-dimensional
features of $P^{s}$.  Alternatively, we could have chosen to rely on the Super
Learning        methodology~\cite{vanderlaan07,R:SL}        (by       setting
\verb|flavor="superLearning"|), in  which case we could  have parallelized the
computations using  several nodes (by  tuning the \verb|nodes|  argument). All
options are given in the documentation of the \verb|tmle.npvi| function.


<<>>=
npvi <- tmle.npvi(obs, f=identity, flavor="learning")
npvi
@ 

The basic  summary of a \verb|NPVI|  object like \verb|npvi|,  as shown above,
presents: 
\begin{itemize}
\item[-] the sample size;
\item[-] the value  of the TMLE estimator of $\Psi_{f}  (P)$ and its estimated
  standard deviation;
\item[-] the fine-tuning of the convergence criteria, number of iterations and
  reasons for stopping the iterative procedure;
\item[-]  a confidence  interval for  $\Psi_{f} (P)$  (default 95\%-confidence
  level), and the $p$-values of  the two-sided tests of $"\Psi_{f} (P)=0"$ and
  $"\Psi_{f}(P)  = \Phi_{f}  (P)"$ (the  estimate  of $\Phi_{f}  (P)$ is  also
  provided).
\end{itemize}

It is possible to specify another confidence level.

<<>>=
setConfLevel(npvi, 0.9)
npvi
@

A more comprehensive history of the TMLE procedure can be easily obtained from
a \verb|NPVI| object like \verb|npvi|. The  content of each column is given in
the documentation of the \verb|getHistory| function. 

<<>>=
history <- getHistory(npvi)
print(round(history, 4))
@

The following lines produce the plot shown in Figure~\ref{fig:visu}.

<<confInt, include=FALSE>>=
hp <- history[, "psi"]
hs <- history[, "sic"]
hs[1] <- NA
ics <-  c(-1,1) %*% t(qnorm(0.975)*hs/sqrt(nrow(getObs(npvi))))

pch <- 20
ylim <- range(c(confInt, hp, ics+hp), na.rm=TRUE)

xs <- (1:length(hs))-1
plot(xs, hp, ylim=ylim, pch=pch, xlab="Iteration", ylab=expression(psi[n]),
     xaxp=c(0, length(hs)-1, length(hs)-1))
dummy <- sapply(seq(along=xs), function(x) lines(c(xs[x],xs[x]), hp[x]+ics[, x]))

abline(h=confInt, col="blue")
abline(h=confInt0, col="red")
@ 

\begin{figure}
  \centering
  \includegraphics[width=6cm]{confInt-1}
  \caption{A visual summary of  the TMLE procedure contained in \texttt{npvi}.
    The black  dots represent  the successive values  of $\Psi_{f}(P_{n}^{k})$
    for    $k=0,1,2$,   where   $\Psi_{f}(P_{n}^{2})$    is   the    TMLE   of
    $\Psi_{f}(P^{s})$ based on $n  =$ \Sexpr{nrow(obs)} observations (here, $f
    = \text{identity}$).   The black vertical  lines represent 95\%-confidence
    intervals  for  $\Psi_{f}(P^{s})$.   The  red (blue,  respectively)  lines
    represent   the    interval   approximately   centered    at   the   truth
    $\Psi_{f}(P^{s})$  with  a  length  approximately equal  to  the  smallest
    possible  length of  confidence interval  based  on \Sexpr{nrow(sim2$obs)}
    (\Sexpr{nrow(obs)}, respectively) observations.}
  \label{fig:visu}
\end{figure}

\section{Analysis of TCGA data}

\subsection{TCGA data included in the package}
\label{subsec:tcga}

The package  includes real data, namely  expression, DNA copy  number, and DNA
methylation  data of 150  genes for  463 breast  cancer samples  from publicly
available TCGA data~\cite{TCGA12}. 
<<>>=
data(tcga2012brca)
@ 

Gene names and genomic coordinates are stored in the names of the list:
<<>>=
nms <- names(tcga2012brca)
str(nms)
@ 


\subsection{Gene TP53 analysis}

The data  set associated  with gene TP53  includes 3 DNA  methylation measures
across the gene.
<<pairs>>=
ii <- grep("TP53", nms)
obs <- tcga2012brca[[ii]]
head(obs)
@ 

In  this case,  there are  only \Sexpr{sum(obs[,  "X"]==0)}  observations with
neutral copy number ($X=0$ after shifting).  We arbitrarily set a threshold to
$0.02$. This is what the data set looks like, where green points correspond to
observations whose  copy numbers are  smaller than this threshold  in absolute
value:
<<>>=
thr <- 0.02
whichSmall <- which(abs(obs[, "X"]) <= thr)
cols <- rep("black", nrow(obs))
cols[whichSmall] <- "green"
pairs(obs, main=nms[ii], col=cols, pch=19, cex=0.5)

## thresholding
whichSmall <- which(abs(obs[, "X"]) <= thr)
obs[whichSmall, "X"] <- 0
@ 

After  thresholding  there are  \Sexpr{sum(obs[,  "X"]==0)} observations  with
neutral copy number.  We analyze the data set as follows:
<<>>=
npvi.TP53 <- tmle.npvi(obs)
npvi.TP53
@

\subsection{Whole genome analysis}

The following script creates a data set for each gene from TCGA~\cite{TCGA12}.
<<eval=FALSE>>=
system.file("testScripts/tcga2012brca/01.merge,manyCG.R", 
            package="tmle.npvi")
@ 

Once it is run, executing the script below yields the \texttt{tcga2012brca} data set
presented in Section~\ref{subsec:tcga}.
<<eval=FALSE>>=
system.file("testScripts/tcga2012brca/01.1.exportGeneLevelData.R", 
            package="tmle.npvi")
@    

The following  script analyzes all the  data sets previously  created based on
the \verb|tmle.npvi| function.
<<eval=FALSE>>=
system.file("testScripts/tcga2012brca/02.tmle.npvi.R", 
            package="tmle.npvi")
@  


The computation of $p$-values and illustration of the results along the genome
can be performed by drawing inspiration from the following last two scripts.
<<eval=FALSE>>=
system.file("testScripts/tcga2012brca/03.pValues.R", 
            package="tmle.npvi")
system.file("testScripts/tcga2012brca/04.propZero.R", 
            package="tmle.npvi")
@ 

\section{Session information}
\label{sec:session-information}

<<echo=FALSE>>=
sessionInfo()
@ 

\bibliographystyle{plain}
\begin{thebibliography}{}

\bibitem[Chambaz et~al., 2012]{chambaz12estimation}
Chambaz, A., Neuvial, P., and van~der Laan, M.~J. (2012).
\newblock Estimation of a non-parametric variable importance measure of a
  continuous exposure.
\newblock {\em Electronic Journal of Statistics}, 6:1059--1099.

\bibitem[Polley and van~der Laan, 2011]{R:SL}
Polley, E. and van~der Laan, M.~J. (2011).
\newblock {\em SuperLearner}.
\newblock R package version 2.0-4.

\bibitem[{The Cancer Genome Atlas (TGCA) research Network}, 2008]{TCGA08}
{The Cancer Genome Atlas (TGCA) research Network} (2008).
\newblock Comprehensive genomic characterization defines human glioblastoma
  genes and core pathways.
\newblock {\em Nature}, 455:1061--1068.

\bibitem[{The Cancer Genome Atlas (TGCA) research Network}, 2012]{TCGA12}
{The Cancer Genome Atlas (TGCA) research Network} (2012).
\newblock .
\newblock {\em Nature}, 490:(7418), 61--70.

\bibitem[van~der Laan et~al., 2007]{vanderlaan07}
van~der Laan, M.~J., Polley, E.~C., and Hubbard, A.~E. (2007).
\newblock Super learner.
\newblock {\em Stat. Appl. Genet. Mol. Biol.}, 6:Article~25.

\end{thebibliography}


\end{document}




