LaTeX source file

This section describes the LaTeX commands that allows you to design your exam answer sheets from a LaTeX souce file. If you chose another format for your source file, you can skip this section. The MCQ can be described as a LaTeX file using the automultiplechoice package. You can check the LaTeX file you are designing at any moment by compiling it with the latex command, then visualizing the resulting dvi file.

We start with a few examples giving quick illustrations of how to build LaTeX files for MCQs; the corresponding tex file are available as templates, so that one can create a new MCQ project starting with one of these templates.

A simple example

\documentclass[a4paper]{article}

\usepackage[utf8x]{inputenc}    1
\usepackage[T1]{fontenc}

\usepackage[box,completemulti]{automultiplechoice}    2
\begin{document}

\onecopy{10}{    3

%%% beginning of the test sheet header:    4

\noindent{\bf QCM  \hfill TEST}

\vspace*{.5cm}
\begin{minipage}{.4\linewidth}
\centering\large\bf Test\\ Examination on Jan., 1st, 2008\end{minipage}
\namefield{\fbox{    5
                \begin{minipage}{.5\linewidth}
                  Firstname and lastname:

                  \vspace*{.5cm}\dotfill
                  \vspace*{1mm}
                \end{minipage}
         }}

\begin{center}\em
Duration : 10 minutes.

  No documents allowed. The use of electronic calculators is forbidden.


  Questions using the sign \multiSymbole{} may have
  zero, one or several correct answers.  Other questions have a single correct answer.

  Negative points may be attributed to \emph{very
    bad} answers.
\end{center}
\vspace{1ex}

%%% end of the header

\begin{question}{prez}    6
  Among the following persons, which one has ever been a President of the French Republic?
  \begin{choices}
    \correctchoice{René Coty}
    \wrongchoice{Alain Prost}
    \wrongchoice{Marcel Proust}
    \wrongchoice{Claude Monet}
  \end{choices}
\end{question}

\begin{questionmult}{pref}    7
  Among the following cities, which ones are french prefectures?
  \begin{choices}
    \correctchoice{Poitiers}
    \wrongchoice{Sainte-Menehould}
    \correctchoice{Avignon}
  \end{choices}
\end{questionmult}

\clearpage    8

}   9

\end{document}

A few extra details on this example:

1

The packages inputenc and fontenc allow one to use the UTF-8 encoding. You can of course modify them depending on the encoding you want to use.

2

The options used here for the automultiplechoice LaTeX package prevent questions from being split between two pages (box) and to automatically complete any multiple choice question by a standard answer allowing the student to mention that, in her/his opinion, none of the listed answers is correct (completemulti).

3

The onecopy command produces as many (distinct) realizations of the MCQ test as desired (here 10). See the section called “Description of a copy” for an alternative syntax using an environment.

4

Lines that start here describe the header of the test-sheet.

5

The namefield command specifies where students write their name.

6

The environments question and choices allow one to build a multiple choice question for which there is a single correct answer. A unique identifier for the question has to be specified (here: prez).

7

The environments questionmult and choices allow one to build a multiple choice question that may have zero, one or several correct answers. Student are asked to check all the boxes corresponding to an answer that she/he thinks is correct, or the last box (added automatically thanks to the completemulti option used in the reference to the package in line 6).

8

The clearpage is used to start the next realization of the MCQ test on a new page.

9

This marks the end of the onecopy command (started at line 9).

An example with groups of questions and shuffling

In this example, we want the order in which questions appear in the MCQ test to be different from one realization of the test to the other, but still keeping together questions dealing with the same subject. To this end, we create two groups of questions, within which questions are shuffled at random.

\documentclass[a4paper]{article}

\usepackage[utf8x]{inputenc}
\usepackage[T1]{fontenc}

\usepackage[box,completemulti]{automultiplechoice}
\begin{document}

%%% preparation of the groups

\element{geographie}{
  \begin{question}{Paris}
    In which continent is Paris?
    \begin{choices}
      \correctchoice{Europe}
      \wrongchoice{Africa}
      \wrongchoice{Asia}
      \wrongchoice{planet Mars}
    \end{choices}
  \end{question}
}

\element{geographie}{
  \begin{question}{Cameroon}
    Which is the capital city of Cameroon?
    \begin{choices}
      \correctchoice{Yaoundé}
      \wrongchoice{Douala}
      \wrongchoice{Abou-Dabi}
    \end{choices}
  \end{question}
}

\element{histoire}{
  \begin{question}{Marignan}
    In which year did the battle of Marignan take place?
    \begin{choiceshoriz}
      \correctchoice{1515}
      \wrongchoice{1915}
      \wrongchoice{1519}
    \end{choiceshoriz}
  \end{question}
}

\element{histoire}{
  \begin{questionmult}{Nantes}
    What can be said about the \emph{Édit de Nantes}?
    \begin{choices}
      \correctchoice{It was signed in 1598}
      \correctchoice{Il has been revoked by Louis XIV}
      \wrongchoice{It was signed by Henri II}
    \end{choices}
  \end{questionmult}
}

%%% copies

\onecopy{10}{

%%% beginning of the test sheet header:

\noindent{\bf QCM  \hfill TEST}

\vspace*{.5cm}
\begin{minipage}{.4\linewidth}
  \centering\large\bf History and geography\\ Examination on Jan. 1st, 2008
\end{minipage}
\namefield{\fbox{\begin{minipage}{.5\linewidth}
Firstname and lastname:

\vspace*{.5cm}\dotfill
\vspace*{1mm}
\end{minipage}}}

%%% end of the header

\begin{center}
  \hrule\vspace{2mm}
  \bf\Large Geography
  \vspace{1mm}\hrule
\end{center}

\shufflegroup{geographie}
\insertgroup{geographie}

\begin{center}
  \hrule\vspace{2mm}
  \bf\Large History
  \vspace{2mm}\hrule
\end{center}

\shufflegroup{histoire}
\insertgroup{histoire}

\clearpage

}

\end{document}

An example with a separate answer sheet

In this example, one wants the check-boxes to be put together in a separate sheet. This makes cheating more difficult, and, more importantly, it is enough to scan a single sheet per student, which makes things easier if one has to do a manual scan. In this example, the number of questions is limited: they fit into a single page, so that such a layout would not be really useful in this particular case. It is up to you to modify this example in order to use this layout with a large number of questions!

\documentclass[a4paper]{article}

\usepackage[utf8x]{inputenc}    
\usepackage[T1]{fontenc}

\usepackage[box,completemulti,separateanswersheet]{automultiplechoice}    1
\begin{document}

\AMCrandomseed{1237893}

\def\AMCformQuestion#1{\vspace{\AMCformVSpace}\par {\sc Question #1:} }    2

\element{general}{
  \begin{question}{prez}    
    Among the following persons, which one has ever been a President of the French Republic?
    \begin{choices}
      \correctchoice{René Coty}
      \wrongchoice{Alain Prost}
      \wrongchoice{Marcel Proust}
      \wrongchoice{Claude Monet}
    \end{choices}
  \end{question}
}

\element{general}{
  \begin{questionmult}{pref}    
    Among the following cities, which ones are french prefectures?
    \begin{choices}
      \correctchoice{Poitiers}
      \wrongchoice{Sainte-Menehould}
      \correctchoice{Avignon}
    \end{choices}
  \end{questionmult}
}

\element{general}{
  \begin{question}{nb-ue}
    How many different states were members of the European Union in Jan. 2009?
    \begin{choiceshoriz}[o]
      \wrongchoice{15}
      \wrongchoice{21}
      \wrongchoice{25}
      \correctchoice{27}
      \wrongchoice{31}
    \end{choiceshoriz}
  \end{question}
}

\onecopy{5}{    

%%% beginning of the test sheet header:    

\noindent{\bf QCM  \hfill TEST}

\vspace*{.5cm}
\begin{minipage}{.4\linewidth}
  \centering\large\bf Test\\ Examination on Jan. 1st, 2008
\end{minipage}

\begin{center}\em
Durée : 10 minutes.

  No documents allowed. The use of electronic calculators is forbidden.

  Questions using the sign \multiSymbole{} may have
  zero, one or several correct answers.  Other questions have a single correct answer.

  Negative points may be attributed to \emph{very
    bad} answers.

\end{center}
\vspace{1ex}

%%% end of the header

\shufflegroup{general}
\insertgroup{general}

\AMCcleardoublepage    3

\AMCformBegin    4

%%% beginning of the answer sheet header

{\large\bf Answer sheet:}
\hfill \namefield{\fbox{    5
    \begin{minipage}{.5\linewidth}
      Firstname and lastname:
      
      \vspace*{.5cm}\dotfill
      \vspace*{1mm}
    \end{minipage}
  }}

\begin{center}
  \bf\em Answers must be given exclusively on this sheet: 
  answers given on the other sheets will be ignored.
\end{center}

%%% end of the answer sheet header

\AMCform    6

\clearpage    

}  

\end{document}

The following remarks should make the above example clearer :

1

The separateanswersheet option is what allows us to do what we wanted.

2

One can re-define in this manner the way the questions are identified on the answer sheet (this line is optional).

3

This page break is put before the special page where the check-boxes are put together. If one does recto-verso printing, it is preferable to use \AMCcleardoublepage so that this page is printed apart from the others. In the case of recto printing, one can simply use \clearpage.

4

This command marks the beginning of the answer sheet part. Its use is necessary for the appropriate treatment of the questions which appear only in that part, e.g. those generated by AMCcode.

5

Students should normally write their name on the answer sheet!

6

The LaTeX command AMCform writes all the check-boxes.

[Warning]Warning

When one uses a separate answer sheet, letters (or digits, if one uses the option digits, see the section called “Package options”) are written in the check-boxes. To achieve a correct detection of the checked boxes, one has to ask students to completely fill the relevant boxes (checking by simply drawing a cross would not suffice). One also has to tune the grey level threshold (defining the proportion of black dots in a box above which that box is considered to be checked) to a value of order 0.5.

Description of the LaTeX commands

Package options

To use the automultiplechoice package, one uses the line

\usepackage[...]{automultiplechoice}

where the dots are replaced by a list of options separated by commas. Here are the available options:

  • lang=XX: sets the subject language to XX. At present, only DE (German), ES (Spanish), FR (French), IT (Italian), JA (Japanese) and NL (Dutch) are available. Several strings added by automultiplechoice will be translated, such as "None of these answers are correct", see option completemulti.

  • box: puts every question in a block, so that it cannot be split by a page break.

  • completemulti: automatically adds a "None of these answers are correct" choice at the end of each multiple question. Thus, for these questions, a distinction can be made between no answer and the answer consisting in treating none of the listed answers as correct. This behaviour can be forced or cancelled for a particular question using one of the commands \AMCcompleteMulti or \AMCnoCompleteMulti inside the corresponding questionmult environnement.

  • noshuffle: stops the automatic shuffling of the answers for every question

  • answers: produces the corrected version of the MCQ test, not the test sheet itself.

  • separateanswersheet: requires that all check-boxes be put together at the end of the test sheet (usually, this option is used when one wants to have only one sheet to scan per student - see the example in the section called “An example with a separate answer sheet”).

  • digits: if one uses the separateanswersheet option, the digits option requires the question to be identified with digits rather than with letters (which corresponds to the default setting). With this option, one has to take care that the number of answers does not exceed 9.

  • outsidebox: when using separateanswersheet, this option asks to print letters (or digits) outside the boxes on the answer sheet.

  • insidebox: when not using separateanswersheet, this options asks to print letters (or digits) inside the boxes to be filled by the students.

  • catalog: use this option to make a catalog of your questions to be used to compose future exams. No need to use \onecopy with this layout.

  • postcorrect: use this option if you want to give the correct answers after scans analysis, from a teacher completed answer sheet - see the section called “Post correcting” for details.

  • automarks: in separateanswersheet mode, use this option if you want to cancel marks printing on the subject pages. They will only be print on the answer sheet pages. To change the way pages numbers are print on the subject pages, redefine the \AMCsubjectPageTag command:

    \renewcommand\AMCsubjectPageTag{%
      \fbox{\texttt{\the\AMCid@etud:\thepage}}%
    }
    [Warning]Warning

    Only use automarks option if no data are to be collected on the subjects pages, as AMC won't be able to process these pages.

Description of a copy

The LaTeX source code describing the content of the test sheet has to be included in a call to the command \onecopy, the first argument being the number of distinct realizations to be produced, and the second argument being the code used to generate a realization.

\onecopy{50}{ ... }

If you have downloaded the LaTeX package environ before automultiplechoice, an alternative syntax is available, using the examcopy environment, where the number of realizations is an option (default is 5).

\begin{examcopy}[50]
...
\end{examcopy}
[Note]Note

The environ package is not available in the TeX Live 2007 distribution, which is still used in Ubuntu distributions up to version 9.10 (Karmic Koala).

Questions and answers

For simple questions (a single correct answer), one uses the following model:

\begin{question}{identifiant}
  Here is the question...
  \begin{choices}
    \correctchoice{The correct answer}
    \wrongchoice{A wrong answer}
    \wrongchoice{Another wrong answer}
  \end{choices}
\end{question}
[Important]Important

One must use a different identifier for every question. An identifier can be made of digits, letters, and simple characters (but do not use e.g. braces or brackets). Don't end your question identifier with a dot followed by digits, as this syntax is reserved to codes input.

[Note]Note

The maximum number of answers for a given question is limited to 199.

To keep the original order of the answers and prevent shuffling for this specific question, one can use the o option of the choices environment, replacing line 3 by the following:

\begin{choices}[o]

To put the answers on two columns, one can use the multicol package: load it in the preamble (just after the reference to the package automultiplechoice for instance) with

\usepackage{multicol}

and include the choices environment inside a multicols environment in the following manner:

  \begin{multicols}{2}
    \begin{choices}
      \correctchoice{The correct answer}
      \wrongchoice{A wrong answer}
      \wrongchoice{Another wrong answer}
    \end{choices}
  \end{multicols}

For even shorter answers, one can require questions to be printed following one another, using the choiceshoriz environment instead of choices.

Multiple questions (those for which no, one, or several answers can be correct) use the questionmult environment instead of question.

When the answer to the question is not supposed to be taken into account in the grading, one uses the \QuestionIndicative command, as in the following example:

\begin{question}{difficulty}\QuestionIndicative
  \scoring{auto=0,v=-1,e=-2}
  Did you find this class easy or difficult? Please answer on a scale from 0 (very difficult) to 5 
(very easy).
  \begin{choiceshoriz}[o]
    \correctchoice{0}
    \correctchoice{1}
    \correctchoice{2}
    \correctchoice{3}
    \correctchoice{4}
    \correctchoice{5}
  \end{choiceshoriz}
\end{question}

Putting answers on multiple columns

To put answers on several columns (and thus save space), one can embed the choices environment in a multicols environment, using the LaTeX package multicol.

If, moreover, the answers do not fit into a single line, an answer might be split over several columns, which might be a little puzzling for the reader. The \AMCBoxedAnswers command was defined in order to prevent this phenomenon, by embedding each answer into a box. Here is an example of use:

\begin{question}{two columns}
  What is a bird ?
  \begin{multicols}{2}\AMCBoxedAnswers
    \begin{choices}
      \correctchoice{It is an animal with wings, laying eggs. There are birds with all sorts of colors.}
      \wrongchoice{It is a large piece of furniture, made of wood, and used most of the time to store 
      household linen}
      \wrongchoice{It is a steam machine devised to seal cans at high speed.}
    \end{choices}
  \end{multicols}
\end{question}

Let us note that it is also possible to parametrize the vertical space between two answer blocks, thanks to the dimension AMCinterBrep:

\AMCinterBrep=.5ex

Groups of questions

Putting questions into groups allows one to shuffle questions inside these groups, in a different way for each realization of the test. Every group of questions must have a name formed solely with plain letters.

One can put questions in a group one by one, as in the following example.

\element{mygroup}{
  \begin{question}{easy}
    So, how much is one plus one?
    \begin{choiceshoriz}
      \correctchoice{two}
      \wrongchoice{zero}
      \wrongchoice{three}
    \end{choiceshoriz}
  \end{question}
}
[Important]Important

The formation of the group, using the element commands, must be made only once: thus, these commands have to be used before the onecopy command, which repeats some actions for every realization.

Once a group is formed, it is possible to shuffle questions inside this group using the shufflegroup command. For instance

\shufflegroup{mygroup}

Finally, the group content can be output to the test sheet using command insertgroup, as in

\insertgroup{mygroup}
[Note]Note

These last two commands (shufflegroup and insertgroup) are to be used inside the argument of the command onecopy, so that shuffling is performed before each realization.

Groups of questions can be manipulated more precisely thanks to the following commands:

  • \insertgroup[n]{mygroup} (using optional parameterl n) only inserts the n first elements from the group.

  • \cleargroup{mygroup} clears all group content.

  • \copygroup{groupA}{groupB} copies all the elements from group groupA to the end of group groupB. With an optional argument n, only the n first elements will be copied: \copygroup[n]{groupA}{groupB}.

With these commands, you can for exemple make a exam taking 4 questions from group GA at random, 5 questions from group GB at random, and all the questions from group GO, shuffling all these questions, with the following code (to be used inside the argument of the command onecopy):

\cleargroup{all}
\shufflegroup{GA}\copygroup[4]{GA}{all}
\shufflegroup{GB}\copygroup[5]{GB}{all}
\copygroup{GO}{all}
\shufflegroupe{all}
\insertgroup{all}

Page size, margins

The automultiplechoice LaTeX package uses geometry to set the margins and page layout. You can overwrite its settings using the \geometry command just before the \begin{document} - see the geometry package documentation for details. The values initially set by AMC are:

\geometry{hmargin=3cm,headheight=2cm,headsep=.3cm,footskip=1cm,top=3.5cm,bottom=2.5cm}

When reducing the margins to gain some space, keep in mind that:

  • The four corner marks must be printed entirely (they could disappear due to the printer margins).

  • The four corner marks must be entirely visible on the scans (if they are too close from the border and the paper moved a little or turned a little during scanning, this could not be the case).

It is also possible to set the paper size as an option to add to the list given as argument to the \geometry command. Available values include a4paper, a5paper, a6paper, b4paper, b5paper, ansibpaper, ansicpaper, ansidpaper, letterpaper, executivepaper, legalpaper.

For small paper sizes, it may also be interesting to change the position of the human readable sheet IDs (like +1/1/53+) in the header. This can be done using the \AMCidsPosition command, in the form

\AMCidsPosition{pos=p,width=w,height=h}

where p can be none, top or side, and the dimensions w and h refers to the (invisible) box containing the ID. The default values are

\AMCidsPosition{pos=side,width=4cm,height=3ex}

Let us end with an example for A5 paper sheets:

\geometry{a5paper,hmargin=1.6cm,top=2.5cm}
\AMCidsPosition{pos=top}

Check-box presentation style

The \AMCboxDimensions command allows one to modify one or several dimensions of the check-boxes.

  • shape is the shape of the boxes. Use the value square to get squares or rectangles, and oval to get circles or ovals. Note that the LaTeX package tikz must be loaded for oval to work.

  • width is the width of the box;

  • height is the height of the box;

  • size is the size (width and height) of the box;

  • rule is the thickness of the boundary of the box;

  • down controls by how much boxes are pushed down.

To obtain smaller boxes, one can e.g. use the command

\AMCboxDimensions{size=1.7ex,down=.2ex}

When using separateanswersheet package option, you can also customize the boxes labelling. The default behaviour is to use uppercase alphabetical labelling, or arabic numbering if the digits package option is used. To use your own labelling, one has to redefine the \AMCchoiceLabel command which takes as argument the name of the counter used to number the choices. For example, the following code will ask for lowercase letters to label the boxes:

\def\AMCchoiceLabel#1{\alph{#1}}

As an other example, when using arabxetex package, the following code may be useful:

\def\AMCchoiceLabel#1{\textLR{\Alph{#1}}}

One can also change the style of the boxes labels redefining the \AMCchoiceLabelFormat command, as in the following example (here we need bold labels):

\def\AMCchoiceLabelFormat#1{\textbf{#1}}

Also note that the color of the boxes to be ticked by the students can be set using

\AMCboxColor{red}

replacing red by the desired color (that must be recognized by the xcolor package). For example, you can get a light green with

\definecolor{amcboxcolor}{rgb}{0.67,0.88,0.5}
\AMCboxColor{amcboxcolor}

Questions presentation style

The way each question is presented can be modified by redefining the LaTeX command AMCbeginQuestion, whose default definition is the following:

\def\AMCbeginQuestion#1#2{\par\noindent{\bf Question #1} #2\hspace*{1em}}

The first parameter transmitted to this command is the number of the question to be displayed. The second parameter contains \multiSymbole in the case of a multiple question, and is void in all other cases. The \multiSymbole command too can be modified: its goal is to distinguish multiple questions from the others. By default, it displays a club.

\def\multiSymbole{$\clubsuit$}

Finally, one can modify the number of the next question with the \AMCnumero command. At the beginning of each realization of the test, a call to

\AMCnumero{1}

is performed, but this command can be used at any place.

The display of answers can be modified in the same fashion, if one uses the choicescustom environment instead of choices or choiceshoriz, redefining the three following LaTeX macros:

\def\AMCbeginAnswer{}
\def\AMCendAnswer{}
\def\AMCanswer#1#2{#1 #2}

One can also change spacing redefining the following dimensions (here are the default values):

\AMCinterIrep=0pt
\AMCinterBrep=.5ex
\AMCinterIquest=0pt
\AMCinterBquest=3ex

These dimensions are the vertical space between questions (quest) or answers (rep), in boxed mode (B, with \AMCBoxedAnswers or box package option) or standard mode (I).

Separate answer sheet presentation style

It is also possible to modify the layout of the separate answer sheet produced with the separateanswersheet option (see section the section called “An example with a separate answer sheet”).

  1. If one only wants to modify the horizontal spacing between two check-boxes or the vertical spacing between two questions, one just has to redefine the following dimensions:

    \AMCformHSpace=.3em
    \AMCformVSpace=1.2ex
    
  2. For a deeper modification of the display settings, one can also redefine the commands that are used at the beginning of each question and for each answer (here follows the default definitions):

    \def\AMCformQuestion#1{\vspace{\AMCformVSpace}\par{\bf Question #1:}}
    \def\AMCformAnswer#1{\hspace{\AMCformHSpace} #1}
    

These definitions have to be inserted just after \begin{document} in the LaTeX file.

Code acquisition

Code acquisition can be easily performed thanks to the LaTeX command AMCcode, for instance to allow each student to enter her/his student number by herself/himself on the answer sheet. The two arguments of this command are a code/question identifier, and the number of digits to be used by the code. One can e.g. use the following header

{\setlength{\parindent}{0pt}\hspace*{\fill}\AMCcode{etu}{8}\hspace*{\fill}
\begin{minipage}[b]{6.5cm}
$\longleftarrow{}$\hspace{0pt plus 1cm} please encode your student number below,
and write your first and last names below.

\vspace{3ex}

\hfill\namefield{\fbox{    
    \begin{minipage}{.9\linewidth}
      Firstname and lastname:
      
      \vspace*{.5cm}\dotfill
      
      \vspace*{.5cm}\dotfill
      \vspace*{1mm}
    \end{minipage}
  }}\hfill\vspace{5ex}\end{minipage}\hspace*{\fill}

}

If the separateanswersheet option is used, the AMCcode command has to be placed after the AMCformBegin command.

Note that the codes rendering from \AMCcode can be adapted modifying the lenghts \AMCcodeHspace, \AMCcodeVspace and \AMCcodeBoxSep, representing the horizontal and vertical amount of space between boxes, and the amount of space between boxes and labels (when the labels are written outside the boxes). Defaut values are set with the following commands:

\AMCcodeHspace=.5em
\AMCcodeVspace=.5em
\AMCcodeBoxSep=.1em

Note that an horizontal version AMCcodeH is also available, specially for the case of small number of digits.

Open questions

One can sometimes require some open questions to be added to the subject. One way to do so is to reserve boxes use to the teacher for these questions. After the exam, the teacher reads the completed answer sheets and tick the boxes according to the answers written by the students for open questions. He will then scan the sheets and let AMC correct the multiple choice questions and integrate the open questions scores into the marks.

\begin{question}{open}
  Define \emph{inflation}.
  \AMCOpen{lines=5}{\wrongchoice[W]{w}\scoring{0}\wrongchoice[P]{p}\scoring{1}\correctchoice[C]{c}\scoring{2}}
\end{question}

In this example, the teacher will get three boxes. If the first (labelled W for wrong) is ticked, the student will get 0 points. If the second (labelled P for partial) is ticked, the student will get 1 point. If the third (labelled C for correct) is ticked, the student will get 2 points.

The first argument to \AMCOpen is a comma separated list of options. The available options are:

lineup=bool

if true, the answering area and the scoring boxes will be on the same line. If false (this is default), the answering area is enclosed in a frame and placed below the scoring boxes.

lines=num

sets the number of lines for the answer. Default value is 1.

lineheight=dim

sets the height of each line. Default value is 1cm.

dots=bool

if true (defaut), each line will be realized by a line of dots.

contentcommand=cmdname

Use this option if you want to customize the content of the answer area. You will have to define a \cmdname command that has to produce the content.

hspace=dim

sets the space between boxes in the marking area.

backgroundcol=color

sets the background color of the marking area.

foregroundcol=color

sets the foreground color of the marking area.

scan=bool

if false, the boxes are not scanned (this can be useful if you plan to use manual data capture only to mark this question, and don't want to take into account the students drawings on the boxes). Defaults to true.

annotate=bool

if false (default value), the boxes from this question won't be annotated when annotating the answer sheets (only the score will be written).

question=text

sets a short text that helps the examiner to identify the question. This text will be written before the scoring boxes, only if a separate answer sheet is used.

answer=text

sets a short text that will be written in the answering area for corrected answer sheets.

width=dim

sets the width of the frame enclosing the answering area when lineup=false. Default value is .95\linewidth.

framerule=dim

sets the line width for the frame enclosing the answering area.

framerulecol=color

sets the frame color for the answering area.

boxmargin=dim

sets the margin around the scoring boxes.

boxframerule=dim

sets the line width for the frame around the scoring boxes.

boxframerulecol=color

sets the color of the frame around the scoring boxes.

You can set other default values (for the whole exam) for all these parameters using the command \AMCopenOpts, like

\AMCopenOpts{boxframerule=2pt,boxframerulecol=red}

Moreover, a little text can be written in the marking area to tell the students not to tick these boxes, redefining the \AMCotextReserved command, as:

\def\AMCotextReserved{\emph{Reserved}}

When using separate answer sheets, the text added to each open question can also be defined, as:

\def\AMCotextGoto{\par{\bf\emph{Please write the answer on the separate answer sheet.}}}

Choice of shuffling parameters

One can modify the seed of the random number generator used to produce the shuffle, thanks to the following command (to be used just at the beginning of the document, and in any case outside the onecopy command):

\AMCrandomseed{1527384}

If the value that is assigned (to be chosen between 1 and 4194303) is modified, then the shuffling will differ. Of course, one must not modify this value after the test sheets have been printed.

Using sectioning and separate answer sheet

For sectioning to be also visible in the separate answer sheet (if any), use \AMCsection and \AMCsubsection instead of \section and \subsection.

Using references inside the test sheets

Using LaTeX commands \label, \ref and \pageref within questions or answers is problematic since they will be called with the same arguments for every realization of the test, which will alter the numbering of references. To solve this problem, one should use instead the commands\AMClabel, \AMCref and \AMCpageref: they add the realization number to their argument before transmitting it to \label, \ref and \pageref.

One also has to reset counters to zero at the beginning of each realization. For instance, if one wants to include references to pictures that are put together in a separate page, one might write something like

\element{animals}{
  \begin{figure}[p]
    \centering
    \includegraphics[width=.6\linewidth]{tiger}
    \caption{An animal}
    \AMClabel{tiger}
  \end{figure}
    
  \begin{question}{tiger}
    Which is the animal on figure~\AMCref{tiger} page~\AMCpageref{tiger}?
    \begin{choices}
      \correctchoice{A tiger}
      \wrongchoice{A giraffe}
      \wrongchoice{An elephant}
      \wrongchoice{A cat}
    \end{choices}
  \end{question}
}

and it is then important to add, just after the command \onecopy the line

\setcounter{figure}{0}

so that the numbering of figures starts at 1 for every realization. Without that last command, the numbering of figures would go on from one realization to the next one, which is clearly not desirable.

Customizing some texts inserted by AMC

Use \AMCtext for the following customizations:

  • \AMCtext{none}{sentence} replaces « None of these answers are correct. » (the English default text) with the given sentence when using option completemulti.

  • \AMCtext{corrected}{title} replaces « Corrected » (the English default text) with the given title on the corrected answer sheet.

  • \AMCtext{catalog}{title} replaces « Catalog » (the English default text) with the given title on the questions catalog produced thanks to option catalog.

  • You can also consider using commands like the following ones (here the second argument is set to the default English value):

    \AMCtext{draft}{DRAFT}
    \AMCtext{message}{For your examination, preferably print documents
                      compiled from auto-multiple-choice.}

Options for AMC

You can add in the source file header (the first lines that begin with a '%') some options to be passed to AMC:

%%AMC:preprocess_command=commandname

tells AMC to run the commandname command before calling LaTeX to process the source file. This command will be run inside the project directory, and the name of a source file copy will be passed as an argument. There is no problem for commandname to change this file content, because this is only a copy.

%%AMC:latex_engine=engine

tells AMC to set the LaTeX engine to use for this file, regardless to the one entered as a preference by the user.

Mathematical questions with randomized statements

Using package fp

Thanks to the LaTeX package fp, whose documentation is available at http://mirrors.ctan.org/macros/latex/contrib/fp/README, and which can be downloaded with the command

\usepackage{fp}

added before that corresponding to automultiplechoice, one can create exercises with randomized numerical data. Let us start with a simple example.

\begin{question}{addition}
  \FPeval\VQa{trunc(1+random*8,0)}  1
  \FPeval\VQb{trunc(4+random*5,0)}
  \FPeval\VQsomme{clip(VQa+VQb)}  2
  \FPeval\VQnonA{clip(VQa+VQb-1)}  3
  \FPeval\VQnonB{clip(VQa*VQb)}
  \FPeval\VQnonC{clip(VQa-VQb)}

  What is the sum of \VQa{} et \VQb{} ?
  \begin{choiceshoriz}
    \correctchoice{\VQsomme}
    \wrongchoice{\VQnonA}
    \wrongchoice{\VQnonB}
    \wrongchoice{\VQnonC}
  \end{choiceshoriz}
\end{question}

The \FPeval command is used to perform computations:

1

Since random returns a real number in the interval [0,1], this command sets VQa to a random integer value between 1 et 8. The next line sets VQb to a random integer value between 4 et 8.

2

Putting the correct answer in the variable VQsomme.

3

Putting wrong answers in variables VQnonA, VQnonB et VQnonC...

Variable names beginning with VQ have been chosen so as to avoid interference with other LaTeX commands.

Choosing an interval

The automultiplechoice package moreover defines a \AMCIntervals command which makes this kind of construction simpler, as illustrated in the next example:

\begin{question}{inf-expo-indep}
  \FPeval\VQa{trunc(2 + random * 4,0)}
  \FPeval\VQb{trunc(6 + random * 5,0)}
  \FPeval\VQr{VQa/(VQa+VQb)}
  
  Let $X$ and $Y$ be two independent random variables, following the exponential distribution with
respective parameters \VQa{} et \VQb{}.
  To which interval does the probability $\mathbb{P}[X<Y]$ belong ?

  \begin{multicols}{5}
    \begin{choices}[o]
      \AMCIntervals{\VQr}{0}{1}{0.1}  1
    \end{choices}
  \end{multicols}
\end{question}

1

This lines inserts ten answers corresponding to the intervals [0,0.1[ [0.1,0.2[ ... [0.9,1[, while indicating that the correct interval is the one containing VQr. The arguments of the \AMCIntervals command are the following:

  1. The correct answer,

  2. The left point of the first interval,

  3. The right point of the last interval,

  4. The length of each interval.

Note that the interval formatting can be changed redefining the \AMCintervalFormat command, which is originally defined as

\def\AMCIntervalFormat#1#2{[#1,\,#2[}

to follow local conventions (writting [a,b) instead of [a,b[ is for example a common usage).

Coding the result

The students can also be asked to code the numerical answer, using the \AMCnumericChoices command, as in the following example:

\begin{questionmultx}{sqrt}
  \FPeval\VQa{trunc(5+random*15,0)}
  \FPeval\VQs{VQa^0.5}
  Compute $\sqrt{\VQa}$ and round it with two digits after period.

  \AMCnumericChoices{\VQs}{digits=3,decimals=2,sign=true,
                 borderwidth=0pt,backgroundcol=lightgray,approx=5}
\end{questionmultx}

Note the use of questionmultx environment: we need this question to be multiple as several boxes has to be ticked, but we can’t say that several answers are correct, so we don’t show the symbol for multiple questions.

Available options that can be used in the second argument of the \AMCnumericChoices command are the following (bool can be true or false, and color must be a color known by the xcolor package):

digits=num

gives the number of digits to request (defaults to 3).

decimals=num

gives the number of digits after period to request (defaults to 0). Note that when num is positive, the LaTeX package fp must be loaded.

base=num

gives the base for digits and decimals (defaults to 10).

significant=bool

if true, the numbers to code are the first significant digits from the first argument of \AMCnumericChoices. For example, the right answer to \AMCnumericChoices{56945.23}{digits=2,significant=true} is 57.

nozero=bool

if true, the choice 0 is removed for all digits. May be useful when using \AMCnumericChoices to enter small (<10) positive values.

sign=bool

requests (or not) a signed value (defaults to true).

strict=bool

if true, a box has to be ticked for every digit and for the sign. If false, if some digits has no ticked box, they will be set to zero. Defaults to false.

vertical=bool

if true, each digit is represented on one raw. If false (default), each digit is represented on one line.

reverse=bool

if true, place higher values of the digits on the top in vertical mode (defaults to true).

vhead=bool

if true, in vertical mode, a header is placed over all digits rows, made using the command \AMCntextVHead that is originally defined as

\def\AMCntextVHead#1{\emph{b#1}}

This default value is useful to number the binary digits.

Default value is false.

hspace=space

sets the horizontal space between boxes (defaults to .5em).

vspace=space

sets the vertical space between boxes (defaults to 1ex).

borderwidth=space

sets the width of the frame border around all the boxes (defaults to 1mm).

bordercol=color

sets the color of the frame (defaults to lightgray).

backgroundcol=color

sets the background color (defaults to white).

Tsign=text

sets the text to print at the top of the boxes to set the sign (Can also be redefined by \def\AMCntextSign{text}, and defaults to be empty).

Tpoint=text

sets the text for the period. Can also be redefined by \def\AMCdecimalPoint{text}, and defaults to \raisebox{1ex}{\bf .}.

scoring=bool

if true, a scoring strategy is given to AMC for this question. Defaults to true.

scoreexact=num

gives the score for an exact answer (defaults to 2).

exact=num

sets the maximal distance to the correct integer value (value without the decimal point) for an answer to be said exact and be rewarded to scoreexact points (defaults to 0).

scoreapprox=num

gives the score for an approximative answer (defaults to 1).

approx=num

sets the maximal distance to the correct integer value (value without the decimal point) for an answer to be said approximative and be rewarded to scoreapprox points (defaults to 0).

You can set other default values (for the whole exam) for all these parameters using the command \AMCnumericOpts, like

\AMCnumericOpts{scoreexact=3,borderwidth=2pt}

Moreover, the text added at the end of the questions using \AMCnumericChoices when not in the separate answer sheet (and when a separate answer sheet is requested by the separateanswersheet package option) can also be set redefining the \AMCntextGoto command, as:

\def\AMCntextGoto{\par{\bf\emph{Please code the answer on
                           the separate answer sheet.}}}

Using package pgf/tikz

LaTeX package pgf/tikz (see http://www.ctan.org/tex-archive/graphics/pgf/base) provides mathematical functions that can be loaded with

\usepackage{tikz}

First of all, you must set the random seed to be sure to get the same result each time latex is run to compile the subject:

\pgfmathsetseed{2056}
A simple computation

Here is an exemple with a simple computation:

\begin{question}{inverse}
  \pgfmathrandominteger{\x}{1}{50}
       
  How much is the reciprocal of $x=\x$?

  \begin{choices}
    \correctchoice{\pgfmathparse{1/\x}\pgfmathresult }
    \wrongchoice{\pgfmathparse{1/(\x +1))}\pgfmathresult}
    \wrongchoice{\pgfmathparse{cos(\x)} \pgfmathresult}
    \wrongchoice{\pgfmathparse{\x^(-0.5)}\pgfmathresult}
  \end{choices}
\end{question}

Here, the command \pgfmathparse makes the computation, and \pgfmathresult outputs the result.

Output formatting is also available with the command \pgfmathprintnumber, as in the following exemple (three digits after decimal point, and use of the comma as a decimal point).

\begin{question}{inverse3}
  \pgfmathrandominteger{\x}{1}{50}
  \pgfkeys{/pgf/number format/.cd,fixed,fixed zerofill,precision=3,use comma}
  How much is the reciprocal of $x=\pgfmathprintnumber{\x}$?

  \begin{choices}
    \correctchoice{\pgfmathparse{1/\x}\pgfmathprintnumber{\pgfmathresult}} 
    \wrongchoice{\pgfmathparse{1/(\x +1))} \pgfmathprintnumber{\pgfmathresult}}
    \wrongchoice{\pgfmathparse{cos(\x)} \pgfmathprintnumber{\pgfmathresult}}
    \wrongchoice{\pgfmathparse{\x^(-0.5)} \pgfmathprintnumber{\pgfmathresult}}
  \end{choices}
\end{question}
[Note]Note

You can also use the \AMCIntervals and \AMCnumericChoices commands (see the section called “Choosing an interval” and the section called “Coding the result”)

Graphics

The tkiz package also allows to make (random or not) graphs.

\begin{questionmult}{graph}
  Let us consider the three functions which graphs are plotted below:
  \pgfmathrandominteger{\a}{2}{4}  
  \begin{center}
    \begin{tikzpicture}[domain=0:4]
      \draw[very thin,color=gray] (-0.1,-4.1) grid (3.9,3.9);
      \draw[->] (-0.2,0) -- (4.2,0) node[right] {$x$};
      \draw[->] (0,-4.2) -- (0,4.2) node[above] {$f(x)$};
      \draw[color=red] plot (\x,{(1+\a/4)*\x-\a}) node[right] {$f_{1} (x)$};
      \draw[color=blue] plot (\x,{\a*sin(\x r)}) node[right] {$f_{2}(x)$};
      \draw[color=orange] plot (\x,{\a*cos(\x r)}) node[right] {$f_{3}(x)$};
    \end{tikzpicture}
  \end{center}
  Then:
  \begin{choices}
    \pgfmathrandominteger{\x0}{2}{4}  
    \correctchoice{$f_{2}(\x0)$=\pgfmathparse{\a*sin(\x0 r)} \pgfmathprintnumber{\pgfmathresult}.}
    \correctchoice{$f_{3}(\x0)$=\pgfmathparse{\a*cos(\x0 r)} \pgfmathprintnumber{\pgfmathresult}.}
    \wrongchoice{La fonction $f_{1}(x)$ est une fonction linéaire.}
  \end{choices}
\end{questionmult}

To make pretty graphs, package pgfplots can also be useful.

With pgfmath, precision is limited, so that a "Arithmetic overflow" error can be encountered. Packages tikz and pgfplots allows to overcome this problem, using gnuplot as a backend. You need to install gnuplot on your system, and use LaTeX option --shell-escape. To this purpose, go to AMC preferences window, and set the LaTeX engine for your project to "pdflatex --shell-escape" (without the quotes).

Using LuaLaTeX

LUA language can be used inside LaTeX documents thanks to the lualatex command. If you uses it, your document needs to be UTF-8 encoded, and you must not load the inputenc package. See http://www.luatex.org/documentation.html for some information.

LUA commands are to be given as a \directlua argument. The most useful LUA function is tex.print, which will output results back to LaTeX.

Once again, if you use random numbers, allways fix the random seed to get the same results across differents compilations:

\directlua{math.randomseed (2048)}

Here is a very simple sample source file:

\documentclass[a4paper]{article}
%\usepackage[utf8x]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[box,completemulti]{automultiplechoice}
\begin{document}

\onecopy{10}{

%%% head

\noindent{\bf QCM  \hfill TEST}

\vspace*{.5cm}
\begin{minipage}{.4\linewidth}
  \centering\large\bf LuaLaTeX sample exam
\end{minipage}
\namefield{\fbox{\begin{minipage}{.5\linewidth}
Name :

\vspace*{.5cm}\dotfill
\vspace*{1mm}
\end{minipage}}}

%%%

\directlua{math.randomseed (2048)}
\directlua{a=math.random()}

\begin{question}{square-root}
  How much is the square root of \directlua{tex.print(a)}?

  \begin{choices}
    \correctchoice{\directlua{tex.print(math.sqrt(a))}} 
    \wrongchoice{\directlua{tex.print(math.sqrt(2*a))}} 
    \wrongchoice{\directlua{tex.print(math.sqrt(a*1.001))}} 
  \end{choices}
\end{question}

\clearpage
}

\end{document}      

Output formatting can be obtained using lua functions, or with the siunitx package.

[Note]Note

You can also use the \AMCIntervals and \AMCnumericChoices commands (see the section called “Choosing an interval” and the section called “Coding the result”)