[Summary view]

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401]

   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   * Question statistics calculator class. Used in the quiz statistics report but also available for use elsewhere.
  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  
  27  namespace core_question\statistics\questions;
  28  defined('MOODLE_INTERNAL') || die();
  29  
  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   */
  37  class calculator {
  38  
  39      /**
  40       * @var all_calculated_for_qubaid_condition all the stats calculated for slots and sub-questions and variants of those
  41       *                                                  questions.
  42       */
  43      protected $stats;
  44  
  45      /**
  46       * @var float
  47       */
  48      protected $sumofmarkvariance = 0;
  49  
  50      /**
  51       * @var array[] keyed by a string representing the pool of questions that this random question draws from.
  52       *              string as returned from {@link \core_question\statistics\questions\calculated::random_selector_string}
  53       */
  54      protected $randomselectors = array();
  55  
  56      /**
  57       * @var \progress_trace
  58       */
  59      protected $progress;
  60  
  61      /**
  62       * @var string The class name of the class to instantiate to store statistics calculated.
  63       */
  64      protected $statscollectionclassname = '\core_question\statistics\questions\all_calculated_for_qubaid_condition';
  65  
  66      /**
  67       * Constructor.
  68       *
  69       * @param object[] questions to analyze, keyed by slot, also analyses sub questions for random questions.
  70       *                              we expect some extra fields - slot, maxmark and number on the full question data objects.
  71       * @param \core\progress\base|null $progress the element to send progress messages to, default is {@link \core\progress\none}.
  72       */
  73      public function __construct($questions, $progress = null) {
  74  
  75          if ($progress === null) {
  76              $progress = new \core\progress\none();
  77          }
  78          $this->progress = $progress;
  79          $this->stats = new $this->statscollectionclassname();
  80          foreach ($questions as $slot => $question) {
  81              $this->stats->initialise_for_slot($slot, $question);
  82              $this->stats->for_slot($slot)->randomguessscore = $this->get_random_guess_score($question);
  83          }
  84      }
  85  
  86      /**
  87       * Calculate the stats.
  88       *
  89       * @param \qubaid_condition $qubaids Which question usages to calculate the stats for?
  90       * @return all_calculated_for_qubaid_condition The calculated stats.
  91       */
  92      public function calculate($qubaids) {
  93  
  94          $this->progress->start_progress('', 6);
  95  
  96          list($lateststeps, $summarks) = $this->get_latest_steps($qubaids);
  97  
  98          if ($lateststeps) {
  99              $this->progress->start_progress('', count($lateststeps), 1);
 100              // Compute the statistics of position, and for random questions, work
 101              // out which questions appear in which positions.
 102              foreach ($lateststeps as $step) {
 103  
 104                  $this->progress->increment_progress();
 105  
 106                  $israndomquestion = ($step->questionid != $this->stats->for_slot($step->slot)->questionid);
 107                  $breakdownvariants = !$israndomquestion && $this->stats->for_slot($step->slot)->break_down_by_variant();
 108                  // If this is a variant we have not seen before create a place to store stats calculations for this variant.
 109                  if ($breakdownvariants && !$this->stats->has_slot($step->slot, $step->variant)) {
 110                      $question = $this->stats->for_slot($step->slot)->question;
 111                      $this->stats->initialise_for_slot($step->slot, $question, $step->variant);
 112                      $this->stats->for_slot($step->slot, $step->variant)->randomguessscore =
 113                                                                                      $this->get_random_guess_score($question);
 114                  }
 115  
 116                  // Step data walker for main question.
 117                  $this->initial_steps_walker($step, $this->stats->for_slot($step->slot), $summarks, true, $breakdownvariants);
 118  
 119                  // If this is a random question do the calculations for sub question stats.
 120                  if ($israndomquestion) {
 121                      if (!$this->stats->has_subq($step->questionid)) {
 122                          $this->stats->initialise_for_subq($step);
 123                      } else if ($this->stats->for_subq($step->questionid)->maxmark != $step->maxmark) {
 124                          $this->stats->for_subq($step->questionid)->differentweights = true;
 125                      }
 126  
 127                      // If this is a variant of this subq we have not seen before create a place to store stats calculations for it.
 128                      if (!$this->stats->has_subq($step->questionid, $step->variant)) {
 129                          $this->stats->initialise_for_subq($step, $step->variant);
 130                      }
 131  
 132                      $this->initial_steps_walker($step, $this->stats->for_subq($step->questionid), $summarks, false);
 133  
 134                      // Extra stuff we need to do in this loop for subqs to keep track of where they need to be displayed later.
 135  
 136                      $number = $this->stats->for_slot($step->slot)->question->number;
 137                      $this->stats->for_subq($step->questionid)->usedin[$number] = $number;
 138  
 139                      // Keep track of which random questions are actually selected from each pool of questions that random
 140                      // questions are pulled from.
 141                      $randomselectorstring = $this->stats->for_slot($step->slot)->random_selector_string();
 142                      if (!isset($this->randomselectors[$randomselectorstring])) {
 143                          $this->randomselectors[$randomselectorstring] = array();
 144                      }
 145                      $this->randomselectors[$randomselectorstring][$step->questionid] = $step->questionid;
 146                  }
 147              }
 148              $this->progress->end_progress();
 149  
 150              foreach ($this->randomselectors as $key => $notused) {
 151                  ksort($this->randomselectors[$key]);
 152                  $this->randomselectors[$key] = implode(',', $this->randomselectors[$key]);
 153              }
 154  
 155              $this->stats->subquestions = question_load_questions($this->stats->get_all_subq_ids());
 156              // Compute the statistics for sub questions, if there are any.
 157              $this->progress->start_progress('', count($this->stats->subquestions), 1);
 158              foreach ($this->stats->subquestions as $qid => $subquestion) {
 159                  $this->progress->increment_progress();
 160                  $subquestion->maxmark = $this->stats->for_subq($qid)->maxmark;
 161                  $this->stats->for_subq($qid)->question = $subquestion;
 162                  $this->stats->for_subq($qid)->randomguessscore = $this->get_random_guess_score($subquestion);
 163  
 164                  if ($variants = $this->stats->for_subq($qid)->get_variants()) {
 165                      foreach ($variants as $variant) {
 166                          $this->stats->for_subq($qid, $variant)->question = $subquestion;
 167                          $this->stats->for_subq($qid, $variant)->randomguessscore = $this->get_random_guess_score($subquestion);
 168                      }
 169                      $this->stats->for_subq($qid)->sort_variants();
 170                  }
 171                  $this->initial_question_walker($this->stats->for_subq($qid));
 172  
 173                  if ($this->stats->for_subq($qid)->usedin) {
 174                      sort($this->stats->for_subq($qid)->usedin, SORT_NUMERIC);
 175                      $this->stats->for_subq($qid)->positions = implode(',', $this->stats->for_subq($qid)->usedin);
 176                  } else {
 177                      $this->stats->for_subq($qid)->positions = '';
 178                  }
 179              }
 180              $this->progress->end_progress();
 181  
 182              // Finish computing the averages, and put the sub-question data into the
 183              // corresponding questions.
 184              $slots = $this->stats->get_all_slots();
 185              $totalnumberofslots = count($slots);
 186              $maxindex = $totalnumberofslots - 1;
 187              $this->progress->start_progress('', $totalnumberofslots, 1);
 188              foreach ($slots as $index => $slot) {
 189                  $this->stats->for_slot($slot)->sort_variants();
 190                  $this->progress->increment_progress();
 191                  $nextslotindex = $index + 1;
 192                  $nextslot = ($nextslotindex > $maxindex) ? false : $slots[$nextslotindex];
 193  
 194                  $this->initial_question_walker($this->stats->for_slot($slot));
 195  
 196                  // The rest of this loop is to finish working out where randomly selected question stats should be displayed.
 197                  if ($this->stats->for_slot($slot)->question->qtype == 'random') {
 198                      $randomselectorstring = $this->stats->for_slot($slot)->random_selector_string();
 199                      if ($nextslot &&  ($randomselectorstring == $this->stats->for_slot($nextslot)->random_selector_string())) {
 200                          continue; // Next loop iteration.
 201                      }
 202                      if (isset($this->randomselectors[$randomselectorstring])) {
 203                          $this->stats->for_slot($slot)->subquestions = $this->randomselectors[$randomselectorstring];
 204                      }
 205                  }
 206              }
 207              $this->progress->end_progress();
 208  
 209              // Go through the records one more time.
 210              $this->progress->start_progress('', count($lateststeps), 1);
 211              foreach ($lateststeps as $step) {
 212                  $this->progress->increment_progress();
 213                  $israndomquestion = ($this->stats->for_slot($step->slot)->question->qtype == 'random');
 214                  $this->secondary_steps_walker($step, $this->stats->for_slot($step->slot), $summarks);
 215  
 216                  if ($israndomquestion) {
 217                      $this->secondary_steps_walker($step, $this->stats->for_subq($step->questionid), $summarks);
 218                  }
 219              }
 220              $this->progress->end_progress();
 221  
 222              $slots = $this->stats->get_all_slots();
 223              $this->progress->start_progress('', count($slots), 1);
 224              $sumofcovariancewithoverallmark = 0;
 225              foreach ($this->stats->get_all_slots() as $slot) {
 226                  $this->progress->increment_progress();
 227                  $this->secondary_question_walker($this->stats->for_slot($slot));
 228  
 229                  $this->sumofmarkvariance += $this->stats->for_slot($slot)->markvariance;
 230  
 231                  $covariancewithoverallmark = $this->stats->for_slot($slot)->covariancewithoverallmark;
 232                  if (null !== $covariancewithoverallmark && $covariancewithoverallmark >= 0) {
 233                      $sumofcovariancewithoverallmark += sqrt($covariancewithoverallmark);
 234                  }
 235              }
 236              $this->progress->end_progress();
 237  
 238              $subqids = $this->stats->get_all_subq_ids();
 239              $this->progress->start_progress('', count($subqids), 1);
 240              foreach ($subqids as $subqid) {
 241                  $this->progress->increment_progress();
 242                  $this->secondary_question_walker($this->stats->for_subq($subqid));
 243              }
 244              $this->progress->end_progress();
 245  
 246              foreach ($this->stats->get_all_slots() as $slot) {
 247                  if ($sumofcovariancewithoverallmark) {
 248                      if ($this->stats->for_slot($slot)->negcovar) {
 249                          $this->stats->for_slot($slot)->effectiveweight = null;
 250                      } else {
 251                          $this->stats->for_slot($slot)->effectiveweight =
 252                                                          100 * sqrt($this->stats->for_slot($slot)->covariancewithoverallmark) /
 253                                                          $sumofcovariancewithoverallmark;
 254                      }
 255                  } else {
 256                      $this->stats->for_slot($slot)->effectiveweight = null;
 257                  }
 258              }
 259              $this->stats->cache($qubaids);
 260          }
 261          // All finished.
 262          $this->progress->end_progress();
 263          return $this->stats;
 264      }
 265  
 266      /**
 267       * Used when computing Coefficient of Internal Consistency by quiz statistics.
 268       *
 269       * @return float
 270       */
 271      public function get_sum_of_mark_variance() {
 272          return $this->sumofmarkvariance;
 273      }
 274  
 275      /**
 276       * Get the latest step data from the db, from which we will calculate stats.
 277       *
 278       * @param \qubaid_condition $qubaids Which question usages to get the latest steps for?
 279       * @return array with two items
 280       *              - $lateststeps array of latest step data for the question usages
 281       *              - $summarks    array of total marks for each usage, indexed by usage id
 282       */
 283      protected function get_latest_steps($qubaids) {
 284          $dm = new \question_engine_data_mapper();
 285  
 286          $fields = "    qas.id,
 287      qa.questionusageid,
 288      qa.questionid,
 289      qa.variant,
 290      qa.slot,
 291      qa.maxmark,
 292      qas.fraction * qa.maxmark as mark";
 293  
 294          $lateststeps = $dm->load_questions_usages_latest_steps($qubaids, $this->stats->get_all_slots(), $fields);
 295          $summarks = array();
 296          if ($lateststeps) {
 297              foreach ($lateststeps as $step) {
 298                  if (!isset($summarks[$step->questionusageid])) {
 299                      $summarks[$step->questionusageid] = 0;
 300                  }
 301                  $summarks[$step->questionusageid] += $step->mark;
 302              }
 303          }
 304  
 305          return array($lateststeps, $summarks);
 306      }
 307  
 308      /**
 309       * Calculating the stats is a four step process.
 310       *
 311       * We loop through all 'last step' data first.
 312       *
 313       * Update $stats->totalmarks, $stats->markarray, $stats->totalothermarks
 314       * and $stats->othermarksarray to include another state.
 315       *
 316       * @param object     $step         the state to add to the statistics.
 317       * @param calculated $stats        the question statistics we are accumulating.
 318       * @param array      $summarks     of the sum of marks for each question usage, indexed by question usage id
 319       * @param bool       $positionstat whether this is a statistic of position of question.
 320       * @param bool       $dovariantalso do we also want to do the same calculations for this variant?
 321       */
 322      protected function initial_steps_walker($step, $stats, $summarks, $positionstat = true, $dovariantalso = true) {
 323          $stats->s++;
 324          $stats->totalmarks += $step->mark;
 325          $stats->markarray[] = $step->mark;
 326  
 327          if ($positionstat) {
 328              $stats->totalothermarks += $summarks[$step->questionusageid] - $step->mark;
 329              $stats->othermarksarray[] = $summarks[$step->questionusageid] - $step->mark;
 330  
 331          } else {
 332              $stats->totalothermarks += $summarks[$step->questionusageid];
 333              $stats->othermarksarray[] = $summarks[$step->questionusageid];
 334          }
 335          if ($dovariantalso) {
 336              $this->initial_steps_walker($step, $stats->variantstats[$step->variant], $summarks, $positionstat, false);
 337          }
 338      }
 339  
 340      /**
 341       * Then loop through all questions for the first time.
 342       *
 343       * Perform some computations on the per-question statistics calculations after
 344       * we have been through all the step data.
 345       *
 346       * @param calculated $stats question stats to update.
 347       */
 348      protected function initial_question_walker($stats) {
 349          if ($stats->s != 0) {
 350              $stats->markaverage = $stats->totalmarks / $stats->s;
 351              $stats->othermarkaverage = $stats->totalothermarks / $stats->s;
 352              $stats->summarksaverage = $stats->totalsummarks / $stats->s;
 353          } else {
 354              $stats->markaverage = 0;
 355              $stats->othermarkaverage = 0;
 356              $stats->summarksaverage = 0;
 357          }
 358  
 359          if ($stats->maxmark != 0) {
 360              $stats->facility = $stats->markaverage / $stats->maxmark;
 361          } else {
 362              $stats->facility = null;
 363          }
 364  
 365          sort($stats->markarray, SORT_NUMERIC);
 366          sort($stats->othermarksarray, SORT_NUMERIC);
 367  
 368          // Here we have collected enough data to make the decision about which questions have variants whose stats we also want to
 369          // calculate. We delete the initialised structures where they are not needed.
 370          if (!$stats->get_variants() || !$stats->break_down_by_variant()) {
 371              $stats->clear_variants();
 372          }
 373  
 374          foreach ($stats->get_variants() as $variant) {
 375              $this->initial_question_walker($stats->variantstats[$variant]);
 376          }
 377      }
 378  
 379      /**
 380       * Loop through all last step data again.
 381       *
 382       * Now we know the averages, accumulate the date needed to compute the higher
 383       * moments of the question scores.
 384       *
 385       * @param object $step        the state to add to the statistics.
 386       * @param calculated $stats       the question statistics we are accumulating.
 387       * @param float[]  $summarks    of the sum of marks for each question usage, indexed by question usage id
 388       */
 389      protected function secondary_steps_walker($step, $stats, $summarks) {
 390          $markdifference = $step->mark - $stats->markaverage;
 391          if ($stats->subquestion) {
 392              $othermarkdifference = $summarks[$step->questionusageid] - $stats->othermarkaverage;
 393          } else {
 394              $othermarkdifference = $summarks[$step->questionusageid] - $step->mark - $stats->othermarkaverage;
 395          }
 396          $overallmarkdifference = $summarks[$step->questionusageid] - $stats->summarksaverage;
 397  
 398          $sortedmarkdifference = array_shift($stats->markarray) - $stats->markaverage;
 399          $sortedothermarkdifference = array_shift($stats->othermarksarray) - $stats->othermarkaverage;
 400  
 401          $stats->markvariancesum += pow($markdifference, 2);
 402          $stats->othermarkvariancesum += pow($othermarkdifference, 2);
 403          $stats->covariancesum += $markdifference * $othermarkdifference;
 404          $stats->covariancemaxsum += $sortedmarkdifference * $sortedothermarkdifference;
 405          $stats->covariancewithoverallmarksum += $markdifference * $overallmarkdifference;
 406  
 407          if (isset($stats->variantstats[$step->variant])) {
 408              $this->secondary_steps_walker($step, $stats->variantstats[$step->variant], $summarks);
 409          }
 410      }
 411  
 412      /**
 413       * And finally loop through all the questions again.
 414       *
 415       * Perform more per-question statistics calculations.
 416       *
 417       * @param calculated $stats question stats to update.
 418       */
 419      protected function secondary_question_walker($stats) {
 420          if ($stats->s > 1) {
 421              $stats->markvariance = $stats->markvariancesum / ($stats->s - 1);
 422              $stats->othermarkvariance = $stats->othermarkvariancesum / ($stats->s - 1);
 423              $stats->covariance = $stats->covariancesum / ($stats->s - 1);
 424              $stats->covariancemax = $stats->covariancemaxsum / ($stats->s - 1);
 425              $stats->covariancewithoverallmark = $stats->covariancewithoverallmarksum /
 426                  ($stats->s - 1);
 427              $stats->sd = sqrt($stats->markvariancesum / ($stats->s - 1));
 428  
 429              if ($stats->covariancewithoverallmark >= 0) {
 430                  $stats->negcovar = 0;
 431              } else {
 432                  $stats->negcovar = 1;
 433              }
 434          } else {
 435              $stats->markvariance = null;
 436              $stats->othermarkvariance = null;
 437              $stats->covariance = null;
 438              $stats->covariancemax = null;
 439              $stats->covariancewithoverallmark = null;
 440              $stats->sd = null;
 441              $stats->negcovar = 0;
 442          }
 443  
 444          if ($stats->markvariance * $stats->othermarkvariance) {
 445              $stats->discriminationindex = 100 * $stats->covariance /
 446                  sqrt($stats->markvariance * $stats->othermarkvariance);
 447          } else {
 448              $stats->discriminationindex = null;
 449          }
 450  
 451          if ($stats->covariancemax) {
 452              $stats->discriminativeefficiency = 100 * $stats->covariance /
 453                  $stats->covariancemax;
 454          } else {
 455              $stats->discriminativeefficiency = null;
 456          }
 457  
 458          foreach ($stats->variantstats as $variantstat) {
 459              $this->secondary_question_walker($variantstat);
 460          }
 461      }
 462  
 463      /**
 464       * Given the question data find the average grade that random guesses would get.
 465       *
 466       * @param object $questiondata the full question object.
 467       * @return float the random guess score for this question.
 468       */
 469      protected function get_random_guess_score($questiondata) {
 470          return \question_bank::get_qtype(
 471              $questiondata->qtype, false)->get_random_guess_score($questiondata);
 472      }
 473  
 474      /**
 475       * Find time of non-expired statistics in the database.
 476       *
 477       * @param \qubaid_condition $qubaids Which question usages to look for?
 478       * @return int|bool Time of cached record that matches this qubaid_condition or false is non found.
 479       */
 480      public function get_last_calculated_time($qubaids) {
 481          return $this->stats->get_last_calculated_time($qubaids);
 482      }
 483  
 484      /**
 485       * Load cached statistics from the database.
 486       *
 487       * @param \qubaid_condition $qubaids Which question usages to load the cached stats for?
 488       * @return all_calculated_for_qubaid_condition The cached stats.
 489       */
 490      public function get_cached($qubaids) {
 491          $this->stats->get_cached($qubaids);
 492          return $this->stats;
 493      }
 494  }