MDL-41754 (2) quiz statistics : using Sam's new progress classes
[moodle.git] / question / classes / statistics / questions / calculator.php
CommitLineData
e68e4ccf
JP
1<?php
2// This file is part of Moodle - http://moodle.org/
3//
4// Moodle is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// Moodle is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
16
17/**
515b3ae6 18 * Question statistics calculator class. Used in the quiz statistics report but also available for use elsewhere.
e68e4ccf
JP
19 *
20 * @package core
21 * @subpackage questionbank
22 * @copyright 2013 Open University
23 * @author Jamie Pratt <me@jamiep.org>
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 */
26
515b3ae6 27namespace core_question\statistics\questions;
e68e4ccf
JP
28defined('MOODLE_INTERNAL') || die();
29
e68e4ccf
JP
30/**
31 * This class has methods to compute the question statistics from the raw data.
32 *
33 * @copyright 2013 Open University
34 * @author Jamie Pratt <me@jamiep.org>
35 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
36 */
515b3ae6 37class calculator {
e68e4ccf
JP
38
39 /**
515b3ae6 40 * @var calculated[]
e68e4ccf 41 */
515b3ae6 42 public $questionstats = array();
e68e4ccf
JP
43
44 /**
515b3ae6 45 * @var calculated_for_subquestion[]
e68e4ccf 46 */
515b3ae6 47 public $subquestionstats = array();
e68e4ccf
JP
48
49 /**
515b3ae6 50 * @var float
e68e4ccf 51 */
515b3ae6 52 protected $sumofmarkvariance = 0;
e68e4ccf 53
515b3ae6 54 protected $randomselectors = array();
e68e4ccf 55
8da6fc9d
JP
56 /**
57 * @var \progress_trace
58 */
59 protected $progress;
60
515b3ae6
JP
61 /**
62 * Constructor.
63 *
64 * @param object[] questions to analyze, keyed by slot, also analyses sub questions for random questions.
65 * we expect some extra fields - slot, maxmark and number on the full question data objects.
8da6fc9d 66 * @param \core\progress\base|null $progress the element to send progress messages to, default is {@link \core\progress\null}.
515b3ae6 67 */
8da6fc9d
JP
68 public function __construct($questions, $progress = null) {
69
70 if ($progress === null) {
71 $progress = new \core\progress\null();
72 }
73 $this->progress = $progress;
74
515b3ae6
JP
75 foreach ($questions as $slot => $question) {
76 $this->questionstats[$slot] = new calculated();
77 $this->questionstats[$slot]->questionid = $question->id;
78 $this->questionstats[$slot]->question = $question;
79 $this->questionstats[$slot]->slot = $slot;
80 $this->questionstats[$slot]->positions = $question->number;
81 $this->questionstats[$slot]->maxmark = $question->maxmark;
82 $this->questionstats[$slot]->randomguessscore = $this->get_random_guess_score($question);
e68e4ccf 83 }
e68e4ccf
JP
84 }
85
86 /**
515b3ae6
JP
87 * @param $qubaids \qubaid_condition
88 * @return array containing two arrays calculated[] and calculated_for_subquestion[].
e68e4ccf
JP
89 */
90 public function calculate($qubaids) {
8da6fc9d
JP
91
92 $this->progress->start_progress('', 6);
e68e4ccf 93
8e328617 94 list($lateststeps, $summarks) = $this->get_latest_steps($qubaids);
e68e4ccf
JP
95
96 if ($lateststeps) {
8da6fc9d 97 $this->progress->start_progress('', count($lateststeps), 1);
e68e4ccf
JP
98 // Compute the statistics of position, and for random questions, work
99 // out which questions appear in which positions.
8da6fc9d 100 $countdone = 1;
e68e4ccf 101 foreach ($lateststeps as $step) {
8da6fc9d
JP
102 $this->progress->progress($countdone);
103 $countdone++;
515b3ae6 104 $this->initial_steps_walker($step, $this->questionstats[$step->slot], $summarks);
e68e4ccf
JP
105
106 // If this is a random question what is the real item being used?
515b3ae6
JP
107 if ($step->questionid != $this->questionstats[$step->slot]->questionid) {
108 if (!isset($this->subquestionstats[$step->questionid])) {
109 $this->subquestionstats[$step->questionid] = new calculated_for_subquestion();
110 $this->subquestionstats[$step->questionid]->questionid = $step->questionid;
111 $this->subquestionstats[$step->questionid]->maxmark = $step->maxmark;
112 } else if ($this->subquestionstats[$step->questionid]->maxmark != $step->maxmark) {
113 $this->subquestionstats[$step->questionid]->differentweights = true;
e68e4ccf
JP
114 }
115
515b3ae6 116 $this->initial_steps_walker($step, $this->subquestionstats[$step->questionid], $summarks, false);
e68e4ccf 117
515b3ae6
JP
118 $number = $this->questionstats[$step->slot]->question->number;
119 $this->subquestionstats[$step->questionid]->usedin[$number] = $number;
e68e4ccf 120
515b3ae6
JP
121 $randomselectorstring = $this->questionstats[$step->slot]->question->category. '/'
122 .$this->questionstats[$step->slot]->question->questiontext;
e68e4ccf
JP
123 if (!isset($this->randomselectors[$randomselectorstring])) {
124 $this->randomselectors[$randomselectorstring] = array();
125 }
515b3ae6 126 $this->randomselectors[$randomselectorstring][$step->questionid] = $step->questionid;
e68e4ccf
JP
127 }
128 }
8da6fc9d 129 $this->progress->end_progress();
e68e4ccf
JP
130
131 foreach ($this->randomselectors as $key => $notused) {
132 ksort($this->randomselectors[$key]);
133 }
134
135 // Compute the statistics of question id, if we need any.
515b3ae6 136 $subquestions = question_load_questions(array_keys($this->subquestionstats));
8da6fc9d
JP
137 $this->progress->start_progress('', count($subquestions), 1);
138 $countdone = 1;
515b3ae6 139 foreach ($subquestions as $qid => $subquestion) {
8da6fc9d
JP
140 $this->progress->progress($countdone);
141 $countdone++;
515b3ae6
JP
142 $this->subquestionstats[$qid]->question = $subquestion;
143 $this->subquestionstats[$qid]->question->maxmark = $this->subquestionstats[$qid]->maxmark;
144 $this->subquestionstats[$qid]->randomguessscore = $this->get_random_guess_score($subquestion);
e68e4ccf 145
515b3ae6 146 $this->initial_question_walker($this->subquestionstats[$qid]);
e68e4ccf 147
515b3ae6 148 if ($this->subquestionstats[$qid]->differentweights) {
e68e4ccf
JP
149 // TODO output here really sucks, but throwing is too severe.
150 global $OUTPUT;
515b3ae6
JP
151 $name = $this->subquestionstats[$qid]->question->name;
152 echo $OUTPUT->notification( get_string('erroritemappearsmorethanoncewithdifferentweight',
153 'quiz_statistics', $name));
e68e4ccf
JP
154 }
155
515b3ae6
JP
156 if ($this->subquestionstats[$qid]->usedin) {
157 sort($this->subquestionstats[$qid]->usedin, SORT_NUMERIC);
158 $this->subquestionstats[$qid]->positions = implode(',', $this->subquestionstats[$qid]->usedin);
e68e4ccf 159 } else {
515b3ae6 160 $this->subquestionstats[$qid]->positions = '';
e68e4ccf
JP
161 }
162 }
8da6fc9d 163 $this->progress->end_progress();
e68e4ccf
JP
164
165 // Finish computing the averages, and put the subquestion data into the
166 // corresponding questions.
167
168 // This cannot be a foreach loop because we need to have both
169 // $question and $nextquestion available, but apart from that it is
170 // foreach ($this->questions as $qid => $question).
515b3ae6 171 reset($this->questionstats);
8da6fc9d
JP
172 $this->progress->start_progress('', count($this->questionstats), 1);
173 $countdone = 1;
515b3ae6 174 while (list($slot, $questionstat) = each($this->questionstats)) {
8da6fc9d
JP
175 $this->progress->progress($countdone);
176 $countdone++;
515b3ae6
JP
177 $nextquestionstats = current($this->questionstats);
178
179 $this->initial_question_walker($questionstat);
180
181 if ($questionstat->question->qtype == 'random') {
182 $randomselectorstring = $questionstat->question->category .'/'. $questionstat->question->questiontext;
183 if ($nextquestionstats && $nextquestionstats->question->qtype == 'random') {
184 $nextrandomselectorstring =
185 $nextquestionstats->question->category .'/'. $nextquestionstats->question->questiontext;
e68e4ccf
JP
186 if ($randomselectorstring == $nextrandomselectorstring) {
187 continue; // Next loop iteration.
188 }
189 }
190 if (isset($this->randomselectors[$randomselectorstring])) {
515b3ae6 191 $questionstat->subquestions = implode(',', $this->randomselectors[$randomselectorstring]);
e68e4ccf
JP
192 }
193 }
194 }
8da6fc9d 195 $this->progress->end_progress();
e68e4ccf
JP
196
197 // Go through the records one more time.
8da6fc9d
JP
198 $this->progress->start_progress('', count($lateststeps), 1);
199 $countdone = 1;
e68e4ccf 200 foreach ($lateststeps as $step) {
8da6fc9d
JP
201 $this->progress->progress($countdone);
202 $countdone++;
8e328617 203 $this->secondary_steps_walker($step, $this->questionstats[$step->slot], $summarks);
e68e4ccf 204
59abb707 205 if ($this->questionstats[$step->slot]->subquestions) {
8e328617 206 $this->secondary_steps_walker($step, $this->subquestionstats[$step->questionid], $summarks);
e68e4ccf
JP
207 }
208 }
8da6fc9d 209 $this->progress->end_progress();
e68e4ccf 210
8da6fc9d 211 $this->progress->start_progress('', count($this->questionstats), 1);
e68e4ccf 212 $sumofcovariancewithoverallmark = 0;
8da6fc9d 213 $countdone = 1;
515b3ae6 214 foreach ($this->questionstats as $questionstat) {
8da6fc9d
JP
215 $this->progress->progress($countdone);
216 $countdone++;
515b3ae6 217 $this->secondary_question_walker($questionstat);
e68e4ccf 218
515b3ae6 219 $this->sumofmarkvariance += $questionstat->markvariance;
e68e4ccf 220
515b3ae6
JP
221 if ($questionstat->covariancewithoverallmark >= 0) {
222 $sumofcovariancewithoverallmark += sqrt($questionstat->covariancewithoverallmark);
e68e4ccf
JP
223 }
224 }
8da6fc9d 225 $this->progress->end_progress();
e68e4ccf 226
8da6fc9d
JP
227 $this->progress->start_progress('', count($this->subquestionstats), 1);
228 $countdone = 1;
515b3ae6 229 foreach ($this->subquestionstats as $subquestionstat) {
8da6fc9d
JP
230 $this->progress->progress($countdone);
231 $countdone++;
515b3ae6 232 $this->secondary_question_walker($subquestionstat);
e68e4ccf 233 }
8da6fc9d 234 $this->progress->end_progress();
e68e4ccf 235
515b3ae6 236 foreach ($this->questionstats as $questionstat) {
e68e4ccf 237 if ($sumofcovariancewithoverallmark) {
515b3ae6
JP
238 if ($questionstat->negcovar) {
239 $questionstat->effectiveweight = null;
e68e4ccf 240 } else {
515b3ae6 241 $questionstat->effectiveweight = 100 * sqrt($questionstat->covariancewithoverallmark) /
e68e4ccf
JP
242 $sumofcovariancewithoverallmark;
243 }
244 } else {
515b3ae6 245 $questionstat->effectiveweight = null;
e68e4ccf
JP
246 }
247 }
248 $this->cache_stats($qubaids);
8da6fc9d
JP
249
250 // All finished.
251 $this->progress->end_progress();
e68e4ccf 252 }
515b3ae6 253 return array($this->questionstats, $this->subquestionstats);
e68e4ccf
JP
254 }
255
256 /**
515b3ae6
JP
257 * Load cached statistics from the database.
258 *
259 * @param $qubaids \qubaid_condition
260 * @return array containing two arrays calculated[] and calculated_for_subquestion[].
e68e4ccf 261 */
515b3ae6 262 public function get_cached($qubaids) {
e68e4ccf 263 global $DB;
515b3ae6 264 $timemodified = time() - self::TIME_TO_CACHE;
59abb707 265 $questionstatrecs = $DB->get_records_select('question_statistics', 'hashcode = ? AND timemodified > ?',
515b3ae6
JP
266 array($qubaids->get_hash_code(), $timemodified));
267
268 $questionids = array();
269 foreach ($questionstatrecs as $fromdb) {
270 if (!$fromdb->slot) {
271 $questionids[] = $fromdb->questionid;
272 }
e68e4ccf 273 }
515b3ae6
JP
274 $subquestions = question_load_questions($questionids);
275 foreach ($questionstatrecs as $fromdb) {
276 if ($fromdb->slot) {
277 $this->questionstats[$fromdb->slot]->populate_from_record($fromdb);
278 // Array created in constructor and populated from question.
279 } else {
280 $this->subquestionstats[$fromdb->questionid] = new calculated_for_subquestion();
281 $this->subquestionstats[$fromdb->questionid]->populate_from_record($fromdb);
282 $this->subquestionstats[$fromdb->questionid]->question = $subquestions[$fromdb->questionid];
283 }
284 }
285 return array($this->questionstats, $this->subquestionstats);
286 }
e68e4ccf 287
515b3ae6
JP
288 /**
289 * Find time of non-expired statistics in the database.
290 *
291 * @param $qubaids \qubaid_condition
292 * @return integer|boolean Time of cached record that matches this qubaid_condition or false is non found.
293 */
294 public function get_last_calculated_time($qubaids) {
295 global $DB;
296
297 $timemodified = time() - self::TIME_TO_CACHE;
e4b17111 298 return $DB->get_field_select('question_statistics', 'timemodified', 'hashcode = ? AND timemodified > ?',
487e7e66 299 array($qubaids->get_hash_code(), $timemodified), IGNORE_MULTIPLE);
515b3ae6
JP
300 }
301
302 /** @var integer Time after which statistics are automatically recomputed. */
303 const TIME_TO_CACHE = 900; // 15 minutes.
304
305 /**
306 * Used when computing Coefficient of Internal Consistency by quiz statistics.
307 *
308 * @return float
309 */
310 public function get_sum_of_mark_variance() {
311 return $this->sumofmarkvariance;
312 }
313
314 /**
315 * @param $qubaids \qubaid_condition
8e328617 316 * @return array with two items
515b3ae6
JP
317 * - $lateststeps array of latest step data for the question usages
318 * - $summarks array of total marks for each usage, indexed by usage id
515b3ae6
JP
319 */
320 protected function get_latest_steps($qubaids) {
321 $dm = new \question_engine_data_mapper();
322
323 $fields = " qas.id,
324 qa.questionusageid,
325 qa.questionid,
326 qa.slot,
327 qa.maxmark,
328 qas.fraction * qa.maxmark as mark";
329
330 $lateststeps = $dm->load_questions_usages_latest_steps($qubaids, array_keys($this->questionstats), $fields);
331 $summarks = array();
332 if ($lateststeps) {
333 foreach ($lateststeps as $step) {
334 if (!isset($summarks[$step->questionusageid])) {
335 $summarks[$step->questionusageid] = 0;
336 }
337 $summarks[$step->questionusageid] += $step->mark;
338 }
e68e4ccf
JP
339 }
340
8e328617 341 return array($lateststeps, $summarks);
e68e4ccf
JP
342 }
343
344 /**
345 * Update $stats->totalmarks, $stats->markarray, $stats->totalothermarks
346 * and $stats->othermarksarray to include another state.
347 *
515b3ae6
JP
348 * @param object $step the state to add to the statistics.
349 * @param calculated $stats the question statistics we are accumulating.
350 * @param array $summarks of the sum of marks for each question usage, indexed by question usage id
351 * @param bool $positionstat whether this is a statistic of position of question.
e68e4ccf
JP
352 */
353 protected function initial_steps_walker($step, $stats, $summarks, $positionstat = true) {
354 $stats->s++;
355 $stats->totalmarks += $step->mark;
356 $stats->markarray[] = $step->mark;
357
358 if ($positionstat) {
359 $stats->totalothermarks += $summarks[$step->questionusageid] - $step->mark;
360 $stats->othermarksarray[] = $summarks[$step->questionusageid] - $step->mark;
361
362 } else {
363 $stats->totalothermarks += $summarks[$step->questionusageid];
364 $stats->othermarksarray[] = $summarks[$step->questionusageid];
365 }
366 }
367
368 /**
369 * Perform some computations on the per-question statistics calculations after
370 * we have been through all the states.
371 *
515b3ae6 372 * @param calculated $stats question stats to update.
e68e4ccf
JP
373 */
374 protected function initial_question_walker($stats) {
375 $stats->markaverage = $stats->totalmarks / $stats->s;
376
377 if ($stats->maxmark != 0) {
378 $stats->facility = $stats->markaverage / $stats->maxmark;
379 } else {
380 $stats->facility = null;
381 }
382
383 $stats->othermarkaverage = $stats->totalothermarks / $stats->s;
384
8e328617
JP
385 $stats->summarksaverage = $stats->totalsummarks / $stats->s;
386
e68e4ccf
JP
387 sort($stats->markarray, SORT_NUMERIC);
388 sort($stats->othermarksarray, SORT_NUMERIC);
389 }
390
391 /**
392 * Now we know the averages, accumulate the date needed to compute the higher
393 * moments of the question scores.
394 *
515b3ae6
JP
395 * @param object $step the state to add to the statistics.
396 * @param calculated $stats the question statistics we are accumulating.
397 * @param array $summarks of the sum of marks for each question usage, indexed by question usage id
e68e4ccf 398 */
8e328617 399 protected function secondary_steps_walker($step, $stats, $summarks) {
e68e4ccf
JP
400 $markdifference = $step->mark - $stats->markaverage;
401 if ($stats->subquestion) {
402 $othermarkdifference = $summarks[$step->questionusageid] - $stats->othermarkaverage;
403 } else {
515b3ae6 404 $othermarkdifference = $summarks[$step->questionusageid] - $step->mark - $stats->othermarkaverage;
e68e4ccf 405 }
8e328617 406 $overallmarkdifference = $summarks[$step->questionusageid] - $stats->summarksaverage;
e68e4ccf
JP
407
408 $sortedmarkdifference = array_shift($stats->markarray) - $stats->markaverage;
515b3ae6 409 $sortedothermarkdifference = array_shift($stats->othermarksarray) - $stats->othermarkaverage;
e68e4ccf
JP
410
411 $stats->markvariancesum += pow($markdifference, 2);
412 $stats->othermarkvariancesum += pow($othermarkdifference, 2);
413 $stats->covariancesum += $markdifference * $othermarkdifference;
414 $stats->covariancemaxsum += $sortedmarkdifference * $sortedothermarkdifference;
415 $stats->covariancewithoverallmarksum += $markdifference * $overallmarkdifference;
416 }
417
418 /**
419 * Perform more per-question statistics calculations.
420 *
515b3ae6 421 * @param calculated $stats question stats to update.
e68e4ccf
JP
422 */
423 protected function secondary_question_walker($stats) {
515b3ae6 424
e68e4ccf
JP
425 if ($stats->s > 1) {
426 $stats->markvariance = $stats->markvariancesum / ($stats->s - 1);
427 $stats->othermarkvariance = $stats->othermarkvariancesum / ($stats->s - 1);
428 $stats->covariance = $stats->covariancesum / ($stats->s - 1);
429 $stats->covariancemax = $stats->covariancemaxsum / ($stats->s - 1);
430 $stats->covariancewithoverallmark = $stats->covariancewithoverallmarksum /
515b3ae6 431 ($stats->s - 1);
e68e4ccf
JP
432 $stats->sd = sqrt($stats->markvariancesum / ($stats->s - 1));
433
515b3ae6
JP
434 if ($stats->covariancewithoverallmark >= 0) {
435 $stats->negcovar = 0;
436 } else {
437 $stats->negcovar = 1;
438 }
e68e4ccf
JP
439 } else {
440 $stats->markvariance = null;
441 $stats->othermarkvariance = null;
442 $stats->covariance = null;
443 $stats->covariancemax = null;
444 $stats->covariancewithoverallmark = null;
445 $stats->sd = null;
515b3ae6 446 $stats->negcovar = 0;
e68e4ccf
JP
447 }
448
449 if ($stats->markvariance * $stats->othermarkvariance) {
450 $stats->discriminationindex = 100 * $stats->covariance /
515b3ae6 451 sqrt($stats->markvariance * $stats->othermarkvariance);
e68e4ccf
JP
452 } else {
453 $stats->discriminationindex = null;
454 }
455
456 if ($stats->covariancemax) {
457 $stats->discriminativeefficiency = 100 * $stats->covariance /
515b3ae6 458 $stats->covariancemax;
e68e4ccf
JP
459 } else {
460 $stats->discriminativeefficiency = null;
461 }
462 }
463
464 /**
465 * @param object $questiondata
466 * @return number the random guess score for this question.
467 */
468 protected function get_random_guess_score($questiondata) {
515b3ae6
JP
469 return \question_bank::get_qtype(
470 $questiondata->qtype, false)->get_random_guess_score($questiondata);
e68e4ccf
JP
471 }
472
473 /**
515b3ae6 474 * @param $qubaids \qubaid_condition
e68e4ccf 475 */
515b3ae6
JP
476 protected function cache_stats($qubaids) {
477 foreach ($this->questionstats as $questionstat) {
478 $questionstat->cache($qubaids);
e68e4ccf
JP
479 }
480
515b3ae6
JP
481 foreach ($this->subquestionstats as $subquestionstat) {
482 $subquestionstat->cache($qubaids);
e68e4ccf
JP
483 }
484 }
485
486}