INFORMATICS 41 • DAVID G. KAY • UC IRVINE • FALL 2011

Lab Assignment 9

This assignment is due at the end of lab on Friday, December 2.

Choose a partner for this assignment, someone you haven't worked with already. It will work best if you choose someone whose level of commitment to developing programming ability is close to your own (whether that's high or low).

Professor Andrea Anteater wants you to design a grade management system for her students in Applied Epistemology 101. This system will read and write students' scores from a file and allow the user to produce statistics and histograms (frequency graphs) of the scores.

Your task this week is to create this program from scratch. It's not really from scratch, though, so don't panic: We provide a set of specifications for you to implement and you can use all of the example programs we've seen all quarter. Hardly any programming today is totally from scratch; we have application frameworks (skeleton programs with all the infrastructure supplied), we have function libraries that provide commonly useful tasks, we have object libraries and class hierarchies that we can adopt and adapt to our own purposes.

To help you along, here are six pieces of development advice:

• Read the specifications carefully, more than once. Technical documents must be milked for all the detailed information they contain; you can't just read them one time quickly, like a mystery novel.
• Follow the model-view-controller organization; have a separate top-level "front end" part of your program (the view and controller part) that handles interaction with the user and a "back end" part (the model) that implements the operations on the different classes of data. This is how the restaurants program is organized.
• As you build the "model" part of the program, follow the design recipes, especially for creating examples and tests in advance.
• How do you know if you have enough tests, or the right tests? One simple measure of test effectiveness is called "code coverage"—your tests should, at the very least, evaluate each expression in the code. DrScheme helps you with this: After running your program, if you haven't tested every expression, some of the code appears highlighted in black. The highlighted code hasn't been evaluated, so you should add tests to exercise those parts of the program.
• Implement one small feature at a time, test it thoroughly, and then save a copy of your program so far. That way, if your next phase of development runs into trouble, you can "roll back" to the previous version and start over.
• Nearly every technique needed for this lab is something you've seen or done earlier this quarter. If you find yourself working on something that seems much more complex or convoluted than we've done before, reconsider your approach.

You'll be using Advanced Student Scheme for this program, with the advanced-file-io.ss teachpack. (Download the file; don't just copy and paste the code.)

One more thing before you get started: This assignment has two different starting points; you and your partner can choose either, and we'll make sure that either way, successful work is rewarded. If you're interested in software development, software engineering, or building your programming skills, start with part (a) below; that's the fully "from-scratch" approach, including building the input and output ("view") part. If you're less committed to software development, though, you can start with part (c), skipping parts (a) and (b) and using our "starter version" of the program; this will let you focus on the more substantial parts of the assignment and skip the input and output, which is important as a practical matter but kind of tedious to code up. If you choose the second approach, you'll still need to read through parts (a) and (b) below to understand what's involved, and read through the starter version of the program to understand how it works and how to modify it.

(a) Your program will handle these classes of data:

• Assignments, each represented by a name, a weight in computing the course grade [the weights of all assignments should sum to 100, though we're not requiring you to check this], and a number of points possible [which is independent of the weight; a three-point assignment could be worth 50% of the course grade]. ("Graded item" would be a better term, since it includes things like exams and projects. But we'll use "assignment" just because it's shorter.)


• A collection of assignment descriptions that together describe the graded items in the course
  
  
• Students, each represented by a name, an ID number, and a vector of scores (which should be the same size as the collection of assignments, one score for this student on each assignment)


• A collection of students

To start out, make sure you understand these data structures: Make up some examples; draw a picture; get comfortable with how they're organized. Then you'll want to define functions to display the information in an assignment and a student clearly; base these on rrant-print. Then, test out those functions with objects you construct using make-assignment and make-student. [Note on terminology]

(b) When your program starts, it will read the collection of assignments from a plain text file called Assignments.txt. (If you place your program file and these data files in the same directory/folder, DrScheme will find them without your having to do anything fancy.) Then it will read the collection of students from a text file called Students.txt. Since the user can create these files without knowing any Scheme, your program won't have to handle changes to the data (although that's an enhancement we discuss below).

The user can create these files using a plain ASCII text editor like NotePad (or from Word by using Save As and the Text Only format, which saves plain ASCII without the additional Word formatting information that your Scheme program can't read).

For a course with a 75-point midterm worth 40% of the grade and a 100-point final worth 60%, the assignments file would look like this:

2
Midterm Exam
40 75
Final Exam
60 100

The first line contains the number of assignments. Then each assignment has two lines, the first containing the assignment's name and the second containing two numbers, the weight followed by the possible points. [The code for creating one assignment should be similar to the rrant-get-info function, except that it's reading from a file instead of from the keyboard.]

A file of students for this course would look like this:

2
Aardvark, Aaron
11223344
68 85
Tapir, Tamara
44332211
74 92

The first line contains the number of students. Then each student has three lines, the first containing the student's name, the second containing the student's ID, and the third containing the student's scores on each assignment, in order.

Here are two lines of code to set up the reading from the two files listed above (in the same folder as your Scheme code):

(define assignment-port (open-input-file "Assignments.txt"))
(define student-port (open-input-file "Students.txt"))

Here are two examples of reading from the files:

(read assignment-port) ; Read one expression from the assignments file
(read-line student-port 'any) ; Read one line from the students file and return it as a string.

The 'any argument to read-line will handle files on both Windows and Mac; these systems use different characters to signal the end of a line.

As you read the input files, remember that the read-line function reads an entire line of input and returns a string (this is useful for reading strings that may contain blanks, without requiring the user to enclose the strings in quotation marks). The read function reads the next Scheme expression (e.g., a single number) from the input. You'll also want to call read-line (ignoring its return value) after reading numbers from a line; this will put you at the start of the next line so you're ready to read what's there. Some sample code using read-line is available.

[This organization of the input files should make it easy for you to use read and read-line to create the internal representation of the data in your program; your task is to fit these components together, and you should spend some time trying to do that. But if you decide you need some additional guidance, start by reading the assignments file, because it's simpler. As always when designing programs with more than one "layer" of data structures, you should treat one layer at a time. For the file of assignments, for example, you should have (a) a function to read the information for one assignment and create that assignment, and (b) a function to read the number of assignments (from the first line of the assignments file), call the single-assignment-creation function that number of times, and finally create the collection of assignments. Do make sure you understand how to use read and read-line: Choose the right function for the right kind of data, as described above.]

Define functions that will fill the assignment and student collections by reading these files. It will also be helpful to write functions that print out these collections legibly; they'll help you in testing.

(c) Since assignments don't necessarily all have the same number of points possible, it will be useful to compute and store a scaled score on each assignment (i.e., a number from 0 to 100, calculated from the student's raw score and the number of points possible on the assignment). It might be easiest to implement this by storing for each student a second, parallel vector of scaled scores.

You should also compute and store for each student the weighted overall score in the course, a number from 0 to 100 calculated from the scaled scores and the weights of each assignment.

To make the output look reasonable, use the function format-decimal. It takes two numbers (the first is the value to display, the second is the number of digits after the decimal point) and returns a string, suitable for use as an argument to display. So, (format-decimal 25 2) returns "25.00" and (format-decimal 17.9876 3) returns "17.988".

(d) Your program will have a text-based menu interface like the one in the restaurants programs. It should include commands to

• Search for a student by name or by ID (and display the student's information).
  
  
• Display all the students' information sorted by name or by overall score. [If your collection of students is a list, you can use the predefined quicksort function with a carefully constructed lambda expression to accomplish this automatically.]
  
  
• Display the information for all the assignments.
  
  
• Display a histogram for overall course scores or for the scores on a single assignment (see below).
  
  
• Quit.

[Your first step here should be to write the menu-handling code, based on the restaurants programs, before writing code to do anything when the user selects a given command. For each menu command besides Quit, just print out "Received command X," where X is the command; we call this a "program stub," a simple placeholder so you can see that the menu framework works before you write the code that actually performs each command. Then take each command, one by one, and code and test its implementation. You should use the restaurants code as a starting point, just changing the things you need to change for this task; don't try to create a new view/controller from scratch. Start with displaying the assignment information (because that's the easiest).]

(e) A histogram is a bar graph showing the distribution of all the students' scores, from highest to lowest. Given a list of scores, for example

(list 23 23 20 18 25 14 16 18 15 16 23)

the histogram should display

   25 *
   24
   23 ***
   22
   21
   20 *
   19
   18 **
   17
   16 **
   15 *
   14 *

Hints: You might find it particularly convenient to create a vector of frequencies where (vector-ref freqency-vector N) contains the number of students whose score was N. A simpler histogram would display the frequencies of scaled (0 to 100) scores, with 101 lines from 100 down to 0; start by implementing it that way. You'll want to use the predefined round function to convert all the scores to integers.

(f) Implement at least one of the following enhancements. In a comment at the top of your definitions, list which one(s) you implemented. Note that it is never acceptable (in class or in the real world) to submit buggy code. It is much better to deliver fewer features, but features that work correctly, than to provide fancier functionality that "almost works." [This doesn't mean that you have to implement every single aspect of a bullet item below, but it does mean that whatever you do implement must work correctly and consistently with the rest of your program.]

• Allow the user to change assignment and student information within the program, rather than just by editing the data files. Of course this also requires recomputing scaled and weighted scores and writing the files out when the user quits the program.
  
  
• Allow the user to add new students and new assignments, and to remove students and assignments, within the program rather than just by editing the data files. This will require creating new, larger (or smaller) vectors (or else creating vectors with a default size and keeping separate track for each vector of how much of it is actually being used). Adding a new student would require adding scores for that student on each assignment (although you could implement a default score of zero), and adding a new assignment would require adding scores for all students on that assignment (though you might handle it by reading the new scores in from a separate file).
  
  
• Improve the interface somehow (to give the user clearer or better organized information, help the user navigate through the functions and menus, or make it easier and less error-prone to enter data--not just to add decoration that doesn't serve any purpose). For example, you could allow the user to request a list of students sorted by score on an individual assignment (or to specify sorting in ascending or descending order). Or, you could implement a log file that saves a record of each transaction (each operation that changes the data); this could be useful for reconstructing the data files if they get damaged or deleted.
  
  
• Implement some error checking. What if the input file doesn't exist (or what if it does exist when you ask to create a new file)? What if the input data are not in the right order or format? Do the weights of the assignments add up to 100%? And so on.
  
  
• Implement hierarchical, nested assignments. In a typical course, there might be lab assignments worth 30% of the course grade (let's say five assignments, each equally weighted at 20% of the total lab assignment score), a midterm worth 25% of the course grade, and a final exam worth 45% of the course grade (made up of eight problems whose points total to 100). The point is that each graded item can be a single item (as we've been handling all along) or it can be a compound item (with its overall weight in the course along with some number of subcomponents (each of which has its own name, possible points, and weight as part of its parent component). Of course that means a subcomponent is just a graded item, and that there's no reason subcomponents can't have their own subcomponents. You'll need to represent these graded items in the "model" part of the program and work out how to read, write, and display them.
  
  
• Enhance the file-handling. You could get a name or number for each course; incorporating that into the names of the data files would allow using the program for more than one course. Then, when the program starts, you'd need to ask the user which course to handle. You might also give the user the option to create a new class rather than reading information from an existing one, or to choose any name for the assignment and student files.


• Add a command to produce a histogram of the scores for a given graded item (e.g., just the midterm).


• Enhance the histogram in a variety of ways:


• The original histogram displays scores in one-point intervals. That could lead to a pretty big histogram on a 100-point test. This interval is sometimes called the "bin size." You can allow the user to specify the bin size and display scores grouped accordingly.


• Make the upper end of the top bin's interval the highest score on the list (so if nobody scored above, say, 80, you don't have empty space between 80 and 100. Likewise, don't go lower than the lowest score.
  
  
• Take the number of bins as the parameter (so you'd calculate the bin size based on the top score, the bottom score, and how many bins the user wants).


• Take the lowest 5% of the scores and collect them into the bottom bin, "N points and under." This may spare the feelings of the person who had the very lowest score in the class.
  
  
• Scale the histogram horizontally, too: The bars may be too wide if the class is large. Let the user specify the length of the widest bar and scale the others accordingly.


• Print the histogram horizontally (on its back, so to speak).
  
  
• Use the functions in the picturing-programs.rkt teachpack to produce the histograms graphically.
  
  
• Implement the collection of students as a binary search tree, sorted by the students' names.


• Distinguish between no score (which would be appropriate if someone missed an assignment entirely) and a zero (for someone who did the assignment but earned zero credit).

(g) Submit the file containing all your definitions as usual via Checkmate.

(h) Complete your last partner evaluation form at eee.uci.edu. Please do this by Saturday morning at the latest, or you won't get credit.

Written by David G. Kay for the innaugural Informatics Core Course, Fall 2004, and modified Fall 2005, Fall 2008, and Fall 2009. Modified Fall 2010 by David G. Kay to reflect the Picturing Programs text and Fall 2011 to include multiple starting points.