1ffa28cf6d43b937a74f9c657f79d923ead87d93
[moodle.git] / analytics / classes / course.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  *
19  * @package   core_analytics
20  * @copyright 2016 David Monllao {@link http://www.davidmonllao.com}
21  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
22  */
24 namespace core_analytics;
26 defined('MOODLE_INTERNAL') || die();
28 require_once($CFG->dirroot . '/course/lib.php');
29 require_once($CFG->dirroot . '/lib/gradelib.php');
31 /**
32  *
33  * @package   core_analytics
34  * @copyright 2016 David Monllao {@link http://www.davidmonllao.com}
35  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
36  */
37 class course implements \core_analytics\analysable {
39     protected static $instances = array();
41     protected $studentroles = [];
42     protected $teacherroles = [];
44     protected $course = null;
45     protected $coursecontext = null;
47     protected $courseactivities = array();
49     protected $starttime = null;
50     protected $started = null;
51     protected $endtime = null;
52     protected $finished = null;
54     protected $studentids = [];
55     protected $teacherids = [];
57     protected $ntotallogs = null;
59     /**
60      * Course manager constructor.
61      *
62      * Use self::instance() instead to get cached copies of the course. Instances obtained
63      * through this constructor will not be cached either.
64      *
65      * Loads course students and teachers.
66      *
67      * Let's try to keep this computationally inexpensive.
68      *
69      * @param int|stdClass $course Course id
70      * @param array $studentroles
71      * @param array $teacherroles
72      * @return void
73      */
74     public function __construct($course) {
76         if (is_scalar($course)) {
77             $this->course = get_course($course);
78         } else {
79             $this->course = $course;
80         }
82         $this->coursecontext = \context_course::instance($this->course->id);
84         $studentroles = get_config('analytics', 'studentroles');
85         $teacherroles = get_config('analytics', 'teacherroles');
87         if (empty($studentroles) || empty($teacherroles)) {
88             // Unexpected, site settings should be set with default values.
89             throw new \moodle_exception('errornoroles', 'analytics');
90         }
92         $this->studentroles = explode(',', $studentroles);
93         $this->teacherroles = explode(',', $teacherroles);
95         $this->now = time();
97         // Get the course users, including users assigned to student and teacher roles at an higher context.
98         $this->studentids = $this->get_user_ids($this->studentroles);
99         $this->teacherids = $this->get_user_ids($this->teacherroles);
100     }
102     /**
103      * instance
104      *
105      * @param int|stdClass $course Course id
106      * @return void
107      */
108     public static function instance($course) {
110         $courseid = $course;
111         if (!is_scalar($courseid)) {
112             $courseid = $course->id;
113         }
115         if (!empty(self::$instances[$courseid])) {
116             return self::$instances[$courseid];
117         }
119         $instance = new \core_analytics\course($course);
120         self::$instances[$courseid] = $instance;
121         return self::$instances[$courseid];
122     }
124     public function get_id() {
125         return $this->course->id;
126     }
128     public function get_context() {
129         if ($this->coursecontext === null) {
130             $this->coursecontext = \context_course::instance($this->course->id);
131         }
132         return $this->coursecontext;
133     }
135     /**
136      * Get the course start timestamp.
137      *
138      * @return int Timestamp or 0 if has not started yet.
139      */
140     public function get_start() {
141         global $DB;
143         if ($this->starttime !== null) {
144             return $this->starttime;
145         }
147         // The field always exist but may have no valid if the course is created through a sync process.
148         if (!empty($this->course->startdate)) {
149             $this->starttime = (int)$this->course->startdate;
150         } else {
151             $this->starttime = 0;
152         }
154         return $this->starttime;
155     }
157     public function guess_start() {
158         global $DB;
160         if (!$this->get_total_logs()) {
161             // Can't guess.
162             return 0;
163         }
165         // We first try to find current course student logs.
166         list($filterselect, $filterparams) = $this->course_students_query_filter();
167         $sql = "SELECT MIN(timecreated) FROM {logstore_standard_log}
168                   WHERE $filterselect
169                  GROUP BY userid";
170         $firstlogs = $DB->get_fieldset_sql($sql, $filterparams);
171         if (empty($firstlogs)) {
172             return 0;
173         }
174         sort($firstlogs);
175         $firstlogsmedian = $this->median($firstlogs);
177         // Not using enrol API because we may be dealing with databases that used
178         // 3rd party enrolment plugins that are not available in the database.
179         // TODO We will need to switch to enrol API once we have enough data.
180         list($studentssql, $studentparams) = $DB->get_in_or_equal($this->studentids, SQL_PARAMS_NAMED);
181         $sql = "SELECT ue.* FROM {user_enrolments} ue
182                   JOIN {enrol} e ON e.id = ue.enrolid
183                  WHERE e.courseid = :courseid AND ue.userid $studentssql";
184         $studentenrolments = $DB->get_records_sql($sql, array('courseid' => $this->course->id) + $studentparams);
185         if (empty($studentenrolments)) {
186             return 0;
187         }
189         $enrolstart = array();
190         foreach ($studentenrolments as $studentenrolment) {
191             // I don't like CASE WHEN :P
192             $enrolstart[] = ($studentenrolment->timestart) ? $studentenrolment->timestart : $studentenrolment->timecreated;
193         }
194         sort($enrolstart);
195         $enrolstartmedian = $this->median($enrolstart);
197         return intval(($enrolstartmedian + $firstlogsmedian) / 2);
198     }
200     /**
201      * Get the course end timestamp.
202      *
203      * @return int Timestamp or 0 if time end was not set.
204      */
205     public function get_end() {
206         global $DB;
208         if ($this->endtime !== null) {
209             return $this->endtime;
210         }
212         // The enddate field is only available from Moodle 3.2 (MDL-22078).
213         if (!empty($this->course->enddate)) {
214             $this->endtime = (int)$this->course->enddate;
215             return $this->endtime;
216         }
218         return 0;
219     }
221     /**
222      * Get the course end timestamp.
223      *
224      * @return int Timestamp, \core_analytics\analysable::MAX_TIME if we don't know but ongoing and 0 if we can not work it out.
225      */
226     public function guess_end() {
227         global $DB;
229         if ($this->get_total_logs() === 0) {
230             // No way to guess if there are no logs.
231             $this->endtime = 0;
232             return $this->endtime;
233         }
235         list($filterselect, $filterparams) = $this->course_students_query_filter('ula');
237         // Consider the course open if there are still student accesses.
238         $monthsago = time() - (WEEKSECS * 4 * 2);
239         $select = $filterselect . ' AND timeaccess > :timeaccess';
240         $params = $filterparams + array('timeaccess' => $monthsago);
241         $sql = "SELECT timeaccess FROM {user_lastaccess} ula
242                   JOIN {enrol} e ON e.courseid = ula.courseid
243                   JOIN {user_enrolments} ue ON e.id = ue.enrolid AND ue.userid = ula.userid
244                  WHERE $select";
245         if ($records = $DB->get_records_sql($sql, $params)) {
246             return 0;
247         }
249         $sql = "SELECT timeaccess FROM {user_lastaccess} ula
250                   JOIN {enrol} e ON e.courseid = ula.courseid
251                   JOIN {user_enrolments} ue ON e.id = ue.enrolid AND ue.userid = ula.userid
252                  WHERE $filterselect AND ula.timeaccess != 0
253                  ORDER BY timeaccess DESC";
254         $studentlastaccesses = $DB->get_fieldset_sql($sql, $filterparams);
255         if (empty($studentlastaccesses)) {
256             return 0;
257         }
258         sort($studentlastaccesses);
260         return $this->median($studentlastaccesses);
261     }
263     public function get_course_data() {
264         return $this->course;
265     }
267     /**
268      * Is the course valid to extract indicators from it?
269      *
270      * @return bool
271      */
272     public function is_valid() {
274         if (!$this->was_started() || !$this->is_finished()) {
275             return false;
276         }
278         return true;
279     }
281     /**
282      * Has the course started?
283      *
284      * @return bool
285      */
286     public function was_started() {
288         if ($this->started === null) {
289             if ($this->get_start() === 0 || $this->now < $this->get_start()) {
290                 // Not yet started.
291                 $this->started = false;
292             } else {
293                 $this->started = true;
294             }
295         }
297         return $this->started;
298     }
300     /**
301      * Has the course finished?
302      *
303      * @return bool
304      */
305     public function is_finished() {
307         if ($this->finished === null) {
308             $endtime = $this->get_end();
309             if ($endtime === 0 || $this->now < $endtime) {
310                 // It is not yet finished or no idea when it finishes.
311                 $this->finished = false;
312             } else {
313                 $this->finished = true;
314             }
315         }
317         return $this->finished;
318     }
320     /**
321      * Returns a list of user ids matching the specified roles in this course.
322      *
323      * @param array $roleids
324      * @return array
325      */
326     public function get_user_ids($roleids) {
328         // We need to index by ra.id as a user may have more than 1 $roles role.
329         $records = get_role_users($roleids, $this->coursecontext, true, 'ra.id, u.id AS userid, r.id AS roleid', 'ra.id ASC');
331         // If a user have more than 1 $roles role array_combine will discard the duplicate.
332         $callable = array($this, 'filter_user_id');
333         $userids = array_values(array_map($callable, $records));
334         return array_combine($userids, $userids);
335     }
337     /**
338      * Returns the course students.
339      *
340      * @return stdClass[]
341      */
342     public function get_students() {
343         return $this->studentids;
344     }
346     /**
347      * Returns the total number of student logs in the course
348      *
349      * @return int
350      */
351     public function get_total_logs() {
352         global $DB;
354         // No logs if no students.
355         if (empty($this->studentids)) {
356             return 0;
357         }
359         if ($this->ntotallogs === null) {
360             list($filterselect, $filterparams) = $this->course_students_query_filter();
361             $this->ntotallogs = $DB->count_records_select('logstore_standard_log', $filterselect, $filterparams);
362         }
364         return $this->ntotallogs;
365     }
367     public function get_all_activities($activitytype) {
369         // Using is set because we set it to false if there are no activities.
370         if (!isset($this->courseactivities[$activitytype])) {
371             $modinfo = get_fast_modinfo($this->get_course_data(), -1);
372             $instances = $modinfo->get_instances_of($activitytype);
374             if ($instances) {
375                 $this->courseactivities[$activitytype] = array();
376                 foreach ($instances as $instance) {
377                     // By context.
378                     $this->courseactivities[$activitytype][$instance->context->id] = $instance;
379                 }
380             } else {
381                 $this->courseactivities[$activitytype] = false;
382             }
383         }
385         return $this->courseactivities[$activitytype];
386     }
388     public function get_student_grades($courseactivities) {
390         if (empty($courseactivities)) {
391             return array();
392         }
394         $grades = array();
395         foreach ($courseactivities as $contextid => $instance) {
396             $gradesinfo = grade_get_grades($this->course->id, 'mod', $instance->modname, $instance->instance, $this->studentids);
398             // Sort them by activity context and user.
399             if ($gradesinfo && $gradesinfo->items) {
400                 foreach ($gradesinfo->items as $gradeitem) {
401                     foreach ($gradeitem->grades as $userid => $grade) {
402                         if (empty($grades[$contextid][$userid])) {
403                             // Initialise it as array because a single activity can have multiple grade items (e.g. workshop).
404                             $grades[$contextid][$userid] = array();
405                         }
406                         $grades[$contextid][$userid][$gradeitem->id] = $grade;
407                     }
408                 }
409             }
410         }
412         return $grades;
413     }
415     public function get_activities($activitytype, $starttime, $endtime, $student = false) {
417         // $student may not be available, default to not calculating dynamic data.
418         $studentid = -1;
419         if ($student) {
420             $studentid = $student->id;
421         }
422         $modinfo = get_fast_modinfo($this->get_course_data(), $studentid);
423         $activities = $modinfo->get_instances_of($activitytype);
425         $timerangeactivities = array();
426         foreach ($activities as $activity) {
427             if (!$this->completed_by($activity, $starttime, $endtime)) {
428                 continue;
429             }
431             $timerangeactivities[$activity->context->id] = $activity;
432         }
434         return $timerangeactivities;
435     }
437     protected function completed_by(\cm_info $activity, $starttime, $endtime) {
439         // We can't check uservisible because:
440         // - Any activity with available until would not be counted.
441         // - Sites may block student's course view capabilities once the course is closed.
443         // Students can not view hidden activities by default, this is not reliable 100% but accurate in most of the cases.
444         if ($activity->visible === false) {
445             return false;
446         }
448         // TODO Use course_modules_completion's timemodified + COMPLETION_COMPLETE* to discard
449         // activities that have already been completed.
451         // We skip activities that were not yet visible or their 'until' was not in this $starttime - $endtime range.
452         if ($activity->availability) {
453             $info = new \core_availability\info_module($activity);
454             $activityavailability = $this->availability_completed_by($info, $starttime, $endtime);
455             if ($activityavailability === false) {
456                 return false;
457             } else if ($activityavailability === true) {
458                 // This activity belongs to this time range.
459                 return true;
460             }
461         }
463         //// We skip activities in sections that were not yet visible or their 'until' was not in this $starttime - $endtime range.
464         $section = $activity->get_modinfo()->get_section_info($activity->sectionnum);
465         if ($section->availability) {
466             $info = new \core_availability\info_section($section);
467             $sectionavailability = $this->availability_completed_by($info, $starttime, $endtime);
468             if ($sectionavailability === false) {
469                 return false;
470             } else if ($sectionavailability === true) {
471                 // This activity belongs to this section time range.
472                 return true;
473             }
474         }
476         // When the course is using format weeks we use the week's end date.
477         $format = course_get_format($activity->get_modinfo()->get_course());
478         if ($this->course->format === 'weeks') {
479             $dates = $format->get_section_dates($section);
481             // We need to consider the +2 hours added by get_section_dates.
482             // Avoid $starttime <= $dates->end because $starttime may be the start of the next week.
483             if ($starttime < ($dates->end - 7200) && $endtime >= ($dates->end - 7200)) {
484                 return true;
485             } else {
486                 return false;
487             }
488         }
490         // TODO Think about activities in sectionnum 0.
491         if ($activity->sectionnum == 0) {
492             return false;
493         }
495         if (!$this->get_end() || !$this->get_start()) {
496             debugging('Activities which due date is in a time range can not be calculated ' .
497                 'if the course doesn\'t have start and end date', DEBUG_DEVELOPER);
498             return false;
499         }
501         if (!course_format_uses_sections($this->course->format)) {
502             // If it does not use sections and there are no availability conditions to access it it is available
503             // and we can not magically classify it into any other time range than this one.
504             return true;
505         }
507         // Split the course duration in the number of sections and consider the end of each section the due
508         // date of all activities contained in that section.
509         $formatoptions = $format->get_format_options();
510         if (!empty($formatoptions['numsections'])) {
511             $nsections = $formatoptions['numsections'];
512         } else {
513             // There are course format that use sections but without numsections, we fallback to the number
514             // of cached sections in get_section_info_all, not that accurate though.
515             $coursesections = $activity->get_modinfo()->get_section_info_all();
516             $nsections = count($coursesections);
517             if (isset($coursesections[0])) {
518                 // We don't count section 0 if it exists.
519                 $nsections--;
520             }
521         }
523         $courseduration = $this->get_end() - $this->get_start();
524         $sectionduration = round($courseduration / $nsections);
525         $activitysectionenddate = $this->get_start() + ($sectionduration * $activity->sectionnum);
526         if ($activitysectionenddate > $starttime && $activitysectionenddate <= $endtime) {
527             return true;
528         }
530         return false;
531     }
533     protected function availability_completed_by(\core_availability\info $info, $starttime, $endtime) {
535         $dateconditions = $info->get_availability_tree()->get_all_children('\availability_date\condition');
536         foreach ($dateconditions as $condition) {
537             // Availability API does not allow us to check from / to dates nicely, we need to be naughty.
538             // TODO Would be nice to expand \availability_date\condition API for this calling a save that
539             // does not save is weird.
540             $conditiondata = $condition->save();
542             if ($conditiondata->d === \availability_date\condition::DIRECTION_FROM &&
543                     $conditiondata->t > $endtime) {
544                 // Skip this activity if any 'from' date is later than the end time.
545                 return false;
547             } else if ($conditiondata->d === \availability_date\condition::DIRECTION_UNTIL &&
548                     ($conditiondata->t < $starttime || $conditiondata->t > $endtime)) {
549                 // Skip activity if any 'until' date is not in $starttime - $endtime range.
550                 return false;
551             } else if ($conditiondata->d === \availability_date\condition::DIRECTION_UNTIL &&
552                     $conditiondata->t < $endtime && $conditiondata->t > $starttime) {
553                 return true;
554             }
555         }
557         // This can be interpreted as 'the activity was available but we don't know if its expected completion date
558         // was during this period.
559         return null;
560     }
562     /**
563      * Used by get_user_ids to extract the user id.
564      *
565      * @param \stdClass $record
566      * @return int The user id.
567      */
568     protected function filter_user_id($record) {
569         return $record->userid;
570     }
572     /**
573      * Returns the average time between 2 timestamps.
574      *
575      * @param int $start
576      * @param int $end
577      * @return array [starttime, averagetime, endtime]
578      */
579     protected function update_loop_times($start, $end) {
580         $avg = intval(($start + $end) / 2);
581         return array($start, $avg, $end);
582     }
584     /**
585      * Returns the query and params used to filter {logstore_standard_log} table by this course students.
586      *
587      * @return array
588      */
589     protected function course_students_query_filter($prefix = false) {
590         global $DB;
592         if ($prefix) {
593             $prefix = $prefix . '.';
594         }
596         // Check the amount of student logs in the 4 previous weeks.
597         list($studentssql, $studentsparams) = $DB->get_in_or_equal($this->studentids, SQL_PARAMS_NAMED);
598         $filterselect = $prefix . 'courseid = :courseid AND ' . $prefix . 'userid ' . $studentssql;
599         $filterparams = array('courseid' => $this->course->id) + $studentsparams;
601         return array($filterselect, $filterparams);
602     }
604     /**
605      * Calculate median
606      *
607      * Keys are ignored.
608      *
609      * @param int|float $values Sorted array of values
610      * @return int
611      */
612     protected function median($values) {
613         $count = count($values);
615         if ($count === 1) {
616             return reset($values);
617         }
619         $middlevalue = floor(($count - 1) / 2);
621         if ($count % 2) {
622             // Odd number, middle is the median.
623             $median = $values[$middlevalue];
624         } else {
625             // Even number, calculate avg of 2 medians.
626             $low = $values[$middlevalue];
627             $high = $values[$middlevalue + 1];
628             $median = (($low + $high) / 2);
629         }
630         return intval($median);
631     }