---
title: "autoRasch: Working with the models"
author: "John Doe"
# output:
#   html_vignette:
#     keep_md: true
#   pdf_document: default
# output:
#   pdf_document:
#     latex_engine: pdflatex
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{autoRasch: Working with the models}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{}
# install.packages("remotes")
remotes::install_github("fwijayanto/autoRasch", build_manual = TRUE, build_vignettes = TRUE)
```

```{r setup}
library(autoRasch)
```


In this autoRasch package four models are implemented, i.e., the PCM, the GPCM, the PCM-DIF, and the GPCM-DIF. For binary responses, the PCM and GPCM will transform to the Rasch model and the 2-PL model, respectively.

### The PCM and PCM-DIF

The Partial Credit Model (PCM) is the model multi-categorical responses, which generalizes the Rasch model.

```{r}
pcm_res <- pcm(shortDIF)
```

Similar with the PCM the PCM-DIF generalize the Rasch model even more by parameterizing the DIF effect in the items. However, in the PCM-DIF, we need to define the groups of the subjects. In this simulated dataset, the groups are pre-designed as the first half and the rest.

```{r}
grMap <- matrix(c(rep(0,50),rep(1,50)),ncol = 1, dimnames = list(c(1:100),c("cov")))
pcmdif_res <- pcm_dif(shortDIF, groups_map = grMap)
```

Some of the S3 generic functions are implemented to this model, i.e., summary() and print(). However, to filter which model's parameter to plot, I add `par` argument. It could be filled in using `theta`, `beta`, `gamma`, `alpha`, and `delta`, depends on the models applied. Ignoring this argument shows all estimated parameters of the model. `Item Loc.` represents the item location which is obtained by averaging the threshold values. `*` indicates the occurence of a disordered threshold.  

```{r}
summary(pcm_res, par="beta")
```

```{r}
summary(pcmdif_res, par="delta")
```

For PCM and PCM-DIF, the estimated parameters could be plotted as a Person-Item map. However, as for PCM-DIF the items with DIF will be resolved by splitting the items based on the given groups. As the results, we may obtain more than one item with the same number.

```{r fig.height=3.5, fig.width=7}
plot_PImap(pcm_res, main = "Person-Item map of the PCM")
```

```{r fig.height=3.5, fig.width=7}
plot_PImap(pcmdif_res, main = "Person-Item map of the PCM-DIF")
```

Since item~1~~9~ is a DIF-item, there are two item~1~~9~ in the Person-Item map of the PCM-DIF, the `I 19` and `I 19_a` for the reference and the focal group, respectively. Red color means that there is a threshold disorder within the item.

The `plot_ICC()` and `plot_EVC()` could be used to plot the item characteristic curve (ICC) and the expected value curve (EVC), respectively, for each item.

```{r fig.height=3.5, fig.width=7}
plot_ICC(pcm_res, itemno = 2, main = "ICC of I 17; estimated using PCM")
```

To implement the standard Rasch goodness-of-fit statistics, a specific S3 function have been developed to compute the (item/person) fit statistics, i.e., `fitStats()` function, for the PCM and the PCM-DIF. To summarize only item or person statistic, `itemfit()` or `personfit()` could be used, respectively.

```{r}
pcm_fit <- fitStats(pcm_res)
itemfit(pcm_fit)
```

```{r}
pcmdif_fit <- fitStats(pcmdif_res)
itemfit(pcmdif_fit)
```

### The GPCM and GPCM-DIF

The Generalized Partial Credit Model (GPCM) generalizes the Partial Credit Model by modelling the predictability of the subjects' responses (discrimination parameters).

```{r}
gpcm_res <- gpcm(shortDIF)
```

For further generalization to the PCM, the Generalized Partial Credit Model with DIF (GPCM-DIF) not only models the predictability, but also the effects of the differential functioning of each items.

```{r}
grMap <- matrix(c(rep(0,50),rep(1,50)),ncol = 1, dimnames = list(c(1:100),c("cov")))
gpcmdif_res <- gpcm_dif(shortDIF, groups_map = grMap)
```

Similar to the PCM and PCM-DIF, some of the S3 generic functions such as `summary()` and `print()` also applied to these models.

```{r}
summary(gpcm_res, par="alpha")
```

```{r}
summary(gpcmdif_res, par="delta")
```

Unlike `plot_PImap()` which only implemented to the PCM and PCM-DIF, `plot_EVC()` and `plot_ICC()` are also implemented to the GPCM and the GPCM-DIF.