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

<<loadLibrary, echo=F,results=hide>>=
library(Zelig)
@ 

\section{{\tt lognorm}: Log-Normal Regression for Duration
Dependent Variables}\label{lognorm}

The log-normal model describes an event's duration, the dependent
variable, as a function of a set of explanatory variables.  The
log-normal model may take time censored dependent variables, and
allows the hazard rate to increase and decrease.

\subsubsection{Syntax}

\begin{verbatim}
> z.out <- zelig(Surv(Y, C) ~ X, model = "lognorm", data = mydata)
> x.out <- setx(z.out)
> s.out <- sim(z.out, x = x.out)
\end{verbatim}
Log-normal 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) of each subject, 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).  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 lognormal 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}) based on the options 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 = "lognorm",
                 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)
@ 
<<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$ with the density
function $f(y)$ and the corresponding distribution function
$F(t)=\int_{0}^t f(y) dy$. 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^*$.  For the lognormal model,
there are two equivalent representations:  
  \begin{eqnarray*}
    Y_i^* \; \sim \; \textrm{LogNormal}(\mu_i, \sigma^2) & \textrm{ or
} & \log(Y_i^*) \; \sim \; \textrm{Normal}(\mu_i, \sigma^2)
\end{eqnarray*}
where the parameters $\mu_i$ and $\sigma^2$ are the mean and variance
of the Normal distribution. (Note that the output from {\tt zelig()}
parameterizes {\tt scale}$ = \sigma$.)

 In addition, survival models like the lognormal 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 lognormal model, 
\begin{eqnarray*}
h(t) &=& \frac{1}{\sqrt{2 \pi} \, \sigma t \, S(t)}
\exp\left\{-\frac{1}{2 \sigma^2} (\log \lambda t)^2\right\} \\
S(t) &=& 1 - \Phi\left(\frac{1}{\sigma} \log \lambda t\right) \\
H(t) &=& -\log \left\{ 1 - \Phi\left(\frac{1}{\sigma} \log \lambda t\right) \right\}
\end{eqnarray*}
where $\Phi(\cdot)$ is the cumulative density function for the Normal
distribution.  

\item The \emph{systematic component} is described as: 
\begin{equation*}
\mu_i = x_i \beta .
\end{equation*}

\end{itemize}

\subsubsection{Quantities of Interest} 

\begin{itemize}
\item The expected values ({\tt qi\$ev}) for the lognormal model are
  simulations of the expected duration:  
\begin{equation*}
E(Y) =  \exp\left(\mu_i + \frac{1}{2}\sigma^2 \right),
\end{equation*}
given draws of $\beta$ and $\sigma$ from their sampling distributions. 

\item The predicted value is a draw from the log-normal distribution
  given simulations of the parameters $(\lambda_i, \sigma)$.

\item The first difference ({\tt qi\$fd}) is
\begin{equation*}
\textrm{FD} = E(Y \mid x_1) - E(Y \mid x). 
\end{equation*}

\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 \{ Y_i(t_i=1) - E[Y_i(t_i=0)] \}, \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 \{  Y_i(t_i=1) -
\widehat{Y_i(t_i=0)} \}, 
\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
  are 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 = "lognorm", 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 $\sigma$.  
   \item {\tt var}: Variance-covariance matrix.  
   \item {\tt loglik}: 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.
   \end{itemize}

\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 the
     distribution defined by $(\lambda_i, \sigma)$.
   \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/lognorm}
\input{citeZelig}

\subsection* {See also}
The exponential function is part of the survival library by 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: 




