\SweaveOpts{results=hide, prefix.string=vigpics/tobit}
\include{zinput}
%\VignetteIndexEntry{Linear regression for Left-Censored Dependet Variable}
%\VignetteDepends{Zelig, survival}
%\VignetteKeyWords{model, linear,regression,left-censored,continuous}
%\VignettePackage{Zelig}
\begin{document}
\nobibliography*
<<beforepkgs, echo=FALSE>>=
 before=search()
@

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

\section{\texttt{tobit}: Linear Regression for a
Left-Censored Dependent Variable} \label{tobit}

Tobit regression estimates a linear regression model for a
left-censored dependent variable, where the dependent variable is
censored from below.  While the classical tobit model has values
censored at 0, you may select another censoring point.  For other
linear regression models with fully observed dependent variables, see
Bayesian regression (\Sref{normal.bayes}), maximum likelihood normal
regression (\Sref{normal}), or least squares (\Sref{ls}).

\subsubsection{Syntax}
\begin{verbatim}
> z.out <- zelig(Y ~ X1 + X2, below = 0, above = Inf, 
                  model = "tobit", data = mydata)
> x.out <- setx(z.out)
> s.out <- sim(z.out, x = x.out)
\end{verbatim}

\subsubsection{Inputs}
{\tt zelig()} accepts the following arguments to specify how the
dependent variable is censored.
\begin{itemize}
\item \texttt{below}: (defaults to 0)  The point at which the dependent
variable is censored from below.  If any values in the dependent
variable are observed to be less than the censoring point, it is
assumed that that particular observation is censored from below at the
observed value.  (See \Sref{tobit.bayes} for a Bayesian
implementation that supports both left and right censoring.) 
 \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 = "tobit", 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}

Zelig users may wish to refer to \texttt{help(survreg)} for more 
information.

\subsubsection{Examples}

\begin{enumerate}
\item {Basic Example} \\
Attaching the sample  dataset:
<<Examples.data>>=
 data(tobin)
@ 
Estimating linear regression using \texttt{tobit}:
<<Examples.zelig>>=
 z.out <- zelig(durable ~ age + quant, model = "tobit", data = tobin)
@ 
Setting values for the explanatory variables to their sample averages:
<<Examples.setx>>=
 x.out <- setx(z.out)
@ 
Simulating quantities of interest from the posterior distribution given 
\texttt{x.out}.
<<Examples.sim>>=
 s.out1 <- sim(z.out, x = x.out)
@ 
<<Examples.summary.sim>>= 
summary(s.out1)
@ 
\item {Simulating First Differences} \\
Set explanatory variables to their default(mean/mode) values, with high
(80th percentile) and low (20th percentile) liquidity ratio (\texttt{quant}):

<<FirstDifferences.setx>>=
 x.high <- setx(z.out, quant = quantile(tobin$quant, prob = 0.8))
 x.low <- setx(z.out, quant = quantile(tobin$quant, prob = 0.2))
@ 
Estimating the first difference for the effect of
high versus low liquidity ratio on duration(\texttt{durable}):
<<FirstDifferences.sim>>=
 s.out2 <- sim(z.out, x = x.high, x1 = x.low)
@ 
<<FirstDifferences.sim.summary>>= 
summary(s.out2)
@ 
\end{enumerate} 

\subsubsection{Model}
\begin{itemize} 
\item Let $Y_i^*$ be a latent dependent variable which is distributed with
\emph{stochastic} component
\begin{eqnarray*}
Y_i^* & \sim & \textrm{Normal}(\mu_i, \sigma^2) \\
\end{eqnarray*}
where $\mu_i$ is a vector means and $\sigma^2$ is a scalar variance
parameter.  $Y_i^*$ is not directly observed, however.  Rather we
observed $Y_i$ which is defined as:  
\begin{equation*}
Y_i = \left\{
\begin{array}{lcl}
Y_i^*  &\textrm{if} & c <Y_i^* \\
c    &\textrm{if} & c \ge Y_i^* 
\end{array}\right.
\end{equation*}
where $c$ is the lower bound below which $Y_i^*$ is censored.

\item The \emph{systematic component} is given by
\begin{eqnarray*}
\mu_{i} &=& x_{i} \beta,
\end{eqnarray*}
where $x_{i}$ is the vector of $k$ explanatory variables for
observation $i$ and $\beta$ is the vector of coefficients.
\end{itemize}

\subsubsection{Quantities of Interest}

\begin{itemize}
\item The expected values (\texttt{qi\$ev}) for the tobit regression
model are the same as the expected value of $Y*$:  
\begin{equation*}
E(Y^* | X) = \mu_{i} = x_{i} \beta
\end{equation*}

\item The first difference (\texttt{qi\$fd}) for the tobit regression
model is defined as
\begin{eqnarray*}
\text{FD}=E(Y^* \mid x_{1}) - E(Y^* \mid x).
\end{eqnarray*}

\item In conditional prediction models, the average expected treatment effect
(\texttt{qi\$att.ev}) for the treatment group is
\begin{eqnarray*}
\frac{1}{\sum t_{i}}\sum_{i:t_{i}=1}[E[Y^*_{i}(t_{i}=1)]-E[Y^*_{i}(t_{i}=0)]],
\end{eqnarray*}
where $t_{i}$ is a binary explanatory variable defining the treatment
($t_{i}=1$) and control ($t_{i}=0$) groups. 

\end{itemize}

\subsubsection{Output Values}

The output of each Zelig command contains useful information which you may
view. For example, if you run:
\begin{verbatim}
z.out <- zelig(y ~ x, model = "tobit.bayes", data)
\end{verbatim}

\noindent then you may examine the available information in \texttt{z.out} by
using \texttt{names(z.out)}, see the draws from the posterior distribution of
the \texttt{coefficients} by using \texttt{z.out\$coefficients}, and view a 
default summary of information through \texttt{summary(z.out)}. Other elements
available through the \texttt{\$} operator are listed below.

\begin{itemize}
\item From the \texttt{zelig()} output object \texttt{z.out}, you may extract:

\begin{itemize}
\item \texttt{coefficients}: draws from the posterior distributions
of the estimated parameters. The first $k$ columns contain the posterior draws
of the coefficients $\beta$, and the last column contains the posterior draws 
of the variance $\sigma^2$.

   \item {\tt zelig.data}: the input data frame if {\tt save.data = TRUE}.  
\item \texttt{seed}: the random seed used in the model.

\end{itemize}

\item From the \texttt{sim()} output object \texttt{s.out}:

\begin{itemize}
\item \texttt{qi\$ev}: the simulated expected value for the specified
  values of \texttt{x}.

\item \texttt{qi\$fd}: the simulated first difference in the expected
  values given the values specified in \texttt{x} and \texttt{x1}.

\item \texttt{qi\$att.ev}: the simulated average expected treatment
  effect for the treated from conditional prediction models.

\end{itemize}
\end{itemize}



\subsection*{How to Cite}
\input{cites/tobit}
\input{citeZelig}
\subsection*{See also}
The tobit 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:
