MDL-65588 analytics: New models for student accesses

analytics/classes/local/time_splitting/after_start.php

@@ -0,0 +1,111 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * Time splitting method that generates predictions X days/weeks/months after the analysable start.
+ *
+ * @package   core_analytics
+ * @copyright 2019 David Monllao {@link http://www.davidmonllao.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+namespace core_analytics\local\time_splitting;
+
+defined('MOODLE_INTERNAL') || die();
+
+/**
+ * Time splitting method that generates predictions X days/weeks/months after the analysable start.
+ *
+ * @package   core_analytics
+ * @copyright 2019 David Monllao {@link http://www.davidmonllao.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+abstract class after_start extends \core_analytics\local\time_splitting\base implements before_now {
+
+    /**
+     * The period we should wait until we generate predictions for this.
+     *
+     * @param  \core_analytics\analysable $analysable
+     * @return \DateInterval
+     */
+    abstract protected function wait_period(\core_analytics\analysable $analysable);
+
+    /**
+     * Returns whether the course can be processed by this time splitting method or not.
+     *
+     * @param \core_analytics\analysable $analysable
+     * @return bool
+     */
+    public function is_valid_analysable(\core_analytics\analysable $analysable) {
+
+        if (!$analysable->get_start()) {
+            return false;
+        }
+
+        $predictionstart = $this->get_prediction_interval_start($analysable);
+        if ($analysable->get_start() > $predictionstart) {
+            // We still need to wait.
+            return false;
+        }
+
+        return true;
+    }
+
+    /**
+     * This time-splitting method returns one single range, the start to two days before the end.
+     *
+     * @return array The list of ranges, each of them including 'start', 'end' and 'time'
+     */
+    protected function define_ranges() {
+
+        $now = time();
+        $ranges = [
+            [
+                'start' => $this->analysable->get_start(),
+                'end' => $now,
+                'time' => $now,
+            ]
+        ];
+
+        return $ranges;
+    }
+
+    /**
+     * Whether to cache or not the indicator calculations.
+     *
+     * @return bool
+     */
+    public function cache_indicator_calculations(): bool {
+        return false;
+    }
+
+    /**
+     * Calculates the interval start time backwards, from now.
+     *
+     * @param  \core_analytics\analysable $analysable
+     * @return int
+     */
+    protected function get_prediction_interval_start(\core_analytics\analysable $analysable) {
+
+        // The prediction time is always time(). We don't want to reuse the firstanalysis time
+        // because otherwise samples (e.g. students) which start after the analysable (e.g. course)
+        // start would use an incorrect analysis interval.
+        $predictionstart = new \DateTime('now');
+        $predictionstart->sub($this->wait_period($analysable));
+
+        return $predictionstart->getTimestamp();
+    }
+}

analytics/classes/local/time_splitting/past_periodic.php

@@ -0,0 +1,97 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * Time splitting method that generates predictions regularly.
+ *
+ * @package   core_analytics
+ * @copyright 2019 David Monllao {@link http://www.davidmonllao.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+namespace core_analytics\local\time_splitting;
+
+defined('MOODLE_INTERNAL') || die();
+
+/**
+ * Time splitting method that generates predictions periodically.
+ *
+ * @package   core_analytics
+ * @copyright 2019 David Monllao {@link http://www.davidmonllao.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+abstract class past_periodic extends periodic implements before_now {
+
+    /**
+     * Gets the next range with start on the provided time.
+     *
+     * The next range is based on the past period so we substract this
+     * range's periodicity from $time.
+     *
+     * @param  \DateTimeImmutable $time
+     * @return array
+     */
+    protected function get_next_range(\DateTimeImmutable $time) {
+
+        $end = $time->getTimestamp();
+        $start = $time->sub($this->periodicity())->getTimestamp();
+
+        if ($start < $this->analysable->get_start()) {
+            // We skip the first range generated as its start is prior to the analysable start.
+            return false;
+        }
+
+        return [
+            'start' => $start,
+            'end' => $end,
+            'time' => $end
+        ];
+    }
+
+    /**
+     * Get the start of the first time range.
+     *
+     * @return int A timestamp.
+     */
+    protected function get_first_start() {
+        return $this->analysable->get_start();
+    }
+
+    /**
+     * Guarantees that the last range dates end right now.
+     *
+     * @param  array  $ranges
+     * @return array
+     */
+    protected function update_last_range(array $ranges) {
+        $lastrange = end($ranges);
+
+        if ($lastrange['time'] > time()) {
+            // We just need to wait in this case.
+            return $lastrange;
+        }
+
+        $timetoenddiff = time() - $lastrange['time'];
+
+        $ranges[count($ranges) - 1] = [
+            'start' => $lastrange['start'] + $timetoenddiff,
+            'end' => $lastrange['end'] + $timetoenddiff,
+            'time' => $lastrange['time'] + $timetoenddiff,
+        ];
+
+        return $ranges;
+    }
+}

analytics/classes/local/time_splitting/periodic.php

@@ -42,6 +42,21 @@ abstract class periodic extends base {
      */
     abstract protected function periodicity();
 
+    /**
+     * Gets the next range with start on the provided time.
+     *
+     * @param  \DateTimeImmutable $time
+     * @return array
+     */
+    abstract protected function get_next_range(\DateTimeImmutable $time);
+
+    /**
+     * Get the start of the first time range.
+     *
+     * @return int A timestamp.
+     */
+    abstract protected function get_first_start();
+
     /**
      * Returns whether the analysable can be processed by this time splitting method or not.
      *
@@ -67,25 +82,42 @@ protected function define_ranges() {
         if ($this->analysable->get_end()) {
             $end = (new \DateTimeImmutable())->setTimestamp($this->analysable->get_end());
         }
-        $next = (new \DateTimeImmutable())->setTimestamp($this->get_first_start());
+        $nexttime = (new \DateTimeImmutable())->setTimestamp($this->get_first_start());
 
         $now = new \DateTimeImmutable('now', \core_date::get_server_timezone_object());
 
-        $ranges = [];
-        while ($next < $now &&
-                (empty($end) || $next < $end)) {
-            $range = $this->get_next_range($next);
-            if ($range) {
-                $ranges[] = $range;
+        $range = $this->get_next_range($nexttime);
+        if (!$range) {
+            $nexttime = $nexttime->add($periodicity);
+            $range = $this->get_next_range($nexttime);
+
+            if (!$range) {
+                throw new \coding_exception('The get_next_range implementation is broken. The difference between two consecutive
+                    ranges can not be more than the periodicity.');
             }
-            $next = $next->add($periodicity);
         }
 
-        $nextrange = $this->get_next_range($next);
-        if ($this->ready_to_predict($nextrange) && (empty($end) || $next < $end)) {
-            // Add the next one if we have not reached the analysable end yet.
-            // It will be used to get predictions.
-            $ranges[] = $nextrange;
+        $ranges = [];
+        $endreached = false;
+        while (($this->ready_to_predict($range) || $this->ready_to_train($range)) && !$endreached) {
+            $ranges[] = $range;
+            $nexttime = $nexttime->add($periodicity);
+            $range = $this->get_next_range($nexttime);
+
+            $endreached = (!empty($end) && $nexttime > $end);
+        }
+
+        if ($ranges && !$endreached) {
+            // If this analysable is not finished we adjust the start and end of the last element in $ranges
+            // so that it ends in time().The reason is that the start of these ranges is based on the analysable
+            // start and the end is calculated based on the start. This is to prevent the same issue we had in MDL-65348.
+            //
+            // An example of the situation we want to avoid is:
+            // A course started on a Monday, in 2015. It has no end date. Now the system is upgraded to Moodle 3.8, which
+            // includes this code. This happens on Wednesday. Periodic ranges (e.g. weekly) will be calculated from a Monday
+            // so the data provided by the time-splitting method would be from Monday to Monday, when we really want to
+            // provide data from Wednesday to the past Wednesday.
+            $ranges = $this->update_last_range($ranges);
         }
 
         return $ranges;
@@ -119,34 +151,12 @@ public function get_training_ranges() {
     }
 
     /**
-     * The next range is based on the past period.
+     * Allows child classes to update the last range provided.
      *
-     * @param  \DateTimeImmutable $next
+     * @param  array  $ranges
      * @return array
      */
-    protected function get_next_range(\DateTimeImmutable $next) {
-
-        $end = $next->getTimestamp();
-        $start = $next->sub($this->periodicity())->getTimestamp();
-
-        if ($start < $this->analysable->get_start()) {
-            // We skip the first range generated as its start is prior to the analysable start.
-            return false;
-        }
-
-        return [
-            'start' => $start,
-            'end' => $end,
-            'time' => $end
-        ];
-    }
-
-    /**
-     * Get the start of the first time range.
-     *
-     * @return int A timestamp.
-     */
-    protected function get_first_start() {
-        return $this->analysable->get_start();
+    protected function update_last_range(array $ranges) {
+        return $ranges;
     }
 }

analytics/classes/local/time_splitting/upcoming_periodic.php

@@ -36,15 +36,18 @@
 abstract class upcoming_periodic extends periodic implements after_now {
 
     /**
-     * The next range indicator calculations should be based on upcoming dates.
+     * Gets the next range with start on the provided time.
      *
-     * @param  \DateTimeImmutable $next
+     * The next range is based on the upcoming period so we add this
+     * range's periodicity to $time.
+     *
+     * @param  \DateTimeImmutable $time
      * @return array
      */
-    protected function get_next_range(\DateTimeImmutable $next) {
+    protected function get_next_range(\DateTimeImmutable $time) {
 
-        $start = $next->getTimestamp();
-        $end = $next->add($this->periodicity())->getTimestamp();
+        $start = $time->getTimestamp();
+        $end = $time->add($this->periodicity())->getTimestamp();
         return [
             'start' => $start,
             'end' => $end,
@@ -87,7 +90,7 @@ protected function get_first_start() {
             return $firstanalysis;
         }
 
-        // This analysable has not yet been analysed, the start is therefore now (-1 so ready_to_predict can be executed).
-        return time() - 1;
+        // This analysable has not yet been analysed, the start is therefore now.
+        return time();
     }
 }

analytics/tests/fixtures/test_timesplitting_seconds.php

@@ -31,7 +31,7 @@
  * @copyright 2019 David Monllaó {@link http://www.davidmonllao.com}
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
-class test_timesplitting_seconds extends \core_analytics\local\time_splitting\periodic {
+class test_timesplitting_seconds extends \core_analytics\local\time_splitting\past_periodic {
 
     /**
      * Every second.