MDL-64693 analytics: new course_competencies target
[moodle.git] / lib / classes / analytics / target / course_competencies.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  * Course competencies achievement target.
19  *
20  * @package   core
21  * @copyright 2019 Victor Deniz <victor@moodle.com>
22  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 namespace core\analytics\target;
27 defined('MOODLE_INTERNAL') || die();
29 /**
30  * Course competencies achievement target.
31  *
32  * @package   core
33  * @copyright 2019 Victor Deniz <victor@moodle.com>
34  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
35  */
36 class course_competencies extends \core\analytics\target\course_enrolments {
38     /**
39      * Number of competencies assigned per course.
40      * @var int[]
41      */
42     protected $coursecompetencies = array();
44     /**
45      * Count the competencies in a course.
46      *
47      * Save the value in $coursecompetencies array to prevent new accesses to the database.
48      *
49      * @param int $courseid The course id.
50      * @return int Number of competencies assigned to the course.
51      */
52     protected function get_num_competencies_in_course ($courseid) {
54         if (!isset($this->coursecompetencies[$courseid])) {
55             $ccs = \core_competency\api::count_competencies_in_course($courseid);
56             // Save the number of competencies per course to avoid another database access in calculate_sample().
57             $this->coursecompetencies[$courseid] = $ccs;
58         } else {
59             $ccs = $this->coursecompetencies[$courseid];
60         }
61         return $ccs;
62     }
64     /**
65      * Returns the name.
66      *
67      * If there is a corresponding '_help' string this will be shown as well.
68      *
69      * @return \lang_string
70      */
71     public static function get_name() : \lang_string {
72         return new \lang_string('target:coursecompetencies');
73     }
75     /**
76      * Returns descriptions for each of the values the target calculation can return.
77      *
78      * @return string[]
79      */
80     protected static function classes_description() {
81         return array(
82             get_string('targetlabelstudentcompetenciesno'),
83             get_string('targetlabelstudentcompetenciesyes'),
84         );
85     }
87     /**
88      * Discards courses that are not yet ready to be used for training or prediction.
89      *
90      * @param \core_analytics\analysable $course
91      * @param bool $fortraining
92      * @return true|string
93      */
94     public function is_valid_analysable(\core_analytics\analysable $course, $fortraining = true) {
95         $isvalid = parent::is_valid_analysable($course, $fortraining);
97         if (is_string($isvalid)) {
98             return $isvalid;
99         }
101         $ccs = $this->get_num_competencies_in_course($course->get_id());
103         if (!$ccs) {
104             return get_string('nocompetenciesincourse', 'tool_lp');
105         }
107         return true;
108     }
110     /**
111      * To have the proficiency or not in each of the competencies assigned to the course sets the target value.
112      *
113      * @param int $sampleid
114      * @param \core_analytics\analysable $course
115      * @param int $starttime
116      * @param int $endtime
117      * @return float 0 -> competencies achieved, 1 -> competencies not achieved
118      */
119     protected function calculate_sample($sampleid, \core_analytics\analysable $course, $starttime = false, $endtime = false) {
121         $userenrol = $this->retrieve('user_enrolments', $sampleid);
123         $key = $course->get_id();
124         // Number of competencies in the course.
125         $ccs = $this->get_num_competencies_in_course($key);
126         // Number of proficient competencies in the same course for the user.
127         $ucs = \core_competency\api::count_proficient_competencies_in_course_for_user($key, $userenrol->userid);
129         // If they are the equals, the user achieved all the competencies assigned to the course.
130         if ($ccs == $ucs) {
131             return 0;
132         }
134         return 1;
135     }