ybe 0.3.6

Simple software package for storing exams.

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 , HTML or plain text, 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
    title: Optional title
    points: 1
    text: !markdown 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. By prefixing the text with !markdown we indicate that that the text is in Markdown format and as such allows all Markdown operators. The answers are not prefixed with !markdown making them plain text. The item correct marks the 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, YbeToQTI_v1p2

ybe_exam = read_ybe_file('example.ybe')

# QTI v1.2 for use in Canvas
YbeToQTI_v1p2(convert_canvas_equations=True).convert(ybe_exam, 'qti_canvas.zip')

Exporting to other formats

Alternatively, you could export your Ybe exam file to other formats like Latex, Markdown, HTML or Docx/ODT:

from ybe import read_ybe_file, \
    YbeToLatex, YbeToMarkdown, YbeToDocx, YbeToODT, YbeToHTML

ybe_exam = read_ybe_file('example.ybe')

YbeToLatex().convert(ybe_exam, '/tmp/ybe/latex/main.tex', copy_resources=True)
YbeToMarkdown().convert(ybe_exam, '/tmp/ybe/markdown/main.md', copy_resources=True)
YbeToHTML().convert(ybe_exam, '/tmp/ybe/html/main.html', copy_resources=True)
YbeToDocx().convert(ybe_exam, '/tmp/ybe/main.docx')
YbeToODT().convert(ybe_exam, '/tmp/ybe/main.odt')

This compiles all your questions in a single Latex, Markdown, HTML or docx/odt file for printing or further processing. For technical minded people, this uses a Jinja2 templating system which can be fully adapted for your specific needs.

Supported question types

Ybe supports multiple choice, multiple response, text-only and open/essay questions. 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
    title: Questions can have a title
    points: 1
    text: Example multiple choice question.
    answers:
        - answer:
            text: First answer
        - answer:
            text: Second answer
            correct: true
    feedback:
        general: Here's the explanation for
                the correct and incorrect
                answer (or "general comments")
        on_correct: Here's the explanation for
                    the correct answer.
        on_incorrect: Here's the explanation
                      for the incorrect answer.

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

- multiple_response:
    id: q3
    points: 2
    text: !html A multiple response <b>question<b/> is a
        multiple choice question, where
        multiple answers are possible.
    answers:
        - answer:
            text: First answer
            correct: true
            hint: Multiple choice/response answers
                  can have hints.
        - answer:
            text: Second answer
            hint: This is not correct!
        - answer:
            text: Third answer
            correct: true
        - answer:
            text: Fourth answer

- text_only:
    id: q4
    text: !markdown |-
        This text is prefixed with !markdown, meaning 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 $$

Support for hints and explanations

Ybe supports comments to the answer of a question by means of hints and explanations. Explanations can be added to any question and allow commenting on the provided answer. Hints are meant as a comment to a selected multiple choice or multiple response answer. In Ybe, these can be added as follows:

questions:
- multiple_choice:
    id: q1
    points: 1
    text: Example multiple choice question.
    answers:
        - answer:
            text: First answer
            hint: This is the wrong answer
        - answer:
            text: Second answer
            correct: true
            hint: This is the correct answer
    feedback:
        general: General comment after finishing the question.
        on_correct: Here's the explanation for the correct answer.
        on_incorrect: Here's the explanation for the incorrect answer.

That is, every answer can contain a hint, and every question can contain a feedback element. What to do with this information is application dependent.

Adding meta-data

In addition, Ybe supports adding meta-data to your questions. A full example of all the available meta-data options is given below. Not all the options need to be used, one can leave one or more out if not needed. A full example:

questions:
- open:
    id: q5
    points: 1
    text: Example with meta data
    meta_data:
        general:
            description: Some description
            keywords: [alpha, beta]
            language: en
            creation_date: 2020-05-29
            authors:
                - John Doe
            module: Science
            chapters:
                - Some book, ed. 2, ch. 1
                - Some book, ed. 3, ch. 2
            skill_type: Knowledge
            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 can export these to QTI file and convert those 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 and the resources (images)
write_ybe_file(ybe_exam, './qti_to_ybe.ybe', copy_resources=True)

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:

• Free software: GPL v3 license

• Full documentation: https://ybe.readthedocs.io

• Project home: https://github.com/robbert-harms/ybe

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

Contributors

• Software by Dr. Harms

• Commissioned by Asst.Prof.Dr.Ir. S. Schoenmakers, Eindhoven University.