[Summary view] [Print] [Text view]

   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   * This file contains the code to analyse all the responses to a particular
  19   * question.
  20   *
  21   * @package    core_question
  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\responses;
  28  defined('MOODLE_INTERNAL') || die();
  29  
  30  /**
  31   * Analysis for possible responses for parts of a question. It is up to a question type designer to decide on how many parts their
  32   * question has. See {@link \question_type::get_possible_responses()} and sub classes where the sub parts and response classes are
  33   * defined.
  34   *
  35   * A sub part might represent a sub question embedded in the question for example in a matching question there are
  36   * several sub parts. A numeric question with a unit might be divided into two sub parts for the purposes of response analysis
  37   * or the question type designer might decide to treat the answer, both the numeric and unit part,
  38   * as a whole for the purposes of response analysis.
  39   *
  40   * - There is a separate data structure for each question or sub question's analysis
  41   * {@link \core_question\statistics\responses\analysis_for_question}
  42   * or {@link \core_question\statistics\responses\analysis_for_question_all_tries}.
  43   * - There are separate analysis for each variant in this top level instance.
  44   * - Then there are class instances representing the analysis of each of the sub parts of each variant of the question.
  45   * {@link \core_question\statistics\responses\analysis_for_subpart}.
  46   * - Then within the sub part analysis there are response class analysis
  47   * {@link \core_question\statistics\responses\analysis_for_class}.
  48   * - Then within each class analysis there are analysis for each actual response
  49   * {@link \core_question\statistics\responses\analysis_for_actual_response}.
  50   *
  51   * @package    core_question
  52   * @copyright  2014 The Open University
  53   * @author     James Pratt me@jamiep.org
  54   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  55   */
  56  class analysis_for_question {
  57  
  58      /**
  59       * Constructor method.
  60       *
  61       * @param array[] Two index array, first index is unique string for each sub question part,
  62       *                    the second string index is the 'class' that sub-question part can be classified into.
  63       *                    Value in array is instance of {@link \question_possible_response}
  64       *                    This is the return value from {@link \question_type::get_possible_responses()}
  65       *                    see that method for fuller documentation.
  66       */
  67      public function __construct(array $possiblereponses = null) {
  68          if ($possiblereponses !== null) {
  69              $this->possibleresponses = $possiblereponses;
  70          }
  71      }
  72  
  73      /**
  74       * @var array[] See description above in constructor method.
  75       */
  76      protected $possibleresponses = array();
  77  
  78      /**
  79       * A multidimensional array whose first index is variant no and second index is subpart id, array contents are of type
  80       * {@link analysis_for_subpart}.
  81       *
  82       * @var array[]
  83       */
  84      protected $subparts = array();
  85  
  86      /**
  87       * Initialise data structure for response analysis of one variant.
  88       *
  89       * @param int $variantno
  90       */
  91      protected function initialise_stats_for_variant($variantno) {
  92          $this->subparts[$variantno] = array();
  93          foreach ($this->possibleresponses as $subpartid => $classes) {
  94              $this->subparts[$variantno][$subpartid] = new analysis_for_subpart($classes);
  95          }
  96      }
  97  
  98      /**
  99       * Variant nos found in this question's attempt data.
 100       *
 101       * @return int[]
 102       */
 103      public function get_variant_nos() {
 104          return array_keys($this->subparts);
 105      }
 106  
 107      /**
 108       * Unique ids for sub parts.
 109       *
 110       * @param int $variantno
 111       * @return string[]
 112       */
 113      public function get_subpart_ids($variantno) {
 114          return array_keys($this->subparts[$variantno]);
 115      }
 116  
 117      /**
 118       * Get the response counts etc. for variant $variantno, question sub part $subpartid.
 119       *
 120       * Or if there is no recorded analysis yet then initialise the data structure for that part of the analysis and return the
 121       * initialised analysis objects.
 122       *
 123       * @param int    $variantno
 124       * @param string $subpartid id for sub part.
 125       * @return analysis_for_subpart
 126       */
 127      public function get_analysis_for_subpart($variantno, $subpartid) {
 128          if (!isset($this->subparts[$variantno])) {
 129              $this->initialise_stats_for_variant($variantno);
 130          }
 131          return $this->subparts[$variantno][$subpartid];
 132      }
 133  
 134      /**
 135       * Used to work out what kind of table is needed to display stats.
 136       *
 137       * @return bool whether this question has (a subpart with) more than one response class.
 138       */
 139      public function has_multiple_response_classes() {
 140          foreach ($this->get_variant_nos() as $variantno) {
 141              foreach ($this->get_subpart_ids($variantno) as $subpartid) {
 142                  if ($this->get_analysis_for_subpart($variantno, $subpartid)->has_multiple_response_classes()) {
 143                      return true;
 144                  }
 145              }
 146          }
 147          return false;
 148      }
 149  
 150      /**
 151       * Used to work out what kind of table is needed to display stats.
 152       *
 153       * @return bool whether this analysis has more than one subpart.
 154       */
 155      public function has_subparts() {
 156          foreach ($this->get_variant_nos() as $variantno) {
 157              if (count($this->get_subpart_ids($variantno)) > 1) {
 158                  return true;
 159              }
 160          }
 161          return false;
 162      }
 163  
 164      /**
 165       * @return bool Does this response analysis include counts for responses for multiple tries of the question?
 166       */
 167      public function has_multiple_tries_data() {
 168          return false;
 169      }
 170  
 171      /**
 172       * What is the highest number of tries at this question?
 173       *
 174       * @return int always 1 as this class is for analysing only one try.
 175       */
 176      public function get_maximum_tries() {
 177          return 1;
 178      }
 179  
 180  
 181      /**
 182       * Takes an array of {@link \question_classified_response} and adds counts of the responses to the sub parts and classes.
 183       *
 184       * @param int                             $variantno
 185       * @param \question_classified_response[] $responseparts keys are sub-part id.
 186       */
 187      public function count_response_parts($variantno, $responseparts) {
 188          foreach ($responseparts as $subpartid => $responsepart) {
 189              $this->get_analysis_for_subpart($variantno, $subpartid)->count_response($responsepart);
 190          }
 191      }
 192  
 193      /**
 194       * @param \qubaid_condition $qubaids    which question usages have been analysed.
 195       * @param string            $whichtries which tries have been analysed?
 196       * @param int               $questionid which question.
 197       */
 198      public function cache($qubaids, $whichtries, $questionid) {
 199          foreach ($this->get_variant_nos() as $variantno) {
 200              foreach ($this->get_subpart_ids($variantno) as $subpartid) {
 201                  $analysisforsubpart = $this->get_analysis_for_subpart($variantno, $subpartid);
 202                  $analysisforsubpart->cache($qubaids, $whichtries, $questionid, $variantno, $subpartid);
 203              }
 204          }
 205      }
 206  
 207      /**
 208       * @return bool whether this analysis has a response class with more than one
 209       *      different actual response, or if the actual response is different from
 210       *      the model response.
 211       */
 212      public function has_actual_responses() {
 213          foreach ($this->get_variant_nos() as $variantno) {
 214              foreach ($this->get_subpart_ids($variantno) as $subpartid) {
 215                  if ($this->get_analysis_for_subpart($variantno, $subpartid)->has_actual_responses()) {
 216                      return true;
 217                  }
 218              }
 219          }
 220          return false;
 221      }
 222  
 223  }