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