LabQuiz overview - LabQuiz suite documentation

labquiz is a Python package that allows you to seamlessly integrate interactive quizzes directly into Jupyter notebooks — useful for labs, tutorials, practical assignments, continuous assessment, and controlled exams.

It combines:

✅ Multiple-choice and numerical questions
🧩 Template-based parameterized questions
🔁 Configurable number of attempts
💡 Hints and detailed feedback
📊 Automatic scoring
🌐 Optional remote logging (Google Sheets)
📈 Real-time monitoring dashboard (if logging)
🔐 Integrity checks and anti-tampering mechanisms

And it comes with two optional companion tools:

✏️ quiz_editor — Create, edit, encrypt, and export question banks
📊 quiz_dash — Monitor, correct, and analyze results in real time

Together, these components make up the LabQuiz ecosystem, which is distributed as a bundle, labquizbundle.

Figure: Overview of the LabQuiz ecosystem. Dashed arrows indicate optional components. YAML quizzes drive both interactive notebooks and exports, monitored via a dashboard producing analytics, marks tables, and student reports.

👉🏼 Live version Try it in binder
Installation: All packages can be installed at once (labquiz, quiz_editor and quiz_dash)

# From PyPI
   pip install labquizbundle

or individually, e.g.

   pip install labquiz

They can also be installed from source e.g.

# From source
pip install git+https://github.com/jfbercher/labquiz.git#subdirectory=quiz_editor

with subdirectories meta (the bundle) , quiz_nb (for labquiz), quiz_editor and quiz_dash.

1.1🚀 Why LabQuiz?¶

LabQuiz is designed for active learning and controlled assessment in computational notebooks.

It helps instructors:

Increase student engagement with embedded exercises
Provide structured feedback during lab sessions
Monitor progress in real time
Run controlled tests and exams
Detect configuration tampering or integrity violations

It helps students:

Learn through interaction and immediate feedback
Track their progress
Work within structured assessment modes

1.2🚠 What LabQuiz Does¶

Inside your notebook, you can:

✅ Add multiple-choice questions (mcq)
🔢 Add numerical questions with tolerance (numeric)
🧩 Create parameterized template questions
🔁 Limit attempts
💡 Provide hints and corrections
📊 Compute automatic scores
🌐 Log all activity to a Google Sheet backend (optional)
🔐 Enable exam mode with integrity checks

Example:

from labquiz import QuizLab

quiz = QuizLab(URL, "my_quiz.yml", retries=2, exam_mode=False)
quiz.show("quiz1")

1.3📸 Examples¶

1.3.1Multiple-choice question (with hints & correction)¶

1.3.2Numerical question¶

1.3.3Template-based question (dynamic variables)¶

1.4🧩 Question Types, Pedagogical modes, Logging¶

1.4.1Question types¶

LabQuiz supports four types:

Type	Description
`mcq`	Standard multiple-choice
`numeric`	Numerical answers with tolerance
`mcq-template`	Context-dependent MCQ
`numeric-template`	Context-dependent numerical questions

Template questions allow dynamic evaluation based on runtime variables — ideal for practical lab computations.

Example:

quiz.show("quiz54", a=res1, b=res2)

Variables can also be generated dynamically

quiz.show("quiz54", autovars=True)

The expected solution is dynamically computed using Python expressions.

1.4.2Pedagogical modes¶

LabQuiz supports three pedagogical modes:

Learning mode (hints + correction available, score display)
Test mode (limited attempts, score display but no correction)
Exam mode (no feedback, secure logging)

Quizzes are defined in simple YAML format and support

Logical constraints (XOR, IMPLY, SAME, IMPLYFALSE)
Bonuses and penalties
Relative and absolute tolerances
Variable generation for templates

1.4.3📊 Remote Logging & Dashboard¶

All data can be stored in a Google Sheet backend.

LabQuiz can log: Validation events, Parameters, User answers, Integrity hashes... LabQuiz also includes multiple anti-cheating mechanisms (Machine fingerprinting, Source hash verification, Detection of parameter tampering, Optional encrypted question files, Runtime integrity daemon...)

1.5⚙️ Installation¶

1.5.1From PyPI¶

pip install labquiz

1.5.2From source¶

pip install git+https://github.com/jfbercher/labquiz.git

Import:

import labquiz
from labquiz import QuizLab

Instantiate:

quiz = QuizLab(URL, QUIZFILE,
               retries=2,
               needAuthentication=True,
               mandatoryInternet=False)

1.6🛠 Additional Tools¶

1.6.1✏️ `quiz_editor` — Build & Export Question Banks¶

Creating YAML files manually is possible — but quiz_editor is intended to make it easier. It can also be useful outside of LabQuiz as a general quiz-editor with export capabilities and large markdown support (including images, tables, equations, etc).

1.6.1.1Key features:¶

Visual question editing (MCQ, numeric, templates)
Categories & tags
Variable generation for templates
Bonus / malus configuration
Logical constraints (XOR, IMPLY, SAME, etc.)
One-click export to:
- ✅ YAML
- 🔐 Encrypted version
- 🌍 Interactive HTML (training mode), with dynamic support for regenerating variable values in template questions
- 📝 HTML exam version (Google Sheet connected)
- 📄 AMC–LaTeX format (paper exams), static and dynamic versions (using pythonTeX)

Online version: 👉 https://jfb-quizeditor.streamlit.app/

Install locally:

pip install quiz-editor

1.6.2📊 `quiz_dash` — Real-Time Monitoring & Correction¶

quiz_dash is the companion dashboard for instructors.

It connects to your Google Sheet backend and provides:

📈 Live tracking of submissions
Live class overview
👤 Student-by-student monitoring
🔍 Integrity checks (mode changes, retries tampering, hash verification)
⚖ Adjustable grading weights and scale
🔄 Automatic recalculation
📔 Full individual corrections available for download
📥 CSV export of results

Online version: 👉 https://jfb-quizdash.streamlit.app/

1.6.3🌍 Optional: Zero Installation with JupyterLite¶

LabQuiz can run entirely in the browser using JupyterLite (WASM). Perfect for fully web-based lab environments.

1.7📦 Ecosystem¶

Tool	Purpose
labquiz	Notebook quiz engine
quiz_editor	Question bank creation & export
quiz_dash	Monitoring & correction dashboard

📦 Repositories:

https://github.com/jfbercher/labquiz is a multipackage repository, that includes the bundle, and

Online tools:

1.8🎯 Typical Workflow¶

Prepare questions (YAML or quiz_editor)
Optionally encrypt file
Create Google Sheet backend
Instantiate QuizLab in notebook
Run lab / test / exam
Monitor using a python console or with quiz_dash
Post-correct with adjustable grading

1.9🏁 Demonstration¶

See:

labQuizDemo_en.ipynb in extras/
👉🏼 Live version 👈 Try it in binder

1.10📜 License¶

GPL-3.0 license

1 LabQuiz overview