f95768d5f14646de852befe6301e328d3b7e410d
[moodle.git] / analytics / classes / manager.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  * Analytics basic actions manager.
19  *
20  * @package   core_analytics
21  * @copyright 2017 David Monllao {@link http://www.davidmonllao.com}
22  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 namespace core_analytics;
27 defined('MOODLE_INTERNAL') || die();
29 /**
30  * Analytics basic actions manager.
31  *
32  * @package   core_analytics
33  * @copyright 2017 David Monllao {@link http://www.davidmonllao.com}
34  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
35  */
36 class manager {
38     /**
39      * @var \core_analytics\predictor[]
40      */
41     protected static $predictionprocessors = null;
43     /**
44      * @var \core_analytics\local\indicator\base[]
45      */
46     protected static $allindicators = null;
48     /**
49      * @var \core_analytics\local\time_splitting\base[]
50      */
51     protected static $alltimesplittings = null;
53     /**
54      * Checks that the user can manage models
55      *
56      * @throws \required_capability_exception
57      * @return void
58      */
59     public static function check_can_manage_models() {
60         require_capability('moodle/analytics:managemodels', \context_system::instance());
61     }
63     /**
64      * Checks that the user can list that context insights
65      *
66      * @throws \required_capability_exception
67      * @param \context $context
68      * @return void
69      */
70     public static function check_can_list_insights(\context $context) {
71         require_capability('moodle/analytics:listinsights', $context);
72     }
74     /**
75      * Returns all system models that match the provided filters.
76      *
77      * @param bool $enabled
78      * @param bool $trained
79      * @param \context|false $predictioncontext
80      * @return \core_analytics\model[]
81      */
82     public static function get_all_models($enabled = false, $trained = false, $predictioncontext = false) {
83         global $DB;
85         $params = array();
87         $sql = "SELECT DISTINCT am.* FROM {analytics_models} am";
88         if ($predictioncontext) {
89             $sql .= " JOIN {analytics_predictions} ap ON ap.modelid = am.id AND ap.contextid = :contextid";
90             $params['contextid'] = $predictioncontext->id;
91         }
93         if ($enabled || $trained) {
94             $conditions = [];
95             if ($enabled) {
96                 $conditions[] = 'am.enabled = :enabled';
97                 $params['enabled'] = 1;
98             }
99             if ($trained) {
100                 $conditions[] = 'am.trained = :trained';
101                 $params['trained'] = 1;
102             }
103             $sql .= ' WHERE ' . implode(' AND ', $conditions);
104         }
105         $sql .= ' ORDER BY am.enabled DESC, am.timemodified DESC';
107         $modelobjs = $DB->get_records_sql($sql, $params);
109         $models = array();
110         foreach ($modelobjs as $modelobj) {
111             $model = new \core_analytics\model($modelobj);
112             if ($model->is_available()) {
113                 $models[$modelobj->id] = $model;
114             }
115         }
116         return $models;
117     }
119     /**
120      * Returns the site selected predictions processor.
121      *
122      * @param string $predictionclass
123      * @param bool $checkisready
124      * @return \core_analytics\predictor
125      */
126     public static function get_predictions_processor($predictionclass = false, $checkisready = true) {
128         // We want 0 or 1 so we can use it as an array key for caching.
129         $checkisready = intval($checkisready);
131         if ($predictionclass === false) {
132             $predictionclass = get_config('analytics', 'predictionsprocessor');
133         }
135         if (empty($predictionclass)) {
136             // Use the default one if nothing set.
137             $predictionclass = '\mlbackend_php\processor';
138         }
140         if (!class_exists($predictionclass)) {
141             throw new \coding_exception('Invalid predictions processor ' . $predictionclass . '.');
142         }
144         $interfaces = class_implements($predictionclass);
145         if (empty($interfaces['core_analytics\predictor'])) {
146             throw new \coding_exception($predictionclass . ' should implement \core_analytics\predictor.');
147         }
149         // Return it from the cached list.
150         if (!isset(self::$predictionprocessors[$checkisready][$predictionclass])) {
152             $instance = new $predictionclass();
153             if ($checkisready) {
154                 $isready = $instance->is_ready();
155                 if ($isready !== true) {
156                     throw new \moodle_exception('errorprocessornotready', 'analytics', '', $isready);
157                 }
158             }
159             self::$predictionprocessors[$checkisready][$predictionclass] = $instance;
160         }
162         return self::$predictionprocessors[$checkisready][$predictionclass];
163     }
165     /**
166      * Return all system predictions processors.
167      *
168      * @return \core_analytics\predictor[]
169      */
170     public static function get_all_prediction_processors() {
172         $mlbackends = \core_component::get_plugin_list('mlbackend');
174         $predictionprocessors = array();
175         foreach ($mlbackends as $mlbackend => $unused) {
176             $classfullpath = '\mlbackend_' . $mlbackend . '\processor';
177             $predictionprocessors[$classfullpath] = self::get_predictions_processor($classfullpath, false);
178         }
179         return $predictionprocessors;
180     }
182     /**
183      * Get all available time splitting methods.
184      *
185      * @return \core_analytics\local\time_splitting\base[]
186      */
187     public static function get_all_time_splittings() {
188         if (self::$alltimesplittings !== null) {
189             return self::$alltimesplittings;
190         }
192         $classes = self::get_analytics_classes('time_splitting');
194         self::$alltimesplittings = [];
195         foreach ($classes as $fullclassname => $classpath) {
196             $instance = self::get_time_splitting($fullclassname);
197             // We need to check that it is a valid time splitting method, it may be an abstract class.
198             if ($instance) {
199                 self::$alltimesplittings[$instance->get_id()] = $instance;
200             }
201         }
203         return self::$alltimesplittings;
204     }
206     /**
207      * Returns the enabled time splitting methods.
208      *
209      * @return \core_analytics\local\time_splitting\base[]
210      */
211     public static function get_enabled_time_splitting_methods() {
213         if ($enabledtimesplittings = get_config('analytics', 'timesplittings')) {
214             $enabledtimesplittings = array_flip(explode(',', $enabledtimesplittings));
215         }
217         $timesplittings = self::get_all_time_splittings();
218         foreach ($timesplittings as $key => $timesplitting) {
220             // We remove the ones that are not enabled. This also respects the default value (all methods enabled).
221             if (!empty($enabledtimesplittings) && !isset($enabledtimesplittings[$key])) {
222                 unset($timesplittings[$key]);
223             }
224         }
225         return $timesplittings;
226     }
228     /**
229      * Returns a time splitting method by its classname.
230      *
231      * @param string $fullclassname
232      * @return \core_analytics\local\time_splitting\base|false False if it is not valid.
233      */
234     public static function get_time_splitting($fullclassname) {
235         if (!self::is_valid($fullclassname, '\core_analytics\local\time_splitting\base')) {
236             return false;
237         }
238         return new $fullclassname();
239     }
241     /**
242      * Return all system indicators.
243      *
244      * @return \core_analytics\local\indicator\base[]
245      */
246     public static function get_all_indicators() {
247         if (self::$allindicators !== null) {
248             return self::$allindicators;
249         }
251         $classes = self::get_analytics_classes('indicator');
253         self::$allindicators = [];
254         foreach ($classes as $fullclassname => $classpath) {
255             $instance = self::get_indicator($fullclassname);
256             if ($instance) {
257                 // Using get_class as get_component_classes_in_namespace returns double escaped fully qualified class names.
258                 self::$allindicators[$instance->get_id()] = $instance;
259             }
260         }
262         return self::$allindicators;
263     }
265     /**
266      * Returns the specified target
267      *
268      * @param mixed $fullclassname
269      * @return \core_analytics\local\target\base|false False if it is not valid
270      */
271     public static function get_target($fullclassname) {
272         if (!self::is_valid($fullclassname, 'core_analytics\local\target\base')) {
273             return false;
274         }
275         return new $fullclassname();
276     }
278     /**
279      * Returns an instance of the provided indicator.
280      *
281      * @param string $fullclassname
282      * @return \core_analytics\local\indicator\base|false False if it is not valid.
283      */
284     public static function get_indicator($fullclassname) {
285         if (!self::is_valid($fullclassname, 'core_analytics\local\indicator\base')) {
286             return false;
287         }
288         return new $fullclassname();
289     }
291     /**
292      * Returns whether a time splitting method is valid or not.
293      *
294      * @param string $fullclassname
295      * @param string $baseclass
296      * @return bool
297      */
298     public static function is_valid($fullclassname, $baseclass) {
299         if (is_subclass_of($fullclassname, $baseclass)) {
300             if ((new \ReflectionClass($fullclassname))->isInstantiable()) {
301                 return true;
302             }
303         }
304         return false;
305     }
307     /**
308      * Returns the logstore used for analytics.
309      *
310      * @return \core\log\sql_reader|false False if no log stores are enabled.
311      */
312     public static function get_analytics_logstore() {
313         $readers = get_log_manager()->get_readers('core\log\sql_reader');
314         $analyticsstore = get_config('analytics', 'logstore');
315         if (empty($analyticsstore)) {
316             $logstore = reset($readers);
317         } else if (!empty($readers[$analyticsstore])) {
318             $logstore = $readers[$analyticsstore];
319         } else if (!empty($readers)) {
320             $logstore = reset($readers);
321             debugging('The selected log store for analytics is not available anymore. Using "' .
322                 $logstore->get_name() . '"', DEBUG_DEVELOPER);
323         }
325         if (empty($logstore)) {
326             debugging('No system log stores available to use for analytics', DEBUG_DEVELOPER);
327             return false;
328         }
330         if (!$logstore->is_logging()) {
331             debugging('The selected log store for analytics "' . $logstore->get_name() .
332                 '" is not logging activity logs', DEBUG_DEVELOPER);
333         }
335         return $logstore;
336     }
338     /**
339      * Returns the models with insights at the provided context.
340      *
341      * @param \context $context
342      * @return \core_analytics\model[]
343      */
344     public static function get_models_with_insights(\context $context) {
346         self::check_can_list_insights($context);
348         $models = self::get_all_models(true, true, $context);
349         foreach ($models as $key => $model) {
350             // Check that it not only have predictions but also generates insights from them.
351             if (!$model->uses_insights()) {
352                 unset($models[$key]);
353             }
354         }
355         return $models;
356     }
358     /**
359      * Returns a prediction
360      *
361      * @param int $predictionid
362      * @param bool $requirelogin
363      * @return array array($model, $prediction, $context)
364      */
365     public static function get_prediction($predictionid, $requirelogin = false) {
366         global $DB;
368         if (!$predictionobj = $DB->get_record('analytics_predictions', array('id' => $predictionid))) {
369             throw new \moodle_exception('errorpredictionnotfound', 'report_insights');
370         }
372         if ($requirelogin) {
373             list($context, $course, $cm) = get_context_info_array($predictionobj->contextid);
374             require_login($course, false, $cm);
375         } else {
376             $context = \context::instance_by_id($predictionobj->contextid);
377         }
379         self::check_can_list_insights($context);
381         $model = new \core_analytics\model($predictionobj->modelid);
382         $sampledata = $model->prediction_sample_data($predictionobj);
383         $prediction = new \core_analytics\prediction($predictionobj, $sampledata);
385         return array($model, $prediction, $context);
386     }
388     /**
389      * Adds the models included with moodle core to the system.
390      *
391      * @return void
392      */
393     public static function add_builtin_models() {
395         $target = self::get_target('\core\analytics\target\course_dropout');
397         // Community of inquiry indicators.
398         $coiindicators = array(
399             '\mod_assign\analytics\indicator\cognitive_depth',
400             '\mod_assign\analytics\indicator\social_breadth',
401             '\mod_book\analytics\indicator\cognitive_depth',
402             '\mod_book\analytics\indicator\social_breadth',
403             '\mod_chat\analytics\indicator\cognitive_depth',
404             '\mod_chat\analytics\indicator\social_breadth',
405             '\mod_choice\analytics\indicator\cognitive_depth',
406             '\mod_choice\analytics\indicator\social_breadth',
407             '\mod_data\analytics\indicator\cognitive_depth',
408             '\mod_data\analytics\indicator\social_breadth',
409             '\mod_feedback\analytics\indicator\cognitive_depth',
410             '\mod_feedback\analytics\indicator\social_breadth',
411             '\mod_folder\analytics\indicator\cognitive_depth',
412             '\mod_folder\analytics\indicator\social_breadth',
413             '\mod_forum\analytics\indicator\cognitive_depth',
414             '\mod_forum\analytics\indicator\social_breadth',
415             '\mod_glossary\analytics\indicator\cognitive_depth',
416             '\mod_glossary\analytics\indicator\social_breadth',
417             '\mod_imscp\analytics\indicator\cognitive_depth',
418             '\mod_imscp\analytics\indicator\social_breadth',
419             '\mod_label\analytics\indicator\cognitive_depth',
420             '\mod_label\analytics\indicator\social_breadth',
421             '\mod_lesson\analytics\indicator\cognitive_depth',
422             '\mod_lesson\analytics\indicator\social_breadth',
423             '\mod_lti\analytics\indicator\cognitive_depth',
424             '\mod_lti\analytics\indicator\social_breadth',
425             '\mod_page\analytics\indicator\cognitive_depth',
426             '\mod_page\analytics\indicator\social_breadth',
427             '\mod_quiz\analytics\indicator\cognitive_depth',
428             '\mod_quiz\analytics\indicator\social_breadth',
429             '\mod_resource\analytics\indicator\cognitive_depth',
430             '\mod_resource\analytics\indicator\social_breadth',
431             '\mod_scorm\analytics\indicator\cognitive_depth',
432             '\mod_scorm\analytics\indicator\social_breadth',
433             '\mod_survey\analytics\indicator\cognitive_depth',
434             '\mod_survey\analytics\indicator\social_breadth',
435             '\mod_url\analytics\indicator\cognitive_depth',
436             '\mod_url\analytics\indicator\social_breadth',
437             '\mod_wiki\analytics\indicator\cognitive_depth',
438             '\mod_wiki\analytics\indicator\social_breadth',
439             '\mod_workshop\analytics\indicator\cognitive_depth',
440             '\mod_workshop\analytics\indicator\social_breadth',
441         );
442         $indicators = array();
443         foreach ($coiindicators as $coiindicator) {
444             $indicator = self::get_indicator($coiindicator);
445             $indicators[$indicator->get_id()] = $indicator;
446         }
447         if (!\core_analytics\model::exists($target, $indicators)) {
448             $model = \core_analytics\model::create($target, $indicators);
449         }
451         // No teaching model.
452         $target = self::get_target('\core\analytics\target\no_teaching');
453         $timesplittingmethod = '\core\analytics\time_splitting\single_range';
454         $noteacher = self::get_indicator('\core_course\analytics\indicator\no_teacher');
455         $indicators = array($noteacher->get_id() => $noteacher);
456         if (!\core_analytics\model::exists($target, $indicators)) {
457             \core_analytics\model::create($target, $indicators, $timesplittingmethod);
458         }
459     }
461     /**
462      * Returns the provided element classes in the site.
463      *
464      * @param string $element
465      * @return string[] Array keys are the FQCN and the values the class path.
466      */
467     private static function get_analytics_classes($element) {
469         // Just in case...
470         $element = clean_param($element, PARAM_ALPHANUMEXT);
472         // Core analytics classes (analytics subsystem should not contain uses of the analytics API).
473         $classes = \core_component::get_component_classes_in_namespace('core', 'analytics\\' . $element);
475         // Plugins.
476         foreach (\core_component::get_plugin_types() as $type => $unusedplugintypepath) {
477             foreach (\core_component::get_plugin_list($type) as $pluginname => $unusedpluginpath) {
478                 $frankenstyle = $type . '_' . $pluginname;
479                 $classes += \core_component::get_component_classes_in_namespace($frankenstyle, 'analytics\\' . $element);
480             }
481         }
483         // Core subsystems.
484         foreach (\core_component::get_core_subsystems() as $subsystemname => $unusedsubsystempath) {
485             $componentname = 'core_' . $subsystemname;
486             $classes += \core_component::get_component_classes_in_namespace($componentname, 'analytics\\' . $element);
487         }
489         return $classes;
490     }