---
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.