analytics/classes/calculable.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/>.
  16
  17 /**
  18  * Calculable dataset items abstract class.
  19  *
  20  * @package   core_analytics
  21  * @copyright 2016 David Monllao {@link http://www.davidmonllao.com}
  22  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23  */
  24
  25 namespace core_analytics;
  26
  27 defined('MOODLE_INTERNAL') || die();
  28
  29 /**
  30  * Calculable dataset items abstract class.
  31  *
  32  * @package   core_analytics
  33  * @copyright 2016 David Monllao {@link http://www.davidmonllao.com}
  34  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  35  */
  36 abstract class calculable {
  37
  38     /**
  39      * Neutral calculation outcome.
  40      */
  41     const OUTCOME_NEUTRAL = 0;
  42
  43     /**
  44      * Very positive calculation outcome.
  45      */
  46     const OUTCOME_VERY_POSITIVE = 1;
  47
  48     /**
  49      * Positive calculation outcome.
  50      */
  51     const OUTCOME_OK = 2;
  52
  53     /**
  54      * Negative calculation outcome.
  55      */
  56     const OUTCOME_NEGATIVE = 3;
  57
  58     /**
  59      * Very negative calculation outcome.
  60      */
  61     const OUTCOME_VERY_NEGATIVE = 4;
  62
  63     /**
  64      * @var array[]
  65      */
  66     protected $sampledata = array();
  67
  68     /**
  69      * @var \core_analytics\calculation_info|null
  70      */
  71     protected $calculationinfo = null;
  72
  73     /**
  74      * Returns a lang_string object representing the name for the indicator or target.
  75      *
  76      * Used as column identificator.
  77      *
  78      * If there is a corresponding '_help' string this will be shown as well.
  79      *
  80      * @return \lang_string
  81      */
  82     public static abstract function get_name() : \lang_string;
  83
  84     /**
  85      * The class id is the calculable class full qualified class name.
  86      *
  87      * @return string
  88      */
  89     public function get_id() {
  90         // Using get_class as get_component_classes_in_namespace returns double escaped fully qualified class names.
  91         return '\\' . get_class($this);
  92     }
  93
  94     /**
  95      * add_sample_data
  96      *
  97      * @param array $data
  98      * @return void
  99      */
 100     public function add_sample_data($data) {
 101         $this->sampledata = $this->array_merge_recursive_keep_keys($this->sampledata, $data);
 102     }
 103
 104     /**
 105      * clear_sample_data
 106      *
 107      * @return void
 108      */
 109     public function clear_sample_data() {
 110         $this->sampledata = array();
 111     }
 112
 113     /**
 114      * Returns the visible value of the calculated value.
 115      *
 116      * @param float $value
 117      * @param string|false $subtype
 118      * @return string
 119      */
 120     public function get_display_value($value, $subtype = false) {
 121         return $value;
 122     }
 123
 124     /**
 125      * Returns how good the calculated value is.
 126      *
 127      * Use one of \core_analytics\calculable::OUTCOME_* values.
 128      *
 129      * @param float $value
 130      * @param string|false $subtype
 131      * @return int
 132      */
 133     abstract public function get_calculation_outcome($value, $subtype = false);
 134
 135     /**
 136      * Retrieve the specified element associated to $sampleid.
 137      *
 138      * @param string $elementname
 139      * @param int $sampleid
 140      * @return \stdClass|false An \stdClass object or false if it can not be found.
 141      */
 142     protected function retrieve($elementname, $sampleid) {
 143         if (empty($this->sampledata[$sampleid]) || empty($this->sampledata[$sampleid][$elementname])) {
 144             // We don't throw an exception because indicators should be able to
 145             // try multiple tables until they find something they can use.
 146             return false;
 147         }
 148         return $this->sampledata[$sampleid][$elementname];
 149     }
 150
 151     /**
 152      * Adds info related to the current calculation for later use when generating insights.
 153      *
 154      * Note that the data in $info array is reused across multiple samples, if you want to add data just for this
 155      * sample you can use the sample id as key.
 156      *
 157      * Please, note that you should be careful with how much data you add here as it can kill the server memory.
 158      *
 159      * @param  int      $sampleid       The sample id this data is associated with
 160      * @param  array    $info           The data. Indexed by an id unique across the site. E.g. an activity id.
 161      * @return null
 162      */
 163     protected final function add_shared_calculation_info(int $sampleid, array $info) {
 164         if (is_null($this->calculationinfo)) {
 165             // Lazy loading.
 166             $this->calculationinfo = new \core_analytics\calculation_info();
 167         }
 168
 169         $this->calculationinfo->add_shared($sampleid, $info);
 170     }
 171
 172     /**
 173      * Stores in MUC the previously added data and it associates it to the provided $calculable.
 174      *
 175      * Flagged as final as we don't want people to extend this, it is likely to be moved to \core_analytics\calculable
 176      *
 177      * @param  \core_analytics\local\time_splitting\base $timesplitting
 178      * @param  int                                       $rangeindex
 179      * @return null
 180      */
 181     public final function save_calculation_info(\core_analytics\local\time_splitting\base $timesplitting, int $rangeindex) {
 182         if (!is_null($this->calculationinfo)) {
 183             $this->calculationinfo->save($this, $timesplitting, $rangeindex);
 184         }
 185     }
 186
 187     /**
 188      * Returns the number of weeks a time range contains.
 189      *
 190      * Useful for calculations that depend on the time range duration. Note that it returns
 191      * a float, rounding the float may lead to inaccurate results.
 192      *
 193      * @param int $starttime
 194      * @param int $endtime
 195      * @return float
 196      */
 197     protected function get_time_range_weeks_number($starttime, $endtime) {
 198         if ($endtime <= $starttime) {
 199             throw new \coding_exception('End time timestamp should be greater than start time.');
 200         }
 201
 202         $starttimedt = new \DateTime();
 203         $starttimedt->setTimestamp($starttime);
 204         $starttimedt->setTimezone(new \DateTimeZone('UTC'));
 205         $endtimedt = new \DateTime();
 206         $endtimedt->setTimestamp($endtime);
 207         $endtimedt->setTimezone(new \DateTimeZone('UTC'));
 208
 209         $diff = $endtimedt->getTimestamp() - $starttimedt->getTimestamp();
 210         return $diff / WEEKSECS;
 211     }
 212
 213     /**
 214      * Limits the calculated value to the minimum and maximum values.
 215      *
 216      * @param float $calculatedvalue
 217      * @return float|null
 218      */
 219     protected function limit_value($calculatedvalue) {
 220         return max(min($calculatedvalue, static::get_max_value()), static::get_min_value());
 221     }
 222
 223     /**
 224      * Classifies the provided value into the provided range according to the ranges predicates.
 225      *
 226      * Use:
 227      * - eq as 'equal'
 228      * - ne as 'not equal'
 229      * - lt as 'lower than'
 230      * - le as 'lower or equal than'
 231      * - gt as 'greater than'
 232      * - ge as 'greater or equal than'
 233      *
 234      * @throws \coding_exception
 235      * @param int|float $value
 236      * @param array $ranges e.g. [ ['lt', 20], ['ge', 20] ]
 237      * @return float
 238      */
 239     protected function classify_value($value, $ranges) {
 240
 241         // To automatically return calculated values from min to max values.
 242         $rangeweight = (static::get_max_value() - static::get_min_value()) / (count($ranges) - 1);
 243
 244         foreach ($ranges as $key => $range) {
 245
 246             $match = false;
 247
 248             if (count($range) != 2) {
 249                 throw new \coding_exception('classify_value() $ranges array param should contain 2 items, the predicate ' .
 250                     'e.g. greater (gt), lower or equal (le)... and the value.');
 251             }
 252
 253             list($predicate, $rangevalue) = $range;
 254
 255             switch ($predicate) {
 256                 case 'eq':
 257                     if ($value == $rangevalue) {
 258                         $match = true;
 259                     }
 260                     break;
 261                 case 'ne':
 262                     if ($value != $rangevalue) {
 263                         $match = true;
 264                     }
 265                     break;
 266                 case 'lt':
 267                     if ($value < $rangevalue) {
 268                         $match = true;
 269                     }
 270                     break;
 271                 case 'le':
 272                     if ($value <= $rangevalue) {
 273                         $match = true;
 274                     }
 275                     break;
 276                 case 'gt':
 277                     if ($value > $rangevalue) {
 278                         $match = true;
 279                     }
 280                     break;
 281                 case 'ge':
 282                     if ($value >= $rangevalue) {
 283                         $match = true;
 284                     }
 285                     break;
 286                 default:
 287                     throw new \coding_exception('Unrecognised predicate ' . $predicate . '. Please use eq, ne, lt, le, ge or gt.');
 288             }
 289
 290             // Calculate and return a linear calculated value for the provided value.
 291             if ($match) {
 292                 return round(static::get_min_value() + ($rangeweight * $key), 2);
 293             }
 294         }
 295
 296         throw new \coding_exception('The provided value "' . $value . '" can not be fit into any of the provided ranges, you ' .
 297             'should provide ranges for all possible values.');
 298     }
 299
 300     /**
 301      * Merges arrays recursively keeping the same keys the original arrays have.
 302      *
 303      * @link http://php.net/manual/es/function.array-merge-recursive.php#114818
 304      * @return array
 305      */
 306     private function array_merge_recursive_keep_keys() {
 307         $arrays = func_get_args();
 308         $base = array_shift($arrays);
 309
 310         foreach ($arrays as $array) {
 311             reset($base);
 312             foreach ($array as $key => $value) {
 313                 if (is_array($value) && !empty($base[$key]) && is_array($base[$key])) {
 314                     $base[$key] = $this->array_merge_recursive_keep_keys($base[$key], $value);
 315                 } else {
 316                     if (isset($base[$key]) && is_int($key)) {
 317                         $key++;
 318                     }
 319                     $base[$key] = $value;
 320                 }
 321             }
 322         }
 323
 324         return $base;
 325     }
 326 }