plotPIccc: RMX Rasch Modeling Extended: A Visualisation Tool for IRT...

In RMX: Rasch Models -- eXtensions

RMX Rasch Modeling Extended: A Visualisation Tool for IRT Models

Description

Provides a customizable function plotPIccc(), which draws classical PImaps (Wright-Maps) with various graphical extensions, enabling the user to get quick and differentiated overview for psychometric analyses.

Usage

plotPIccc(
  resobj,
  pp = "auto",
  breaks = "Sturges",
  type = "CCC",
  tmin = -6,
  tmax = 6,
  isel = NULL,
  ilab = NULL,
  plab = c("none", "abs", "rel", "den"),
  dsel = NULL,
  dlab = NULL,
  lmar = 2,
  ylas = 0,
  showlab = c(1:3, 5:6),
  isort = "none",
  gsort = FALSE,
  infomax = "equal",
  height = 7,
  width = height * (sqrt(5) - 1)/2,
  funhprop = 0.7,
  funwprop = (sqrt(5) - 1)/2,
  main = NULL,
  csel = NULL,
  dimcol = c(grey(0.85), "steelblue1", "lightcoral", "orange", "lightgreen"),
  dencol = c(grey(0.5), "steelblue3", "indianred3", "darkorange2", "limegreen"),
  funcol = "Rstandard",
  infcol = "black",
  tifcol = "seagreen4",
  se_col = "firebrick4",
  bgcol = grey(0.9),
  gridcol = "white",
  usedimcol = FALSE,
  highlight = NULL,
  dens = FALSE,
  TIF = TRUE,
  sTIF = TRUE,
  SE = TRUE,
  sSE = TRUE,
  TIFmax = "auto",
  SEmax = "auto",
  funlty = 1,
  funlwd = 2,
  disind = "*",
  discol = grey(0.2),
  discex = 1.5,
  legend = TRUE,
  legoff = 0.1,
  legcex = 0.7,
  leglsp = 1,
  thrpch = 16,
  thrsup = TRUE,
  src = TRUE,
  grid = TRUE,
  classical = FALSE,
  plot = TRUE,
  extwin = NULL,
  resetpar = TRUE,
  debug = FALSE
)

Arguments

resobj	Result object of originating package. Compatible packages are eRm, psychotools, ltm, mirt, and TAM. Supported models are 1-4PL Models, RM, PCM, RSM, GPCM, GRM, GRSM, and NRM.
pp	Provide previously calculated person parameter estimates (practical if the estimation process is slow). In the multidimensional case person parameters need to be provided column wise in matrix form, i.e., first column = PP of first dimension, ...). If "auto" (default) the person parameters are determined using the default function of the originating package. The special option pp="skip" will omit the entire plot and prevent the call to person parameter estimation to speed up.
breaks	Adopted from the base R hist function. Used in the person parameter histogram.
type	The function type to plot. Possible options are: CCC, the Category Characteristic Curve (default), TCC, the Threshold Characteristic Curve, IIF, the Item Information Function, CIF, the Category Information Function, and BIF, both the Category and Item information curves. Multiple types may be plotted simultaneously if only one item is selected. (length(isel)==1).
tmin	Minimum of theta range to plot.
tmax	Maximum of theta range to plot.
isel	Item selection. Select items either by their index on each dimension or by their names. If an item is defined on multiple dimensions, all instances will be used.
ilab	Provide item labels (names) for plotting. Has priority over isel.
plab	Labels of person parameter diagramm: abs: absolute frequencies, rel: relative frequencies (in den: density estimate values, none: omit labels (default).
dsel	Dimension selection. Same principle as for isel.
dlab	Provide dimension labels for plotting. See ilab for more information.
lmar	Left margin (in lines).
ylas	Specify alignment of the y-axis labels (e.g. ylas=2. for horizontal labels).
showlab	Vector of options in the range are 0:6: 0 = show no axis labels, 1 = show outer x-axis (theta range) labels, 2 = show outer y-axis (item labels), 3 = show inner y-axis labels of item function diagrams, 4 = show y-axis labels of person parameter distribution, 5 = show y-axis labels of SE and sSE line, 6 = show y-axis labels of TIF and sTIF line, (default: 1:3).
isort	Sorting way may be specified. Possible options are mean, var, min, max, range, disc, lazy, guess, and none (default).
gsort	Global sort. If TRUE all items will be sorted across dimensions. If FALSE items will be sorted within dimensions.
infomax	Vertical scaling of information curves (i.e., CIF, IIF, and BIF). Takes either one of the keywords auto (maximize each plot) or equal (same scaling for all visible information functions), or a number indicating the maximum to be shown.
height	Specify the hight of the diagram window.
width	Width of the diagram (default: the golden ratio to the height).
funhprop	Proportions of the horizontal axis to be used for the function plots. The value of 1 will show only the functions, a value of 0 only the person parameters + legend(s).
funwprop	Proportion of the vertical axis to be used for the functions. A value of 1 will only draw the functions and person parameter histograms, and a value of 0 frequency barplots.
main	Title string (e.g., for question wording or scale name). If not NULL, the upper margin is set to 2, otherwise 0.
csel	Category selection. Select categories to draw by category indices. Only numerical values are allowed. This is merely a graphical option and has no effect on the calculation of related constructs (IIF or TIF). Do not combinde csel with highlight.
dimcol	Vector of dimension color for the person parameter histograms.
dencol	Vector of color for the person parameter density lines.
funcol	The color for functions and thresholds. Provide color vector or one of the predefined color schemes Rstandard (default), rainbow10 (up to 10 response categories), warm1 (up to 5 response categories), cool1 (up to 5 response categories), contrast1 (up to 5 response categories) or colorful1 (up to 5 response categories).
infcol	Specify a separate color for the item information function curve (default: black).
tifcol	Specify color of the test information function (TIF).
se_col	Specify color of the standard error function.
bgcol	Background color of function plot areas.
gridcol	Grid color in function plots.
usedimcol	Use dimension colors for threshold points (classical only).
highlight	Numerical vector containing the category numbers to be highlighted (the others will be drawn in grey). Do not combine highlight with csel.
dens	Draw kernel density estimate of person parameter distribution (default: TRUE).
TIF	Draw test information function (default: TRUE).
sTIF	Draw test information function of selected items (default: TRUE).
SE	Draw standard error function (default: TRUE).
sSE	Draw standard error function of selected items (default: TRUE).
TIFmax	Maximum of test information function (default: "auto").
SEmax	Maximum of standard error function (default: "auto").
funlty	Line type of the functions, see type.
funlwd	Line width of the functions.
disind	Disordering indicator (default: "*").
discol	Color of the threshold disorder indicator (default: "red")
discex	Size of the threshold disorder indicator (default: 1.5)
legend	If TRUE (default) insert legend.
legoff	Legend offset (vertical) from top margin (default: 0.1)
legcex	Legend text size.
leglsp	Legend line spacing.
thrpch	Threshold point character mark may be set.
thrsup	If TRUE (default) plot threshold supporting lines.
src	If TRUE write the originating package and the estimated model in the bottom right corner.
grid	If TRUE (default) draw a grid in the function area.
classical	If TRUE plot the classical person-item map.
plot	Plot the diagram (default: TRUE)
extwin	(logical) Draw diagram(s) into an external window (for better compatibility with RStudio and drawing to an external file (pdf, png, ...); default: FALSE).
resetpar	Reset graphics parameter (default: TRUE). If FALSE, the diagram coordinates remain, so that further annotations can be made to the diagram (see Details).
debug	(logical) Print call stack (might help tracking error).

Details

See Preston & Reise (2013) for the definition and interpretation of the category boundary discrimination (CBD) and threshold characteristic curves (TCCs) in NRM. See de Ayala (1993) for the definition of the intersections in the NRM. See Samejima (1969) for the definition of the category information curve. For references concerning the supported models see the originating packages' documentation.

The resetpar=FALSE option keeps the actual graphics parameters used for drawing the diagram. It allows for adding further graphic elements like text annotations or auxiliary lines (e.g., a vertical zero-line with abline(v=0)). It should prove useful especially for the horizontal axis, as the theta-scale remains active. The default TRUE returns to the R-defaults (margins, scale, ...)

Note that using one of the internal palette definitions (e.g., warm1), will also set the color of the information function (infcol).

Note for R-Studio users: Setting extwin=TRUE will allow for defining the graphics window's exact size. Note further that the new graphics window will open in the back of the R-Studio.

Value

plotPIccc returns a nested list containing:

• one list element per dimension. Named by default F1, F2, ..., but can be changed with the dlab= option.

• the element freq with the response frequencies of each item, and

• sortvec with the positions of the items as displayed.

It further contains the attributes

• source, indicating the package used for parameter estimation and the model,

• pp, a matrix with the estimated person parameters (used for avoiding re-estimation if plotPIccc is repeatedly called,

• data, the data set as returned from the originating package

• theta, the vector used for the horizontal axis.

Author(s)

Milica Kabic, Rainer W. Alexandrowicz

References

Preston, K. S. J. & Reise, S. P. (2013). Estimating the Nominal Response Model Under Nonnormal Conditions. Educational and Psychological Measurement, 74(3) 377–399. <doi:10.1177/0013164413507063> de Ayala, R. J. (1993). An introduction to polytomous item response theory models. Measurement and Evaluation in Counseling and Development, 25(4), 172–189. <https://psycnet.apa.org/record/1993-28125-001> Samejima, F. (1969). Estimation of latent ability using a response pattern of graded scores. Psychometrika 34 (Supplement 1), 1–97. <doi:10.1007/BF03372160>

Examples

library(RMX)
data(big5)

  dat_extra = big5[,c(1,6,11,16)]
  dat_agree = big5[,c(2,7,12,17)]
  dat_consc = big5[,c(3,8,13,18)]
  dat_neuro = big5[,c(4,9,14,19)]

library(eRm)

# Note: each feature is accessible with each package!

# 1 --- PCM with eRm (Extraversion)

 res0 = PCM(dat_extra)                    # PCM

 plotPIccc(res0)

# 1.1 How to select only items Q6 and Q16?
 plotPIccc(res0, isel=c("Q6", "Q16"))
 plotPIccc(res0, isel=c(2,4))

# 1.2 Turn off the Test Item Information (TIF)
 plotPIccc(res0, isel=c(2,4), TIF=FALSE)

# 1.3 Turn off the selected Test Item Information (sTIF)
 plotPIccc(res0, isel=c(2,4), TIF=FALSE, sTIF=FALSE)

# 1.4 Change color of functions and thresholds
 plotPIccc(res0, funcol="warm1")

# 1.5 Create classical PImap
 plotPIccc(res0, funcol="warm1", classical=TRUE)

# examples might take a few seconds
# 2 --- GRM with mirt (Agreeableness)

library(mirt)

 res1 = mirt(dat_agree, 1, "graded")      # GRM

 plotPIccc(res1)

# 2.1 Sort the items according to their discrimination par (\alpha)
 plotPIccc(res1, isort = "disc")

# 2.2 Show category + item information Functions
 plotPIccc(res1, type="BIF")

# 2.3 "Zoom in" to see how item infotmation categories behave
 plotPIccc(res1, type="BIF", infomax="auto")

# 2.4 Pick your PIccc
# ... only item functions and barplots
 plotPIccc(res1, type="BIF", funhprop = 1)

# ... only item functions
 plotPIccc(res1, type="BIF", funhprop = 1, funwprop = 1)

# ... only barplots
 plotPIccc(res1, type="BIF", funhprop = 1, funwprop = 0)

# ... only person parameters
 plotPIccc(res1, type="BIF", funhprop = 0, funwprop = 1)

# 2.5 Customise person part of the diagram
 plotPIccc(res1, type="BIF", funhprop = 0, funwprop = 1, breaks=20,
           tmin=-3, tmax=3, se_col = 1, TIF=FALSE, src=FALSE, dimcol="#40E0D0",
           main="Person Parameters with SE")

# 3 --- GPCM with TAM (Conscienciousness)

library(TAM)

 res2 = tam.mml.2pl(dat_consc, verbose=FALSE,,control=list(maxiter=20)) # 2PL

 plotPIccc(res2)

# 3.1 higlight category 3
 plotPIccc(res2, highlight = 3)

# 3.2 select only category 4
 plotPIccc(res2, csel = 4)

# 3.3 hide threshold points
 plotPIccc(res2, csel = 4, thrpch = "")

# 3.4 show detailed analysis of Item Q3
 plotPIccc(res2, isel = 1, type = c("CCC", "TCC", "BIF"))

# 4 --- NRM with mirt (Neuroticism)

 res3 = mirt(dat_neuro, 1, "nominal")     # NRM

 plotPIccc(res3,isel=1:2)

# 4.1 ordinality check with NRM (CBD Parameter; see Reise et al. 2021)
 plotPIccc(res3, isel=3:4, type="TCC") # Discrimination parameters of TCCs = CBD!

RMX documentation built on Sept. 11, 2024, 8:38 p.m.