---
title: "The R Package equateMultiple: A Tutorial"
output: 
  rmarkdown::html_document:
    toc: true
    toc_float: true
    number_sections: true
    theme: spacelab
    highlight: pygments
vignette: >
  %\VignetteIndexEntry{The R Package equateMultiple: A Tutorial}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

# Functionalities

The equateMultiple package computes:

* __Equating coefficients__ between __multiple forms__.
* __Item parameter estimates on a common scale__ (based on the item parameter estimates from different forms).
* __Standard errors__ of the equating coefficients and the item parameter estimates on a common scale.

# Data preparation

Data preparation follows the same steps of the equateIRT package.

Load the package equateMultiple and the data

```{r}
library("equateMultiple")
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`

```{r}
mlist<- list(m1, m2, m3, m4, m5)
test <- paste("test", 1:5, sep = "")
mods <- modIRT(est.mods = mlist, names = test, display = FALSE)
```

The linkage plan

```{r}
lplan<-linkp(mods = mods)
lplan
```


# Multiple equating coefficients

Estimation of the equating coefficients using
the multiple mean-mean method. Form 1 is the base form.

```{r}
eqMM <- multiec(mods = mods, method = "mean-mean")
summary(eqMM)
```

Estimation of the equating coefficients using the 
multiple mean-geometric mean method.

```{r}
eqMGM <- multiec(mods = mods, method = "mean-gmean")
summary(eqMGM)
```

Estimation of the equating coefficients using the multiple 
item response function method.

```{r}
eqIRF<-multiec(mods = mods, method = "irf")
summary(eqIRF)
```

Estimation of the equating coefficients using the multiple item response function method.
The initial values are the estimates obtained with the 
multiple mean-geometric mean method.

```{r}
eqMGM <- multiec(mods = mods, method = "mean-gmean", se = FALSE)
eqIRF<-multiec(mods = mods, method = "irf", start = eqMGM)
summary(eqIRF)
```

Estimation of the equating coefficients using the multiple test response function method.

```{r}
eqTRF<-multiec(mods = mods, method = "trf")
summary(eqTRF)
```

Estimation of the equating coefficients using the likelihood-based method.

```{r}
eqLIK <- multiec(mods = mods, method = "lik")
summary(eqLIK)
```

It is possible to change the base form, that is the form whose item parameter estimates
are left unchanged. All other item parameter estimates are converted to the scale of the
base form.

```{r}
eqLIK <- multiec(mods = mods, method = "lik", base = 5)
summary(eqLIK)
```


# Item parameter estimates on a common scale

The package computes estimates of the item parameters on the scale
of the base form, obtained using all estimates available for the same item
across all the forms. Their standard errors are also computed.
They can be extracted as follows (using the multiple item response function method).

```{r}
item.common(eqIRF)
```

# Equated scores


Equated scores with the true score equating method

```{r}
scTSE<-score(eqIRF)
round(scTSE,3)
```

Equated scores with the observed score equating method, 
avoiding computation of standard errors

```{r}
scOSE<-score(eqIRF, method = "OSE", se = FALSE)
round(scOSE,3)
```