Merge branch 'MDL-68749-310-2' of git://github.com/mickhawkins/moodle into MOODLE_310...
[moodle.git] / question / type / numerical / question.php
CommitLineData
fe041243 1<?php
fe041243
TH
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
fe041243
TH
17/**
18 * Numerical question definition class.
19 *
7764183a
TH
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
fe041243
TH
24 */
25
a17b297d
TH
26
27defined('MOODLE_INTERNAL') || die();
28
97562c4d
MG
29require_once($CFG->dirroot . '/question/type/questionbase.php');
30
fe041243
TH
31/**
32 * Represents a numerical question.
33 *
7764183a
TH
34 * @copyright 2009 The Open University
35 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
fe041243 36 */
544de1c0 37class qtype_numerical_question extends question_graded_automatically {
fe041243
TH
38 /** @var array of question_answer. */
39 public $answers = array();
544de1c0 40
8566369f 41 /** @var int one of the constants UNITNONE, UNITRADIO, UNITSELECT or UNITINPUT. */
544de1c0
TH
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;
47
fe041243
TH
48 /** @var qtype_numerical_answer_processor */
49 public $ap;
50
fe041243 51 public function get_expected_data() {
5073fb74 52 $expected = array('answer' => PARAM_RAW_TRIMMED);
8566369f 53 if ($this->has_separate_unit_field()) {
5073fb74
TH
54 $expected['unit'] = PARAM_RAW_TRIMMED;
55 }
56 return $expected;
fe041243
TH
57 }
58
8566369f
TH
59 public function has_separate_unit_field() {
60 return $this->unitdisplay == qtype_numerical::UNITRADIO ||
61 $this->unitdisplay == qtype_numerical::UNITSELECT;
62 }
63
1da821bb 64 public function start_attempt(question_attempt_step $step, $variant) {
ef31a283
TH
65 $step->set_qt_var('_separators',
66 $this->ap->get_point() . '$' . $this->ap->get_separator());
67 }
68
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);
fe041243
TH
72 }
73
74 public function summarise_response(array $response) {
75 if (isset($response['answer'])) {
5073fb74 76 $resp = $response['answer'];
fe041243 77 } else {
5073fb74
TH
78 $resp = null;
79 }
80
8566369f 81 if ($this->has_separate_unit_field() && !empty($response['unit'])) {
5073fb74 82 $resp = $this->ap->add_unit($resp, $response['unit']);
fe041243 83 }
5073fb74
TH
84
85 return $resp;
fe041243
TH
86 }
87
9b1fc262
SL
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.');
71fc74ce
SL
93 }
94
9b1fc262
SL
95 if (!empty($summary)) {
96 return ['answer' => $summary];
97 } else {
98 return [];
71fc74ce 99 }
71fc74ce
SL
100 }
101
5d2465c3 102 public function is_gradable_response(array $response) {
fe041243
TH
103 return array_key_exists('answer', $response) &&
104 ($response['answer'] || $response['answer'] === '0' || $response['answer'] === 0);
105 }
106
5d2465c3
TH
107 public function is_complete_response(array $response) {
108 if (!$this->is_gradable_response($response)) {
109 return false;
110 }
111
112 list($value, $unit) = $this->ap->apply_units($response['answer']);
113 if (is_null($value)) {
114 return false;
115 }
116
5073fb74
TH
117 if ($this->unitdisplay != qtype_numerical::UNITINPUT && $unit) {
118 return false;
119 }
120
8566369f 121 if ($this->has_separate_unit_field() && empty($response['unit'])) {
5d2465c3
TH
122 return false;
123 }
124
e64e28d7
DP
125 if ($this->ap->contains_thousands_seaparator($response['answer'])) {
126 return false;
127 }
128
5d2465c3
TH
129 return true;
130 }
131
fe041243 132 public function get_validation_error(array $response) {
5d2465c3
TH
133 if (!$this->is_gradable_response($response)) {
134 return get_string('pleaseenterananswer', 'qtype_numerical');
135 }
136
137 list($value, $unit) = $this->ap->apply_units($response['answer']);
138 if (is_null($value)) {
139 return get_string('invalidnumber', 'qtype_numerical');
fe041243 140 }
5d2465c3 141
5073fb74 142 if ($this->unitdisplay != qtype_numerical::UNITINPUT && $unit) {
5d2465c3
TH
143 return get_string('invalidnumbernounit', 'qtype_numerical');
144 }
145
8566369f 146 if ($this->has_separate_unit_field() && empty($response['unit'])) {
5073fb74
TH
147 return get_string('unitnotselected', 'qtype_numerical');
148 }
149
e64e28d7
DP
150 if ($this->ap->contains_thousands_seaparator($response['answer'])) {
151 return get_string('pleaseenteranswerwithoutthousandssep', 'qtype_numerical',
152 $this->ap->get_separator());
153 }
154
5d2465c3 155 return '';
fe041243
TH
156 }
157
158 public function is_same_response(array $prevresponse, array $newresponse) {
5073fb74
TH
159 if (!question_utils::arrays_same_at_key_missing_is_blank(
160 $prevresponse, $newresponse, 'answer')) {
161 return false;
162 }
163
8566369f 164 if ($this->has_separate_unit_field()) {
5073fb74
TH
165 return question_utils::arrays_same_at_key_missing_is_blank(
166 $prevresponse, $newresponse, 'unit');
167 }
168
cc9fc649 169 return true;
fe041243
TH
170 }
171
544de1c0
TH
172 public function get_correct_response() {
173 $answer = $this->get_correct_answer();
174 if (!$answer) {
175 return array();
176 }
177
eef75d4b 178 $response = array('answer' => str_replace('.', $this->ap->get_point(), $answer->answer));
5073fb74 179
8566369f 180 if ($this->has_separate_unit_field()) {
5073fb74
TH
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 }
185
186 return $response;
544de1c0
TH
187 }
188
189 /**
190 * Get an answer that contains the feedback and fraction that should be
f4555f88 191 * awarded for this response.
544de1c0 192 * @param number $value the numerical value of a response.
3a6eb8ef
TH
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.
544de1c0
TH
195 * @return question_answer the matching answer.
196 */
3a6eb8ef 197 public function get_matching_answer($value, $multiplier) {
b2a79cc1
TH
198 if (is_null($value) || $value === '') {
199 return null;
200 }
201
3a6eb8ef
TH
202 if (!is_null($multiplier)) {
203 $scaledvalue = $value * $multiplier;
204 } else {
205 $scaledvalue = $value;
206 }
f4555f88 207 foreach ($this->answers as $answer) {
3a6eb8ef
TH
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;
544de1c0
TH
213 return $answer;
214 }
215 }
b2a79cc1 216
544de1c0
TH
217 return null;
218 }
219
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 }
229
3a6eb8ef
TH
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) {
d7d8cee2
TH
238 return $fraction;
239 }
240
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 }
248
544de1c0 249 public function grade_response(array $response) {
8566369f 250 if ($this->has_separate_unit_field()) {
5073fb74
TH
251 $selectedunit = $response['unit'];
252 } else {
253 $selectedunit = null;
254 }
3a6eb8ef
TH
255 list($value, $unit, $multiplier) = $this->ap->apply_units(
256 $response['answer'], $selectedunit);
6e344148 257
3a6eb8ef 258 $answer = $this->get_matching_answer($value, $multiplier);
544de1c0
TH
259 if (!$answer) {
260 return array(0, question_state::$gradedwrong);
261 }
262
3a6eb8ef 263 $fraction = $this->apply_unit_penalty($answer->fraction, $answer->unitisright);
544de1c0 264 return array($fraction, question_state::graded_state_for_fraction($fraction));
fe041243
TH
265 }
266
544de1c0 267 public function classify_response(array $response) {
1d75d9fe 268 if (!$this->is_gradable_response($response)) {
544de1c0
TH
269 return array($this->id => question_classified_response::no_response());
270 }
271
8566369f 272 if ($this->has_separate_unit_field()) {
5073fb74
TH
273 $selectedunit = $response['unit'];
274 } else {
275 $selectedunit = null;
276 }
3a6eb8ef
TH
277 list($value, $unit, $multiplier) = $this->ap->apply_units($response['answer'], $selectedunit);
278 $ans = $this->get_matching_answer($value, $multiplier);
5073fb74
TH
279
280 $resp = $response['answer'];
8566369f 281 if ($this->has_separate_unit_field()) {
5073fb74
TH
282 $resp = $this->ap->add_unit($resp, $unit);
283 }
284
f4555f88
JP
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.
24400682
TH
290 return array($this->id => new question_classified_response(0, $resp, 0));
291 }
292
d7d8cee2 293 return array($this->id => new question_classified_response($ans->id,
5073fb74 294 $resp,
3a6eb8ef 295 $this->apply_unit_penalty($ans->fraction, $ans->unitisright)));
fe041243 296 }
52ad7e0c 297
03b2b8fa
TH
298 public function check_file_access($qa, $options, $component, $filearea, $args,
299 $forcedownload) {
52ad7e0c
TH
300 if ($component == 'question' && $filearea == 'answerfeedback') {
301 $currentanswer = $qa->get_last_qt_var('answer');
3a6eb8ef
TH
302 if ($this->has_separate_unit_field()) {
303 $selectedunit = $qa->get_last_qt_var('unit');
304 } else {
305 $selectedunit = null;
306 }
b2a79cc1 307 list($value, $unit, $multiplier) = $this->ap->apply_units(
3a6eb8ef 308 $currentanswer, $selectedunit);
b2a79cc1 309 $answer = $this->get_matching_answer($value, $multiplier);
3d9645ae 310 $answerid = reset($args); // Itemid is answer id.
b2a79cc1 311 return $options->feedback && $answer && $answerid == $answer->id;
52ad7e0c
TH
312
313 } else if ($component == 'question' && $filearea == 'hint') {
314 return $this->check_hint_file_access($qa, $options, $args);
315
52ad7e0c 316 } else {
e0736817
TH
317 return parent::check_file_access($qa, $options, $component, $filearea,
318 $args, $forcedownload);
52ad7e0c
TH
319 }
320 }
fe041243
TH
321}
322
323
324/**
325 * Subclass of {@link question_answer} with the extra information required by
326 * the numerical question type.
327 *
7764183a
TH
328 * @copyright 2009 The Open University
329 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
fe041243
TH
330 */
331class 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;
336
337 public function __construct($id, $answer, $fraction, $feedback, $feedbackformat, $tolerance) {
338 parent::__construct($id, $answer, $fraction, $feedback, $feedbackformat);
339 $this->tolerance = abs($tolerance);
340 }
341
342 public function get_tolerance_interval() {
343 if ($this->answer === '*') {
88f0eb15 344 throw new coding_exception('Cannot work out tolerance interval for answer *.');
fe041243
TH
345 }
346
93266d0f
TH
347 // Smallest number that, when added to 1, is different from 1.
348 $epsilon = pow(10, -1 * ini_get('precision'));
349
fe041243
TH
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.
93266d0f 353 $tolerance = abs($this->tolerance) + $epsilon;
fe041243
TH
354
355 switch ($this->tolerancetype) {
356 case 1: case 'relative':
357 $range = abs($this->answer) * $tolerance;
358 return array($this->answer - $range, $this->answer + $range);
359
360 case 2: case 'nominal':
93266d0f 361 $tolerance = $this->tolerance + $epsilon * max(abs($this->tolerance), abs($this->answer), $epsilon);
fe041243
TH
362 return array($this->answer - $tolerance, $this->answer + $tolerance);
363
364 case 3: case 'geometric':
365 $quotient = 1 + abs($tolerance);
366 return array($this->answer / $quotient, $this->answer * $quotient);
367
368 default:
88f0eb15 369 throw new coding_exception('Unknown tolerance type ' . $this->tolerancetype);
fe041243
TH
370 }
371 }
372
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 }
380}