a5384527237c6dc45c4841e42692a8cef32a05b1
[moodle.git] / question / behaviour / behaviourbase.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  * Defines the quetsion behaviour base class
19  *
20  * @package    moodlecore
21  * @subpackage questionbehaviours
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();
30 /**
31  * The base class for question behaviours.
32  *
33  * A question behaviour is used by the question engine, specifically by
34  * a {@link question_attempt} to manage the flow of actions a student can take
35  * as they work through a question, and later, as a teacher manually grades it.
36  * In turn, the behaviour will delegate certain processing to the
37  * relevant {@link question_definition}.
38  *
39  * @copyright  2009 The Open University
40  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
41  */
42 abstract class question_behaviour {
43     /**
44      * Certain behaviours are definitive of a  way that questions can
45      * behave when attempted. For example deferredfeedback model, interactive
46      * model, etc. These are the options that should be listed in the
47      * user-interface. These models should define the class constant
48      * IS_ARCHETYPAL as true. Other models are more implementation details, for
49      * example the informationitem model, or a special subclass like
50      * interactive_adapted_for_my_qtype. These models should IS_ARCHETYPAL as
51      * false.
52      * @var boolean
53      */
54     const IS_ARCHETYPAL = false;
56     /** @var question_attempt the question attempt we are managing. */
57     protected $qa;
58     /** @var question_definition shortcut to $qa->get_question(). */
59     protected $question;
61     /**
62      * Normally you should not call this constuctor directly. The appropriate
63      * behaviour object is created automatically as part of
64      * {@link question_attempt::start()}.
65      * @param question_attempt $qa the question attempt we will be managing.
66      * @param string $preferredbehaviour the type of behaviour that was actually
67      *      requested. This information is not needed in most cases, the type of
68      *      subclass is enough, but occasionally it is needed.
69      */
70     public function __construct(question_attempt $qa, $preferredbehaviour) {
71         $this->qa = $qa;
72         $this->question = $qa->get_question();
73         if (!$this->is_compatible_question($this->question)) {
74             throw new coding_exception('This behaviour (' . $this->get_name() .
75                     ') cannot work with this question (' . get_class($this->question) . ')');
76         }
77     }
79     /**
80      * Some behaviours can only work with certing types of question. This method
81      * allows the behaviour to verify that a question is compatible.
82      *
83      * This implementation is only provided for backwards-compatibility. You should
84      * override this method if you are implementing a behaviour.
85      *
86      * @param question_definition $question the question.
87      */
88     public abstract function is_compatible_question(question_definition $question);
90     /**
91      * @return string the name of this behaviour. For example the name of
92      * qbehaviour_mymodle is 'mymodel'.
93      */
94     public function get_name() {
95         return substr(get_class($this), 11);
96     }
98     /**
99      * 'Override' this method if there are some display options that do not make
100      * sense 'during the attempt'.
101      * @return array of {@link question_display_options} field names, that are
102      * not relevant to this behaviour before a 'finish' action.
103      */
104     public static function get_unused_display_options() {
105         return array();
106     }
108     /**
109      * Cause the question to be renderered. This gets the appropriate behaviour
110      * renderer using {@link get_renderer()}, and adjusts the display
111      * options using {@link adjust_display_options()} and then calls
112      * {@link core_question_renderer::question()} to do the work.
113      * @param question_display_options $options controls what should and should not be displayed.
114      * @param unknown_type $number the question number to display.
115      * @param core_question_renderer $qoutput the question renderer that will coordinate everything.
116      * @param qtype_renderer $qtoutput the question type renderer that will be helping.
117      * @return HTML fragment.
118      */
119     public function render(question_display_options $options, $number,
120             core_question_renderer $qoutput, qtype_renderer $qtoutput) {
121         $behaviouroutput = $this->get_renderer($qoutput->get_page());
122         $options = clone($options);
123         $this->adjust_display_options($options);
124         return $qoutput->question($this->qa, $behaviouroutput, $qtoutput, $options, $number);
125     }
127     /**
128      * Checks whether the users is allow to be served a particular file.
129      * @param question_display_options $options the options that control display of the question.
130      * @param string $component the name of the component we are serving files for.
131      * @param string $filearea the name of the file area.
132      * @param array $args the remaining bits of the file path.
133      * @param bool $forcedownload whether the user must be forced to download the file.
134      * @return bool true if the user can access this file.
135      */
136     public function check_file_access($options, $component, $filearea, $args, $forcedownload) {
137         $this->adjust_display_options($options);
138         return $this->question->check_file_access($this->qa, $options, $component,
139                 $filearea, $args, $forcedownload);
140     }
142     /**
143      * @param moodle_page $page the page to render for.
144      * @return qbehaviour_renderer get the appropriate renderer to use for this model.
145      */
146     public function get_renderer(moodle_page $page) {
147         return $page->get_renderer(get_class($this));
148     }
150     /**
151      * Make any changes to the display options before a question is rendered, so
152      * that it can be displayed in a way that is appropriate for the statue it is
153      * currently in. For example, by default, if the question is finished, we
154      * ensure that it is only ever displayed read-only.
155      * @param question_display_options $options the options to adjust. Just change
156      * the properties of this object - objects are passed by referece.
157      */
158     public function adjust_display_options(question_display_options $options) {
159         if (!$this->qa->has_marks()) {
160             $options->correctness = false;
161             $options->numpartscorrect = false;
162         }
163         if ($this->qa->get_state()->is_finished()) {
164             $options->readonly = true;
165             $options->numpartscorrect = $options->numpartscorrect &&
166                     $this->qa->get_state()->is_partially_correct() &&
167                     !empty($this->question->shownumcorrect);
168         } else {
169             $options->hide_all_feedback();
170         }
171     }
173     /**
174      * Get the most applicable hint for the question in its current state.
175      * @return question_hint the most applicable hint, or null, if none.
176      */
177     public function get_applicable_hint() {
178         return null;
179     }
181     /**
182      * What is the minimum fraction that can be scored for this question.
183      * Normally this will be based on $this->question->get_min_fraction(),
184      * but may be modified in some way by the model.
185      *
186      * @return number the minimum fraction when this question is attempted under
187      * this model.
188      */
189     public function get_min_fraction() {
190         return 0;
191     }
193     /**
194      * Adjust a random guess score for a question using this model. You have to
195      * do this without knowing details of the specific question, or which usage
196      * it is in.
197      * @param number $fraction the random guess score from the question type.
198      * @return number the adjusted fraction.
199      */
200     public static function adjust_random_guess_score($fraction) {
201         return $fraction;
202     }
204     /**
205      * Return an array of the behaviour variables that could be submitted
206      * as part of a question of this type, with their types, so they can be
207      * properly cleaned.
208      * @return array variable name => PARAM_... constant.
209      */
210     public function get_expected_data() {
211         if (!$this->qa->get_state()->is_finished()) {
212             return array();
213         }
215         $vars = array('comment' => PARAM_RAW);
216         if ($this->qa->get_max_mark()) {
217             $vars['mark'] = question_attempt::PARAM_MARK;
218             $vars['maxmark'] = PARAM_FLOAT;
219         }
220         return $vars;
221     }
223     /**
224      * Return an array of question type variables for the question in its current
225      * state. Normally, if {@link adjust_display_options()} would set
226      * {@link question_display_options::$readonly} to true, then this method
227      * should return an empty array, otherwise it should return
228      * $this->question->get_expected_data(). Thus, there should be little need to
229      * override this method.
230      * @return array|string variable name => PARAM_... constant, or, as a special case
231      *      that should only be used in unavoidable, the constant question_attempt::USE_RAW_DATA
232      *      meaning take all the raw submitted data belonging to this question.
233      */
234     public function get_expected_qt_data() {
235         $fakeoptions = new question_display_options();
236         $fakeoptions->readonly = false;
237         $this->adjust_display_options($fakeoptions);
238         if ($fakeoptions->readonly) {
239             return array();
240         } else {
241             return $this->question->get_expected_data();
242         }
243     }
245     /**
246      * Return an array of any im variables, and the value required to get full
247      * marks.
248      * @return array variable name => value.
249      */
250     public function get_correct_response() {
251         return array();
252     }
254     /**
255      * Generate a brief, plain-text, summary of this question. This is used by
256      * various reports. This should show the particular variant of the question
257      * as presented to students. For example, the calculated quetsion type would
258      * fill in the particular numbers that were presented to the student.
259      * This method will return null if such a summary is not possible, or
260      * inappropriate.
261      *
262      * Normally, this method delegates to {question_definition::get_question_summary()}.
263      *
264      * @return string|null a plain text summary of this question.
265      */
266     public function get_question_summary() {
267         return $this->question->get_question_summary();
268     }
270     /**
271      * Generate a brief, plain-text, summary of the correct answer to this question.
272      * This is used by various reports, and can also be useful when testing.
273      * This method will return null if such a summary is not possible, or
274      * inappropriate.
275      *
276      * @return string|null a plain text summary of the right answer to this question.
277      */
278     public function get_right_answer_summary() {
279         return null;
280     }
282     /**
283      * Used by {@link start_based_on()} to get the data needed to start a new
284      * attempt from the point this attempt has go to.
285      * @return array name => value pairs.
286      */
287     public function get_resume_data() {
288         $olddata = $this->qa->get_step(0)->get_all_data();
289         $olddata = $this->qa->get_last_qt_data() + $olddata;
290         $olddata = $this->get_our_resume_data() + $olddata;
291         return $olddata;
292     }
294     /**
295      * Used by {@link start_based_on()} to get the data needed to start a new
296      * attempt from the point this attempt has go to.
297      * @return unknown_type
298      */
299     protected function get_our_resume_data() {
300         return array();
301     }
303     /**
304      * @return array subpartid => object with fields
305      *      ->responseclassid matches one of the values returned from
306      *                        quetion_type::get_possible_responses.
307      *      ->response the actual response the student gave to this part, as a string.
308      *      ->fraction the credit awarded for this subpart, may be null.
309      *      returns an empty array if no analysis is possible.
310      */
311     public function classify_response() {
312         return $this->question->classify_response($this->qa->get_last_qt_data());
313     }
315     /**
316      * Generate a brief textual description of the current state of the question,
317      * normally displayed under the question number.
318      *
319      * @param bool $showcorrectness Whether right/partial/wrong states should
320      * be distinguised.
321      * @return string a brief summary of the current state of the qestion attempt.
322      */
323     public function get_state_string($showcorrectness) {
324         return $this->qa->get_state()->default_string($showcorrectness);
325     }
327     public abstract function summarise_action(question_attempt_step $step);
329     /**
330      * Initialise the first step in a question attempt when a new
331      * {@link question_attempt} is being started.
332      *
333      * This method must call $this->question->start_attempt($step, $variant), and may
334      * perform additional processing if the behaviour requries it.
335      *
336      * @param question_attempt_step $step the first step of the
337      *      question_attempt being started.
338      * @param int $variant which variant of the question to use.
339      */
340     public function init_first_step(question_attempt_step $step, $variant) {
341         $this->question->start_attempt($step, $variant);
342         $step->set_state(question_state::$todo);
343     }
345     /**
346      * When an attempt is started based on a previous attempt (see
347      * {@link question_attempt::start_based_on}) this method is called to setup
348      * the new attempt.
349      *
350      * This method must call $this->question->apply_attempt_state($step), and may
351      * perform additional processing if the behaviour requries it.
352      *
353      * @param question_attempt_step The first step of the {@link question_attempt}
354      *      being loaded.
355      */
356     public function apply_attempt_state(question_attempt_step $step) {
357         $this->question->apply_attempt_state($step);
358         $step->set_state(question_state::$todo);
359     }
361     /**
362      * Checks whether two manual grading actions are the same. That is, whether
363      * the comment, and the mark (if given) is the same.
364      *
365      * @param question_attempt_step $pendingstep contains the new responses.
366      * @return bool whether the new response is the same as we already have.
367      */
368     protected function is_same_comment($pendingstep) {
369         $previouscomment = $this->qa->get_last_behaviour_var('comment');
370         $newcomment = $pendingstep->get_behaviour_var('comment');
372         if (is_null($previouscomment) && !html_is_blank($newcomment) ||
373                 $previouscomment != $newcomment) {
374             return false;
375         }
377         // So, now we know the comment is the same, so check the mark, if present.
378         $previousfraction = $this->qa->get_fraction();
379         $newmark = $pendingstep->get_behaviour_var('mark');
381         if (is_null($previousfraction)) {
382             return is_null($newmark) || $newmark === '';
383         } else if (is_null($newmark) || $newmark === '') {
384             return false;
385         }
387         $newfraction = $newmark / $pendingstep->get_behaviour_var('maxmark');
389         return abs($newfraction - $previousfraction) < 0.0000001;
390     }
392     /**
393      * The main entry point for processing an action.
394      *
395      * All the various operations that can be performed on a
396      * {@link question_attempt} get channeled through this function, except for
397      * {@link question_attempt::start()} which goes to {@link init_first_step()}.
398      * {@link question_attempt::finish()} becomes an action with im vars
399      * finish => 1, and manual comment/grade becomes an action with im vars
400      * comment => comment text, and mark => ..., max_mark => ... if the question
401      * is graded.
402      *
403      * This method should first determine whether the action is significant. For
404      * example, if no actual action is being performed, but instead the current
405      * responses are being saved, and there has been no change since the last
406      * set of responses that were saved, this the action is not significatn. In
407      * this case, this method should return {@link question_attempt::DISCARD}.
408      * Otherwise it should return {@link question_attempt::KEEP}.
409      *
410      * If the action is significant, this method should also perform any
411      * necessary updates to $pendingstep. For example, it should call
412      * {@link question_attempt_step::set_state()} to set the state that results
413      * from this action, and if this is a grading action, it should call
414      * {@link question_attempt_step::set_fraction()}.
415      *
416      * This method can also call {@link question_attempt_step::set_behaviour_var()} to
417      * store additional infomation. There are two main uses for this. This can
418      * be used to store the result of any randomisation done. It is important to
419      * store the result of randomisation once, and then in future use the same
420      * outcome if the actions are ever replayed. This is how regrading works.
421      * The other use is to cache the result of expensive computations performed
422      * on the raw response data, so that subsequent display and review of the
423      * question does not have to repeat the same expensive computations.
424      *
425      * Often this method is implemented as a dispatching method that examines
426      * the pending step to determine the kind of action being performed, and
427      * then calls a more specific method like {@link process_save()} or
428      * {@link process_comment()}. Look at some of the standard behaviours
429      * for examples.
430      *
431      * @param question_attempt_pending_step $pendingstep a partially initialised step
432      *      containing all the information about the action that is being peformed. This
433      *      information can be accessed using {@link question_attempt_step::get_behaviour_var()}.
434      * @return bool either {@link question_attempt::KEEP} or {@link question_attempt::DISCARD}
435      */
436     public abstract function process_action(question_attempt_pending_step $pendingstep);
438     /**
439      * Auto-saved data. By default this does nothing. interesting processing is
440      * done in {@link question_behaviour_with_save}.
441      *
442      * @param question_attempt_pending_step $pendingstep a partially initialised step
443      *      containing all the information about the action that is being peformed. This
444      *      information can be accessed using {@link question_attempt_step::get_behaviour_var()}.
445      * @return bool either {@link question_attempt::KEEP} or {@link question_attempt::DISCARD}
446      */
447     public function process_autosave(question_attempt_pending_step $pendingstep) {
448         return question_attempt::DISCARD;
449     }
451     /**
452      * Implementation of processing a manual comment/grade action that should
453      * be suitable for most subclasses.
454      * @param question_attempt_pending_step $pendingstep a partially initialised step
455      *      containing all the information about the action that is being peformed.
456      * @return bool either {@link question_attempt::KEEP}
457      */
458     public function process_comment(question_attempt_pending_step $pendingstep) {
459         if (!$this->qa->get_state()->is_finished()) {
460             throw new coding_exception('Cannot manually grade a question before it is finshed.');
461         }
463         if ($this->is_same_comment($pendingstep)) {
464             return question_attempt::DISCARD;
465         }
467         if ($pendingstep->has_behaviour_var('mark')) {
468             $fraction = $pendingstep->get_behaviour_var('mark') /
469                             $pendingstep->get_behaviour_var('maxmark');
470             if ($pendingstep->get_behaviour_var('mark') === '') {
471                 $fraction = null;
472             } else if ($fraction > 1 || $fraction < $this->qa->get_min_fraction()) {
473                 throw new coding_exception('Score out of range when processing ' .
474                         'a manual grading action.', 'Question ' . $this->question->id .
475                                 ', slot ' . $this->qa->get_slot() . ', fraction ' . $fraction);
476             }
477             $pendingstep->set_fraction($fraction);
478         }
480         $pendingstep->set_state($this->qa->get_state()->corresponding_commented_state(
481                 $pendingstep->get_fraction()));
482         return question_attempt::KEEP;
483     }
485     /**
486      * Validate that the manual grade submitted for a particular question is in range.
487      * @param int $qubaid the question_usage id.
488      * @param int $slot the slot number within the usage.
489      * @return bool whether the submitted data is in range.
490      */
491     public static function is_manual_grade_in_range($qubaid, $slot) {
492         $prefix = 'q' . $qubaid . ':' . $slot . '_';
493         $mark = question_utils::optional_param_mark($prefix . '-mark');
494         $maxmark = optional_param($prefix . '-maxmark', null, PARAM_FLOAT);
495         $minfraction = optional_param($prefix . ':minfraction', null, PARAM_FLOAT);
496         return is_null($mark) || ($mark >= $minfraction * $maxmark && $mark <= $maxmark);
497     }
499     /**
500      * @param $comment the comment text to format. If omitted,
501      *      $this->qa->get_manual_comment() is used.
502      * @param $commentformat the format of the comment, one of the FORMAT_... constants.
503      * @return string the comment, ready to be output.
504      */
505     public function format_comment($comment = null, $commentformat = null) {
506         $formatoptions = new stdClass();
507         $formatoptions->noclean = true;
508         $formatoptions->para = false;
510         if (is_null($comment)) {
511             list($comment, $commentformat) = $this->qa->get_manual_comment();
512         }
514         return format_text($comment, $commentformat, $formatoptions);
515     }
517     /**
518      * @return string a summary of a manual comment action.
519      * @param unknown_type $step
520      */
521     protected function summarise_manual_comment($step) {
522         $a = new stdClass();
523         if ($step->has_behaviour_var('comment')) {
524             $a->comment = shorten_text(html_to_text($this->format_comment(
525                     $step->get_behaviour_var('comment')), 0, false), 200);
526         } else {
527             $a->comment = '';
528         }
530         $mark = $step->get_behaviour_var('mark');
531         if (is_null($mark) || $mark === '') {
532             return get_string('commented', 'question', $a->comment);
533         } else {
534             $a->mark = $mark / $step->get_behaviour_var('maxmark') * $this->qa->get_max_mark();
535             return get_string('manuallygraded', 'question', $a);
536         }
537     }
539     public function summarise_start($step) {
540         return get_string('started', 'question');
541     }
543     public function summarise_finish($step) {
544         return get_string('attemptfinished', 'question');
545     }
549 /**
550  * A subclass of {@link question_behaviour} that implements a save
551  * action that is suitable for most questions that implement the
552  * {@link question_manually_gradable} interface.
553  *
554  * @copyright  2009 The Open University
555  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
556  */
557 abstract class question_behaviour_with_save extends question_behaviour {
558     public function required_question_definition_type() {
559         return 'question_manually_gradable';
560     }
562     public function apply_attempt_state(question_attempt_step $step) {
563         parent::apply_attempt_state($step);
564         if ($this->question->is_complete_response($step->get_qt_data())) {
565             $step->set_state(question_state::$complete);
566         }
567     }
569     /**
570      * Work out whether the response in $pendingstep are significantly different
571      * from the last set of responses we have stored.
572      * @param question_attempt_step $pendingstep contains the new responses.
573      * @return bool whether the new response is the same as we already have.
574      */
575     protected function is_same_response(question_attempt_step $pendingstep) {
576         return $this->question->is_same_response(
577                 $this->qa->get_last_step()->get_qt_data(), $pendingstep->get_qt_data());
578     }
580     /**
581      * Work out whether the response in $pendingstep represent a complete answer
582      * to the question. Normally this will call
583      * {@link question_manually_gradable::is_complete_response}, but some
584      * behaviours, for example the CBM ones, have their own parts to the
585      * response.
586      * @param question_attempt_step $pendingstep contains the new responses.
587      * @return bool whether the new response is complete.
588      */
589     protected function is_complete_response(question_attempt_step $pendingstep) {
590         return $this->question->is_complete_response($pendingstep->get_qt_data());
591     }
593     public function process_autosave(question_attempt_pending_step $pendingstep) {
594         // If already finished. Nothing to do.
595         if ($this->qa->get_state()->is_finished()) {
596             return question_attempt::DISCARD;
597         }
599         // If the new data is the same as we already have, then we don't need it.
600         if ($this->is_same_response($pendingstep)) {
601             return question_attempt::DISCARD;
602         }
604         // Repeat that test discarding any existing autosaved data.
605         if ($this->qa->has_autosaved_step()) {
606             $this->qa->discard_autosaved_step();
607             if ($this->is_same_response($pendingstep)) {
608                 return question_attempt::DISCARD;
609             }
610         }
612         // OK, we need to save.
613         return $this->process_save($pendingstep);
614     }
616     /**
617      * Implementation of processing a save action that should be suitable for
618      * most subclasses.
619      * @param question_attempt_pending_step $pendingstep a partially initialised step
620      *      containing all the information about the action that is being peformed.
621      * @return bool either {@link question_attempt::KEEP} or {@link question_attempt::DISCARD}
622      */
623     public function process_save(question_attempt_pending_step $pendingstep) {
624         if ($this->qa->get_state()->is_finished()) {
625             return question_attempt::DISCARD;
626         } else if (!$this->qa->get_state()->is_active()) {
627             throw new coding_exception('Question is not active, cannot process_actions.');
628         }
630         if ($this->is_same_response($pendingstep)) {
631             return question_attempt::DISCARD;
632         }
634         if ($this->is_complete_response($pendingstep)) {
635             $pendingstep->set_state(question_state::$complete);
636         } else {
637             $pendingstep->set_state(question_state::$todo);
638         }
639         return question_attempt::KEEP;
640     }
642     public function summarise_submit(question_attempt_step $step) {
643         return get_string('submitted', 'question',
644                 $this->question->summarise_response($step->get_qt_data()));
645     }
647     public function summarise_save(question_attempt_step $step) {
648         $data = $step->get_submitted_data();
649         if (empty($data)) {
650             return $this->summarise_start($step);
651         }
652         return get_string('saved', 'question',
653                 $this->question->summarise_response($step->get_qt_data()));
654     }
657     public function summarise_finish($step) {
658         $data = $step->get_qt_data();
659         if ($data) {
660             return get_string('attemptfinishedsubmitting', 'question',
661                     $this->question->summarise_response($data));
662         }
663         return get_string('attemptfinished', 'question');
664     }
668 /**
669  * This helper class contains the constants and methods required for
670  * manipulating scores for certainly based marking.
671  *
672  * @copyright  2009 The Open University
673  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
674  */
675 abstract class question_cbm {
676     /**#@+ @var integer named constants for the certainty levels. */
677     const LOW = 1;
678     const MED = 2;
679     const HIGH = 3;
680     /**#@-*/
682     /** @var array list of all the certainty levels. */
683     public static $certainties = array(self::LOW, self::MED, self::HIGH);
685     /**#@+ @var array coefficients used to adjust the fraction based on certainty.. */
686     protected static $factor = array(
687         self::LOW => 0.333333333333333,
688         self::MED => 1.333333333333333,
689         self::HIGH => 3,
690     );
691     protected static $offset = array(
692         self::LOW => 0,
693         self::MED => -0.666666666666667,
694         self::HIGH => -2,
695     );
696     /**#@-*/
698     /**
699      * @return int the default certaintly level that should be assuemd if
700      * the student does not choose one.
701      */
702     public static function default_certainty() {
703         return self::LOW;
704     }
706     /**
707      * Given a fraction, and a certainly, compute the adjusted fraction.
708      * @param number $fraction the raw fraction for this question.
709      * @param int $certainty one of the certainly level constants.
710      * @return number the adjusted fraction taking the certainly into account.
711      */
712     public static function adjust_fraction($fraction, $certainty) {
713         return self::$offset[$certainty] + self::$factor[$certainty] * $fraction;
714     }
716     /**
717      * @param int $certainty one of the LOW/MED/HIGH constants.
718      * @return string a textual desciption of this certainly.
719      */
720     public static function get_string($certainty) {
721         return get_string('certainty' . $certainty, 'qbehaviour_deferredcbm');
722     }
724     public static function summary_with_certainty($summary, $certainty) {
725         if (is_null($certainty)) {
726             return $summary;
727         }
728         return $summary . ' [' . self::get_string($certainty) . ']';
729     }