Proyectos de Subversion Moodle

<?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/>.

/**

 * Contains logic class and interface for the grading evaluation plugin "Comparison

 * with the best assessment".

 *

 * @package    workshopeval

 * @subpackage best

 * @copyright  2009 David Mudrak <david.mudrak@gmail.com>

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

defined('MOODLE_INTERNAL') || die();

require_once(__DIR__ . '/../lib.php');  // interface definition

require_once($CFG->libdir . '/gradelib.php');

/**

 * Defines the computation login of the grading evaluation subplugin

 */

class workshop_best_evaluation extends workshop_evaluation {

    /** @var the recently used settings in this workshop */

    protected $settings;

    /**

     * Constructor

     *

     * @param workshop $workshop The workshop api instance

     * @return void

     */

    public function __construct(workshop $workshop) {

        global $DB;

        $this->workshop = $workshop;

        $this->settings = $DB->get_record('workshopeval_best_settings', array('workshopid' => $this->workshop->id));

    }

    /**

     * Calculates the grades for assessment and updates 'gradinggrade' fields in 'workshop_assessments' table

     *

     * This function relies on the grading strategy subplugin providing get_assessments_recordset() method.

     * {@see self::process_assessments()} for the required structure of the recordset.

     *

     * @param stdClass $settings       The settings for this round of evaluation

     * @param null|int|array $restrict If null, update all reviewers, otherwise update just grades for the given reviewers(s)

     *

     * @return void

     */

    public function update_grading_grades(stdclass $settings, $restrict=null) {

        global $DB;

        // Remember the recently used settings for this workshop.

        if (empty($this->settings)) {

            $record = new stdclass();

            $record->workshopid = $this->workshop->id;

            $record->comparison = $settings->comparison;

            $DB->insert_record('workshopeval_best_settings', $record);

        } elseif ($this->settings->comparison != $settings->comparison) {

            $DB->set_field('workshopeval_best_settings', 'comparison', $settings->comparison,

                    array('workshopid' => $this->workshop->id));

        }

        // Get the grading strategy instance.

        $grader = $this->workshop->grading_strategy_instance();

        // get the information about the assessment dimensions

        $diminfo = $grader->get_dimensions_info();

        // fetch a recordset with all assessments to process

        $rs         = $grader->get_assessments_recordset($restrict);

        $batch      = array();    // will contain a set of all assessments of a single submission

        $previous   = null;       // a previous record in the recordset

        foreach ($rs as $current) {

            if (is_null($previous)) {

                // we are processing the very first record in the recordset

                $previous = $current;

            }

            if ($current->submissionid == $previous->submissionid) {

                $batch[] = $current;

            } else {

                // process all the assessments of a single submission

                $this->process_assessments($batch, $diminfo, $settings);

                // start with a new batch to be processed

                $batch = array($current);

                $previous = $current;

            }

        }

        // do not forget to process the last batch!

        $this->process_assessments($batch, $diminfo, $settings);

        $rs->close();

    }

    /**

     * Returns an instance of the form to provide evaluation settings.

     *

     * @return workshop_best_evaluation_settings_form

     */

    public function get_settings_form(moodle_url $actionurl=null) {

        $customdata['workshop'] = $this->workshop;

        $customdata['current'] = $this->settings;

        $attributes = array('class' => 'evalsettingsform best');

        return new workshop_best_evaluation_settings_form($actionurl, $customdata, 'post', '', $attributes);

    }

    /**

     * Delete all data related to a given workshop module instance

     *

     * @see workshop_delete_instance()

     * @param int $workshopid id of the workshop module instance being deleted

     * @return void

     */

    public static function delete_instance($workshopid) {

        global $DB;

        $DB->delete_records('workshopeval_best_settings', array('workshopid' => $workshopid));

    }

    ////////////////////////////////////////////////////////////////////////////////

    // Internal methods                                                           //

    ////////////////////////////////////////////////////////////////////////////////

    /**

     * Given a list of all assessments of a single submission, updates the grading grades in database

     *

     * @param array $assessments of stdclass (->assessmentid ->assessmentweight ->reviewerid ->gradinggrade ->submissionid ->dimensionid ->grade)

     * @param array $diminfo of stdclass (->id ->weight ->max ->min)

     * @param stdClass grading evaluation settings

     * @return void

     */

    protected function process_assessments(array $assessments, array $diminfo, stdclass $settings) {

        global $DB;

        if (empty($assessments)) {

            return;

        }

        // reindex the passed flat structure to be indexed by assessmentid

        $assessments = $this->prepare_data_from_recordset($assessments);

        // normalize the dimension grades to the interval 0 - 100

        $assessments = $this->normalize_grades($assessments, $diminfo);

        // get a hypothetical average assessment

        $average = $this->average_assessment($assessments);

        // if unable to calculate the average assessment, set the grading grades to null

        if (is_null($average)) {

            foreach ($assessments as $asid => $assessment) {

                if (!is_null($assessment->gradinggrade)) {

                    $DB->set_field('workshop_assessments', 'gradinggrade', null, array('id' => $asid));

                }

            }

            return;

        }

        // calculate variance of dimension grades

        $variances = $this->weighted_variance($assessments);

        foreach ($variances as $dimid => $variance) {

            $diminfo[$dimid]->variance = $variance;

        }

        // for every assessment, calculate its distance from the average one

        $distances = array();

        foreach ($assessments as $asid => $assessment) {

            $distances[$asid] = $this->assessments_distance($assessment, $average, $diminfo, $settings);

        }

        // identify the best assessments - that is those with the shortest distance from the best assessment

        $bestids = moodle_array_keys_filter($distances, min($distances));

        // for every assessment, calculate its distance from the nearest best assessment

        $distances = array();

        foreach ($bestids as $bestid) {

            $best = $assessments[$bestid];

            foreach ($assessments as $asid => $assessment) {

                $d = $this->assessments_distance($assessment, $best, $diminfo, $settings);

                if (!is_null($d) and (!isset($distances[$asid]) or $d < $distances[$asid])) {

                    $distances[$asid] = $d;

                }

            }

        }

        // calculate the grading grade

        foreach ($distances as $asid => $distance) {

            $gradinggrade = (100 - $distance);

            if ($gradinggrade < 0) {

                $gradinggrade = 0;

            }

            if ($gradinggrade > 100) {

                $gradinggrade = 100;

            }

            $grades[$asid] = grade_floatval($gradinggrade);

        }

        // if the new grading grade differs from the one stored in database, update it

        // we do not use set_field() here because we want to pass $bulk param

        foreach ($grades as $assessmentid => $grade) {

            if (grade_floats_different($grade, $assessments[$assessmentid]->gradinggrade)) {

                // the value has changed

                $record = new stdclass();

                $record->id = $assessmentid;

                $record->gradinggrade = grade_floatval($grade);

                // do not set timemodified here, it contains the timestamp of when the form was

                // saved by the peer reviewer, not when it was aggregated

                $DB->update_record('workshop_assessments', $record, true);  // bulk operations expected

            }

        }

        // done. easy, heh? ;-)

    }

    /**

     * Prepares a structure of assessments and given grades

     *

     * @param array $assessments batch of recordset items as returned by the grading strategy

     * @return array

     */

    protected function prepare_data_from_recordset($assessments) {

        $data = array();    // to be returned

        foreach ($assessments as $a) {

            $id = $a->assessmentid; // just an abbreviation

            if (!isset($data[$id])) {

                $data[$id] = new stdclass();

                $data[$id]->assessmentid = $a->assessmentid;

                $data[$id]->weight       = $a->assessmentweight;

                $data[$id]->reviewerid   = $a->reviewerid;

                $data[$id]->gradinggrade = $a->gradinggrade;

                $data[$id]->submissionid = $a->submissionid;

                $data[$id]->dimgrades    = array();

            }

            $data[$id]->dimgrades[$a->dimensionid] = $a->grade;

        }

        return $data;

    }

    /**

     * Normalizes the dimension grades to the interval 0.00000 - 100.00000

     *

     * Note: this heavily relies on PHP5 way of handling references in array of stdclasses. Hopefully

     * it will not change again soon.

     *

     * @param array $assessments of stdclass as returned by {@see self::prepare_data_from_recordset()}

     * @param array $diminfo of stdclass

     * @return array of stdclass with the same structure as $assessments

     */

    protected function normalize_grades(array $assessments, array $diminfo) {

        foreach ($assessments as $asid => $assessment) {

            foreach ($assessment->dimgrades as $dimid => $dimgrade) {

                $dimmin = $diminfo[$dimid]->min;

                $dimmax = $diminfo[$dimid]->max;

                if ($dimmin == $dimmax) {

                    $assessment->dimgrades[$dimid] = grade_floatval($dimmax);

                } else {

                    $assessment->dimgrades[$dimid] = grade_floatval(($dimgrade - $dimmin) / ($dimmax - $dimmin) * 100);

                }

            }

        }

        return $assessments;

    }

    /**

     * Given a set of a submission's assessments, returns a hypothetical average assessment

     *

     * The passed structure must be array of assessments objects with ->weight and ->dimgrades properties.

     * Returns null if all passed assessments have zero weight as there is nothing to choose

     * from then.

     *

     * @param array $assessments as prepared by {@link self::prepare_data_from_recordset()}

     * @return null|stdClass

     */

    protected function average_assessment(array $assessments) {

        $sumdimgrades = array();

        foreach ($assessments as $a) {

            foreach ($a->dimgrades as $dimid => $dimgrade) {

                if (!isset($sumdimgrades[$dimid])) {

                    $sumdimgrades[$dimid] = 0;

                }

                $sumdimgrades[$dimid] += $dimgrade * $a->weight;

            }

        }

        $sumweights = 0;

        foreach ($assessments as $a) {

            $sumweights += $a->weight;

        }

        if ($sumweights == 0) {

            // unable to calculate average assessment

            return null;

        }

        $average = new stdclass();

        $average->dimgrades = array();

        foreach ($sumdimgrades as $dimid => $sumdimgrade) {

            $average->dimgrades[$dimid] = grade_floatval($sumdimgrade / $sumweights);

        }

        return $average;

    }

    /**

     * Given a set of a submission's assessments, returns standard deviations of all their dimensions

     *

     * The passed structure must be array of assessments objects with at least ->weight

     * and ->dimgrades properties. This implementation uses weighted incremental algorithm as

     * suggested in "D. H. D. West (1979). Communications of the ACM, 22, 9, 532-535:

     * Updating Mean and Variance Estimates: An Improved Method"

     * {@link http://en.wikipedia.org/wiki/Algorithms_for_calculating_variance#Weighted_incremental_algorithm}

     *

     * @param array $assessments as prepared by {@link self::prepare_data_from_recordset()}

     * @return null|array indexed by dimension id

     */

    protected function weighted_variance(array $assessments) {

        $first = reset($assessments);

        if (empty($first)) {

            return null;

        }

        $dimids = array_keys($first->dimgrades);

        $asids  = array_keys($assessments);

        $vars   = array();  // to be returned

        foreach ($dimids as $dimid) {

            $n = 0;

            $s = 0;

            $sumweight = 0;

            foreach ($asids as $asid) {

                $x = $assessments[$asid]->dimgrades[$dimid];    // value (data point)

                $weight = $assessments[$asid]->weight;          // the values' weight

                if ($weight == 0) {

                    continue;

                }

                if ($n == 0) {

                    $n = 1;

                    $mean = $x;

                    $s = 0;

                    $sumweight = $weight;

                } else {

                    $n++;

                    $temp = $weight + $sumweight;

                    $q = $x - $mean;

                    $r = $q * $weight / $temp;

                    $s = $s + $sumweight * $q * $r;

                    $mean = $mean + $r;

                    $sumweight = $temp;

                }

            }

            if ($sumweight > 0 and $n > 1) {

                // for the sample: $vars[$dimid] = ($s * $n) / (($n - 1) * $sumweight);

                // for the population:

                $vars[$dimid] = $s / $sumweight;

            } else {

                $vars[$dimid] = null;

            }

        }

        return $vars;

    }

    /**

     * Measures the distance of the assessment from a referential one

     *

     * The passed data structures must contain ->dimgrades property. The referential

     * assessment is supposed to be close to the average assessment. All dimension grades are supposed to be

     * normalized to the interval 0 - 100.

     * Returned value is rounded to 4 valid decimals to prevent some rounding issues - see the unit test

     * for an example.

     *

     * @param stdClass $assessment the assessment being measured

     * @param stdClass $referential assessment

     * @param array $diminfo of stdclass(->weight ->min ->max ->variance) indexed by dimension id

     * @param stdClass $settings

     * @return float|null rounded to 4 valid decimals

     */

    protected function assessments_distance(stdclass $assessment, stdclass $referential, array $diminfo, stdclass $settings) {

        $distance = 0;

        $n = 0;

        foreach (array_keys($assessment->dimgrades) as $dimid) {

            $agrade = $assessment->dimgrades[$dimid];

            $rgrade = $referential->dimgrades[$dimid];

            $var    = $diminfo[$dimid]->variance;

            $weight = $diminfo[$dimid]->weight;

            $n     += $weight;

            // variations very close to zero are too sensitive to a small change of data values

            $var = max($var, 0.01);

            if ($agrade != $rgrade) {

                $absdelta   = abs($agrade - $rgrade);

                $reldelta   = pow($agrade - $rgrade, 2) / ($settings->comparison * $var);

                $distance  += $absdelta * $reldelta * $weight;

            }

        }

        if ($n > 0) {

            // average distance across all dimensions

            return round($distance / $n, 4);

        } else {

            return null;

        }

    }

}

/**

 * Represents the settings form for this plugin.

 */

class workshop_best_evaluation_settings_form extends workshop_evaluation_settings_form {

    /**

     * Defines specific fields for this evaluation method.

     */

    protected function definition_sub() {

        $mform = $this->_form;

        $plugindefaults = get_config('workshopeval_best');

        $current = $this->_customdata['current'];

        $options = array();

        for ($i = 9; $i >= 1; $i = $i-2) {

            $options[$i] = get_string('comparisonlevel' . $i, 'workshopeval_best');

        }

        $mform->addElement('select', 'comparison', get_string('comparison', 'workshopeval_best'), $options);

        $mform->addHelpButton('comparison', 'comparison', 'workshopeval_best');

        $mform->setDefault('comparison', $plugindefaults->comparison);

        $this->set_data($current);

    }

}