Skip to main content Skip to navigation


GB: A Gradebook for Splus


Introduction | Examples | Tips


Listing Multiple Sections

Saving to a File

Converting Rosters to Datafiles



General Weirdness

Private Grade Home

Creating New Grade Types


Listing Multiple Sections

If you want to list all sections in a class, you just leave out the section letter...
and you'll get all sections in the class.

But if you TA two different sections and just want to list just your two sections, you can just supply a string of desired section letters...

to get sections A and F. the top


Saving a Gradebook to a file

While GBget can be used to display the gradebook, it can be also used to save it to a file...
> GBget(202,"A",File="202A.txt")
              Sec H1 L1 L2 L3 
    Smith.Joe   F 86  1  1  1
    Adams.Sue   F 74  1  1  1
      Wu.Jack   F 91  1  1  1
Neyman.Marcus   F 72 NA  1  0
The gradebook is still displayed as well as written to a file. the top


Converting rosters to datafiles

The function ezGBcreate can automatically create grade books based on comma-separated datafiles from the registrar's electronic grading website. Unfortunately, grad students can only get pretty-formatted rosters (after getting "proxy" access). This tip is about converting the rosters to the datafiles with the shell script rost2tab .

First, download this shell script rost2tab make it executable with

chmod +x rost2tab
and put it in the directory where you will work (or in your ~/bin/ directory).

Goto the electronic grading website and save your rosters to a file. Don't edit the file! Don't edit out header information because that's where the section letter is listed (though it's OK to edit out email headers if there are any). Also, it is OK to save all sections together in one file. Let's say I saved the file in " Rost.dat ", then I could say

rost2tab Rost.dat Comm.dat
The Comm.dat file will not look exactly like a registrar's comma-separated datafile, as some fields are NA, but all fields that are needed for the grade book are set.

Now you are all set to automagically create the grade book with ezGBcreate ! the top



To quickly create a stem and leaf plots of homeworks do this..
> stem(GBget(202,"A")$H1)
N = 40   Median = 83
Quartiles = 40.5, 89.5
Decimal point is 1 place to the right of the colon
   0 : zzzzzzzzz
   1 :
   2 :
   3 :
   4 : 01
   5 : 4
   6 : 356
   7 : 249
   8 : 033446666789
   9 : 0011111235
The key piece here is knowing what the column name of interest is. All homeworks are "H" then the number; Labs are "L"; Exams are "E"; Finals are "F"; the section column has label "Sec".

So, for example, to see the distribution of exam 1 scores, after the GBget call above, instead of "H1" you would use "E1". the top


"Did I just delete everything?"

The S object files are kept off in Andrew land (unless GRADE.HOME has been set otherwise) so you can't easily screw things up from S.

If you start using a function and you realize that you are doing something wrong or that you want to abort, just hit Control-C.

It is always OK to hit Control-C. In fact, until you see something like

Wrote 'GB.202.A' to '/afs/andrew/usr/tn0o/stats'.
no changes have been committed to the gradebook. This is useful to remember.

If you do see this message, then all is not lost: A " .bak " file is kept. Use the GBrecover function to get this back. (Precisely, it swaps the .bak with the current version.)

Alternatively, if you go to your GRADE.HOME directory you will find a backup file and you can manually manipuate it as follows. Look for your grade book Splus object file. It is named something like GB.202.A where 202 is your class and A is your section. The backup file is named GB.202.A.bak . Assuming that the current grade book is bad, swap it with your backup file like

cd /afs/andrew/usr/tn0o/stats
mv GB.202.A GB.202.A.bad
mv GB.202.A.bak GB.202.A
Return to Splus and run GBget(202,"A") to ensure that you have restored the previous version. the top



If each time you enter a grade you get a double echo...
    Abdul-Jalil,Jazaluddin.................. 0
    Casaday,Jeffrey......................... 1
    Chan,Susana............................. NA
...this is because you are using Splus with the emacs (-e) option. I don't know why this happens. It doesn't seem to have any effect on the gradebook.

The solution is to not specify the -e on the command line. If you don't and you get this weirdness anyway you most likely have "Splus" aliased to "Splus -e"; the easy solution is to disable the alias with a backslash, that is, "\Splus". the top


Private Grade Homes

By default the grade home is located on my Andrew account in a directory that only statistics faculty and grad students can access. If you are the only person who needs to access a grade file then you can simply set the S variable GRADE.HOME to whatever directory you like, but then only you will be able to view and change the grades. Using andrew's group access control facility can allow multiple Andrew user to have access to a directory.

To find out how to set up andrew groups so that you and a collection of Andrew users can all use the same GRADE.HOME directory, read this page on the AFS command pts. the top


Creating New Grade Types

When a new grade book is created there are seven types of grades: Section, Homework, Lab, Special, Exam, Final and Overall. These are determined by a function called DefaultGBtypes ; by creating you own version of this function you can create grade books that have different and/or additional grade types. This section outlines how to do this.

Danger!!! Do not proceed unless you are comfortable with programming in Splus! If you screw up this you can create broken grade books. Proceed carefully!

Here is the default DefaultGBtypes function. Start by copying this to a file:

"DefaultGBtypes"<- function()
    # "Section" ***must*** be in the first row
    #                   Type      Column    Grade    Mult
    #                   Name    Name/Prefix  T/F      T/F
    Types <- matrix(c("Section",  "Sec",     "F",     "F", 
		      "Homework", "H",       "T",     "T",
		      "Lab",      "L",       "T",     "T", 
		      "Special",  "S",       "T",     "T", 
		      "Exam",     "E",       "T",     "T", 
		      "Final",    "F",       "T",     "F", 
		      "Overall",  "OVL",     "T",     "F"), 
		    byrow = T, ncol = 4)  
    # row names are used to index into GBtypeC list
    dimnames(Types) <- list(1:dim(Types)[1], 
	c("Type", "ColNm", "bGrade", "bMult"))
First study this and understand what it does. In the form of a matrix of character strings, this describes everything GB needs to know about a grade. Going across columns...
Name of grade displayed in menus
Column Name/Prefix
A letter or few letters for column names
T/F, always true, except for Section
T/F, does the grade have multiple instantiations.
So the only thing you need to do is change the definition of the Types variable to alter the grades available, but take care of the following things
  • Section must be the first row, and it cannot be altered from it's current state.
  • The matrix is defined with a c(...) vector, take great care that there are exactly 4 elements for each row.
  • It is a character matrix; do not forget to put quotes around the "T" and "F" (all elements for that matter).
  • Multiple grades types should have single letter column names to prevent the printing of the table from taking too much room.
  • Do not alter anything else in the function!!!
  • Once you have made your changes, source the file in Splus and create a new grade book. Add a grade with GBaddgrade and you should see your grade types. You can also look at your matrix by examining the grade book object attributes, with
    You should see your type definition matrix listed as GBtypes .
    Extra for Experts!
    In the attributes you will also see a list GBtypeC consisting of vectors of column numbers; this is the key to the gradebook. For each row of GBtypes there is one element of GBtypeC ; that element lists the columns where you can find grades of a certain grade type.

    For example, the second row of GBtypes is "Homework"; say that the second element of GBtypeC was a vector 3 5 6 7 . This means that the first homework is in the 3rd column of the grade book data.frame, the second homework is in the 5th column, and so on. If an element of GBtypeC is NULL or numeric(0) , then there are no grades of that type.

    As an example of a new DefaultGBtypes function, say that I wanted to make a lean and mean grade book machine, tearing out all the grade book types I didn't use. I would create the following function:
    "DefaultGBtypes"<- function()
        # "Section" ***must*** be in the first row
        #                   Type      Column    Grade    Mult
        #                   Name    Name/Prefix  T/F      T/F
        Types <- matrix(c("Section",  "Sec",     "F",     "F", 
    		      "Homework", "H",       "T",     "T",
    		      "Lab",      "L",       "T",     "T"), 
    		    byrow = T, ncol = 4)  
        # row names are used to index into GBtypeC list
        dimnames(Types) <- list(1:dim(Types)[1], 
    	c("Type", "ColNm", "bGrade", "bMult"))
    This would be appropriate if I created my final grades outside of the grade book framework and there were no exams.
    Note 1
    Each time you re-source the original GdBk.S , you will overwrite your own DefaultGBtypes function; you will have to re-source your own private copy of DefaultGBtypes to retain the custom grade types.


    Note 2
    Once a gradebook is created with a modified grade types, the modified DefaultGBtypes is not needed. That means that the head TA can make her own private DefaultGBtypes , create the grade books for all the sections and then the individual TAs do not need to make any alterations to their grade book functions! The altered GBtypes are recorded in the grade book object and the standard GdBk functions will use them. (Cool, eh?) the top


    Last modified: Mon Jul 5 12:35:37 EDT 2004
    Tom Nichols (
    UM Biostatistics



    Contact Info

    Room D0.03
    Deptment of Statistics
    University of Warwick
    CV4 7AL
    United Kingdom

    Tel: +44(0)24 761 51086
    Email: t.e.nichols 'at'
    Blog: NISOx blog

    [Book Cover]

    Handbook of fMRI Data Analysis by Russ Poldrack, Thomas Nichols and Jeanette Mumford