Grades

There is an ongoing discussion about this spec here Template:obsolete design

Executive Summary

The gradebook mechanisms must be rebuilt to:

1. Improve performance and scalability - All grades from throughout the system will be pushed to a central system of tables. This means reports based on grades can be generated much faster, and the gradebook has ultimate control over the content.
2. Improve flexibility - All aspects of the new gradebook will use simple plugin structures, namely: exports, imports and displays/reports. It is expected that the community will be very active in producing special-purpose reports analysing the basic grade data in new ways, for example, or writing plugins to transfer grades to student information systems.
3. Allow rubrics for outcomes (aka standards,competencies,goals) - As well as numerical grades, each grading item can consist of a number of scores made on a rubric against a standard outcome statement. These can be automatically converted to a numerical grade if desired or just shown as is.
4. Allow arbitrary columns and derived columns - Arbitrary columns of data can be added (either manually or via import). Columns can also be automatically filled based on formulas.
5. Implement limited public API - Activities may use this API to send grades/outcomes to gradebook and find out the final grades.

Glossary

Here are some terms used in the gradebook, both in the development and the user interface. Using these terms in discussions about the gradebook will help to reduce confusion.

Term	Definition
Activity	An instance of an activity module (e.g. a single quiz, assignment etc...)
Calculation	A formula used to calculate grades, based (optionally) on other grade items. Not the same as Calculated question types.
Category	A set of Grade Items. A Category also has its own aggregated Grade which is calculated from its Grade Items. There is no limit to the level of nesting of Categories (a Category may belong to another Category). However, each Grade Item may belong to only one Category.
Course completion	The concept of meeting certain criteria for completing a course. In the context of the gradebook, this means a set of grades that must be reached, or a number of outcomes/competencies to complete/master.
Grade	A Grade is a single assessment. It may be a number or an item on a scale (possibly tied to an Outcome). Raw grade value is the numerical or scale grade from activity. Final grade is the grade reported in gradebook.
Gradebook	A central location in Moodle where students' Grades are stored and displayed. Teachers can keep track of their students' progress and organise which set of Grades their students will be able to see. Students see their own Grades.
Grade Item	A "column" of Grades. It can be created from a specific Activity or other module, calculated from other Grade Items, or entered manually.
Grade Locks	See linked section of this page
History	The gradebook has its own type of log, which keeps a History of all changes made to grades.
Outcome	Outcomes are specific descriptions of what a person is expected to be able to do or understand at the completion of an activity or course. An activity might have more than one outcome, and each may have a grade against it (usually on a scale). Other terms for Outcomes are Competencies and Goals. See some Examples.
Scale	A scale is a set of responses from which the teacher can choose one. eg Very cool, Cool, Fairly cool, Not very cool, Not cool
Letter Grades	Special representation of grade values similar to scales. Letters are configured in course contexts or above and are defined by lower boundary. eg A (above 90 %), B (above 80 %), C (above 70 %), D (above 50 %), F (above 0 %)

Database structures

grade_items

This table keeps information about gradeable items (ie columns). If an activity (eg an assignment or quiz) has multiple grade_items associated with it (eg several outcomes and numerical grade), then there will be a corresponding multiple number of rows in this table.

idnumber is a tag unique inside a course identifying the grade item, useful for identifying data in exports and for referring to the grade item in calculations. It is the same as the idnumber in course_modules.

Field	Type	Default	Info
id	int(10)		autoincrementing
courseid	int(10)		The course this item is part of
categoryid	int(10)	NULL	the category group this item belongs to
itemname	varchar(255)	NULL	The name of this item (pushed in by the module or entered by user)
itemtype	varchar(30)		'mod', 'blocks', 'manual', 'course', 'category' etc
itemmodule	varchar(30)	NULL	'forum', 'quiz', 'csv', etc
iteminstance	int(10)	NULL	id of the item module
itemnumber	int(10)	NULL	Can be used to distinguish multiple grades for an activity
iteminfo	text	NULL	Info and notes about this item XXX
idnumber	varchar(255)	NULL	Arbitrary idnumber provided by the module responsible (optional and course unique)
calculation	text	NULL	Spreadsheet-type formula used to process the raw grades into final grades
gradetype	int(4)	1	0 = none, 1 = value, 2 = scale, 3 = text
grademax	float(10,5)	100	What is the maximum allowable grade?
grademin	float(10,5)	0	What is the minimum allowable grade?
scaleid	int(10)	NULL	If this grade is based on a scale, which one is it?
outcomeid	int(10)	NULL	If this is outcome item, which outcome is it?
gradepass	float(10,5)	0	What grade is needed to pass? grademin <= gradepass <= grademax
multfactor	float(10,5)	1.0	Multiply all raw grades from activities by this
plusfactor	float(10,5)	0.0	Add this to all raw grades from activities by this
aggregationcoef	float(10,5)	0.0	Weight applied to all grades in this grade item during aggregation with other grade items.
sortorder	int(10)	0	Sorting order of the columns (pre-order walk of the grading tree)
display	int(10)	0	Display as real grades, percentages (in reference to the minimum and maximum grades) or letters (A, B, C etc..), or course default (0)
hidden	int(10)	0	1 is hidden, 1 is hide always, > 1 is a date to hide until (prevents viewing of all user grades)
locked	int(10)	0	0 is not locked, > 0 is a date when was item locked (no final grade or grade_item updates possible)
locktime	int(10)	0	0 no auto locking, > 0 is a date to lock grade item and final grades after automatically
deleted	int(10)	0	1 means the associated module instance has been deleted
needsupdate	int(10)	0	If this flag is set, then the whole column will be recalculated. If set in course item, some other item needs recalculation. Calculated and category items are recalculated together with any other items.
timecreated	int(10)		The first time this grade_item was created
timemodified	int(10)		The last time this grade_item was modified

grade_categories

This table keeps information about categories, used for grouping items. An associated grade_item will be maintained for each category to store the aggregate data.

Field	Type	Default	Info
id	int(10)		autoincrementing
courseid	int(10)		The course this grade category is part of
parent	int(10)	NULL	Parent grade_category (hierarchical)
depth	int(10)	0	How deep is this category from the highest level (1,2,3)
path	varchar(255)		Shows the path as /1/2/3/
fullname	varchar(255)		The name of this grade category
aggregation	int(10)	0	A constant pointing to one of the predefined aggregation strategies (none, mean,median,sum, etc)
keephigh	int(10)	0	Keep only the X highest items
droplow	int(10)	0	Drop the X lowest items
aggregateonlygraded	int(1)	0	Aggregate only existing grades
aggregateoutcomes	int(1)	0	Aggregate otcomes together with normal items
aggregatesubcats	int(1)	0	Aggregate only items placed directly in category or all items in subcategories excluding the subcategory totals
timecreated	int(10)		The first time this grade_category was created
timemodified	int(10)		The last time this grade_category was modified

grade_grades

This table keeps individual grades for each user and each item. The raw grade is exactly as imported or submitted by modules. The rawgrademax/min and rawscaleid are stored here to record the values at the time the grade was stored, because teachers might change this for an activity! All the results are normalised/resampled/calculated for the finalgrade, which is relative to the max/min/scaleid values stored in the grade_item. The finalgrade field is effectively a cache and values are rebuilt whenever raw values or the grade_item changes.

Note that the finalgrade for a scale-based item may be non-integer! It needs to be rounded on display.

Field	Type	Default	Info
id	int(10)		autoincrementing
itemid	int(10)		The item this grade belongs to
userid	int(10)		The user who this grade is for
rawgrade	float(11,10)	NULL	The raw grade that came into the system
rawgrademax	float(11,10)	100	The maximum allowable grade when this was created
rawgrademin	float(11,10)	0	The minimum allowable grade when this was created
rawscaleid	int(10)	NULL	If this grade is based on a scale, which one was it?
usermodified	int(10)	NULL	the userid of the person who last modified the raw grade value
finalgrade	float(11,10)	NULL	The final grade (cached) after all calculations are made. Overriden grades are also stored here.
hidden	int(10)	0	0 is not hidden, 1 is hide always, > 1 is a date to hide until
locked	int(10)	0	0 is not locked, > 0 when was the grade locked
locktime	int(10)	0	0 is never, > 0 is a date to lock the final grade after automatically
exported	int(10)	0	0 is not exported, > 0 is the last exported date
excluded	int(10)	0	grade excluded from aggregation, > 0 is the last exported date
overridden	int(10)	0	0 is not overridden, > 0 is the last overridden date
feedback	text	NULL	Manual feedback from the teacher. Could be a code like 'mi'.
feedbackformat	int(10)	0	Text format for feedback
information	text	NULL	not sued yet (Further information like forum rating distribution 4/5/7/0/1 ?)
informationformat	int(10)	0	Text format for information
timecreated	int(10)		temporary hack - the date of submission in activity if any, new field expected in 2.0
timemodified	int(10)		temporary hack - the date of grading in activity or date of manual grading in gradebook, new field expected in 2.0

grade_outcomes

This table describes the outcomes used in the system. An outcome is a statement tied to a rubric scale from low to high, such as “Not met, Borderline, Met” (stored as 0,1 or 2). For more info about these see Outcomes.

Field	Type	Default	Info
id	int(10)		autoincrementing
courseid	int(10)	NULL	Mostly these are defined site wide ie NULL
shortname	varchar(255)		The short name or code for this outcome statement
fullname	text		The full description of the outcome (usually 1 sentence)
scaleid	int(10)		The recommended scale for this outcome.
description	text	NULL	The full description of the outcome (usually 1 sentence)
timecreated	int(10)		the time this outcome was first created
timemodified	int(10)		the time this outcome was last updated
usermodified	int(10)	NULL	the userid of the person who last modified this outcome

grade_outcomes_courses

An intersection table used to make standard outcomes available to courses.

Field	Type	Default	Info
id	int(10)		autoincrementing
courseid	int(10)		The id of the course being assigned the outcome
outcomeid	int(10)		The id of the outcome being assigned to the course

grade_import_newitem

Field	Type	Default	Info
id	int(10)		autoincrementing
itemname	varchar(255)		*TODO* Document
importcode	int(12)		*TODO* Document

grade_import_values

Field	Type	Default	Info
id	int(10)		autoincrementing
itemid	int(10)	NULL	*TODO* Document
newgradeitem	int(10)	NULL	*TODO* Document
userid	int(10)		*TODO* Document
finalgrade	float(10,5)	NULL	*TODO* Document
feedback	text	NULL	*TODO* Document
importcode	int(12)		*TODO* Document

History tables

These table keep track of changes to most of the grade tables. Using these it should be possible to reconstruct the grades at any point in time in the past, or to audit grade changes over time. It should be quicker to use these tables for that, rather than storing this information in the main Moodle log. The following tables are set up for that purpose:

1. grade_categories_history
2. grade_grades_history
3. grade_items_history
4. grade_outcomes_history

Each of them has exactly the same DB structure as their matching table (e.g. grade_categories), with 3 extra fields:

Field	Type	Default	Info
action	int(10)	0	The action that lead to the change being recorded (insert, update, delete)
oldid	int(10)		The id of the record being changed or inserted (PK of the main table, not the history table)
source	varchar(255)	NULL	The module from which the action originated

grade_letters

Field	Type	Default	Info
id	int(10)		autoincrementing
contextid	int(10)		What contextid does this letter apply to (from levels CONTEXT_SYSTEM, CONTEXT_COURSECAT or CONTEXT_COURSE)
lowerboundary	float(10,5)		The lower boundary of the letter. Its upper boundary is the lower boundary of the next highest letter, unless there is none above, in which case it's grademax for that grade_item.
letter	varchar(255)		The display value of the letter. Can be any character or string of characters (OK, A, 10% etc..)

Overview of module communication

Modules usually store raw grades internally and pass them into gradebook every time they change. Gradebook may also request activities to resend the grades.

The gradebook is designed to be as separate as possible from the code of activities - modules do not read grade tables or use internal gradebook API.

Originally it was planned to use new events API, but in the end it was decided to use minimal API consisting of several function in lib/gradelib.php and each mod/xxx/lib.php

Backward compatibility with Moodle 1.8 and earlier

Function grade_grab_legacy_grades($courseid) may be used to request transfer of grades from legacy or 3rd party activities which were not yet converted to new grade API. This function is not called automatically.

Modules are responsible to push existing grades into gradebook during upgrade.

API for communication with modules/blocks

Modules may use only functions from lib/gradelib.php which are marked as public. This API may be extended in later 1.9.x release. Activities should access/update only own grades.

grade_get_grades()

grade_get_grades($courseid, $itemtype, $itemmodule, $iteminstance, $userid_or_ids=0)

Returns grading information for given activity - optionally with users grades. Manual, course or category items can not be queried.

grade_get_outcomes()

grade_get_outcomes($courseid, $itemtype, $itemmodule, $iteminstance,$userid=0)

Returns list of outcomes used in course together with current outcomes for this user.

grade_is_locked()

eg grade_is_locked($courseid, $itemtype, $itemmodule, $iteminstance, $itemnumber, $userid=NULL)

This function will tell a module whether a grade (or grade_item if $userid is not given) is currently locked or not. If it's locked to the current user then the module can print a nice message or prevent editing in the module. If no $userid is given, the method will always return the grade_item's locked state. If a $userid is given, the method will first check the grade_item's locked state (the column). If it is locked, the method will return true no matter the locked state of the specific grade being checked. If unlocked, it will return the locked state of the specific grade. (info)

grade_update()

grade_update($source, $courseid, $itemtype, $itemmodule, $iteminstance, $itemnumber, $grades=NULL, $itemdetails=NULL)

Submit new or update grade; update/create grade_item definition. Grade must have userid specified, rawgrade and feedback with format are optional. rawgrade NULL means 'Not graded', missing property or key means do not change existing. Only following grade item properties can be changed 'itemname', 'idnumber', 'gradetype', 'grademax', 'grademin', 'scaleid', 'multfactor', 'plusfactor', 'deleted'.

grade_update_outcomes()

grade_update_outcomes($source, $courseid, $itemtype, $itemmodule, $iteminstance, $userid, $data)

Updates outcomes of a given user. Manual outcomes cannot be updated.

Private gradebook API

Private API is used by gradebook plugins and core Moodle code, it may change in 2.0. Most of the interesting classes and functions are in lib/gradelib.php, grade/lib.php and grade/report/lib.php.

grade_regrade_final_grades()

grade_regrade_final_grades($courseid=NULL, $userid=NULL, $updated_item=NULL)

Updates all grade_grades->finalgrade records for each grade_item matching the given attributes. The search is further restricted, so that only grade_items that have needs_update == true or that use calculation are retrieved and used for the update. The function returns the number of grade_items updated (NOT the same as the number of grades_grades updated!).

grade_verify_idnumber()

grade_verify_idnumber($idnumber, $grade_item = null, $cm = null, $gradeitem)

Verify new value of idnumber - checks for uniqueness of new idnubmers, existing are kept intact.

remove_course_grades()

remove_course_grades($courseid, $showfeedback)

Remove all grade related course data - history is kept

TODO: add description of the other methods and classes + simple usage examples + querylib.php description

Dealing with multiple grades

Modules usually produce only one grade item per activity. Optionally one or more outcomes may be attached to activities.

Some activities may need to aggregate multiple ratings or attempts before sending them into the gradebook. Activities can not send variable number of items.

If the gradebook receives multiple grade items from a module, then they are automatically grouped together in a unique grade category (with the same name as the module instance). See Outcomes for more details.

TODO: this may still be changed

Calculated grade items

Categories or manual items maybe calculated using spreadsheet-like formulas. Formulas may reference other items from the same course only using Id numbers in double square brackets.

eg:  = MEAN([[quiz121]], [[quizend]]) + [[assignmentAXC]] + 20.0

Regrading / updating of final grades

TODO: describe needsupdate flag and incremental updates

Adjustment of raw grades

Grade_item contains optional rules for adjusting the raw grade before it is cached into a final grade. These rules are processed BEFORE the calculation discussed above. Scale is never changed. Multfactor and plusfactor may be used to alter raw grades coming from activities, but it is recommended to use formulas instead.

Displaying the grades to ordinary participants

The module takes responsibility for displaying grades within the module (to a student, say). It is recommended to use the real final grades obtained using grade_get_grades() functionBecause guidebook might force hiding, override grade, etc.

For full display of grades in a whole course say, the student uses the same link as teachers use to access the gradebook. However, due to their different permissions they will only have access to specific reports. By default this is the User report report which only shows their own grades and has very few configuration options.

Locked grades

Both whole columns and individual grades can be locked in the gradebook, via the locked field. Teachers may want to do this to prevent further changes from the modules, or from other teachers. When a grade is locked, any changes that might affect that grade are ignored. When the graded is unlocked, activities are asked to resend the latest grades.

In the main GUIs the lock toggling will be achieved by clicking on a little padlock icon beside each entry or column.

There is also an option to lock grade or item after some specified date.

Overridden grades

Grades can be manually modified (overridden) in the gradebook. When this is done the entered value is always used instead of the aggregated, calculated or activity grade.

Logging

All grading related changes maybe logged in history tables.

Security Issues

For security an option to force SSL for the gradebook might be good.

Overall grade

Each course has exactly one course grade item. It may be used for this purpose now. Other course completion criteria will be implemented in 2.0.

Report plugins

All the main interface of the gradebook are implemented as report plugins. Each plugin is fully responsible for page layout, there are some handy functions in grade/lib.php. They can even define their own capabilities and extra tables if the core tables are not enough, as they'll have a full /grade/report/xxxx/db directory.

Each report defines one capability to allow people to see that report, so that admins have control over who can see what reports. For example, the participant interface can be a totally separate report plugin.

This allows for the widest flexibility and safety in how grades are presented.

Default teacher interface

This interface will be what teachers see by default, and will subsume everything the current interface (in Moodle 1.8) does.

Some snippets of functionality: Moodle1.9

Overall it's a grid, with participant names down one side and grade items along the top.

Columns will be able to be collapsed together by grouping them into categories. Grades for categories can be calculated via various means.

“Eye-cons” on the columns and checkboxes by every grade (this bit possibly controlled with a switch) allow hiding by category, by column, by individual grade.

Textual notes can be added to each grade for more info. These show up to participants as well.

A groups menu allows the teacher to switch between showing EACH of the groups they have access to, or ALL the groups they have access to.

All grade items will link to modulepath/grade.php?id=44 which will work out what the current person should be allowed to see and either redirect them to the correct page or just show them immediately. This copes with situations like the quiz, say, where we want editing teachers to go to the detailed reports there while participants just see their own grade or whatever the quiz is set to show.

User preference to SWITCH between showing raw grades, percentage grades, or both, or grade letters (A/B/C etc).

Settings for grade letters not only define the transformation from percentage to grades, but also the transformation from letters to grades (in case the teacher edits some of the letter grades).

Categories are shown above the headings for each column. Clicking for more info on a category will just show the category with a summary column showing total/average for just that category (PLUS the summary column for the whole course).

All columns should be sortable up/down.

At the bottom of each column is a row with the mean course score. If in groups mode, then add ANOTHER row with just the group mean. Add the number of grades used in brackets. eg 56% (11). When the report is paged, these means are still for the whole course/group (not the page!)

Moodle 2.0

Teachers can type “straight into” the grid using AJAX or fallback to forms. No popup menus for values.

Later on we can support customisable shorthand codes to make data entry quick (eg type 'ab' for absent, or 'nge' for not good enough).

See the test site for a live demo of this report.

Default participant interface

This interface will be what participants see by default:

Some snippets of functionality:

• Invert the grid to show one item per row, with the total/average at the bottom.
• Use second/third columns to show categories.
• Include ranking score in another column.
• Show feedback
• Show percentage
• No editing functionality.

See the test site for a live demo of this report.

Outcomes report

This simple informational report displays all the outcomes used by the course, with the following information:

• Outcome name
• Overall average: If the outcome is used by more than one activity, this shows you the mean across all these activities in the current course
• Site-wide: Yes or No: A site-wide outcome is automatically made available to all courses.
• Activities: A list of links to the activities in the current course that use each outcome. One row per activity (table splits here)
• Average: For each activity using the outcome, the average score is shown.
• Number of grades: For each activity using the outcome, the number of grades is shown (non-graded participants are ignored)

See the test site for a live demo of this report.

Overview report

Another basic report, showing a participant's course averages in each of the courses in which s/he has received grades.

See the test site for a live demo of this report.

Export plugins

The API for these is extremely simple. Each export plugin should occupy a directory under /grade/export/xyz and needs to provide only an index.php file as a the primary interface. This file just accepts a 'courseid' parameter.

Import plugins

Each import plugin should occupy a directory under /grade/import/xyz and needs to provide only an index.php file as a the primary interface. This file just accepts a 'courseid' parameter.

The index.php will show an interface for further options and selections.

Import plugin must validate data before starting the import operation, if some parts of import fail the user must be notified.

Some sample import plugins are:

Import from CSV

Accepts an upload of (or URL to) a CSV file. Multiple options describe how to process the file, which columns to add etc. The imported grades always override current grades.

Import from XML

Accepts an upload of (or URL to) an XML file with this kind of format (from OU).

<results batch="[someuniqueimportnumber]">
    <result>
        <state>['new' or 'regrade']</state>
            <assignment>[idnumber]</assignment>
            <student>[studentid]</student>
            <score>[score]</score>
        </result>
        <result>
            <state>['new' or 'regrade']</state>
            <assignment>[idnumber]</assignment>
            <student>[studentid]</student>
            <score>[score]</score>
        </result>
        [...]
</results>

Capabilities and Permissions

• moodle/grade:view - view own grades or grades of other user if used in CONTEXT_USER

• moodle/grade:viewall - view grades of all users

• moodle/grade:viewhidden - see grades that are marked as hidden for the owner

• moodle/grade:hide - be able to hide/unhide cells, items or categories

• moodle/grade:lock - be able to lock cells, items or categories

• moodle/grade:unlock - be able to unlock cells, items or categories

• moodle/grade:manage - manage grade items and categories in gradebook (create, edit, lock, hide, delete, etc.)

• moodle/grade:import - general import grades, requires separate permission for each plugin

• moodle/grade:export - export grades, requires separate permission for each plugin

• gradereport/grader:view - can view the grader report

• gradeimport/csv:view - can view/use the csv import plugin

• gradeexport/csv:view - can view/use the csv export plugin

• moodle:site/accessallgroups

Development Tasks and Tracking

See [https://tracker.moodle.org/browse/MDL-9137 MDL-9137] for the full details.

Updating module code

Module authors must implement new gradebook API and add upgrade code for migration of old grades into new gradebook. Fortunately the needed changes are not big.

Steps:

• add xxx_update_grades() function into mod/xxx/lib.php
• add xxx_grade_item_update() function into mod/xxx/lib.php
• patch xxx_update_instance(), xxx_add_instance() and xxx_delete_instance() to call xxx_grade_item_update()
• patch all places of code that change grade values to call xxx_update_grades()
• patch code that displays grades to students to use final grades from the gradebook

There are many examples in official modules, assignment has the most advanced implementation.

Ideas for the future

Moodle 2.0

TODO: add new meta issue into tracker

• option to aggregate including/excluding hidden grades - needs db changes
• option to rollback all changes during import operation if anything fails
• performance improvements
• conditional activities
• course completion criteria
• better public API for modules
• better API for gradebook plugins
• better state tracking in export plugins
• ajax reports
• specialised reports
• submission and marking date tracking db changes
• calculation formula improvements
• historical views
• individual graph of grades (time vs %). Bar graph, lineal graph. Add (or not) the maximum posible; line of 0 (=minimum), 25, 50 (=median), 75 and 100 (=max) percentils of the group.

See also

• Gradebook Development ideas forum discussion
• Using Moodle New gradebook for Moodle forum discussion
• Gradebook Report Tutorial