Merge branch 'MDL-43369-master' of git://github.com/jamiepratt/moodle
[moodle.git] / question / classes / statistics / questions / calculated.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  * Question statistics calculations 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  */
27 namespace core_question\statistics\questions;
28 defined('MOODLE_INTERNAL') || die();
30 /**
31  * This class is used to return the stats as calculated by {@link \core_question\statistics\questions\calculator}
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 calculated {
39     public $questionid;
41     // These first fields are the final fields cached in the db and shown in reports.
43     // See : http://docs.moodle.org/dev/Quiz_statistics_calculations#Position_statistics .
45     public $slot = null;
47     /**
48      * @var bool is this a sub question.
49      */
50     public $subquestion = false;
52     /**
53      * @var int total attempts at this question.
54      */
55     public $s = 0;
57     /**
58      * @var float effective weight of this question.
59      */
60     public $effectiveweight;
62     /**
63      * @var bool is covariance of this questions mark with other question marks negative?
64      */
65     public $negcovar;
67     /**
68      * @var float
69      */
70     public $discriminationindex;
72     /**
73      * @var float
74      */
75     public $discriminativeefficiency;
77     /**
78      * @var float standard deviation
79      */
80     public $sd;
82     /**
83      * @var float
84      */
85     public $facility;
87     /**
88      * @var float max mark achievable for this question.
89      */
90     public $maxmark;
92     /**
93      * @var string comma separated list of the positions in which this question appears.
94      */
95     public $positions;
97     /**
98      * @var null|float The average score that students would have got by guessing randomly. Or null if not calculable.
99      */
100     public $randomguessscore = null;
103     // End of fields in db.
105     protected $fieldsindb = array('questionid', 'slot', 'subquestion', 's', 'effectiveweight', 'negcovar', 'discriminationindex',
106         'discriminativeefficiency', 'sd', 'facility', 'subquestions', 'maxmark', 'positions', 'randomguessscore');
108     // Fields used for intermediate calculations.
110     public $totalmarks = 0;
112     public $totalothermarks = 0;
114     /**
115      * @var float The total of marks achieved for all positions in all attempts where this item was seen.
116      */
117     public $totalsummarks = 0;
119     public $markvariancesum = 0;
121     public $othermarkvariancesum = 0;
123     public $covariancesum = 0;
125     public $covariancemaxsum = 0;
127     public $subquestions = '';
129     public $covariancewithoverallmarksum = 0;
131     public $markarray = array();
133     public $othermarksarray = array();
135     public $markaverage;
137     public $othermarkaverage;
139     /**
140      * @var float The average for all attempts, of the sum of the marks for all positions in which this item appeared.
141      */
142     public $summarksaverage;
144     public $markvariance;
145     public $othermarkvariance;
146     public $covariance;
147     public $covariancemax;
148     public $covariancewithoverallmark;
150     /**
151      * @var object full question data
152      */
153     public $question;
155     /**
156      * Set if this record has been retrieved from cache. This is the time that the statistics were calculated.
157      *
158      * @var integer
159      */
160     public $timemodified;
162     /**
163      * Cache calculated stats stored in this object in 'question_statistics' table.
164      *
165      * @param \qubaid_condition $qubaids
166      */
167     public function cache($qubaids) {
168         global $DB;
169         $toinsert = new \stdClass();
170         $toinsert->hashcode = $qubaids->get_hash_code();
171         $toinsert->timemodified = time();
172         foreach ($this->fieldsindb as $field) {
173             $toinsert->{$field} = $this->{$field};
174         }
175         $DB->insert_record('question_statistics', $toinsert, false);
176     }
178     /**
179      * @param object $record Given a record from 'question_statistics' copy stats from record to properties.
180      */
181     public function populate_from_record($record) {
182         foreach ($this->fieldsindb as $field) {
183             $this->$field = $record->$field;
184         }
185         $this->timemodified = $record->timemodified;
186     }