emIRT (version 0.0.14)

hierIRT: Hierarchichal IRT estimation via Variational Inference

Description

hierIRT estimates an hierarchical IRT model with two response categories, allowing the use of covariates to help determine ideal point estimates. Estimation is conducted using the variational EM algorithm described in the reference paper below. A special case of this model occurs when time/session is used as the covariate --- this allows legislator ideal points to vary over time with a parametric time trend. Notably, the popular DW-NOMINATE model (Poole and Rosenthal, 1997) is one such example, in which legislator ideal points shift by a constant amount each period, and the error term in the hierarchical model is set to 0. In contrast to other functions in this package, this model does not assume a `rectangular' roll call matrix, and all data are stored in vector form.

Usage

hierIRT(.data, .starts = NULL, .priors = NULL, .control = NULL)

Value

An object of class hierIRT.

means

list, containing several matrices of point estimates for the parameters corresponding to the inputs for the priors. The list should contain the following matrices.

alpha

A (J x 1) matrix of point estimates for the item difficulty parameter \(\alpha_j\).

beta

A (J x 1) matrix of point estimates for the item discrimination parameter \(\beta_j\).

gamma

An (I x D) matrix of point estimates for the group level coefficients \(\gamma_{m}\).

eta

An (I x 1) matrix of point estimates for the ideal point error term \(\eta_n\).

sigma

An (G x 1) matrix of point estimates for the group level variance parameter \(\sigma^2_m\).

x_implied

An (I x 1) matrix of the implied ideal point \(x_i\), calculated as a function of gamma, z, and eta using the point estimates for those parameters.

vars

list, containing several matrices of variance estimates for several parameters of interest for diagnostic purposes. Note that these variances are those recovered via variational approximation, and in most cases they are known to be far too small and generally unusable. The list should contain the following matrices:

eta

A (I x 1) matrix of variance estimates for the ideal point noise parameter \(\eta_n\).

gamma

A (G x D x D) cube of covariance estimates for the gamma parameters for each group. Each of the G items is a matrix with a single covariance matrix for the m-th group's D gamma parameters.

beta2

A (J x 2 x 2) cube of covariance estimates for the item parameters \(\alpha_j\) and \(\beta_j\). Each of the J items is a matrix with a single covariance matrix for the j-th item.

runtime

A list of fit results, with elements listed as follows:

iters

integer, number of iterations run.

conv

integer, convergence flag. Will return 1 if threshold reached, and 0 if maximum number of iterations reached.

threads

integer, number of threads used to estimated model.

tolerance

numeric, tolerance threshold for convergence. Identical to thresh argument in input to .control list.

N

A list of counts of various items:

D

integer, number of dimensions (i.e. number of covariates, including intercept).

G

integer, number of groups.

I

integer, number of ideal points.

J

integer, number of items/bill parameters.

L

integer, number of observed votes.

call

Function call used to generate output.

Arguments

.data

a list with the following items:

y

A (L x 1) matrix of observed votes. `1' and `-1' are the yea and nay codes.

i

A (L x 1) integer matrix of indexes of the ideal point i[l] linked to each observed vote l = 0 \(\ldots\) L. Indexes begin at 0 and reach a maximum value of I - 1.

j

A (L x 1) integer matrix of indexes of the bill/item j[l] linked to each observed vote l = 0 \(\ldots\) L. Indexes begin at 0 and reach a maximum value of J - 1.

g

A (I x 1) integer matrix of indexes of the group membership g[i[l]] linked to each ideal point i = 0 \(\ldots\) I. Indexes begin at 0 and reach a maximum value of G - 1.

z

A (I x D) numeric matrix of observed covariates. Rows correspond to ideal points i = 0 \(\ldots\) I. The columns correspond to the D different covariates. Typically, the first column will be an intercept and fixed to 1, while other columns represent ideal point-specific covariates such as session.

.starts

a list containing several matrices of starting values for the parameters. The list should contain the following matrices:

alpha

A (J x 1) matrix of starting values for the item difficulty parameter \(\alpha_j\).

beta

A (J x 1) matrix of starting values for the item discrimination parameter \(\beta_j\).

gamma

An (I x D) matrix of starting values for the group level coefficients \(\gamma_{m}\).

eta

An (I x 1) matrix of starting values for the ideal point error term \(\eta_n\).

sigma

An (G x 1) matrix of starting values for the group level variance parameter \(\sigma^2_m\).

.priors

list, containing several matrices of starting values for the parameters. The list should contain the following matrices:

gamma.mu

A (D x 1) prior means matrix for all group level coefficients \(\gamma_{m}\).

gamma.sigma

A (D x D) prior covariance matrix for all group level coefficients \(\gamma_{m}\).

beta.mu

A (2 x 1) prior means matrix for all bill parameters \(\alpha_j\) and \(\beta_j\).

beta.sigma

A (2 x 2) prior covariance matrix for all bill parameters \(\alpha_j\) and \(\beta_j\).

sigma.v

A (1 x 1) matrix containing the group level variance prior parameter \(\nu_{\sigma}\).

sigma.s

A (1 x 1) matrix containing the group level variance prior parameter \(s^2_{\sigma}\).

.control

list, specifying some control functions for estimation. Options include the following:

threads

integer, indicating number of cores to use. Default is to use a single core, but more can be supported if more speed is desired.

verbose

boolean, indicating whether output during estimation should be verbose or not. Set FALSE by default.

thresh

numeric. Algorithm will run until all parameters correlate at 1 - thresh across consecutive iterations. Set at 1e-6 by default.

maxit

integer. Sets the maximum number of iterations the algorithm can run. Set at 500 by default.

checkfreq

integer. Sets frequency of verbose output by number of iterations. Set at 50 by default.

Author

Kosuke Imai

James Lo

Jonathan Olmsted

References

Variational model is described in Kosuke Imai, James Lo, and Jonathan Olmsted ``Fast Estimation of Ideal Points with Massive Data.'' American Political Science Review, Volume 110, Issue 4, November 2016, pp. 631-656. <DOI:10.1017/S000305541600037X>.

See Also

'dwnom'.

Examples

### Real data example of US Senate 80-110 (not run)
### Based on voteview.com example of DW-NOMINATE (\url{https://voteview.com/})
### We estimate a hierarchical model without noise and a linear time covariate
### This model corresponds very closely to the DW-NOMINATE model

if (FALSE) {
data(dwnom)

## This takes about 10 minutes to run on 8 threads
## You may need to reduce threads depending on what your machine can support
lout <- hierIRT(.data = dwnom$data.in,
                    .starts = dwnom$cur,
                    .priors = dwnom$priors,
                    .control = {list(
                    threads = 8,
                    verbose = TRUE,
                    thresh = 1e-4,
				    maxit=200,
				    checkfreq=1
                        )})

## Bind ideal point estimates back to legislator data
final <- cbind(dwnom$legis, idealpt.hier=lout$means$x_implied)

## These are estimates from DW-NOMINATE as given on the Voteview example
## From file "SL80110C21.DAT"
nomres <- dwnom$nomres

## Merge the DW-NOMINATE estimates to model results by legislator ID
## Check correlation between hierIRT() and DW-NOMINATE scores
res <- merge(final, nomres, by=c("senate","id"),all.x=TRUE,all.y=FALSE)
cor(res$idealpt.hier, res$dwnom1d)

}