plot.irtfit {irtQ}R Documentation

Draw Raw and Standardized Residual Plots

Description

This method provides graphical displays of the residuals between observed data and model-based predictions (Hambleton et al., 1991). For each score category of an item, it generates two types of residual plots: (a) the raw residual plot and (b) the standardized residual plot. Note that for dichotomous items, residual plots are drawn only for score category 1.

Usage

## S3 method for class 'irtfit'
plot(
  x,
  item.loc = NULL,
  type = "both",
  ci.method = c("wald", "wilson", "wilson.cr"),
  show.table = TRUE,
  layout.col = 2,
  xlab.text,
  ylab.text,
  main.text,
  lab.size = 15,
  main.size = 15,
  axis.size = 15,
  line.size = 1,
  point.size = 2.5,
  strip.size = 12,
  ylim.icc = c(0, 1),
  ylim.sr.adjust = FALSE,
  ylim.sr = c(-4, 4),
  ...
)

Arguments

x

x An object of class irtfit obtained from irtfit().

item.loc

An integer specifying the position of the item to be plotted (i.e., the nth item in the item set). See Details below.

type

A character string indicating the type of residual plot to be displayed. Available options are:

  • "icc" for the raw residual plot

  • "sr" for the standardized residual plot

  • "both" for displaying both plots

Default is "both".

ci.method

A character string specifying the method used to compute confidence intervals for the raw residual plot. Available options are:

  • "wald" for the Wald method

  • "wilson" for the Wilson score interval

  • "wilson.cr" for the Wilson interval with continuity correction

Default is "wald". See Details below.

show.table

A logical value indicating whether to return the contingency table used for drawing the residual plots of the specified item. If TRUE, the function returns the same contingency table stored in the internal contingency.plot object of the irtfit object. Default is TRUE.

layout.col

An integer specifying the number of columns in the panel layout when plotting residuals for a polytomous item. Default is 2.

xlab.text

A character string specifying the title for the x-axis. If omitted, a default label is used.

ylab.text

A character string specifying the title for the y-axis. If type = "both", a character vector of length two can be provided, corresponding to the y-axis titles for the raw residual and standardized residual plots, respectively. If omitted, default labels are used.

main.text

A character string specifying the main title for the plot. If type = "both", a character vector of length two can be provided, corresponding to the main titles for the raw residual and standardized residual plots, respectively. If omitted, default titles are used.

lab.size

Numeric value specifying the font size of axis titles. Default is 15.

main.size

Numeric value specifying the font size of the plot title. Default is 15.

axis.size

Numeric value specifying the font size of axis tick labels. Default is 15.

line.size

Numeric value specifying the thickness of plot lines. Default is 1.

point.size

A numeric value specifying the size of points. Default is 2.5.

strip.size

A numeric value specifying the size of facet label text. Default is 12.

ylim.icc

A numeric vector of length two specifying the y-axis limits for the raw residual plot. Default is c(0, 1).

ylim.sr.adjust

Logical. If TRUE, the y-axis range for the standardized residual plot is automatically adjusted based on the maximum residual value for each item. If FALSE, the range is fixed according to the values specified in the ylim.sr argument. Default is FALSE.

ylim.sr

A numeric vector of length two specifying the y-axis limits for the standardized residual plot. Default is c(-4, 4).

...

Additional arguments passed to ggplot2::ggplot() from the ggplot2 package.

Details

All plots are generated using the ggplot2 package.

Once the IRT model fit analysis is completed using irtfit(), the resulting object of class irtfit can be used to draw raw and standardized residual plots.These plots are primarily based on the information stored in the internal object contingency.plot.

Because residual plots are generated for one item at a time, you must specify which item to evaluate by providing an integer value for the item.loc argument, indicating the item's position in the test form. For example, to draw residual plots for the third item, set item.loc = 3.

For the raw residual plot, the ci.method argument determines the method used to estimate confidence intervals. The available methods are:

For more information, see https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval. Note that the width of the confidence interval is governed by the \alpha-level specified in the alpha argument of the irtfit() function.

For the standardized residual plot, residuals exceeding the threshold specified in the overSR argument of the irtfit() function are displayed as circles. Residuals that do not exceed the threshold are displayed as crosses.

Value

This method displays the IRT raw residual plot, standardized residual plot, or both for the specified item. When show.table = TRUE, a contingency table used to generate the residual plots is also returned. See irtfit() for more details about the contingency table.

Author(s)

Hwanggyu Lim hglim83@gmail.com

References

Hambleton, R. K., Swaminathan, H., & Rogers, H. J. (1991).Fundamentals of item response theory. Newbury Park, CA: Sage.

Laplace, P. S. (1820).Theorie analytique des probabilites (in French). Courcier.

Newcombe, R. G. (1998). Two-sided confidence intervals for the single proportion: comparison of seven methods. Statistics in medicine, 17(8), 857-872.

Wilson, E. B. (1927). Probable inference, the law of succession, and statistical inference. Journal of the American Statistical Association, 22(158), 209-212.

See Also

irtfit()

Examples

## Import the "-prm.txt" output file from flexMIRT
flex_sam <- system.file("extdata", "flexmirt_sample-prm.txt", package = "irtQ")

# Select the first two dichotomous items and the last polytomous item
x <- bring.flexmirt(file = flex_sam, "par")$Group1$full_df[c(1:2, 55), ]

# Generate examinees' abilities from N(0, 1)
set.seed(23)
score <- rnorm(1000, mean = 0, sd = 1)

# Simulate response data
data <- simdat(x = x, theta = score, D = 1)


# Compute fit statistics
fit <- irtfit(
  x = x, score = score, data = data, group.method = "equal.freq",
  n.width = 11, loc.theta = "average", range.score = c(-4, 4), D = 1,
  alpha = 0.05, overSR = 1.5
)

# Residual plots for the first item (dichotomous item)
plot(x = fit, item.loc = 1, type = "both", ci.method = "wald",
     show.table = TRUE, ylim.sr.adjust = TRUE)

# Residual plots for the third item (polytomous item)
plot(x = fit, item.loc = 3, type = "both", ci.method = "wald",
     show.table = FALSE, ylim.sr.adjust = TRUE)

# Raw residual plot for the third item (polytomous item)
plot(x = fit, item.loc = 3, type = "icc", ci.method = "wald",
     show.table = TRUE, ylim.sr.adjust = TRUE)

# Standardized residual plot for the third item (polytomous item)
plot(x = fit, item.loc = 3, type = "sr", ci.method = "wald",
     show.table = TRUE, ylim.sr.adjust = TRUE)



[Package irtQ version 1.0.0 Index]