---
title: "Overview of `eatATA` Functionality"
author: "Benjamin Becker"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Overview of `eatATA` Functionality}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

`eatATA` efficiently translates test design requirements for Automated Test Assembly (`ATA`) into constraints for a Mixed Integer Linear Programming Model (MILP). A number of user-friendly functions are available that translate conceptual test assembly constraints to constraint objects for MILP solver. Currently, `GLPK`, `lpSolve`, `SYMPHONY`, and `Gurobi` are supported as solvers. In the remainder of this vignette we provide an overview of the functionality of `eatATA`. A minimal `ATA` example can be found in the vignette [Typical Use of `eatATA`: a Minimal Example](minimal_example.html), a more complex use case for a pilot study can be found in the vignette [Typical Use of `eatATA`: a Pilot Study Example](use_case_pilot_study.html).

## Setup
The `eatATA` package can be installed from `CRAN`.  

```{r installation, eval = FALSE}
install.packages("eatATA")
```

As a default solver, we recommend `GLPK`, which is automatically installed alongside this package. `lpSolve` and `SYMPHONY` are also freely available open source solvers. If you want to use `Gurobi` as a solver (the most powerful and efficient solver currently supported by `eatATA`), an external software installation and licensing is required. This means, you need to install the `Gurobi` solver and its corresponding `R` package. A detailed vignette on the installation process can be found [here](https://CRAN.R-project.org/package=prioritizr/vignettes/gurobi_installation_guide.html). 

```{r library, message = FALSE}
# loading eatATA
library(eatATA)
```

## Item pool preparation
`eatATA` provides functions to prepare the item pool for test assembly:

* `calculateIIF()`
* `calculatExpectedRT()`
* `dummiesToFactor()`
* `computeTargetValues()`

These functions can be used to calculate the item information function (`calculateIIF()`) and expected response times (`calculatExpectedRT()`). `dummiesToFactor()` allows the transformation of a variable coded as multiple dummy variables into a single factor. `computeTargetValues()` allows the calculation of target values for test form constraints, but this functionality is also contained in the `autoItemValuesMinMax()` function.

There also a number of example item pools included in the package:
* `items_mini`: A small minimal example item pool
* `items_diao`: An item pool modeled after the first problem in Diao & van der Linden (2011)
* `items_pilot`: An item pool for a calibration study
* `items_lsa`: An item pool for the block assembly of a large-scale assessment
* `items_vera`: An item pool similar to a `Vergleichsarbeiten` item pool 

## Objective function
Constraints defining the optimization goal of the automated test assembly:

* `maxObjective()`
* `minObjective()`
* `maximinObjective()`
* `minimaxObjective()`
* `cappedMaximinObjective()`

## Constraints
Here is a list of functions that can be used to set constraints:

Constraints controlling how often an item should or can be used:

* `depletePoolConstraint()`
* `itemUsageConstraint()`

Constraints controlling number of items per test forms:

* `itemUsageConstraint()`
* `itemsPerFormConstraint()`

Constraints controlling categorical properties of items per test forms:

* `itemCategoryConstraint()`
* `itemCategoryDeviationConstraint()`
* `itemCategoryMaxConstraint()`
* `itemCategoryMinConstraint()`
* `itemCategoryRangeConstraint()`

Constraints controlling metric properties of items per test forms:

* `autoItemValuesMinMaxConstraint()`
* `itemValuesConstraint()`
* `itemValuesDeviationConstraint()`
* `itemValuesMaxConstraint()`
* `itemValuesMinConstraint()`
* `itemValuesRangeConstraint()`

Constraints controlling metric properties of items across test forms:

* `acrossFormsConstraint()`

Constraints controlling item inclusions or exclusions within test forms: 

* `itemExclusionConstraint()`
* `itemInclusionConstraint()`

Input for the inclusion and exclusion function can be prepared using:

* `itemTuples()`
* `matrixExclusionTuples()`
* `stemInclusionTuples()`

## Solver function
After defining all required constraints using the functions above, `useSolver()` can be used to call the desired solver. Optionally, constraints can be combined beforehand using the `combineConstraint()` function.

## Using the solver output
`useSolver()` structures the output consistently, independent of the solver used. This output can be further processed by `inspectSolution()` (to inspect the assembled booklets) and `appendSolution()` (to append the assembly information to the existing item `data.frame`).

## Booklet exclusions
Test form assembly might be performed in a two stage process, first assembling booklets from items and then assembling test forms from booklets. In this case, item exclusions might translate to exclusions on booklets level. Booklet exclusions can exist between booklets of one automated booklet assembly run or between booklets of multiple automated booklet assembly runs. For the first case, `analyzeBlockExclusion()` can be used to inspect booklet exclusions. For the second case, `analyzeComplexBlockExclusion()` can be used to inspect booklet exclusions.