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
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/>.
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  */
27 namespace core_question\statistics\questions;
29 /**
30  * A collection of all the question statistics calculated for an activity instance.
31  *
32  * @package core_question
33  */
34 class all_calculated_for_qubaid_condition {
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;
42     /**
43      * @var object[]
44      */
45     public $subquestions;
47     /**
48      * Holds slot (position) stats and stats for variants of questions in slots.
49      *
50      * @var calculated[]
51      */
52     public $questionstats = array();
54     /**
55      * Holds sub-question stats and stats for variants of subqs.
56      *
57      * @var calculated_for_subquestion[]
58      */
59     public $subquestionstats = array();
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     }
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     }
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     }
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     }
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     }
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     }
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     }
170     /**
171      * Load cached statistics from the database.
172      *
173      * @param $qubaids \qubaid_condition
174      */
175     public function get_cached($qubaids) {
176         global $DB;
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));
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     }
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;
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     }
232     /** @var integer Time after which statistics are automatically recomputed. */
233     const TIME_TO_CACHE = 900; // 15 minutes.
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         }
245         foreach ($this->get_all_subq_ids() as $subqid) {
246             $this->for_subq($subqid)->cache($qubaids);
247         }
248     }
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     }
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     }
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     }
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();
303         foreach ($this->for_slot($slot)->get_variants() as $variant) {
304             $toreturn[] = $this->for_slot($slot, $variant);
305         }
306         return $toreturn;
307     }
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     }
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     }
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      *
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
354      */
355     protected function all_subq_and_variant_stats_for_slot($slot, $limited) {
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         }
391     }
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     }
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     }
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;
442     }