---
title: "The R Package equateIRT: A Tutorial"
output:
rmarkdown::html_document:
toc: true
toc_float: true
number_sections: true
theme: spacelab
highlight: pygments
vignette: >
%\VignetteIndexEntry{The R Package equateIRT: A Tutorial}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
# Functionalities
The equateIRT package computes:
* __Direct equating coefficients__ (between two forms with common items).
* __Chain equating coefficients__ (through a chain of forms with common items in pairs).
* __Average (bisector) equating coefficients__ (between two forms connected through more than one path).
* __Equated scores__ with __true score equating__ and __observed score equating__ methods.
* __Standard errors__ of all equating coefficients and equated scores.
* __Test for DIF__ and __tests for drifts__.
# Data preparation
Load the package equateIRT and the data
```{r}
library("equateIRT")
data("data2pl", package = "equateIRT")
```
Estimate a two parameter logistic model for 5 data sets with the R package mirt
```{r, message=FALSE, results='hide'}
library("mirt")
m1 <- mirt(data2pl[[1]], SE = TRUE)
m2 <- mirt(data2pl[[2]], SE = TRUE)
m3 <- mirt(data2pl[[3]], SE = TRUE)
m4 <- mirt(data2pl[[4]], SE = TRUE)
m5 <- mirt(data2pl[[5]], SE = TRUE)
```
Create an object of class `modIRT` (since package versione 2.5.0 it is possible to skip the import.mirt function)
```{r}
mlist<- list(m1, m2, m3, m4, m5)
test <- paste("test", 1:5, sep = "")
mod2pl <- modIRT(est.mods = mlist, names = test, display = FALSE)
coef(mod2pl$test1)[1:5]
```
The linkage plan
```{r}
lplan<-linkp(mods = mod2pl)
lplan
```
A graphic of the linkage plan with package `sna`
```{r, message=FALSE, fig.cap="Linkage plan",fig.width=3.5,fig.height=3}
library(sna)
par(mar=c(0, 0, 0, 0))
set.seed(6)
gplot(lplan, displaylabels = TRUE, vertex.sides = 4, vertex.cex = 5, vertex.rot =45, usearrows = FALSE, label.pos = 5, label.cex = 1, vertex.col = 0)
```
# Direct equating coefficients
Estimation of direct equating coefficients between Forms 1 and 2 using
the mean-mean method.
__NOTE: Item parameters are converted to the scale of Form 2.__
```{r}
l12 <- direc(mods = mod2pl, which = c(1,2), method = "mean-mean")
l12
summary(l12)
```
Estimation of all direct equating coefficients between forms with common
items using the mean-mean method
```{r}
direclist2pl <- alldirec(mods = mod2pl, method = "mean-mean")
direclist2pl
```
```{r}
```
Direct equating coefficients for Forms 1 and 2
```{r}
summary(direclist2pl, link="test1.test2")
```
# Chain equating coefficients
Estimation of all chain equating coefficients of length 4
```{r}
cec4 <- chainec(r = 4, direclist = direclist2pl)
cec4
```
Chain equating coefficients for path {1, 2, 3, 4}
```{r}
summary(cec4, path="test1.test2.test3.test4")
```
Estimation of all chain equating coefficients of length 4
from Form 1 to Form 4
```{r}
cec14 <- chainec(r = 4, direclist = direclist2pl, f1 = "test1", f2 = "test4")
cec14
summary(cec14)
```
Estimation of chain equating coefficient for path {1, 5, 4}
```{r}
pth <- paste("test", c(1,5,4), sep = "")
chainec154 <- chainec(direclist = direclist2pl, pths = pth)
summary(chainec154)
```
__NOTE: Item parameters are converted to the scale of Form 4.__
# Average equating coefficients
When two forms are linked through more than one path, the equating coefficients can be averaged
using the bisector method.
Estimation of bisector equating coefficients:
```{r}
ecall <- c(cec14, chainec154)
fec <- bisectorec(ecall = ecall, weighted = TRUE, unweighted = TRUE)
fec
summary(fec)
```
Extract the equating coefficients
```{r}
eqc(fec)
```
Extract item parameters of two forms being equated in the original scale
and item parameters of the first form converted to the scale of the second form.
```{r}
itm(fec, bistype = "weighted")
```
# Equated scores
Equated scores with the true score equating method
```{r}
score(fec, bistype = "weighted")
```
Equated scores with the observed score equating method
```{r}
score(fec, method = "OSE", bistype = "weighted")
```
A comparison of equated scores obtained with 2 different chains,
bisector and weighted bisector methods.
```{r}
score(chainec154, scores = 17)
score(cec4, path = "test1.test2.test3.test4", scores = 17)
score(fec, bistype = "unweighted", scores = 17)
score(fec, bistype = "weighted", scores = 17)
```
# Test for DIF
Load the data
```{r}
data(dataDIF)
```
Create a dataset for each group and estimate a 2PL model for each group using the R package mirt
```{r, message=FALSE, results='hide'}
library(mirt)
data1 <- dataDIF[dataDIF$group == 1, 1:20]
data2 <- dataDIF[dataDIF$group == 2, 1:20]
data3 <- dataDIF[dataDIF$group == 3, 1:20]
mod1 <- mirt(data1, SE = TRUE)
mod2 <- mirt(data2, SE = TRUE)
mod3 <- mirt(data3, SE = TRUE)
```
Perform the test for DIF on two groups
```{r}
res_diftest2 <- dif.test(est.mods = list(mod1, mod2))
res_diftest2
```
Perform the test for DIF on three groups
```{r}
res_diftest3 <- dif.test(est.mods = list(mod1, mod2, mod3))
res_diftest3
```
It is possible to change the reference group, the equating method used, and to apply purification.
```{r}
res_diftest3 <- dif.test(est.mods = list(mod1, mod2, mod3), reference = 2,
method = "Haebara", purification = TRUE)
res_diftest3
```
# Tests for drifts
The identity test performs a statistical test to verify if the chain equating coefficients from one form to itself are A=1 and B=0.
```{r}
data(est3pl)
test <- paste("test", 1:5, sep = "")
mod3pl <- modIRT(coef = est3pl$coef, var = est3pl$var, names = test, display = FALSE)
direclist3pl <- alldirec(mods = mod3pl, method = "Haebara")
pth3 <- paste("test", c(1:5,1), sep = "")
chainec_circle <- chainec(direclist = direclist3pl, pths = pth3)
summary(chainec_circle)
id.test(chainec_circle)
```
The null hypothesis A=1 and B=0 is not rejected.
It is also possible to performs a statistical test to verify if the chain equating coefficients that link the same two forms are equal.
In the following example test 1 and 5 are linked through two different paths giving
two different pairs of equating coefficients.
The example uses the 3PL models and the Haebara method, though other options are possible.
```{r}
pth3 <- paste("test", 1:5, sep = "")
chainec3 <- chainec(direclist = direclist3pl, pths = pth3)
ecall <- c(chainec3, direclist3pl["test1.test5"])
summary(chainec3)
summary(direclist3pl$test1.test5)
sd.test(ecall)
```
The null hypothesis of equality of the equating coefficients is not rejected.