Title: | Rasch Models -- eXtensions |
---|---|
Description: | Extend Rasch and Item Response Theory (IRT) analyses by providing tools for post-processing the output from five major IRT packages (i.e., 'eRm', 'psychotools', 'ltm', 'mirt', and 'TAM'). The current version provides the plotPIccc() function, which extracts from the return object of the originating package all information required to draw an extended Person-Item-Map (PIccc), showing any combination of * category characteristic curves (CCCs), * threshold characteristic curves (TCCs), * item characteristic curves (ICCs), * category information functions (CIFs), * item information functions (IIFs), * test information function (TIF), and the * standard error curve (S.E.). for uni- and multidimensional models (as far as supported by each package). It allows for selecting dimensions, items, and categories to plot and offers numerous options to adapt the output. The return object contains all calculated values for further processing. |
Authors: | Milica Kabic [aut], Rainer W. Alexandrowicz [aut, cre] |
Maintainer: | Rainer W. Alexandrowicz <[email protected]> |
License: | GPL (>= 3) |
Version: | 0.1-6 |
Built: | 2024-12-11 07:20:24 UTC |
Source: | CRAN |
Description: A data set simulated after a students survey of the BIG 5 (Openness [O], Conscienciousness [C], Extraversion [E], Agreeableness [A], and Neuroticism [N]). The scale comprises 21 items following the structure of the BFIK (DOI 10.1026/0012-1924.51.4.195).
big5
big5
A data.frame with 1076 rows and 21 columns.
The items were originally presented in German. Here is a rough translation (untested):
[E] I ... am rather reserved.
[A] I ... tend to criticize others.
[C] I ... complete tasks thoroughly.
[N] I ... get depressed easily, depressed.
[O] I ... am interested in many things.
[E] I ... am enthusiastic and can easily carry others away.
[A] I ... trust others easily, believe in the good in people.
[C] I ... am comfortable, tend to laziness.
[N] I ... am relaxed, do not let stress upset me.
[O] I ... am profound, like to think about things.
[E] I ... am rather the 'quiet type', taciturn.
[A] I ... can act cold and distant.
[C] I ... am efficient and work briskly.
[N] I ... worry a lot.
[O] I ... have an active imagination, am imaginative.
[E] I ... go out of myself, am sociable.
[A] I ... can be brusque and dismissive towards others.
[C] I ... make plans and carry them out.
[N] I ... get nervous and insecure easily.
[O] I ... appreciate artistic and aesthetic impressions.
[O] I ... have little artistic interest.
The response format of all items was:
very inapplicable
rather inapplicable
neither-nor
rather true
very true
library(RMX) summary(big5)
library(RMX) summary(big5)
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.
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 )
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 )
resobj |
Result object of originating package. Compatible packages
are |
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:
Multiple types may be plotted simultaneously
if only one item is selected. ( |
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
|
plab |
Labels of person parameter diagramm:
|
dsel |
Dimension selection. Same principle as for |
dlab |
Provide dimension labels for plotting. See |
lmar |
Left margin (in lines). |
ylas |
Specify alignment of the y-axis labels (e.g. |
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
|
gsort |
Global sort. If |
infomax |
Vertical scaling of information curves (i.e., CIF, IIF, and BIF). Takes either one of the keywords
|
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 |
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
|
infcol |
Specify a separate color for the item information function
curve (default: |
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 |
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 |
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 |
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 |
src |
If |
grid |
If |
classical |
If |
plot |
Plot the diagram (default: |
extwin |
(logical) Draw diagram(s) into an external window (for
better compatibility with RStudio and drawing to an external
file (pdf, png, ...); default: |
resetpar |
Reset graphics parameter (default: |
debug |
(logical) Print call stack (might help tracking error). |
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.
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.
Milica Kabic, Rainer W. Alexandrowicz
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>
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!
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!