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

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

\section{{\tt ei.RxC}: Hierarchical Multinomial-Dirichlet Ecological
  Inference Model for $R \times C$ Tables}\label{ei.RxC}

Given $n$ contingency tables, each with observed marginals (column and
row totals), ecological inference ({\sc ei}) estimates the internal
cell values in each table.  The hierarchical Multinomial-Dirichlet
model estimates cell counts in $R \times C$ tables. The model is
implemented using a nonlinear least squares approximation and, with
bootstrapping for standard errors, had good frequentist properties.

\subsubsection{Syntax}
\begin{verbatim}
> z.out <- zelig(cbind(T0, T1, T2, T3) ~ X0 + X1, 
                 covar = NULL, 
                 model = "ei.RxC", data = mydata)
> x.out <- setx(z.out, fn = NULL)
> s.out <- sim(z.out)
\end{verbatim}

\subsubsection{Inputs}

\begin{itemize}
\item \texttt{T0}, \texttt{T1}, \texttt{T2},\ldots, \texttt{TC}:
  numeric vectors (either counts, or proportions that sum to one for
  each row) containing the column margins of the units to be analyzed.

\item \texttt{X0}, {\tt X1}, {\tt X2},\ldots,{\tt XR}: numeric vectors
  (either counts, or proportions that sum to one for each row)
  containing the row margins of the units to be analyzed.

\item {\tt covar}: (optional) a covariate that varies across tables,
specified as \verb|covar = ~ Z1|, for example.  (The model only
accepts one covariate.)
\end{itemize}

\subsubsection{Examples}

\begin{enumerate}
 \item Basic examples: No covariate \\
 Attaching the example dataset:
<<ExampleNoCov.data>>= 
  data(Weimar)
@
Estimating the model:
<<ExampleNoCov.zelig>>=
 z.out <- zelig(cbind(Nazi, Government, Communists, FarRight, Other) ~  
                shareunemployed + shareblue + sharewhite + shareself + 
                sharedomestic, model = "ei.RxC", data = Weimar)
 summary(z.out)
@ 

Estimate fractions of different social groups that support political parties:
<<ExampleNoCov.sim>>=
 s.out <- sim(z.out, num = 10)
@ 

Summarizing fractions of different social groups that support political parties:
<<ExampleNoCov.summary>>=
 summary(s.out)
@ 

 \item Example of covariates being present in the model \\

 Using the example dataset Weimar and estimating the model
<<ExampleCov.zelig>>=
 z.out <- zelig(cbind(Nazi, Government, Communists, FarRight, Other) ~  
                shareunemployed + shareblue + sharewhite + shareself + 
                sharedomestic,
                covar = ~ shareprotestants, 
                model = "ei.RxC", data = Weimar)
 summary(z.out)
@ 

Set the covariate to its default (mean/median) value

<<ExampleCov.setx>>=
 x.out <- setx(z.out)
@ 

Estimate fractions of different social groups that support political parties:

\begin{verbatim}
> s.out <- sim(z.out, num = 100) 
\end{verbatim}

Summarizing fractions of different social groups that support political parties:
\begin{verbatim}
> s.out <- summary(s.out) 
\end{verbatim}

\end{enumerate}

\clearpage

\subsubsection{Model}
Consider the following $5 \times 5$ contingency table for the voting
patterns in Weimar Germany.  For each geographical unit $i$ ($i = 1,
\dots, p$), the marginals $T_{1i}$,\dots, $T_{Ci}$, $X_{1i}$,\dots,
$X_{Ri}$ are known for each of the $p$ electoral precincts, and we
would like to estimate ($\beta_i^{rc}, r=1,\dots,R, c=1,\dots,C-1$)
which are the fractions of people in social class $r$ who vote for
party $c$, for all $r$ and $c$.
\begin{table}[!h]
  \begin{center}
    \begin{tabular}{l|ccccc|c}
      & Nazi  & Government & Communists & Far Right & Other         \\
      \hline
      Unemployed & $\beta_{11}^{i}$  & $\beta_{12}^{i}$ & $\beta_{13}^{i}$  & $\beta_{14}^{i}$  & $1-\sum_{c=1}^4 \beta_{1c}^i$ & $X_1^i$   \\
      Blue  & $\beta_{21}^{i}$  & $\beta_{22}^{i}$ & $\beta_{23}^{i}$  & $\beta_{24}^{i}$  & $1-\sum_{c=1}^4 \beta_{2c}^i$ & $X_2^i$   \\
      White  & $\beta_{31}^{i}$  & $\beta_{32}^{i}$ & $\beta_{33}^{i}$  & $\beta_{34}^{i}$  & $1-\sum_{c=1}^4 \beta_{3c}^i$ & $X_3^i$   \\
      Self  & $\beta_{41}^{i}$  & $\beta_{42}^{i}$ & $\beta_{43}^{i}$  & $\beta_{44}^{i}$  & $1-\sum_{c=1}^4 \beta_{4c}^i$ & $X_4^i$   \\
      Domestic  & $\beta_{51}^{i}$  & $\beta_{52}^{i}$ & $\beta_{53}^{i}$  & $\beta_{54}^{i}$  & $1-\sum_{c=1}^4 \beta_{5c}^i$ & $X_5^i$   \\
      \hline
      & $T_{1i}$ & $T_{2i}$  & $T_{3i}$      & $T_{4i}$  & $1-\sum_{c=1}^4 \beta_{ci}$
    \end{tabular}
  \end{center}
\end{table}

\noindent 
The marginal values $X_{1i},\dots,X_{Ri}$, $T_{1i},\dots,T_{Ci}$ may be
observed as counts or fractions.

Let $T_i^{'}=(T_{1i}^{'},T_{2i}^{'},\dots,T_{Ci}^{'})$ be the number
of voting age persons who turn out to vote for different parties.
There are three levels of hierarchy in the 
Multinomial-Dirichlet {\sc ei} model.  At the first stage, we model
the data as:
\begin{itemize}

\item The \emph{stochastic component} is described $T_i^{'}$ which
follows a multinomial distribution: 
\begin{eqnarray*}
T_i^{'} &\sim & \textrm{Multinomial}(\Theta_{1i},\dots,\Theta_{Ci})
\end{eqnarray*}

\item The \emph{systematic components} are
\begin{eqnarray*}
\Theta_{ci}=\sum_{r=1}^{R}\beta_{rc}^{i}X_{ri} & \textrm{for} &  c=1,\dots,C
\end{eqnarray*}

\end{itemize}

At the second stage, we use an optional covariate to model
$\Theta_{ci}$'s and $\beta_{qrc}^{i}$: 
\begin{itemize}
\item The \emph{stochastic component} is described by
$\beta_{r}^{i}=(\beta_{r1},\beta_{r2},\dots,\beta_{r,C-1})$ for 
  $i=1,\dots,,p$ and $r=1,\dots,R$,  which follows a Dirichlet distribution:

  \begin{eqnarray*}
    \beta_r^{i}  &\sim & \textrm{Dirichlet}(\alpha_{r1}^{i},\dots,\alpha_{rc}^{i})
  \end{eqnarray*}

\item The \emph{systematic components} are 
\begin{eqnarray*}
  \alpha_{rc}^{i}=\frac{d_{r}exp(\gamma_{rc}+\delta_{rc}Z_{i})}{d_r(1+\sum_{j=1}^{C-1}exp(\gamma_{rj}+\delta_{rj}Z_i))} = \frac{exp(\gamma_{rc}+\delta_{rc}Z_i)}{1+\sum_{j=1}^{C-1}exp(\gamma_{rj}+\delta_{rj}Z_i)} 
\end{eqnarray*}
for $i=1, \dots,p$, $r=1,\dots,R$, and $c=1, \dots, C-1$.

In the third stage, we assume that the regression parameters (the
$\gamma_{rc}$'s and $\delta_{rc}$'s) are \emph{a priori} independent,
and put a flat prior on these regression parameters.  The parameters
$d_{r}$ for $r=1,\dots,R$ are assumed to follow exponential distributions with
mean $\frac{1}{\lambda}$.
\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(cbind(T0, T1, T2) ~ X0 + X1 + X2, 
          model = "ei.RxC", data = mydata)
\end{verbatim}

\noindent then you may examine the available information in
\texttt{z.out} by using \texttt{names(z.out)}.  For example,

\begin{itemize}
\item From the \texttt{zelig()} output object
  \texttt{z.out\$coefficients} are the estimates of $\gamma_{ij}$ (and
  also $\delta_{ij}$, if covariates are present). The parameters are
  returned as a single vector of length $R\times (C-1)$. If there is a
  covariate, $\delta$ is concatenated to it.

\item From the \texttt{sim()} output object, you may extract the
  parameters $\beta_{ij}$ corresponding to the estimated fractions of
  different social groups that support different political parties, by
  using \texttt{s.out\$qi\$ev}.  For each precinct, that will be a
  matrix with dimensions: simulations $\times R \times C$. \\ 
  \texttt{summary(s.out)} will give you the nationwide aggregate parameters.
\end{itemize}

\subsection*{How to Cite}
\input{cites/ei.RxC}
\input{citeZelig}
\subsection*{See also}
For more information please see \cite{RosJiaKin01}
\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:
