---
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.

# 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 ltm

```{r, message=FALSE}
library("ltm")
m1 <- ltm(data2pl[[1]] ~ z1)
m2 <- ltm(data2pl[[2]] ~ z1)
m3 <- ltm(data2pl[[3]] ~ z1)
m4 <- ltm(data2pl[[4]] ~ z1)
m5 <- ltm(data2pl[[5]] ~ z1)
```

Extract the item parameter estimates and the covariance matrices

```{r}
estm1 <- import.ltm(m1, display = FALSE)
estm2 <- import.ltm(m2, display = FALSE)
estm3 <- import.ltm(m3, display = FALSE)
estm4 <- import.ltm(m4, display = FALSE)
estm5 <- import.ltm(m5, display = FALSE)
estm1$coef[1:3, ]
estm1$var[1:3, 1:3]
```

Create a list of coefficients and covariance matrices

```{r}
estc <- list(estm1$coef, estm2$coef, estm3$coef, estm4$coef, estm5$coef)
estv <- list(estm1$var, estm2$var, estm3$var, estm4$var, estm5$var)
test <- paste("test", 1:5, sep = "")
```

Create an object of class `modIRT`

```{r}
mod2pl <- modIRT(coef = estc, var = estv, names = test, display = FALSE)
coef(mod2pl$test1)[1:5]
```

The linkage plan

```{r}
lplan<-linkp(coef = estc)
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
summary(cec4, path="test1.test2.test3.test4")
```

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

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)
```




