residuals-method: Compute model residuals

In mirt: Multidimensional Item Response Theory

Compute model residuals

Description

Return model implied residuals for linear dependencies between items or at the person level. If the latent trait density was approximated (e.g., Davidian curves, Empirical histograms, etc) then passing use_dentype_estimate = TRUE will use the internally saved quadrature and density components (where applicable).

Usage

## S4 method for signature 'SingleGroupClass'
residuals(
  object,
  type = "LD",
  p.adjust = "none",
  df.p = FALSE,
  approx.z = FALSE,
  full.scores = FALSE,
  QMC = FALSE,
  printvalue = NULL,
  tables = FALSE,
  verbose = TRUE,
  Theta = NULL,
  suppress = NA,
  theta_lim = c(-6, 6),
  quadpts = NULL,
  fold = TRUE,
  upper = TRUE,
  technical = list(),
  ...
)

Arguments

object	an object of class SingleGroupClass or MultipleGroupClass. Bifactor models are automatically detected and utilized for better accuracy
type	type of residuals to be displayed. Can be either 'LD' or 'LDG2' for a local dependence matrix based on the X2 or G2 statistics (Chen & Thissen, 1997), 'Q3' for the statistic proposed by Yen (1984), 'JSI' for the jack-knife statistic proposed Edwards et al. (2018), 'exp' for the expected values for the frequencies of every response pattern, and 'expfull' for the expected values for every theoretically observable response pattern. For the 'LD' and 'LDG2' types, the upper diagonal elements represent the standardized residuals in the form of signed Cramers V coefficients
p.adjust	method to use for adjusting all p-values (see p.adjust for available options). Default is 'none'
df.p	logical; print the degrees of freedom and p-values?
approx.z	logical; transform \chi^2(df) information from LD tests into approximate z-ratios instead using the transformation z=\sqrt{2 * \chi^2} - \sqrt{2 * df - 1}?
full.scores	logical; compute relevant statistics for each subject in the original data?
QMC	logical; use quasi-Monte Carlo integration? If quadpts is omitted the default number of nodes is 5000
printvalue	a numeric value to be specified when using the res='exp' option. Only prints patterns that have standardized residuals greater than abs(printvalue). The default (NULL) prints all response patterns
tables	logical; for LD type, return the observed, expected, and standardized residual tables for each item combination?
verbose	logical; allow information to be printed to the console?
Theta	a matrix of factor scores used for statistics that require empirical estimates (i.e., Q3). If supplied, arguments typically passed to fscores() will be ignored and these values will be used instead
suppress	a numeric value indicating which parameter local dependency combinations to flag as being too high (for LD, LDG2, and Q3 the standardize correlations are used; for JSI, the z-ratios are used). Absolute values for the standardized estimates greater than this value will be returned, while all values less than this value will be set to missing
theta_lim	range for the integration grid
quadpts	number of quadrature nodes to use. The default is extracted from model (if available) or generated automatically if not available
fold	logical; apply the sum 'folding' described by Edwards et al. (2018) for the JSI statistic?
upper	logical; which portion of the matrix (upper versus lower triangle) should the suppress argument be applied to?
technical	list of technical arguments when models are re-estimated (see mirt for details)
...	additional arguments to be passed to fscores()

References

Chalmers, R., P. (2012). mirt: A Multidimensional Item Response Theory Package for the R Environment. Journal of Statistical Software, 48(6), 1-29. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.18637/jss.v048.i06")}

Chen, W. H. & Thissen, D. (1997). Local dependence indices for item pairs using item response theory. Journal of Educational and Behavioral Statistics, 22, 265-289.

Edwards, M. C., Houts, C. R. & Cai, L. (2018). A Diagnostic Procedure to Detect Departures From Local Independence in Item Response Theory Models. Psychological Methods, 23, 138-149.

Yen, W. (1984). Effects of local item dependence on the fit and equating performance of the three parameter logistic model. Applied Psychological Measurement, 8, 125-145.

Examples

## Not run: 

x <- mirt(Science, 1)
residuals(x)
residuals(x, tables = TRUE)
residuals(x, type = 'exp')
residuals(x, suppress = .15)
residuals(x, df.p = TRUE)
residuals(x, df.p = TRUE, p.adjust = 'fdr') # apply FWE control

# Pearson's X2 estimate for goodness-of-fit
full_table <- residuals(x, type = 'expfull')
head(full_table)
X2 <- with(full_table, sum((freq - exp)^2 / exp))
df <- nrow(full_table) - extract.mirt(x, 'nest') - 1
p <- pchisq(X2, df = df, lower.tail=FALSE)
data.frame(X2, df, p, row.names='Pearson-X2')

# above FOG test as a function
PearsonX2 <- function(x){
   full_table <- residuals(x, type = 'expfull')
   X2 <- with(full_table, sum((freq - exp)^2 / exp))
   df <- nrow(full_table) - extract.mirt(x, 'nest') - 1
   p <- pchisq(X2, df = df, lower.tail=FALSE)
   data.frame(X2, df, p, row.names='Pearson-X2')
}
PearsonX2(x)


# extract results manually
out <- residuals(x, df.p = TRUE, verbose=FALSE)
str(out)
out$df.p[1,2]

# with and without supplied factor scores
Theta <- fscores(x)
residuals(x, type = 'Q3', Theta=Theta)
residuals(x, type = 'Q3', method = 'ML')

# Edwards et al. (2018) JSI statistic
N <- 250
a <- rnorm(10, 1.7, 0.3)
d <- rnorm(10)
dat <- simdata(a, d, N=250, itemtype = '2PL')

mod <- mirt(dat, 1)
residuals(mod, type = 'JSI')
residuals(mod, type = 'JSI', fold=FALSE) # unfolded

# LD between items 1-2
aLD <- numeric(10)
aLD[1:2] <- rnorm(2, 2.55, 0.15)
a2 <- cbind(a, aLD)
dat <- simdata(a2, d, N=250, itemtype = '2PL')

mod <- mirt(dat, 1)

# JSI executed in parallel over multiple cores
if(interactive()) mirtCluster()
residuals(mod, type = 'JSI')


## End(Not run)

mirt documentation built on Sept. 11, 2024, 7:14 p.m.