*! version 1.1 2022.01.24
help uirt_theta

Title

uirt_theta -- Postestimation command of uirt to add EAP or PVs

Syntax

uirt_theta [newvar1 newvar2] [,options]

newvar1 and newvar2 are optional. If specified, the expected a posteriori (EAP) estimator of theta and its standard error
will be added at the end of the dataset using newvar1 and newvar2 to name these new variables.

Options

eap create EAP estimator of theta and its standard error

nip(#) number of GH quadrature points used when calculating EAP and its SE; default: nip(195)

pv(#) number of plausible values added to the dataset, default is pv(0) (no PVs added)

pvreg(str) define regression for conditioning PVs

suffix(name) specify a suffix used in naming of EAP and PVs

scale(#,#) scale parameters (m,sd) of theta in reference group

skipnote suppress adding notes to newly created variables

Description

uirt_theta is a postestimation command of uirt that allows adding EAP point estimates of theta to the dataset.
Drawing plausible values (PVs) is also available; conditioning of PVs on ancillary variables is supported.

Options

eap adds the expected a posteriori (EAP) estimator of theta and its standard error at the end of the dataset.
These will be named "theta" and "se_theta" unless suffix() is specified.
Using eap is redundant if newvar1 and newvar2 are provided.

nip(#) sets the number of Gauss-Hermite quadrature points used when calculating EAP estimator of theta and its SE.
Default value is 195 which is an obvious overkill, but it does not consume much resources while
too low nip() values may lead to inadequate estimate of standard errors of EAP.

pv(#) is used to declare the number of plausible values that are to be added to the dataset.
Default value is 0 (no PVs added).
The PVs will be named "pv_1",..., "pv_#" unless suffix() is specified.
The PVs are generated after the estimation is completed.
The general procedure involves two steps.
In the first step, # random draws, b*, of model parameters are taken from MVN distribution with means vector e(b) and covariance matrix e(V).
In the second step, for each person, # independent MCMC chains are run according to procedure described by
Patz & Junker (1999) with b* parameter draws treated as fixed.
Finally, after a burn-in period, each of the PVs is drawn from a different MCMC chain.
Such procedure allows incorporating IRT model uncertainty in PV generation without the need of multilevel-structured MCMC,
thus reducing the computational expense and avoiding the use of Bayesian priors for item parameters.
Note that if some of the item parameters were fixed with fix() option of uirt the PVs will take no account
of the uncertainty of estimation of these fixed parameters.
Additional pvreg() option allows to modify the procedure so that it includes conditioning by a latent regression.

pvreg(str) is used to perform conditioning of plausible values on ancillary variables.
If other variables, than the ones used in defining the IRT model,
are to be used in the analyses performed with PVs, these variables need to be included in pvreg() option.
Otherwise, the analyses will produce effects which are biased towards 0.
The syntax for pvreg() is the same as in defining the regression term in xtmixed, e.g. pvreg(ses ||school:).
Note that multilevel modelling is allowed here.
If pv() is called without pvreg() the PVs for all observations within a group are generated with the same
normal prior distribution of ability with parameters taken from e(group_par).
By including the pvreg() option the procedure of generating PVs is modified in such a way that after each MCMC step
a regression of the ability on the variables provided by the user is performed by xtmixed. The xtmixed
model estimates are then used to recompute the priors.
Note that if some observations are excluded from xtmixed run (for example due to missing cases on any of the regressors)
these observations will not be conditioned.

suffix(name) specifies a suffix used in naming new EAP and PVs variables.
If newvar1 and newvar2 are provided they will take precedence in naming EAP, however suffix() will still apply to the PVs.

scale(#,#) is used to change the scale of the latent trait for variables that are added to the dataset.
By default the EAP and the PVs are obtained accordingly to the group parameters that are reported in e(group_par).
Specifying scale(m,sd) will rescale the latent trait so that the mean and the standard deviation in reference group are m and sd.
Note that because scale(m,sd) acts on the latent trait variable level,
the EAP estimates will most probably have smaller standard deviation in the reference group than sd due to shrinkage.

skipnote suppresses adding notes to newly created variables. Default behavior is to add notes.

Examples

Setup

. webuse masc2

Fit an IRT model with default settings of uirt using items q1-q9

. uirt q*

Add EAP point estimate of theta to data and its standard error with default names

. uirt_theta , eap

The same as above, but with user specified variable names

. uirt_theta my_eap my_se_of_eap

Add 5 unconditioned plausible values to data and use suffix "uncond" when naming them

. uirt_theta , pv(5) suf(uncond)

Add 5 plausible values to data but condition them on the female variable, use suffix "cond", and change scale to m=500 and sd=100

. uirt_theta , pv(5) pvreg(i.female) suf(cond) scale(500,100)

List contents of notes of newly created variables to inspect the comments that were added by uirt_theta

. notes list

Stored results

uirt_theta does not store anything in r():

Author

Bartosz Kondratek
everythingthatcounts@gmail.com

References

Patz, R. J., Junker, B. W. 1999.
A Straightforward Approach to Markov Chain Monte Carlo Methods for Item Response Models.
Journal of Educational and Behavioral Statistics, 24(2), 146-178.