MDL-41758 quiz statistics : link to full break down of stats for slots
[moodle.git] / question / classes / statistics / questions / all_calculated_for_qubaid_condition.php
CommitLineData
c3e2e754
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/**
18 * A collection of all the question statistics calculated for an activity instance ie. the stats calculated for slots and
19 * sub-questions and variants of those questions.
20 *
21 * @package core_question
22 * @copyright 2013 The Open University
23 * @author James Pratt me@jamiep.org
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 */
26
27namespace core_question\statistics\questions;
28
29/**
30 * A collection of all the question statistics calculated for an activity instance.
31 *
32 * @package core_question
33 */
34class all_calculated_for_qubaid_condition {
35
36 /**
37 * The limit of rows of sub-question and variants rows to display on main page of report before switching to showing min,
38 * median and max variants.
39 */
40 const SUBQ_AND_VARIANT_ROW_LIMIT = 10;
41
42 /**
43 * @var object[]
44 */
45 public $subquestions;
46
47 /**
48 * Holds slot (position) stats and stats for variants of questions in slots.
49 *
50 * @var calculated[]
51 */
52 public $questionstats = array();
53
54 /**
55 * Holds sub-question stats and stats for variants of subqs.
56 *
57 * @var calculated_for_subquestion[]
58 */
59 public $subquestionstats = array();
60
61 /**
62 * Set up a calculated_for_subquestion instance ready to store a randomly selected question's stats.
63 *
64 * @param object $step
65 * @param int|null $variant Is this to keep track of a variant's stats? If so what is the variant, if not null.
66 */
67 public function initialise_for_subq($step, $variant = null) {
68 $newsubqstat = new calculated_for_subquestion($step, $variant);
69 if ($variant === null) {
70 $this->subquestionstats[$step->questionid] = $newsubqstat;
71 } else {
72 $this->subquestionstats[$step->questionid]->variantstats[$variant] = $newsubqstat;
73 }
74 }
75
76 /**
77 * Set up a calculated instance ready to store a slot question's stats.
78 *
79 * @param int $slot
80 * @param object $question
81 * @param int|null $variant Is this to keep track of a variant's stats? If so what is the variant, if not null.
82 */
83 public function initialise_for_slot($slot, $question, $variant = null) {
84 $newqstat = new calculated($question, $slot, $variant);
85 if ($variant === null) {
86 $this->questionstats[$slot] = $newqstat;
87 } else {
88 $this->questionstats[$slot]->variantstats[$variant] = $newqstat;
89 }
90 }
91
92 /**
93 * Reference for a item stats instance for a questionid and optional variant no.
94 *
95 * @param $questionid
96 * @param int|null $variant if not null then we want the object to store a variant of a sub-question's stats.
97 * @return calculated_for_subquestion|null null if the stats object does not yet exist.
98 */
99 public function for_subq($questionid, $variant = null) {
100 if ($variant === null) {
101 if (!isset($this->subquestionstats[$questionid])) {
102 return null;
103 } else {
104 return $this->subquestionstats[$questionid];
105 }
106 } else {
107 if (!isset($this->subquestionstats[$questionid]->variantstats[$variant])) {
108 return null;
109 } else {
110 return $this->subquestionstats[$questionid]->variantstats[$variant];
111 }
112 }
113 }
114
115 /**
116 * ids of all randomly selected question for all slots.
117 *
118 * @return int[] An array of all sub-question ids.
119 */
120 public function get_all_subq_ids() {
121 return array_keys($this->subquestionstats);
122 }
123
124 /**
125 * All slots nos that stats have been calculated for.
126 *
127 * @return int[] An array of all slot nos.
128 */
129 public function get_all_slots() {
130 return array_keys($this->questionstats);
131 }
132
133 /**
134 * Array of variants of one randomly selected question that have appeared in the attempt data.
135 *
136 * @param $questionid
137 * @return int[]
138 */
139 public function get_variants_for_subq($questionid) {
140 if (count($this->subquestionstats[$questionid]->variantstats) > 1) {
141 return array_keys($this->subquestionstats[$questionid]->variantstats);
142 } else {
143 return false;
144 }
145 }
146
c3e2e754
JP
147 /**
148 * Reference to position stats instance for a slot and optional variant no.
149 *
150 * @param $slot
151 * @param null $variant if provided then we want the object which stores a variant of a position's stats.
152 * @return calculated|null
153 */
154 public function for_slot($slot, $variant = null) {
155 if ($variant === null) {
156 if (!isset($this->questionstats[$slot])) {
157 return null;
158 } else {
159 return $this->questionstats[$slot];
160 }
161 } else {
162 if (!isset($this->questionstats[$slot]->variantstats[$variant])) {
163 return null;
164 } else {
165 return $this->questionstats[$slot]->variantstats[$variant];
166 }
167 }
168 }
169
170 /**
171 * Load cached statistics from the database.
172 *
173 * @param $qubaids \qubaid_condition
174 */
175 public function get_cached($qubaids) {
176 global $DB;
177
178 $timemodified = time() - self::TIME_TO_CACHE;
179 $questionstatrecs = $DB->get_records_select('question_statistics', 'hashcode = ? AND timemodified > ?',
180 array($qubaids->get_hash_code(), $timemodified));
181
182 $questionids = array();
183 foreach ($questionstatrecs as $fromdb) {
184 if (is_null($fromdb->variant) && !$fromdb->slot) {
185 $questionids[] = $fromdb->questionid;
186 }
187 }
188 $this->subquestions = question_load_questions($questionids);
189 foreach ($questionstatrecs as $fromdb) {
190 if (is_null($fromdb->variant)) {
191 if ($fromdb->slot) {
192 $this->questionstats[$fromdb->slot]->populate_from_record($fromdb);
193 // Array created in constructor and populated from question.
194 } else {
195 $this->subquestionstats[$fromdb->questionid] = new calculated_for_subquestion();
196 $this->subquestionstats[$fromdb->questionid]->populate_from_record($fromdb);
197 $this->subquestionstats[$fromdb->questionid]->question = $this->subquestions[$fromdb->questionid];
198 }
199 }
200 }
201 // Add cached variant stats to data structure.
202 foreach ($questionstatrecs as $fromdb) {
203 if (!is_null($fromdb->variant)) {
204 if ($fromdb->slot) {
205 $newcalcinstance = new calculated();
206 $this->questionstats[$fromdb->slot]->variantstats[$fromdb->variant] = $newcalcinstance;
207 $newcalcinstance->question = $this->questionstats[$fromdb->slot]->question;
208 } else {
209 $newcalcinstance = new calculated_for_subquestion();
210 $this->subquestionstats[$fromdb->questionid]->variantstats[$fromdb->variant] = $newcalcinstance;
211 $newcalcinstance->question = $this->subquestions[$fromdb->questionid];
212 }
213 $newcalcinstance->populate_from_record($fromdb);
214 }
215 }
216 }
217
218 /**
219 * Find time of non-expired statistics in the database.
220 *
221 * @param $qubaids \qubaid_condition
222 * @return int|bool Time of cached record that matches this qubaid_condition or false is non found.
223 */
224 public function get_last_calculated_time($qubaids) {
225 global $DB;
226
227 $timemodified = time() - self::TIME_TO_CACHE;
228 return $DB->get_field_select('question_statistics', 'timemodified', 'hashcode = ? AND timemodified > ?',
229 array($qubaids->get_hash_code(), $timemodified), IGNORE_MULTIPLE);
230 }
231
232 /** @var integer Time after which statistics are automatically recomputed. */
233 const TIME_TO_CACHE = 900; // 15 minutes.
234
235 /**
236 * Save stats to db.
237 *
238 * @param $qubaids \qubaid_condition
239 */
240 public function cache($qubaids) {
241 foreach ($this->get_all_slots() as $slot) {
242 $this->for_slot($slot)->cache($qubaids);
243 }
244
245 foreach ($this->get_all_subq_ids() as $subqid) {
246 $this->for_subq($subqid)->cache($qubaids);
247 }
248 }
249
250 /**
251 * Return all sub-questions used.
252 *
253 * @return \object[] array of questions.
254 */
255 public function get_sub_questions() {
256 return $this->subquestions;
257 }
258
259 /**
260 * Are there too many rows of sub-questions and / or variant rows.
261 *
262 * @param array $rows the rows we intend to add.
263 * @return bool
264 */
265 protected function too_many_subq_and_or_variant_rows($rows) {
266 return (count($rows) > static::SUBQ_AND_VARIANT_ROW_LIMIT);
267 }
268
269 /**
270 * From a number of calculated instances find the three instances with min, median and maximum facility index values.
271 *
272 * @param calculated[] $questionstats
273 * @return calculated[] 3 stat objects with minimum, median and maximum facility index.
274 */
275 protected function find_min_median_and_max_facility_stats_objects($questionstats) {
276 $facilities = array();
277 foreach ($questionstats as $key => $questionstat) {
278 $facilities[$key] = (float)$questionstat->facility;
279 }
280 asort($facilities);
281 $facilitykeys = array_keys($facilities);
282 $keyformin = $facilitykeys[0];
283 $keyformedian = $facilitykeys[(int)(round(count($facilitykeys) / 2)-1)];
284 $keyformax = $facilitykeys[count($facilitykeys) - 1];
285 $toreturn = array();
286 foreach (array($keyformin => 'minimumfacility',
287 $keyformedian => 'medianfacility',
288 $keyformax => 'maximumfacility') as $key => $stringid) {
289 $questionstats[$key]->minmedianmaxnotice = $stringid;
290 $toreturn[] = $questionstats[$key];
291 }
292 return $toreturn;
293 }
294
295 /**
296 * Return all stats for variants of question in slot $slot.
297 *
298 * @param int $slot
299 * @return calculated[]
300 */
301 protected function all_variant_stats_for_one_slot($slot) {
302 $toreturn = array();
51e3ded8
JP
303 foreach ($this->for_slot($slot)->get_variants() as $variant) {
304 $toreturn[] = $this->for_slot($slot, $variant);
c3e2e754
JP
305 }
306 return $toreturn;
307 }
308
309 /**
310 * Return all stats for variants of randomly selected questions for one slot $slot.
311 *
312 * @param int $slot
313 * @return calculated[]
314 */
315 protected function all_subq_variants_for_one_slot($slot) {
316 $toreturn = array();
317 $displayorder = 1;
318 foreach ($this->for_slot($slot)->get_sub_question_ids() as $subqid) {
319 if ($variants = $this->get_variants_for_subq($subqid)) {
320 foreach ($variants as $variant) {
321 $toreturn[] = $this->make_new_subq_stat_for($displayorder, $slot, $subqid, $variant);
322 }
323 }
324 $displayorder++;
325 }
326 return $toreturn;
327 }
328
329 /**
330 * Return all stats for randomly selected questions for one slot $slot.
331 *
332 * @param int $slot
333 * @return calculated[]
334 */
335 protected function all_subqs_for_one_slot($slot) {
336 $displayorder = 1;
337 $toreturn = array();
338 foreach ($this->for_slot($slot)->get_sub_question_ids() as $subqid) {
339 $toreturn[] = $this->make_new_subq_stat_for($displayorder, $slot, $subqid);
340 $displayorder++;
341 }
342 return $toreturn;
343 }
344
345 /**
346 * Return all variant or 'sub-question' stats one slot, either :
347 * - variants of question
348 * - variants of randomly selected questions
349 * - randomly selected questions
350 *
51e3ded8
JP
351 * @param int $slot the slot no
352 * @param bool $limited limit number of variants and sub-questions displayed?
353 * @return calculated|calculated_for_subquestion[] stats to display
c3e2e754 354 */
51e3ded8 355 protected function all_subq_and_variant_stats_for_slot($slot, $limited) {
c3e2e754
JP
356 // Random question in this slot?
357 if ($this->for_slot($slot)->get_sub_question_ids()) {
358 if ($limited) {
359 $subqvariantstats = $this->all_subq_variants_for_one_slot($slot);
360 if ($this->too_many_subq_and_or_variant_rows($subqvariantstats)) {
361 // Too many variants from randomly selected questions.
362 return $this->find_min_median_and_max_facility_stats_objects($subqvariantstats);
363 }
364 $subqstats = $this->all_subqs_for_one_slot($slot);
365 if ($this->too_many_subq_and_or_variant_rows($subqstats)) {
366 // Too many randomly selected questions.
367 return $this->find_min_median_and_max_facility_stats_objects($subqstats);
368 }
369 }
370 $toreturn = array();
371 $displaynumber = 1;
372 foreach ($this->for_slot($slot)->get_sub_question_ids() as $subqid) {
373 $toreturn[] = $this->make_new_subq_stat_for($displaynumber, $slot, $subqid);
374 if ($variants = $this->get_variants_for_subq($subqid)) {
375 foreach ($variants as $variant) {
376 $toreturn[] = $this->make_new_subq_stat_for($displaynumber, $slot, $subqid, $variant);
377 }
378 }
379 $displaynumber++;
380 }
381 return $toreturn;
382 } else {
383 $variantstats = $this->all_variant_stats_for_one_slot($slot);
384 if ($limited && $this->too_many_subq_and_or_variant_rows($variantstats)) {
385 return $this->find_min_median_and_max_facility_stats_objects($variantstats);
386 } else {
387 return $variantstats;
388 }
389 }
390
391 }
392
51e3ded8
JP
393 /**
394 * Return all stats for one slot, stats for the slot itself, and either :
395 * - variants of question
396 * - variants of randomly selected questions
397 * - randomly selected questions
398 *
399 * @param int $slot the slot no
400 * @param int $limitvariants limit number of variants and sub-questions displayed?
401 * @return calculated|calculated_for_subquestion[] stats to display
402 */
403 public function structure_analysis_for_one_slot($slot, $limitvariants = false) {
404 return array_merge(array($this->for_slot($slot)),
405 $this->all_subq_and_variant_stats_for_slot($slot, $limitvariants));
406 }
407
c3e2e754
JP
408 /**
409 * We need a new object for display. Sub-question stats can appear more than once in different slots.
410 * So we create a clone of the object and then we can set properties on the object that are per slot.
411 *
412 * @param $displaynumber
413 * @param $slot
414 * @param $subqid
415 * @param null $variant
416 * @return calculated_for_subquestion|null
417 */
418 protected function make_new_subq_stat_for($displaynumber, $slot, $subqid, $variant = null) {
419 $slotstat = fullclone($this->for_subq($subqid, $variant));
420 $slotstat->question->number = $this->for_slot($slot)->question->number;
421 $slotstat->subqdisplayorder = $displaynumber;
422 return $slotstat;
423 }
424
425 /**
426 * Call after calculations to output any error messages.
427 *
428 * @return string[] Array of strings describing error messages found during stats calculation.
429 */
430 public function any_error_messages() {
431 $errors = array();
432 foreach ($this->get_all_slots() as $slot) {
433 foreach ($this->for_slot($slot)->get_sub_question_ids() as $subqid) {
434 if ($this->for_subq($subqid)->differentweights) {
435 $name = $this->for_subq($subqid)->question->name;
436 $errors[] = get_string('erroritemappearsmorethanoncewithdifferentweight', 'quiz_statistics', $name);
437 }
438 }
439 }
440 return $errors;
441
442 }
443
444}