Difference between revisions of "report/analytics/api"

Jump to: navigation, search
Line 3: Line 3:
 
== Main info ==
 
== Main info ==
  
User documentation here: https://docs.moodle.org/22/en/report/analytics/index
+
User documentation here: https://docs.moodle.org/22/en/report/engagement/index
  
 
'''IMPORTANT''' This page is a WIP and does not reflect the final state of the engagement analytics API!
 
'''IMPORTANT''' This page is a WIP and does not reflect the final state of the engagement analytics API!
Line 14: Line 14:
  
 
===File Layout===
 
===File Layout===
Indicators live in a folder in <tt>mod/analytics/indicator</tt>. The layout inside this folder follows the typical layout for a Moodle plugin. For example, inside the <tt>mod/analytics/indicator/myind</tt> folder we would have:
+
Indicators live in a folder in <tt>mod/engagement/indicator</tt>. The layout inside this folder follows the typical layout for a Moodle plugin. For example, inside the <tt>mod/engagement/indicator/myind</tt> folder we would have:
  
 
; indicator.class.php : Defines the <tt>indicator_myind</tt> class, which should extend the <tt>indicator</tt> base class.
 
; indicator.class.php : Defines the <tt>indicator_myind</tt> class, which should extend the <tt>indicator</tt> base class.
; renderer.php : This contains the definition of the <tt>analyticsindicator_myind_renderer</tt> class, which should extend the <tt>analyticsindicator_renderer</tt> base class.
+
; renderer.php : This contains the definition of the <tt>engagementindicator_myind_renderer</tt> class, which should extend the <tt>engagementindicator_renderer</tt> base class.
; thresholds_form.php : Defines the <tt>analyticsindicator_myind_thresholds_form</tt> which contains a function <tt>definition_inner</tt> for including on the report settings page.
+
; thresholds_form.php : Defines the <tt>engagementindicator_myind_thresholds_form</tt> which contains a function <tt>definition_inner</tt> for including on the report settings page.
; lang/en/analyticsindicator_myind.php : English language strings for this indicator. You can, of course, include other languages too. The language file must define at least the string giving the indicator a name, for example <tt>$string['pluginname'] = 'My Indicator';</tt>
+
; lang/en/engagementindicator_myind.php : English language strings for this indicator. You can, of course, include other languages too. The language file must define at least the string giving the indicator a name, for example <tt>$string['pluginname'] = 'My Indicator';</tt>
 
; db/install.xml, db/upgrade.php : For creating any database tables required, [[Installing_and_upgrading_plugin_database_tables|as normal]]. See [[#Database_tables]] below.
 
; db/install.xml, db/upgrade.php : For creating any database tables required, [[Installing_and_upgrading_plugin_database_tables|as normal]]. See [[#Database_tables]] below.
 
; db/access.php : Defines any capabilities required by this question type. This is very rarely needed.
 
; db/access.php : Defines any capabilities required by this question type. This is very rarely needed.
Line 47: Line 47:
 
</code>
 
</code>
  
The <tt>get_rawdata</tt> function is intended to do the heavy lifting part of the indicator. It'll do the lookups into the database to find out the raw data for the courses users. For example, this collects the counts of read/new/total/replied posts in the forum indicator. This function is called on by the parent class and is put into a cache. The cache has a configurable lifetime set in Site administration / ► Plugins / ► Activity modules / ► Engagement analytics. The setting is <tt>analytics|cachettl</tt> which defaults to 5 minutes. Larger sites may want to consider setting this to a larger number depending on the set of indicators they're using.
+
The <tt>get_rawdata</tt> function is intended to do the heavy lifting part of the indicator. It'll do the lookups into the database to find out the raw data for the courses users. For example, this collects the counts of read/new/total/replied posts in the forum indicator. This function is called on by the parent class and is put into a cache. The cache has a configurable lifetime set in Site administration / ► Plugins / ► Activity modules / ► Engagement analytics. The setting is <tt>engagement|cachettl</tt> which defaults to 5 minutes. Larger sites may want to consider setting this to a larger number depending on the set of indicators they're using.
  
 
The next step in the workflow takes that raw data (which comes from get_cache() unless there's no valid cache entry, which means get_rawdata is called for the data instead) and applies the course specific settings for that indicator. This is done in the <tt>calculate_risks</tt> function. This function will apply the settings set in the report settings page. This allows teachers to update the weightings / thresholds of indicators and see the new risk values without having to refetch raw data every time.
 
The next step in the workflow takes that raw data (which comes from get_cache() unless there's no valid cache entry, which means get_rawdata is called for the data instead) and applies the course specific settings for that indicator. This is done in the <tt>calculate_risks</tt> function. This function will apply the settings set in the report settings page. This allows teachers to update the weightings / thresholds of indicators and see the new risk values without having to refetch raw data every time.
Line 136: Line 136:
 
require_once(dirname(__FILE__).'/indicator.class.php');
 
require_once(dirname(__FILE__).'/indicator.class.php');
  
class analyticsindicator_random_thresholds_form {
+
class engagementindicator_random_thresholds_form {
 
     public function definition_inner(&$mform) {
 
     public function definition_inner(&$mform) {
 
         $defaults = indicator_login::get_defaults();
 
         $defaults = indicator_login::get_defaults();
         $mform->addElement('text', 'random_min', get_string('minimum', 'analyticsindicator_random'));
+
         $mform->addElement('text', 'random_min', get_string('minimum', 'engagementindicator_random'));
 
         $mform->setDefault("random_min", $defaults['min']);
 
         $mform->setDefault("random_min", $defaults['min']);
  
         $mform->addElement('text', 'random_max', get_string('maximum', 'analyticsindicator_random'));
+
         $mform->addElement('text', 'random_max', get_string('maximum', 'engagementindicator_random'));
 
         $mform->setDefault("random_max", $defaults['max']);
 
         $mform->setDefault("random_max", $defaults['max']);
 
     }
 
     }
Line 157: Line 157:
 
defined('MOODLE_INTERNAL') || die();
 
defined('MOODLE_INTERNAL') || die();
  
class analyticsindicator_random_renderer extends analyticsindicator_renderer {
+
class engagementindicator_random_renderer extends engagementindicator_renderer {
 
     public function user_report($data) {
 
     public function user_report($data) {
 
         $html = '';
 
         $html = '';
Line 165: Line 165:
 
             $html .= html_writer::end_tag('strong');
 
             $html .= html_writer::end_tag('strong');
 
             $html .= html_writer::empty_tag('br');
 
             $html .= html_writer::empty_tag('br');
             $html .= $this->output->help_icon('localrisk', 'analyticsindicator_random');
+
             $html .= $this->output->help_icon('localrisk', 'engagementindicator_random');
 
             $html .= html_writer::tag('span', 'Local risk: ' . $i->localrisk);
 
             $html .= html_writer::tag('span', 'Local risk: ' . $i->localrisk);
 
             $html .= html_writer::empty_tag('br');
 
             $html .= html_writer::empty_tag('br');

Revision as of 00:28, 16 August 2012

Moodle 2.2 This page describes the API used by the Engagement Analytics indicators and reporting mechanisms.

Main info

User documentation here: https://docs.moodle.org/22/en/report/engagement/index

IMPORTANT This page is a WIP and does not reflect the final state of the engagement analytics API!

The indicator's used by this plugin have been designed as sub-plugins to allow (and encourage) other developers to create their own indicators. Indicators could be developed to report on a wide range of things inside Moodle or even collect data from external systems to report on if desired.

Caching of raw data from different indicator plugins is automatically handled by the base indicator class so developers of new indicators don't need to worry about more expensive queries.

Indicator

File Layout

Indicators live in a folder in mod/engagement/indicator. The layout inside this folder follows the typical layout for a Moodle plugin. For example, inside the mod/engagement/indicator/myind folder we would have:

indicator.class.php 
Defines the indicator_myind class, which should extend the indicator base class.
renderer.php 
This contains the definition of the engagementindicator_myind_renderer class, which should extend the engagementindicator_renderer base class.
thresholds_form.php 
Defines the engagementindicator_myind_thresholds_form which contains a function definition_inner for including on the report settings page.
lang/en/engagementindicator_myind.php 
English language strings for this indicator. You can, of course, include other languages too. The language file must define at least the string giving the indicator a name, for example $string['pluginname'] = 'My Indicator';
db/install.xml, db/upgrade.php 
For creating any database tables required, as normal. See #Database_tables below.
db/access.php 
Defines any capabilities required by this question type. This is very rarely needed.

Functions

The indicator base class defines the following functions:

public function get_risk($userid, $courseid, $startdate = null, $enddate = null);
public function get_course_risks($startdate = null, $enddate = null);
private function get_risk_for_users($userids, $startdate, $enddate);
final private function get_cache();
final private function set_cache();
abstract protected function get_rawdata($startdate, $enddate);
abstract protected function calculate_risks(array $userids);
public function get_name();
protected function load_config();
public function save_config();

Except for the functions mentioned below, the rest of the ones mentioned above are not generally intended to be overridden in the indicators themselves.

For the development of any new indicator, the functions you must implement are the abstracted ones:

abstract protected function get_rawdata($startdate, $enddate);
abstract protected function calculate_risks(array $userids);

The get_rawdata function is intended to do the heavy lifting part of the indicator. It'll do the lookups into the database to find out the raw data for the courses users. For example, this collects the counts of read/new/total/replied posts in the forum indicator. This function is called on by the parent class and is put into a cache. The cache has a configurable lifetime set in Site administration / ► Plugins / ► Activity modules / ► Engagement analytics. The setting is engagement|cachettl which defaults to 5 minutes. Larger sites may want to consider setting this to a larger number depending on the set of indicators they're using.

The next step in the workflow takes that raw data (which comes from get_cache() unless there's no valid cache entry, which means get_rawdata is called for the data instead) and applies the course specific settings for that indicator. This is done in the calculate_risks function. This function will apply the settings set in the report settings page. This allows teachers to update the weightings / thresholds of indicators and see the new risk values without having to refetch raw data every time.

If you have any settings (and most indicators probably will), you'll probably need:

protected function load_config();

Which can be used to setup any default values you need for when a user hasn't input any on their own.

Examples

indicator_random

Return a random risk score for each user.

defined('MOODLE_INTERNAL') || die();
require_once(dirname(__FILE__).'/../indicator.class.php');
 
class indicator_random extends indicator {
    protected function get_rawdata($startdate, $enddate) {
        global $DB;
        $rawdata = array();
        $someusers = get_enrolled_users($this->context);
        foreach ($someusers as $user) {
            $rawdata[$user->id] = mt_rand(0,100);
        }
        return $rawdata;
    }
 
    protected function calculate_risks(array $userids) {
        $risks = array();
        foreach ($userids as $userid) {
            if (!isset($this->rawdata[$userid])) {
                $risk = new stdClass();
                $risk->risk = 0;
                $risk->info = 'No risk, user had no data collected.';
                $risks[$userid] = $risk;
            }
 
            $risk = new stdClass();
            $value = $this->rawdata[$userid];
            if ($value > $this->config['max']) {
                $value = $this->config['max'];
            } else if ($value < $this->config['min']) {
                $value = $this->config['min'];
            }
            $risk->risk = $value;
            $risk->info = 'Random risk calcualted.';
            $risks[$userid] = $risk;
        }
        return $risks;
    }
 
    protected function load_config() {
        parent::load_config();
        $defaults = $this->get_defaults();
        foreach ($defaults as $setting => $value) {
            if (!isset($this->config[$setting])) {
                $this->config[$setting] = $value;
            }
        }
    }
 
    public function get_defaults() {
        $defaults = array();
        $defaults['min'] = 5;
        $defaults['max'] = 20;
        return $defaults;
    }
}

Helper Functions

Indicator Thresholds

Thresholds and other settings that get applied in the calculate_risks stage can be added to an indicator in the thresholds_form.php file.

The settings added to the definition_inner function should have a name of the format: "<indicatorname>_<setting>". i.e. for the setting "e_loginsperweek" setting of the "login" indicator, the name would be "login_e_loginsperweek".

Example

thresholds_form.php :

<?php
defined('MOODLE_INTERNAL') || die();
 
require_once(dirname(__FILE__).'/../indicator.class.php');
require_once(dirname(__FILE__).'/indicator.class.php');
 
class engagementindicator_random_thresholds_form {
    public function definition_inner(&$mform) {
        $defaults = indicator_login::get_defaults();
        $mform->addElement('text', 'random_min', get_string('minimum', 'engagementindicator_random'));
        $mform->setDefault("random_min", $defaults['min']);
 
        $mform->addElement('text', 'random_max', get_string('maximum', 'engagementindicator_random'));
        $mform->setDefault("random_max", $defaults['max']);
    }
}

Indicator Renderer

The user report view which lists details from each indicator is defined in an indicators renderer file. If the user_report function is not overridden, the default renderer will simply display the risk score given by that indicator.

Example

<?php
defined('MOODLE_INTERNAL') || die();
 
class engagementindicator_random_renderer extends engagementindicator_renderer {
    public function user_report($data) {
        $html = '';
        foreach ($data->info as $i) {
            $html .= html_writer::start_tag('strong');
            $html .= html_writer::tag('span', $i->title);
            $html .= html_writer::end_tag('strong');
            $html .= html_writer::empty_tag('br');
            $html .= $this->output->help_icon('localrisk', 'engagementindicator_random');
            $html .= html_writer::tag('span', 'Local risk: ' . $i->localrisk);
            $html .= html_writer::empty_tag('br');
        }
        return $html;
    }

For the above example to work, the random indicator would need to be returning valid data in the...<TODO>

See also

User documentation: https://docs.moodle.org/22/en/report/analytics/index