Merge branch 'MDL-68749-310-2' of git://github.com/mickhawkins/moodle into MOODLE_310...
[moodle.git] / question / type / numerical / question.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  * Numerical question definition class.
19  *
20  * @package    qtype
21  * @subpackage numerical
22  * @copyright  2009 The Open University
23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  */
27 defined('MOODLE_INTERNAL') || die();
29 require_once($CFG->dirroot . '/question/type/questionbase.php');
31 /**
32  * Represents a numerical question.
33  *
34  * @copyright  2009 The Open University
35  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
36  */
37 class qtype_numerical_question extends question_graded_automatically {
38     /** @var array of question_answer. */
39     public $answers = array();
41     /** @var int one of the constants UNITNONE, UNITRADIO, UNITSELECT or UNITINPUT. */
42     public $unitdisplay;
43     /** @var int one of the constants UNITGRADEDOUTOFMARK or UNITGRADEDOUTOFMAX. */
44     public $unitgradingtype;
45     /** @var number the penalty for a missing or unrecognised unit. */
46     public $unitpenalty;
48     /** @var qtype_numerical_answer_processor */
49     public $ap;
51     public function get_expected_data() {
52         $expected = array('answer' => PARAM_RAW_TRIMMED);
53         if ($this->has_separate_unit_field()) {
54             $expected['unit'] = PARAM_RAW_TRIMMED;
55         }
56         return $expected;
57     }
59     public function has_separate_unit_field() {
60         return $this->unitdisplay == qtype_numerical::UNITRADIO ||
61                 $this->unitdisplay == qtype_numerical::UNITSELECT;
62     }
64     public function start_attempt(question_attempt_step $step, $variant) {
65         $step->set_qt_var('_separators',
66                 $this->ap->get_point() . '$' . $this->ap->get_separator());
67     }
69     public function apply_attempt_state(question_attempt_step $step) {
70         list($point, $separator) = explode('$', $step->get_qt_var('_separators'));
71                 $this->ap->set_characters($point, $separator);
72     }
74     public function summarise_response(array $response) {
75         if (isset($response['answer'])) {
76             $resp = $response['answer'];
77         } else {
78             $resp = null;
79         }
81         if ($this->has_separate_unit_field() && !empty($response['unit'])) {
82             $resp = $this->ap->add_unit($resp, $response['unit']);
83         }
85         return $resp;
86     }
88     public function un_summarise_response(string $summary) {
89         if ($this->has_separate_unit_field()) {
90             throw new coding_exception('Sorry, but at the moment un_summarise_response cannot handle the
91                 has_separate_unit_field case for numerical questions.
92                     If you need this, you will have to implement it yourself.');
93         }
95         if (!empty($summary)) {
96             return ['answer' => $summary];
97         } else {
98             return [];
99         }
100     }
102     public function is_gradable_response(array $response) {
103         return array_key_exists('answer', $response) &&
104                 ($response['answer'] || $response['answer'] === '0' || $response['answer'] === 0);
105     }
107     public function is_complete_response(array $response) {
108         if (!$this->is_gradable_response($response)) {
109             return false;
110         }
112         list($value, $unit) = $this->ap->apply_units($response['answer']);
113         if (is_null($value)) {
114             return false;
115         }
117         if ($this->unitdisplay != qtype_numerical::UNITINPUT && $unit) {
118             return false;
119         }
121         if ($this->has_separate_unit_field() && empty($response['unit'])) {
122             return false;
123         }
125         if ($this->ap->contains_thousands_seaparator($response['answer'])) {
126             return false;
127         }
129         return true;
130     }
132     public function get_validation_error(array $response) {
133         if (!$this->is_gradable_response($response)) {
134             return get_string('pleaseenterananswer', 'qtype_numerical');
135         }
137         list($value, $unit) = $this->ap->apply_units($response['answer']);
138         if (is_null($value)) {
139             return get_string('invalidnumber', 'qtype_numerical');
140         }
142         if ($this->unitdisplay != qtype_numerical::UNITINPUT && $unit) {
143             return get_string('invalidnumbernounit', 'qtype_numerical');
144         }
146         if ($this->has_separate_unit_field() && empty($response['unit'])) {
147             return get_string('unitnotselected', 'qtype_numerical');
148         }
150         if ($this->ap->contains_thousands_seaparator($response['answer'])) {
151             return get_string('pleaseenteranswerwithoutthousandssep', 'qtype_numerical',
152                     $this->ap->get_separator());
153         }
155         return '';
156     }
158     public function is_same_response(array $prevresponse, array $newresponse) {
159         if (!question_utils::arrays_same_at_key_missing_is_blank(
160                 $prevresponse, $newresponse, 'answer')) {
161             return false;
162         }
164         if ($this->has_separate_unit_field()) {
165             return question_utils::arrays_same_at_key_missing_is_blank(
166                 $prevresponse, $newresponse, 'unit');
167         }
169         return true;
170     }
172     public function get_correct_response() {
173         $answer = $this->get_correct_answer();
174         if (!$answer) {
175             return array();
176         }
178         $response = array('answer' => str_replace('.', $this->ap->get_point(), $answer->answer));
180         if ($this->has_separate_unit_field()) {
181             $response['unit'] = $this->ap->get_default_unit();
182         } else if ($this->unitdisplay == qtype_numerical::UNITINPUT) {
183             $response['answer'] = $this->ap->add_unit($answer->answer);
184         }
186         return $response;
187     }
189     /**
190      * Get an answer that contains the feedback and fraction that should be
191      * awarded for this response.
192      * @param number $value the numerical value of a response.
193      * @param number $multiplier for the unit the student gave, if any. When no
194      *      unit was given, or an unrecognised unit was given, $multiplier will be null.
195      * @return question_answer the matching answer.
196      */
197     public function get_matching_answer($value, $multiplier) {
198         if (is_null($value) || $value === '') {
199             return null;
200         }
202         if (!is_null($multiplier)) {
203             $scaledvalue = $value * $multiplier;
204         } else {
205             $scaledvalue = $value;
206         }
207         foreach ($this->answers as $answer) {
208             if ($answer->within_tolerance($scaledvalue)) {
209                 $answer->unitisright = !is_null($multiplier);
210                 return $answer;
211             } else if ($answer->within_tolerance($value)) {
212                 $answer->unitisright = false;
213                 return $answer;
214             }
215         }
217         return null;
218     }
220     public function get_correct_answer() {
221         foreach ($this->answers as $answer) {
222             $state = question_state::graded_state_for_fraction($answer->fraction);
223             if ($state == question_state::$gradedright) {
224                 return $answer;
225             }
226         }
227         return null;
228     }
230     /**
231      * Adjust the fraction based on whether the unit was correct.
232      * @param number $fraction
233      * @param bool $unitisright
234      * @return number
235      */
236     public function apply_unit_penalty($fraction, $unitisright) {
237         if ($unitisright) {
238             return $fraction;
239         }
241         if ($this->unitgradingtype == qtype_numerical::UNITGRADEDOUTOFMARK) {
242             $fraction -= $this->unitpenalty * $fraction;
243         } else if ($this->unitgradingtype == qtype_numerical::UNITGRADEDOUTOFMAX) {
244             $fraction -= $this->unitpenalty;
245         }
246         return max($fraction, 0);
247     }
249     public function grade_response(array $response) {
250         if ($this->has_separate_unit_field()) {
251             $selectedunit = $response['unit'];
252         } else {
253             $selectedunit = null;
254         }
255         list($value, $unit, $multiplier) = $this->ap->apply_units(
256                 $response['answer'], $selectedunit);
258         $answer = $this->get_matching_answer($value, $multiplier);
259         if (!$answer) {
260             return array(0, question_state::$gradedwrong);
261         }
263         $fraction = $this->apply_unit_penalty($answer->fraction, $answer->unitisright);
264         return array($fraction, question_state::graded_state_for_fraction($fraction));
265     }
267     public function classify_response(array $response) {
268         if (!$this->is_gradable_response($response)) {
269             return array($this->id => question_classified_response::no_response());
270         }
272         if ($this->has_separate_unit_field()) {
273             $selectedunit = $response['unit'];
274         } else {
275             $selectedunit = null;
276         }
277         list($value, $unit, $multiplier) = $this->ap->apply_units($response['answer'], $selectedunit);
278         $ans = $this->get_matching_answer($value, $multiplier);
280         $resp = $response['answer'];
281         if ($this->has_separate_unit_field()) {
282             $resp = $this->ap->add_unit($resp, $unit);
283         }
285         if ($value === null) {
286             // Invalid response shown as no response (but show actual response).
287             return array($this->id => new question_classified_response(null, $resp, 0));
288         } else if (!$ans) {
289             // Does not match any answer.
290             return array($this->id => new question_classified_response(0, $resp, 0));
291         }
293         return array($this->id => new question_classified_response($ans->id,
294                 $resp,
295                 $this->apply_unit_penalty($ans->fraction, $ans->unitisright)));
296     }
298     public function check_file_access($qa, $options, $component, $filearea, $args,
299             $forcedownload) {
300         if ($component == 'question' && $filearea == 'answerfeedback') {
301             $currentanswer = $qa->get_last_qt_var('answer');
302             if ($this->has_separate_unit_field()) {
303                 $selectedunit = $qa->get_last_qt_var('unit');
304             } else {
305                 $selectedunit = null;
306             }
307             list($value, $unit, $multiplier) = $this->ap->apply_units(
308                     $currentanswer, $selectedunit);
309             $answer = $this->get_matching_answer($value, $multiplier);
310             $answerid = reset($args); // Itemid is answer id.
311             return $options->feedback && $answer && $answerid == $answer->id;
313         } else if ($component == 'question' && $filearea == 'hint') {
314             return $this->check_hint_file_access($qa, $options, $args);
316         } else {
317             return parent::check_file_access($qa, $options, $component, $filearea,
318                     $args, $forcedownload);
319         }
320     }
324 /**
325  * Subclass of {@link question_answer} with the extra information required by
326  * the numerical question type.
327  *
328  * @copyright  2009 The Open University
329  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
330  */
331 class qtype_numerical_answer extends question_answer {
332     /** @var float allowable margin of error. */
333     public $tolerance;
334     /** @var integer|string see {@link get_tolerance_interval()} for the meaning of this value. */
335     public $tolerancetype = 2;
337     public function __construct($id, $answer, $fraction, $feedback, $feedbackformat, $tolerance) {
338         parent::__construct($id, $answer, $fraction, $feedback, $feedbackformat);
339         $this->tolerance = abs($tolerance);
340     }
342     public function get_tolerance_interval() {
343         if ($this->answer === '*') {
344             throw new coding_exception('Cannot work out tolerance interval for answer *.');
345         }
347         // Smallest number that, when added to 1, is different from 1.
348         $epsilon = pow(10, -1 * ini_get('precision'));
350         // We need to add a tiny fraction depending on the set precision to make
351         // the comparison work correctly, otherwise seemingly equal values can
352         // yield false. See MDL-3225.
353         $tolerance = abs($this->tolerance) + $epsilon;
355         switch ($this->tolerancetype) {
356             case 1: case 'relative':
357                 $range = abs($this->answer) * $tolerance;
358                 return array($this->answer - $range, $this->answer + $range);
360             case 2: case 'nominal':
361                 $tolerance = $this->tolerance + $epsilon * max(abs($this->tolerance), abs($this->answer), $epsilon);
362                 return array($this->answer - $tolerance, $this->answer + $tolerance);
364             case 3: case 'geometric':
365                 $quotient = 1 + abs($tolerance);
366                 return array($this->answer / $quotient, $this->answer * $quotient);
368             default:
369                 throw new coding_exception('Unknown tolerance type ' . $this->tolerancetype);
370         }
371     }
373     public function within_tolerance($value) {
374         if ($this->answer === '*') {
375             return true;
376         }
377         list($min, $max) = $this->get_tolerance_interval();
378         return $min <= $value && $value <= $max;
379     }