Installation & Administration

This is a single Moodle plugin — installing local_quizanalytics is the whole install. Every section runs entirely in-process; there is no separate service to deploy, and nothing here ever talks to the public internet (see Privacy & Security).

For the exhaustive version of everything on this page — full rationale, every setting's own docblock reference, and a longer troubleshooting table — see INSTALL.md at the repo root. This page is the condensed walkthrough.

Prerequisites

• Admin access to the Moodle site, plus shell/SFTP access to the Moodle codebase (not just the web UI).
• Moodle 4.0+ (version.php's requires).
• mod_quiz (core) and qtype_stack installed — this plugin is a no-op without STACK questions to analyze.
• Moodle cron running on a real schedule. This is a hard requirement, not a performance nice-to-have: the cache-warming scheduled task and the on-demand background-compute safeguard for large courses both depend on php admin/cli/cron.php actually running. Without it, a large quiz/course's Analytics page shows "generating in the background" and never resolves. Confirm cron is running (Site administration → Server → Scheduled tasks should show recent "Last run" times) before relying on this plugin for anything beyond a small course.

1. Place the files

This repository's own root is the plugin — a plain "Download ZIP" of this repo can go straight into Moodle's plugin uploader.

• Easiest: Site administration → Plugins → Install plugins → upload a zip of this repository's contents.
• Shell/SFTP:

  cp -r . <moodleroot>/local/quizanalytics
  chown -R www-data:www-data <moodleroot>/local/quizanalytics

Either way, the folder must land at exactly <moodleroot>/local/quizanalytics — Moodle derives the component name from that path. Plotly.js, KaTeX, and TCPDF are already vendored inside the plugin; no separate download step is needed.

2. Run the Moodle upgrade

Log in as an admin and visit Site administration. This one step:

• Registers the local/quizanalytics:view capability.
• Registers the Quiz Analytics/Question Analytics caches.
• Registers Model 1 ("Student at risk in a STACK-based course") and Model 2 ("STACK question/PRT needs review") — both created disabled.
• Registers the "Warm STACK q-type Analytics result caches" scheduled task (every 15 minutes).

3. (Optional) Review performance settings

Site administration → Plugins → Local plugins → STACK q-type Analytics. Most of these auto-configure themselves against your actual server on first install/upgrade — review, don't feel you need to hand-tune them on a normal install:

4. Review and enable the Model Analytics models

Site administration → Analytics → Models. Both models appear here, disabled by default. Before enabling either:

• Review the thresholds on the same settings page as step 3: Question-needs-review pass-rate threshold (default 0.5), Bloated-tree "low traffic" floor (default 2), Help-seeking lookback window (default 3600 seconds).
• Read the proxy-label circularity caveat on Model 2 in How Everything Is Calculated before relying on its predictions.
• A model needs training data before it predicts anything — use Evaluate/Get predictions on the model's own page once enabled.
• If those actions are missing, Moodle's Restrict processing to CLI only analytics setting (onlycli) is on — predictions still happen automatically via cron either way.

5–7. Test it

1. Open a course with a STACK quiz that has a finished attempt. Find Analytics in the course's secondary navigation (check More if the bar is full).
2. You land on Quiz Analytics. Use the Section: switcher to reach Question Analytics and Model Analytics. Diagnostics Analytics isn't in that switcher yet — reach it directly at local/quizanalytics/diagnosticsanalytics.php?id=<courseid>.
3. Open a STACK quiz directly — its settings/administration menu should also have an Analytics entry, jumping straight to that quiz's Question Analytics.
4. Confirm a student account gets a standard permission-denied error on any of this plugin's pages — this plugin is teacher/manager-only by design (see Privacy & Security).
5. Once a model is enabled and has run at least once, check Site administration → Analytics → Insights for predictions.

How do I know it's working

1. Site administration → Server → Scheduled tasks: "Warm STACK q-type Analytics result caches" should show a recent Last run.
2. Site administration → Server → Tasks → Task logs: filter for local_quizanalytics, confirm runs complete (not fail).
3. This plugin's own settings page shows no cron-status warning banner, and "Detected server resources" shows real numbers.
4. On a course/quiz large enough to exceed the background-compute budget, you should see "generating in the background," not a timeout — and the real report a short while later on revisit.

Tested scale

Benchmarked against a real 38-quiz, 48,445-attempt production course, and a synthetic 50 quizzes × 1,000 students dataset. See Getting Started § Tested at and CHANGELOG.md for the specific numbers.

Troubleshooting quick-reference

Full table, with more rows: INSTALL.md.