\SweaveOpts{results=hide, prefix.string=vigpics/irtkd}
\include{zinput}
%\VignetteIndexEntry{K-Dimensional Item Response Model}
%\VignetteDepends{Zelig, MCMCpack}
%\VignetteKeyWords{model,item response,dichotomous, Gibbs}
%\VignettePackage{Zelig, stats}
\begin{document}
\nobibliography*
<<beforepkgs, echo=FALSE>>=
 before=search()
@

<<loadLibrary, echo=F,results=hide>>=
library(Zelig)
@ 
\section{\texttt{irtkd}: $k$-Dimensional Item Response Theory Model}

\label{irtkd}

Given several observed dependent variables and an unobserved
explanatory variable, item response theory estimates the latent
variable (ideal points).  The model is estimated using the Markov
Chain Monte Carlo algorithm, via a combination of Gibbs sampling and
data augmentation.  Use this model if you believe that the ideal
points lie in $k$ dimensions.  See the unidimensional item response
model (\Sref{irt1d}) for a single hypothesized latent variable. 

\subsubsection{Syntax}
\begin{verbatim}
> z.out <- zelig(cbind(Y1, Y2, Y3) ~ NULL, dimensions = 1, 
                 model = "irtkd", data = mydata)
\end{verbatim}

\subsubsection{Inputs}
\texttt{irtkd} accepts the following arguments:
\begin{itemize}
\item \texttt{Y1}, {\tt Y2}, and \texttt{Y3}: \texttt{Y1} contains the items for 
subject ``Y1'', \texttt{Y2} contains the items for subject ``Y2'', and so on. 

\item \texttt{dimensions}: The number of dimensions in the latent space. The 
default is 1.

\end{itemize}

\subsubsection{Additional arguments}

\texttt{irtkd} accepts the following additional arguments for model specification:
\begin{itemize}
\item \texttt{item.constraints}: a list of lists specifying possible 
simple equality or inequality constraints on the item parameters.
A typical entry has one of the following forms: 
\begin{itemize}

\item {\tt varname = list()}: by default, no constraints are
imposed.

\item \texttt{varname = list(d, c)}: constrains the
$d$th item parameter for the item named \texttt{varname} to be equal
to \texttt{c}.

\item \texttt{varname = list(d, "+")}: constrains the
$d$th item parameter for the item  named \texttt{varname} to be positive;

\item \texttt{varname = list(d, "-")}: constrains the
$d$th item parameter for the item named \texttt{varname} to be negative.
\end{itemize} 
In a $k$ dimensional model, the first item parameter for item $i$ is
the difficulty parameter $\alpha_i$, the second item parameter is the
discrimination parameter on dimension 1, $(\beta_{i,1})$, the third
item parameter is the discrimination parameter on dimension 2,
$(\beta_{i,2}),\ldots$, and $(k+1)$th item parameter is the
discrimination parameter on dimension $k$, $(\beta_{i,k})$. The item
difficulty parameter($\alpha$) should not be constrained in general.
\end{itemize}

\noindent \texttt{irtkd} accepts the following additional arguments 
to monitor the sampling scheme for 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 20,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. The default 
is \texttt{FALSE}.

   \item {\tt zelig.data}: the input data frame if {\tt save.data = TRUE}.  

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

\item \texttt{alphabeta.start}: starting values for the item parameters
$\alpha$ and $\beta$, either a scalar or a $(k+1) \times items$
matrix. If it is a scalar, then that value will be the starting value
for all the elements of \texttt{alphabeta.start}. The default is
\texttt{NA} which sets the starting values for the unconstrained
elements based on a series of proportional odds logistic
regressions. The starting values for the inequality constrained
elements are set to be either 1.0 or -1.0 depending on the nature of
the constraints.

\item \texttt{store.item}: defaults to {\tt FALSE}.  If {\tt TRUE} stores the
posterior draws of the item parameters.  (For a large number of draws or
a large number observations, this may take a lot of memory.)  

\item \texttt{store.ability}: defaults to {\tt TRUE}, storing the
posterior draws of the subject abilities.  (For a large number of draws or
a large number observations, this may take a lot of memory.) 

\item \texttt{drop.constant.items}: defaults to {\tt TRUE}, dropping
items with no variation before fitting the model.  
\end{itemize}

\noindent \texttt{irtkd} accepts the following additional arguments to 
specify prior parameters used in the model:

\begin{itemize}

\item \texttt{b0}: prior mean of $(\alpha, \beta)$, either as a scalar or
a vector of compatible length. If a scalar value, then the prior means
for both $\alpha$ and $\beta$ will be set to that value. The default
is 0.

\item \texttt{B0}: prior precision for $(\alpha, \beta)$, either a
scalar or a $(k+1) \times items$ matrix. If a scalar value, the prior
precision will be a blocked diagonal matrix with elements
\texttt{diag(B0,items)}. The prior precision is assumed to be same for
all the items. The default is 0.25.

\end{itemize}

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

\input{coda_diag}

\subsubsection{Examples}

\begin{enumerate}
\item {Basic Example} \\
Attaching the sample  dataset:
<<BasicExample.data>>= 
 data(SupremeCourt)
names(SupremeCourt) <- c("Rehnquist","Stevens","OConnor","Scalia",
                         "Kennedy","Souter","Thomas","Ginsburg","Breyer")
@ 
Fitting a one-dimensional item response theory model using \texttt{irtkd}:
<<BasicExample.zelig>>= 
 z.out <- zelig(cbind(Rehnquist, Stevens, OConnor, Scalia, Kennedy, Souter, 
                       Thomas, Ginsburg, Breyer) ~ NULL, dimensions = 1,
                 data = SupremeCourt, model = "irtkd", B0 = 0.25, 
                 burnin = 5000, mcmc = 50000, 
                 thin = 10, verbose = TRUE)
@ 

Checking for convergence 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>>= 
summary(z.out)
@  
\end{enumerate} 

\subsubsection{Model} 

Let $Y_i$ be a vector of choices on $J$ items made by subject $i$ for 
$i = 1, \ldots, n$. The choice $Y_{ij}$ is assumed to be 
determined by unobserved utility $Z_{ij}$, which is a function
of subject abilities (ideal points) $\theta_i$ and item parameters
$\alpha_j$ and $\beta_j$,
\begin{eqnarray*}
Z_{ij} &=& -\alpha_j + \beta_j' \theta_i + \epsilon_{ij}.
\end{eqnarray*}
In the $k$-dimensional item response theory model, each subject's ability is 
represented by a $k$-vector, $\theta_i$. Each item has a difficulty 
parameter $\alpha_j$ and a $k$-dimensional discrimination parameter
$\beta_j$. In one-dimensional item response theory model, $k = 1$.

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

The error term in the unobserved utility equation has
a standard normal distribution,
\begin{eqnarray*}
\epsilon_{ij} \sim \textrm{Normal}(0, 1).
\end{eqnarray*}

\item The \emph{systematic component} is given by
\begin{eqnarray*}
\pi_{ij} &=& \Phi(-\alpha_j + \beta_j \theta_i),
\end{eqnarray*}
where $\Phi(\cdot)$ is the cumulative density function of the standard
normal distribution with mean 0 and variance 1, while $\theta_i$
contains the $k$-dimensional subject abilities(ideal points), and
$\alpha_{j}$ and $\beta_j$ are the item parameters. Both subject
abilities and item parameters need to estimated from the model. The
model is identified by placing constraints on the item parameters.

\item The \emph{prior} for $\theta_i$ is given by
\begin{eqnarray*}
\theta_i &\sim& \textrm{Normal}_k(0, I_k)
\end{eqnarray*}

\item The joint \emph{prior} for $\alpha_j$ and $\beta_j$ is given by
\begin{eqnarray*}
(\alpha_j, \beta_j)' &\sim& \textrm{Normal}_{k+1} \left( b_{0_j}, B_{0_j}^{-1}\right)
\end{eqnarray*}
where $b_{0_j}$ is a $(k+1)$-vector of prior mean and $B_{0_j}$ is a $(k+1) 
\times (k+1)$ prior precision matrix which is assumed to be diagonal.

\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(Y1, Y2, Y3) ~ NULL, model = "irtkd", 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 subject abilities(ideal points). If 
\texttt{store.item = TRUE}, the estimated item parameters $\alpha$ and $\beta$
 are also contained in \texttt{coefficients}.

\item \texttt{data}: the name of the input data frame.
\item \texttt{seed}: the random seed used in the model.   

\end{itemize}

\item Since there are no explanatory variables, the \texttt{sim()}
procedure is not applicable for item response models.

\end{itemize}

\subsection*{How to Cite}
\input{cites/irtkd}
\input{citeZelig}
\subsection*{See also}
The $k$ dimensional item-response 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 data 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:
