first commit

analytics/classes/local/indicator/base.php

@@ -0,0 +1,197 @@
+<?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/>.
+
+/**
+ * Abstract base indicator.
+ *
+ * @package   core_analytics
+ * @copyright 2016 David Monllao {@link http://www.davidmonllao.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+namespace core_analytics\local\indicator;
+
+defined('MOODLE_INTERNAL') || die();
+
+/**
+ * Abstract base indicator.
+ *
+ * @package   core_analytics
+ * @copyright 2016 David Monllao {@link http://www.davidmonllao.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+abstract class base extends \core_analytics\calculable {
+
+    /**
+     * Min value an indicator can return.
+     */
+    const MIN_VALUE = -1;
+
+    /**
+     * Max value an indicator can return.
+     */
+    const MAX_VALUE = 1;
+
+    /**
+     * Converts the calculated indicators to dataset feature/s.
+     *
+     * @param float|int[] $calculatedvalues
+     * @return array
+     */
+    abstract protected function to_features($calculatedvalues);
+
+    /**
+     * Calculates the sample.
+     *
+     * Return a value from self::MIN_VALUE to self::MAX_VALUE or null if the indicator can not be calculated for this sample.
+     *
+     * @param int $sampleid
+     * @param string $sampleorigin
+     * @param integer $starttime Limit the calculation to this timestart
+     * @param integer $endtime Limit the calculation to this timeend
+     * @return float|null
+     */
+    abstract protected function calculate_sample($sampleid, $sampleorigin, $starttime, $endtime);
+
+    /**
+     * Should this value be displayed?
+     *
+     * Indicators providing multiple features can be used this method to discard some of them.
+     *
+     * @param float $value
+     * @param string $subtype
+     * @return bool
+     */
+    public function should_be_displayed($value, $subtype) {
+        // We should everything by default.
+        return true;
+    }
+
+    /**
+     * Allows indicators to specify data they need.
+     *
+     * e.g. A model using courses as samples will not provide users data, but an indicator like
+     * "user is hungry" needs user data.
+     *
+     * @return null|string[] Name of the required elements (use the database tablename)
+     */
+    public static function required_sample_data() {
+        return null;
+    }
+
+    /**
+     * Returns an instance of the indicator.
+     *
+     * Useful to reset cached data.
+     *
+     * @return \core_analytics\local\indicator\base
+     */
+    public static function instance() {
+        return new static();
+    }
+
+    /**
+     * Returns the maximum value an indicator calculation can return.
+     *
+     * @return float
+     */
+    public static function get_max_value() {
+        return self::MAX_VALUE;
+    }
+
+    /**
+     * Returns the minimum value an indicator calculation can return.
+     *
+     * @return float
+     */
+    public static function get_min_value() {
+        return self::MIN_VALUE;
+    }
+
+    /**
+     * Hook to allow indicators to pre-fill data that is shared accross time range calculations.
+     *
+     * Useful to fill analysable-dependant data that does not depend on the time ranges. Use
+     * instance vars to cache data that can be re-used across samples calculations but changes
+     * between time ranges (indicator instances are reset between time ranges to avoid unexpected
+     * problems).
+     *
+     * You are also responsible of emptying previous analysable caches.
+     *
+     * @param \core_analytics\analysable $analysable
+     * @return void
+     */
+    public function fill_per_analysable_caches(\core_analytics\analysable $analysable) {
+    }
+
+    /**
+     * Calculates the indicator.
+     *
+     * Returns an array of values which size matches $sampleids size.
+     *
+     * @param int[] $sampleids
+     * @param string $samplesorigin
+     * @param integer $starttime Limit the calculation to this timestart
+     * @param integer $endtime Limit the calculation to this timeend
+     * @param array $existingcalculations Existing calculations of this indicator, indexed by sampleid.
+     * @return array [0] = [$sampleid => int[]|float[]], [1] = [$sampleid => int|float], [2] = [$sampleid => $sampleid]
+     */
+    public function calculate($sampleids, $samplesorigin, $starttime = false, $endtime = false, $existingcalculations = array()) {
+
+        if (!PHPUNIT_TEST && CLI_SCRIPT) {
+            echo '.';
+        }
+
+        $calculations = array();
+        $newcalculations = array();
+        $notnulls = array();
+        foreach ($sampleids as $sampleid => $unusedsampleid) {
+
+            if (isset($existingcalculations[$sampleid])) {
+                $calculatedvalue = $existingcalculations[$sampleid];
+            } else {
+                $calculatedvalue = $this->calculate_sample($sampleid, $samplesorigin, $starttime, $endtime);
+                $newcalculations[$sampleid] = $calculatedvalue;
+            }
+
+            if (!is_null($calculatedvalue)) {
+                $notnulls[$sampleid] = $sampleid;
+                $this->validate_calculated_value($calculatedvalue);
+            }
+
+            $calculations[$sampleid] = $calculatedvalue;
+        }
+
+        $features = $this->to_features($calculations);
+
+        return array($features, $newcalculations, $notnulls);
+    }
+
+    /**
+     * Validates the calculated value.
+     *
+     * @throws \coding_exception
+     * @param float $calculatedvalue
+     * @return true
+     */
+    protected function validate_calculated_value($calculatedvalue) {
+        if ($calculatedvalue > self::MAX_VALUE || $calculatedvalue < self::MIN_VALUE) {
+            throw new \coding_exception('Calculated values should be higher than ' . self::MIN_VALUE .
+                ' and lower than ' . self::MAX_VALUE . ' ' . $calculatedvalue . ' received');
+        }
+        return true;
+    }
+}

analytics/classes/local/indicator/binary.php

@@ -0,0 +1,128 @@
+<?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/>.
+
+/**
+ * Abstract binary indicator.
+ *
+ * @package   core_analytics
+ * @copyright 2017 David Monllao {@link http://www.davidmonllao.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+namespace core_analytics\local\indicator;
+
+defined('MOODLE_INTERNAL') || die();
+
+/**
+ * Abstract binary indicator.
+ *
+ * @package   core_analytics
+ * @copyright 2017 David Monllao {@link http://www.davidmonllao.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+abstract class binary extends discrete {
+
+    /**
+     * get_classes
+     *
+     * @return array
+     */
+    final public static function get_classes() {
+        return [-1, 1];
+    }
+
+    /**
+     * It should always be displayed.
+     *
+     * Binary values have no subtypes by default, please overwrite if
+     * your indicator is adding extra features.
+     *
+     * @param float $value
+     * @param string $subtype
+     * @return bool
+     */
+    public function should_be_displayed($value, $subtype) {
+        if ($subtype != false) {
+            return false;
+        }
+        return true;
+    }
+
+    /**
+     * get_display_value
+     *
+     * @param float $value
+     * @param string $subtype
+     * @return string
+     */
+    public function get_display_value($value, $subtype = false) {
+
+        // No subtypes for binary values by default.
+        if ($value == -1) {
+            return get_string('no');
+        } else if ($value == 1) {
+            return get_string('yes');
+        } else {
+            throw new \moodle_exception('errorpredictionformat', 'analytics');
+        }
+    }
+
+    /**
+     * get_calculation_outcome
+     *
+     * @param float $value
+     * @param string $subtype
+     * @return int
+     */
+    public function get_calculation_outcome($value, $subtype = false) {
+
+        // No subtypes for binary values by default.
+        if ($value == -1) {
+            return self::OUTCOME_NEGATIVE;
+        } else if ($value == 1) {
+            return self::OUTCOME_OK;
+        } else {
+            throw new \moodle_exception('errorpredictionformat', 'analytics');
+        }
+    }
+
+    /**
+     * get_feature_headers
+     *
+     * @return array
+     */
+    public static function get_feature_headers() {
+        // Just 1 single feature obtained from the calculated value.
+        return array('\\' . get_called_class());
+    }
+
+    /**
+     * to_features
+     *
+     * @param array $calculatedvalues
+     * @return array
+     */
+    protected function to_features($calculatedvalues) {
+        // Indicators with binary values have only 1 feature for indicator, here we do nothing else
+        // than converting each sample scalar value to an array of scalars with 1 element.
+        array_walk($calculatedvalues, function(&$calculatedvalue) {
+            // Just return it as an array.
+            $calculatedvalue = array($calculatedvalue);
+        });
+
+        return $calculatedvalues;
+    }
+}

analytics/classes/local/indicator/discrete.php

@@ -0,0 +1,159 @@
+<?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/>.
+
+/**
+ * Abstract discrete indicator.
+ *
+ * @package   core_analytics
+ * @copyright 2017 David Monllao {@link http://www.davidmonllao.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+namespace core_analytics\local\indicator;
+
+defined('MOODLE_INTERNAL') || die();
+
+/**
+ * Abstract discrete indicator.
+ *
+ * @package   core_analytics
+ * @copyright 2017 David Monllao {@link http://www.davidmonllao.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+abstract class discrete extends base {
+
+    /**
+     * Classes need to be defined so they can be converted internally to individual dataset features.
+     *
+     * @return string[]
+     */
+    protected static function get_classes() {
+        throw new \coding_exception('Please overwrite get_classes() specifying your discrete-values\' indicator classes');
+    }
+
+    /**
+     * Returns 1 feature header for each of the classes.
+     *
+     * @return string[]
+     */
+    public static function get_feature_headers() {
+        $fullclassname = '\\' . get_called_class();
+
+        foreach (static::get_classes() as $class) {
+            $headers[] = $fullclassname . '/' . $class;
+        }
+
+        return $headers;
+    }
+
+    /**
+     * Whether the value should be displayed or not.
+     *
+     * @param float $value
+     * @param string $subtype
+     * @return bool
+     */
+    public function should_be_displayed($value, $subtype) {
+        if ($value != static::get_max_value()) {
+            // Discrete values indicators are converted internally to 1 feature per indicator, we are only interested
+            // in showing the feature flagged with the max value.
+            return false;
+        }
+        return true;
+    }
+
+    /**
+     * Returns the value to display when the prediction is $value.
+     *
+     * @param float $value
+     * @param string $subtype
+     * @return string
+     */
+    public function get_display_value($value, $subtype = false) {
+
+        $displayvalue = array_search($subtype, static::get_classes(), false);
+
+        debugging('Please overwrite \core_analytics\local\indicator\discrete::get_display_value to show something ' .
+            'different than the default "' . $displayvalue . '"', DEBUG_DEVELOPER);
+
+        return $displayvalue;
+    }
+
+    /**
+     * get_display_style
+     *
+     * @param float $ignoredvalue
+     * @param string $ignoredsubtype
+     * @return int
+     */
+    public function get_display_style($ignoredvalue, $ignoredsubtype) {
+        // No style attached to indicators classes, they are what they are, a cat,
+        // a horse or a sandwich, they are not good or bad.
+        return \core_analytics\calculable::OUTCOME_NEUTRAL;
+    }
+
+    /**
+     * From calculated values to dataset features.
+     *
+     * One column for each class.
+     *
+     * @param float[] $calculatedvalues
+     * @return float[]
+     */
+    protected function to_features($calculatedvalues) {
+
+        $classes = static::get_classes();
+
+        foreach ($calculatedvalues as $sampleid => $calculatedvalue) {
+
+            // Using intval as it may come as a float from the db.
+            $classindex = array_search(intval($calculatedvalue), $classes, true);
+
+            if ($classindex === false && !is_null($calculatedvalue)) {
+                throw new \coding_exception(get_class($this) . ' calculated value "' . $calculatedvalue .
+                    '" is not one of its defined classes (' . json_encode($classes) . ')');
+            }
+
+            // We transform the calculated value into multiple features, one for each of the possible classes.
+            $features = array_fill(0, count($classes), 0);
+
+            // 1 to the selected value.
+            if (!is_null($calculatedvalue)) {
+                $features[$classindex] = 1;
+            }
+
+            $calculatedvalues[$sampleid] = $features;
+        }
+
+        return $calculatedvalues;
+    }
+
+    /**
+     * Validates the calculated value.
+     *
+     * @param float $calculatedvalue
+     * @return true
+     */
+    protected function validate_calculated_value($calculatedvalue) {
+
+        // Using intval as it may come as a float from the db.
+        if (!in_array(intval($calculatedvalue), static::get_classes())) {
+            throw new \coding_exception(get_class($this) . ' calculated value "' . $calculatedvalue .
+                '" is not one of its defined classes (' . json_encode(static::get_classes()) . ')');
+        }
+        return true;
+    }
+}

analytics/classes/local/indicator/linear.php

@@ -0,0 +1,147 @@
+<?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/>.
+
+/**
+ * Abstract linear indicator.
+ *
+ * @package   core_analytics
+ * @copyright 2017 David Monllao {@link http://www.davidmonllao.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+namespace core_analytics\local\indicator;
+
+defined('MOODLE_INTERNAL') || die();
+
+/**
+ * Abstract linear indicator.
+ *
+ * @package   core_analytics
+ * @copyright 2017 David Monllao {@link http://www.davidmonllao.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+abstract class linear extends base {
+
+    /**
+     * Set to false to avoid context features to be added as dataset features.
+     *
+     * @return bool
+     */
+    protected static function include_averages() {
+        return true;
+    }
+
+    /**
+     * get_feature_headers
+     *
+     * @return array
+     */
+    public static function get_feature_headers() {
+
+        $fullclassname = '\\' . get_called_class();
+
+        if (static::include_averages()) {
+            // The calculated value + context indicators.
+            $headers = array($fullclassname, $fullclassname . '/mean');
+        } else {
+            $headers = array($fullclassname);
+        }
+        return $headers;
+    }
+
+    /**
+     * Show only the main feature.
+     *
+     * @param float $value
+     * @param string $subtype
+     * @return bool
+     */
+    public function should_be_displayed($value, $subtype) {
+        if ($subtype != false) {
+            return false;
+        }
+        return true;
+    }
+
+    /**
+     * get_display_value
+     *
+     * @param float $value
+     * @param string $subtype
+     * @return string
+     */
+    public function get_display_value($value, $subtype = false) {
+        $diff = static::get_max_value() - static::get_min_value();
+        return round(100 * ($value - static::get_min_value()) / $diff) . '%';
+    }
+
+    /**
+     * get_calculation_outcome
+     *
+     * @param float $value
+     * @param string $subtype
+     * @return int
+     */
+    public function get_calculation_outcome($value, $subtype = false) {
+        if ($value < 0) {
+            return self::OUTCOME_NEGATIVE;
+        } else {
+            return self::OUTCOME_OK;
+        }
+    }
+
+    /**
+     * Converts the calculated values to a list of features for the dataset.
+     *
+     * @param array $calculatedvalues
+     * @return array
+     */
+    protected function to_features($calculatedvalues) {
+
+        // Null mean if all calculated values are null.
+        $nullmean = true;
+        foreach ($calculatedvalues as $value) {
+            if (!is_null($value)) {
+                // Early break, we don't want to spend a lot of time here.
+                $nullmean = false;
+                break;
+            }
+        }
+
+        if ($nullmean) {
+            $mean = null;
+        } else {
+            $mean = round(array_sum($calculatedvalues) / count($calculatedvalues), 2);
+        }
+
+        foreach ($calculatedvalues as $sampleid => $calculatedvalue) {
+
+            if (!is_null($calculatedvalue)) {
+                $calculatedvalue = round($calculatedvalue, 2);
+            }
+
+            if (static::include_averages()) {
+                $calculatedvalues[$sampleid] = array($calculatedvalue, $mean);
+            } else {
+                // Basically just convert the scalar to an array of scalars with a single value.
+                $calculatedvalues[$sampleid] = array($calculatedvalue);
+            }
+        }
+
+        // Returns each sample as an array of values, appending the mean to the calculated value.
+        return $calculatedvalues;
+    }
+}