ybe 0.2.1

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, './')