A simple example, and why it's like that
Changes since the previous version
A grades file has two parts:
We'll show an example of a simple grades file, and then discuss the rules in the light of the example. Then, after a more complex example, we'll discuss the rules it exemplifies.
* A simple grades file a1 / 10 * the first assignment a2 / 10 * A comment on a line by itself is acceptable. a3 / 10 a4 / 10 p / 20 t / 50 e / 100 asts = a1 : 5 a2 : 5 a3 : 10 a4 : 10 p : 15 term = asts : 45 t : 15 finl = term : 60 e : 40 123456789 Alice 10 10 10 10 20 L 50 100 123456790 d Brian 5 5 5 5 10 25 50 123456791 x Carla 0 10 0 10 10 20 65
The grading scheme contained in the file header consists of a list of mark names, together with instructions on how to get a value for each one. Mark names can consist of letters, digits, and the underscore character. The first character must be a letter or underscore. The name can be as long as you like, but if it's longer than five characters, it may be truncated by some of the display programs.
Comments are allowed in the header. They begin with the character '*' and extend to the end of the line. A comment line does not terminate the header like an empty line, even if it contains no mark definition.
A mark can be a "raw" mark or a "calculated" mark. For a raw mark, the person marking the work determines a number to be assigned to each student, and all the marking scheme needs to do is to specify the name and the "maximum" mark for the item. ("Maximum" is in quotation marks because if there are bonus marks or a generous marker, the maximum may be exceeded. A better name would be something like the "out-of mark".)
For a calculated mark, we need to specify the formula used for the calculation. This will consist of a list of other marks, with the weight assigned to each of those items in the calculation.
In our example, the grades-file header consists of every line down to the one beginning "finl = ...". The raw marks are called a1, a2, a3, a4, p, t, and e, and you can tell that they are raw marks because all that is given is the symbol '/' and then the maximum mark given by the person marking.
The calculated marks are called asts, term, and finl. For these marks, you see the symbol '=' and then the formula used to do the calculation. Each formula consists of a series of terms, and each term consists of the name of another mark and the weight of that other mark in the formula. For example, the mark "finl" is determined by giving the mark "term" a weight of 60 and "e" a weight of 40. That is, the value for "term" is taken as a fraction of the maximum possible and multiplied by 60, and then the same is done with "e", multiplying by 40. The maximum mark for "finl" is then 100.
Each line in the body gives what we know about one student. A student record consists of these fields:
First, the marks in a student record are associated with a mark definition in the grades-file header by their sequence number in the record, so if a mark is omitted you must still include the tab character preceding it, unless there are no more marks in this student record.
Secondly, the "tab character" preceding each mark is really a separator character. Probably you will want it to be a tab, but you're allowed to specify something else: if the first three characters of the marks file are */K, where K is any character, then the grading programs use K as the separator character for that marks file. Obviously, this is a facility to be used with some caution.
Thirdly, a word about the flag character. It can be used to select or de-select student records in many of the grades programs, but the particular values have no meaning except as you decide to use them. By contrast, the idea of dropping a course is so important that it has its own field, even though you could manage the same idea with the flag character.
Finally, notice that you can add short comments at the end of a mark value, as long as the first part of the string in the mark field is a representation of a correct value for the mark. For instance, Alice's mark p has a trailing 'L' as a comment.
In our simple example, Brian has dropped the course, while Carla is flagged 'x', for what reason we cannot say.
Here is what the simple example looks like after we calculate the marks with the grades program gen:
* A simple grades file a1 / 10 * the first assignment a2 / 10 * A comment on a line by itself is acceptable. a3 / 10 a4 / 10 p / 20 t / 50 e / 100 asts = a1 : 5 a2 : 5 a3 : 10 a4 : 10 p : 15 term = asts : 45 t : 15 finl = term : 60 e : 40 123456789 Alice 10 10 10 10 20 L 50 100 45 60 100 123456790 d Brian 5 5 5 5 10 25 50 22 30 50 123456791 x Carla 0 10 0 10 10 20 65 22 28 54
Unless you need to construct complex grades files yourself, you can stop reading here (or skip to the last section, "Changes since the previous version"). For example, course instructors probably need to keep reading, while tutors or TAs can probably quit now.
a1 / 10 a2 / 10 a3 / 10 a4 / 10 p / 20 t / 50 e / 100 tutor " asts = $desc (a1 a2 a3 : 10 5 5) a4 : 10 p : 15 ! 1 term = asts : 45 t : 15 $pick (tutor ? "Larry" ($add (1.1)) "Curly" ($mul(0.9)) "Moe" ()) ! 1 finl = term : 60 e : 40 ! 1 123456789 Alice 10 10 10 10 20 50 100 Larry 123456790 Brian 7 5 5 5 10 25 50 Moe 123456790* Was sick for all of November. Medical note seen. 123456791 Carla 7 5 5 5 10 25 50 Curly 123456792 David 7 5 5 5 10 25 50 Larry 123456793 Ellen 0 10 0 10 10 20 65 Curly 123456794 Filip 0 10 10 10 20 65 Curly 123456794* a3 = a1:5 a2:5
Sometimes, the kind of simple calculation described in the previous section is sufficient. More often, you'll discover that you marked something too hard or too generously, or that some of your TAs marked differently from others. You need to make adjustments, and adjustments mean a departure from the basic "sum of weighted marks" scheme.
(It's not against the University's rules to make adjustments. But some adjustments are indeed contrary to the rules, and you should check if you're not sure you're doing something legal. The grading programs try not to cater to illicit schemes, but they don't guarantee you can't do something illegal.)
Departures from the basics in mark definitions are represented by the grading programs in the form of functions. For a function "f", a function call looks like this:
$f ( argument-string )Another way of looking at this is to consider that function names all start with the character '$'. (The '$' is not part of a legal mark name, or a function name after the first character.) The argument string is of different forms for different functions. For example, the function $mul, which multiplies by a constant, requires that the argument string represent a number. Here's how you would increase everyone's final grade by 10%:
finl = term : 60 e : 40 $mul(1.1)You could also achieve this by giving "term" a weight of 66 and "e" a weight of 44, as in the old grading programs; but then the total weight of "finl" would be 110, whereas $mul doesn't change the weight, so in the formula above the maximum mark for "finl" is still 100, even though some students may actually have their marks increased above 100.
In a moment, we'll tell you about all the functions you can use, but first you need to know about data types. It turns out that it's helpful to allow general strings rather than just numbers, so there are two data types for marks: numbers and strings. For example, if you want to include the tutor's name in every student record, you could do it with a "mark" defined like this:
tutor "Instead of the '/' that denotes a raw numerical mark, the double-quotation-mark character indicates a raw string mark. It's a raw mark in the sense that it would be entered by some human; but there are ways of generating it automatically too. (See $setstring, below.)
Calculated marks can have either data type, string or number. All calculated marks have the character '=' after the mark name, followed by a formula. The data type is determined from the formula, and it is illegal to have a formula of undetermined or mixed data type.
Thus for each function we have to specify the resulting data type and the effect on the weight (if it's a numerical formula) -- as well as the obvious requirements to know the form of the arguments and the value calculated.
a = a1 : 10 $mul(1.1) a2 : 10gives the value of "a1" a weight of 10 and then multiplies by 1.1. The value of "a2" is not multiplied by 1.1.
mul: The $mul function multiplies the current value of the formula by its argument, which must be a number. The data type is numeric. There is no effect on the weight.
add: The $add function adds the value of its argument to the current value of the formula. The argument is either a number or the name of another mark. If it is another mark, then the actual value of that mark is added, without scaling or weighting. The data type is numeric. There is no effect on the weight.
set: The $set function sets the current value of the formula to be the value of its argument. The argument is either a number or the name of another mark. If it is another mark, then the actual value of that mark is used, without scaling or weighting. The data type is numeric. The weight of the formula is changed to 0, because all previous terms of the formula are effectively discarded.
desc: The $desc function (which replaces the multi-item terms of the old grading programs) takes an argument consisting of a sequence of mark names, followed by the character ':', followed by a sequence of numeric weights; there must be the same number of weights as of mark names. The values of each of the named marks are are scaled by their maximum marks, and then sorted in descending order. Each scaled mark is then multiplied by the corresponding numeric weight, and the result is added to the current value of the formula. The data type is numeric. The weight of the formula is increased by the total of all the weights in the argument. Here is an example call of $desc:
a1 / 10 a2 / 10 a = $desc (a1 a2 : 14 7)If the values of "a1" and "a2" are 6 and 8 respectively, then the value of a is (8/10)*14 + (6/10)*7 = 15.4, with a weight of 21.
pick: The $pick function allows you to choose a formula on the basis of the value of another mark. The other mark must be a string. Thus, if the mark "tutor" contains the tutor's name, then
a = a1:10 a2:10 $pick(tutor ? <series of labelled formulas>)selects one of the "series of labelled formulas", using the value of "tutor" as the selection criterion. Each labelled formula is of the form:
"<string>" ( <formula> )Here is an example of a complete $pick call:
a = a1:10 a2:10 $pick(tutor ? "Larry" ($add(1.1)) "Curly" ($mul(1.05)))If the value in "tutor" is Larry, then 1.1 is added to the current formula value; if the value in "tutor" is Curly, then the current formula value is multiplied by 1.05.
There must be quotation marks around the strings used to label selections. However, there are no quotation marks around strings in string mark values, unless the string is meant to be part of the value. You can use the escape character '\' to put quotation marks and parentheses in strings in the $pick labelling context and elsewhere in the grading scheme context.
The labelling string "" (the null string) matches any selecting value (like the default label in C's switch statement). If present, it must be the last label in the series.
The labelled formulas in a $pick call may contain only calls to $add, $set, $mul and $fail. The data type of a $pick call is numeric. There is no effect on the weight of the formula (even if the call contains a $set call.)
fail: The $fail function causes the formula evaluation to fail, producing an error message if it is called from a sensibly-implemented grading program. It takes no arguments. It has no data type. It has no effect on the weight of the formula.
Obviously, the only use for the $fail function is as one of the labelled formulas in a $pick call -- a formula, presumably, that should not be evaluated for any actual student.
If there is no default label ("") in a $pick call, one is automatically supplied, and its formula is $fail().
setstring: The $setstring function sets the current value of the formula to be the value of its argument. The argument is a string. The data type is string, and therefore the formula has no weight.
It is expected that a typical use of $setstring would be to insert some standard value in all students' records in a file that is later to be combined with other files, as from other tutorials. After combining the files, you would change the definition for this mark from
tutor = $setstring(...)to
tutor "However, it does seem possible that users will invent other applications not thought of yet.
round: The $round function rounds the current value of the formula to the nearest multiple of its argument. For example, to round to the nearest integer, use
rnd = ... $round(1)Judging by the availability of an equivalent option in the old grading programs (1988 and earlier), at least one instructor thought this function should be applied to all calculations automatically. However, it was in fact introduced here to facilitate operations on letter grades.
The use of $round by itself does not determine the rounding of the mark inserted into a grades file by gen; it determines the number that is used in further calculations, but this number may be rounded further before being put back into the file, because gen formats the its output mark according to the specifications in the mark formula.
For example, with these mark specifications:
m1 / A m2 = m1 : 100 $round(0.1)m2 will be calculated as 87.5, but will appear as 88 in the file after processing by gen, because there is an implicit "! 0" at the end of the definition.
The argument for $round is not the same as the argument for the output format specification.
When you use a program such as gen to calculated the marks in a grades file, the program calculates both a number that is the value of the mark, and a string representing the number.
If you append "! f" to the end of a mark definition, then f determines the format of the string representing the mark. If f is an integer, then that many decimal places are provided in the string. If f is the character 'A', then the value of the mark is converted to a letter grade.
The argument for the output format specification is not the same as the argument for the $round function.
You may put comments after the marks in the line representing a student's record, but long comments are awkward to insert and don't sit well with the grading programs intended to make printable representations of grades files. Instead, you can put comments on a separate line, as in the case of the student Brian.
Comments must follow the line containing the student's main record, and must begin with the student number, followed by the comment character, '*'.
Some students are exceptions: they miss a piece of work with a good excuse, for example, or there is some other reason to evaluate their marks differently from everybody else's. For these students, you may want to specify an individual formula.
An individual formula is given as a comment with the student's marks, not in the header with the general marking scheme. The contents of the comment must be the mark-definition formula that you want to use, as in the case of the student Filip in our example.
Either a raw or a calculated mark can have an individual formula, and you can have individual formulas for more than one of a student's marks. The type of the individual formula must match the type of that mark in the regular marking scheme. If the mark is numeric and the total weight of the individual formula is different from the total weight in the regular marking scheme, a warning message is given (unless the individual formula, or the regular mark, or both, have zero weight).
Here is what the complex example looks like after we calculate the marks with the grades program gen:
a1 / 10 a2 / 10 a3 / 10 a4 / 10 p / 20 t / 50 e / 100 tutor " asts = $desc (a1 a2 a3 : 10 5 5) a4 : 10 p : 15 ! 1 term = asts : 45 t : 15 $pick (tutor ? "Larry" ($add (1.1)) "Curly" ($mul(0.9)) "Moe" ()) ! 1 finl = term : 60 e : 40 ! 1 123456789 Alice 10 10 10 10 20 50 100 Larry 45.0 61.1 101.1 123456790 Brian 7 5 5 5 10 25 50 Moe 24.5 32.0 52.0 123456790* Was sick for all of November. Medical note seen. 123456791 Carla 7 5 5 5 10 25 50 Curly 24.5 28.8 48.8 123456792 David 7 5 5 5 10 25 50 Larry 24.5 33.1 53.1 123456793 Ellen 0 10 0 10 10 20 65 Curly 27.5 30.2 56.2 123456794 Filip 0 10 5 10 10 20 65 Curly 30.0 32.4 58.4 123456794* a3 = a1:5 a2:5(Your browser may leave the ends of the student records invisible to the right. You can view them by shifting the viewing range to the right with the thumb-wheel control at the bottom of the window.)
The new file format is very like the old one in essentials, but the details are quite different.
Any formula from an old grades file can be represented in a new grades file, but a multiple-element term such as "a1 a2 a3 : 10 10 5" must be made the argument of the function $desc, and additive corrections must be arguments to $add.
There are also things you can express with the new format that are impossible with the old. These are the ones that are most important, in the sense of meeting the most usual complaints:
The biggest change is that student marks are preceded by tabs. Note "preceded by": you don't have to have a tab at the end of a line. This change is almost certainly a good thing. It isn't certainly a good thing, because having marks at random places on the screen isn't going to make editing any easier, and when your tutors use peculiar methods of formatting, you're probably still going to have to do some fixing up. But at least the grading programs aren't going to complain about missing or excessive blanks at the ends of lines.
A minor consequential change is that student names can be of variable length.
Other minor changes: