---
title: "Using `AMCTestmakeR`"
author: "Nils Myszkowski"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using `AMCTestmakeR`}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---


`AMCTestmakeR` provides functions to be used with the free Optical Mark Recognition (OMR) software Auto Multiple Choice.

It's main purpose is to facilitate working with R and AMC in parallel, but it can also be used to transform a spreadsheet into an AMC questionnaire easily.

So far, the features are limited to generating AMC-LaTeX code questions for Multiple Choice Questionnaires (single and multiple answer). Hopefully, it's how most people use Auto Multiple Choice.

# Install and load the library

Install the library with `install.packages("AMCTestmakeR")`, and load it with:

```{r comment=NA}
library(AMCTestmakeR)
```

# Basic Use : Generating questions

## Generating code for one question

Let's say that we have a simple question to add:
- How much is $1+1$?
- The correct answer is $2$ (if you didn't get this one, you're probably at the wrong place)
- The incorrect ones are $3$ and $11$

```{r comment=NA}
AMCcreatequestions(
  question = "How much is $1+1$?",
  correctanswers = 2,
  incorrectanswers = list(3, 11))
```
Or, more simply `AMCcreatequestions("How much is $1+1$?",2,list(3, 11))`.

## Writing questions to a .tex file

R escapes different characters than LaTeX, so doing a copy-and-paste of the console output will require than you tweak things a bit.

Instead of doing that, I recommend to use the optional argument `writefile = TRUE` to write the generated code into a file. The default creates a `questions.tex` file in the working directory, but you can indicate another path with `filepath`, and append to an existing file -- rather than overwriting the existing file -- with `append = TRUE`).


## Generating code for multiple questions

If you have an entire questionnaire to generate, the `AMCcreatequestions` can use vectors for many of its arguments.

Let's first create 3 questions, putting the questions and answers in vectors.

```{r}
question <- c("How much is $1+1$ ?",
              "How much is $1 \\times 1$ ?",
              "How much is $\\frac{1}{2}$ ?")
correct <- c(2,1,0.5)
incorrect1 <- c(3,4,10)
incorrect2 <- c(1,3,100)
incorrect3 <- c(4,8,NA)
```

Note that the third question has only 2 incorrect answers: `AMCTestmakeR` will simply skip missing values (`NA` and `""`).

```{r}
AMCcreatequestions(question = question,
   correctanswers = correct,
   incorrectanswers = list(incorrect1,incorrect2,incorrect3))
```

Like before, copy-paste is not optimal, as R escapes different characters than LaTeX. Using `writefile = TRUE` is more convenient to take care of this and translate R text into LaTeX (see above for details). Also, consider using the function `AMCcreatetest()` to handle the full test creation (described later as *Suggested Workflow 1*).


## Additional options

### Changing the element

The element in AMC corresponds to a group of questions. They can for example correspond to different learning outcomes or chapters of a book. AMC is able to randomize questions within elements.

Provide a character value or vector to the argument `element` to define it. If you provide a value, all questions will have this value as element. If you provide a vector, each question will have its corresponding element.

```{r}
AMCcreatequestions(element = c("ADD", "MULT", "DIV"),
   question = question,
   correctanswers = correct,
   incorrectanswers = list(incorrect1,incorrect2,incorrect3))
```

The default element is `general`.

### Changing the question codes

In AMC, each question should have a unique code.

The code can be provided in `AMCTestmakeR` through the argument `code` (like for the `element` argument, a character value or vector can be used).

```{r}
AMCcreatequestions(code = c("ADD1", "MULT1", "DIV1"),
   question = question,
   correctanswers = correct,
   incorrectanswers = list(incorrect1,incorrect2,incorrect3))
```

A lazy version of this is, instead of codes, to input a code prefix with the `codeprefix` argument. Unique codes will be generated by the function by incrementing numbers after the prefix.

```{r}
AMCcreatequestions(codeprefix = "MATH",
   question = question,
   correctanswers = correct,
   incorrectanswers = list(incorrect1,incorrect2,incorrect3))
```

# Once the questions are ready...

When your questions are ready and the `AMCcreatequestions()` gives a satisfactory result. I suggest to directly use `AMCcreatetest()` to create the other .tex files and to have a fully working test easily (*Workflow 1*).

## Workflow 1: Creating the test files from scratch with `AMCcreatetest()`

`AMCTestmakeR` can create a test from scratch with the function `AMCcreatetest()`. It creates 3 .tex files (groups.tex, questions.tex, elements.tex) that can be directly used in the AMC project folder.

The first arguments of this function are passed to the `AMCcreatequestions()` function (see above for how to use it). The rest of the arguments are used to set test options (like `fontsize`, `separateanswersheet`, `title`, `identifier`, etc.). See the function documentation for a full list of options. If you don't pass any option (except for the questions of course), you should have a useable -- albeit not customized -- test.


```{r eval=F}
AMCcreatetest("How much is $1+2$?",2,list("3", "11"))
```


### More options

Separate answer sheets, font size, title, instructions, etc.

```{r eval=F}
AMCcreatetest(
  #This part is passed to the AMCcreatequestions() function:
  question = "How much is $1+1$?",
  2,
  list("3", "11"),
  #The next part is passed to AMCcreateelements():
  shuffle = T,
  sections = T,
  #The last part is for general test options:
  title = "Exam", #Custom title
  paper = "a4", #change the paper for a4
  fontsize = 11, #change fontsize
  identifier = "ID Number", #change identifier
  twosided = F, #print in one sided
  instructions = "Don't respond here.", #show an instructions block
  separateanswersheet = T, #use a separate answer sheet
  answersheettitle = "Respond Here", #Change answer sheet title
  answersheetinstructions = "Fill the boxes."#Answer sheet instructions
)
```

When working on the questions, I suggest to work using `AMCcreatequestions()` with the default output as notes (to check the result without opening a separate .tex file). Once your questions are ready, I suggest to switch to `AMCcreatequestions()`, using the same beginning arguments, and changing the rest.


## Workflow 2: Doing things manually with your own template and `AMCcreateelements()`

If you want to customize more, you can do things step by step. If doing that, I highly recommend starting by reading the AMC documentation.

When using `AMCcreatequestions()` to create a questionnaire in AMC, I suggest to create, with `writefile = TRUE`, the questions in a separate questions file (e.g. `questions.tex`) in your AMC project folder.

From there, in your main .tex document (usually, that's named `groups.tex` by AMC), add `\input{questions.tex}` at the beginning (but still after your `\begin{document}`).

Then, where you want to place the different `elements`, in your main .tex, add `\insertgroup{element}` for each of them. Before the `\insertgroup{}` command, you can use `\shufflegroup{element}` to shuffle the questions within the element.

### The `AMCcreateelements()` function

If you have many elements in your document, and therefore many `\insertgroup{}` (and `\shufflegroup{}`) to insert, you may want to use the function `AMCcreateelements()` function. It will show as a console message (which you can, this time, easily copy-and-paste into your main .tex document) the commands to insert (and shuffle, if desired, through the `shuffle` argument) the elements:

```{r}
AMCcreateelements(element = c("ADD", "MULT", "DIV"), shuffle = T, sections = T)
```

Note that, if the same element is input multiple times (which often happens if you pass to this function the same vector of elements as the one used in `AMCcreatequestions()`), it is not a problem, since only unique values are output:

```{r}
AMCcreateelements(element = c("MATH", "MATH", "MATH", "STAT"), shuffle = F, sections = F)
```



# Future features

Auto Multiple Choice is a great freeware that is able to do a lot more that what `AMCTestmakeR` helps for, so I will try to add the most helpful features here soon. This software feels the In any case, I strongly encourage to read the documentation of how to use LaTeX in Auto Multiple Choice to get a sense of its many possibilities.



