DCS grading programs (1998 version)

The current version of the standard DCS grading programs is available on the CS Lab "apps" machines in the directory

	/p/teach/pkgs/grade

and on CDF in the directory

	/u/clarke/pub/gradebin

To use the programs, you need to add the appropriate directory to your search path, because some of the programs are in fact shell scripts referring to others of the programs.

The documentation for these programs is right here, in this web page and the others it refers to. There is no non-web-based documentation.

A fast introduction, mainly for TAs, is available. Anyone who wants to be able to construct grades files, however -- such as course instructors -- should keep reading here. (Both TAs and course instructors should also read about sending grades files by mail.)

The new programs are direct descendants of the "old" or "1988" version of the grading programs. That version is described on the web, and also in man pages on CS Lab. However, although the new programs are similar in many ways to the old ones, they are completely rewritten, are used in somewhat different ways, and have a different file format. Even if you're familiar with the old programs, you should read this documentation before using the current version.

Recent changes

November 1999:

A new function, $round, was added for use in mark formulas.
A warning about calculated letter grades was added to all programs.

July-August 2001:

Ghidenames was added to the set of programs.
The basic reading functions were altered to accept DOS-style line endings, though output still uses regular newlines.
Markscan was made more paranoid.

Basics

The grading programs are a set of C programs and Unix shell scripts that operate on grades files in a standard format. To work with these programs, you need to understand the University of Toronto's standard approach to grading, which you can read about in the calendars of almost all faculties or on-line at

   http://www.utoronto.ca/govcncl/pap/policies/gradprpolicy.htm

The essential idea is that in every course a "marking scheme" must be defined that specifies which marks a student will receive and what weight each mark has in the overall grading scheme of the course.

File format

The file format accepted by the grading programs mirrors this approach by having consisting of two parts:

a header giving the mark definitions -- the names and weights of the marks directly earned by the students, and the names of the marks derived from the directly-earned marks, together with the formulas used to calculate these derived marks.
a body giving the values of the actual marks earned by the actual students.

The file format determines much of what the grading programs allow you to do, so the first step is read about the file format, described in a separate page,

file format.

The grading programs

Here is a list of the grading programs, each linked to a longer description in its own web page:

garchive -- format marks in a style suitable for long-term archival storage, as by the Undergraduate Office.
gclear -- clear the contents of all entries for a mark.
gcopy -- copy a mark from one grades file to another.
gdelete -- delete all entries for a mark, either clearing the contents or completely removing the entire column of marks; this command is specialized by gclear and gremove.
gdiff -- look for differences between two grades files.
gdisplay -- format marks in a style suitable for public display.
gen -- calculate the values of marks derived from the marks directly earned by the students.
genter -- enter newly-earned marks into grades files.
ghidenames -- replace the names in a grades file with a fixed string, so as to protect students' privay in a minimal way.
glint -- check grades files for problems, in format or (to some extent) in values.
gnames -- reformat a class list provided by the University's student record system into a form suitable for the grading programs.
goldtonew -- convert a grades file from the format used by the old version of the grades programs to the format used by the new programs ... mostly.
gpadnames -- lengthen the names in a grades file so that it's easier to work on in an editor.
gpr -- print grades files in a generalized form (which is specialized by garchive, gdisplay, gpubreport, greport and gstats).
gpubreport -- display the marks of one student in a style suitable for public display.
gremove -- completely remove a column of marks from a grades file.
greport -- display the marks of one student in a form that includes all available information.
gselect -- echo a grades file, omitting student records that were not selected.
gsort -- sort the student records stored in grades files.
gstats -- display statistics on student marks.
gsub -- "submit the marks" for a course; that is, copy marks from a grades file into a file of the form used for official final-grades submission.
gswap -- interchange the values for two marks.
markscan -- scan a file intended for official final-grades submission to see if it conforms to the required format, and provide a statistical summary of the marks in the file. (This program is the only one the name of which does not begin with 'g'. The reason is that it can be used on grade-submission files prepared by any means, not just by the grading programs described here.)

All of these programs are Unix commands, of course, and they accept various command-line options. Two sets of options are common to many of the programs, and they are described in their own web pages:

selection options, allowing the effects of a grading program to be applied only to a subset of the student records in a grades file.
sort options, allowing a grading program to be applied to student records in an order other than the order of their appearance in a grades file, without necessarily changing the order of the contents of the file.

Changes since the previous version

The grading programs' view of what marks mean is the same as in the previous (1988) version, and the file format is in many ways the same, but there are enough changes that the old programs don't work on the new files, and the new ones don't work on the old files.

Each program's web page includes a note on "Changes since the previous version", and in addition there are two pages specifically on this topic:

changes -- an overview of the changes.
goldtonew -- a program that helps you convert a grades file from the old format to the new.