first commit

question/bank/statistics/classes/columns/discrimination_index.php

@@ -0,0 +1,68 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace qbank_statistics\columns;
+
+use core_question\local\bank\column_base;
+
+/**
+ * This columns shows a message about whether this question is OK or needs revision.
+ *
+ * This is based on the average discrimination index.
+ *
+ * @package    qbank_statistics
+ * @copyright  2021 Catalyst IT Australia Pty Ltd
+ * @author     Nathan Nguyen <nathannguyen@catalyst-au.net>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class discrimination_index extends column_base {
+
+    public function get_title(): string {
+        return get_string('discrimination_index', 'qbank_statistics');
+    }
+
+    public function help_icon(): ?\help_icon {
+        return new \help_icon('discrimination_index', 'qbank_statistics');
+    }
+
+    public function get_name(): string {
+        return 'discrimination_index';
+    }
+
+    public function get_required_statistics_fields(): array {
+        return ['discriminationindex'];
+    }
+
+    protected function display_content($question, $rowclasses) {
+        global $PAGE;
+
+        $discriminationindex = $this->qbank->get_aggregate_statistic($question->id, 'discriminationindex');
+        echo $PAGE->get_renderer('qbank_statistics')->render_discrimination_index($discriminationindex);
+    }
+
+    public function display_preview(\stdClass $question, string $rowclasses): void {
+        global $PAGE;
+
+        $this->display_start($question, $rowclasses);
+        echo $PAGE->get_renderer('qbank_statistics')->render_discrimination_index(50.00);
+        $this->display_end($question, $rowclasses);;
+    }
+
+    public function get_extra_classes(): array {
+        return ['pr-3'];
+    }
+
+}

question/bank/statistics/classes/columns/discriminative_efficiency.php

@@ -0,0 +1,65 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace qbank_statistics\columns;
+
+use core_question\local\bank\column_base;
+
+/**
+ * This column show the average discriminative efficiency for this question.
+ *
+ * @package    qbank_statistics
+ * @copyright  2021 Catalyst IT Australia Pty Ltd
+ * @author     Nathan Nguyen <nathannguyen@catalyst-au.net>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class discriminative_efficiency extends column_base {
+
+    public function get_title(): string {
+        return get_string('discriminative_efficiency', 'qbank_statistics');
+    }
+
+    public function help_icon(): ?\help_icon {
+        return new \help_icon('discriminative_efficiency', 'qbank_statistics');
+    }
+
+    public function get_name(): string {
+        return 'discriminative_efficiency';
+    }
+
+    public function get_required_statistics_fields(): array {
+        return ['discriminativeefficiency'];
+    }
+
+    protected function display_content($question, $rowclasses) {
+        global $PAGE;
+
+        $discriminativeefficiency = $this->qbank->get_aggregate_statistic($question->id, 'discriminativeefficiency');
+        echo $PAGE->get_renderer('qbank_statistics')->render_discriminative_efficiency($discriminativeefficiency);
+    }
+
+    public function display_preview(\stdClass $question, string $rowclasses): void {
+        global $PAGE;
+
+        $this->display_start($question, $rowclasses);
+        echo $PAGE->get_renderer('qbank_statistics')->render_discriminative_efficiency(25);
+        $this->display_end($question, $rowclasses);;
+    }
+
+    public function get_extra_classes(): array {
+        return ['pr-3'];
+    }
+}

question/bank/statistics/classes/columns/facility_index.php

@@ -0,0 +1,66 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace qbank_statistics\columns;
+
+use core_question\local\bank\column_base;
+use qbank_statistics\helper;
+
+/**
+ * This column show the average facility index for this question.
+ *
+ * @package    qbank_statistics
+ * @copyright  2021 Catalyst IT Australia Pty Ltd
+ * @author     Nathan Nguyen <nathannguyen@catalyst-au.net>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class facility_index extends column_base {
+
+    public function get_title(): string {
+        return get_string('facility_index', 'qbank_statistics');
+    }
+
+    public function help_icon(): ?\help_icon {
+        return new \help_icon('facility_index', 'qbank_statistics');
+    }
+
+    public function get_name(): string {
+        return 'facility_index';
+    }
+
+    public function get_required_statistics_fields(): array {
+        return ['facility'];
+    }
+
+    protected function display_content($question, $rowclasses) {
+        global $PAGE;
+
+        $facility = $this->qbank->get_aggregate_statistic($question->id, 'facility');
+        echo $PAGE->get_renderer('qbank_statistics')->render_facility_index($facility);
+    }
+
+    public function display_preview(\stdClass $question, string $rowclasses): void {
+        global $PAGE;
+
+        $this->display_start($question, $rowclasses);
+        echo $PAGE->get_renderer('qbank_statistics')->render_facility_index(0.75);
+        $this->display_end($question, $rowclasses);;
+    }
+
+    public function get_extra_classes(): array {
+        return ['pr-3'];
+    }
+}

question/bank/statistics/classes/helper.php

@@ -0,0 +1,255 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace qbank_statistics;
+
+use core_question\statistics\questions\all_calculated_for_qubaid_condition;
+use core_component;
+
+/**
+ * Helper for statistics
+ *
+ * @package    qbank_statistics
+ * @copyright  2021 Catalyst IT Australia Pty Ltd
+ * @author     Nathan Nguyen <nathannguyen@catalyst-au.net>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class helper {
+
+    /**
+     * @var float Threshold to determine 'Needs checking?'
+     */
+    private const NEED_FOR_REVISION_LOWER_THRESHOLD = 30;
+
+    /**
+     * @var float Threshold to determine 'Needs checking?'
+     */
+    private const NEED_FOR_REVISION_UPPER_THRESHOLD = 50;
+
+    /**
+     * For a list of questions find all the places, defined by (component, contextid) where there are attempts.
+     *
+     * @param int[] $questionids array of question ids that we are interested in.
+     * @return \stdClass[] list of objects with fields ->component and ->contextid.
+     * @deprecated since Moodle 4.3 please use the method from statistics_bulk_loader.
+     * @todo MDL-78090 Final deprecation in Moodle 4.7
+     */
+    private static function get_all_places_where_questions_were_attempted(array $questionids): array {
+        global $DB;
+
+        [$questionidcondition, $params] = $DB->get_in_or_equal($questionids);
+        // The MIN(qu.id) is just to ensure that the rows have a unique key.
+        $places = $DB->get_records_sql("
+                SELECT MIN(qu.id) AS somethingunique, qu.component, qu.contextid, " .
+                       \context_helper::get_preload_record_columns_sql('ctx') . "
+                  FROM {question_usages} qu
+                  JOIN {question_attempts} qa ON qa.questionusageid = qu.id
+                  JOIN {context} ctx ON ctx.id = qu.contextid
+                 WHERE qa.questionid $questionidcondition
+              GROUP BY qu.component, qu.contextid, " .
+                       implode(', ', array_keys(\context_helper::get_preload_record_columns('ctx'))) . "
+              ORDER BY qu.contextid ASC
+                ", $params);
+
+        // Strip out the unwanted ids.
+        $places = array_values($places);
+        foreach ($places as $place) {
+            unset($place->somethingunique);
+            \context_helper::preload_from_record($place);
+        }
+
+        return $places;
+    }
+
+    /**
+     * Load the question statistics for all the attempts belonging to a particular component in a particular context.
+     *
+     * @param string $component frankenstyle component name, e.g. 'mod_quiz'.
+     * @param \context $context the context to load the statistics for.
+     * @return all_calculated_for_qubaid_condition|null question statistics.
+     * @deprecated since Moodle 4.3 please use the method from statistics_bulk_loader.
+     * @todo MDL-78090 Final deprecation in Moodle 4.7
+     */
+    private static function load_statistics_for_place(string $component, \context $context): ?all_calculated_for_qubaid_condition {
+        // This check is basically if (component_exists).
+        if (empty(core_component::get_component_directory($component))) {
+            return null;
+        }
+
+        if (!component_callback_exists($component, 'calculate_question_stats')) {
+            return null;
+        }
+
+        return component_callback($component, 'calculate_question_stats', [$context]);
+    }
+
+    /**
+     * Extract the value for one question and one type of statistic from a set of statistics.
+     *
+     * @param all_calculated_for_qubaid_condition $statistics the batch of statistics.
+     * @param int $questionid a question id.
+     * @param string $item one of the field names in all_calculated_for_qubaid_condition, e.g. 'facility'.
+     * @return float|null the required value.
+     * @deprecated since Moodle 4.3 please use the method from statistics_bulk_loader.
+     * @todo MDL-78090 Final deprecation in Moodle 4.7
+     */
+    private static function extract_item_value(all_calculated_for_qubaid_condition $statistics,
+            int $questionid, string $item): ?float {
+
+        // Look in main questions.
+        foreach ($statistics->questionstats as $stats) {
+            if ($stats->questionid == $questionid && isset($stats->$item)) {
+                return $stats->$item;
+            }
+        }
+
+        // If not found, look in sub questions.
+        foreach ($statistics->subquestionstats as $stats) {
+            if ($stats->questionid == $questionid && isset($stats->$item)) {
+                return $stats->$item;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Calculate average for a stats item on a list of questions.
+     *
+     * @param int[] $questionids list of ids of the questions we are interested in.
+     * @param string $item one of the field names in all_calculated_for_qubaid_condition, e.g. 'facility'.
+     * @return array array keys are question ids and the corresponding values are the average values.
+     *      Only questions for which there are data are included.
+     * @deprecated since Moodle 4.3 please use the method from statistics_bulk_loader.
+     * @todo MDL-78090 Final deprecation in Moodle 4.7
+     */
+    private static function calculate_average_question_stats_item(array $questionids, string $item): array {
+        $places = self::get_all_places_where_questions_were_attempted($questionids);
+
+        $counts = [];
+        $sums = [];
+
+        foreach ($places as $place) {
+            $statistics = self::load_statistics_for_place($place->component,
+                    \context::instance_by_id($place->contextid));
+            if ($statistics === null) {
+                continue;
+            }
+
+            foreach ($questionids as $questionid) {
+                $value = self::extract_item_value($statistics, $questionid, $item);
+                if ($value === null) {
+                    continue;
+                }
+
+                $counts[$questionid] = ($counts[$questionid] ?? 0) + 1;
+                $sums[$questionid] = ($sums[$questionid] ?? 0) + $value;
+            }
+        }
+
+        // Return null if there is no quizzes.
+        $averages = [];
+        foreach ($sums as $questionid => $sum) {
+            $averages[$questionid] = $sum / $counts[$questionid];
+        }
+        return $averages;
+    }
+
+    /**
+     * Calculate average facility index
+     *
+     * @param int $questionid
+     * @return float|null
+     * @deprecated since Moodle 4.3 please use the method from statistics_bulk_loader.
+     * @todo MDL-78090 Final deprecation in Moodle 4.7
+     */
+    public static function calculate_average_question_facility(int $questionid): ?float {
+        debugging('Deprecated: please use statistics_bulk_loader instead, ' .
+                'or get_required_statistics_fields in your question bank column class.', DEBUG_DEVELOPER);
+        $averages = self::calculate_average_question_stats_item([$questionid], 'facility');
+        return $averages[$questionid] ?? null;
+    }
+
+    /**
+     * Calculate average discriminative efficiency
+     *
+     * @param int $questionid question id
+     * @return float|null
+     * @deprecated since Moodle 4.3 please use the method from statistics_bulk_loader.
+     * @todo MDL-78090 Final deprecation in Moodle 4.7
+     */
+    public static function calculate_average_question_discriminative_efficiency(int $questionid): ?float {
+        debugging('Deprecated: please use statistics_bulk_loader instead, ' .
+                'or get_required_statistics_fields in your question bank column class.', DEBUG_DEVELOPER);
+        $averages = self::calculate_average_question_stats_item([$questionid], 'discriminativeefficiency');
+        return $averages[$questionid] ?? null;
+    }
+
+    /**
+     * Calculate average discriminative efficiency
+     *
+     * @param int $questionid question id
+     * @return float|null
+     * @deprecated since Moodle 4.3 please use the method from statistics_bulk_loader.
+     * @todo MDL-78090 Final deprecation in Moodle 4.7
+     */
+    public static function calculate_average_question_discrimination_index(int $questionid): ?float {
+        debugging('Deprecated: please use statistics_bulk_loader instead, ' .
+                'or get_required_statistics_fields in your question bank column class.', DEBUG_DEVELOPER);
+        $averages = self::calculate_average_question_stats_item([$questionid], 'discriminationindex');
+        return $averages[$questionid] ?? null;
+    }
+
+    /**
+     * Format a number to a localised percentage with specified decimal points.
+     *
+     * @param float|null $number The number being formatted
+     * @param bool $fraction An indicator for whether the number is a fraction or is already multiplied by 100
+     * @param int $decimals Sets the number of decimal points
+     * @return string
+     * @throws \coding_exception
+     */
+    public static function format_percentage(?float $number, bool $fraction = true, int $decimals = 2): string {
+        if (is_null($number)) {
+            return get_string('na', 'qbank_statistics');
+        }
+        $coefficient = $fraction ? 100 : 1;
+        return get_string('percents', 'moodle', format_float($number * $coefficient, $decimals));
+    }
+
+    /**
+     * Format discrimination index (Needs checking?).
+     *
+     * @param float|null $value stats value
+     * @return array
+     */
+    public static function format_discrimination_index(?float $value): array {
+        if (is_null($value)) {
+            $content = get_string('emptyvalue', 'qbank_statistics');
+            $classes = '';
+        } else if ($value < self::NEED_FOR_REVISION_LOWER_THRESHOLD) {
+            $content = get_string('verylikely', 'qbank_statistics');
+            $classes = 'alert-danger';
+        } else if ($value < self::NEED_FOR_REVISION_UPPER_THRESHOLD) {
+            $content = get_string('likely', 'qbank_statistics');
+            $classes = 'alert-warning';
+        } else {
+            $content = get_string('unlikely', 'qbank_statistics');
+            $classes = 'alert-success';
+        }
+        return [$content, $classes];
+    }
+}

question/bank/statistics/classes/output/renderer.php

@@ -0,0 +1,64 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace qbank_statistics\output;
+
+use qbank_statistics\helper;
+/**
+ * Description
+ *
+ * @package    qbank_statistics
+ * @copyright  2021 Catalyst IT Australia Pty Ltd
+ * @author     Nathan Nguyen <nathannguyen@catalyst-au.net>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class renderer extends \plugin_renderer_base {
+
+    /**
+     * Render facility index column.
+     *
+     * @param float|null $facility facility index
+     * @return string
+     */
+    public function render_facility_index(?float $facility): string {
+        $displaydata['facility_index'] = helper::format_percentage($facility);
+        return $this->render_from_template('qbank_statistics/facility_index', $displaydata);
+    }
+
+    /**
+     * Render discriminative_efficiency column.
+     *
+     * @param float|null $discriminativeefficiency discriminative efficiency
+     * @return string
+     */
+    public function render_discriminative_efficiency(?float $discriminativeefficiency): string {
+        $displaydata['discriminative_efficiency'] = helper::format_percentage($discriminativeefficiency, false);
+        return $this->render_from_template('qbank_statistics/discriminative_efficiency', $displaydata);
+    }
+
+    /**
+     * Render discrimination index column.
+     *
+     * @param float|null $discriminationindex discrimination index
+     * @return string
+     */
+    public function render_discrimination_index(?float $discriminationindex): string {
+        list($content, $classes) = helper::format_discrimination_index($discriminationindex);
+        $displaydata['discrimination_index'] = $content;
+        $displaydata['classes'] = $classes;
+        return $this->render_from_template('qbank_statistics/discrimination_index', $displaydata);
+    }
+}

question/bank/statistics/classes/plugin_feature.php

@@ -0,0 +1,45 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace qbank_statistics;
+
+use qbank_statistics\columns\facility_index;
+use qbank_statistics\columns\discrimination_index;
+use qbank_statistics\columns\discriminative_efficiency;
+/**
+ * Class plugin_features is the entrypoint for the columns.
+ *
+ * @package    qbank_statistics
+ * @copyright  2021 Catalyst IT Australia Pty Ltd
+ * @author     Nathan Nguyen <nathannguyen@catalyst-au.net>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class plugin_feature extends \core_question\local\bank\plugin_features_base {
+
+    /**
+     * This method will return the array of objects to be rendered as a prt of question bank columns/actions.
+     *
+     * @param view $qbank
+     * @return array
+     */
+    public function get_question_columns($qbank): array {
+        return [
+            new discrimination_index($qbank),
+            new facility_index($qbank),
+            new discriminative_efficiency($qbank)
+        ];
+    }
+}

question/bank/statistics/classes/privacy/provider.php

@@ -0,0 +1,37 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace qbank_statistics\privacy;
+
+/**
+ * Privacy Subsystem implementation.
+ *
+ * @package    qbank_statistics
+ * @copyright  2021 Catalyst IT Australia Pty Ltd
+ * @author     Nathan Nguyen <nathannguyen@catalyst-au.net>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class provider implements \core_privacy\local\metadata\null_provider {
+
+    /**
+     * Explain why qbank_statistics store no data
+     *
+     * @return string reason why this plugin store no data
+     */
+    public static function get_reason(): string {
+        return 'privacy:metadata';
+    }
+}