\SweaveOpts{results=hide, prefix.string=vigpics/mlogitBayes}
\include{zinput}
%\VignetteIndexEntry{Bayesian Multinomial Logistic Regression for Dependent Variables with Unordered Categorical Values}
%\VignetteDepends{Zelig, MCMCpack}
%\VignetteKeyWords{model, bayes,multinomial, logistic regression}
%\VignettePackage{Zelig}
\begin{document}
\nobibliography*
<<beforepkgs, echo=FALSE>>=
 before=search()
@

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

\section{\texttt{mlogit.bayes}: Bayesian Multinomial Logistic
Regression}

\label{mlogit.bayes}

Use Bayesian multinomial logistic regression to model unordered
categorical variables.  The dependent variable may be in the format of
either character strings or integer values.  The model is estimated
via a random walk Metropolis algorithm or a slice sampler.  See
\Sref{mlogit} for the maximum-likelihood estimation of this model.

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

\subsubsection{Additional Inputs}

{\tt zelig()} accepts the following arguments for {\tt mlogit.bayes}:
\begin{itemize}
\item \texttt{baseline}: either a character string or numeric value
(equal to one of the observed values in the dependent variable)
specifying a baseline category.  The default value is \texttt{NA}
which sets the baseline to the first alphabetical or numerical unique
value of the dependent variable.
\end{itemize}

The model accepts the following additional arguments to monitor the
Markov chains:  
\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{mcmc.method}: either {\tt "MH"} or {\tt "slice"}, specifying whether
to use Metropolis Algorithm or slice sampler. The default value is
\texttt{"MH"}.

\item \texttt{tune}: tuning parameter for the Metropolis-Hasting step,
either a scalar or a numeric vector (for $k$ coefficients, enter a $k$
vector).  The tuning parameter should be set such that the acceptance 
rate is satisfactory (between 0.2 and 0.5). The default value is 1.1.

\item \texttt{verbose}: defaults to \texttt{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 a vector (for $k$ coefficients, enter a $k$
vector). The default is \texttt{NA} where the maximum likelihood
estimates are used as the starting values.

\end{itemize}

Use the following arguments to specify the priors for the model:  
\begin{itemize}
\item \texttt{b0}: prior mean for the coefficients, either a scalar or
vector.  If a scalar, 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, 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(MCMCmnl)} for more 
information.

\input{coda_diag}

\subsubsection{Examples}

\begin{enumerate}
\item {Basic Example} \\
Attaching the sample dataset:
<<BasicExample.data>>=
 data(mexico)
@ 
Estimating multinomial logistics regression using \texttt{mlogit.bayes}:
<<BasicExample.zelig>>=
 z.out <- zelig(vote88 ~ pristr + othcok + othsocok, model = "mlogit.bayes", 
               data = mexico)
@ 
Checking for convergence before summarizing the estimates:
<<BasicExample.heidel>>=
 heidel.diag(z.out$coefficients)
@ 
<<BasicExample.raftery>>= 
raftery.diag(z.out$coefficients)
@ 
<<BasicExample.summary>>= 
summary(z.out)
@ \end{verbatim} 
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 the probabilities of
voting different candidates when \texttt{pristr} (the strength of the
PRI) is set to be weak (equal to 1) versus strong (equal to 3)
while all the other variables held at their default values.
<<FirstDifferences.setx>>=
 x.weak <- setx(z.out, pristr = 1)
 x.strong <- setx(z.out, pristr = 3)
@ 
<<FirstDifferences.sim>>= 
s.out2 <- sim(z.out, x = x.strong, x1 = x.weak)
@ 
<<FirstDifferences.summary>>= 
summary(s.out2)
@ 
\end{enumerate}

\subsubsection{Model}

Let $Y_{i}$ be the (unordered) categorical dependent variable for observation 
$i$ which takes an integer values $j=1, \ldots, J$.

\begin{itemize}
\item The \emph{stochastic component} is given by:
\begin{eqnarray*}
Y_{i} &\sim& \textrm{Multinomial}(Y_i \mid \pi_{ij}).
\end{eqnarray*}
where $\pi_{ij}=\Pr(Y_i=j)$ for $j=1, \ldots, J$.

\item The \emph{systematic component} is given by

\begin{eqnarray*}
\pi_{ij}=\frac{\exp(x_i\beta_j)}{\sum_{k=1}^J \exp(x_i\beta_k)},
\textrm{ for } j=1,\ldots, J-1,
\end{eqnarray*}
where $x_{i}$ is the vector of $k$ explanatory variables for
observation $i$ and $\beta_j$ is the vector of coefficient for
category $j$. Category $J$ is assumed to be the baseline category.

\item The \emph{prior} for $\beta$ is given by
\begin{eqnarray*}
\beta_j \sim \textrm{Normal}_k\left(  b_{0},B_{0}^{-1}\right) 
\textrm{ for } j = 1, \ldots, J-1,
\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 multinomial logistics
 regression model are the predicted probability of belonging to each
 category:
\begin{eqnarray*}
\Pr(Y_i=j)=\pi_{ij}=\frac{\exp(x_i \beta_j)}{\sum_{k=1}^J \exp(x_J
\beta_k)}, \quad \textrm{ for } j=1,\ldots, J-1,
\end{eqnarray*}
and 
\begin{eqnarray*}
\Pr(Y_i=J)=1-\sum_{j=1}^{J-1}\Pr(Y_i=j)
\end{eqnarray*}
given the posterior draws of $\beta_j$ for all categories from the 
MCMC iterations.

\item The predicted values (\texttt{qi\$pr}) are the draws of 
$Y_i$  from a multinomial distribution whose parameters are the expected 
values(\texttt{qi\$ev}) computed based on the posterior draws 
of $\beta$ from the MCMC iterations.

\item The first difference (\texttt{qi\$fd}) in category $j$ for the 
multinomial logistic model is defined as
\begin{eqnarray*}
\text{FD}_j=\Pr(Y_i=j\mid X_{1})-\Pr(Y_i=j\mid X).
\end{eqnarray*}

\item The risk ratio (\texttt{qi\$rr}) in category $j$ is defined as
\begin{eqnarray*}
\text{RR}_j=\Pr(Y_i=j\mid X_{1})\ /\ \Pr(Y_i=j\mid X).
\end{eqnarray*}


\item In conditional prediction models, the average expected treatment effect
(\texttt{qi\$att.ev}) for the treatment group in category $j$ is
\begin{eqnarray*}
\frac{1}{n_j}\sum_{i:t_{i}=1}^{n_j}[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, and $n_j$ is the 
number of treated observations in category $j$.

\item In conditional prediction models, the average predicted treatment effect
(\texttt{qi\$att.pr}) for the treatment group in category $j$ is
\begin{eqnarray*}
\frac{1}{n_j}\sum_{i:t_{i}=1}^{n_j}[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, and $n_j$ is the 
number of treated observations in category $j$.
\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 = "mlogit.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 coefficients $\beta$ for each category except the baseline
category. 

   \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) of 
each of the $J$ categories given the specified values of \texttt{x}.

\item \texttt{qi\$pr}: the simulated predicted values drawn from the 
multinomial distribution defined by the expected values(\texttt{qi\$ev})
given the specified values of \texttt{x}.

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

\item \texttt{qi\$rr}: the simulated risk ratio for the 
expected values of each of the $J$ categories 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/mlogit.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:
