MDL-64693 analytics: new course_competencies target

Added new target to predict which students are at risk of not achieving the
competencies assigned to a course.

lang/en/moodle.php

@@ -1972,12 +1972,16 @@ $string['tagmanagement'] = 'Add/delete tags ...';
 $string['tags'] = 'Tags';
 $string['target:coursecompletion'] = 'Students at risk of not meeting the course completion conditions';
 $string['target:coursecompletion_help'] = 'This target describes whether the student is considered at risk of not meeting the course completion conditions.';
+$string['target:coursecompetencies'] = 'Students at risk of not achieving the competencies assigned to a course';
+$string['target:coursecompetencies_help'] = 'This target describes whether a student is at risk of not achieving the competencies assigned to a course. This target considers that all competencies assigned to the course must be achieved by the end of the course.';
 $string['target:coursedropout'] = 'Students at risk of dropping out';
 $string['target:coursedropout_help'] = 'This target describes whether the student is considered at risk of dropping out.';
 $string['target:noteachingactivity'] = 'No teaching';
 $string['target:noteachingactivity_help'] = 'This target describes whether courses due to start in the coming week will have teaching activity.';
 $string['targetlabelstudentcompletionno'] = 'Student who is likely to meet the course completion conditions';
 $string['targetlabelstudentcompletionyes'] = 'Student at risk of not meeting the course completion conditions';
+$string['targetlabelstudentcompetenciesno'] = 'Student who is likely to achieve the competencies assigned to a course';
+$string['targetlabelstudentcompetenciesyes'] = 'Student at risk of not achieving the competencies assigned to a course';
 $string['targetlabelstudentdropoutyes'] = 'Student at risk of dropping out';
 $string['targetlabelstudentdropoutno'] = 'Not at risk';
 $string['targetlabelteachingyes'] = 'Users with teaching capabilities have access to the course';

lib/classes/analytics/target/course_competencies.php

@@ -0,0 +1,136 @@
+<?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/>.
+
+/**
+ * Course competencies achievement target.
+ *
+ * @package   core
+ * @copyright 2019 Victor Deniz <victor@moodle.com>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+namespace core\analytics\target;
+
+defined('MOODLE_INTERNAL') || die();
+
+/**
+ * Course competencies achievement target.
+ *
+ * @package   core
+ * @copyright 2019 Victor Deniz <victor@moodle.com>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class course_competencies extends \core\analytics\target\course_enrolments {
+
+    /**
+     * Number of competencies assigned per course.
+     * @var int[]
+     */
+    protected $coursecompetencies = array();
+
+    /**
+     * Count the competencies in a course.
+     *
+     * Save the value in $coursecompetencies array to prevent new accesses to the database.
+     *
+     * @param int $courseid The course id.
+     * @return int Number of competencies assigned to the course.
+     */
+    protected function get_num_competencies_in_course ($courseid) {
+
+        if (!isset($this->coursecompetencies[$courseid])) {
+            $ccs = \core_competency\api::count_competencies_in_course($courseid);
+            // Save the number of competencies per course to avoid another database access in calculate_sample().
+            $this->coursecompetencies[$courseid] = $ccs;
+        } else {
+            $ccs = $this->coursecompetencies[$courseid];
+        }
+        return $ccs;
+    }
+
+    /**
+     * Returns the name.
+     *
+     * If there is a corresponding '_help' string this will be shown as well.
+     *
+     * @return \lang_string
+     */
+    public static function get_name() : \lang_string {
+        return new \lang_string('target:coursecompetencies');
+    }
+
+    /**
+     * Returns descriptions for each of the values the target calculation can return.
+     *
+     * @return string[]
+     */
+    protected static function classes_description() {
+        return array(
+            get_string('targetlabelstudentcompetenciesno'),
+            get_string('targetlabelstudentcompetenciesyes'),
+        );
+    }
+
+    /**
+     * Discards courses that are not yet ready to be used for training or prediction.
+     *
+     * @param \core_analytics\analysable $course
+     * @param bool $fortraining
+     * @return true|string
+     */
+    public function is_valid_analysable(\core_analytics\analysable $course, $fortraining = true) {
+        $isvalid = parent::is_valid_analysable($course, $fortraining);
+
+        if (is_string($isvalid)) {
+            return $isvalid;
+        }
+
+        $ccs = $this->get_num_competencies_in_course($course->get_id());
+
+        if (!$ccs) {
+            return get_string('nocompetenciesincourse', 'tool_lp');
+        }
+
+        return true;
+    }
+
+    /**
+     * To have the proficiency or not in each of the competencies assigned to the course sets the target value.
+     *
+     * @param int $sampleid
+     * @param \core_analytics\analysable $course
+     * @param int $starttime
+     * @param int $endtime
+     * @return float 0 -> competencies achieved, 1 -> competencies not achieved
+     */
+    protected function calculate_sample($sampleid, \core_analytics\analysable $course, $starttime = false, $endtime = false) {
+
+        $userenrol = $this->retrieve('user_enrolments', $sampleid);
+
+        $key = $course->get_id();
+        // Number of competencies in the course.
+        $ccs = $this->get_num_competencies_in_course($key);
+        // Number of proficient competencies in the same course for the user.
+        $ucs = \core_competency\api::count_proficient_competencies_in_course_for_user($key, $userenrol->userid);
+
+        // If they are the equals, the user achieved all the competencies assigned to the course.
+        if ($ccs == $ucs) {
+            return 0;
+        }
+
+        return 1;
+    }
+}

lib/tests/targets_test.php

@@ -164,7 +164,7 @@ class core_analytics_targets_testcase extends advanced_testcase {
     }
 
     /**
-     * Test valid analysable conditions.
+     * Test the conditions of a valid analysable, both common and specific to this target (course_completion).
      *
      * @dataProvider analysable_provider
      * @param mixed $courseparams Course data
@@ -217,7 +217,7 @@ class core_analytics_targets_testcase extends advanced_testcase {
     }
 
     /**
-     * Test valid sample conditions.
+     * Test the conditions of a valid sample, both common and specific to this target (course_completion).
      *
      * @dataProvider sample_provider
      * @param int $coursestart Course start date
@@ -252,4 +252,93 @@ class core_analytics_targets_testcase extends advanced_testcase {
 
         $this->assertEquals($isvalid, $target->is_valid_sample($sampleid, $analysable));
     }
+
+    /**
+     * Setup user, framework, competencies and course competencies.
+     */
+    protected function setup_competencies_environment() {
+        $this->resetAfterTest(true);
+        $now = time();
+        $this->setAdminUser();
+        $dg = $this->getDataGenerator();
+        $lpg = $dg->get_plugin_generator('core_competency');
+
+        $course = $dg->create_course(array('startdate' => $now - WEEKSECS, 'enddate' => $now - DAYSECS));
+        $coursenocompetencies = $dg->create_course(array('startdate' => $now - WEEKSECS, 'enddate' => $now - DAYSECS));
+
+        $u1 = $dg->create_user();
+        $this->getDataGenerator()->enrol_user($u1->id, $course->id);
+        $this->getDataGenerator()->enrol_user($u1->id, $coursenocompetencies->id);
+        $f1 = $lpg->create_framework();
+        $c1 = $lpg->create_competency(array('competencyframeworkid' => $f1->get('id')));
+        $c2 = $lpg->create_competency(array('competencyframeworkid' => $f1->get('id')));
+        $c3 = $lpg->create_competency(array('competencyframeworkid' => $f1->get('id')));
+        $c4 = $lpg->create_competency(array('competencyframeworkid' => $f1->get('id')));
+        $cc1 = $lpg->create_course_competency(array('competencyid' => $c1->get('id'), 'courseid' => $course->id,
+            'ruleoutcome' => \core_competency\course_competency::OUTCOME_NONE));
+        $cc2 = $lpg->create_course_competency(array('competencyid' => $c2->get('id'), 'courseid' => $course->id,
+            'ruleoutcome' => \core_competency\course_competency::OUTCOME_EVIDENCE));
+        $cc3 = $lpg->create_course_competency(array('competencyid' => $c3->get('id'), 'courseid' => $course->id,
+            'ruleoutcome' => \core_competency\course_competency::OUTCOME_RECOMMEND));
+        $cc4 = $lpg->create_course_competency(array('competencyid' => $c4->get('id'), 'courseid' => $course->id,
+            'ruleoutcome' => \core_competency\course_competency::OUTCOME_COMPLETE));
+
+        return array(
+            'course' => $course,
+            'coursenocompetencies' => $coursenocompetencies,
+            'user' => $u1,
+            'course_competencies' => array($cc1, $cc2, $cc3, $cc4)
+        );
+    }
+
+     /**
+      * Test the specific conditions of a valid analysable for the course_competencies target.
+      */
+    public function test_core_target_course_competencies_analysable() {
+
+        $data = $this->setup_competencies_environment();
+
+        $analysable = new \core_analytics\course($data['course']);
+        $target = new \core\analytics\target\course_competencies();
+
+        $this->assertTrue($target->is_valid_analysable($analysable));
+
+        $analysable = new \core_analytics\course($data['coursenocompetencies']);
+        $this->assertEquals(get_string('nocompetenciesincourse', 'tool_lp'), $target->is_valid_analysable($analysable));
+    }
+
+    /**
+     * Test the target value calculation.
+     */
+    public function test_core_target_course_competencies_calculate() {
+
+        $data = $this->setup_competencies_environment();
+
+        $target = new \core\analytics\target\course_competencies();
+        $analyser = new \core\analytics\analyser\student_enrolments(1, $target, [], [], []);
+        $analysable = new \core_analytics\course($data['course']);
+
+        $class = new ReflectionClass('\core\analytics\analyser\student_enrolments');
+        $method = $class->getMethod('get_all_samples');
+        $method->setAccessible(true);
+
+        list($sampleids, $samplesdata) = $method->invoke($analyser, $analysable);
+        $target->add_sample_data($samplesdata);
+        $sampleid = reset($sampleids);
+
+        $class = new ReflectionClass('\core\analytics\target\course_competencies');
+        $method = $class->getMethod('calculate_sample');
+        $method->setAccessible(true);
+
+        // Method calculate_sample() returns 1 when the user has not achieved all the competencies assigned to the course.
+        $this->assertEquals(1, $method->invoke($target, $sampleid, $analysable));
+
+        // Grading of all the competences assigned to the course, in such way that the user achieves them all.
+        foreach ($data['course_competencies'] as $competency) {
+            \core_competency\api::grade_competency_in_course($data['course']->id, $data['user']->id,
+                    $competency->get('competencyid'), 3, 'Unit test');
+        }
+        // Method calculate_sample() returns 0 when the user has achieved all the competencies assigned to the course.
+        $this->assertEquals(0, $method->invoke($target, $sampleid, $analysable));
+    }
 }

version.php

@@ -29,7 +29,7 @@
 
 defined('MOODLE_INTERNAL') || die();
 
-$version  = 2019040200.00;              // YYYYMMDD      = weekly release date of this DEV branch.
+$version  = 2019040200.01;              // YYYYMMDD      = weekly release date of this DEV branch.
                                         //         RR    = release increments - 00 in DEV branches.
                                         //           .XX = incremental changes.