<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
namespace mod_quiz;
use coding_exception;
use core\di;
use core\hook;
use core_component;
use mod_quiz\event\quiz_grade_updated;
use mod_quiz\hook\structure_modified;
use mod_quiz\output\grades\grade_out_of;
use qubaid_condition;
use qubaid_list;
use question_engine_data_mapper;
use question_usage_by_activity;
use stdClass;
/**
* This class contains all the logic for computing the grade of a quiz.
*
* There are two sorts of calculation which need to be done. For a single
* attempt, we need to compute the total attempt score from score for each question.
* And for a quiz user, we need to compute the final grade from all the separate attempt grades.
*
* @package mod_quiz
* @copyright 2023 The Open University
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class grade_calculator {
/** @var float a number that is effectively zero. Used to avoid division-by-zero or underflow problems. */
const ALMOST_ZERO = 0.000005;
/** @var quiz_settings the quiz for which this instance computes grades. */
protected $quizobj;
/**
* @var stdClass[]|null quiz_grade_items for this quiz indexed by id, sorted by sortorder, with a maxmark field added.
*
* Lazy-loaded when needed. See {@see ensure_grade_items_loaded()}.
*/
protected ?array $gradeitems = null;
/**
* @var ?stdClass[]|null quiz_slot for this quiz. Only ->slot and ->quizgradeitemid fields are used.
*
* This is either set by another class that already has the data, using {@see set_slots()}
* or it is lazy-loaded when needed. See {@see ensure_slots_loaded()}.
*/
protected ?array $slots = null;
/**
* Constructor. Recommended way to get an instance is $quizobj->get_grade_calculator();
*
* @param quiz_settings $quizobj
*/
protected function __construct(quiz_settings $quizobj) {
$this->quizobj = $quizobj;
}
/**
* Factory. The recommended way to get an instance is $quizobj->get_grade_calculator();
*
* @param quiz_settings $quizobj settings of a quiz.
* @return grade_calculator instance of this class for the given quiz.
*/
public static function create(quiz_settings $quizobj): grade_calculator {
return new self($quizobj);
}
/**
* Update the sumgrades field of the quiz.
*
* This needs to be called whenever the grading structure of the quiz is changed.
* For example if a question is added or removed, or a question weight is changed.
*
* You should call {@see quiz_delete_previews()} before you call this function.
*/
public function recompute_quiz_sumgrades(): void {
global $DB;
$quiz = $this->quizobj->get_quiz();
// Update sumgrades in the database.
$DB->execute("
UPDATE {quiz}
SET sumgrades = COALESCE((
SELECT SUM(maxmark)
FROM {quiz_slots}
WHERE quizid = {quiz}.id
), 0)
WHERE id = ?
", [$quiz->id]);
// Update the value in memory.
$quiz->sumgrades = $DB->get_field('quiz', 'sumgrades', ['id' => $quiz->id]);
if ($quiz->sumgrades < self::ALMOST_ZERO && quiz_has_attempts($quiz->id)) {
// If the quiz has been attempted, and the sumgrades has been
// set to 0, then we must also set the maximum possible grade to 0, or
// we will get a divide by zero error.
self::update_quiz_maximum_grade(0);
}
// This class callback is deprecated, and will be removed in Moodle 4.8 (MDL-80327).
// Use the structure_modified hook instead.
$callbackclasses = core_component::get_plugin_list_with_class('quiz', 'quiz_structure_modified');
foreach ($callbackclasses as $callbackclass) {
component_class_callback($callbackclass, 'callback', [$quiz->id], null, true);
}
di::get(hook\manager::class)->dispatch(new structure_modified($this->quizobj->get_structure()));
}
/**
* Update the sumgrades field of attempts at this quiz.
*/
public function recompute_all_attempt_sumgrades(): void {
global $DB;
$dm = new question_engine_data_mapper();
$timenow = time();
$DB->execute("
UPDATE {quiz_attempts}
SET timemodified = :timenow,
sumgrades = (
{$dm->sum_usage_marks_subquery('uniqueid')}
)
WHERE quiz = :quizid AND state = :finishedstate
", [
'timenow' => $timenow,
'quizid' => $this->quizobj->get_quizid(),
'finishedstate' => quiz_attempt::FINISHED
]);
}
/**
* Update the final grade at this quiz for a particular student.
*
* That is, given the quiz settings, and all the attempts this user has made,
* compute their final grade for the quiz, as shown in the gradebook.
*
* The $attempts parameter is for efficiency. If you already have the data for
* all this user's attempts loaded (for example from {@see quiz_get_user_attempts()}
* or because you are looping through a large recordset fetched in one efficient query,
* then you can pass that data here to save DB queries.
*
* @param int|null $userid The userid to calculate the grade for. Defaults to the current user.
* @param array $attempts if you already have this user's attempt records loaded, pass them here to save queries.
*/
public function recompute_final_grade(?int $userid = null, array $attempts = []): void {
global $DB, $USER;
$quiz = $this->quizobj->get_quiz();
if (empty($userid)) {
$userid = $USER->id;
}
if (!$attempts) {
// Get all the attempts made by the user.
$attempts = quiz_get_user_attempts($quiz->id, $userid);
}
// Calculate the best grade.
$bestgrade = $this->compute_final_grade_from_attempts($attempts);
$bestgrade = quiz_rescale_grade($bestgrade, $quiz, false);
// Save the best grade in the database.
if (is_null($bestgrade)) {
$DB->delete_records('quiz_grades', ['quiz' => $quiz->id, 'userid' => $userid]);
} else if ($grade = $DB->get_record('quiz_grades',
['quiz' => $quiz->id, 'userid' => $userid])) {
$grade->grade = $bestgrade;
$grade->timemodified = time();
$DB->update_record('quiz_grades', $grade);
} else {
$grade = new stdClass();
$grade->quiz = $quiz->id;
$grade->userid = $userid;
$grade->grade = $bestgrade;
$grade->timemodified = time();
$DB->insert_record('quiz_grades', $grade);
}
quiz_update_grades($quiz, $userid);
}
/**
* Calculate the overall grade for a quiz given a number of attempts by a particular user.
*
* @param array $attempts an array of all the user's attempts at this quiz in order.
* @return float|null the overall grade, or null if the user does not have a grade.
*/
protected function compute_final_grade_from_attempts(array $attempts): ?float {
$grademethod = $this->quizobj->get_quiz()->grademethod;
switch ($grademethod) {
case QUIZ_ATTEMPTFIRST:
$firstattempt = reset($attempts);
return $firstattempt->sumgrades;
case QUIZ_ATTEMPTLAST:
$lastattempt = end($attempts);
return $lastattempt->sumgrades;
case QUIZ_GRADEAVERAGE:
$sum = 0;
$count = 0;
foreach ($attempts as $attempt) {
if (!is_null($attempt->sumgrades)) {
$sum += $attempt->sumgrades;
$count++;
}
}
if ($count == 0) {
return null;
}
return $sum / $count;
case QUIZ_GRADEHIGHEST:
$max = null;
foreach ($attempts as $attempt) {
if ($attempt->sumgrades > $max) {
$max = $attempt->sumgrades;
}
}
return $max;
default:
throw new coding_exception('Unrecognised grading method ' . $grademethod);
}
}
/**
* Update the final grade at this quiz for all students.
*
* This function is equivalent to calling {@see recompute_final_grade()} for all
* users who have attempted the quiz, but is much more efficient.
*/
public function recompute_all_final_grades(): void {
global $DB;
$quiz = $this->quizobj->get_quiz();
// If the quiz does not contain any graded questions, then there is nothing to do.
if (!$quiz->sumgrades) {
return;
}
$param = ['iquizid' => $quiz->id, 'istatefinished' => quiz_attempt::FINISHED];
$firstlastattemptjoin = "JOIN (
SELECT
iquiza.userid,
MIN(attempt) AS firstattempt,
MAX(attempt) AS lastattempt
FROM {quiz_attempts} iquiza
WHERE
iquiza.state = :istatefinished AND
iquiza.preview = 0 AND
iquiza.quiz = :iquizid
GROUP BY iquiza.userid
) first_last_attempts ON first_last_attempts.userid = quiza.userid";
switch ($quiz->grademethod) {
case QUIZ_ATTEMPTFIRST:
// Because of the where clause, there will only be one row, but we
// must still use an aggregate function.
$select = 'MAX(quiza.sumgrades)';
$join = $firstlastattemptjoin;
$where = 'quiza.attempt = first_last_attempts.firstattempt AND';
break;
case QUIZ_ATTEMPTLAST:
// Because of the where clause, there will only be one row, but we
// must still use an aggregate function.
$select = 'MAX(quiza.sumgrades)';
$join = $firstlastattemptjoin;
$where = 'quiza.attempt = first_last_attempts.lastattempt AND';
break;
case QUIZ_GRADEAVERAGE:
$select = 'AVG(quiza.sumgrades)';
$join = '';
$where = '';
break;
default:
case QUIZ_GRADEHIGHEST:
$select = 'MAX(quiza.sumgrades)';
$join = '';
$where = '';
break;
}
if ($quiz->sumgrades >= self::ALMOST_ZERO) {
$finalgrade = $select . ' * ' . ($quiz->grade / $quiz->sumgrades);
} else {
$finalgrade = '0';
}
$param['quizid'] = $quiz->id;
$param['quizid2'] = $quiz->id;
$param['quizid3'] = $quiz->id;
$param['quizid4'] = $quiz->id;
$param['statefinished'] = quiz_attempt::FINISHED;
$param['statefinished2'] = quiz_attempt::FINISHED;
$param['almostzero'] = self::ALMOST_ZERO;
$finalgradesubquery = "
SELECT quiza.userid, $finalgrade AS newgrade
FROM {quiz_attempts} quiza
$join
WHERE
$where
quiza.state = :statefinished AND
quiza.preview = 0 AND
quiza.quiz = :quizid3
GROUP BY quiza.userid";
$changedgrades = $DB->get_records_sql("
SELECT users.userid, qg.id, qg.grade, newgrades.newgrade
FROM (
SELECT userid
FROM {quiz_grades} qg
WHERE quiz = :quizid
UNION
SELECT DISTINCT userid
FROM {quiz_attempts} quiza2
WHERE
quiza2.state = :statefinished2 AND
quiza2.preview = 0 AND
quiza2.quiz = :quizid2
) users
LEFT JOIN {quiz_grades} qg ON qg.userid = users.userid AND qg.quiz = :quizid4
LEFT JOIN (
$finalgradesubquery
) newgrades ON newgrades.userid = users.userid
WHERE
ABS(newgrades.newgrade - qg.grade) > :almostzero OR
((newgrades.newgrade IS NULL OR qg.grade IS NULL) AND NOT
(newgrades.newgrade IS NULL AND qg.grade IS NULL))",
// The mess on the previous line is detecting where the value is
// NULL in one column, and NOT NULL in the other, but SQL does
// not have an XOR operator, and MS SQL server can't cope with
// (newgrades.newgrade IS NULL) <> (qg.grade IS NULL).
$param);
$timenow = time();
$todelete = [];
foreach ($changedgrades as $changedgrade) {
if (is_null($changedgrade->newgrade)) {
$todelete[] = $changedgrade->userid;
} else if (is_null($changedgrade->grade)) {
$toinsert = new stdClass();
$toinsert->quiz = $quiz->id;
$toinsert->userid = $changedgrade->userid;
$toinsert->timemodified = $timenow;
$toinsert->grade = $changedgrade->newgrade;
$DB->insert_record('quiz_grades', $toinsert);
} else {
$toupdate = new stdClass();
$toupdate->id = $changedgrade->id;
$toupdate->grade = $changedgrade->newgrade;
$toupdate->timemodified = $timenow;
$DB->update_record('quiz_grades', $toupdate);
}
}
if (!empty($todelete)) {
list($test, $params) = $DB->get_in_or_equal($todelete);
$DB->delete_records_select('quiz_grades', 'quiz = ? AND userid ' . $test,
array_merge([$quiz->id], $params));
}
}
/**
* Update the quiz setting for the grade the quiz is out of.
*
* This function will update the data in quiz_grades and quiz_feedback, and
* pass the new grades on to the gradebook.
*
* @param float $newgrade the new maximum grade for the quiz.
*/
public function update_quiz_maximum_grade(float $newgrade): void {
global $DB;
$quiz = $this->quizobj->get_quiz();
// This is potentially expensive, so only do it if necessary.
if (abs($quiz->grade - $newgrade) < self::ALMOST_ZERO) {
// Nothing to do.
return;
}
// Use a transaction.
$transaction = $DB->start_delegated_transaction();
// Update the quiz table.
$oldgrade = $quiz->grade;
$quiz->grade = $newgrade;
$timemodified = time();
$DB->update_record('quiz', (object) [
'id' => $quiz->id,
'grade' => $newgrade,
'timemodified' => $timemodified,
]);
// Rescale the grade of all quiz attempts.
if ($oldgrade < $newgrade) {
// The new total is bigger, so we need to recompute fully to avoid underflow problems.
$this->recompute_all_final_grades();
} else {
// New total smaller, so we can rescale the grades efficiently.
$DB->execute("
UPDATE {quiz_grades}
SET grade = ? * grade, timemodified = ?
WHERE quiz = ?
", [$newgrade / $oldgrade, $timemodified, $quiz->id]);
}
// Rescale the overall feedback boundaries.
if ($oldgrade > self::ALMOST_ZERO) {
// Update the quiz_feedback table.
$factor = $newgrade / $oldgrade;
$DB->execute("
UPDATE {quiz_feedback}
SET mingrade = ? * mingrade, maxgrade = ? * maxgrade
WHERE quizid = ?
", [$factor, $factor, $quiz->id]);
}
// Update grade item and send all grades to gradebook.
quiz_grade_item_update($quiz);
quiz_update_grades($quiz);
// Log quiz grade updated event.
quiz_grade_updated::create([
'context' => $this->quizobj->get_context(),
'objectid' => $quiz->id,
'other' => [
'oldgrade' => $oldgrade + 0, // Remove trailing 0s.
'newgrade' => $newgrade,
]
])->trigger();
$transaction->allow_commit();
}
/**
* Ensure the {@see grade_calculator::$gradeitems} field is ready to use.
*/
protected function ensure_grade_items_loaded(): void {
global $DB;
if ($this->gradeitems !== null) {
return; // Already done.
}
$this->gradeitems = $DB->get_records_sql("
SELECT gi.id,
gi.quizid,
gi.sortorder,
gi.name,
COALESCE(SUM(slot.maxmark), 0) AS maxmark
FROM {quiz_grade_items} gi
LEFT JOIN {quiz_slots} slot ON slot.quizgradeitemid = gi.id
WHERE gi.quizid = ? AND slot.quizid = ?
GROUP BY gi.id, gi.quizid, gi.sortorder, gi.name
ORDER BY gi.sortorder
", [$this->quizobj->get_quizid(), $this->quizobj->get_quizid()]);
}
/**
* Get the extra grade items for this quiz.
*
* Returned objects have fields ->id, ->quizid, ->sortorder, ->name and maxmark.
* @return stdClass[] the grade items for this quiz.
*/
public function get_grade_items(): array {
$this->ensure_grade_items_loaded();
return $this->gradeitems;
}
/**
* Lets other code pass in the slot information, so it does note have to be re-loaded from the DB.
*
* @param stdClass[] $slots the data from quiz_slots. The only required fields are ->slot and ->quizgradeitemid.
*/
public function set_slots(array $slots): void {
global $CFG;
$this->slots = $slots;
if ($CFG->debugdeveloper) {
foreach ($slots as $slot) {
if (!property_exists($slot, 'slot') || !property_exists($slot, 'quizgradeitemid')) {
debugging('Slot data passed to grade_calculator::set_slots ' .
'must have at least ->slot and ->quizgradeitemid set.', DEBUG_DEVELOPER);
break; // Only necessary to say this once.
}
}
}
}
/**
* Ensure the {@see $gradeitems} field is ready to use.
*/
protected function ensure_slots_loaded(): void {
global $DB;
if ($this->slots !== null) {
return; // Already done.
}
$this->slots = $DB->get_records('quiz_slots', ['quizid' => $this->quizobj->get_quizid()],
'slot', 'slot, id, quizgradeitemid');
}
/**
* Compute the grade and maximum for each item, for an attempt where the question_usage_by_activity is available.
*
* @param question_usage_by_activity $quba usage for the quiz attempt we want to calculate the grades of.
* @return grade_out_of[] the grade for each item where the total grade is not zero.
* ->name will be set to the grade item name. Must be output through {@see format_string()}.
*/
public function compute_grade_item_totals(question_usage_by_activity $quba): array {
$this->ensure_grade_items_loaded();
if (empty($this->gradeitems)) {
// No extra grade items.
return [];
}
$this->ensure_slots_loaded();
// Prepare a place to store the results for each grade-item.
$grades = [];
foreach ($this->gradeitems as $gradeitem) {
$grades[$gradeitem->id] = new grade_out_of(
$this->quizobj->get_quiz(), 0, $gradeitem->maxmark, name: $gradeitem->name);
}
// Add up the scores.
foreach ($this->slots as $slot) {
if (!$slot->quizgradeitemid) {
continue;
}
$grades[$slot->quizgradeitemid]->grade += $quba->get_question_mark($slot->slot);
}
// Remove any grade items where the total is 0.
foreach ($grades as $gradeitemid => $grade) {
if ($grade->maxgrade < self::ALMOST_ZERO) {
unset($grades[$gradeitemid]);
}
}
return $grades;
}
/**
* Compute the grade and maximum for each item, for some attempts where we only have the usage ids.
*
* @param int[] $qubaids array of usage ids.
* @return grade_out_of[][] question_usage.id => array of grade_out_of.
* ->name will be set to the grade item name. Must be output through {@see format_string()}..
*/
public function compute_grade_item_totals_for_attempts(array $qubaids): array {
$this->ensure_grade_items_loaded();
$grades = [];
foreach ($qubaids as $qubaid) {
$grades[$qubaid] = [];
}
if (empty($this->gradeitems || empty($qubaids))) {
// Nothing to do.
return $grades;
}
$gradesdata = $this->load_grade_item_totals(new qubaid_list($qubaids));
foreach ($qubaids as $qubaid) {
foreach ($this->gradeitems as $gradeitem) {
if ($gradeitem->maxmark < self::ALMOST_ZERO) {
continue;
}
$grades[$qubaid][$gradeitem->id] = new grade_out_of(
$this->quizobj->get_quiz(),
$gradesdata[$qubaid][$gradeitem->id] ?? 0,
$gradeitem->maxmark,
name: $gradeitem->name,
);
}
}
return $grades;
}
/**
* Query the database return the total mark for each grade item for a set of attempts.
*
* @param qubaid_condition $qubaids which question_usages to computer the total marks for.
* @return float[][] Array question_usage.id => quiz_grade_item.id => mark.
*/
public function load_grade_item_totals(qubaid_condition $qubaids): array {
global $DB;
$dm = new question_engine_data_mapper();
[$qalatestview, $viewparams] = $dm->question_attempt_latest_state_view('qalatest', $qubaids);
$totals = $DB->get_records_sql("
SELECT " . $DB->sql_concat('qalatest.questionusageid', "'#'", 'slot.quizgradeitemid') . " AS uniquefirstcolumn,
qalatest.questionusageid,
slot.quizgradeitemid,
SUM(qalatest.fraction * qalatest.maxmark) AS summarks
FROM $qalatestview
JOIN {quiz_slots} slot ON slot.slot = qalatest.slot
JOIN {quiz_grade_items} qgi ON qgi.id = slot.quizgradeitemid
GROUP BY qalatest.questionusageid, slot.quizgradeitemid
", $viewparams);
$marks = [];
foreach ($totals as $total) {
$marks[$total->questionusageid][$total->quizgradeitemid] = $total->summarks + 0; // Convert to float with + 0.
}
return $marks;
}
}