Gradebook 2.x architecture

Gradebook 2.x architecture
Project state	Planning
Tracker issue	MDL-25423
Discussion	N/A
Assignee	unassigned

This page summarizes some initial ideas and suggestions that may help to resolve Stage 3 of the Gradebook improvements project.

Current issues

These are some of the most important issues with the current Gradebook design that this spec tries to deal with. See http://www.mindmeister.com/89537697/gradebook-2-x-issues-braindump for the full record of the braindumping session.

The grades appear in the gradebook immediately (MDL-25439)

The grade values are stateless. We need a way how to store grades in the gradebook but exclude them from aggregations yet. Currently, the hiddenuntil feature tries to solve this but it is pretty limited and hacky (MDL-25440).

Students and teachers may see different values

Because of how grades hiding is implemented currently, it is practically impossible to pre-populate whole grades tree and/or export reliable data (because they are dependent on the current role permissions).

Unable to alter grades processing

There is a demand for alternate methods of grades processing (eg grades over 100% or negative grades) due to local conventions in various countries and school systems.

Grading logic and UI implemented in activity modules

Grading tools like single point grade, scale-based grading or a new rubric-based grading should be handled by the Gradebook core with a rich set of interface toward activity modules (and eventually other plugin types).

Manual and auto grades interaction

What should happen in this scenario has never been defined: 1. Student makes first attempt at the quiz, gets grade of 50%, this is pushed to the gradebook. 2. Teacher manually edits the grade to be 60%. 3. Student makes second quiz attempt and scores 75%. What should the gradebook show now? -- Tim Hunt

": a similar situation happens in AMOS when the original English text is modified after it has been translated. If we record the timestamps, we can highlight such overridden grade as "outdated" (with a possibility to mark it as up-to-date hence un-highlight it). Still the manually edited value 60% should be the valid one IMHO --David Mudrak 15:45, 14 April 2011 (WST)

Suggested solutions and improvements

The goal is to make the gradebook so that simple things are easy and complex things are possible. That is for courses that just need to maintain a list of graded activities and calculate the final grade, the setup for teacher should be straightforward using default values. Advanced usage with a complex tree of grade items and calculations happening at several layers should be possible, though the setup may require more experience and insight into the internals.

According to this document, the gradebook to be still represented as a tree of grade items. There is no need to change this. Grade items may be associated with an activity module (multiple grade items per mod are supported) or a gradebook category. Grades are aggregated from the leaves of the tree to the root grade item that represents the total course grade.

In the example above, there are two grade items associated with modules in the course. These two are aggregated into a single item associated with a grades category. This category grade item is aggregated together with yet another grade item (that itself is populated via grader report) and form the course total grade.

Grades in core space or plugin space

Generally the grade values are to be stored by the gradebook in its own core tables. This will centralize and unify the storage and processing of the grades. For most modules like Assignment, Forum, Wiki, Database etc. (and eventually other plugin types like blocks if we ever decide to support grades there, too) this is enough as they do not need to keep the grades in their own tables.

This does not mean that the modules would be forced to give up advanced grades processing features. For example Quiz or Workshop modules must store a lot of additional data to calculate the final grades. So the Quiz will still hold the calculated grades for all user's attempts. But it will push the valid one (best attempt, average, maximum or whatever is set) to the gradebook. Similarly the Workshop will hold the information how the assessment forms were filled by peers. But the final grades for each student will be pushed into the gradebook tables via some nice API.

Introducing grade values states

This is a suggestion to extend the grade_grades table so that every grade item can actually hold three independent values:

• Available grade value - This is the value that comes from the source - from the activity module, from the grader report or as a result of the aggregation at lower levels. It behaves as an input buffer that just keeps the most recent incoming value.
• Overridden grade value - This is the value of the grade defined in the gradebook.
• Effectual grade value - This is a public value of the grade, it is used for aggregations at higher levels, it is being exported, displayed to users etc.

The key point of this new scheme is how and when the effectual value is populated. The container (column) holding the effectual value is populated during the grade approbation. Whenever a process of approbation is executed (typically during the recalculation of the gradebook tree), the following procedure is taken:

• If the value of overridden grade is not null, then use it as the effectual value (and break as we are finished)
• If there are no approbation conditions defined, take the available grade value and use it as the effectual value
• If there are some approbation conditions defined, evaluate the list of conditions. If the evaluation passes, use the available grade as the effectual grade value

The approbation conditions mechanism should support at least the following types of conditions:

• Date-based conditions - This would replace the current hidden-until feature
• Event-based conditions - Things like "take the grades into account when all submissions are assessed"
• Manual trigger - special type of an event. The teacher can easily order the gradebook to "take the grades into account NOW" by clicking a button or so

At the moment, we are unable to distinguish between the incoming available grade and the outgoing effectual grade value. Therefore it is not easy to put a grade on hold. For teachers in schools, it is pretty natural to have some grades already known but not having them counted into the total grade yet.

To be decided: do the conditions have to pass to take the overridden value into account, too? That is - if there are some approbation conditions defined, is the overridden value dependent on them or not?

Grade values and their interpretation and display

Currently, grading configuration (like max grade, grade type etc) is stored by modules themselves, often independently on the associated grade item settings. This is a proposal to change it so:

• The modules themselves do not know anything about the actual grade setting. That is, they do not know max grade, min grade, the grade display type etc.
• All the grade items settings is stored and controlled exclusively by the the gradebook code
• There is a callback mechanism introduced so that the gradebook can push the required grades setting into the mod_edit form and the module settings node in the Settings block (compare with how enrol plugins push their settings into the course edit form and how they have their own setting in the course settings node)
• When pushing a grade into the gradebook (so that is saved as the available grade value - see above), the activity module uses normalized decimal value from 0.00000 to 1.00000.
• The activity can ask the gradebook via its public API to format a given float value according the current grade item settings. "Hey gradebook, this student reached 0.81076. What shall I print to them?" and the gradebook would return "4/5" or "pretty good" or "81%" or whatever is defined there.

So the effectual, overridden and available grade values are stored as normalized 0.00000 - 1.00000 decimals in grade_grades. Their actual interpretation depends on the grade item settings.

Question: should the effectual value depend on the actual grade item type? Example: let us have a grade item the type of which is three-points scale 1, 2, 3 and the available grade value is 0.97654. During the approbation, should the value be transformed to 1.00000 or should it stay original?

Introducing gradebook engines

The grade values stored in the tree and the aggregation and approbation logic will be separated. Right now, the grade item itself contain the computation logic. A new class, so called gradebook engine, will be responsible for all grade values handling in the future. This should be pluggable and OOP-ish. This way, we should be able to implement alternative calculation engines, for example one that does not strip normalized values to <0; 1> interval but supports grades over 100% or negative grades.