get.fit.index: Goodness-of-Fit Indices for Fitted Models
In ForceChoice: Forced-Choice Modeling Based on Item Response Theory and Cognitive Diagnostic Models
View source: R/get.fit.index.R
get.fit.index.FCDCM R Documentation
Goodness-of-Fit Indices for Fitted Models
Description
Generic function to compute a comprehensive suite of model-fit diagnostics
for fitted ForceChoice model objects. The function dispatches on the class
of the fitted model and returns an object of class "good.of.fit"
containing likelihood-based, limited-information, and residual-based
diagnostics.
Usage
## S3 method for class 'FCDCM'
get.fit.index(object, ...)
## S3 method for class 'FCGDINA'
get.fit.index(object, ...)
## S3 method for class 'FCGGUM'
get.fit.index(object, ...)
## S3 method for class 'FCMIRT'
get.fit.index(object, ...)
## S3 method for class 'MGGUM'
get.fit.index(object, ...)
## S3 method for class 'MGPCM'
get.fit.index(object, ...)
## S3 method for class 'MIRT'
get.fit.index(object, ...)
## S3 method for class 'TIRT'
get.fit.index(object, ...)
Arguments
object
A fitted model object (class "MIRT", "MGPCM",
"MGGUM", "FCMIRT", "FCDCM", "FCGGUM", or
"TIRT").
...
Additional arguments passed to good.of.fit.
Common options include alpha (tail probability for RMSEA CI;
default 0.05 gives a 90% CI), bivariate.groups (exclude pairs
within the same group from bivariate moments), and n.boot
(bootstrap replicates).
Value
An object of class "good.of.fit". Use
summary.good.of.fit and print.good.of.fit
for formatted output. Key components:
-
LogLik, deviance, AIC, AICc,
BIC, CAIC, SABIC, HQIC
-
M2.value, df, p.value
-
RMSEA2, RMSEA.lower, RMSEA.upper,
RMSEA.p.close
-
SRMSR
-
CFI, TLI, IFI
-
McFadden.R2, CoxSnell.R2, Nagelkerke.R2
-
q3.mean, q3.abs.max, q3.adjusted.abs.max
-
posterior.entropy, posterior.entropy.normalized
Methods (by class)
-
get.fit.index(FCDCM): FCDCM model: binary block responses with
quadrature over higher-order \theta and exact marginalization
over 2^D attribute patterns.
-
get.fit.index(FCGDINA): FCGDINA model: forced-choice CDM with nominal
binary expansion; within-block pairs excluded.
-
get.fit.index(FCGGUM): FCGGUM model: forced-choice unfolding with nominal
binary expansion; within-block pairs excluded.
-
get.fit.index(FCMIRT): FCMIRT model: forced-choice ranking data expanded
to nominal binary indicators; within-block pairs excluded from bivariate
moments.
-
get.fit.index(MGGUM): MGGUM model: polytomous unfolding responses with
M2* category-collapsed construction.
-
get.fit.index(MGPCM): MGPCM model: polytomous responses with M2*
category-collapsed construction.
-
get.fit.index(MIRT): MIRT model: binary responses with Gauss–Hermite
quadrature over D-dimensional latent space.
-
get.fit.index(TIRT): TIRT model: pairwise binary responses with
within-block pairs excluded via bivariate.groups.
Limited-Information M2 Framework
Following Maydeu-Olivares and Joe (2005, 2006), the test statistic uses
first- and second-order marginal moments rather than the full contingency
table, making it suitable for sparse high-dimensional responses.
Let \boldsymbol{\pi}(\boldsymbol{\psi}) be the vector of
M model-implied univariate and bivariate moments,
\mathbf{p} the observed moments, and
\boldsymbol{\Delta} = \partial\boldsymbol{\pi}/\partial\boldsymbol{\psi}'
the Jacobian. The M2 statistic is:
M_2 = N\,\mathbf{e}'\hat{\mathbf{C}}_2\mathbf{e},
\qquad \mathbf{e} = \mathbf{p} - \boldsymbol{\pi}(\hat{\boldsymbol{\psi}}),
where \hat{\mathbf{C}}_2 = \boldsymbol{\Delta}_c
(\boldsymbol{\Delta}_c'\hat{\boldsymbol{\Xi}}_2\boldsymbol{\Delta}_c)^{-1}
\boldsymbol{\Delta}_c' with \boldsymbol{\Delta}_c the orthogonal
complement of \boldsymbol{\Delta}. Under the null,
M_2 \sim \chi^2_{M - p} asymptotically.
Fit Index Formulas
Information criteria (Akaike 1974; Schwarz 1978; Bozdogan 1987;
Sclove 1987; Hannan & Quinn 1979):
\begin{aligned}
\text{AIC} &= -2\ell + 2p, \\
\text{AICc} &= \text{AIC} + \frac{2p(p+1)}{N-p-1}, \\
\text{BIC} &= -2\ell + p\log N, \\
\text{CAIC} &= -2\ell + p(\log N + 1), \\
\text{SABIC} &= -2\ell + p\log\!\bigl(\frac{N+2}{24}\bigr), \\
\text{HQIC} &= -2\ell + 2p\log(\log N).
\end{aligned}
RMSEA (Browne & Cudeck 1993):
\text{RMSEA} = \sqrt{\max\!\left(0,\; \frac{M_2 - df}{N \cdot df}\right)},
\qquad df = M - p.
Confidence intervals via non-central \chi^2 inversion; close-fit
test H_0: \text{RMSEA} \le 0.05.
SRMSR:
\text{SRMSR} = \sqrt{\frac{1}{J}\sum_{i<j}(r_{ij}^{\text{obs}} - r_{ij}^{\text{model}})^2}.
CFI / TLI / IFI (Bentler 1990; Tucker & Lewis 1973; Bollen 1989):
\begin{aligned}
\text{CFI} &= 1 - \frac{\max(M_2 - df, 0)}{\max(M_2^{\text{null}} - df^{\text{null}},\; M_2 - df,\; 0)}, \\[4pt]
\text{TLI} &= \frac{M_2^{\text{null}}/df^{\text{null}} - M_2/df}{M_2^{\text{null}}/df^{\text{null}} - 1}, \\[4pt]
\text{IFI} &= \frac{M_2^{\text{null}} - M_2}{M_2^{\text{null}} - df}.
\end{aligned}
Pseudo-R^2:
\begin{aligned}
R^2_{\text{McF}} &= 1 - \ell/\ell_0, \\
R^2_{\text{CS}} &= 1 - \exp\!\bigl(\tfrac{2}{N}(\ell_0 - \ell)\bigr), \\
R^2_{\text{N}} &= R^2_{\text{CS}} / \bigl(1 - \exp(2\ell_0/N)\bigr), \\
R^2_{\text{AN}} &= G^2/(G^2 + N), \quad G^2 = D_0 - D.
\end{aligned}
Yen's Q3 (Yen 1984):
Q_{3,ik} = \text{Corr}(r_{ji}, r_{jk}), \qquad
r_{ji} = Y_{ji} - E[Y_{ji} \mid \hat{\boldsymbol{\theta}}_j].
Posterior diagnostics (Celeux & Soromenho 1996):
E = -\frac{1}{N}\sum_{j=1}^{N}\sum_{c=1}^{Q}\hat{\tau}_{jc}\log\hat{\tau}_{jc},
\qquad
E_{\text{norm}} = 1 - E / \log Q.
Heuristic Guidelines
RMSEA: \le 0.05 close, \le 0.08 reasonable
SRMSR: \le 0.08 acceptable (Hu & Bentler 1999)
CFI / TLI: \ge 0.95 good, \ge 0.90 acceptable
Normalized entropy: \ge 0.70 acceptable separation
References
Akaike, H. (1974). IEEE Trans. Autom. Control, 19, 716–723.
Bozdogan, H. (1987). Psychometrika, 52, 345–370.
Browne, M. W., & Cudeck, R. (1993). In Bollen & Long (Eds.), Testing
structural equation models (pp. 136–162). Sage.
Celeux, G., & Soromenho, G. (1996). J. Classification, 13, 195–212.
Hu, L. T., & Bentler, P. M. (1999). Struct. Equ. Modeling, 6, 1–55.
Maydeu-Olivares, A., & Joe, H. (2005). JASA, 100, 1009–1020.
Maydeu-Olivares, A., & Joe, H. (2006). Psychometrika, 71, 713–732.
Schwarz, G. (1978). Ann. Statist., 6, 461–464.
Yen, W. M. (1984). Appl. Psychol. Meas., 8, 125–145.
See Also
good.of.fit for the underlying engine,
summary.good.of.fit for formatted summary tables.
Examples
sim <- sim.data.MIRT(N = 20, I = 6, D = 2, model = "m2pl")
fit <- fit.MIRT(
sim$response, model = "m2pl", D = 2, method = "iStEM",
control.method = list(
vis = FALSE, seed = 123,
M = 2, B = 2, burnin.maxitr = 2,
maxitr = 3, eps1 = 10, eps2 = 10,
estimate.se = FALSE)
)
gof <- get.fit.index(fit)
summary(gof)
# Custom RMSEA confidence level (99%)
gof99 <- get.fit.index(fit, alpha = 0.005)
summary(gof99)
ForceChoice documentation built on Sept. 13, 2026, 1:06 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
View source: R/get.fit.index.R
| get.fit.index.FCDCM | R Documentation |
Goodness-of-Fit Indices for Fitted Models
Description
Generic function to compute a comprehensive suite of model-fit diagnostics
for fitted ForceChoice model objects. The function dispatches on the class
of the fitted model and returns an object of class "good.of.fit"
containing likelihood-based, limited-information, and residual-based
diagnostics.
Usage
## S3 method for class 'FCDCM'
get.fit.index(object, ...)
## S3 method for class 'FCGDINA'
get.fit.index(object, ...)
## S3 method for class 'FCGGUM'
get.fit.index(object, ...)
## S3 method for class 'FCMIRT'
get.fit.index(object, ...)
## S3 method for class 'MGGUM'
get.fit.index(object, ...)
## S3 method for class 'MGPCM'
get.fit.index(object, ...)
## S3 method for class 'MIRT'
get.fit.index(object, ...)
## S3 method for class 'TIRT'
get.fit.index(object, ...)
Arguments
object |
A fitted model object (class |
... |
Additional arguments passed to |
Value
An object of class "good.of.fit". Use
summary.good.of.fit and print.good.of.fit
for formatted output. Key components:
-
LogLik,deviance,AIC,AICc,BIC,CAIC,SABIC,HQIC -
M2.value,df,p.value -
RMSEA2,RMSEA.lower,RMSEA.upper,RMSEA.p.close -
SRMSR -
CFI,TLI,IFI -
McFadden.R2,CoxSnell.R2,Nagelkerke.R2 -
q3.mean,q3.abs.max,q3.adjusted.abs.max -
posterior.entropy,posterior.entropy.normalized
Methods (by class)
-
get.fit.index(FCDCM): FCDCM model: binary block responses with quadrature over higher-order\thetaand exact marginalization over2^Dattribute patterns. -
get.fit.index(FCGDINA): FCGDINA model: forced-choice CDM with nominal binary expansion; within-block pairs excluded. -
get.fit.index(FCGGUM): FCGGUM model: forced-choice unfolding with nominal binary expansion; within-block pairs excluded. -
get.fit.index(FCMIRT): FCMIRT model: forced-choice ranking data expanded to nominal binary indicators; within-block pairs excluded from bivariate moments. -
get.fit.index(MGGUM): MGGUM model: polytomous unfolding responses with M2* category-collapsed construction. -
get.fit.index(MGPCM): MGPCM model: polytomous responses with M2* category-collapsed construction. -
get.fit.index(MIRT): MIRT model: binary responses with Gauss–Hermite quadrature overD-dimensional latent space. -
get.fit.index(TIRT): TIRT model: pairwise binary responses with within-block pairs excluded viabivariate.groups.
Limited-Information M2 Framework
Following Maydeu-Olivares and Joe (2005, 2006), the test statistic uses first- and second-order marginal moments rather than the full contingency table, making it suitable for sparse high-dimensional responses.
Let \boldsymbol{\pi}(\boldsymbol{\psi}) be the vector of
M model-implied univariate and bivariate moments,
\mathbf{p} the observed moments, and
\boldsymbol{\Delta} = \partial\boldsymbol{\pi}/\partial\boldsymbol{\psi}'
the Jacobian. The M2 statistic is:
M_2 = N\,\mathbf{e}'\hat{\mathbf{C}}_2\mathbf{e},
\qquad \mathbf{e} = \mathbf{p} - \boldsymbol{\pi}(\hat{\boldsymbol{\psi}}),
where \hat{\mathbf{C}}_2 = \boldsymbol{\Delta}_c
(\boldsymbol{\Delta}_c'\hat{\boldsymbol{\Xi}}_2\boldsymbol{\Delta}_c)^{-1}
\boldsymbol{\Delta}_c' with \boldsymbol{\Delta}_c the orthogonal
complement of \boldsymbol{\Delta}. Under the null,
M_2 \sim \chi^2_{M - p} asymptotically.
Fit Index Formulas
Information criteria (Akaike 1974; Schwarz 1978; Bozdogan 1987; Sclove 1987; Hannan & Quinn 1979):
\begin{aligned}
\text{AIC} &= -2\ell + 2p, \\
\text{AICc} &= \text{AIC} + \frac{2p(p+1)}{N-p-1}, \\
\text{BIC} &= -2\ell + p\log N, \\
\text{CAIC} &= -2\ell + p(\log N + 1), \\
\text{SABIC} &= -2\ell + p\log\!\bigl(\frac{N+2}{24}\bigr), \\
\text{HQIC} &= -2\ell + 2p\log(\log N).
\end{aligned}
RMSEA (Browne & Cudeck 1993):
\text{RMSEA} = \sqrt{\max\!\left(0,\; \frac{M_2 - df}{N \cdot df}\right)},
\qquad df = M - p.
Confidence intervals via non-central \chi^2 inversion; close-fit
test H_0: \text{RMSEA} \le 0.05.
SRMSR:
\text{SRMSR} = \sqrt{\frac{1}{J}\sum_{i<j}(r_{ij}^{\text{obs}} - r_{ij}^{\text{model}})^2}.
CFI / TLI / IFI (Bentler 1990; Tucker & Lewis 1973; Bollen 1989):
\begin{aligned}
\text{CFI} &= 1 - \frac{\max(M_2 - df, 0)}{\max(M_2^{\text{null}} - df^{\text{null}},\; M_2 - df,\; 0)}, \\[4pt]
\text{TLI} &= \frac{M_2^{\text{null}}/df^{\text{null}} - M_2/df}{M_2^{\text{null}}/df^{\text{null}} - 1}, \\[4pt]
\text{IFI} &= \frac{M_2^{\text{null}} - M_2}{M_2^{\text{null}} - df}.
\end{aligned}
Pseudo-R^2:
\begin{aligned}
R^2_{\text{McF}} &= 1 - \ell/\ell_0, \\
R^2_{\text{CS}} &= 1 - \exp\!\bigl(\tfrac{2}{N}(\ell_0 - \ell)\bigr), \\
R^2_{\text{N}} &= R^2_{\text{CS}} / \bigl(1 - \exp(2\ell_0/N)\bigr), \\
R^2_{\text{AN}} &= G^2/(G^2 + N), \quad G^2 = D_0 - D.
\end{aligned}
Yen's Q3 (Yen 1984):
Q_{3,ik} = \text{Corr}(r_{ji}, r_{jk}), \qquad
r_{ji} = Y_{ji} - E[Y_{ji} \mid \hat{\boldsymbol{\theta}}_j].
Posterior diagnostics (Celeux & Soromenho 1996):
E = -\frac{1}{N}\sum_{j=1}^{N}\sum_{c=1}^{Q}\hat{\tau}_{jc}\log\hat{\tau}_{jc},
\qquad
E_{\text{norm}} = 1 - E / \log Q.
Heuristic Guidelines
RMSEA:
\le 0.05close,\le 0.08reasonableSRMSR:
\le 0.08acceptable (Hu & Bentler 1999)CFI / TLI:
\ge 0.95good,\ge 0.90acceptableNormalized entropy:
\ge 0.70acceptable separation
References
Akaike, H. (1974). IEEE Trans. Autom. Control, 19, 716–723. Bozdogan, H. (1987). Psychometrika, 52, 345–370. Browne, M. W., & Cudeck, R. (1993). In Bollen & Long (Eds.), Testing structural equation models (pp. 136–162). Sage. Celeux, G., & Soromenho, G. (1996). J. Classification, 13, 195–212. Hu, L. T., & Bentler, P. M. (1999). Struct. Equ. Modeling, 6, 1–55. Maydeu-Olivares, A., & Joe, H. (2005). JASA, 100, 1009–1020. Maydeu-Olivares, A., & Joe, H. (2006). Psychometrika, 71, 713–732. Schwarz, G. (1978). Ann. Statist., 6, 461–464. Yen, W. M. (1984). Appl. Psychol. Meas., 8, 125–145.
See Also
good.of.fit for the underlying engine,
summary.good.of.fit for formatted summary tables.
Examples
sim <- sim.data.MIRT(N = 20, I = 6, D = 2, model = "m2pl")
fit <- fit.MIRT(
sim$response, model = "m2pl", D = 2, method = "iStEM",
control.method = list(
vis = FALSE, seed = 123,
M = 2, B = 2, burnin.maxitr = 2,
maxitr = 3, eps1 = 10, eps2 = 10,
estimate.se = FALSE)
)
gof <- get.fit.index(fit)
summary(gof)
# Custom RMSEA confidence level (99%)
gof99 <- get.fit.index(fit, alpha = 0.005)
summary(gof99)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.