\SweaveOpts{results=hide, prefix.string=vigpics/logitBayes}
\include{zinput}
%\VignetteIndexEntry{Bayesian Logistic Regression for Dichotomous Dependent Variables}
%\VignetteDepends{Zelig, MCMCpack}
%\VignetteKeyWords{model,bayes,dichotomous, Metropolis}
%\VignettePackage{Zelig, MCMCpack}
\begin{document}
\nobibliography*
<<beforepkgs, echo=FALSE>>=
 before=search()
@

<<loadLibrary, echo=F,results=hide>>=
library(Zelig)
@ 
\section{\texttt{logit.bayes}: Bayesian Logistic Regression}

\label{logit.bayes}

Logistic regression specifies a dichotomous dependent variable as a
function of a set of explanatory variables using a random walk
Metropolis algorithm.  For a maximum likelihood implementation, see
\Sref{logit}.  

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

\subsubsection{Additional Inputs}

Use the following arguments to monitor the Markov chain: 
\begin{itemize}
\item \texttt{burnin}: number of the initial MCMC iterations to be 
 discarded (defaults to 1,000). 

\item \texttt{mcmc}: number of the MCMC iterations after burnin
(defaults to 10,000).

\item \texttt{thin}: thinning interval for the Markov chain. Only every 
 \texttt{thin}-th draw from the Markov chain is kept. The value of 
\texttt{mcmc} must be divisible by this value. The default value is 1.

\item \texttt{tune}: Metropolis tuning parameter, either 
a positive scalar or a vector of length $k$, where $k$ is the number
of coefficients. The tuning parameter should be set such that the
acceptance rate of the Metropolis algorithm is satisfactory (typically
between 0.20 and 0.5) before using the posterior density for
inference. The default value is 1.1.

\item \texttt{verbose}: defaults to {\tt FALSE}.  If \texttt{TRUE}, the progress 
 of the sampler (every $10\%$) is printed to the screen.

\item \texttt{seed}: seed for the random number generator.  The
default is \texttt{NA} which corresponds to a random seed of 12345.

\item \texttt{beta.start}: starting values for the Markov 
chain, either a scalar or vector with length equal to the number of
estimated coefficients. The default is \texttt{NA}, such that the maximum
likelihood estimates are used as the starting values.

\end{itemize}

Use the following parameters to specify the model's priors:  
\begin{itemize}
\item \texttt{b0}: prior mean for the coefficients, either a numeric 
vector or a scalar. If a scalar value, that value will
be the prior mean for all the coefficients. The default is 0.

\item \texttt{B0}: prior precision parameter for the coefficients,
either a square matrix (with the dimensions equal to the number of
coefficients) or a scalar. If a scalar value, that value times an
identity matrix will be the prior precision parameter. The default is
0, which leads to an improper prior.

\end{itemize}

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

\input{coda_diag}

\subsubsection{Examples}

\begin{enumerate}
\item {Basic Example} \\
Attaching the sample  dataset:
<<BasicExample.data>>=
 data(turnout)
@ 
Estimating the logistic regression using \texttt{logit.bayes}:
<<BasicExample.zelig>>=
 z.out <- zelig(vote ~ race + educate, model = "logit.bayes",
                  data = turnout, verbose = TRUE)
@ 
Convergence diagnostics before summarizing the estimates:
<<BasicExample.geweke>>=
 geweke.diag(z.out$coefficients)
@
<<BasicExample.heidel>>=
 heidel.diag(z.out$coefficients)
@ 
<<BasicExample.raftery>>= 
 raftery.diag(z.out$coefficients)
@ 
<<BasicExample.summary.zout>>= 
summary(z.out)
@ 
Setting values for the explanatory variables to their sample averages:
<<BasicExample.setx>>=
 x.out <- setx(z.out)
@ 
Simulating quantities of interest from the posterior distribution given 
\texttt{x.out}.
<<BasicExample.sim>>=
 s.out1 <- sim(z.out, x = x.out)
@ 
<<BasicExample.summary.sim>>= 
summary(s.out1)
@ 
\item {Simulating First Differences} \\
Estimating the first difference (and risk ratio) in individual's probability of
voting  when education is set to be low (25th percentile) versus 
high (75th percentile) while all the other variables held at their 
default values.
<<FirstDifferences.setx.high>>=
 x.high <- setx(z.out, educate = quantile(turnout$educate, prob = 0.75))
@ 
<<FirstDifferences.setx.low>>= 
x.low <- setx(z.out, educate = quantile(turnout$educate, prob = 0.25))
@ 
<<FirstDifferences.sim>>= 
s.out2 <- sim(z.out, x = x.high, x1 = x.low)
@ 
<<FirstDifferences.summary>>= 
summary(s.out2)
@ 
\end{enumerate}

\subsubsection{Model}

Let $Y_{i}$ be the binary dependent variable for observation $i$ which takes
the value of either 0 or 1.

\begin{itemize}
\item The \emph{stochastic component} is given by
\begin{eqnarray*}
Y_{i}  &  \sim & \rm{Bernoulli}(\pi_{i})\\
&  = & \pi_{i}^{Y_{i}}(1-\pi_{i})^{1-Y_{i}},
\end{eqnarray*}
where $\pi_{i}=\Pr(Y_{i}=1)$.

\item The \emph{systematic component} is given by
\begin{eqnarray*}
\pi_{i}= \frac{1}{1+\exp(-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.

\item The \emph{prior} for $\beta$ is given by
\begin{eqnarray*}
\beta \sim \textrm{Normal}_k \left(  b_{0},B_{0}^{-1}\right)
\end{eqnarray*}
where $b_{0}$ is the vector of means for the $k$ explanatory variables
and $B_{0}$ is the $k \times k$ precision matrix (the inverse of a
variance-covariance matrix).
\end{itemize}

\subsubsection{Quantities of Interest}

\begin{itemize}
\item The expected values (\texttt{qi\$ev}) for the logit model are
simulations of the predicted probability of a success:
\begin{eqnarray*}
E(Y) = \pi_{i}= \frac{1}{1 + \exp(-x_{i} \beta)},
\end{eqnarray*}
given the posterior draws of $\beta$ from the MCMC iterations.

\item The predicted values (\texttt{qi\$pr}) are draws from the Bernoulli
distribution with mean equal to the simulated expected value $\pi_{i}$.

\item The first difference (\texttt{qi\$fd}) for the logit model is defined
as
\begin{eqnarray*}
\text{FD}=\Pr(Y=1\mid X_{1})-\Pr(Y=1\mid X).
\end{eqnarray*}

\item The risk ratio (\texttt{qi\$rr})is defined as
\begin{eqnarray*}
\text{RR}=\Pr(Y=1\mid X_{1})\ /\ \Pr(Y=1\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}[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. 

\item In conditional prediction models, the average predicted treatment effect
(\texttt{qi\$att.pr}) for the treatment group is
\begin{eqnarray*}
\frac{1}{\sum t_{i}}\sum_{i:t_{i}=1}[Y_{i}(t_{i}=1)-\widehat{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 = "logit.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 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.
   \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 values(probabilities) for the specified
values of \texttt{x}.

\item \texttt{qi\$pr}: the simulated predicted values for the specified values
of \texttt{x}.

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

\item \texttt{qi\$rr}: the simulated risk ratio for the expected values
simulated from \texttt{x} and \texttt{x1}.

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

\item \texttt{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/logit.bayes}
\input{citeZelig}
\subsection*{See also}
Bayesian logistic regression is part of the MCMCpack library by Andrew D. Martin and Kevin M. Quinn \citep{MarQui05}. The convergence diagnostics are part of the CODA library by Martyn Plummer, Nicky Best, Kate Cowles, and Karen Vines \citep{PluBesCowVin05}.

\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:
