\SweaveOpts{results=hide, prefix.string=vigpics/eiHier}
\include{zinput}
%\VignetteIndexEntry{Hierarchical Ecological Inference Model for 2x2 tables}
%\VignetteDepends{Zelig}
%\VignetteKeyWords{model,ecological, two contingency tables, Gibbs sampling}
%\VignettePackage{Zelig}
\begin{document}
\nobibliography*
<<beforepkgs, echo=FALSE>>=
 before=search()
@

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

%\SweaveInput{ei.dynamic}
\section{{\tt ei.hier}: Hierarchical Ecological Inference Model for
$2 \times 2$ Tables} \label{ei.hier}

Given contingency tables with observed marginals, ecological inference
({\sc ei}) models estimate each internal cell value for each table.
The hierarchical {\sc ei} model estimates a Bayesian model for $2
\times 2$ tables.  The model is implemented using a Markov Chain Monte
Carlo algorithm (via a combination of slice and Gibbs sampling).  
For a Bayesian implementation of {\sc ei} that accounts for temporal
dependence, see Quinn's dynamic {\sc ei} model (\Sref{ei.dynamic}).
For contingency tables larger than
2 rows by 2 columns, see R$\times$C {\sc ei} (\Sref{eiRxC}). 

\subsubsection{Syntax}
\begin{verbatim}
> z.out <- zelig(cbind(t0, t1) ~ x0 + x1, N = NULL, 
                 model = "MCMCei.hier", data = mydata)
> x.out <- setx(z.out, fn = NULL, cond = TRUE)
> s.out <- sim(z.out, x = x.out)
\end{verbatim}

\subsubsection{Inputs}

\begin{itemize}
\item \texttt{t0}, {\tt t1}: numeric vectors (either counts or
proportions) containing the column margins of the units to be
analyzed.

\item \texttt{x0}, {\tt x1}: numeric vectors (either counts or
proportions) containing the row margins of the units to be
analyzed.

\item \texttt{N}: total counts per contingency table (unit).  If
\texttt{t0},\texttt{t1}, \texttt{x0} and \texttt{x1} are proportions,
you must specify \texttt{N}. 

\end{itemize}

\subsubsection{Additional Inputs}

In addition, {\tt zelig()} accepts the following additional inputs for
\texttt{ei.hier} to monitor the convergence of the Markov chain:

\begin{itemize}
\item \texttt{burnin}: number of the initial MCMC iterations to be 
 discarded (defaults to 5,000).

\item \texttt{mcmc}: number of the MCMC iterations after burnin
(defaults to 50,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{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. 

\end{itemize}

\noindent The model also accepts the following additional arguments to specify 
 prior parameters used in the model:

\begin{itemize}
\item \texttt{m0}: prior mean of $\mu_{0}$ (defaults to 0).

\item \texttt{M0}: prior variance of $\mu_{0}$ (defaults to 2.287656).

\item \texttt{m1}: prior mean of $\mu_{1}$ (defaults to 0).
 
\item \texttt{M1}: prior variance of $\mu_{1}$ (defaults to 2.287656).

\item \texttt{a0}: $a_{0}/2$ is the shape parameter for the Inverse Gamma
prior on $\sigma_{0}^{2}$ (defaults to 0.825).

\item \texttt{b0}: $b_{0}/2$ is the scale parameter for the Inverse Gamma
prior on $\sigma_{0}^{2}$ (defaults to 0.0105).

\item \texttt{a1}: $a_{1}/2$ is the shape parameter for the Inverse Gamma
prior on $\sigma_{1}^{2}$ (defaults to 0.825).

\item \texttt{b1}: $b_{1}/2$ is the scale parameter for the Inverse Gamma
prior on $\sigma_{1}^{2}$ (defaults to 0.0105).
\end{itemize}

\noindent Users may wish to refer to \texttt{help(MCMChierEI)} for more information.

\input{coda_diag}

\subsubsection{Examples}

\begin{enumerate}
 \item Basic examples \\
 Attaching the example dataset:
<<Examples.data>>=
 data(eidat)
 eidat
@ 
Estimating the model using \texttt{ei.hier}:
<<Examples.zelig>>=
z.out <- zelig(cbind(t0, t1) ~ x0 + x1, model = "ei.hier", 
                 data = eidat, mcmc = 40000, thin = 10, burnin = 10000, 
                 verbose = TRUE)
 summary(z.out)
@ 

Setting values for in-sample simulations given marginal values 
of {\tt x0}, {\tt x1}, {\tt t0}, and {\tt t1}:
<<Examples.setx>>=
 x.out <- setx(z.out, fn = NULL, cond = TRUE)
@ 

In-sample simulations from the posterior distribution:
<<Examples.sim>>=
 s.out <- sim(z.out, x = x.out)
@ 
Summarizing in-sample simulations at aggregate level 
weighted by the count in each unit:
<<Examples.summary>>=
summary(s.out)
@ 
Summarizing in-sample simulations at unit level for the first 5 units:
<<Examples.summary.subset>>=
summary(s.out, subset = 1:5)
@ 

\end{enumerate}
\clearpage
\subsubsection{Model}
Consider the following $2 \times 2$ contingency table for the racial
voting example.  For each geographical unit $i = 1, \dots, p$, the
marginals $t_i^0$, $t_i^1$, $x_i^0$, and $x_i^1$ are known, and we
would like to estimate $n_i^{00}$, $n_i^{01}$, $n_i^{10}$, and $n_i^{11}$.

\begin{table}[!h]
  \begin{center}
    \begin{tabular}{l|cc|c}
      & No Vote  & Vote &         \\
      \hline
      Black & $n_i^{00}$  & $n_i^{01}$ & $x_i^0$   \\
      White & $n_i^{10}$  & $n_i^{11}$ & $x_i^1$ \\
      \hline
      & $t_i^0$ & $t_i^1$ & $N_i$         
    \end{tabular}
  \end{center}
\end{table}

\noindent The marginal values $x_{i}^0$, $x_{i}^1$, $t_i^0$,
$t_i^1$ are observed as either counts or fractions. If fractions, the
counts can be obtained by multiplying by the total counts per table
$N_i = n_i^{00} + n_i^{01} + n_i^{10} + n_i^{11}$ and rounding to the
nearest integer.  Although there are four internal cells, only two
unknowns are modeled since $n_i^{01} = x_i^0 - n_{i}^{00}$ and
$n_{i}^{11} = s_i^1 - n_{i}^{10}$.

The hierarchical Bayesian model for ecological inference in $2 \times
2$ is illustrated as following:
\begin{itemize}
\item The \emph{stochastic component} of the model assumes that
\begin{eqnarray*}
n_{i}^{00}\mid x_i^0,\beta_i^b &\sim& \textrm{Binomial}\left(
x_i^0, \beta_i^b\right)  ,\\
n_{i}^{10} \mid x_i^1, \beta_i^w &\sim& \textrm{Binomial}\left(
x_i^1, \beta_i^w\right)  \\
\end{eqnarray*}
where $\beta_{i}^{b}$ is the fraction of the black voters who vote
and $\beta_i^w$ is the fraction of the white voters who vote. $\beta_i^b$ 
and $\beta_i^w$ as well as their aggregate level summaries are the focus
of inference.

\item The \emph{systematic component} is 
\begin{eqnarray*}
\beta_i^b &=& \frac{\exp\theta_i^0}{1 - \exp\theta_i^0} \\
\beta_i^w &=& \frac{\exp\theta_i^1}{1 - \exp\theta_i^1} 
\end{eqnarray*}
The logit transformations of $\beta^b_i$ and $\beta^w_i$, $\theta_{i}^0$, 
and $\theta_i^1$ now take value on the real line. (Future versions may allow
$\beta_{i}^{b}$ and $\beta_{i}^{w}$ to be functions of observed covariates.)

\item The \emph{priors} for $\theta_{i}^0$ and $\theta_{i}^1$
 are given by
\begin{eqnarray*}
\theta_{i}^{0}   \mid\mu_{0},\sigma_{0}^{2}&\sim&\textrm{Normal}\left(  \mu
_{0},\sigma_{0}^{2}\right),\\
\theta_{i}^{1}  \mid\mu_{1},\sigma_{1}^{2}&\sim&\textrm{Normal}\left(  \mu
_{1},\sigma_{1}^{2}\right)  
\end{eqnarray*}
where $\mu_{0}$ and $\mu_{1}$ are the means, and $\sigma_{0}^{2}$ 
and $\sigma_{1}^{2}$ are the variances of the two corresponding 
(independent) normal distributions.

\item The \emph{hyperpriors} for $\mu_{0}$ and $\mu_{1}$ are given by
\begin{eqnarray*}
\mu_{0}    &\sim& \textrm{Normal} \left(  m_{0}, M_{0} \right)  ,\\
\mu_{1}    &\sim& \textrm{Normal} \left(  m_{1}, M_{1} \right)  ,
\end{eqnarray*}
where $m_{0}$ and $m_{1}$ are the means of the (independent) normal
distributions while $M_{0}$ and $M_{1}$ are the variances.

\item The \emph{hyperpriors} for $\sigma_{0}^{2}$ and $\sigma_{1}^{2}$ are
given by
\begin{eqnarray*}
\sigma_{0}^{2}& \sim& \textrm{Inverse Gamma}\left(\frac{a_{0}}{2},\frac{b_{0}}{2}\right),\\
\sigma_{1}^{2}& \sim& \textrm{Inverse Gamma}\left(\frac{a_{1}}{2},\frac{b_{1}}{2}\right),
\end{eqnarray*}
where $a_{0}/2$ and $a_{1}/2$ are the shape parameters of the
(independent) Gamma distributions while $b_{0}/2$ and $b_{1}/2$ are
the scale parameters. 

The default hyperpriors for $\mu_{0},$ $\mu_{1}$, $\sigma_{0}^{2},$
and $\sigma_{1}^{2}$ are chosen such that the prior distributions of
$\beta^b$ and $\beta^w$ are flat.

\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 <- (cbind(t0, t1) ~ x0 + x1, N = NULL, 
          model = "ei.hier", data = mydata)
\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 quantities of interest 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 parameters.
   \item {\tt zelig.data}: the input data frame if {\tt save.data = TRUE}.  
\item \texttt{N}: the total counts when the inputs are fractions.
\item \texttt{seed}: the random seed used in the model.
\end{itemize}

\item From \texttt{summary(z.out)}, you may extract:
\begin{itemize}
\item \texttt{summary}: a matrix containing the summary information of the 
posterior estimation of $\beta^b_i$ and$\beta^w_i$ for each unit and
the parameters $\mu_0$, $\mu_1$, $\sigma_1$ and $\sigma_2$ based on
the posterior distribution.  The first $p$ rows correspond to
$\beta_i^b$, $i=1,\ldots p$, the row names are in the form of
\texttt{p0table}$i$. The $(p+1)$-th to the $2p$-th rows correspond to
$\beta_i^w$, $i=1,\ldots,p$. The row names are in the form of
\texttt{p1table}$i$. The last four rows contain information about
$\mu_0$, $\mu_1$, $\sigma_0^2$ and $\sigma_1^2$, the prior means and
variances of $\theta_0$ and $\theta_1$. 
\end{itemize}
\item From the \texttt{sim()} output object \texttt{s.out}, you may
extract quantities of interest arranged as arrays indexed by
simulation $\times$ column $\times$ row $\times$ observation, where
column and row refer to the column dimension and the row dimension of
the contingency table, respectively. In this model, only $2 \times 2$
contingency tables are analyzed, hence column$=2$ and row$=2$ in all
cases. Available quantities are:
\begin{itemize}
\item \texttt{qi\$ev}: the simulated expected values of each internal cell
given the observed marginals. 
\item \texttt{qi\$pr}: the simulated expected values of each internal cell 
given the observed marginals.  
\end{itemize}

\end{itemize}

\subsection*{How to Cite}
\input{cites/ei.hier}
\input{citeZelig}
\subsection*{See also}
\emph{ei.hier} function 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}. Sample date are adapted from \cite{MarQui05}.

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