[Summary view]

   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  }