Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 39 and 401] [Versions 401 and 402] [Versions 401 and 403]

Allocates the submissions randomly

Copyright: 2009 David Mudrak <david.mudrak@gmail.com>
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 798 lines (37 kb)
Included or required: 2 times
Referenced: 0 times
Includes or requires: 3 files
 mod/workshop/locallib.php
 mod/workshop/allocation/lib.php
 mod/workshop/allocation/random/settings_form.php

Defines 2 classes


Class: workshop_random_allocator  - X-Ref

Allocates the submissions randomly

__construct(workshop $workshop)   X-Ref

param: workshop $workshop Workshop API object

init()   X-Ref
Allocate submissions as requested by user

return: workshop_allocation_result

execute(workshop_random_allocator_setting $settings, workshop_allocation_result $result)   X-Ref
Executes the allocation based on the given settings

param: workshop_random_allocator_setting $setting
param: workshop_allocation_result allocation result logger

ui()   X-Ref
Returns the HTML code to print the user interface


delete_instance($workshopid)   X-Ref
Delete all data related to a given workshop module instance

This plugin does not store any data.

param: int $workshopid id of the workshop module instance being deleted
return: void

available_numofreviews_list()   X-Ref
Return an array of possible numbers of reviews to be done

Should contain numbers 1, 2, 3, ... 10 and possibly others up to a reasonable value

return: array of integers

self_allocation($authors=array()   X-Ref
Allocates submissions to their authors for review

If the submission has already been allocated, it is skipped. If the author is not found among
reviewers, the submission is not assigned.

param: array $authors grouped of {@see workshop::get_potential_authors()}
param: array $reviewers grouped by {@see workshop::get_potential_reviewers()}
param: array $assessments as returned by {@see workshop::get_all_assessments()}
return: array of new allocations to be created, array of array(reviewerid => authorid)

add_new_allocations(array $newallocations, array $dataauthors, array $datareviewers)   X-Ref
Creates new assessment records

param: array $newallocations pairs 'reviewerid' => 'authorid'
param: array $dataauthors    authors by group, group [0] contains all authors
param: array $datareviewers  reviewers by group, group [0] contains all reviewers
return: bool

index_submissions_by_authors($submissions)   X-Ref
Flips the structure of submission so it is indexed by authorid attribute

It is the caller's responsibility to make sure the submissions are not teacher
examples so no user is the author of more submissions.

param: string $submissions array indexed by submission id
return: array indexed by author id

get_author_ids($newallocations)   X-Ref
Extracts unique list of authors' IDs from the structure of new allocations

param: array $newallocations of pairs 'reviewerid' => 'authorid'
return: array of authorids

get_unique_allocations($newallocations)   X-Ref
Removes duplicate allocations

param: mixed $newallocations array of 'reviewerid' => 'authorid' pairs
return: array

get_unkept_assessments($assessments, $newallocations, $keepselfassessments)   X-Ref
Returns the list of assessments to remove

If user selects "removecurrentallocations", we should remove all current assessment records
and insert new ones. But this would needlessly waste table ids. Instead, let us find only those
assessments that have not been re-allocated in this run of allocation. So, the once-allocated
submissions are kept with their original id.

param: array $assessments         list of current assessments
param: mixed $newallocations      array of 'reviewerid' => 'authorid' pairs
param: bool  $keepselfassessments do not remove already allocated self assessments
return: array of assessments ids to be removed

random_allocation($authors, $reviewers, $assessments, $result, array $options)   X-Ref
Allocates submission reviews randomly

The algorithm of this function has been described at http://moodle.org/mod/forum/discuss.php?d=128473
Please see the PDF attached to the post before you study the implementation. The goal of the function
is to connect each "circle" (circles are representing either authors or reviewers) with a required
number of "squares" (the other type than circles are).

The passed $options array must provide keys:
(int)numofreviews - number of reviews to be allocated to each circle
(int)numper - what user type the circles represent.
(bool)excludesamegroup - whether to prevent peer submissions from the same group in visible group mode

param: array    $authors      structure of grouped authors
param: array    $reviewers    structure of grouped reviewers
param: array    $assessments  currently assigned assessments to be kept
param: workshop_allocation_result $result allocation result logger
param: array    $options      allocation options
return: array                 array of (reviewerid => authorid) pairs

convert_assessments_to_links($assessments)   X-Ref
Extracts the information about reviews from the authors' and reviewers' perspectives

param: array $assessments array of assessments as returned by {@link workshop::get_all_assessments()}
return: array of two arrays

get_element_with_lowest_workload($workload)   X-Ref
Selects an element with the lowest workload

If there are more elements with the same workload, choose one of them randomly. This may be
used to select a group or user.

param: array $workload [groupid] => (int)workload
return: mixed int|bool id of the selected element or false if it is impossible to choose

shuffle_assoc(&$array)   X-Ref
Shuffle the order of array elements preserving the key=>values

param: array $array to be shuffled
return: true

filter_current_assessments(&$newallocations, $assessments)   X-Ref
Filter new allocations so that they do not contain an already existing assessment

param: mixed $newallocations array of ('reviewerid' => 'authorid') tuples
param: array $assessments    array of assessment records
return: void

Class: workshop_random_allocator_setting  - X-Ref

Data object defining the settings structure for the random allocator

__construct()   X-Ref
Use the factory method {@link self::instance_from_object()}


instance_from_object(stdClass $data)   X-Ref
Factory method making the instance from data in the passed object

param: stdClass $data an object holding the values for our public properties
return: workshop_random_allocator_setting

instance_from_text($text)   X-Ref
Factory method making the instance from data in the passed text

param: string $text as returned by {@link self::export_text()}
return: workshop_random_allocator_setting

export_text()   X-Ref
Exports the instance data as a text for persistant storage

The returned data can be later used by {@self::instance_from_text()} factory method
to restore the instance data. The current implementation uses JSON export format.

return: string JSON representation of our public properties