---
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__.
* __Synthetic item parameters__ (sort of mean of the item parameter estimates from different forms).
* __Standard errors__ of the equating coefficients and the synthetic item parameters.

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


# Synthetic item parameters

The synthetic item parameters are an estimate of the item parameters on the scale
of the base form, obtained using all estimates available for the same item parameter
across all the forms.
The synthetic item parameters and their standard errors can be
extracted as follows (using the multiple item response function method).

```{r}
eqIRF$as
eqIRF$bs
eqIRF$se.as
eqIRF$se.bs
```

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