Documentation for tt.py

This program examines a csv file ????TT.csv (e.g. 0910TT.csv -- see below) which holds the 'local' version of the Math Department Timetable for an academic year. It checks for certain errors (e.g. the same instructor teaching two different courses at the same time) and produces various html files (see below) which show different views of the timetable. A companion program cmpTT-TD.py compares the local version of the timetable with the 'official' version from the UW Data Warehouse. The local version changes frequently, but the official version should only be updated during certain 'windows'. The associate chair uses the local version to record and display changes; the timetable secretary updates the official version as allowed. The departmental administrator will use the html output to ascertain that each instructor is teaching his/her contractual load. The documentation (including these very words) is written into the program itself and is output as tt_doc.html every time the program is executed.

Auxiliary files

Two auxiliary files are used:

A .csv file named ????FAC.csv (for example 0910FAC.csv--see below) with one row for each instructor showing how many courses that instructor will teach for the math department during the year together with a maximum for the fall and a maximum for the spring. A typical line is 'viaclovsky,3,2,2'
A file strings.py which defines three associative arrays:
- name[]: The key is the instructor's last name in lower case, possibly extended to avoid clashes, e.g. name['robbin']='Robbin,Joel', name['miller_a']='Miller,Arnold', name['miller_j']='Miller,Joe'. See get_key() below. This array should be updated to enter new faculty members. The array name[] may also contain fictitious instructors who will be assigned courses outside the math department so that the program can catch time conflicts. For example, the instructor for math 709 is 'statistics' (taught as an overload -- see ! below) and the program will issue a warning if math 709 has a time conflict with math 721. (See check_for_time_clash_miscellaneous() below.)
- title[]: The key is a three digit course number, and the value is the title of the course, e.g. title['112']='College Algebra'.
- time[]: These are the standard times. The value is a pair (two element array) consisting of the begin time and the end time, and the key follows the naming convention 50_xx (for a 50 minute period) or 75_xx (for a 75 minute period) where xx is the hour (24 hour clock) when the period begins. For example, time['75_09']=['09:30','10:45'] and time['50_13']=['13:20','14:10']. If a course is to be taught at an unusual time, a corresponding entry should appear in this array. Be sure to type '09:30' not '9:30'.

The function get_key() in strings.py assumes that name clashes can be resolved by adjoining '_'+ch where ch is the first character of the first name. Thus get_key("Miller,Arnold")="miller_a". Itis possible (but unlikely) that this function will have to be modified if a new faculty member has the same name as an existing faculty member.

Invocation

The invocation 'tt.py 0910' will define the names of the two csv files to be used in the program as '0910TT.csv' and '0910FAC.csv' It will also define names 'FALL=1102' and 'SPRING=1104'. These are the names of the fall and spring semesters in the UW data warehouse cyyt format (see below). For the academic year 2010-2011 the invocation will be 'tt.py 1011', the csv files will be 1011TT.csv and 1011FAC.csv and FALL and SPRING will have the values 1112 and 1114 etc. In this documentation we refer to these files as '????TT.csv' and '????TT.csv'; the '????' is intended to emphasize that the files get a different name each year.

The invocation 'tt.py -h 0910' prints the first (header) line of 0910TT.csv and exits. The purpose is so that the user can ascertain that 0910TT.csv has a heading and that it is in the proper format. The -h option is the only recognized option.

Reading the .csv files

The function csv2rows(file_name) reads a .csv file and returns an array of arrays (rows). It assumes that fields are separated by a comma and that there are no quote characters. Empty lines are discarded. All fields are read as strings. There are two calls:

instructor_table=csv2rows(INSTRUCTOR_FILE)
course_table=csv2rows(COURSE_FILE)

Format of instructor_table

The function normalize_instructor_table below will convert columns 1,2,3 in instructor_table to int and add two more columns so that instructor_table has six columns:

NAME=0
NCOURSES=1
MAXFALL=2
MAXSPRING=3
ASSIGNEDFALL=4
ASSIGNEDSPRING=5

The NAME field contains a key which must appear in the aformentionned associative array name[] from strings.py. The fields NCOURSES, MAXFALL, MAXSPRING, represent respectively the number of courses the instructor will teach in the academic year (for the math department), the maximum number in the fall, and the maximum number in the spring. The function extend_instructor_table() will fill in the values for fields 4 and 5 using information in course_table. Fields 1-5 will converted to ints.

Format of course_table

Here are the fields which (should) appear in course_table:

TERM=0
NUMBER=1
SECTION=2
FLAGS=3
DAYS=4
TIME=5
INSTRUCTOR=6
ROOM=7
CAP=8
NOTES=9

The INSTRUCTOR field in course_table should be a key in the associative array name[] in strings.py. It will be matched with the NAME field in instructor_table. The NUMBER field should be a key in title[] and the FIELD should be a key in time[]. The DAYS field should be a set of letters chosen from MTWRF. The four fields TERM, NUMBER, SECTION, FLAGS determine the row uniquely. A digit in the FLAGS field is used to distinguish multiple instructors for the same seminar. A ! in the FLAGS field indicates that the course is an overload, i.e. is not part of the instructor's required teaching load in the math dept. An instructor with a joint appointment teaching a course in another department should show a reduced teaching load in ????FAC.csv and, if that other course shows in our timetable, there should be a ! in the FLAGS field. It is desirable to show the other course in our timetable so that the program can check for time conflicts and so that it will show up in the html files.

Utility Functions

The function error_in_file(msg) reports an error (to the terminal) which must be fixed to ensure the integrity of the data. It reports the error as on line cx+2 since the header line was deleted and the first line of an array has index 0.

The function time_clash(cx1,cx2) tests whether course_table[cx1] and course_table[cx2] ever meet at the same time. It depends on strings.py

The routine cyyt2semester(cyyt) translates the arcane UW code for the semester into normal language. Here cyyt denotes a semester in the UW numbering system c = century (0=1900 or 1=2000), yy = academic year (09 represents 08-09), t = term (2=Fall, 4=Spring, 6=Summer). For example ccyt2semester(1102) returns 'Fall 2009'.

The function show_header() displays the header row in the course_table on the terminal as reassurance that the file ????TT.csv is in the correct format. It is only executed if the user chooses the 'h' option and types an academic year ???? in the invocation. The header row is then deleted from course_table[]. (The program tt.py does not modify the .csv files.)

Integrity Checks

The routines normalize_instructor_table(), normalize_course_table(), extend_instructor_table(), ensure that instructor_table and course_table have predictable form. The function extend_instructor_table() also incorporates information from course_table into instructor_table as explained above.

More Error Chacks

The function check_for_duplicate_keys() checks that distinct rows in course_table have distinct keys, i.e. that they differ in at least one of the four fields TERM, NUMBER, SECTION, FLAGS. The data returned from the UW data warehouse does not include a FLAGS field and the three values TERM, NUMBER, SECTION do NOT determine a row uniquely, e.g. if the same section has multiple instructors.

The function check_for_time_clash_by_instructor() ensures that an instructor does not have to be in two different places at the same time.

The function check_for_time_clash_in_our_rooms() assures that two classes do not meet in one of the rooms
our_rooms=['B102','B130','B239','B107']
at the same time. The three lecture rooms B102, B130, B239 are the only large rooms in Van Vleck and the Math Dept has first dibs on them. The room B107 is a special computer room which is sometimes used as a class room. The program cmpTT-TD.py mentioned above does NOT attempt to ascertain that there is agreement in the ROOM field.

Warnings

The function check_for_time_clash_in_qualifying_exam_courses() warns if the times of two qualifying exams conflict. These courses are

qualifying_exam_courses = ['703','704','714', '715', '721','722','725','741','742','751', '752','761','770','771','773','776']

The function check_for_time_clash_miscellaneous() warns against certain undesirable time conflicts in various courses. These are
required_math_ed_courses=["371","441","461","475"]
fall_statistics=['709','721','831']
spring_statistics=['710','629','832']
advanced_undergraduate=["551","552","522","542","561","567"]
Also the Math Ed course should be offered at the following times:
ok_math_ed_times=[["TR",'75_08'],["TR",'75_09'],["TR",'75_11'],["MWF",'50_12'],["MWF",'50_11']]
Click here: here for info on the math ed program.

The function check_for_too_many_days() warns if an instructor has a teaching schedule of more than three days per week.

The function check_instructors_have_correct_number_of_courses() warns if an instructor's teaching load does not agree with the information in instructor_table (i.e. in the file ????FAC.csv'). Note that a (!) in the FLAGS field in course_table means that the course is an overload, i.e. is not part of the instructor's required teaching as indicated in the file ????FAC.csv.

The function show_still_must_be_assigned_fall() is used to ascertain that before the spring semester begins, every instructor has been assigned enough courses in the fall semester so that it will be possible to complete his/her required teaching in the spring.

Unlike the previous error checks and warnings, the function count_courses() produces only terminal output (not html). It counts the number of courses in in course_table[] and examines instructor_table[] to report how many instructors are available.

HTML files

The following html files are produced as output:

TT_timetable_by_course_(term).html
TT_timetable_by_instructor.html #
TT_abridged_timetable_by_course_(term).html
TT_sorted_by_time.html
TT_grad_courses_sorted_by_time_(term).html
TT_timetable_by_grad_course_(term).html
TT_our_rooms_usage.html
TT_warnings.html
tt_doc.html