Extract Components from 'est_irt', 'est_mg', or 'est_item' Objects

Extracts internal components from an object of class est_irt (from est_irt()), est_mg (from est_mg()), or est_item (from est_item()).

Usage

getirt(x, ...)

# S3 method for class 'est_irt'
getirt(x, what, ...)

# S3 method for class 'est_mg'
getirt(x, what, ...)

# S3 method for class 'est_item'
getirt(x, what, ...)

Arguments

x: An object of class est_irt, est_mg, or est_item as returned by est_irt(), est_mg(), or est_item(), respectively.
...: Additional arguments passed to or from other methods.
what: A character string specifying the name of the internal component to extract.

Value

The internal component extracted from an object of class est_irt, est_mg, or est_item, depending on the input to the x argument.

Details

The following components can be extracted from an object of class est_irt created by est_irt():

estimates: A data frame containing both the item parameter estimates and their corresponding standard errors.
par.est: A data frame containing only the item parameter estimates.
se.est: A data frame containing the standard errors of the item parameter estimates, computed from the inverse of the information matrix: the cross-product (empirical) information matrix of the marginal log-likelihood evaluated at the final estimates (Meilijson, 1989), plus the prior information (the negative second derivatives of the log prior densities) for the parameters that have prior distributions.
pos.par: A data frame indicating the position index of each estimated item parameter. This is useful when interpreting the variance-covariance matrix.
covariance: A variance-covariance matrix of the item parameter estimates.
loglikelihood: The marginal log-likelihood of the response data at the final estimates: the sum over examinees of the logarithm of the probability of each examinee's response pattern, integrated over the latent ability distribution. The log prior densities of the item parameters are not included.
aic: Akaike Information Criterion (AIC) based on the marginal log-likelihood.
bic: Bayesian Information Criterion (BIC) based on the marginal log-likelihood.
group.par: A data frame containing the mean, variance, and standard deviation of the latent variable's prior distribution.
weights: A two-column data frame containing quadrature points (first column) and corresponding weights (second column) of the (updated) latent trait prior.
posterior.dist: A matrix of the posterior probabilities of the quadrature points for each examinee. Rows represent examinees, and columns represent quadrature points; each row sums to 1.
data: A matrix of the examinee response dataset used in estimation.
scale.D: The scaling constant (usually 1 or 1.702) used in the IRT model.
ncase: The number of examinees.
nitem: The number of items included in the dataset.
Etol: The convergence criterion of the EM algorithm: the largest absolute change in the estimated item parameters between consecutive cycles. For FIPC with all items fixed, it applies to the change in the mean and variance of the latent ability distribution; see est_irt().
MaxE: The maximum number of EM cycles allowed during estimation (1 when fipc.method = "OEM").
aprior: A list describing the prior distribution for item slope parameters.
bprior: A list describing the prior distribution for item difficulty (or threshold) parameters.
gprior: A list describing the prior distribution for item guessing parameters.
npar.est: The number of freely estimated parameters used for aic and bic; see est_irt().
niter: The number of EM cycles completed.
maxpar.diff: The largest absolute change in the estimated item parameters at the last EM cycle (for FIPC with all items fixed, in the mean and variance of the latent ability distribution).
EMtime: Computation time (in seconds) for the EM algorithm.
SEtime: Computation time (in seconds) for estimating standard errors.
TotalTime: Total computation time (in seconds) for model estimation.
test.1: A message indicating whether the convergence criteria were met (M-step convergence and the EM criterion).
test.2: A message indicating whether the information matrix used for the standard errors was positive definite. Printed results label it "Second-order test", but because the cross-product information matrix is positive semidefinite by construction, this check mainly detects a singular (rank-deficient) information matrix; it is not a second-order test of the log-likelihood surface. When FIPC is used with all items fixed, no information matrix is computed, and the message says so.
var.note: A note indicating whether the variance-covariance matrix was successfully derived from the information matrix.
fipc: Logical value indicating whether Fixed Item Parameter Calibration (FIPC) was applied.
fipc.method: The specific method used for FIPC.
fix.loc: An integer vector of the positions of the fixed items in FIPC, or NULL without FIPC.
npar.detail: The numbers of free parameters by type; see est_irt().
call: The matched call.

Components that can be extracted from an object of class est_mg created by est_mg() include:

estimates

A list with two components: overall and group.

overall: A data frame containing item parameter estimates and their standard errors, based on the combined data set across all groups.
group: A list of group-specific data frames containing item parameter estimates and standard errors for each group.

par.est

Same structure as estimates, but containing only the item parameter estimates (without standard errors).

se.est

Same structure as estimates, but containing only the standard errors of the item parameter estimates. The standard errors are computed from the inverse of the information matrix: the cross-product (empirical) information matrix of the marginal log-likelihood evaluated at the final estimates (Meilijson, 1989), plus the prior information (the negative second derivatives of the log prior densities) for the parameters that have prior distributions.

pos.par

A data frame indicating the position index of each estimated parameter. This index is based on the combined item set across all groups and is useful when interpreting the variance-covariance matrix. It is NULL when all items are fixed in FIPC.

covariance

A variance-covariance matrix for the item parameter estimates based on the combined data from all groups. It is NULL when se = FALSE or when all items are fixed in FIPC.

loglikelihood

A list with overall and group components:

overall: The marginal log-likelihood of the response data of all groups at the final estimates (summed over examinees, without the log prior densities).
group: The same sums within the groups.

aic

Akaike Information Criterion (AIC) computed from the overall log-likelihood.

bic

Bayesian Information Criterion (BIC) computed from the overall log-likelihood.

group.par

A list of group-specific data frames with the mean, variance, and standard deviation of the latent ability distribution and their standard errors; see est_mg().

weights

A list of two-column data frames (one per group) containing the quadrature points (first column) and the corresponding weights (second column) for the updated prior distributions.

posterior.dist

A matrix of the posterior probabilities of the quadrature points for each examinee. Rows represent the examinees of all groups in the order of group.name, and columns represent quadrature points; each row sums to 1.

data

A list with overall and group components, each containing examinee response data.

scale.D

The scaling constant used in the IRT model (typically 1 or 1.702).

ncase

A list with overall and group components indicating the numbers of examinees.

nitem

A list with overall and group components indicating the number of items in the respective response sets.

Etol

The convergence criterion of the EM algorithm: the largest absolute change in the estimated item parameters between consecutive cycles. For FIPC with all items fixed, it applies to the change in the means and variances of the latent ability distributions of all groups; see est_mg().

MaxE

The maximum number of EM cycles allowed during estimation (1 when fipc.method = "OEM").

aprior

A list describing the prior distribution for item slope parameters.

bprior

A list describing the prior distribution for item difficulty parameters.

gprior

A list describing the prior distribution for item guessing parameters.

npar.est

The number of freely estimated parameters used for aic and bic; see est_mg().

niter

Number of EM cycles completed.

maxpar.diff

The largest absolute change in the estimated item parameters at the last EM cycle (for FIPC with all items fixed, in the means and variances of the latent ability distributions of all groups; see Etol in est_mg()).

EMtime

Computation time (in seconds) for EM estimation.

SEtime

Computation time (in seconds) for estimating standard errors.

TotalTime

Total computation time (in seconds) for model estimation.

test.1

A message indicating whether the convergence criteria were met (M-step convergence and the EM criterion).

test.2

A message indicating whether the information matrix used for the standard errors was positive definite. Printed results label it "Second-order test", but because the cross-product information matrix is positive semidefinite by construction, this check mainly detects a singular (rank-deficient) information matrix; it is not a second-order test of the log-likelihood surface. When FIPC is used with all items fixed, no information matrix is computed, and the message says so.

var.note

A note indicating whether the variance-covariance matrix was successfully derived from the information matrix.

fipc

Logical value indicating whether Fixed Item Parameter Calibration (FIPC) was used.

fipc.method

The method used for FIPC.

fix.loc

A list with overall and group components specifying the locations of fixed items when FIPC was applied.

npar.detail

The numbers of free parameters by type; see est_mg().

call

The matched call.

Components that can be extracted from an object of class est_item created by est_item() include:

estimates: A data frame containing both the item parameter estimates and their corresponding standard errors.
par.est: A data frame containing only the item parameter estimates.
se.est: A data frame containing the standard errors of the item parameter estimates, computed from the inverse of the observed information matrix (the Hessian of the negative log-likelihood, plus the negative second derivatives of the log prior densities when priors are used). The abilities in score are treated as known, so their estimation error is not reflected in the standard errors.
pos.par: A data frame indicating the position index of each estimated item parameter. This is useful when interpreting the variance-covariance matrix.
covariance: A variance-covariance matrix of the item parameter estimates.
loglikelihood: The log-likelihood of the observed responses given the abilities in score, summed over the items, at the final estimates, without the log prior densities of the item parameters.
group.par: A named numeric vector with the mean (mu) and the standard deviation (sigma) of the abilities in score.
data: A data frame of examinee response data.
score: A numeric vector of examinees' ability values used as fixed effects during estimation.
scale.D: The scaling constant (typically 1 or 1.702) used in the IRT model.
convergence: A character string indicating the convergence status of the item parameter estimation.
nitem: The number of items in the response data as supplied, including the excluded items.
deleted.item: The positions of the items that contained no response data and were excluded from estimation.
npar.est: The total number of estimated item parameters.
n.response: A numeric vector of the numbers of responses to the items (0 for the excluded items).
TotalTime: Total computation time (in seconds) for the estimation process.
call: The matched call.

See est_irt(), est_mg(), and est_item() for more details.

Methods (by class)

getirt(est_irt): An object created by the function est_irt().
getirt(est_mg): An object created by the function est_mg().
getirt(est_item): An object created by the function est_item().

Author

Hwanggyu Lim hglim83@gmail.com

Examples

# \donttest{
# Fit a 2PL model to the LSAT6 data
mod.2pl <- est_irt(data = LSAT6, D = 1, model = "2PLM", cats = 2)
#> Parsing input... 
#> Estimating item parameters... 
#> 
 EM iteration: 1, Loglike: -3182.3860, Max-Change: 2.294233
 EM iteration: 2, Loglike: -2561.0478, Max-Change: 0.58517
 EM iteration: 3, Loglike: -2482.8950, Max-Change: 0.323232
 EM iteration: 4, Loglike: -2469.4379, Max-Change: 0.180623
 EM iteration: 5, Loglike: -2467.2706, Max-Change: 0.106034
 EM iteration: 6, Loglike: -2466.8615, Max-Change: 0.066546
 EM iteration: 7, Loglike: -2466.7487, Max-Change: 0.044361
 EM iteration: 8, Loglike: -2466.7049, Max-Change: 0.030996
 EM iteration: 9, Loglike: -2466.6843, Max-Change: 0.022467
 EM iteration: 10, Loglike: -2466.6736, Max-Change: 0.016791
 EM iteration: 11, Loglike: -2466.6674, Max-Change: 0.012897
 EM iteration: 12, Loglike: -2466.6636, Max-Change: 0.010155
 EM iteration: 13, Loglike: -2466.6611, Max-Change: 0.008179
 EM iteration: 14, Loglike: -2466.6593, Max-Change: 0.00672
 EM iteration: 15, Loglike: -2466.6580, Max-Change: 0.005616
 EM iteration: 16, Loglike: -2466.6571, Max-Change: 0.00476
 EM iteration: 17, Loglike: -2466.6563, Max-Change: 0.004082
 EM iteration: 18, Loglike: -2466.6557, Max-Change: 0.003532
 EM iteration: 19, Loglike: -2466.6553, Max-Change: 0.003079
 EM iteration: 20, Loglike: -2466.6549, Max-Change: 0.00270
 EM iteration: 21, Loglike: -2466.6546, Max-Change: 0.002378
 EM iteration: 22, Loglike: -2466.6544, Max-Change: 0.002102
 EM iteration: 23, Loglike: -2466.6542, Max-Change: 0.001863
 EM iteration: 24, Loglike: -2466.6540, Max-Change: 0.001655
 EM iteration: 25, Loglike: -2466.6539, Max-Change: 0.001473
 EM iteration: 26, Loglike: -2466.6538, Max-Change: 0.001313
 EM iteration: 27, Loglike: -2466.6537, Max-Change: 0.001172
 EM iteration: 28, Loglike: -2466.6537, Max-Change: 0.001047
 EM iteration: 29, Loglike: -2466.6536, Max-Change: 0.000936
 EM iteration: 30, Loglike: -2466.6536, Max-Change: 0.000838
 EM iteration: 31, Loglike: -2466.6535, Max-Change: 0.000751
 EM iteration: 32, Loglike: -2466.6535, Max-Change: 0.000673
 EM iteration: 33, Loglike: -2466.6535, Max-Change: 0.000603
 EM iteration: 34, Loglike: -2466.6535, Max-Change: 0.000541
 EM iteration: 35, Loglike: -2466.6534, Max-Change: 0.000486
 EM iteration: 36, Loglike: -2466.6534, Max-Change: 0.000436
 EM iteration: 37, Loglike: -2466.6534, Max-Change: 0.000392
 EM iteration: 38, Loglike: -2466.6534, Max-Change: 0.000352
 EM iteration: 39, Loglike: -2466.6534, Max-Change: 0.000316
 EM iteration: 40, Loglike: -2466.6534, Max-Change: 0.000284
 EM iteration: 41, Loglike: -2466.6534, Max-Change: 0.000256
 EM iteration: 42, Loglike: -2466.6534, Max-Change: 0.00023
 EM iteration: 43, Loglike: -2466.6534, Max-Change: 0.000207
 EM iteration: 44, Loglike: -2466.6534, Max-Change: 0.000186
 EM iteration: 45, Loglike: -2466.6534, Max-Change: 0.000167
 EM iteration: 46, Loglike: -2466.6534, Max-Change: 0.000151
 EM iteration: 47, Loglike: -2466.6534, Max-Change: 0.000136
 EM iteration: 48, Loglike: -2466.6534, Max-Change: 0.000122
 EM iteration: 49, Loglike: -2466.6534, Max-Change: 0.00011
 EM iteration: 50, Loglike: -2466.6534, Max-Change: 9.9e-05 
#> Computing item parameter var-covariance matrix... 
#> Estimation is finished in 0.36 seconds. 

# Extract item parameter estimates
(est.par <- getirt(mod.2pl, what = "par.est"))
#>   id cats model     par.1      par.2 par.3
#> 1 V1    2  2PLM 0.8255888 -3.3590452    NA
#> 2 V2    2  2PLM 0.7229138 -1.3697963    NA
#> 3 V3    2  2PLM 0.8904047 -0.2797759    NA
#> 4 V4    2  2PLM 0.6884844 -1.8661188    NA
#> 5 V5    2  2PLM 0.6570762 -3.1250079    NA

# Extract standard error estimates
(est.se <- getirt(mod.2pl, what = "se.est"))
#>   id cats model     par.1      par.2 par.3
#> 1 V1    2  2PLM 0.2538702 0.85483653    NA
#> 2 V2    2  2PLM 0.1879120 0.30935133    NA
#> 3 V3    2  2PLM 0.2298908 0.09951049    NA
#> 4 V4    2  2PLM 0.1862128 0.43815986    NA
#> 5 V5    2  2PLM 0.2027270 0.84271138    NA

# Extract the variance-covariance matrix of item parameter estimates
(cov.mat <- getirt(mod.2pl, what = "covariance"))
#>                [,1]         [,2]          [,3]          [,4]         [,5]
#>  [1,]  0.0644500663  0.213516110 -0.0059296609 -1.012578e-02 -0.004681038
#>  [2,]  0.2135161095  0.730745496 -0.0205129366 -3.393420e-02 -0.016087744
#>  [3,] -0.0059296609 -0.020512937  0.0353109379  5.459288e-02 -0.011084779
#>  [4,] -0.0101257773 -0.033934198  0.0545928849  9.569824e-02 -0.016831654
#>  [5,] -0.0046810378 -0.016087744 -0.0110847789 -1.683165e-02  0.052849776
#>  [6,] -0.0011271119 -0.003110929 -0.0023765393 -2.603282e-03  0.012397532
#>  [7,] -0.0031463866 -0.010012688 -0.0005355098  4.910666e-06 -0.011308992
#>  [8,] -0.0075724067 -0.022812226  0.0001639620  3.457859e-03 -0.026321355
#>  [9,]  0.0002965241  0.002494229 -0.0037729160 -5.976366e-03 -0.004409260
#> [10,]  0.0023222383  0.015568907 -0.0160475746 -2.471635e-02 -0.015974475
#>               [,6]          [,7]         [,8]          [,9]        [,10]
#>  [1,] -0.001127112 -3.146387e-03 -0.007572407  0.0002965241  0.002322238
#>  [2,] -0.003110929 -1.001269e-02 -0.022812226  0.0024942292  0.015568907
#>  [3,] -0.002376539 -5.355098e-04  0.000163962 -0.0037729160 -0.016047575
#>  [4,] -0.002603282  4.910666e-06  0.003457859 -0.0059763663 -0.024716348
#>  [5,]  0.012397532 -1.130899e-02 -0.026321355 -0.0044092598 -0.015974475
#>  [6,]  0.009902337 -2.893417e-03 -0.005765609 -0.0010248799 -0.002351144
#>  [7,] -0.002893417  3.467521e-02  0.078608493 -0.0039184840 -0.017434966
#>  [8,] -0.005765609  7.860849e-02  0.191984062 -0.0094264375 -0.041401179
#>  [9,] -0.001024880 -3.918484e-03 -0.009426438  0.0410982364  0.168071445
#> [10,] -0.002351144 -1.743497e-02 -0.041401179  0.1680714454  0.710162472
# }