Skip to content
Snippets Groups Projects
Unverified Commit 3ce04b79 authored by Nathan Sprenkle's avatar Nathan Sprenkle Committed by GitHub
Browse files

docs: update grades docs (#27341) 

* docs: fix formatting inconsistencies in grade data model docs

* docs: add subsection grade override model

* docs: add gradebbook info to grades / background

* docs: fix formatting issues in grades / background
parent 3fbaf726
No related branches found
Tags release-2021-04-28-12.53
No related merge requests found
Hide whitespace changes
Inline Side-by-side
lms/djangoapps/grades/docs/background.rst
+ 27
− 20
View file @ 3ce04b79
......@@ -116,16 +116,18 @@ Problem Scores
* *weighted_possible* (*a.k.a. max_grade*). The weighted_possible value is the maximum possible score that is achievable on the problem post-weight-computation.
* *weighted_earned* (*a.k.a. grade*). The weighted_earned value is the learner's score computed from the learner's response to the problem. The process for computing this score can be classified into the following types:
- **automatically scored, synchronously** at the time of submission, such as for most Capa-based problems
- **automatically scored, asynchronously** via an `external grader service <http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/external_graders.html>`_
- **manually scored**, such as for `Open Response Assessments <http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/open_response_assessments/OpenResponseAssessments.html>`_, where the calculation requires human input from either
- a single course staff (staff assessment)
- a number of peers (peer assessment)
- the self learner (self assessment)
- **automatically scored, synchronously** at the time of submission, such as for most Capa-based problems
- **automatically scored, asynchronously** via an `external grader service <http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/external_graders.html>`_
- **manually scored**, such as for `Open Response Assessments <http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/open_response_assessments/OpenResponseAssessments.html>`_, where the calculation requires human input from either
- a single course staff (staff assessment)
- a number of peers (peer assessment)
- the self learner (self assessment)
.. image:: images/background_problem_score.png
Grading Policy
......@@ -136,41 +138,46 @@ As described above in the Grade Computation section, the grading policy is distr
* Course level (adjusted in *Settings->Grading page in Studio*)
- Grade Range policy: Pass cutoff and letter grade thresholds
- Assignment Type policy: Weights and Allowable drops
* Subsection level (adjusted in *Content->Outline->Subsection->Settings* modal in Studio)
- A subsection's designation to an assignment type
- A subsection's setting of whether it is 'graded'
* Problem level (adjusted in *Content->Outline->Subsection->Unit->Problem->Edit* modal in Studio)
- A problem's weight
- A problem's external grader configuration
- A problem's individual grading policy - as currently supported by `ORA's assessment configuration <http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/open_response_assessments/OpenResponseAssessments.html#how-scores-for-open-response-assessments-are-calculated>`_
Grade Overrides/Exceptions
--------------------------
Today, we support the following features to `adjust grades <https://edx.readthedocs.io/projects/open-edx-building-and-running-a-course/en/named-release-birch/running_course/course_grades.html#adjust-grades>`_, but don't have a general feature to override a grade for any xBlock:
Today, we support the following features to `adjust grades <https://edx.readthedocs.io/projects/open-edx-building-and-running-a-course/en/open-release-koa.master/student_progress/course_grades.html#adjust-grades-for-one-or-all-learners>`_, but don't have a general feature to override a grade for any xBlock:
* In `ORA Studio settings <http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/open_response_assessments/Manage_ORA_Assignment.html#override-a-learner-s-assessment-grade>`_:
- override a learner's grade for an ORA2 block
* In LMS Instructor Dashboard or `Staff Debug Info <http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/manage_live_course/staff_debug_info.html>`_:
- reset the number of attempts a learner has made for a problem back to 0
- force a rescore on a submission to update all stored scores
- delete a student state for a problem
* In `Gradebook <https://edx.readthedocs.io/projects/open-edx-building-and-running-a-course/en/open-release-koa.master/student_progress/course_grades.html#adjust-grades-for-one-or-all-learners>`_:
- override a subsection grade for a learner
- override subsection grades in bulk (master's track only)
ORA2's Immutable Data
---------------------
......
lms/djangoapps/grades/docs/data-model.rst
+ 71
− 26
View file @ 3ce04b79
......@@ -12,16 +12,16 @@ Course Grades
**Indices from Uniqueness Constraint**: ('course_id', 'user_id')
* course_id
* course_id, user_id
* course_id
* course_id, user_id
**Additional Indices:**
* user_id
* course_id, passed_timestamp
**Fields:**
* user_id
* course_id, passed_timestamp
**Fields:**
+-------------------------+--------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------+
| Field name | Type | Description | Include in Data Package |
+-------------------------+--------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------+
......@@ -83,6 +83,9 @@ Subsection Grades
There are two tables that work in conjunction for storing subsection grades: Subsection Grade and Visible Blocks.
Subsection grades can also be overridden by staff/instructors. The most recent override for a subsection lives in the Subsection Grade Override table.
A history of subsection gtade overrides is also saved in the Subsection Grade Override History table, for auditing purposes.
Subsection Grade Table
^^^^^^^^^^^^^^^^^^^^^^
......@@ -92,13 +95,13 @@ Subsection Grade Table
**Indices from Uniqueness Constraint:** ('course_id', 'user_id', 'usage_key')
course_id
course_id, user_id
course_id, user_id, usage_key
* course_id
* course_id, user_id
* course_id, user_id, usage_key
**Additional Indices:**
visible_blocks_hash
* visible_blocks_hash
**Fields:**
......@@ -165,13 +168,13 @@ Visible Blocks Table
**Table Description:** Stores an ordered list of visible blocks within a subsection for a learner at the time of computing the subsection grade. It is expected that multiple learners will share access to the same list of visible blocks and hence this data is stored in a separate table so it can be referred to by multiple rows in the Subsection Grade table.
**Indices from Uniqueness Constraint:** ('hashed)
**Indices from Uniqueness Constraint:** ('hashed')
* hashed
* hashed
**Additional Indices:**
* course_id
* course_id
**Fields:**
......@@ -189,6 +192,51 @@ Visible Blocks Table
| | | Note: The blocks field contains a list of usage keys of all blocks within a subsection that are visible to the user at the time of computing the user's subsection grade. The value changes whenever users' access to content within the subsection changes: cohort assignment change, role change, course team adds/removes unit/problem, etc. When changed, a new row is created in the table with a corresponding new hash value. | |
+-------------+--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------+
Subsection Grade Overrides
^^^^^^^^^^^^^^^^^^^^^^^^^^
**Table Name:** grades_persistentsubsectiongradeoverride
**Table Description:** Stores the most recent override for a given subsection. In grade calculation, supersedes persisted subsection grade totals. The historical version of this table (grades_historicalpersistentsubsectiongradeoverride) captures a rolling list of previous overrides for audit purposes.
**Indices from Uniqueness Constraint:** ('id')
* id
**Additional Indices:**
* created
* modified
* grade_id
**Fields:**
+--------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------------+
| Field name | Type | Description |
+--------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------------+
| id | int(11) | Auto-incrementing ID of the override. |
+--------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------------+
| created | datetime(6) | When the override was first created. |
+--------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------------+
| modified | datetime(6) | When the override was last modified. |
+--------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------------+
| earned_all_override | double | The total number of earned points (graded and ungraded) to be overridden. |
| | | Note: It’s unclear how this is actually used since this is null in some cases and wouldn’t factor into grade calculation. |
+--------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------------+
| possible_all_override | double | Total number of possible points (both graded and ungraded) for a subsection. |
+--------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------------+
| earned_graded_override | double | The points to be overridden for for the subsection. |
+--------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------------+
| possible_graded_override | double | The total possible graded score for the subsection. |
+--------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------------+
| grade_id | bigint(20) unsigned | 1:1 mapping to a grades_persistentsubsectiongrade.id, specifying which grade this override applies to. |
+--------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------------+
| override_reason | varchar(300) | Instructor provided reason for override. Example: Student bribed me with doughnuts so I’m increasing their score. |
+--------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------------+
| system | varchar(100) | Where the override was performed. |
| | | Examples: GRADEBOOK, grade-import |
+--------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------------+
Problem Scores
--------------
......@@ -201,7 +249,7 @@ Courseware Student Module
**Table Description:** A general-purpose storage for user-specific state for any xBlock/xModule (not just problem-types). In addition to user-state, separate fields exist to store "earned" and "possible" grades for scorable blocks.
**Indices from Uniqueness Constraint: ('student', 'module_id', 'course_id')**
**Indices from Uniqueness Constraint:** ('student', 'module_id', 'course_id')
* student
* student, module_id
......@@ -251,16 +299,16 @@ ORA Submissions
**Table Description:** One of the tables amongst the suite of tables used for ORA submissions. This particular table stores the scores for ORA problems.
**Indices from Uniqueness Constraint: ('id')**
**Indices from Uniqueness Constraint:** ('id')
* id
* id
**Additional Indices:**
* student_item_id
* submission_id
* created_at
* student_item_id
* submission_id
* created_at
**Fields:**
+-----------------+------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
......@@ -279,6 +327,3 @@ ORA Submissions
+-----------------+------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| submission | Submission | Foreign key to the submissions_submission table. |
+-----------------+------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment