Your IP : 192.168.165.1
<?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/>.
/**
* Base class for targets whose analysable is a course using user enrolments as samples.
*
* @package core_course
* @copyright 2019 Victor Deniz <victor@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
namespace core_course\analytics\target;
defined('MOODLE_INTERNAL') || die();
/**
* Base class for targets whose analysable is a course using user enrolments as samples.
*
* @package core_course
* @copyright 2019 Victor Deniz <victor@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
abstract class course_enrolments extends \core_analytics\local\target\binary {
/**
* @var string
*/
const MESSAGE_ACTION_NAME = 'studentmessage';
/**
* @var float
*/
const ENROL_ACTIVE_PERCENT_REQUIRED = 0.7;
/**
* Students in the course.
* @var int[]
*/
protected $students;
/**
* Returns the analyser class that should be used along with this target.
*
* @return string The full class name as a string
*/
public function get_analyser_class() {
return '\core\analytics\analyser\student_enrolments';
}
/**
* Only past stuff.
*
* @param \core_analytics\local\time_splitting\base $timesplitting
* @return bool
*/
public function can_use_timesplitting(\core_analytics\local\time_splitting\base $timesplitting): bool {
return ($timesplitting instanceof \core_analytics\local\time_splitting\before_now);
}
/**
* Overwritten to show a simpler language string.
*
* @param int $modelid
* @param \context $context
* @return string
*/
public function get_insight_subject(int $modelid, \context $context) {
return get_string('studentsatriskincourse', 'course', $context->get_context_name(false));
}
/**
* Returns the body message for the insight.
*
* @param \context $context
* @param string $contextname
* @param \stdClass $user
* @param \moodle_url $insighturl
* @return string[] The plain text message and the HTML message
*/
public function get_insight_body(\context $context, string $contextname, \stdClass $user, \moodle_url $insighturl): array {
global $OUTPUT;
$a = (object)['coursename' => $contextname, 'userfirstname' => $user->firstname];
$fullmessage = get_string('studentsatriskinfomessage', 'course', $a) . PHP_EOL . PHP_EOL . $insighturl->out(false);
$fullmessagehtml = $OUTPUT->render_from_template('core_analytics/insight_info_message',
['url' => $insighturl->out(false), 'insightinfomessage' => get_string('studentsatriskinfomessage', 'course', $a)]
);
return [$fullmessage, $fullmessagehtml];
}
/**
* Discards courses that are not yet ready to be used for training or prediction.
*
* @param \core_analytics\analysable $course
* @param bool $fortraining
* @return true|string
*/
public function is_valid_analysable(\core_analytics\analysable $course, $fortraining = true) {
if (!$course->was_started()) {
return get_string('coursenotyetstarted', 'course');
}
if (!$fortraining && !$course->get_course_data()->visible) {
return get_string('hiddenfromstudents');
}
if (!$this->students = $course->get_students()) {
return get_string('nocoursestudents', 'course');
}
if (!course_format_uses_sections($course->get_course_data()->format)) {
// We can not split activities in time ranges.
return get_string('nocoursesections', 'course');
}
if ($course->get_end() == 0) {
// We require time end to be set.
return get_string('nocourseendtime', 'course');
}
if ($course->get_end() < $course->get_start()) {
return get_string('errorendbeforestart', 'course');
}
// A course that lasts longer than 1 year probably have wrong start or end dates.
if ($course->get_end() - $course->get_start() > (YEARSECS + (WEEKSECS * 4))) {
return get_string('coursetoolong', 'course');
}
// Finished courses can not be used to get predictions.
if (!$fortraining && $course->is_finished()) {
return get_string('coursealreadyfinished', 'course');
}
if ($fortraining) {
// Ongoing courses data can not be used to train.
if (!$course->is_finished()) {
return get_string('coursenotyetfinished', 'course');
}
}
return true;
}
/**
* Discard student enrolments that are invalid.
*
* Note that this method assumes that the target is only interested in enrolments that are/were active
* between the current course start and end times. Targets interested in predicting students at risk before
* their enrolment start and targets interested in getting predictions for students whose enrolment already
* finished should overwrite this method as these students are discarded by this method.
*
* @param int $sampleid
* @param \core_analytics\analysable $course
* @param bool $fortraining
* @return bool
*/
public function is_valid_sample($sampleid, \core_analytics\analysable $course, $fortraining = true) {
$now = time();
$userenrol = $this->retrieve('user_enrolments', $sampleid);
if ($userenrol->timeend && $course->get_start() > $userenrol->timeend) {
// Discard enrolments which time end is prior to the course start. This should get rid of
// old user enrolments that remain on the course.
return false;
}
$limit = $course->get_start() - (YEARSECS + (WEEKSECS * 4));
if (($userenrol->timestart && $userenrol->timestart < $limit) ||
(!$userenrol->timestart && $userenrol->timecreated < $limit)) {
// Following what we do in is_valid_analysable, we will discard enrolments that last more than 1 academic year
// because they have incorrect start and end dates or because they are reused along multiple years
// without removing previous academic years students. This may not be very accurate because some courses
// can last just some months, but it is better than nothing.
return false;
}
if ($course->get_end()) {
if (($userenrol->timestart && $userenrol->timestart > $course->get_end()) ||
(!$userenrol->timestart && $userenrol->timecreated > $course->get_end())) {
// Discard user enrolments that start after the analysable official end.
return false;
}
}
if ($now < $userenrol->timestart && $userenrol->timestart) {
// Discard enrolments whose start date is after now (no need to check timecreated > $now :P).
return false;
}
if (!$fortraining && $userenrol->timeend && $userenrol->timeend < $now) {
// We don't want to generate predictions for finished enrolments.
return false;
}
return true;
}
/**
* prediction_actions
*
* @param \core_analytics\prediction $prediction
* @param bool $includedetailsaction
* @param bool $isinsightuser
* @return \core_analytics\prediction_action[]
*/
public function prediction_actions(\core_analytics\prediction $prediction, $includedetailsaction = false,
$isinsightuser = false) {
$actions = array();
$sampledata = $prediction->get_sample_data();
$studentid = $sampledata['user']->id;
// View outline report.
$url = new \moodle_url('/report/outline/user.php', array('id' => $studentid, 'course' => $sampledata['course']->id,
'mode' => 'outline'));
$pix = new \pix_icon('i/report', get_string('outlinereport'));
$actions[] = new \core_analytics\prediction_action('viewoutlinereport', $prediction, $url, $pix,
get_string('outlinereport'), false, ['target' => '_blank']);
return array_merge(parent::prediction_actions($prediction, $includedetailsaction, $isinsightuser), $actions);
}
/**
* Suggested bulk actions for a user.
*
* @param \core_analytics\prediction[] $predictions List of predictions suitable for the bulk actions to use.
* @return \core_analytics\bulk_action[] The list of bulk actions.
*/
public function bulk_actions(array $predictions) {
$actions = [];
$userids = [];
foreach ($predictions as $prediction) {
$sampledata = $prediction->get_sample_data();
$userid = $sampledata['user']->id;
// Indexed by prediction id because we want the predictionid-userid
// mapping later when sending the message.
$userids[$prediction->get_prediction_data()->id] = $userid;
}
// Send a message for all the students.
$attrs = array(
'data-bulk-sendmessage' => '1',
'data-prediction-to-user-id' => json_encode($userids)
);
$actions[] = new \core_analytics\bulk_action(self::MESSAGE_ACTION_NAME, new \moodle_url(''),
new \pix_icon('t/message', get_string('sendmessage', 'message')),
get_string('sendmessage', 'message'), true, $attrs);
return array_merge($actions, parent::bulk_actions($predictions));
}
/**
* Adds the JS required to run the bulk actions.
*/
public function add_bulk_actions_js() {
global $PAGE;
$PAGE->requires->js_call_amd('report_insights/message_users', 'init',
['.insights-bulk-actions', self::MESSAGE_ACTION_NAME]);
parent::add_bulk_actions_js();
}
/**
* Is/was this user enrolment active during most of the analysis interval?
*
* This method discards enrolments that were not active during most of the analysis interval. It is
* important to discard these enrolments because the indicator calculations can lead to misleading
* results.
*
* Note that this method assumes that the target is interested in enrolments that are/were active
* during the analysis interval. Targets interested in predicting students at risk before
* their enrolment start should not call this method. Similarly, targets interested in getting
* predictions for students whose enrolment already finished should not call this method either.
*
* @param int $sampleid The id of the sample that is being calculated
* @param int $starttime The analysis interval start time
* @param int $endtime The analysis interval end time
* @return bool
*/
protected function enrolment_active_during_analysis_time(int $sampleid, int $starttime, int $endtime) {
$userenrol = $this->retrieve('user_enrolments', $sampleid);
if (!empty($userenrol->timestart)) {
$enrolstart = $userenrol->timestart;
} else {
// This is always set.
$enrolstart = $userenrol->timecreated;
}
if (!empty($userenrol->timeend)) {
$enrolend = $userenrol->timeend;
} else {
// Default to tre end of the world.
$enrolend = PHP_INT_MAX;
}
if ($endtime && $endtime < $enrolstart) {
/* The enrolment starts/ed after the analysis end time.
* |=========| |----------|
* A start A end E start E end
*/
return false;
}
if ($starttime && $enrolend < $starttime) {
/* The enrolment finishes/ed before the analysis start time.
* |---------| |==========|
* E start E end A start A end
*/
return false;
}
// Now we want to discard enrolments that were not active for most of the analysis interval. We
// need both a $starttime and an $endtime to calculate this.
if (!$starttime) {
// Early return. Nothing to discard if there is no start.
return true;
}
if (!$endtime) {
// We can not calculate in relative terms (percent) how far from the analysis start time
// this enrolment start is/was.
return true;
}
if ($enrolstart < $starttime && $endtime < $enrolend) {
/* The enrolment is active during all the analysis time.
* |-----------------------------|
* |========|
* E start A start A end E end
*/
return true;
}
// If we reach this point is because the enrolment is only active for a portion of the analysis interval.
// Therefore, we check that it was active for most of the analysis interval, a self::ENROL_ACTIVE_PERCENT_REQUIRED.
if ($starttime <= $enrolstart && $enrolend <= $endtime) {
/* |=============================|
* |--------|
* A start E start E end A end
*/
$activeenrolduration = $enrolend - $enrolstart;
} else if ($enrolstart <= $starttime && $enrolend <= $endtime) {
/* |===================|
* |------------------|
* E start A start E end A end
*/
$activeenrolduration = $enrolend - $starttime;
} else if ($starttime <= $enrolstart && $endtime <= $enrolend) {
/* |===================|
* |------------------|
* A start E start A end E end
*/
$activeenrolduration = $endtime - $enrolstart;
}
$analysisduration = $endtime - $starttime;
if (floatval($activeenrolduration) / floatval($analysisduration) < self::ENROL_ACTIVE_PERCENT_REQUIRED) {
// The student was not enroled in the course for most of the analysis interval.
return false;
}
// We happily return true if the enrolment was active for more than self::ENROL_ACTIVE_PERCENT_REQUIRED of
// the analysis interval.
return true;
}
}