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