Readme for the `grader` System

Introduction

I have written a suite of perl scripts to assist with recording and analyzing grades for the courses I teach. My motivation for this is the difficulty I have had using a spreadsheet to compute grades. You might like to use this suite as well; use it at your own risk.

Features

This system has the following features that are not present in a spreadsheet. (Note: when I say the system does something "automatically" I mean "without any manual labor required" -- I don't mean that it does them without being asked to do them.)

The data files are tab delimited text files, so you can use vi or pico if you decide to change things by hand.
The facilities to compute final numeric grades are very flexible. For example, you can drop the lowest n grades of a certain category (homework, quizzes, etc) even when the assignments are not of the same point value (see below for a summary of the issues involved). This is painful to do with a spreadsheet and time-consuming to do by hand.
If you enter the letter grade cutoffs, the system can assign letter grades automatically.
Can automatically generate basic statistics about assignments.

Working Directory

The system assumes that you have a directory dedicated to the grades for your class. All operations take place in the current directory, so you must cd there before you begin. Certain files must be present for the system to work; the system can generate most of these files automatically given the proper raw input data. The files are:

roster: a tab-delimited file with the names, SIDs, and email addresses of all the students. This file should only include students who are enrolled; if a student drops the course, their name will remain in the assignment files but should be removed from the roster file. This removal must be done by hand.
assgs: a tab-delimited file which lists the assignments and the maximum score on each assignment.
Assignment files -- each assignment listed in the assgs file has a file of the same name containing the scores that each student received on the assignment (so the grades for assignment hw1 are kept in a file named hw1). A grade of '0' indicates that that the score was actually '0'; a student with no grade at all on an assignment will have no grade recorded for the assignment.
formula: contains the formula for computing the final grade for a student in the class. This is discussed in detail below, because it must be written by hand (since the grading system changes from class to class).
cutoffs: contains the numerical cutoffs for the letter grades. See gcompute below.

Commands

The following commands are available. They are listed roughly in the order they are needed during the semester.

gmkroster [name] - Creates the file 'roster' in the current directory, containing the names, SIDs, and email addresses of the students in the class. The input file is the 'spreadsheet format' class list from elion.psu.edu; just save the email to a text file and feed it to gmkroster.
gmkcal - Creates an HTML calendar table suitable for a course syllabus. Run with no options to see the correct syntax.
gmkassg [name] [points] - Adds a new assignment to the database, and automatically runs 'genter' to enter grades into the assignment. The assignments are listed in the file 'assgs' with the available points on each.
genter [name] - Allows you to enter or change grades for an assignment. You press the letter of the student you want to enter (or change) the grade for, hit enter, then enter the new grade. Press just [Enter] to move to the next page. Hit 'Q' then 'enter' to quit.
glsassg [name] - Displays the grades on a particular assignment. With the '-z' option, only displays those students with no grade recorded.
gmail - Sends form letters to all students in the roster file.
gmkhtml - Creates an html file with the assignment scores for each student. This file is suitable for public display (it has no names and partial SIDs). Requires a file 'gmkhtml.in' - see below.
gcompute - Computes a final grade for each student, computes statistics about assignments, and assigns letter grades. Requires a file named 'formula' with the appropriate syntax to tell how the final grade is computed. If you enter the letter grade cuttoffs in the file cutoffs, can assign letter grades. All these features are discussed below.

Dropping grades

If every assignment had the same weight, then dropping the lowest grades would be easy (actually, even this task is difficult to achieve in some spreadsheets, when dropping more than one grade). More care is needed when different assignment have different point values. First, the grades that represent the lowest percent of available points are the ones that must be dropped. Second, since assignments with different point values may be dropped, it isn't possible to predict before computing a student's grade the number of available points for this student in the end; this number will vary depending on which assignments are dropped. The final grade calculation must take into account the number of points possible with the given assignments dropped. I have written gcompute to do this correctly.

Usage of gmkhtml

gmkhtml requires a file gmkhtml.in in order to run. The first line of this file must be an absolute filename, into which the output is to be placed. The second line tells the desired permission on the output file (e.g. 0644). The rest of the file is an HTML file with two special escapes. These form of each escape is an HTML comment with no whitespace. The escapes are are:

 will be replaced with the current date and time when gmkhtml is executed.
 will be replaced with a series of HTML tables that contain the grade info. This escape must only occur once.

See below for an example of this file

Usage of gcompute

Running gcompute

There are three main options to gcompute, at least one of which must be given:

-r: Generate grade reports. This option adds to the output a report for each student showing that student's grades and the (overall) grade computed for the student according the the formula file. If the -l option is also used, then the grade report will include the letter grade assigned to the student.
-s: Generates statistics about all assignments and about the numerical grades that are computed from the formula file.
-l: Assigns letter grades. A report showing the letter grade of each student is generated.

gcompute will generate all the output requested, then stop. Ordinarily, the output is formated for on-screen viewing, with '---' as the page separator. Adding the '-v' option will format the output for printing, with page feeds and a cover page. The '-p' option is equivalent to '-vrls'.

Specifying the '-e' option limits the results (including computed statistics) to include only those students who appear on the class roster. Without this option, a student who has a grade on any assignment will be included in the statistics for that assignment, and a grade report will be displayed for each student who has received any grades in the course.

The '-n PATTERN' option will limit the output of grade reports to those students whose surname matches PATTERN.

The '-o' option will add to the output a table of letter grade assignments suitable for public display.

Input Files

In addition to the assignment files, gcompute requires that you create (by hand) two files in the current directory: formula and cutoffs. These files are described below.

Format of the 'cutoffs' file

The 'cutoffs' file contains one line for each letter grade to be assigned. Here, a 'letter grade' is any sequence of non-tab characters - so 'A+', 'A', '3.33', and 'fred' could all be "letter grades". Each line of the file contains three fields delimited by tabs (with no spaces):

letter-grade [TAB] lower_cutoff [TAB] upper_cutoff
Example: 
A [TAB] 90 [TAB] 200
B [TAB] 80 [TAB] 90
C [TAB] 70 [TAB] 80

Each letter grade corresponds to all numeric grades in the half-open interval
[lower_cutoff, upper_cutoff). So the highest grade should have an upper cutoff higher than any student's grade. If a student has a grade that doesn't fall in the interval of any letter grade, no letter grade is assigned to that student. The intervals can be in any range; for instance, it is possible to compute grades out of 450 points. In this case, you might set A to the interval [400, 500), B to [350, 400), etc.

Format of the 'formula' file

The 'formula' file is parsed, line by line, once per student. The lines are executed in order.

In the end, you need to tell gcompute how to compute the final grade, but you can compute many intermediate numbers. The final grade must be stored into the variable &GRADE.

While parsing the formula file, gcompute has access to all the grades the student has received. These are accessed using the name of the assignment. Each has two pieces of information: the score the student received, and the maximum possible score.

Each line of the formula file tells gcompute how to compute some new variable. These new variables are differentiated from the assignment values because the new ones must have an ampersand '&' as their first character, while assignment names must not begin with an ampersand. Each of these new variables stores two values: the score that the student earned and the maximum possible score.

Any line containing only whitespace or starting with '#' is ignored.

Each line is a sequence of 'words' separated by whitespace. The words fall into three classes: '&-variables', assignment names, and commands.

&-variables begin with the character '&' and are followed by several letters. I use uppercase letters for clarity, but the identifiers can contain anything that isn't whitespace. These variables store the values of intermediate calculations. The '&GRADE' variable must have the final grade in it when the formula file has been completely parsed.
Assignment names are the literal names from the assgs file, e.g. 'hw1', 'exam2' (these are case sensitive). These automatically take on the value of the student's grade on the assignment.
Commands are: the 'line-type' commands, the '%' sign, number literals (/\d+/), and some misc. command options.

The form of any valid line is

  < &-variable > < command > < arguments >

Each line tells gcompute how to compute a certain &-variable. The first word on the line must be the name of the &-variable into which the current line's value will be stored.

The second word must be 'sum','avg', 'curve' or 'scale'. Several arguments to this command word will then follow on the same line. The arguments vary depending on the command:

scale rescales an assignment to have a fixed maximum value. This is useful because, due to dropped assignments, other &-variables may have different maximum values for different students. The command scale takes two arguments: a variable (which can be an assignment name or an &-variable) and a numeric literal:
```
&DESTINATION scale [var] [num]
Example:  &FINAL scale &RAW_FINAL 100
Example:  &TEST2 scale test2 50
```
The result of this is that the variable &DEST contains the value of [var] scaled to a maximum of [num].
sum adds several variables together. The syntax is:
```
&DEST sum [var1] [var2] [var3] ...
or
&DEST sum [var1] [var2] [var3] ... % [num]

Example: &QUIZ sum quiz1 quiz2 quiz3 quiz4 quiz5 % 1
```
The number of variables to be summed is not limited but all the variables must be on the same line. Each variable can be an assignment name or an &-variable. The value associated with the sum is the sum of the values of the terms. The maximum value associated with the sum is the sum of the max values of the terms added. If the '% num' is present, the lowest 'num' values are dropped (left out of the sum). See the section "Dropping Grades" for an explanation of how this is done.
avg computes the weighted average of several variables (weighted by available points). It is equivalent to a sum command followed by a scale command that scales to maximum value 100. The syntax is:
```
&DEST avg [var1] [var2] [var3] ... 
or
&DEST avg [var1] [var2] [var3] ... % [num]

Example:  &HOMEWORK avg hw1 hw3 hw3 hw4 hw5 hw6 hw7 %2
```
The number of variables to be averaged is not limited but all the variables must be on the same line. Each variable must be an assignment name or an &-variable. In the first form, with no '%', the average is computed using all the variables shown. With the '% num' present, the lowest [num] scores are dropped before averaging; see the section "Dropping Grades" for an explanation of how this is done. The average is scaled to have maximum value 100.
curve adds points to a student's grade without changing the number of points available. There are four forms of this command:
```
 
&DEST curve [var] [num] 
&DEST curve [var] [num]% 
&DEST curve [var] [num] clip
&DEST curve [var] [num]% clip

Examples:

&FINAL curve final 15 clip
&HOMEWORK-CURVED curve &HOMEWORK 10%
```
If the argument [num] ends with a percent sign (no space), then the corresponding percentage of the available points for [var] is added to the points earned for [var], and this is stored as &DEST. If no percent sign is there, the earned points of var are increased by the value [num]. The maximum points available for &DEST is the same as for [var]. If the option 'clip' is present, then the points earned will not be greater than the points available (so they are 'clipped off' at 100%). If no 'clip' is present, the earned points may be higher than the points available.

Example formula file

#add up homework scores, dropping the lowest score
&HW sum hw1 hw2 hw3 hw4 hw5 hw6 hw7 hw8 hw9 hw10 % 1
#scale homework to 100 points
&HW scale &HW 100

#add up exam scores.  Since exam1c is the conflict for exam1,
#I drop one grade from the sum. The dropped grade will always
#be a zero since nobody takes both exam1 and exam1c
&EXAM sum exam1 exam1c exam2 final % 1

#final grade is a weighted average of exams and homework
&GRADE avg &EXAM &HW

Example gmkhtml.in

/home/fourier3/mummert/public_html/230s03/grades.html
0644
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Carl Mummert</title>
<link type="text/css" rel="stylesheet"
href="http://www.math.psu.edu/~mummert/mummert.css">
<body>
<h1>Math 230.05</h1>
<h2>Carl Mummert</h2>
<h2>Spring 2003</h2>
<hr>
<h2>Recorded grades</h2>
<h3><!--Date--></h3>
<p>For a list of the homework assignments, click
<a href="assignments.html">here</a></p>
<!--Report-->

<hr>
<p>
<p>
      <a href="http://validator.w3.org/check/referer"><img border="0"
          src="http://www.w3.org/Icons/valid-html40"
          alt="Valid HTML 4.0!" height="31" width="88"></a>
</p>
    
</html>

Readme for the grader System