Grader: A Grade Preparation Program

Andrew D. Lewis andrew@mast.queensu.ca

17 March 1998

1 What does Grader do?

Grader is a Perl program which computes final grades for a class given data files containing the scores for the various homeworks and exams. When used in conjunction with the gradelist L^{A}TEX document class, Grader virtually eliminates the need for any computation in the determination of the grades for a class.

The format of this manual is as follows: In Section 2 you are told how to get Grader running. The running of a brief demo is also discussed at this time. The setup of the recommended directory and file structure for using Grader is discussed in Section 3. In Section 4 the use of the gradelist document class for preparing data files is discussed. You are told how to format the driver data file input.dat in Section 5. The actual use of Grader to compile your final grades is discussed in Section 6. Finally, in Section 7 the use of Grader without the use of the gradelist document class is discussed.

The use of the gradelist document class is recommended, but not required. In this manual it will be assumed, with the exception of in Section 7, that you will be using this data preparation option.

2 Setting up Grader^{1}

When you get Grader, it will come in a tar file which you first need to untar. When you do this, you should have the following directories and files:

  1. The files grader.script, setup_grades.script and Makefile which are

used to install Grader. There are also man pages grader.man and

     setup_grades.man in this directory.

2. The directory ./demo. This is where the demo for Grader may be run. This directory has subdirectories assignments, .exams, and grades. The assignments directory contains three subdirectories, 1, 2, and 3, and each subdirectory has in it a file grades.tex. The .exams directory has subdirectories midterms and final. The midterms directory has a subdirectory 1 which contains a file grades.tex. A file with the same name is in final. In the directory grades are the data files input1.dat,

1This set up procedure has been performed with SunOS 5.4 and is not guaranteed to work on any other operating system.

     input2.dat, input3.dat, input4.dat, and input5.dat.

3. The directory ./sty which contains the L^{A}TEX files needed if you are going to prepare your grades with gradelist. Process this directory according to 00readme.txt and place the style files where TEX can get them.

4. The directory ./doc which contains the file doc.tex. It is meant to be L^{A}TEX’d. (You are reading the result.)

5. The files 00readme.txt, 00changes.txt, and copyright files.

If all these files and directories are present, you can install Grader. Edit Makefile to set BINDIR and MANDIR to be the correct directories. Also set PERL to the location of Perl on your system. Then go:

  1. make
  2. make install
  3. make man

If you do not have sed then you will have to copy the .script and .man files to appropriate executables and man pages and modify them by hand. Look for the string %% as this marks places where sed would do replacing. I hope it will be clear what needs to be done.

To get some idea of what Grader does, move to the ./demo/grades directory and type

    ln -s input1.dat input.dat.

This will set input1.dat to be the data file read by Grader. The first thing to do to run Grader is get the data files set up. Do this by running the script setup_grades. When you run setup_grades you will get some messages, and when it is done you should have the the files hw1.dat, hw2.dat, hw3.dat,

midterm.dat, final.dat and names.dat in the directory ./demo/grades. To

run Grader simply type

    grader.

Grader will read input data from the file input.dat and will chug through the given data and produce files output.dat and total.dat. Take a look at output.dat. Its layout should be as follows:

1. A list of the homework scores for each student. The order will be the same as that in which the names and scores are read in. If you want that order to be alphabetical, you must make the data files so that this is so. I have not set up Grader to do an alphabetical sort.

2. The next section will be a list of exam scores, both for midterms and the final exam. Again, the order is the same as the order in which the data was read from the data files supplied by setup_grades.

3. Next you should see the total homework, midterm and final exam scores presented in the order that the names and scores are read in. The final score of each student is also is also presented along with their rank.

4. The next section of output.dat is the same as the previous one, except the order is by rank in the class.

5. Next you should see statistics for each assignment, midterm, the final exam, and the final grade.

6. The last thing you will see is names of the students, in the order they are read in, with their corresponding letter grade.

The file total.dat simply contains the total scores in alphabetical order in a column. They are printed out to be processed with my histogram program.

You may wish to try this demo with the other input files to see what the difference is. The differences are outlined in Section 5 if you cannot figure out what is going on and need to know right now.

3 Preparing to use Grader

It will be convenient, but not essential, when using Grader to have the following directory structure present:

   [figure: ./assignments; ./.exams; ./grades; 1; nhwk; · · ·; midterms; final; 1; nmid; · · ·]

Here nhwk is the number of homeworks given in the class, and nmid is the number of midterms given. We shall assume that the base working directory for your class data is “..” The Grader scripts will only pay attention to those files in the directory tree which are as specified in the figure. In other words, if you have other stuff here, that is fine. Grader won’t choke on it.

If you will be using the gradelist document class to prepare the data files, in each directory ./assignments/j, j = 1, …,nhwk should be the file grades.tex. A file with the same name should also be present in the direc-

tories ./.exams/midterms/j, j = 1, . . . ,nmid and ./.exams/final. If the file

grades.tex is not present in any of the directories, then it will be assumed that that homework or exam will not contribute to the final score. If this is not the case, then put a file grader.tex in the directory. The preparation of these files is explained in Section 4.

Note that the directory and file structure just described is the same as that seen in ./demo when you unpacked Grader.

4 Preparation of data files

Here we discuss how to use the gradelist L^{A}TEX document class to prepare the data files for Grader. A typical grades.tex file is shown in Figure 1. The placement of these files in the directory structure is discussed in Section 3. The following TEX macros are available with their use as discussed:

\title : the name of the object (Assignment, Final

Exam, etc.)

\num : the assignment number. It appears in the

title.

\course : the course name. It appears in the title.

\instructor : the instructor’s name. It appears at the top

of the page.

\year : the year. It appears at the top of the page.

\maketitle : prints the title which contains the course

and the assignment number.

\name : writes the argument to the file names.out.

It also gives the name as TEX output.

\add : advances the grade for the assignment by an amount specified by the argument. The argument is a real number. The argument is also printed as TEX output.

\total : writes the assignment grade for that student to a file grades.out. It also increments the

                         counter \numberofstudents by 1. The

argument is printed as TEX output.

Each assignment may have as many problems as desired. When the document is L^{A}TEX’d, the files names.out and grades.out will be produced. The resulting .dvi file will appear something like Figure 2. The exact formatting of the actual TEX output is up to you. We have given a model here. If you are only interested in the data files, then it really doesn’t matter how you format the file from a TEX point of view. The only thing that matters is that the order of the commands

    \name \add . . . \add \total.

If the grades are for an exam, you may want to change the argument of name, but the functionality of the package is not affected by this. In this manner one

\documentclass{gradelist}
\title{Assignment}
\num{1}
\course{ACT1}
\instructor{L.~Olivier}
\year{1942}
\begin{document}
\maketitle
\begin{center}
\begin{tabular}{|l|c|c|c|c|c|}\hline
Name&Problem 1&Problem 2&Problem 3&Problem 4&Total\\\hline
\name{Bergman, I.}&
\add{5.5}&\add{4}&\add{6}&\add{5}&\total\\\hline
\name{Durante, J.}&
\add{4}&\add{6}&\add{3}&\add{4.75}&\total\\\hline
\name{Grant, C.}&
\add{6}&\add{3}&\add{5}&\add{6}&\total\\\hline
\name{Hepburn, K.}&
\add{6}&\add{6}&\add{4}&\add{6}&\total\\\hline
\name{Stewart, J.}&
\add{5.25}&\add{6}&\add{3}&\add{5}&\total\\\hline
\end{tabular}
\end{center}
The total number of students is \the\numberofstudents.
\end{document}

Figure 1: A typical grades.tex file. generates files grades.out and names.out in the directories ./assignments/j,

j = 1, . . . ,nhwk, ./.exams/midtermsj, j = 1, . . . ,nmid, and ./.exams/final.

Note that if you are going to use setup_grades you really never have to run the grades.tex files through L^{A}TEX except to check them. The grades.out and names.out files are created automatically by setup_grades when it comes time to compile the final grades.

5 Setting up the input file

With all the data preparation files, grades.tex, prepared, you now want to get the file input.dat ready in the directory ./grades. This file will contain values of parameters needed by Grader to prepare the final grades. An input file will be formatted as in Figure 3. Below we give the meaning of all the entries in

input.dat.

iassignments : ’y’ if homework is included in the final score. ’n’ otherwise. Present only if homework grades are present.

imidtermj : j = 1, …,nmid. ’y’ if midterm exam j is included in the final score. ’n’ otherwise. Present only if midterm grades are present.

ifinal : ’y’ if the final exam is included in the final score. ’n’ otherwise. Present only if final exam grade is present.

%assignments : present only if iassignments is ’y’. It gives the percentage of the final score given to the homework.

%midtermj : j = 1, …,nmid. Present only if imidtermj is ’y’. It gives the percentage of the final score given to midterm j.

%final : present only if ifinal is ’y’. It gives the percentage of the final score given to the final exam.

assignmentjmax : j = 1, …,nhwk. The maximum score attainable for assignment j. Present when applicable.

midtermjmax : j = 1, …,nmid. The maximum score attainable for midterm j. Present when applicable.

finalmax : the maximum score attainable for the final

exam. Present when applicable.

icutoff : ’y’ if you will be entering cutoffs for letter

grades. ’n’ otherwise.

nletters : present only if icutoff is ’y’. It gives the number of possible letter grades which will be assigned.

L. Olivier 1942

ACT1 Assignment # 1 Grades

Name  Problem 1 Problem 2 Problem 3 Problem 4 Total
Bergman, I.  5.5  4  6  5  20.5
Durante, J.  4  6  3  4.75  17.75
Grant, C.  6  3  5  6  20
Hepburn, K.  6  6  4  6  22
Stewart, J.  5.25  6  3  5  19.25

The total number of students is 5.

Figure 2: The appearance of the output file grades.dvi.

iassignments
imidterm1

⋮

imidterm nmid
ifinal
%assignments
%midterm 1

⋮

%midterm nmid
%final
assignment 1 max

⋮

assignment nhwk max
midterm 1 max

⋮

midterm nmid max
finalmax
icutoff
nletters
letter 1
cutoff 1

⋮

letter nletters
cutoff nletters

Figure 3: The format of input.dat letterj : j = 1, …,nletters. Present only if

icutoff is ’y’. It is the jth letter grade. These are ordered from highest to lowest. Any string is acceptable.

cutoffj : j = 1, …,nletters. Present only if icutoff is ’y’. It is a floating point number. If the student gets a grade grade g so that cutoffk < g ≤cutoffk + 1 then the student gets the letter grade letterk.

Note that input.dat must be compatible with what you are feeding Grader. If there are no assignment grade files, you’d best not include the assignments in the compilation of the final grade! Plain common sense should take over.

You may wish to grade “on a curve.” This would imply that you may not know the value of cutoffj, j = 1, …,nletter before you look at the final scores. In such a case you simply run Grader twice, once with icutoff set to ’n’, and once with it set to ’y’ when you know the cutoffs. The sample input

files input1.dat, input2.dat, input3.dat, input4.dat, and input5.dat may

give you some assistance here. They are set up for the following scenarios.

input1.dat : assignments, midterm, and final exam are all

included in the final score. icutoff is ’y’.

input2.dat : only the assignments and final exam are included

in the final score. icutoff is ’n’.

input3.dat : only the assignments and midterm are included in

the final score. icutoff is ’y’.

input4.dat : only the midterm and final exam are included in

the final score. icutoff is ’n’.

input5.dat : only the final exam is included in the final score.

                   icutoff is ’y’.

Note that when something is not figured in the final score, it may be read in as a dummy, or it may have actual meaning. For example, it is possible that the homework scores may not be included in the final tally, but that you want to know how people did on them anyway.

6 Making the grades

Now you have the data preparation files and the input file all set up and ready to go. It remains to make the data files and then move them to the directory ./grades where they will be processed by Grader. The making and moving of data files is done by the script setup_grades. If you have the directory structure as suggested on page 3, you may simply type

    setup_grades

in the directory ./grades. This accomplishes several things.

1. The files grades.tex are L^{A}TEX’d in all directories where they are present. This creates the files names.out and grades.out in each case.

2. The data files are moved to files with the proper names in the directory ./grades for input to Grader. The grades for the jth homework are put in a file called hwj5.dat, the grades for the jth midterm are put in a file called midtermj.dat, and the final exam grades are put in final.dat.

3. The first time a grade list is processed, a file called names.dat is created from the file names.out. On each subsequent processing of a data file, the file names.out is compared with names.dat to see if the names are the same. This is done using the UNIX command diff and is intended to alert you of any inconsistencies in the data files. The output from diff is sent to a file setup.log. Have a look at it when setup_grades is done and see if there were problems.

Now you have your data files all set up and you can run Grader just like you did in Section 1.

7 Using Grader without using the gradelist document class

It is possible to use Grader without using the gradelist and document class to prepare the data files. If you wish to do this, you are responsible for putting the data files in the appropriate directory yourself and making sure the names match the grades in the data files. The names of these files are as discussed in Point 2 above.

8 Help with errors

There are some common errors you can make with Grader and we give some of them here.

1. If setup_grades hangs, there is probably a TEX mistake in one of your grades.tex files. The working directory should have been echoed by setup_grades, so you should know where to look.

2. If you get a core dump when running grader, it usually indicates a problem with a data file, usually that it is the incorrect size for the parameters given

in input.dat.

3. Often the data given in input.dat is out of order or some such thing. The easiest way to check that you have entered in the values properly is to look over the output Grader writes on the screen as it reads in the data. All read in data is echo printed for this reason.

9 The Big Picture

Grader is part of a larger package that I have for helping me out with classes. I also have L^{A}TEX document class files, in addition to gradelist for making up assignments and solutions, exams and solutions, etc. You may get the necessary files from me if you wish. There is also a histogram making program for displaying your grades. The whole setup is documented for easy implementation.

Please send any comments and errors to: andrew@mast.queensu.ca.