» Home Page
MCQ-XeLaTeX: Multiple Choice Questions for mathematics and LaTeX

Multiple Choice Questions in LaTeX, and OMR (Optical Mark Recognition)

MCQ-XeLaTeX is a program I've been using and developing over the last few years, to author, manage, mark, analyse and transcode exams based on Multiple Choice Questions entirely in LaTeX. It is supposed to be multi-platform (it runs on unix/linux, mac and with a few limitations, due to missing system libraries, on windows - with or withour cygwin), and features an OMR (Optical Mark Recognotion) engine to automatically grade/mark the exam sheets. By design it does not have any Graphical User Interface, and it reinforces a paranoid control model, where every step of the process is accountable, verified, logged and traced. It can help performing the following tasks, keeping the possibility that each of the steps can be performed manually as a failsafe procedure.

Authoring: The format of the questions is LaTeX, with the LaTeX style mcq.sty. For a series of reasons it is necessary to compile it with the xelatex engine, to see a PDF printable version (useful for reviewing and proof-reading). The questions can be just exported to MOODLE or saved as dynamical HTML.

Managing and shuffling: Given a list of questions, it can generate n copies of the exam sheet, each with a permutation of the questions, and each question with permuted answers. Plus, there are truth/false questions, and variants of multiple choice questions. Each sheet has a unique barcode, and the students can be identified by their UID. A table with UID's and student names can be used to fill the names. If you have a list of previous files with MCQ questions (a question bank, a library of questions), mcq.py can choose a random sample of questions.

Marking: If you have a scanner, you can automatically mark the answer sheets (bubblesheets), and export a CSV file with the results. Double-checking possible mistakes is performed by reviewing a visually annotated PDF. The OMR (Optical Mark Recognition) is automatic and reasonably reliable (being a client-server model, it needs internet: the actual Mark Recognition is performed elsewhere, on a secure server). But it is easy, if and where needed, to revert to manual human marking.

Analysing: A few simple statistical indices are computed on the marking data (facility index, discrimination index, non-responses), helping to assess problems.

Transcoding: The MCQ LaTeX format is sufficiently abstract, that mcq.py can export GIFT files (to be imported on a MOODLE course) or dynamical HTML files (such as these examples). In the latter case, the resulting HTML files will be self-contained, will display mathematical symbols with MathJax and will be dynamical (showing proper feedback to readers) with CSS+Javascript (see these examples).


Check the requirements below, first. Then simply download the files mcq.py and mcq.sty, put them in some proper path, and then run


in a terminal. Then follow the on-screen instructions.

A typical list of actions might be:

> generate a new file main.tex
> add exercises to main.tex, compile it, review it, print it, until ready.
> `exam 120` : generated 120 different copies to print and give to students.
> scan the students sheets, or, if no scanner works, create a TXT file 
  with the students answers.
> `omr scannedfiles*.pdf` : perform Optical Mark Recognition on the scanned sheets,
   and obtain a TXT file of their answers, which can be reviewed and modified
   with any text editor (vim, emacs, notepad). 
> `open main_answers.pdf` : open an annotated copy of the student scanned answers,
   to review possible system errors or human mistakes. 
> `uid uidlist.csv`  : add student names to the reviewed answers file, 
   taken from the file `uidlist.csv`. 
> `mark` : evaluate and mark. The output can be later processed with
   any spreadsheet software, or text editor. 
> `makestats` : make a PDF versione of the exam, with annotations
   about some statistical indices. 
> `export main.gift` : export the questions in GIFT format.
> `export main.html` : export the questions in HTML format. 

Since a session usually takes several days, the status is kept persistent between partial sessions, and a few checks are performed, to be sure to avoid simple mistakes. If after delivering the exam you notice that some questions were wrongly evaluated, or some correct answers wrongly attributed, it is always possible to trace back a few steps and correct the mistake, by checking the logs and manually modifying the proper files.


Consider the file example.tex, which produces this PDF (it is a subset of a the Multiple Choice questions written by T. Tao). First we generate and print 10 permuted copies, then we collect the scanned OMR filled sheets like this file, and let mcq.py do the rest. In this example I've used all possible wrong pens, with different outcomes. A sample session can be of some help to understand the workflow (I used `vi` to edit the text files, but of course it is not mandatory: you can use whatever text editor works). The stats output can be generated after the marking.

Some enhancements to the scanned files might be necessary: an example of preprocessing can be found in this bash script.


Requirements are very minimal, and the program has been tested on a variety of platforms.

To install the OTF/TTF font Linux Libertine, as follows:

To install mcq.sty in a place where it can be found by TeX: the main point is to know what is the value of TEXMFHOME, for the local TeX installation. So, run

kpsewhich -var-value TEXMFHOME

and check the output (see how to have private installations of files). Then, add mcq.sty to ${TEXMFHOME}/tex/latex/, or to a subdirectory in it, and run texhash. Or, simply put mcq.sty in the directory where you plan to work.

For example:

To install mcq.py in a place where it can be automatically found by your shell, it suffices to put it in one of the directories listed in the environment variable PATH (${PATH}, or %PATH% accordingly).

Do not forget to make it executable: control-click on the file, or

chmod +x mcq.py

How it works

(to appear)

LaTeX commands and environments

(to appear) Please try to read the (outdated) manual page and quick install page. There is a google-translate button somewhere for the few not understanding Italian. Also, there are some comments in mcq.sty and some explanation in the in-line help of the software itself.

Similar programs


comments powered by Disqus

End-User License Agreement (EULA)

You can use the software described and linked in this page as a trial and evaluation, as-it-is, without any guarantee, at the following additional conditions. By downloading the files you automatically accept these terms and conditions.

Creative Commons License
This work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License.