Getting started

QGen is available through PyPi. So first let's get that with

pip install qgen 

Next, lets think about the types of question we'd like to generate some instances of. Let's start with something simple just to demonstrate how to use QGen. Imagine you're teaching an elementary math class with about 20 students and for their homework you'd like to test how well your students can add two numbers. The question might look like this

What is 11 + 13?

Well, say you wanted to give each student 10 questions. You're a teacher at a modern day school so this institution uses some online learning platform that can help out a bit. Let's take for example Moodle. Ideally you would want each student to see a different set of pairs of numbers so at a higher level the question looks like this

What is {some number} + {some number}?

Okay, so now we have somewhat of an idea of how we'd make our template.

A template for QGen is just a YAML file, so let's start by creating that file and name it say test.yml. First tag will be to name the question, let's call it SimpleAddition and the answer is going to be a number so let's set the type to numerical and let's also give it a reasonable title as well. So the file looks like this now

SimpleAddition:
  title:'Simple addition question ' 
  type:'numerical' 

We also know what we want in the body of the question do let's put that in

SimpleAddition:
  title:'Simple addition question ' 
  type:'numerical'
  body: >
          What is {some number} + {some number}

Braces are used in qgen to replace parameters with values, only thing is no spaces are allowed so let's fix that a bit

SimpleAddition:
  title:'Simple addition question ' 
  type:'numerical'
  body: >
          What is {num1} + {num2}?

Now we need to define how to replace {num1} and {num2} on each instance of the question. qgen does that by using a params tag, under params you would name the parameter and specify what generator is to be used.

SimpleAddition:
  title:'Simple addition question ' 
  type:'numerical'
  body: >
         What is {num1} + {num2}?
  params:
    num1:
      randint:
        start: 1
        end:100
    num2:
      randint:
        start: 1
        end:100

In this case the generator used is randint, randint is a built in generator in qgen that generates a random integer within a given range which is defined through named parameters start and end (inclusive).

Now, let's talk about what the answer for each instance of the question should look. As you can imagine answers are defined under the answer tag. So, we need to ensure that the answer is always the sum of whatever replaces {num1} and {num2}. qgen provides a way to evaluate code using Python syntax, we chose Python because it's simple and intuitive syntax seemed best for the task.

In qgen any text within $ tags are evaluated as Python code. So we need to evaluate the sum of {num1} and {num2} in Python, simply its just {num1} + {num2} but to have it evaluated we enclose as follows ${num1} + {num2}$. So now we add this to the file

SimpleAddition:
  title:'Simple addition question ' 
  type:'numerical'
  body: >
         What is {num1} + {num2}?
  params:
    num1:
      randint:
        start: 1
        end:100
    num2:
      randint:
        start: 1
        end:100
  answer:
    -'${num1} + {num2}$'

We now have a complete file that can be used to generate a large number of questions. Now save this file and let's get back to Python

Open up a python console and then import qgen and use as follows:

import qgen
qgen.build_moodle_xml('/path/to/file/test.yml', number_of_questions=50)

The first parameter is the path to where qgen can find your yaml file and the other named paremeter is used to tell qgen how many questions it should attempt to generate.

After executing the above commands the xml version for your questions should have been returned, but also in the same folder as the yaml file a folder named generated_quizzes has been made. It will contain the resulting file and you can go ahead and upload this file to your Moodle instance and voila! you'd have just added 50 questions to your question bank!