| Title: | A Collection of Functions Related to Item Response Theory (IRT) |
|---|---|
| Description: | A collection of functions useful in learning and practicing IRT, which can be combined into larger programs. Provides basic CTT analysis, a simple common interface to the estimation of item parameters in IRT models for binary responses with three different programs (ICL, BILOG-MG, and ltm), ability estimation (MLE, BME, EAP, WLE, plausible values), item and person fit statistics, scaling methods (MM, MS, Stocking-Lord, and the complete Hebaera method), and a rich array of parametric and non-parametric (kernel) plots. Estimates and plots Haberman's interaction model when all items are dichotomously scored. |
| Authors: | Ivailo Partchev [aut, cre], Gunter Maris [aut], Tamaki Hattori [ctb] |
| Maintainer: | Ivailo Partchev <[email protected]> |
| License: | GPL (>= 2) |
| Version: | 0.2.2 |
| Built: | 2024-11-02 06:32:47 UTC |
| Source: | CRAN |
| Package: | irtoys |
| Type: | Package |
| Version: | 0.2.0 |
| Date: | 2016-01-30 |
| License: | GPL (>= 2) |
| LazyLoad: | yes |
| LazyData: | yes |
The irtoys package contains a bunch of functions potentially useful
to those teaching or learning Item Response Theory (IRT). R being
particularly good at graphics, there is a rich array of plotting
functions to visualize IRT models or assess their fit. Ability estimates
can be estimated by MLE, BME, EAP, WLE. Various IRT scaling methods are supported:
MM, MS, Stocking-Lord, and Hebaera. Last not least, irtoys may be
the only package to estimate Haberman's interaction model, although a new and
more powerful package is in the making.
Currently, there are several R packages that can estimate the item parameters
in various uni- and multidimensional IRT models, but only several years ago one
had to use stand-alone programs that had wildly different and
often unwieldy user interfaces. Besides, no single program does everything
one needs. One of the original purposes of irtoys was to provide a
simple and unified interface to some of the most basic
functions in ICL, BILOG, and R's own ltm, such that beginners could
concentrate on learning IRT rather than syntaxes. Once that these steps
have been made, those wishing to take
advantage of the full functionality of ICL, BILOG & Co. must still master
the syntax of their program of choice.
To take full advantage of irtoys, some IRT software is needed.
Package ltm is automatically loaded. ICL by Brad Hanson can be
downloaded from his site, http://www.openirt.com/b-a-h/software/.
Executables and a very detailed manual (not needed to use ICL with
irtoys are provided for Windows, Linux, and Macintosh. The Mac
version probably does not work with the current OS versions but I still
use the Windows and Linux versions without any problem.
BILOG is commercial software sold by SSI — see https://ssicentral.com/ for further detail.
On Windows, make sure that the executable files (icl.exe for ICL,
BLM1.EXE, BLM2.EXE, and BLM3.EXE for BILOG) are located
in a directory that is included in the PATH variable. On Linux, BILOG,
being a Windows program, is run with wine, and should also be on a
path where wine can find it. On my machine, I have simply put the three
files in ~/.wine/drive_c/windows/. It seems that new versions of wine
expect them to be explicitly tagged as executable. On Macintosh, at least
ltm should work in all cases.
NOTE: Starting with version 0.2.0, function est returns a list of three
elements: est contains the parameter estimates and is thus identical
to the output in earlier versions, se contains the standard errors,
in a similar format, and vcm contains the variance-covariance matrices
(NULL when using ICL). When passing item parameters to another function that
only needs the estimates, irf(ip) and
irf(ip$est) can be used interchangeably. This facilitates using simulated
item parameters. A function that does require the complete object is .
Also, function itf now returns item fit statistics
as a vector rather than a list. Finally, since most of the functions in irtoys
have been written with the "logistic" metric in mind (i.e.,
rather than , function est now estimates item
parameters only in the logistic metric.
Ivailo Partchev <[email protected]>
S. E. Embretson and S. P. Reise (2000), Item Response Theory for Psychologists, Lawrence Erlbaum Associates, Mahwah, NJ
A wrapper around all functions for ability estimation
ability(resp, ip, method = "WLE", mu = 0, sigma = 1, n = 5)ability(resp, ip, method = "WLE", mu = 0, sigma = 1, n = 5)
resp |
A matrix of responses: persons as rows, items as columns, entries are either 0 or 1, no missing data |
ip |
Item parameters: the object returned by |
method |
One of: "MLE", "BME", "WLE", "EAP", "PV", "QRS", "SUM" |
mu |
Mean of the apriori distribution when applicable |
sigma |
Standard deviation of the apriori distribution when applicable
|
n |
The number of plausible values to draw for each person (default is 5). |
Depends on the method.
Ivailo Partchev
theta <- ability(resp=Scored, method="WLE", ip=Scored2pl)theta <- ability(resp=Scored, method="WLE", ip=Scored2pl)
Computes the api appropriateness index, a measure of person fit in IRT models
api(resp, ip, theta)api(resp, ip, theta)
resp |
A matrix of responses: persons as rows, items as columns, entries are either 0 or 1, no missing data |
ip |
Item parameters: the object returned by |
theta |
A measure of ability, typically produced with |
A vector of length equal to the number of rows in resp,
containing the appropriateness indices
Ivailo Partchev
Drasgow, F., Levine, M. V., & Williams, E. A. (1985). Appropriateness measurement with polychotomous item response models and standardized indices. British Journal of Mathematical and Statistical Psychology, 38, 67–80
api(Scored, Scored2pl)api(Scored, Scored2pl)
Item parameter estimates for the 1PL model, estimated with bilog from
the example data set Scored. These are provided because not users will
have BILOG-MG available.
The object returned by est
Item parameter estimates for the 2PL model, estimated with bilog from
the example data set Scored. These are provided because not users will
have BILOG-MG available.
The object returned by est
Item parameter estimates for the 3PL model, estimated with bilog from
the example data set Scored. These are provided because not users will
have BILOG-MG available.
The object returned by est
Draws (by rejection sampling) plausible values from the posterior distribution of ability
dpv(resp, ip, mu = 0, sigma = 1, n = 5)dpv(resp, ip, mu = 0, sigma = 1, n = 5)
resp |
A matrix of responses: persons as rows, items as columns, entries are either 0 or 1, no missing data |
ip |
Item parameters: the object returned by |
mu |
Mean of the apriori distribution. Default is 0. |
sigma |
Standard deviation of the apriori distribution. Ignored when
|
n |
The number of plausible values to draw for each person (default is 5). |
A matrix with n columns
Ivailo Partchev
plval <- dpv(resp=Scored, ip=Scored2pl)plval <- dpv(resp=Scored, ip=Scored2pl)
Estimates the expectation of the posterior distribution of the latent variable ("ability") for each person.
eap(resp, ip, qu)eap(resp, ip, qu)
resp |
A matrix of responses: persons as rows, items as columns, entries are either 0 or 1, no missing data |
ip |
Item parameters: the object returned by |
qu |
A quadrature object produced with |
A matrix with the ability estimates in column 1, and their standard errors of measurement (SEM) in column 2, and the number of non-missing reponses in column 3
Ivailo Partchev
mlebme, normal.qu,
read.qu.icl
th.eap <- eap(resp=Scored, ip=Scored2pl, qu=normal.qu())th.eap <- eap(resp=Scored, ip=Scored2pl, qu=normal.qu())
Produces a plot of the empirical response function (proportion of correct responses at each possible sum score).
erf(resp, item)erf(resp, item)
resp |
A matrix of binary responses to a test, with persons as rows and items as columns. |
item |
The item (column number in |
None
Ivailo Partchev
erf(Scored, 3)erf(Scored, 3)
Estimate IRT item parameters using either ICL, BILOG, or ltm.
Provides access to the most widely used options in these programs.
est( resp, model = "2PL", engine = "icl", omitsWrong = FALSE, nqp = 20, est.distr = FALSE, nch = 5, a.prior = TRUE, b.prior = FALSE, c.prior = TRUE, bilog.defaults = TRUE, rasch = FALSE, run.name = "mymodel" )est( resp, model = "2PL", engine = "icl", omitsWrong = FALSE, nqp = 20, est.distr = FALSE, nch = 5, a.prior = TRUE, b.prior = FALSE, c.prior = TRUE, bilog.defaults = TRUE, rasch = FALSE, run.name = "mymodel" )
resp |
A matrix of responses: persons as rows, items as columns, entries are either 0 or 1, no missing data |
model |
The IRT model: "1PL", "2PL", or "3PL". Default is "2PL". |
engine |
One of "icl", "bilog", or "ltm". Default is "icl". |
omitsWrong |
If TRUE, all omitted items will be recoded as wrong responses, otherwise they will be treated as missing (default) |
nqp |
Number of quadrature points. Default is 20. |
est.distr |
T if the probabilities of the latent distribution are to be
estimated, F if a normal distribution is assumed. Default is F. Ignored when
|
nch |
Number of choices in the original item formulation. Used to
determine the prior for the asymptote when |
a.prior |
Whether a prior for the item discriminations is used. Ignored
when |
b.prior |
Whether a prior for the item difficulties is used. Ignored
when |
c.prior |
Whether a prior for the asymptotes is used. Ignored when
|
bilog.defaults |
When |
rasch |
When |
run.name |
A (short) string used in the names of all files read or
written by ICL or BILOG. Default is |
Estimate the parameters of an IRT model defined in the most general case ("3PL") as
where is a binary response given by person to item
, is the value of the latent variable ("ability") for
person , is the discrimination parameter for item ,
is the difficulty parameter for item , is the
asymptote for item .
Some authors prefer to represent the model with a logit
rather than . This option has been removed from irtoys
as it is not supported by the remaining functions of the package.
In the 2PL model (model="2PL"), all asymptotes are 0. In
the 1PL model (model="1PL"), all asymptotes are 0 and the
discriminations are equal for all items (and sometimes to 1).
Package irtoys provides a simple common interface to the estimation
of item parameters with three different programs. It only accesses the most
basic and widely used options in these programs. Each of the three programs
has a much wider choice of options and cababilities, and serious users must
still learn the corresponding syntax in order to access the advanced
features. Even when models are fit "by hand", irtoys may be useful
in plotting results, doing comparisons across programs etc.
Estimation of the more complex IRT models (2PL and 3PL) for some "difficult"
data sets often has to use prior distributions for the item parameters.
irtoys adopts the default behaviour of BILOG: no priors for
in any model, priors for in the 2PL and 3PL models, priors for
in the 3PL model. This can be overriden by changing the values of
a.prior, b.prior, and c.prior.
If priors are used at all, they will be the same for all items. Note that
both ICL and BILOG can, at some additional effort, set different priors for
any individual item. At default, the common priors are the BILOG defaults:
normal(0,2) for , lognormal (0, 0.5) for , and
beta(20*p+1, 20(1-p)+1) for ; is 1 over the number of
choices in the original item formulations, which can be set with the
parameter nch, and is again assumed the same for all items.
When engine="icl" and bilog.defaults=F, any priors used will
be the ICL default ones, and based on the 4-parameter beta distribution:
beta(1.01, 1.01, -6, 6) for , beta(1.75, 3, 0, 3) for
, and beta(3.5, 4, 0, 0.5) for . When
engine="ltm", all commands involving priors are ignored.
est only works when some IRT software is installed. Package
ltm is automatically loaded. ICL can be downloaded from
http://www.openirt.com/b-a-h/software/.
BILOG is commercial software sold by SSI — see
https://ssicentral.com/ for further detail. On Windows, make sure that the
executable files (icl.exe for ICL, blm1.exe, blm2.exe,
and blm3.exe, for BILOG) are located in directories that are included
in the PATH variable.
A list with three elements: est and se are
matrices containing the parameter estimates and their standard errors, correspondingly.
Each matrix has three columns: [,1] item
discrimination , [,2] item difficulty , and [,3] asymptote
. For the 1PL and 2PL models, all asymptotes are equal to 0; for the
1PL, the discriminations are all equal but not necessarily equal to 1. The third
element, vcm, is a list of variance-covariance matrices for the item
parameters. Currently, vcm is only used in function irfPlot.
When ICL is used as estimation engine, se and vcm are NULL as ICL does not
compute standard errors for the item parameter estimates.
Ivailo Partchev
p.1pl <- est(Scored, model="1PL", engine="ltm") p.2pl <- est(Scored, model="2PL", engine="ltm")p.1pl <- est(Scored, model="1PL", engine="ltm") p.2pl <- est(Scored, model="2PL", engine="ltm")
The item information function (IIF) for the 3PL model can be computed as
where
is the value of the latent variable for a person, is
the discrimination parameter for the item, is the IRF for the person
and item, and . For the 1PL and 2PL models, the expression
reduces to .
iif(ip, items = NULL, x = NULL)iif(ip, items = NULL, x = NULL)
ip |
Item parameters: the output of |
items |
The item(s) for which the information function is computed. If NULL (the default), irf for all items will be returned |
x |
The values of the latent variable ( |
A common use of this function would be to obtain a plot of the IIF.
A list of:
x |
A copy of the argument |
f |
A
matrix containing the IIF values: persons (values of ( |
Ivailo Partchev
plot(iif(Scored2pl, items=1:3))plot(iif(Scored2pl, items=1:3))
Estimates the parameters of the interaction model. The plots can be produced with the appropriate plotting method.
interactionModel(x, eps = 0.1, rasch = FALSE)interactionModel(x, eps = 0.1, rasch = FALSE)
x |
A matrix of responses: persons as rows, items as columns, entries are either 0 or 1, no missing data |
eps |
Convergence criterion, default is 1e-1 |
rasch |
if TRUE, the Rasch model will be estimated instead. |
A matrix
Ivailo Partchev, using C code and theory by Gunter Maris
Shelby Haberman. The interaction model. Chapter in: Mathias von Davier & Claus H. Carstensen (Eds.) (2007). Multivariate and Mixture Distribution Rasch Models. New York:Springer
Returns the item response function of the 3PL (1PL, 2PL) model, the i.e. the probabilities defined by
where is a binary response given by person to item
, is the value of the latent variable ("ability") for
person , is the discrimination parameter for item ,
is the difficulty parameter for item , is the
asymptote for item . Some authors call the IRF "the item characteristic curve".
irf(ip, items = NULL, x = NULL)irf(ip, items = NULL, x = NULL)
ip |
Item parameters: the output of |
items |
The item(s) for which irf is computed. If NULL (the default), irf for all items will be returned |
x |
The values of the latent variable ( |
In the 2PL model (model="2PL"), all asymptotes are 0. In
the 1PL model (model="1PL"), all asymptotes are 0 and the
discriminations are equal for all items (and sometimes to 1).
A common use of this function would be to obtain a plot of the IRF.
A list of:
x |
A copy of the argument |
f |
A
matrix containing the IRF values: persons (values of ( |
Ivailo Partchev
plot(irf(Scored2pl, item=1))plot(irf(Scored2pl, item=1))
Produces a plot that compares the estimated trace line (item response function)
for an item with the data. The data is represented with a non-parametric
trace line computed as in tgf (not npp). Approximate confidence
intervals for the parametric line are also shown.
irfPlot( resp, ip, x = NULL, item, main = "Parametric vs non-parametric trace line", use.sm = FALSE )irfPlot( resp, ip, x = NULL, item, main = "Parametric vs non-parametric trace line", use.sm = FALSE )
resp |
A matrix of responses: persons as rows, items as columns, entries are either 0 or 1, no missing data |
ip |
Item parameters: the object returned by function |
x |
A vector of abilities, as long as there are persons, against which to plot
probabilities of a correct response. Normally these would be the output of |
item |
The item for which a plot is requested (column of |
main |
The main title of the plot. |
use.sm |
When TRUE, empirical data will be shown with a regression estimated
by |
Comparing the outputs of npp and irf has at least two drawbacks:
(i) package sm is used as a black box, and (ii) the confidence intervals
are drawn around the data (even though represented by the nonparametric regression)
rather than the parametric curve. In this function, the parametric curve is shown in
red, with a 68
The non-parametric curve representing the data is shown in black. It is computed
by applying Bayes theorem to the density of ability.
The standard error of the parametric curve is computed by
applying the delta theorem on the standard error of the item parameters, as computed
by the underlying software (currently only available with ICL).
Ivailo Partchev
# a plot for item 5 irfPlot(Scored, ip=b3, item=4)# a plot for item 5 irfPlot(Scored, ip=b3, item=4)
Returns a statistic of item fit together with its degrees of freedom and p-value. Optionally produces a plot.
itf( resp, ip, item, stat = "lr", theta, standardize = TRUE, mu = 0, sigma = 1, bins = 9, breaks = NULL, equal = "count", type = "means", do.plot = TRUE, main = "Item fit" )itf( resp, ip, item, stat = "lr", theta, standardize = TRUE, mu = 0, sigma = 1, bins = 9, breaks = NULL, equal = "count", type = "means", do.plot = TRUE, main = "Item fit" )
resp |
A matrix of responses: persons as rows, items as columns, entries are either 0 or 1, no missing data |
ip |
Item parameters: the object returned by |
item |
A single number pointing to the item (column of |
stat |
The statistic to be computed, either |
theta |
A vector containing some viable estimate of the latent variable
for the same persons whose responses are given in |
standardize |
Standardize the distribution of ability estimates? |
mu |
Mean of the standardized distribution of ability estimates |
sigma |
Standard deviation of the standardized distribution of ability estimates |
bins |
Desired number of bins (default is 9) |
breaks |
A vector of cutpoints. Overrides |
equal |
Either |
type |
The points at which |
do.plot |
Whether to do a plot |
main |
The title of the plot if one is desired |
Given a long test, say 20 items or more, a large-test statistic of item fit could be constructed by dividing examinees into groups of similar ability, and comparing the observed proportion of correct answers in each group with the expected proportion under the proposed model. Different statistics have been proposed for this purpose.
The chi-squared statistic
where
is the number of examinees in group , , is
the number of correct responses to the item in group , and
is the IRF of the proposed model for the median ability in group
, is attributed by Embretson & Reise to R. D. Bock, although the
article they cite does not actually mention it. The statistic is the sum of
the squares of quantities that are often called "Pearson residuals" in the
literature on categorical data analysis.
BILOG uses the likelihood-ratio statistic
where is now the
IRF for the mean ability in group , and all other symbols are as
above.
Both statistics are assumed to follow the chi-squared distribution with
degrees of freedom equal to the number of groups minus the number of
parameters of the model (eg 2 in the case of the 2PL model). The first
statistic is obtained in itf with stat="chi", and the second
with stat="lr" (or not specifying stat at all).
In the real world we can only work with estimates of ability, not with
ability itself. irtoys allows use of any suitable ability measure
via the argument theta. If theta is not specified, itf
will compute EAP estimates of ability, group them in 9 groups having
approximately the same number of cases, and use the means of the ability
eatimates in each group. This is the approximate behaviour of BILOG.
If the test has less than 20 items, itf will issue a warning.
For tests of 10 items or less, BILOG has a special statistic of fit, which
can be found in the BILOG output. Also of interest is the fit in 2- and
3-way marginal tables in package ltm.
A vector of three numbers:
Statistic |
The value of the statistic of item fit |
DF |
The degrees of freedom |
P-value |
The p-value |
Ivailo Partchev
S. E. Embretson and S. P. Reise (2000), Item Response Theory for Psychologists, Lawrence Erlbaum Associates, Mahwah, NJ
M. F. Zimowski, E. Muraki, R. J. Mislevy and R. D. Bock (1996), BILOG–MG. Multiple-Group IRT Analysis and Test Maintenance for Binary Items, SSI Scientific Software International, Chicago, IL
fit <- itf(resp=Scored, ip=Scored2pl, item=7)fit <- itf(resp=Scored, ip=Scored2pl, item=7)
Estimates the value of the latent variable ("ability") for each person by direct optimization
mlebme(resp, ip, mu = 0, sigma = 1, method = "ML")mlebme(resp, ip, mu = 0, sigma = 1, method = "ML")
resp |
A matrix of responses: persons as rows, items as columns, entries are either 0 or 1, no missing data |
ip |
Item parameters: the object returned by |
mu |
Mean of the apriori distribution. Ignored when |
sigma |
Standard deviation of the apriori distribution. Ignored when
|
method |
|
A matrix with the ability estimates in column 1 and their standard errors of measurement (SEM) in column 2, and the number of non-missing responses in column 3
Ivailo Partchev
th.mle <- mlebme(resp=Scored, ip=Scored2pl)th.mle <- mlebme(resp=Scored, ip=Scored2pl)
Quadrature points and weights based on the Normal distribution. Quadrature
objects are used when estimating abilities with eap and for some of
the scaling methods in sca.
normal.qu(n = 15, lower = -4, upper = 4, mu = 0, sigma = 1, scaling = "points")normal.qu(n = 15, lower = -4, upper = 4, mu = 0, sigma = 1, scaling = "points")
n |
Number of quadrature points |
lower |
Lower boundary |
upper |
Upper boundary |
mu |
Mean |
sigma |
Standard deviation |
scaling |
Determines the way in which non-default values of |
A list of:
quad.points |
A vector of |
quad.weights |
A vector of the corresponding quadrature weights |
Ivailo Partchev
quad <- normal.qu(n=20)quad <- normal.qu(n=20)
A plotting routine producing non-parametric analogues of the IRF not unlike
those in Jim Ramsay's TestGraf program. The curves are produced by a kernel
binomial regression of the actual responses to an item on some estimates of
the latent variable, by courtesy of package sm.
npp( resp, x, items, from = -4, to = 4, co = 1, main = "Non-parametric response function", add = FALSE, bands = FALSE, label = FALSE )npp( resp, x, items, from = -4, to = 4, co = 1, main = "Non-parametric response function", add = FALSE, bands = FALSE, label = FALSE )
resp |
A matrix of responses: persons as rows, items as columns, entries are either 0 or 1, no missing data |
x |
The values of the latent variable ("ability") for the same persons
whose responses are given in |
items |
An index to the items (columns of |
from |
Lower limit for ability on the plot. Default is -4. |
to |
Upper limit for ability on the plot. Default is 4. |
co |
The colour of the curves. Default is 1 for black. Use |
main |
The main title of the plot, given that |
add |
When |
bands |
When |
label |
When |
Ivailo Partchev
James O. Ramsay (2000). TestGraf: A program for the graphical analysis of multiple choice test and questionnaire data. McGill University, Montreal, Canada
# plot items 1:5 in different colours, label npp(Scored, items=1:5, co=NA, label=TRUE) # For item 7, compare npp with the 2PL parametric IRF npp(Scored, items=7, bands=TRUE) plot(irf(ip=Scored2pl, items=7), co=3, add=TRUE)# plot items 1:5 in different colours, label npp(Scored, items=1:5, co=NA, label=TRUE) # For item 7, compare npp with the 2PL parametric IRF npp(Scored, items=7, bands=TRUE) plot(irf(ip=Scored2pl, items=7), co=3, add=TRUE)
Useful for plotting item information functions. The x argument of
iif should better be left out unless something special is required.
## S3 method for class 'iif' plot( x, add = FALSE, main = "Item information function", co = 1, label = FALSE, ... )## S3 method for class 'iif' plot( x, add = FALSE, main = "Item information function", co = 1, label = FALSE, ... )
x |
An object produced by function |
add |
When |
main |
The main title of the plot, given that |
co |
The colour of the IIF curve. Default is 1 for black. Use
|
label |
When |
... |
Any additional plotting parameters |
Ivailo Partchev
# plot IIF for all items in red, label with item number plot(iif(Scored2pl), co="red", label=TRUE) # plot IIF for items 2, 3, and 7 in different colours plot(iif(Scored2pl, items=c(2,3,7)), co=NA)# plot IIF for all items in red, label with item number plot(iif(Scored2pl), co="red", label=TRUE) # plot IIF for items 2, 3, and 7 in different colours plot(iif(Scored2pl, items=c(2,3,7)), co=NA)
Plot the item-total regressions fit by the interaction (or Rasch) model
## S3 method for class 'imp' plot( x, items = NULL, shade = 10, highlight = -Inf, add = FALSE, main = "Item-total regression", label = FALSE, ... )## S3 method for class 'imp' plot( x, items = NULL, shade = 10, highlight = -Inf, add = FALSE, main = "Item-total regression", label = FALSE, ... )
x |
An object produced by function |
items |
The items to plot (column numbers). If NULL, all items will be plotted |
shade |
The part of the probability mass for the sum scores to shade out,
shown as percentage. Default is 10: shade the most extreme 10
Ignored when |
highlight |
Cutpoint for the interaction parameter below which a regression line will be highlighted in red. Default is -Inf (do not highlight). |
add |
When |
main |
The main title of the plot, given that |
label |
When |
... |
Any additional plotting parameters |
Ivailo Partchev, using theory and C code by Gunter Maris
plot(interactionModel(Scored), highlight=-.3)plot(interactionModel(Scored), highlight=-.3)
Useful for plotting item response functions. The x argument of
irf should better be left out unless something special is required.
## S3 method for class 'irf' plot( x, add = FALSE, main = "Item response function", co = 1, label = FALSE, ... )## S3 method for class 'irf' plot( x, add = FALSE, main = "Item response function", co = 1, label = FALSE, ... )
x |
An object produced by function |
add |
When |
main |
The main title of the plot, given that |
co |
The colour of the IRF curve. Default is 1 for black. Use
|
label |
When |
... |
Any additional plotting parameters |
Ivailo Partchev
# plot IRF for all items in red, label with item number plot(irf(Scored2pl), co="red", label=TRUE) # plot IRF for items 2, 3, and 7 in different colours plot(irf(Scored2pl, items=c(2,3,7)), co=NA)# plot IRF for all items in red, label with item number plot(irf(Scored2pl), co="red", label=TRUE) # plot IRF for items 2, 3, and 7 in different colours plot(irf(Scored2pl, items=c(2,3,7)), co=NA)
Useful for plotting test information functions. The x argument of
tif should better be left out unless something special is required.
## S3 method for class 'tif' plot(x, add = FALSE, main = "Test information function", co = 1, ...)## S3 method for class 'tif' plot(x, add = FALSE, main = "Test information function", co = 1, ...)
x |
An object produced by function |
add |
When |
main |
The main title of the plot, given that |
co |
The colour of the TIF curve. Default is 1 for black. Use
|
... |
Any additional plotting parameters |
Ivailo Partchev
plot(tif(Scored2pl))plot(tif(Scored2pl))
Useful for plotting test response functions. The x argument of
trf should better be left out unless something special is required.
## S3 method for class 'trf' plot(x, add = FALSE, main = "Test response function", co = 1, ...)## S3 method for class 'trf' plot(x, add = FALSE, main = "Test response function", co = 1, ...)
x |
An object produced by function |
add |
When |
main |
The main title of the plot, given that |
co |
The colour of the TRF curve. Default is 1 for black. Use
|
... |
Any additional plotting parameters |
Ivailo Partchev
plot(trf(Scored2pl))plot(trf(Scored2pl))
A rough estimate of the values of the latent variable ("ability"). The sum
scores (number of correct responses) are ranked, breaking ties at random.
The ranks are divided by the sample size + 1, and the corresponding
quantiles of the standard Normal distribution are returned. Used as default
in the non-parametric IRF plots produced by npp in analogy to
Jim Ramsay's TestGraf. Another possible use is in itf.
qrs(resp)qrs(resp)
resp |
A matrix of responses: persons as rows, items as columns, entries are either 0 or 1, no missing data |
A one-column matrix of values
Ivailo Partchev
sc <- qrs(Scored)sc <- qrs(Scored)
From BILOG output, read in estimates of item parameters. Invoked
automatically when the model is estimated via irtoys. If that is not
the case, file must be a file produced with the >SAVE PARm
file; command in BILOG.
read.ip.bilog(file)read.ip.bilog(file)
file |
File name |
A list with three elements, est, se, vcm for the parameter
estimates, their standard errors, and the variance-covariance matrix per item.
The first two are matrices with one row per item, and three columns: [,1] item
discrimination , [,2] item difficulty , and [,3] asymptote
. For the 1PL and 2PL models, all asymptotes are equal to 0; for the
1PL, the discriminations are all equal but not necessarily equal to 1.
Ivailo Partchev
From ICL output, read in estimates of item parameters. Invoked automatically
when the model is estimated via irtoys. If that is not the case,
file must be a file produced with the write_item_param file
command in ICL.
read.ip.icl(file)read.ip.icl(file)
file |
File name |
A list with three elements, est, se, vcm for the parameter
estimates, their standard errors, and the variance-covariance matrix per item.
Because ICL does not
compute standard errors, se and vcm will be NULL. est is a matrix with
one row per item, and three columns: [,1] item
discrimination , [,2] item difficulty , and [,3] asymptote
. For the 1PL and 2PL models, all asymptotes are equal to 0; for the
1PL, the discriminations are all equal but not necessarily equal to 1.
Ivailo Partchev
From ICL output, read in estimates of item parameters. file must be a
file produced with the write_latent_dist file command in ICL.
Quadrature objects are used when estimating abilities with eap and
for some of the scaling methods in sca.
read.qu.icl(file)read.qu.icl(file)
file |
File name |
A list of:
quad.points |
A vector of quadrature points |
quad.weights |
A vector of the corresponding quadrature weights |
Ivailo Partchev
Reads responses to a questionnaire from a text file
read.resp(file, na = ".")read.resp(file, na = ".")
file |
File name |
na |
The symbol used to represent missing data |
Included for those who are too faint-hearted to write
as.matrix(read.table(file, head=F)). Of course, data can be entered
into R in many other ways.
The data values in the file must be separated with blanks.
Responses are the empirical data used in IRT. Note that irtoys deals
with models for dichotomous data, and typically expects data consisting of
zeroes and ones, without any missing values (non-responses are considered as
wrong responses). In fact, there are only two commands in irtoys that
accept other kinds of data: sco and tgf.
read.resp does accept missing data and values other than 0 and 1. Use
sco and a key to score multiple choice responses to 0/1. If you have
dichotomous data that contains NAs, you can use sco without a key to
change all NA to 0.
A matrix, typically of zeroes and ones, representing the correct or wrong responses given by persons (rows) to items (columns).
Ivailo Partchev
## Not run: r <- read.resp("c:/myfiles/irt.dat") ## End(Not run)## Not run: r <- read.resp("c:/myfiles/irt.dat") ## End(Not run)
Compare the item-total regressions fit by the Rasch model and the interaction model, for one, several, or all items in the test.
rim(x, items = NULL, showData = FALSE, shade = 10, ncol = 3, ...)rim(x, items = NULL, showData = FALSE, shade = 10, ncol = 3, ...)
x |
A matrix of scored responses (persons in rows, items in columns) |
items |
The items to plot (column numbers). If NULL, all items will be plotted |
showData |
If TRUE, the observed proportion correct at each sum score will be shown on the plot. Default is FALSE (show only the regressions) |
shade |
The part of the probability mass for the sum scores to shade out,
shown as percentage. Default is 10: shade the most extreme 10
Ignored when |
ncol |
When plotting multiple items, the user can suggest the number of columns in the matrix of plots (up to 3, will be adjusted if necessary) |
... |
Any additional plotting parameters |
Ivailo Partchev, using theory and C code by Gunter Maris
rim(Scored, items=2)rim(Scored, items=2)
Linearly transform a set of IRT parameters to bring them to the scale of another set of parameters. Four methods are implemented: Mean/Mean, Mean/Sigma, Lord-Stocking, and Haebara.
sca( old.ip, new.ip, old.items, new.items, old.qu = NULL, new.qu = NULL, method = "MS", bec = FALSE )sca( old.ip, new.ip, old.items, new.items, old.qu = NULL, new.qu = NULL, method = "MS", bec = FALSE )
old.ip |
A set of parameters that are already on the desired scale |
new.ip |
A set of parameters that must be placed on the same scale as
|
old.items |
A vector of indexes pointing to those items in
|
new.items |
The indexes of the same items in |
old.qu |
A quadrature object for |
new.qu |
A quadrature object for |
method |
One of "MM" (Mean/Mean), "MS" (Mean/Sigma), "SL" (Stocking-Lord), or "HB" (Haebara). Default is "MS" |
bec |
Use back-equating correction? When TRUE, the Stocking-Lord or Hebaera procedures will be adjusted for back-equating (see Hebaera, 1980). Ignored when method is MM or MS. Default is FALSE. |
A list of:
slope |
The slope of the linear transformation |
intercept |
The intercept of the linear transformation |
scaled.ip |
The parameters in |
Ivailo Partchev and Tamaki Hattori
Kolen, M.J. & R.L. Brennan (1995) Test Equating: Methods and Practices. Springer.
Haebara, T. (1980) Equating logistic ability scales by a weighted lest squares method. Japanese Psychological Research, 22, p.144–149
## Not run: # a small simulation to demonstrate transformation to a common scale # fake 50 2PL items pa <- cbind(runif(50,.8,2), runif(50,-2.4,2.4), rep(0,50)) # simulate responses with two samples of different ability levels r.1 <- sim(ip=pa[1:30,], x=rnorm(1000,-.5)) r.2 <- sim(ip=pa[21:50,], x=rnorm(1000,.5)) # estimate item parameters p.1 <- est(r.1, engine="ltm") p.2 <- est(r.2, engine="ltm") # plot difficulties to show difference in scale plot(c(-3,3), c(-3,3), ty="n", xlab="True",ylab="Estimated", main="Achieving common scale") text(pa[1:30,2], p.1$est[,2], 1:30) text(pa[21:50,2], p.2$est[,2], 21:50, co=2) # scale with the default Mean/Sigma method pa.sc = sca(old.ip=p.1$est, new.ip=p.2$est, old.items=21:30, new.items=1:10) # add difficulties of scaled items to plot text(pa[21:50,2], pa.sc$scaled.ip[,2], 21:50, co=3) ## End(Not run)## Not run: # a small simulation to demonstrate transformation to a common scale # fake 50 2PL items pa <- cbind(runif(50,.8,2), runif(50,-2.4,2.4), rep(0,50)) # simulate responses with two samples of different ability levels r.1 <- sim(ip=pa[1:30,], x=rnorm(1000,-.5)) r.2 <- sim(ip=pa[21:50,], x=rnorm(1000,.5)) # estimate item parameters p.1 <- est(r.1, engine="ltm") p.2 <- est(r.2, engine="ltm") # plot difficulties to show difference in scale plot(c(-3,3), c(-3,3), ty="n", xlab="True",ylab="Estimated", main="Achieving common scale") text(pa[1:30,2], p.1$est[,2], 1:30) text(pa[21:50,2], p.2$est[,2], 21:50, co=2) # scale with the default Mean/Sigma method pa.sc = sca(old.ip=p.1$est, new.ip=p.2$est, old.items=21:30, new.items=1:10) # add difficulties of scaled items to plot text(pa[21:50,2], pa.sc$scaled.ip[,2], 21:50, co=3) ## End(Not run)
Given a key, score a multiple choice test, i.e. recode the original choices to right (1) or wrong (0). Missing responses are treated as wrong.
sco(choices, key, na.false = FALSE)sco(choices, key, na.false = FALSE)
choices |
The original responses to the items in the test: persons as rows, items as columns. May contain NA. |
key |
A vector containing the key (correct answers) to the items in
|
na.false |
Recode non-responses to false responses? |
A matrix of responses scored 0=wrong 1=correct, and possibly NA
Ivailo Partchev
res <- sco(Unscored, key=c(2,3,1,1,4,1,2,1,2,3,3,4,3,4,2,2,4,3))res <- sco(Unscored, key=c(2,3,1,1,4,1,2,1,2,3,3,4,3,4,2,2,4,3))
Real-life data set containing the responses to a test, scored as true or false.
A data set with 472 persons and 18 items.
Item parameter estimates for the 2PL model, estimated with ltm from
the example data set Scored. These are provided as a check, and to
speed up the examples for the various functions in the package.
The object returned by est
From a set of estimated item parameters, compute an item response function in sum score metric, i.e., the probabilities of a correct response predicted by the model at abilities corresponding to the possible (raw) sum scores.
scoreMetric(ip)scoreMetric(ip)
ip |
Item parameters: the output of |
An object with the same structure as the output of irf
Ivailo Partchev
Produces a plot of IRT true scores (test response function at the estimated ability) with a confidence band (plus/minus standard error). The observed sum scores are shown in red.
scp(resp, ip, theta = NULL)scp(resp, ip, theta = NULL)
resp |
A matrix of binary responses to a test, with persons as rows and items as columns. |
ip |
Item parameters: the output of |
theta |
An object containing ability estimates, as output by function
|
None
Ivailo Partchev
scp(Scored, Scored2pl)scp(Scored, Scored2pl)
Simulate responses from the 1PL, 2PL, or 3PL model
sim(ip, x = NULL)sim(ip, x = NULL)
ip |
Item parameters: a matrix with one row per item, and three
columns: [,1] item discrimination |
x |
A vector of values of the latent variable ("abilities"). |
A matrix of responses: persons as rows, items as columns, entries are either 0 or 1, no missing data
Ivailo Partchev
pa <- cbind(runif(20,.8,2), runif(20,-2.4,2.4), rep(0,50)) rs <- sim(ip=pa, x=rnorm(1000))pa <- cbind(runif(20,.8,2), runif(20,-2.4,2.4), rep(0,50)) rs <- sim(ip=pa, x=rnorm(1000))
Matrix of tetchoric correlations using the approximation by Bonett and Price (2005).
tet(d)tet(d)
d |
a matrix (or data frame, which will be converted to a matrix) containing only zeroes an ones. NAs are not allowed. |
A matrix of approximate tetchoric correlations.
Ivailo Partchev
Douglas G. Bonett and Robert M. Price (2005). Inferential Methods for the Tetrachoric Correlation Coefficient. Journal of Educational and Behavioral Statistics, Vol. 30, No. 2, pp. 213–225
tets <- tet(Scored)tets <- tet(Scored)
A plotting function producing non-parametric analogues of the IRF for each option in a multiple choice item not unlike those in Jim Ramsay's TestGraf program.
tgf( choices, key, item, main = "Non-parametric response function", co = 1, label = FALSE )tgf( choices, key, item, main = "Non-parametric response function", co = 1, label = FALSE )
choices |
A matrix of responses to multiple-choice items: persons as
rows, items as columns. As a rare exception in |
key |
A vector containing the key (correct answers) to the items in
|
item |
A single number pointing to the item (column of |
main |
The main title of the plot, given that |
co |
The colour of the curves. Default is 1 for black. Use |
label |
When |
Ivailo Partchev
James O. Ramsay (2000). TestGraf: A program for the graphical analysis of multiple choice test and questionnaire data. McGill University, Montreal, Canada
key=c(2,3,1,1,4,1,2,1,2,3,3,4,3,4,2,2,4,3) tgf(choices=Unscored, key=key, item=4, co=NA, label=TRUE)key=c(2,3,1,1,4,1,2,1,2,3,3,4,3,4,2,2,4,3) tgf(choices=Unscored, key=key, item=4, co=NA, label=TRUE)
Elementary analysis of the items in a test and the test sumscores based on Classical Test Theory.
tia(choices, key, ...)tia(choices, key, ...)
choices |
The original responses to the items in the test: persons as rows, items as columns. May contain NA. |
key |
A vector containing the key (correct answers) to the items in
|
... |
Other parameters that may be passed to |
A list with three elements:
A list of statistics at test level (currently, only Cronbach's alpha, may be extended in future)
A matrix showing, for each item, the proportion of correct responses, the correlation with the sum score, and the alpha that the test would have if the item were dropped.
A matrix showing, for each possible choice in the multiple-choice item, the proportion of responses given, and the correlation with the sum score for the test (including the item). The correct response is highlighted with asterisks.
Ivailo Partchev
itemsum <- tia(Unscored, key=c(2,3,1,1,4,1,2,1,2,3,3,4,3,4,2,2,4,3))itemsum <- tia(Unscored, key=c(2,3,1,1,4,1,2,1,2,3,3,4,3,4,2,2,4,3))
Returns the test information function (TIF) of the 3PL (1PL, 2PL) model. The TIF is the sum of the item information functions (IIF) in a test, and indicates the precision of measurement that can be achieved with the test at any value of the latent variable, bein inversely related to measurement variance.
tif(ip, x = NULL)tif(ip, x = NULL)
ip |
Item parameters: the output of |
x |
The values of the latent variable ( |
A common use of this function would be to obtain a plot of the TIF.
A list of:
x |
A copy of the argument |
f |
A vector containing the TIF values |
Ivailo Partchev
plot(trf(Scored2pl))plot(trf(Scored2pl))
Returns the test response function (TRF) of the 3PL (1PL, 2PL) model. The
TRF is the sum of the item response functions (IRF) in a test, and
represents the expected score as a function of the latent variable
.
trf(ip, x = NULL)trf(ip, x = NULL)
ip |
Item parameters: the output of |
x |
The values of the latent variable ( |
A common use of this function would be to obtain a plot of the TRF.
A list of:
x |
A copy of the argument |
f |
A vector containing the TRF values |
Ivailo Partchev
plot(trf(Scored2pl))plot(trf(Scored2pl))
Computes the IRT true scores (test response function at the estimated ability) and an estimate of their standard error via the delta theorem, treating item parameters as known).
tsc(ip, theta)tsc(ip, theta)
ip |
Item parameters: the output of |
theta |
An object containing ability estimates, as output by function
|
A matrix with the true scores in column 1, and their standard errors of measurement (SEM) in column 2
Ivailo Partchev
th <- mlebme(resp=Scored, ip=Scored2pl) tsc(Scored2pl, th)th <- mlebme(resp=Scored, ip=Scored2pl) tsc(Scored2pl, th)
Real-life data set containing the responses to a test, before they have been
recoded as true or false. Can be used with only two functions in the
package: scoreResponses and tgf. All other functions expect binary data,
which can be produced with scoreResponses.
A data set with 472 persons and 18 items. Each item has 4 possible answers, of which only one is true. There are many NA, which can be treated as wrong responses.
Weighted likelihood estimates (WLE) of ability, designed to remove the first order bias term from the ML estimates. WLE are finite for response patterns consisting of either uniformly wrong or uniformly correct responses.
wle(resp, ip)wle(resp, ip)
resp |
A matrix of responses: persons as rows, items as columns, entries are either 0 or 1, no missing data |
ip |
Item parameters: the object returned by |
A matrix with the ability estimates in column 1, and their standard errors of measurement (SEM) in column 2, and the number of non-missing reponses in column 3
Ivailo Partchev
Warm T.A. (1989) Weighted Likelihood Estimation of Ability in Item Response Theory. Psychometrika, 54, 427-450.
th.bce <- wle(resp=Scored, ip=Scored2pl)th.bce <- wle(resp=Scored, ip=Scored2pl)