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.
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.
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: trueThis 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.
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')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.
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 $$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.
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: 25If 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)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)In general:
- Storing exams in a plain-text
.ybefile - 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
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 ybeLinux
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 ybeFor 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
- Software by Dr. Harms
- Commissioned by Asst.Prof.Dr.Ir. S. Schoenmakers, Eindhoven University.