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/>.
  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
  27 namespace 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  */
  34 class 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
 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();
 303         foreach ($this->for_slot($slot)->get_variants() as $variant) {
 304             $toreturn[] = $this->for_slot($slot, $variant);
 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      *
 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         }
 390
 391     }
 392
 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
 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 }