Gradebook

Column Semantics

In the Pawtograder gradebook system, columns represent individual grade components that collectively form a student’s overall course performance. Each column is defined by a unique slug identifier, a human-readable name, and a maximum score, but their power lies in their flexibility for grade calculation and data sources. Columns can be:

Manually entered by instructors who directly input grades cell-by-cell (supporting both whole numbers and decimal values)
Imported from CSV files to bulk-load grades from external systems (with full metadata tracking of the import source and date)
Linked to programming assignments through the assignment reference system

When linked to assignments, columns automatically pull grades from the autograder system, creating a seamless connection between student code submissions and gradebook entries. Expressions: The most sophisticated column type uses mathematical expressions that reference other columns or assignments, creating a powerful dependency system for calculated grades. Using MathJS syntax, instructors can create complex formulas like (gradebook_columns("homework-*") + assignments("project-*")) / 2 to automatically compute weighted averages, drop lowest scores, or apply curve adjustments. Score expressions can define functions and have access to the full MathJS library of math and utility functions. Any grade that is automatically calculated can also be manually overridden by the instructor on a case-by-case basis.

Student Visibility of Grades

The “released” status in the gradebook determines whether students can see a particular column and its grades. For imported or manually-entered columns, instructors have direct control over this visibility — they can release columns to make them visible to students or unrelease them to hide grades during grading periods or for sensitive assessments. This setting is at the column level only (you can’t release or unrelease individual grades). For columns that are automatically calculated by Pawtograder (via an expression), students always see the current calculation based only on what they can see. For example, a column defined as the average of all homeworks will show the student the average of all homeworks they have released.

Instructor-Only Columns

When creating or editing a calculated column, you can mark it as “Staff-only” (instructor-only). These columns are completely hidden from students until you release them. While unreleased, students cannot see the column definition or their grades. When you release an instructor-only column:

Pawtograder creates a frozen snapshot of the current private scores for students
The instructor-only flag is cleared, making the column behave like a normal column going forward
Subsequent edits propagate to students via standard sync; unreleasing the column clears the public score but the column remains visible

This feature is useful for internal grading calculations, curve adjustments, bonus calculations, or draft grade formulas you want to finalize before sharing with students.

Automatic Recalculation of Dependent Columns

When you release or unrelease a gradebook column, Pawtograder automatically enqueues recalculation for all columns that depend on it. This ensures that calculated columns (those using expressions) always reflect the current visibility state and scores of their source columns. For example, if you have a “Final Grade” column that references “Homework Average,” releasing the homework average will trigger the final grade to recalculate for all students, ensuring they see accurate totals based on what’s now visible to them.

Managing Columns

Reordering Columns

You can reorder gradebook columns to organize them logically:

Drag and drop: Click and drag the grip icon (⋮⋮) in any column header to reorder columns
Move left/right: Use the column menu (⋮) and select Move Left or Move Right to shift a column one position
Auto-layout: Click the auto-layout button (grid icon) to automatically organize columns by their slug prefixes

Column reordering is saved immediately and affects the display for all instructors and the export order in CSV files.

Manual Grade Entry

You can manually enter or edit grades directly in the gradebook by clicking on any cell. The gradebook supports both whole numbers and decimal values, allowing you to enter precise grades like 8.5 or 92.75. This is particularly useful for assignments with partial credit or weighted scoring systems. The system validates that scores don’t exceed the maximum score for the column. When you override a calculated grade or manually adjust a grade, you can add a note explaining the reason for the override. These notes are visible in the gradebook interface and help maintain transparency about grade adjustments.

Gradebook Recalculation

When gradebook columns use expressions that reference other columns, Pawtograder automatically recalculates affected grades when dependencies change. This recalculation process runs asynchronously in the background to maintain performance for large courses.

When a grade changes, the system enqueues a recalculation job for affected gradebook rows
Edge functions process these jobs asynchronously to update calculated columns
The system tracks row versions to ensure updates are applied correctly and prevent race conditions
If a row is already being recalculated, new updates are queued without incrementing the version, allowing the current worker to complete successfully
When rubric check scores change, submission grade totals automatically recalculate to reflect the updated scores

This architecture ensures that calculated grades (such as averages and weighted scores) stay up-to-date even during periods of high activity, such as when multiple graders are entering scores simultaneously.

The gradebook recalculation system was recently fixed to address a critical bug where rows could become permanently stuck in the is_recalculating=true state. The fix ensures that version numbers are read after upserts complete, preventing version mismatches during batch processing.

”What If” Grade Calculations

The gradebook includes a “What If” mode that allows students and instructors to explore hypothetical grade scenarios by temporarily adjusting scores. This feature helps answer questions like “What grade do I need on the final exam to get an A?” or “How will my grade change if I skip this assignment?” When a student enters “what if” mode:

They can edit any editable grade cell to enter hypothetical scores
Calculated columns automatically update to reflect the hypothetical scenario
All changes are temporary and client-side only — no actual grades are modified
Modified cells are visually highlighted to distinguish them from actual grades
Students can reset to actual grades at any time

This feature is useful for:

Students planning how to allocate study time across remaining assignments
Instructors modeling the impact of curve adjustments or extra credit
Advisors helping students understand grade requirements for specific outcomes

Instructors can enable the “What-If” feature for students via Course Settings → Feature flags. When disabled, the student gradebook is view-only. The What-If feature does not apply to the staff preview in the instructor gradebook.

Importing Grades

To import grades, instructors use a 3-step wizard:

File Selection: Click the Import Columns button and select a CSV file from your computer, which the system parses client-side to extract tabular data.
Column Mapping: Choose which CSV column contains student identifiers and select whether they are email addresses or student IDs. For each remaining CSV column, decide whether to map it to an existing gradebook column for updates, create a new column (requiring you to set the maximum score), or ignore the column entirely. The system automatically detects email columns if present.
Preview & Confirm: Review a comprehensive preview table that shows exactly what changes will occur, highlighting grade updates with strikethrough old values and bold new values, warning about students in the CSV who aren’t enrolled in the course, and providing alerts when attempting to override calculated column scores. Only after reviewing this detailed preview can you click Confirm Import to execute the changes.

The system automatically creates new columns with full audit metadata including filename, date, and creator information, updates only enrolled students’ grades while preserving override behavior for calculated columns, and maintains complete import history for traceability and compliance purposes.

Expression Builder

When creating or editing a column with a score expression, Pawtograder provides an Expression Builder interface with live validation and debugging tools:

Live validation: As you type, the expression is parsed and validated in real-time. Parse errors and dependency errors (unknown column slugs, cycles) are shown immediately.
Full-screen mode: Click Expression Builder to expand to a full-screen Monaco editor with additional features:
- Syntax highlighting and autocomplete: The editor provides syntax highlighting for the gradebook expression language, with autocomplete for built-in functions and column slugs. Typing inside gradebook_columns("…") shows matching column slugs from your gradebook.
- Hover documentation: Hover over any sub-expression to see its current evaluated value for the selected student.
- Student picker: Select a student to test the expression against their actual gradebook data.
- Per-line evaluation: See the intermediate value of each statement in your expression, displayed as inline annotations (e.g. = 42) next to each line.
- Score preview: View both the raw numeric result and the rendered form (if a render expression is set).
- Incomplete values panel: See which dependencies are missing or not released for the selected student.
Save blocking: The Save button is disabled until the expression parses correctly and all dependency slugs resolve.
Gradebook table filters: The gradebook table now includes Select all / Select none toolbar buttons in column and section filter dropdowns for faster multi-select filtering.

The Expression Builder helps you write and debug complex expressions before saving them, ensuring they work correctly for all students.

Expression Syntax

The gradebook expression system uses MathJS as its foundation, enhanced with specialized functions for grade calculations. Expressions must return a numeric value that becomes the student’s score for that column. The final expression line is the student’s score for that column.

Core Syntax

Expressions follow standard mathematical notation with variables, operators, and functions:

// Basic arithmetic
hw_average = (hw1 + hw2 + hw3) / 3

// Boolean logic and conditionals
passing = grade >= 60 ? 1 : 0

// Multi-line expressions (last line is the result)
midterm_weight = 0.3
final_weight = 0.7
weighted_score = midterm * midterm_weight + final * final_weight
weighted_score

Data Access Functions

`gradebook_columns("slug-pattern")`

Retrieves gradebook column data with glob pattern matching. Returns objects with:

score: number | null - The student’s score (including overrides)
max_score: number - The maximum score for the column
is_missing: boolean - Whether the grade is missing/not entered
is_excused: boolean - Whether the student is excused from this item
is_droppable: boolean - Whether this item can be dropped in calculations

// Single column
homework1 = gradebook_columns("hw-01")

// Multiple columns with glob patterns
all_homeworks = gradebook_columns("hw-*")
skill_assessments = gradebook_columns("skill-*")

// Access score property
hw_score = gradebook_columns("hw-01").score

Array Processing Functions

`countif(array, predicate)`

Counts array elements matching a condition using lambda syntax:

// Count skill assessments scoring exactly 2
meets_expectations = countif(gradebook_columns("skill-*"), f(x) = x.score == 2)

// Count passing grades
passing_count = countif(gradebook_columns("exam-*"), f(x) = x.score >= 70)

`sum(array)`

Sums numeric values or scores from gradebook objects:

total_points = sum(gradebook_columns("hw-*"))

`mean(array, weighted=true)`

Calculates weighted (default) or unweighted averages. The function gracefully handles undefined values and missing grades:

// Weighted average (accounts for different max scores)
hw_average = mean(gradebook_columns("hw-*"))

// Unweighted average
hw_simple_avg = mean(gradebook_columns("hw-*"), false)

Weighted average is defined as:

const totalPoints = validValues.reduce((a, b) => a + (b?.max_score ?? 0), 0);
const totalScore = validValues.reduce((a, b) => a + (b?.score ?? 0), 0);
if (totalPoints === 0) {
    return undefined;
}
return (100 * totalScore) / totalPoints;

Unweighted average is defined as:

return (100 * validValues.reduce((a, b) => a + (b && b.score ? b.score / b.max_score : 0), 0)) / validValues.length;

In either case, grades that are missing will count as 0 points, unless the grade is marked as excused, in which case it is excluded from the average. The calculation tolerates undefined values in the input array, ensuring robust grade calculations even when some data is missing.

The mean calculation now tolerates undefined values in the input array, automatically filtering them out before computing the average. This prevents errors when some gradebook columns have not yet been populated.

`drop_lowest(array, count)`

Removes the lowest scoring droppable items:

// Drop 2 lowest homework scores
best_homeworks = drop_lowest(gradebook_columns("hw-*"), 2)
hw_final = mean(best_homeworks)

drop_lowest drops the lowest grades (including those that are “missing” or “excused”) as long as the “droppable” flag is set on the grade (this is the default).

Conditional Logic

`case_when([condition, value; ...])`

Convenience function for multi-condition branching using matrix syntax:

letter_grade = case_when([
  score >= 93, 97;  // A
  score >= 90, 93;  // A-
  score >= 87, 90;  // B+
  score >= 83, 87;  // B
  true, 0           // Default case
])

Comparison Functions

Normal comparison functions like ==, >=, <=, etc. are available, and can automatically coerce a gradebook value to a score for you (so that you do not need to map each gradebook value to a score to compare it).

Complete Examples

Simple Counting Example

// Count skills meeting expectations (score = 2)
countif(gradebook_columns("skill-*"), f(x) = x.score == 2)

Complex Grade Calculation

// Multi-criteria grading with modifiers
CriteriaA = gradebook_columns("meets-expectations") >= 10 and 
            gradebook_columns("does-not-meet-expectations") == 0 and 
            gradebook_columns("average.hw") >= 85

CriteriaB = gradebook_columns("meets-expectations") >= 8 and 
            gradebook_columns("does-not-meet-expectations") == 0 and 
            gradebook_columns("average.hw") >= 75

CriteriaC = gradebook_columns("meets-expectations") >= 5 and 
            gradebook_columns("does-not-meet-expectations") == 0 and 
            gradebook_columns("average.hw") >= 65

CriteriaD = gradebook_columns("approaching-expectations") >= 9 and 
            gradebook_columns("does-not-meet-expectations") == 0 and 
            gradebook_columns("average.hw") >= 55

CriteriaPlus = gradebook_columns("total-labs") >= 8
CriteriaMinus = gradebook_columns("total-labs") < 6

letter = case_when([
  CriteriaA, 95;
  CriteriaB, 85;
  CriteriaC, 75;
  CriteriaD, 65;
  true, 0
])

mod = case_when([
  CriteriaPlus, 3;
  CriteriaMinus, -3;
  true, 0
])

final = max(letter + mod, 0)
final

Exporting Grades

You can export gradebook data to CSV format for external analysis or record-keeping. Export buttons display a loading state while the export is being generated, providing clear feedback during the process.

Export Options

The export feature provides two options:

Standard Export: Exports raw scores as stored in the gradebook, including any manual overrides
Export with Rendered Expressions: For columns defined by expressions, evaluates the expression for each student and exports the calculated numeric result instead of the formula

How to Export

Click the Download Gradebook button at the bottom of the gradebook page
Optionally check Use render expressions in CSV to apply formatting
Click Download CSV

Export Contents

The exported CSV includes:

Student names and identifiers
All gradebook columns (both manually entered and calculated)
Current grade values for each student
Expression-rendered columns (when enabled): Columns defined by expressions are exported with their calculated values
Proper UTF-8 encoding with BOM for Excel compatibility
Formula injection protection through proper CSV escaping

Use Cases for Rendered Expressions

Share final calculated grades with students or administrators
Import computed averages into external grading systems that don’t support expression syntax
Analyze grade distributions based on complex calculations
Create reports with final weighted scores

​Gradebook

​Column Semantics

​Student Visibility of Grades

​Instructor-Only Columns

​Automatic Recalculation of Dependent Columns

​Managing Columns

​Reordering Columns

​Manual Grade Entry

​Gradebook Recalculation

​”What If” Grade Calculations

​Importing Grades

​Expression Builder

​Expression Syntax

​Core Syntax

​Data Access Functions

​gradebook_columns("slug-pattern")

​Array Processing Functions

​countif(array, predicate)

​sum(array)

​mean(array, weighted=true)

​drop_lowest(array, count)

​Conditional Logic

​case_when([condition, value; ...])

​Comparison Functions

​Complete Examples

​Simple Counting Example

​Complex Grade Calculation

​Exporting Grades

​Export Options

​How to Export

​Export Contents

​Use Cases for Rendered Expressions

Gradebook

Column Semantics

Student Visibility of Grades

Instructor-Only Columns

Automatic Recalculation of Dependent Columns

Managing Columns

Reordering Columns

Manual Grade Entry

Gradebook Recalculation

”What If” Grade Calculations

Importing Grades

Expression Builder

Expression Syntax

Core Syntax

Data Access Functions

`gradebook_columns("slug-pattern")`

Array Processing Functions

`countif(array, predicate)`

`sum(array)`

`mean(array, weighted=true)`

`drop_lowest(array, count)`

Conditional Logic

`case_when([condition, value; ...])`

Comparison Functions

Complete Examples

Simple Counting Example

Complex Grade Calculation

Exporting Grades

Export Options

How to Export

Export Contents

Use Cases for Rendered Expressions