ideal                  package:pscl                  R Documentation

_a_n_a_l_y_s_i_s _o_f _e_d_u_c_a_t_i_o_n_a_l _t_e_s_t_i_n_g _d_a_t_a _a_n_d _r_o_l_l _c_a_l_l _d_a_t_a _w_i_t_h _I_R_T _m_o_d_e_l_s, _v_i_a _M_a_r_k_o_v
_c_h_a_i_n _M_o_n_t_e _C_a_r_l_o _m_e_t_h_o_d_s

_D_e_s_c_r_i_p_t_i_o_n:

     Analysis of 'rollcall' data via the spatial voting model;
     analogous to fitting educational testing data via an item-response
     model.  Model fitting via Markov chain Monte Carlo (MCMC).

_U_s_a_g_e:

     ideal(object, codes = object$codes,
           dropList = list(codes = "notInLegis", lop = 0),
           d = 1, maxiter = 10000, thin = 100, burnin = 5000,
           impute = FALSE,
           normalize = FALSE,
           meanzero = normalize,
           priors = NULL, startvals = "eigen",
           store.item = FALSE, file = NULL,
           verbose=FALSE)

_A_r_g_u_m_e_n_t_s:

  object: an object of class 'rollcall'

   codes: a 'list' describing the types of voting decisions in the roll
          call matrix (the 'votes' component of the 'rollcall'
          'object'); defaults to  'object$codes', the codes in the
          rollcall object.

dropList: a 'list' (or 'alist') listing voting decisions, legislators
          and/or votes to be dropped from the analysis; see
          'dropRollCall' for details.

       d: numeric, (small) positive integer (defaults to 1).

 maxiter: numeric, positive integer, multiple of 'thin'

    thin: numeric, positive integer, thinning interval used for
          recording MCMC iterations.

  burnin: number of MCMC iterations to run before recording.  The
          iteration numbered 'burnin' will be recorded.  Must be a
          multiple of 'thin'.

  impute: 'logical', whether to treat missing entries of the rollcall
          matrix as missing at random, sampling from the predictive
          density of the missing entries at each MCMC iteration.

normalize: 'logical', impose identification with the constraint that
          the ideal points have mean zero and standard deviation one. 
          This option is only functional for unidimensional models
          (i.e., 'd=1'), and is sufficient to locally identify the
          model parameters in this case; more restrictions are required
          for identification when 'd > 1'. See Details.

meanzero: to be deprecated/ignored; use 'normalize' instead.

  priors: a 'list' of parameters (means and variances) specifying
          normal priors for the legislators' ideal points. The default
          is 'NULL', in which case the normal priors used have mean
          zero and variance 1 for the ideal points (ability parameters)
          and mean zero and variance 100 for the bill parameters (item
          parameters).  If not 'NULL', 'priors' must be a 'list' with
          as many as four named components 'xp, xpv, bp, bpv', where

     '_x_p' a 'n' by 'd' matrix of prior _means_ for the legislators'
          ideal points; or alternatively, a scalar, which will be
          replicated to fill a 'n' by 'd' matrix.

     '_x_p_v' a 'n' by 'd' matrix of prior _precisions_ (inverse
          variances); or alternatively, a scalar, which will be
          replicated to fill a 'n' by 'd' matrix. 

     '_b_p' a 'm' by 'd+1' matrix of prior means for the item parameters
          (with the item difficulty parameter coming last); or
          alternatively, a scalar, which will be replicated to fill a
          'm' by 'd+1' matrix.

     '_b_p_v' a 'm' by 'd+1' matrix of prior precisions for the item
          parameters; or alternatively, a scalar, which will be
          replicated to fill a 'm' by 'd+1' matrix.   None of the
          components should contain 'NA'.  If any of the four possible
          components are not provided, then the corresponding component
          of 'priors' is assigned using the default values described
          above.

startvals: either a string naming a method for generating start values,
          valid options are '"eigen"' (the default) or '"random"'; or a
          'list' containing start values for legislators' ideal points
          and item parameters.  See Details.

store.item: 'logical', whether item discrimination parameters should be
          stored.  Storing item discrimination parameters can consume a
          large amount of memory.  These need to be stored for
          prediction; see 'predict.ideal'.

    file: string, file to write MCMC output.  Default is 'NULL', in
          which case MCMC output is stored in memory.  Note that
          post-estimation commands like 'plot' will not work unless
          MCMC output is stored in memory.

 verbose: logical, default is 'FALSE', which generates relatively
          little output to the R console during execution.

_D_e_t_a_i_l_s:

     The function fits a 'd'+1 parameter item-response model to the
     roll call data object, so in one dimension the model reduces to
     the two-parameter item-response model popular in educational
     testing. See References.

     *Identification*: The model parameters are *not identified*
     without the user supplying some restrictions on the model
     parameters (e.g., translations, rotations and re-scalings of the
     ideal points are observationally equivalent, via offsetting
     transformations of the item parameters).  It is the user's
     responsibility to impose these identifying restrictions if
     desired; the following brief discussion provides some guidance.

     For one-dimensional models (i.e., 'd=1'), a simple route to
     identification is the 'normalize' option, which guarantees _local_
     identification (identification up to a 180 rotation of the
     recovered dimension). Near-degenerate"spike" priors (priors with
     arbitrarily large precisions) or the 'constrain.legis' option on
     any two legislators' ideal points ensures _global_ identification.

     Identification in higher dimensions can be obtained by supplying
     fixed values for 'd+1' legislators' ideal points, provided the
     supplied points span a 'd'-dimensional space (e.g., three supplied
     ideal points form a triangle in 'd=2' dimensions), via the
     'constrain.legis' option. In this case the function defaults to
     vague normal priors, but at each iteration the sampled ideal
     points are transformed back into the space of identified
     parameters, applying the linear transformation that maps the 'd+1'
     fixed ideal points from their sampled values to their fixed
     values.  Alternatively (and equivalently), one can impose
     restrictions on the item parameters via 'constrain.items'. See the
     examples in the documentation for the 'constrain.legis' and
     'constrain.items'.

     Another route to identification is via _post-processing_.  That
     is, the user can run 'ideal' without any identification
     constraints (which does not pose any formal/technical problem in a
     Bayesian analysis - the posterior density is still well defined
     and can be explored via MCMC methods) - but then use the function
     'postProcess' to map the MCMC output from the space of
     unidentified parameters into the subspace of identified
     parameters. See the example in the documentation for the
     'postProcess' function.  When the 'normalize' option is set to
     'TRUE', an unidentified model is run, and the 'ideal' object is
     post-processed with the 'normalize' option, and then returned to
     the user (but again, note that the 'normalize' option is only
     implemented for unidimensional models).

     *Start values*.  Start values can be supplied by the user, or
     generated by the function itself. 

     The default method, corresponding to 'startvals="eigen"', first
     forms a 'n'-by-'n' correlation matrix from the double-centered
     roll call matrix (subtracting row means, and column means, adding
     in the grand mean), and then extracts the first 'd' principal
     components (eigenvectors), scaling the eigenvectors by the square
     root of their corresponding eigenvector. If the user is imposing
     constraints on ideal points (via 'constrain.legis'), these are
     applied to the corresponding elements of the start values
     generated from the eigen decomposition.  Then, to generate start
     values for the rollcall/item parameters, a series of 'binomial'
     'glms' are estimated (with a probit 'link'), one for each
     rollcall/item, j = 1, ..., m.  The votes on the j-th rollcall/item
     are binary responses (presumed to be conditionally independent
     given each legislator's latent preference), and the (constrained
     or unconstrained) start values for legislators are used as
     predictors. The estimated coefficients from these probit models
     are stored to serve as start values for the item discrimination
     and difficulty parameters (with the intercepts from the probit
     GLMs multiplied by -1 so as to make those coefficients difficulty
     parameters).

     The default 'eigen' method generates extremely good start values
     for low-dimensional models fit to recent U.S. congresses (where
     high rates of party line voting mean low dimensional models fit
     well).  The 'eigen' method may be computationally expensive or
     even impossible to implement for 'rollcall' objects with large
     numbers of legislators.

     The 'random' method generates start values via iid sampling from a
     N(0,1) density, via 'rnorm', imposes any constraints that may have
     been supplied via 'constrain.legis', and then uses the probit
     method described above to get start values for the rollcall/item
     parameters.

     If 'startvals' is a 'list', it must contain the elements 'xstart'
     and/or 'bstart', which should be matrices. 'xstart' must be of
     dimensions equal to the number of individuals (legislators) by
     'd'.  If supplied, 'startvals$bstart' must be of dimensions number
     of items (votes) by 'd'+1.  The 'xstart' and 'bstart' components
     cannot contain 'NA'. If 'xstart' is not supplied when 'startvals'
     is a list, then start values are generated using the default
     'eiegn' method described above, and start values for the
     rollcall/item parameters are regenerated using the probit method,
     ignoring any user-supplied values in 'startvals$bstart'.  That is,
     user-supplied values in 'startvals$bstart' are only used when
     accompanied by a valid set of start values for the ideal points in
     'startvals$xstart'.

_V_a_l_u_e:

     a 'list' of class 'ideal' with named components

       n: 'numeric', integer, number of legislators in the analysis,
          after any subseting via processing the 'dropList'.

       m: 'numeric', integer, number of rollcalls in roll call matrix,
          after any subseting via processing the 'dropList'.

       d: 'numeric', integer, number of dimensions fitted.

       x: a 'matrix' containing the MCMC samples for the ideal point of
          each legislator in each dimension for each iteration from
          'burnin' to 'maxiter', at an interval of 'thin'.  Rows of the
          'x' matrix index iterations; columns index legislators.

    beta: a 'matrix' containing the MCMC samples for the item
          discrimination parameter for each item in each dimension,
          plus an intercept, for each iteration from 'burnin' to
          'maxiter', at an interval of 'thin'. Rows of the 'beta'
          matrix index MCMC iterations; columns index parameters.

    xbar: a 'matrix' containing the means of the MCMC samples for the
          ideal point of each legislator in each dimension, using
          iterations 'burnin' to 'maxiter', at an interval of 'thin';
          i.e., the column means of 'x'.

 betabar: a 'matrix' containing the means of the MCMC samples for the
          vote-specific parameters, using iterations 'burnin' to
          'maxiter', at an interval of 'thin'; i.e., the column means
          of 'beta'.

    call: an object of class 'call', containing the arguments passed to
          'ideal' as unevaluated expressions.

_A_u_t_h_o_r(_s):

     Simon Jackman jackman@stanford.edu, with help from Christina
     Maimone and Alex Tahk.

_R_e_f_e_r_e_n_c_e_s:

     Albert, James. 1992. Bayesian Estimation of normal ogive item
     response curves using Gibbs sampling. _Journal of Educational
     Statistics_. 17:251-269.

     Clinton, Joshua, Simon Jackman and Douglas Rivers. 2004. The
     Statistical Analysis of Roll Call Data.  _American Political
     Science Review_.  98:335-370.

     Patz, Richard J. and Brian W. Junker. 1999.  A Straightforward
     Approach to Markov Chain Monte Carlo Methods for Item Response
     Models. _Journal of Education and Behavioral Statistics_.
     24:146-178.

     Rivers, Douglas. 2003.  "Identification of Multidimensional
     Item-Response Models." Typescript.  Department of Political
     Science, Stanford University.

_S_e_e _A_l_s_o:

     'rollcall', 'summary.ideal', 'plot.ideal', 'predict.ideal'.
     'tracex' for graphical display of MCMC iterative history.

     'idealToMCMC' converts the MCMC iterates in an 'ideal' object to a
     form that can be used by the 'coda' library.

     'constrain.items' and 'constrain.legis' for implementing
     identifying restrictions.

     'postProcess' for imposing identifying restrictions _ex post_.

     'MCMCirt1d' and  'MCMCirtKd' in the 'MCMCpack' package provide
     similar functionality to 'ideal'.

_E_x_a_m_p_l_e_s:

     data(s109)

     ## ridiculously short run for examples
     id1 <- ideal(s109,
                  d=1,
                  normalize=TRUE,
                  store.item=TRUE,
                  maxiter=500,
                  burnin=100,
                  thin=10,
                  verbose=TRUE)  
     summary(id1)

     ## Not run: 
     ## more realistic long run
     idLong <- ideal(s109,
                     d=1,
                     priors=list(xpv=1e-12,bpv=1e-12),
                     normalize=TRUE,
                     store.item=TRUE,
                     maxiter=260e3,
                     burnin=1e4,
                     thin=100)  
     ## End(Not run)

