\SweaveOpts{results=hide, prefix.string=vigpics/exp}
\include{zinput}
%\VignetteIndexEntry{Exponential Regression for Duration Dependent Variables}
%\VignetteDepends{Zelig, survival}
%\VignetteKeyWords{model,exponential,regression, time}
%\VignettePackage{Zelig}
\begin{document}
\nobibliography*
<<beforepkgs, echo=FALSE>>=
 before=search()
@

<<loadLibrary, echo=F,results=hide>>=
pkg <- search()
if(!length(grep("package:Zelig",pkg)))
library(Zelig)
@ 

\section{{\tt exp}: Exponential Regression for Duration Dependent Variables}\label{exp}

Use the exponential duration regression model if you have a dependent
variable representing a duration (time until an event).  The model
assumes a constant hazard rate for all events.  The dependent variable
may be censored (for observations have not yet been completed when
data were collected).

\subsubsection{Syntax}

\begin{verbatim}
> z.out <- zelig(Surv(Y, C) ~ X, model = "exp", data = mydata)
> x.out <- setx(z.out)
> s.out <- sim(z.out, x = x.out)
\end{verbatim}
Exponential models require that the dependent variable be in the form
{\tt Surv(Y, C)}, where {\tt Y} and {\tt C} are vectors of length $n$.
For each observation $i$ in 1, \dots, $n$, the value $y_i$ is the
duration (lifetime, for example), and the associated $c_i$ is a binary
variable such that $c_i = 1$ if the duration is not censored ({\it
  e.g.}, the subject dies during the study) or $c_i = 0$ if the
duration is censored ({\it e.g.}, the subject is still alive at the
end of the study and is know to live at least as long as $y_i$).  If
$c_i$ is omitted, all Y are assumed to be completed; that is, time
defaults to 1 for all observations.

\subsubsection{Input Values} 

In addition to the standard inputs, {\tt zelig()} takes the following
additional options for exponential regression:  
\begin{itemize}
\item {\tt robust}: defaults to {\tt FALSE}.  If {\tt TRUE}, {\tt
zelig()} computes robust standard errors based on sandwich estimators
(see \cite{Huber81} and \cite{White80}) and the options selected in
{\tt cluster}.
\item {\tt cluster}:  if {\tt robust = TRUE}, you may select a
variable to define groups of correlated observations.  Let {\tt x3} be
a variable that consists of either discrete numeric values, character
strings, or factors that define strata.  Then
\begin{verbatim}
> z.out <- zelig(y ~ x1 + x2, robust = TRUE, cluster = "x3", 
                 model = "exp", data = mydata)
\end{verbatim}
means that the observations can be correlated within the strata defined by
the variable {\tt x3}, and that robust standard errors should be
calculated according to those clusters.  If {\tt robust = TRUE} but
{\tt cluster} is not specified, {\tt zelig()} assumes that each
observation falls into its own cluster.  
\end{itemize}  

\subsubsection{Example}

Attach the sample data: 
<<Example.data>>=
 data(coalition)
@ 

Estimate the model: 
<<Example.zelig>>=
 z.out <- zelig(Surv(duration, ciep12) ~ fract + numst2, model = "exp", 
                 data = coalition)
@ 
View the regression output:  
<<Example.summary>>=
 summary(z.out)
@ 
Set the baseline values (with the ruling coalition in the minority)
and the alternative values (with the ruling coalition in the majority)
for X:
<<Example.setx>>=
 x.low <- setx(z.out, numst2 = 0)
 x.high <- setx(z.out, numst2 = 1)
@ 
Simulate expected values ({\tt qi\$ev}) and first differences ({\tt qi\$fd}):
<<Example.sim>>=
 s.out <- sim(z.out, x = x.low, x1 = x.high)
@ 
Summarize quantities of interest and produce some plots:  
<<Example.summary>>=
 summary(s.out)
@ 
\begin{center}
<<label=ExamplePlot,fig=true,echo=true>>= 
 plot(s.out)
@ 
\end{center}

\subsubsection{Model}

Let $Y_i^*$ be the survival time for observation $i$. This variable
might be censored for some observations at a fixed time $y_c$ such
that the fully observed dependent variable, $Y_i$, is defined as
\begin{equation*}
  Y_i = \left\{ \begin{array}{ll}
      Y_i^* & \textrm{if }Y_i^* \leq y_c \\
      y_c & \textrm{if }Y_i^* > y_c \\
    \end{array} \right.
\end{equation*}

\begin{itemize}
\item The \emph{stochastic component} is described by the distribution
  of the partially observed variable $Y^*$.  We assume $Y_i^*$ follows
  the exponential distribution whose density function is given by
  \begin{equation*}
    f(y_i^*\mid \lambda_i) = \frac{1}{\lambda_i} \exp\left(-\frac{y_i^*}{\lambda_i}\right)
  \end{equation*}
  for $y_i^*\ge 0$ and $\lambda_i>0$. The mean of this distribution is
  $\lambda_i$.  

  In addition, survival models like the exponential have three
  additional properties.  The hazard function $h(t)$ measures the
  probability of not surviving past time $t$ given survival up to
  $t$. In general, the hazard function is equal to $f(t)/S(t)$ where
  the survival function $S(t) = 1 - \int_{0}^t f(s) ds$ represents the
  fraction still surviving at time $t$.  The cumulative hazard
  function $H(t)$ describes the probability of dying before time $t$.
  In general, $H(t)= \int_{0}^{t} h(s) ds = -\log S(t)$.  In the case
  of the exponential model,
\begin{eqnarray*}
h(t) &=& \frac{1}{\lambda_i} \\
S(t) &=& \exp\left( -\frac{t}{\lambda_i} \right) \\
H(t) &=& \frac{t}{\lambda_i}
\end{eqnarray*}
For the exponential model, the hazard function $h(t)$ is constant over
time.  The Weibull model and lognormal models allow the hazard
function to vary as a function of elapsed time (see \Sref{weibull} and
\Sref{lognorm} respectively).
  
\item The \emph{systematic component} $\lambda_i$ is modeled as
  \begin{equation*}
    \lambda_i = \exp(x_i \beta),
  \end{equation*}
  where $x_i$ is the vector of explanatory variables, and $\beta$ is
  the vector of coefficients.
\end{itemize}  


\subsubsection{Quantities of Interest} 

\begin{itemize}
\item The expected values ({\tt qi\$ev}) for the exponential model are
  simulations of the expected duration given $x_i$ and draws of
  $\beta$ from its posterior, $$E(Y) = \lambda_i = \exp(x_i \beta).$$

\item The predicted values ({\tt qi\$pr}) are draws from the
  exponential distribution with rate equal to the expected value.  

\item The first difference (or difference in expected values, {\tt
  qi\$ev.diff}), is
\begin{equation}
\textrm{FD} \; = \; E(Y \mid x_1) - E(Y \mid x), 
\end{equation}
where $x$ and $x_1$ are different vectors of values for the
explanatory variables.  

\item In conditional prediction models, the average expected treatment
  effect ({\tt att.ev}) for the treatment group is \begin{equation*}
  \frac{1}{\sum_{i=1}^n t_i}\sum_{i:t_i=1}^n \left\{ Y_i(t_i=1) - E[Y_i(t_i=0)]
  \right\}, \end{equation*} where $t_i$ is a binary explanatory
  variable defining the treatment ($t_i=1$) and control ($t_i=0$)
  groups. When $Y_i(t_i=1)$ is censored rather than observed, we
  replace it with a simulation from the model given available
  knowledge of the censoring process.  Variation in the simulations
  is due to two factors: uncertainty in the imputation process for
  censored $y_i^*$ and uncertainty in simulating $E[Y_i(t_i=0)]$, the
  counterfactual expected value of $Y_i$ for observations in the
  treatment group, under the assumption that everything stays the same
  except that the treatment indicator is switched to $t_i=0$.
    
  \item In conditional prediction models, the average predicted
  treatment effect ({\tt att.pr}) for the treatment group is
  \begin{equation*} \frac{1}{\sum_{i=1}^n t_i}\sum_{i:t_i=1}^n \left\{ Y_i(t_i=1) -
  \widehat{Y_i(t_i=0)} \right\}, \end{equation*} where $t_i$ is a
  binary explanatory variable defining the treatment ($t_i=1$) and
  control ($t_i=0$) groups.  When $Y_i(t_i=1)$ is censored rather than
  observed, we replace it with a simulation from the model given
  available knowledge of the censoring process.  Variation in the
  simulations is due to two factors: uncertainty in the imputation
  process for censored $y_i^*$ and uncertainty in simulating
  $\widehat{Y_i(t_i=0)}$, the counterfactual predicted value of $Y_i$
  for observations in the treatment group, under the assumption that
  everything stays the same except that the treatment indicator is
  switched to $t_i=0$.

\end{itemize}

\subsubsection{Output Values}

The output of each Zelig command contains useful information which you
may view.  For example, if you run \texttt{z.out <- zelig(Surv(Y,
  C) \~\, X, model = "exp", data)}, then you may examine the
available information in \texttt{z.out} by using
\texttt{names(z.out)}, see the {\tt coefficients} by using {\tt
  z.out\$coefficients}, and a default summary of information
through \texttt{summary(z.out)}.  Other elements available through
the {\tt \$} operator are listed below.

\begin{itemize}
\item From the {\tt zelig()} output object {\tt z.out}, you may extract:
   \begin{itemize}
   \item {\tt coefficients}: parameter estimates for the explanatory
     variables.
   \item {\tt icoef}: parameter estimates for the intercept and scale
     parameter.  While the scale parameter varies for the Weibull
     distribution, it is fixed to 1 for the exponential distribution
     (which is modeled as a special case of the Weibull).  
   \item {\tt var}: the variance-covariance matrix for the estimates
     of $\beta$.  
   \item {\tt loglik}: a vector containing the log-likelihood for the
     model and intercept only (respectively).
   \item {\tt linear.predictors}: the vector of
     $x_{i}\beta$.
   \item {\tt df.residual}: the residual degrees of freedom.
   \item {\tt df.null}: the residual degrees of freedom for the null
     model. 
   \item {\tt zelig.data}: the input data frame if {\tt save.data = TRUE}.  
   \end{itemize}

\item Most of this may be conveniently summarized using {\tt
   summary(z.out)}.  From {\tt summary(z.out)}, you may
 additionally extract: 
   \begin{itemize}
   \item {\tt table}: the parameter estimates with their
     associated standard errors, $p$-values, and $t$-statistics.  For
     example, {\tt summary(z.out)\$table}
   \end{itemize}

\item From the {\tt sim()} output stored in {\tt s.out}:
  
\item From the {\tt sim()} output object {\tt s.out}, you may extract
  quantities of interest arranged as matrices indexed by simulation
  $\times$ {\tt x}-observation (for more than one {\tt x}-observation).
  Available quantities are:

   \begin{itemize}
   \item {\tt qi\$ev}: the simulated expected values for the specified
     values of {\tt x}.
   \item {\tt qi\$pr}: the simulated predicted values drawn from a
     distribution defined by the expected values.
   \item {\tt qi\$fd}: the simulated first differences between the
     simulated expected values for {\tt x} and {\tt x1}.
   \item {\tt qi\$att.ev}: the simulated average expected treatment
     effect for the treated from conditional prediction models.  
   \item {\tt qi\$att.pr}: the simulated average predicted treatment
     effect for the treated from conditional prediction models.  
   \end{itemize}
\end{itemize}



\subsection* {How to Cite} 
\input{cites/exp}
\input{citeZelig}

\subsection* {See also}
The exponential function is part of the survival library by Terry
Therneau, ported to R by Thomas Lumley.  Advanced users may wish to
refer to \texttt{help(survfit)} in the survival library and \cite{VenRip02}.Sample
data are from \cite{KinAltBur90}.

\bibliographystyle{asa}
\bibliography{gk,gkpubs}
<<afterpkgs, echo=FALSE>>=
 after<-search()
 torm<-setdiff(after,before)
 for (pkg in torm)
 detach(pos=match(pkg,search()))
@
 \end{document}


%%% Local Variables: 
%%% mode: latex
%%% TeX-master: t
%%% End: 









