README.Rmd

---
output: 
  github_document:
    df_print: kable
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)
```

## conquestr

ConQuest generalised item response modelling software (Wu, Adams, Wilson, & Haldane, 2007) is used for a wide variety of purposes including the analysis of educational assessment data. 

`conquestr` is an R package whose first goal was to make it easier to import ConQuest item analysis files into R. This functionality does not appear to be available in other R packages as far as we are aware. 

## Other resources

Several other R packages already integrate with ConQuest to various degrees. For example:

See [TAM](https://CRAN.R-project.org/package=TAM) if you'd like to do analysis similar to ConQuest within R.

The `R2conquest` function in the [sirt](https://CRAN.R-project.org/package=sirt) package provides functionality for using ConQuest from within R.

The [WrightMap](https://CRAN.R-project.org/package=WrightMap) package also contains various features for working with ConQuest and other IRT packages.

## Installation

You can install `conquestr` from github with:

```{r gh-install, eval = FALSE}
# install.packages("devtools")
devtools::install_github("markdly/conquestr")
```

Alternatively, the latest updates are made and tested using the develop branch which can be installed with 

```{r gh-dev-install, eval = FALSE}
# install.packages("devtools")
devtools::install_github("markdly/conquestr#develop")
```

## Example

First load the relevant packages

```{r, message = FALSE}
library(conquestr)
```

Take a ConQuest version 2 item analysis file. In ConQuest, item analysis text files are generated by the ConQuest itanal command (e.g. `itanal >> my_item_analysis_file.itn;`). An example item analysis file is included with `conquestr` out of the box:

```{r example}
cq_example()
```

Use the example file to try out the other functions. The main one is `cq_itanal`:

```{r}
# get the path to the example itanal file that comes with conquestr
fname <- cq_example(display = FALSE)

# import the itanal as a tibble
df <- cq_itanal(fname)
```

Once imported, the original text imported for each 'item' can be found in the `data` column.  


```{r}
df$data[1]
```

Item level details are provided in separate columns:

```{r}
head(dplyr::select(df, -c(data, resp_stat)))
```

The details for each response category is contained in the list column `resp_stat`. The function `cq_resp_stats()` makes viewing these easier:

```{r}
head(cq_resp_stats(df))
```

## Other examples

### Plausible values files

```{r pv_example}
fname <- cq_example(display = FALSE, example_name = "ex1_10.pv") 
pv <- cq_pv(fname, np = 10)  
head(pv)
```

By default the pv files are imported in long format. To convert them to a more typical 'wide' format one way this can be done is:

```{r pv_wide, message=FALSE}
library(dplyr)
library(tidyr)
pv_wide <- pv %>% select(recid, field, val) %>% spread(field, val)
head(pv_wide)
```


## References

Wu, M., Adams, R., Wilson, M., & Haldane, S. (2007). ConQuest Version 2: Generalised Item Response Modelling Software.