Merge branch 'MDL-70037' of git://github.com/paulholden/moodle
[moodle.git] / analytics / classes / manager.php
CommitLineData
369389c9
DM
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/>.
16
17/**
b94dbb55 18 * Analytics basic actions manager.
369389c9
DM
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 */
24
25namespace core_analytics;
26
27defined('MOODLE_INTERNAL') || die();
28
29/**
b94dbb55 30 * Analytics basic actions manager.
369389c9
DM
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 */
36class manager {
37
ed12ba6b
DM
38 /**
39 * Default mlbackend
40 */
41 const DEFAULT_MLBACKEND = '\mlbackend_php\processor';
42
f0584045
DM
43 /**
44 * Name of the file where components declare their models.
45 */
46 const ANALYTICS_FILENAME = 'db/analytics.php';
47
369389c9
DM
48 /**
49 * @var \core_analytics\predictor[]
50 */
aa5b7056 51 protected static $predictionprocessors = [];
369389c9 52
e4453adc
DM
53 /**
54 * @var \core_analytics\local\target\base[]
55 */
56 protected static $alltargets = null;
57
369389c9
DM
58 /**
59 * @var \core_analytics\local\indicator\base[]
60 */
61 protected static $allindicators = null;
62
63 /**
64 * @var \core_analytics\local\time_splitting\base[]
65 */
66 protected static $alltimesplittings = null;
67
1611308b
DM
68 /**
69 * Checks that the user can manage models
70 *
71 * @throws \required_capability_exception
72 * @return void
73 */
74 public static function check_can_manage_models() {
75 require_capability('moodle/analytics:managemodels', \context_system::instance());
76 }
77
78 /**
79 * Checks that the user can list that context insights
80 *
81 * @throws \required_capability_exception
82 * @param \context $context
50935afb 83 * @param bool $return The method returns a bool if true.
1611308b
DM
84 * @return void
85 */
50935afb
DM
86 public static function check_can_list_insights(\context $context, bool $return = false) {
87 global $USER;
88
89 if ($context->contextlevel === CONTEXT_USER && $context->instanceid == $USER->id) {
90 $capability = 'moodle/analytics:listowninsights';
91 } else {
92 $capability = 'moodle/analytics:listinsights';
93 }
94
95 if ($return) {
96 return has_capability($capability, $context);
97 } else {
98 require_capability($capability, $context);
99 }
1611308b
DM
100 }
101
bf25fb16
DM
102 /**
103 * Is analytics enabled globally?
104 *
105 * return bool
106 */
107 public static function is_analytics_enabled(): bool {
108 global $CFG;
109
110 if (isset($CFG->enableanalytics)) {
111 return $CFG->enableanalytics;
112 }
113
114 // Enabled by default.
115 return true;
116 }
117
584ffa4f
DM
118 /**
119 * Returns all system models that match the provided filters.
120 *
121 * @param bool $enabled
122 * @param bool $trained
08015e18 123 * @param \context|false $predictioncontext
584ffa4f
DM
124 * @return \core_analytics\model[]
125 */
369389c9
DM
126 public static function get_all_models($enabled = false, $trained = false, $predictioncontext = false) {
127 global $DB;
128
1611308b
DM
129 $params = array();
130
88777c57 131 $sql = "SELECT am.* FROM {analytics_models} am";
1611308b 132
88777c57 133 if ($enabled || $trained || $predictioncontext) {
1611308b
DM
134 $conditions = [];
135 if ($enabled) {
136 $conditions[] = 'am.enabled = :enabled';
137 $params['enabled'] = 1;
138 }
139 if ($trained) {
140 $conditions[] = 'am.trained = :trained';
141 $params['trained'] = 1;
142 }
88777c57 143 if ($predictioncontext) {
d887b0c7
DM
144 $conditions[] = "EXISTS (SELECT 'x'
145 FROM {analytics_predictions} ap
146 WHERE ap.modelid = am.id AND ap.contextid = :contextid)";
88777c57
DM
147 $params['contextid'] = $predictioncontext->id;
148 }
e10b29ed 149 $sql .= ' WHERE ' . implode(' AND ', $conditions);
369389c9 150 }
e10b29ed
DM
151 $sql .= ' ORDER BY am.enabled DESC, am.timemodified DESC';
152
1611308b 153 $modelobjs = $DB->get_records_sql($sql, $params);
369389c9
DM
154
155 $models = array();
156 foreach ($modelobjs as $modelobj) {
3a396286
DM
157 $model = new \core_analytics\model($modelobj);
158 if ($model->is_available()) {
159 $models[$modelobj->id] = $model;
160 }
369389c9 161 }
35b10d09
DM
162
163 // Sort the models by the model name using the current session language.
164 \core_collator::asort_objects_by_method($models, 'get_name');
165
369389c9
DM
166 return $models;
167 }
168
169 /**
ed12ba6b 170 * Returns the provided predictions processor class.
369389c9 171 *
ed12ba6b 172 * @param false|string $predictionclass Returns the system default processor if false
369389c9
DM
173 * @param bool $checkisready
174 * @return \core_analytics\predictor
175 */
176 public static function get_predictions_processor($predictionclass = false, $checkisready = true) {
177
178 // We want 0 or 1 so we can use it as an array key for caching.
179 $checkisready = intval($checkisready);
180
ed12ba6b 181 if (!$predictionclass) {
369389c9
DM
182 $predictionclass = get_config('analytics', 'predictionsprocessor');
183 }
184
185 if (empty($predictionclass)) {
186 // Use the default one if nothing set.
ed12ba6b 187 $predictionclass = self::default_mlbackend();
369389c9
DM
188 }
189
190 if (!class_exists($predictionclass)) {
191 throw new \coding_exception('Invalid predictions processor ' . $predictionclass . '.');
192 }
193
194 $interfaces = class_implements($predictionclass);
195 if (empty($interfaces['core_analytics\predictor'])) {
196 throw new \coding_exception($predictionclass . ' should implement \core_analytics\predictor.');
197 }
198
199 // Return it from the cached list.
200 if (!isset(self::$predictionprocessors[$checkisready][$predictionclass])) {
201
202 $instance = new $predictionclass();
203 if ($checkisready) {
204 $isready = $instance->is_ready();
205 if ($isready !== true) {
206 throw new \moodle_exception('errorprocessornotready', 'analytics', '', $isready);
207 }
208 }
209 self::$predictionprocessors[$checkisready][$predictionclass] = $instance;
210 }
211
212 return self::$predictionprocessors[$checkisready][$predictionclass];
213 }
214
1611308b
DM
215 /**
216 * Return all system predictions processors.
217 *
08015e18 218 * @return \core_analytics\predictor[]
1611308b 219 */
369389c9
DM
220 public static function get_all_prediction_processors() {
221
222 $mlbackends = \core_component::get_plugin_list('mlbackend');
223
224 $predictionprocessors = array();
225 foreach ($mlbackends as $mlbackend => $unused) {
206d7aa9 226 $classfullpath = '\mlbackend_' . $mlbackend . '\processor';
369389c9
DM
227 $predictionprocessors[$classfullpath] = self::get_predictions_processor($classfullpath, false);
228 }
229 return $predictionprocessors;
230 }
231
aa5b7056
DM
232 /**
233 * Resets the cached prediction processors.
234 * @return null
235 */
236 public static function reset_prediction_processors() {
237 self::$predictionprocessors = [];
238 }
239
ed12ba6b
DM
240 /**
241 * Returns the name of the provided predictions processor.
242 *
243 * @param \core_analytics\predictor $predictionsprocessor
244 * @return string
245 */
246 public static function get_predictions_processor_name(\core_analytics\predictor $predictionsprocessor) {
247 $component = substr(get_class($predictionsprocessor), 0, strpos(get_class($predictionsprocessor), '\\', 1));
248 return get_string('pluginname', $component);
249 }
250
251 /**
252 * Whether the provided plugin is used by any model.
253 *
254 * @param string $plugin
255 * @return bool
256 */
257 public static function is_mlbackend_used($plugin) {
258 $models = self::get_all_models();
259 foreach ($models as $model) {
260 $processor = $model->get_predictions_processor();
261 $noprefixnamespace = ltrim(get_class($processor), '\\');
262 $processorplugin = substr($noprefixnamespace, 0, strpos($noprefixnamespace, '\\'));
263 if ($processorplugin == $plugin) {
264 return true;
265 }
266 }
267
268 // Default predictions processor.
269 $defaultprocessorclass = get_config('analytics', 'predictionsprocessor');
270 $pluginclass = '\\' . $plugin . '\\processor';
271 if ($pluginclass === $defaultprocessorclass) {
272 return true;
273 }
274
275 return false;
276 }
277
369389c9
DM
278 /**
279 * Get all available time splitting methods.
280 *
1cc2b4ba 281 * @return \core_analytics\local\time_splitting\base[]
369389c9
DM
282 */
283 public static function get_all_time_splittings() {
284 if (self::$alltimesplittings !== null) {
285 return self::$alltimesplittings;
286 }
287
288 $classes = self::get_analytics_classes('time_splitting');
289
290 self::$alltimesplittings = [];
291 foreach ($classes as $fullclassname => $classpath) {
292 $instance = self::get_time_splitting($fullclassname);
293 // We need to check that it is a valid time splitting method, it may be an abstract class.
294 if ($instance) {
295 self::$alltimesplittings[$instance->get_id()] = $instance;
296 }
297 }
298
299 return self::$alltimesplittings;
300 }
301
302 /**
303 * Returns the enabled time splitting methods.
304 *
3576b66b 305 * @deprecated since Moodle 3.7
74ee34fd 306 * @todo MDL-65086 This will be deleted in Moodle 3.11
3576b66b 307 * @see \core_analytics\manager::get_time_splitting_methods_for_evaluation
369389c9
DM
308 * @return \core_analytics\local\time_splitting\base[]
309 */
310 public static function get_enabled_time_splitting_methods() {
3576b66b
DM
311 debugging('This function has been deprecated. You can use self::get_time_splitting_methods_for_evaluation if ' .
312 'you want to get the default time splitting methods for evaluation, or you can use self::get_all_time_splittings if ' .
313 'you want to get all the time splitting methods available on this site.');
314 return self::get_time_splitting_methods_for_evaluation();
315 }
316
317 /**
5f1f0ee6 318 * Returns the time-splitting methods for model evaluation.
3576b66b 319 *
5f1f0ee6 320 * @param bool $all Return all the time-splitting methods that can potentially be used for evaluation or the default ones.
3576b66b
DM
321 * @return \core_analytics\local\time_splitting\base[]
322 */
5f1f0ee6 323 public static function get_time_splitting_methods_for_evaluation(bool $all = false) {
369389c9 324
5f1f0ee6
DM
325 if ($all === false) {
326 if ($enabledtimesplittings = get_config('analytics', 'defaulttimesplittingsevaluation')) {
327 $enabledtimesplittings = array_flip(explode(',', $enabledtimesplittings));
328 }
369389c9
DM
329 }
330
331 $timesplittings = self::get_all_time_splittings();
332 foreach ($timesplittings as $key => $timesplitting) {
333
5f1f0ee6 334 if (!$timesplitting->valid_for_evaluation()) {
369389c9
DM
335 unset($timesplittings[$key]);
336 }
5f1f0ee6
DM
337
338 if ($all === false) {
339 // We remove the ones that are not enabled. This also respects the default value (all methods enabled).
340 if (!empty($enabledtimesplittings) && !isset($enabledtimesplittings[$key])) {
341 unset($timesplittings[$key]);
342 }
343 }
369389c9
DM
344 }
345 return $timesplittings;
346 }
347
348 /**
349 * Returns a time splitting method by its classname.
350 *
351 * @param string $fullclassname
352 * @return \core_analytics\local\time_splitting\base|false False if it is not valid.
353 */
354 public static function get_time_splitting($fullclassname) {
355 if (!self::is_valid($fullclassname, '\core_analytics\local\time_splitting\base')) {
356 return false;
357 }
358 return new $fullclassname();
359 }
360
e4453adc
DM
361 /**
362 * Return all targets in the system.
363 *
364 * @return \core_analytics\local\target\base[]
365 */
366 public static function get_all_targets() : array {
367 if (self::$alltargets !== null) {
368 return self::$alltargets;
369 }
370
371 $classes = self::get_analytics_classes('target');
372
373 self::$alltargets = [];
374 foreach ($classes as $fullclassname => $classpath) {
375 $instance = self::get_target($fullclassname);
376 if ($instance) {
377 self::$alltargets[$instance->get_id()] = $instance;
378 }
379 }
380
381 return self::$alltargets;
382 }
369389c9
DM
383 /**
384 * Return all system indicators.
385 *
386 * @return \core_analytics\local\indicator\base[]
387 */
388 public static function get_all_indicators() {
389 if (self::$allindicators !== null) {
390 return self::$allindicators;
391 }
392
393 $classes = self::get_analytics_classes('indicator');
394
395 self::$allindicators = [];
396 foreach ($classes as $fullclassname => $classpath) {
397 $instance = self::get_indicator($fullclassname);
398 if ($instance) {
b0c24929 399 self::$allindicators[$instance->get_id()] = $instance;
369389c9
DM
400 }
401 }
402
403 return self::$allindicators;
404 }
405
1611308b
DM
406 /**
407 * Returns the specified target
408 *
409 * @param mixed $fullclassname
410 * @return \core_analytics\local\target\base|false False if it is not valid
411 */
369389c9
DM
412 public static function get_target($fullclassname) {
413 if (!self::is_valid($fullclassname, 'core_analytics\local\target\base')) {
414 return false;
415 }
416 return new $fullclassname();
417 }
418
419 /**
420 * Returns an instance of the provided indicator.
421 *
422 * @param string $fullclassname
423 * @return \core_analytics\local\indicator\base|false False if it is not valid.
424 */
425 public static function get_indicator($fullclassname) {
426 if (!self::is_valid($fullclassname, 'core_analytics\local\indicator\base')) {
427 return false;
428 }
429 return new $fullclassname();
430 }
431
432 /**
433 * Returns whether a time splitting method is valid or not.
434 *
435 * @param string $fullclassname
1611308b 436 * @param string $baseclass
369389c9
DM
437 * @return bool
438 */
439 public static function is_valid($fullclassname, $baseclass) {
440 if (is_subclass_of($fullclassname, $baseclass)) {
441 if ((new \ReflectionClass($fullclassname))->isInstantiable()) {
442 return true;
443 }
444 }
445 return false;
446 }
447
f67f35f3 448 /**
1611308b 449 * Returns the logstore used for analytics.
f67f35f3 450 *
2db6e981 451 * @return \core\log\sql_reader|false False if no log stores are enabled.
f67f35f3
DM
452 */
453 public static function get_analytics_logstore() {
454 $readers = get_log_manager()->get_readers('core\log\sql_reader');
455 $analyticsstore = get_config('analytics', 'logstore');
85e50ba4
DM
456
457 if (!empty($analyticsstore) && !empty($readers[$analyticsstore])) {
f67f35f3 458 $logstore = $readers[$analyticsstore];
85e50ba4
DM
459 } else if (empty($analyticsstore) && !empty($readers)) {
460 // The first one, it is the same default than in settings.
461 $logstore = reset($readers);
2db6e981 462 } else if (!empty($readers)) {
f67f35f3
DM
463 $logstore = reset($readers);
464 debugging('The selected log store for analytics is not available anymore. Using "' .
465 $logstore->get_name() . '"', DEBUG_DEVELOPER);
466 }
467
2db6e981
DM
468 if (empty($logstore)) {
469 debugging('No system log stores available to use for analytics', DEBUG_DEVELOPER);
470 return false;
471 }
472
f67f35f3
DM
473 if (!$logstore->is_logging()) {
474 debugging('The selected log store for analytics "' . $logstore->get_name() .
475 '" is not logging activity logs', DEBUG_DEVELOPER);
476 }
477
478 return $logstore;
479 }
480
0690a271
DM
481 /**
482 * Returns this analysable calculations during the provided period.
483 *
484 * @param \core_analytics\analysable $analysable
485 * @param int $starttime
486 * @param int $endtime
487 * @param string $samplesorigin The samples origin as sampleid is not unique across models.
488 * @return array
489 */
490 public static function get_indicator_calculations($analysable, $starttime, $endtime, $samplesorigin) {
491 global $DB;
492
493 $params = array('starttime' => $starttime, 'endtime' => $endtime, 'contextid' => $analysable->get_context()->id,
494 'sampleorigin' => $samplesorigin);
495 $calculations = $DB->get_recordset('analytics_indicator_calc', $params, '', 'indicator, sampleid, value');
496
497 $existingcalculations = array();
498 foreach ($calculations as $calculation) {
499 if (empty($existingcalculations[$calculation->indicator])) {
500 $existingcalculations[$calculation->indicator] = array();
501 }
502 $existingcalculations[$calculation->indicator][$calculation->sampleid] = $calculation->value;
503 }
a938e409 504 $calculations->close();
0690a271
DM
505 return $existingcalculations;
506 }
507
1611308b
DM
508 /**
509 * Returns the models with insights at the provided context.
510 *
486e797c
DM
511 * Note that this method is used for display purposes. It filters out models whose insights
512 * are not linked from the reports page.
513 *
1611308b
DM
514 * @param \context $context
515 * @return \core_analytics\model[]
516 */
517 public static function get_models_with_insights(\context $context) {
518
519 self::check_can_list_insights($context);
520
413f19bc 521 $models = self::get_all_models(true, true, $context);
1611308b
DM
522 foreach ($models as $key => $model) {
523 // Check that it not only have predictions but also generates insights from them.
486e797c 524 if (!$model->uses_insights() || !$model->get_target()->link_insights_report()) {
1611308b
DM
525 unset($models[$key]);
526 }
527 }
528 return $models;
529 }
530
93e71c71
DM
531 /**
532 * Returns the models that generated insights in the provided context. It can also be used to add new models to the context.
533 *
534 * Note that if you use this function with $newmodelid is the caller responsibility to ensure that the
535 * provided model id generated insights for the provided context.
536 *
537 * @throws \coding_exception
538 * @param \context $context
539 * @param int|null $newmodelid A new model to add to the list of models with insights in the provided context.
540 * @return int[]
541 */
542 public static function cached_models_with_insights(\context $context, int $newmodelid = null) {
543
544 $cache = \cache::make('core', 'contextwithinsights');
545 $modelids = $cache->get($context->id);
546 if ($modelids === false) {
547 // The cache is empty, but we don't know if it is empty because there are no insights
548 // in this context or because cache/s have been purged, we need to be conservative and
549 // "pay" 1 db read to fill up the cache.
550
551 $models = \core_analytics\manager::get_models_with_insights($context);
552
553 if ($newmodelid && empty($models[$newmodelid])) {
554 throw new \coding_exception('The provided modelid ' . $newmodelid . ' did not generate any insights');
555 }
556
557 $modelids = array_keys($models);
558 $cache->set($context->id, $modelids);
559
560 } else if ($newmodelid && !in_array($newmodelid, $modelids)) {
561 // We add the context we got as an argument to the cache.
562
563 array_push($modelids, $newmodelid);
564 $cache->set($context->id, $modelids);
565 }
566
567 return $modelids;
568 }
569
1611308b
DM
570 /**
571 * Returns a prediction
572 *
573 * @param int $predictionid
574 * @param bool $requirelogin
575 * @return array array($model, $prediction, $context)
576 */
577 public static function get_prediction($predictionid, $requirelogin = false) {
578 global $DB;
579
580 if (!$predictionobj = $DB->get_record('analytics_predictions', array('id' => $predictionid))) {
4a210b06
DM
581 throw new \moodle_exception('errorpredictionnotfound', 'analytics');
582 }
583
584 $context = \context::instance_by_id($predictionobj->contextid, IGNORE_MISSING);
585 if (!$context) {
586 throw new \moodle_exception('errorpredictioncontextnotavailable', 'analytics');
1611308b
DM
587 }
588
589 if ($requirelogin) {
590 list($context, $course, $cm) = get_context_info_array($predictionobj->contextid);
591 require_login($course, false, $cm);
1611308b
DM
592 }
593
413f19bc 594 self::check_can_list_insights($context);
1611308b
DM
595
596 $model = new \core_analytics\model($predictionobj->modelid);
597 $sampledata = $model->prediction_sample_data($predictionobj);
598 $prediction = new \core_analytics\prediction($predictionobj, $sampledata);
599
600 return array($model, $prediction, $context);
601 }
602
e709e544 603 /**
3b7c7918 604 * Used to be used to add models included with the Moodle core.
e709e544 605 *
3b7c7918 606 * @deprecated Deprecated since Moodle 3.7 (MDL-61667) - Use lib/db/analytics.php instead.
74ee34fd 607 * @todo Remove this method in Moodle 3.11 (MDL-65186).
e709e544
DM
608 * @return void
609 */
610 public static function add_builtin_models() {
611
3b7c7918
DM
612 debugging('core_analytics\manager::add_builtin_models() has been deprecated. Core models are now automatically '.
613 'updated according to their declaration in the lib/db/analytics.php file.', DEBUG_DEVELOPER);
e709e544
DM
614 }
615
f9222c49
DM
616 /**
617 * Cleans up analytics db tables that do not directly depend on analysables that may have been deleted.
618 */
619 public static function cleanup() {
620 global $DB;
621
4fd74fba
DM
622 $DB->execute("DELETE FROM {analytics_prediction_actions} WHERE predictionid IN
623 (SELECT ap.id FROM {analytics_predictions} ap
624 LEFT JOIN {context} ctx ON ap.contextid = ctx.id
625 WHERE ctx.id IS NULL)");
f9222c49 626
7f552899
MC
627 // Cleanup analaytics predictions/calcs with MySQL friendly sub-select.
628 $DB->execute("DELETE FROM {analytics_predictions} WHERE id IN (
629 SELECT oldpredictions.id
630 FROM (
631 SELECT p.id
632 FROM {analytics_predictions} p
633 LEFT JOIN {context} ctx ON p.contextid = ctx.id
634 WHERE ctx.id IS NULL
635 ) oldpredictions
636 )");
637
638 $DB->execute("DELETE FROM {analytics_indicator_calc} WHERE id IN (
639 SELECT oldcalcs.id FROM (
640 SELECT c.id
641 FROM {analytics_indicator_calc} c
642 LEFT JOIN {context} ctx ON c.contextid = ctx.id
643 WHERE ctx.id IS NULL
644 ) oldcalcs
645 )");
f9222c49
DM
646
647 // Clean up stuff that depends on analysable ids that do not exist anymore.
500111c5 648
f9222c49
DM
649 $models = self::get_all_models();
650 foreach ($models as $model) {
500111c5
DM
651
652 // We first dump into memory the list of analysables we have in the database (we could probably do this with 1 single
653 // query for the 3 tables, but it may be safer to do it separately).
654 $predictsamplesanalysableids = $DB->get_fieldset_select('analytics_predict_samples', 'DISTINCT analysableid',
655 'modelid = :modelid', ['modelid' => $model->get_id()]);
656 $predictsamplesanalysableids = array_flip($predictsamplesanalysableids);
657 $trainsamplesanalysableids = $DB->get_fieldset_select('analytics_train_samples', 'DISTINCT analysableid',
658 'modelid = :modelid', ['modelid' => $model->get_id()]);
659 $trainsamplesanalysableids = array_flip($trainsamplesanalysableids);
660 $usedanalysablesanalysableids = $DB->get_fieldset_select('analytics_used_analysables', 'DISTINCT analysableid',
661 'modelid = :modelid', ['modelid' => $model->get_id()]);
662 $usedanalysablesanalysableids = array_flip($usedanalysablesanalysableids);
663
f9222c49 664 $analyser = $model->get_analyser(array('notimesplitting' => true));
76b5ee45
DM
665
666 // We do not honour the list of contexts in this model as it can contain stale records.
fccc728f
DM
667 $analysables = $analyser->get_analysables_iterator();
668
669 $analysableids = [];
670 foreach ($analysables as $analysable) {
671 if (!$analysable) {
672 continue;
673 }
500111c5
DM
674 unset($predictsamplesanalysableids[$analysable->get_id()]);
675 unset($trainsamplesanalysableids[$analysable->get_id()]);
676 unset($usedanalysablesanalysableids[$analysable->get_id()]);
f9222c49
DM
677 }
678
500111c5 679 $param = ['modelid' => $model->get_id()];
f9222c49 680
500111c5 681 if ($predictsamplesanalysableids) {
4fd74fba
DM
682 list($idssql, $idsparams) = $DB->get_in_or_equal(array_flip($predictsamplesanalysableids), SQL_PARAMS_NAMED);
683 $DB->delete_records_select('analytics_predict_samples', "modelid = :modelid AND analysableid $idssql",
684 $param + $idsparams);
500111c5
DM
685 }
686 if ($trainsamplesanalysableids) {
4fd74fba
DM
687 list($idssql, $idsparams) = $DB->get_in_or_equal(array_flip($trainsamplesanalysableids), SQL_PARAMS_NAMED);
688 $DB->delete_records_select('analytics_train_samples', "modelid = :modelid AND analysableid $idssql",
689 $param + $idsparams);
500111c5
DM
690 }
691 if ($usedanalysablesanalysableids) {
4fd74fba
DM
692 list($idssql, $idsparams) = $DB->get_in_or_equal(array_flip($usedanalysablesanalysableids), SQL_PARAMS_NAMED);
693 $DB->delete_records_select('analytics_used_analysables', "modelid = :modelid AND analysableid $idssql",
694 $param + $idsparams);
500111c5 695 }
f9222c49 696 }
9ae71673
DM
697
698 // Clean up calculations table.
699 $calclifetime = get_config('analytics', 'calclifetime');
700 if (!empty($calclifetime)) {
701 $lifetime = time() - ($calclifetime * DAYSECS); // Value in days.
702 $DB->delete_records_select('analytics_indicator_calc', 'timecreated < ?', [$lifetime]);
703 }
f9222c49
DM
704 }
705
ed12ba6b
DM
706 /**
707 * Default system backend.
708 *
709 * @return string
710 */
711 public static function default_mlbackend() {
712 return self::DEFAULT_MLBACKEND;
713 }
714
369389c9
DM
715 /**
716 * Returns the provided element classes in the site.
717 *
718 * @param string $element
719 * @return string[] Array keys are the FQCN and the values the class path.
720 */
721 private static function get_analytics_classes($element) {
722
723 // Just in case...
1611308b 724 $element = clean_param($element, PARAM_ALPHANUMEXT);
369389c9 725
0d6a45d2 726 $classes = \core_component::get_component_classes_in_namespace(null, 'analytics\\' . $element);
1cc2b4ba 727
369389c9
DM
728 return $classes;
729 }
f0584045 730
606c3be0
DM
731 /**
732 * Check that all the models declared by the component are up to date.
733 *
734 * This is intended to be called during the installation / upgrade to automatically create missing models.
735 *
736 * @param string $componentname The name of the component to load models for.
737 * @return array \core_analytics\model[] List of actually created models.
738 */
739 public static function update_default_models_for_component(string $componentname): array {
740
741 $result = [];
742
743 foreach (static::load_default_models_for_component($componentname) as $definition) {
744 if (!\core_analytics\model::exists(static::get_target($definition['target']))) {
745 $result[] = static::create_declared_model($definition);
746 }
747 }
748
749 return $result;
750 }
751
f0584045
DM
752 /**
753 * Return the list of models declared by the given component.
754 *
755 * @param string $componentname The name of the component to load models for.
756 * @throws \coding_exception Exception thrown in case of invalid syntax.
757 * @return array The $models description array.
758 */
759 public static function load_default_models_for_component(string $componentname): array {
760
761 $dir = \core_component::get_component_directory($componentname);
762
763 if (!$dir) {
764 // This is either an invalid component, or a core subsystem without its own root directory.
765 return [];
766 }
767
768 $file = $dir . '/' . self::ANALYTICS_FILENAME;
769
770 if (!is_readable($file)) {
771 return [];
772 }
773
774 $models = null;
775 include($file);
776
777 if (!isset($models) || !is_array($models) || empty($models)) {
778 return [];
779 }
780
781 foreach ($models as &$model) {
782 if (!isset($model['enabled'])) {
783 $model['enabled'] = false;
784 } else {
785 $model['enabled'] = clean_param($model['enabled'], PARAM_BOOL);
786 }
787 }
788
789 static::validate_models_declaration($models);
790
791 return $models;
792 }
793
1297fa41
DM
794 /**
795 * Return the list of all the models declared anywhere in this Moodle installation.
796 *
797 * Models defined by the core and core subsystems come first, followed by those provided by plugins.
798 *
799 * @return array indexed by the frankenstyle component
800 */
801 public static function load_default_models_for_all_components(): array {
802
803 $tmp = [];
804
805 foreach (\core_component::get_component_list() as $type => $components) {
806 foreach (array_keys($components) as $component) {
807 if ($loaded = static::load_default_models_for_component($component)) {
808 $tmp[$type][$component] = $loaded;
809 }
810 }
811 }
812
813 $result = [];
814
815 if ($loaded = static::load_default_models_for_component('core')) {
816 $result['core'] = $loaded;
817 }
818
819 if (!empty($tmp['core'])) {
820 $result += $tmp['core'];
821 unset($tmp['core']);
822 }
823
824 foreach ($tmp as $components) {
825 $result += $components;
826 }
827
828 return $result;
829 }
830
f0584045
DM
831 /**
832 * Validate the declaration of prediction models according the syntax expected in the component's db folder.
833 *
834 * The expected structure looks like this:
835 *
836 * [
837 * [
838 * 'target' => '\fully\qualified\name\of\the\target\class',
839 * 'indicators' => [
840 * '\fully\qualified\name\of\the\first\indicator',
841 * '\fully\qualified\name\of\the\second\indicator',
842 * ],
843 * 'timesplitting' => '\optional\name\of\the\time_splitting\class',
844 * 'enabled' => true,
845 * ],
846 * ];
847 *
848 * @param array $models List of declared models.
849 * @throws \coding_exception Exception thrown in case of invalid syntax.
850 */
851 public static function validate_models_declaration(array $models) {
852
853 foreach ($models as $model) {
854 if (!isset($model['target'])) {
855 throw new \coding_exception('Missing target declaration');
856 }
857
858 if (!static::is_valid($model['target'], '\core_analytics\local\target\base')) {
859 throw new \coding_exception('Invalid target classname', $model['target']);
860 }
861
862 if (empty($model['indicators']) || !is_array($model['indicators'])) {
863 throw new \coding_exception('Missing indicators declaration');
864 }
865
866 foreach ($model['indicators'] as $indicator) {
867 if (!static::is_valid($indicator, '\core_analytics\local\indicator\base')) {
868 throw new \coding_exception('Invalid indicator classname', $indicator);
869 }
870 }
871
872 if (isset($model['timesplitting'])) {
873 if (substr($model['timesplitting'], 0, 1) !== '\\') {
874 throw new \coding_exception('Expecting fully qualified time splitting classname', $model['timesplitting']);
875 }
876 if (!static::is_valid($model['timesplitting'], '\core_analytics\local\time_splitting\base')) {
877 throw new \coding_exception('Invalid time splitting classname', $model['timesplitting']);
878 }
879 }
880
881 if (!empty($model['enabled']) && !isset($model['timesplitting'])) {
882 throw new \coding_exception('Cannot enable a model without time splitting method specified');
883 }
884 }
885 }
6187213f
DM
886
887 /**
888 * Create the defined model.
889 *
890 * @param array $definition See {@link self::validate_models_declaration()} for the syntax.
891 * @return \core_analytics\model
892 */
893 public static function create_declared_model(array $definition): \core_analytics\model {
894
7dba0c27 895 list($target, $indicators) = static::get_declared_target_and_indicators_instances($definition);
6187213f
DM
896
897 if (isset($definition['timesplitting'])) {
898 $timesplitting = $definition['timesplitting'];
899 } else {
900 $timesplitting = false;
901 }
902
903 $created = \core_analytics\model::create($target, $indicators, $timesplitting);
904
905 if (!empty($definition['enabled'])) {
906 $created->enable();
907 }
908
909 return $created;
910 }
01d620ee
DM
911
912 /**
913 * Returns a string uniquely representing the given model declaration.
914 *
915 * @param array $model Model declaration
916 * @return string complying with PARAM_ALPHANUM rules and starting with an 'id' prefix
917 */
918 public static function model_declaration_identifier(array $model) : string {
919 return 'id'.sha1(serialize($model));
920 }
7dba0c27
DM
921
922 /**
923 * Given a model definition, return actual target and indicators instances.
924 *
925 * @param array $definition See {@link self::validate_models_declaration()} for the syntax.
926 * @return array [0] => target instance, [1] => array of indicators instances
927 */
928 public static function get_declared_target_and_indicators_instances(array $definition): array {
929
930 $target = static::get_target($definition['target']);
931
932 $indicators = [];
933
934 foreach ($definition['indicators'] as $indicatorname) {
935 $indicator = static::get_indicator($indicatorname);
936 $indicators[$indicator->get_id()] = $indicator;
937 }
938
939 return [$target, $indicators];
940 }
76b5ee45
DM
941
942 /**
943 * Return the context restrictions that can be applied to the provided context levels.
944 *
945 * @throws \coding_exception
946 * @param array|null $contextlevels The list of context levels provided by the analyser. Null if all of them.
06579b18 947 * @param string|null $query
76b5ee45
DM
948 * @return array Associative array with contextid as key and the short version of the context name as value.
949 */
06579b18 950 public static function get_potential_context_restrictions(?array $contextlevels = null, string $query = null) {
76b5ee45
DM
951 global $DB;
952
953 if (empty($contextlevels) && !is_null($contextlevels)) {
954 return false;
955 }
956
957 if (!is_null($contextlevels)) {
958 foreach ($contextlevels as $contextlevel) {
959 if ($contextlevel !== CONTEXT_COURSE && $contextlevel !== CONTEXT_COURSECAT) {
960 throw new \coding_exception('Only CONTEXT_COURSE and CONTEXT_COURSECAT are supported at the moment.');
961 }
962 }
963 }
964
965 $contexts = [];
966
967 // We have a separate process for each context level for performance reasons (to iterate through mdl_context calling
968 // get_context_name() would be too slow).
969 $contextsystem = \context_system::instance();
970 if (is_null($contextlevels) || in_array(CONTEXT_COURSECAT, $contextlevels)) {
971
972 $sql = "SELECT cc.id, cc.name, ctx.id AS contextid
973 FROM {course_categories} cc
974 JOIN {context} ctx ON ctx.contextlevel = :ctxlevel AND ctx.instanceid = cc.id";
06579b18
DM
975 $params = ['ctxlevel' => CONTEXT_COURSECAT];
976
977 if ($query) {
978 $sql .= " WHERE " . $DB->sql_like('cc.name', ':query', false, false);
979 $params['query'] = '%' . $query . '%';
980 }
981
982 $coursecats = $DB->get_recordset_sql($sql, $params);
76b5ee45
DM
983 foreach ($coursecats as $record) {
984 $contexts[$record->contextid] = get_string('category') . ': ' .
985 format_string($record->name, true, array('context' => $contextsystem));
986 }
987 $coursecats->close();
988 }
989
990 if (is_null($contextlevels) || in_array(CONTEXT_COURSE, $contextlevels)) {
991
992 $sql = "SELECT c.id, c.shortname, ctx.id AS contextid
993 FROM {course} c
06579b18
DM
994 JOIN {context} ctx ON ctx.contextlevel = :ctxlevel AND ctx.instanceid = c.id
995 WHERE c.id != :siteid";
996 $params = ['ctxlevel' => CONTEXT_COURSE, 'siteid' => SITEID];
997
998 if ($query) {
999 $sql .= ' AND (' . $DB->sql_like('c.fullname', ':query1', false, false) . ' OR ' .
1000 $DB->sql_like('c.shortname', ':query2', false, false) . ')';
1001 $params['query1'] = '%' . $query . '%';
1002 $params['query2'] = '%' . $query . '%';
1003 }
1004
1005 $courses = $DB->get_recordset_sql($sql, $params);
76b5ee45
DM
1006 foreach ($courses as $record) {
1007 $contexts[$record->contextid] = get_string('course') . ': ' .
1008 format_string($record->shortname, true, array('context' => $contextsystem));
1009 }
1010 $courses->close();
1011 }
1012
1013 return $contexts;
1014 }
1015
369389c9 1016}