Yaml Based Exams

Introduction

Ybe is a software package supporting a YAML based file format for importing, exporting and storing exams in a plain text file. It supports multiple-choice, multiple-response and essay questions. Due to the extensive meta-data storage, storing exams in ybe allows you to easily search, annotate and recombine questions into new exams. Exams can be written as a LaTeX file, or be exported to the QTI format and be imported by Canvas and other educational software.

Examples

Questions can be stored in a plain text file using YAML for structure and Markdown for the content of the questions.

Minimal .ybe file

For example, a minimal example of a multiple choice question is given by:

ybe_version: 0.2.0

questions:
- multiple_choice:
    id: q1
    points: 1
    text: Example multiple choice question.
    answers:
        - answer:
            text: First answer
        - answer:
            text: Second answer
            correct: true

This defines a list of questions with only one question. The id is meant to be provide a unique identifier to every question and should be unique for every question in an .ybe file. The points define the worth of the question. The text is in Markdown format and allows all Markdown operators. The answers are again a list with Markdown text blocks and a marked correct answer.

Exporting to QTI

If you would copy the previous Ybe content into a text file named example.ybe, you could export it to a QTI using:

from ybe import read_ybe_file
from ybe.lib.qti_writer import \
    write_qti_zip, \
    ConvertCanvasEquations

ybe_exam = read_ybe_file('example.ybe')

# QTI with Canvas style equations
write_qti_zip(ybe_exam, 'qti_canvas.zip',
              text_formatter=ConvertCanvasEquations())

Exporting to LaTeX

Alternatively, you could output your exam to a Latex file read for printing:

from ybe import read_ybe_file, write_latex_file

ybe_exam = read_ybe_file('example.ybe')
write_latex_file(ybe_exam, 'main.tex')

Supported question types

An example of an ybe file with all supported questions and some file meta data is given by:

ybe_version: 0.2.0

info:
    title: Example questions
    description: Example of all questions.
    document_version: 0.1.0
    date: 2020-05-24
    authors:
        - The Author

questions:
- multiple_choice:
    id: q1
    points: 1
    text: Example multiple choice question.
    answers:
        - answer:
            text: First answer
        - answer:
            text: Second answer
            correct: true

- open:
    id: q2
    points: 3
    text: Example open question.

- multiple_response:
    id: q3
    points: 2
    text: A multiple response question is a
        multiple choice question, where
        multiple answers are possible.
    answers:
        - answer:
            text: First answer
            correct: true
        - answer:
            text: Second answer
        - answer:
            text: Third answer
            correct: true
        - answer:
            text: Fourth answer

- text_only:
    id: q4
    text: |-
        Since "text" is short for "text_markdown",
        you can use Markdown syntax to markup
        your document.

        For example:

        1. this is a list
        2. *with this in italics*
        3. **and in bold**

        This is a famous formula inline: $E=mc^2$
        and this is a basic displayed formula:

        $$ a^2 = b^2 + c^2 $$

Adding meta-data

In addition, Ybe supports adding meta-data to your questions. This allows you to store a description of the question, the lifecycle (like, who made this question), a classification of for example the skill level and question analytics where you can store statistics of past usage of this question. This can all be stored as follows:

questions:
- open:
    id: q5
    points: 1
    text: Example with meta data
    meta_data:
        general:
            description: Some description for yourself
            keywords: [alpha, beta]
            language: en
        lifecycle:
            author: The Author
        classification:
            skill_level: Knowledge
            related_concepts: [Ybe]
            module: Science
            chapter: 1
            difficulty: 1
        analytics:
            - exam:
                name: 2020_qz1
                participants: 1
                nmr_correct: 0
            - exam:
                name: 2020_qz1
                participants: 200
                nmr_correct: 25

Searching your questions

If you would save the above in a file example.ybe, you could then search through the questions easily. For example, finding all questions that yield exactly one point can be done like:

from ybe import read_ybe_file

ybe_exam = read_ybe_file('example.ybe')

for question in ybe_exam.questions:
    if question.points == 1:
        print(question)

Importing from QTI

If you already have questions in Canvas or other software packages, you could export these to QTI format and convert easily into an .ybe file:

from ybe import read_qti_zip, write_ybe_file
from ybe.lib.utils import copy_ybe_resources

ybe_exam = read_qti_zip('qti_file.zip')

# write the ybe file
write_ybe_file(ybe_exam, './qti_to_ybe.ybe')

# and write the images referred to in the QTI
copy_ybe_resources(ybe_exam, './')

Summary

In general:

  • Storing exams in a plain-text .ybe file
  • Importing and exporting to and from QTI
  • Write exams to LaTeX
  • API for scripting exams

Technical details:

Quick installation guide

Ybe requires Python 3.8+. Either use your package manager, or install a Python distribution like Anaconda. After that it is typically as simple as:

pip install ybe

Linux

For Ubuntu 18.xx you need to install Python 3.8 first, for example see here: https://linuxize.com/post/how-to-install-python-3-8-on-ubuntu-18-04/. Afterwards, simply install using:

pip3 install ybe

For other Linux distributions the setup is typically similar, install Python 3.8 and then install ybe.

Windows

  • Install Anaconda Python 3.8
  • Open an Anaconda shell and type: pip install ybe

Mac

  • Install Anaconda Python 3.8
  • Open an Anaconda shell and type: pip install ybe