This vignette describes the basic way of randomizing exams using this package.

What problem is this software adressing

When you are using 'LaTeX' together with some software to randomize or personalize exams individually, most tools usually require for you to think ahead. It requires you to keep in mind exactly how the structure might change when randomizing the exam, and more importantly, it restricts the formatting that you are allowed to use. You are only allowed to use a certain naming convention, and in many cases it also only allow for one section to be randomize. When usually you would prefer to keep questions about a certain topic together.

This package and the corresponding scripts and TexShop engines that come distributed with it tries to fix this.

It can basically understand any 'LaTeX' “itemize” structure that follows the \begin{envname} \end{envname} that has a certain command that produces “items” within that environemnt \item.

It is capable of understanding structures that are more nested as well, with only a few caveats.


It also adds a layer of personalization as well by being able to modify the values of commands on the preamble on a per-document basis, this is explained further on vignette("ExamOptions", package = "TexExamRandomizer"):

How to start

Enough with the explanations, if you are using the exam class structure on your exam already, (questions, question; choices, choice|Correctchoice), it is fairly easy to adapt. [If you are using another structure, it is explained in the advance section how to tell the program what are you using. vignette("ExamOptions", package = "TexExamRandomizer")]

To get started:

(@) Add the examrandomizer executable somewhere in your path that can be found by the terminal. (@) Then, drop the examrandomizer.engine on the TexShop engine library (Usually it is found in ~/Library/TeXShop/Engines)[If you are using another 'LaTeX' distribution that doesn't allow .engine scripts, you will have to do it on the terminal]. (@) Once you have done that, just add a line in your 'LaTeX' document within the first 200 lines of your documen that says (let's assume you want 5 versions)

`%! TexExamRandomizer = {"noutput" = 5}`

(@) Run the examrandomizer engine choosing it from the TexShop engines list. Keep in mind that double quotes within the json format is mandatory.

All these scripts can be found in the exec/ folder. Which you can find by running

system.file("exec", package = "TexExamRandomizer")
## [1] "/private/var/folders/9v/mybxpy914_1g1mlfp_wr50fw0000gn/T/RtmpSVZU2r/Rinst12177421aa130/TexExamRandomizer/exec"

For a more detailed explanation of all the options, please look at

vignette("ExamOptions", package = "TexExamRandomizer")


If you are planning to also use the automatic grading then, after your students respond to the exams:

(@) Add as well the gradeexamrandomizer to a path that can be found by the terminal. (@) You have to collect the student's responses in a table. Where the columns of the responses should be named “Q 1”, “Q 2”, etc. * To give extra points, if you write a column called “Extra Points” those points will be added to the total grade. (@) Run the following command

    gradeexamrandomizer --resp <student responses csv> --answer <fullanswersheet csv>

(@) You will find a _Graded.csv and a _Stats.csv file in the same folder as the student's responses with the grades and stats of the exam.

For a more detailed explanation,

vignette("GradingExams", package = "TexExamRandomizer")

Creating your own scripts

The implementation of a json-like parser within the document certainly makes it a lot more concise to use. However, that is simply a wrapper of the underlying functions that define this R library.

If you want to use the full functionality, and try to that library, you might want to start by looking at the functions CreateRandomExams and GenerateHomework. Grading is done by calling GradeExams and ObtainExamStats… although if your exam structure is a bit wild it might have issues trying to grade it.

Known “issues” {#caveats}

If you have the expertise or you are willing to put some time to fix these issues I would be happy to talk with you.