CS 315 Homework 1 - Data Grapher Online

Due Fri Sep 12 at 11:59pm

Overview

This assignment will give you a chance to get started with JavaScript and creating graphics, as well as to begin thinking about the use of graphics as representation.

You will be making a basic webpage that displays simple graphs of numeric data. Your webpage will be able to show different kinds of charts: line charts, bar charts, and pie charts. Your charts will include simple decorations (i.e., labels), and should use color to differentiate between data sets. The data to graph will be loaded and parsed from a specially formatted textfile.

You will be drawing these charts using an HTML5 canvas, which provides an API reminiscent of the Java2D API that you should be familiar with. While we will soon move beyond this simple API to doing more complex graphical operations, the canvas provides a good basis for experimenting with and learning JavaScript.

Note: while there are many different existing libraries for generating charts in JavaScript and HTML5, for this assignment you will need to create charts "from scratch". This will give you a more thorough practice with JavaScript, which you will need for the rest of the course. However, you are welcome to look at other libraries for examples of what might make a chart "look good", as well as for ideas for further embellishments!

This assignment should be completed individually.

Objectives

Setup a development environment that will support the creation of future WebGL projects.
Practice implementing programs in JavaScript, using simple control and data structures.
Review and utilize a simple API for creating pretty pictures!
Consider the difference between graphical representations of information.

Necessary Files

You will need a copy of the cs315-hwk1.zip file which contains a basic code framework to get you started. I'll describe the file structure briefly, since future assignments will use a similar setup.

assets/
This folder is a place for you to store application "assets"--images, models, etc. In this assignment, this folder is a nice place to put the textfile that contains your data. An example data file should already be inside!
lib/
This folder contains 3rd party JavaScript libraries that are provided for your convenience. This assignment includes JQuery, an incredibly helpful library for working with HTML and JavaScript, and utils.js which contains a helper method for you (a Utils.loadFileText() that you will need).
grapher.js
This file will contain your code for drawing graphs. I have provided a basic outline to get you started accessing the HTML5 canvas. In short, I've set up a global graphics context that you can start drawing with! Note that you should make additional helper methods to organize your code, refactoring where necessary. You are of course welcome to also refactor into additional JavaScript files if needed.
grapher.html
This is a basic HTML file that loads and runs the JavaScript (as well as the lib libraries), and gives you a simple canvas to work on. Adding extra interaction to your program (like buttons, etc) will require you to modify this; otherwise you can leave it alone. Remember, this is not an HTML class; we'll be focusing on JavaScript and graphics!
- If you want to change the size of the canvas, you would do that here.

Normally, you can view a simple website simply by opening a .html file in your favorite browser. However, for security reasons you can't have JavaScript load a file that comes from a different source. Thus in order to easily load external files (which we'll be doing regularly), you'll need to instead load your grapher.html page from a web server.

You don't actually need to put your assignments online; instead you can just run a local web server and serve web pages to yourself! (You let your computer be both the server and the client). The easiest way to do this (which is sufficient for this class) is by using Node.js and specifically the http-server package.

First, download and install node.js on your machine.
On the terminal, run the command
```
npm install http-server -g
```
in order to install the http-server package.
In the terminal, change directory to the root of your assignment (that is, the directory with the grapher.html file), and run
```
http-server .
```
(don't forget the period!)

This will start a local webserver at you can access at localhost:8080/, and you can access the grapher.html file via localhost:8080/grapher.html. Open that link in your browser and you should see your application! You will need to do this every time you want to view your application (but you only need to run the command once, then just refresh the page to see changes to your code reflected).

Resources

There are a number of good tutorials and references for working with the HTML5 Canvas, including

among others.

Assignment Details

The overall goal of this assignment should be straightforward, though there are a couple of moving parts.

I suggest you start out by making sure you can draw shapes, lines, text, etc.. This will let you get a feel for the starter code, practice calling JavaScript methods, and let you review working with things like the inverted graphics coordinate system.
- For example, can you draw a red square on the canvas? How about a green triangle?
The next think you should do is load in the external data file. You can do this by using the Utils.loadFileText(filename) helper method. (Because the JS file is included via the HTML, the method is already available to you). This method returns the plaintext contents of a file; you can try "printing out" those contents using the console.log() method. This is the closest method to System.out.println() JavaScript has, and will put the results on the "JavaScript Console" (which you can view via the Developer Tools in Chrome or Firefox).
After you've accessed the contents of this file, you should parse it into a format that you can use. In particular, you should parse it into a JavaScript Object (what you might get via JSON notation). This is basically a Hash of the information, with keys linking to different values. You should produce an object with the format:
```
  {
    title : 'This is the Graph Title',
    data : [
      {
        label : 'First Item',
        value: 10
      },
      {
        label : 'Second Item',
        value : 20
      }
    ],
    formats: [ 'bar', 'line', 'pie' ]
  }
```
When you log this object to the console, you should see something like the below in the Developer Console:
- You can use use built-in String methods to process and parse the data. See http://www.w3schools.com/jsref/jsref_obj_string.asp for examples. This should be just like what you would do in Java!
- The first line in the provided data file is a list of formats the graph can and should be displayed in. The second line is the Title of the graph. The subsequent lines are each a line of data as a comma-separated list. The data file I've provided uses categorical numeric data (so the first item is the category, followed by a comma, followed by the number).
- Be sure your final program logs the JSON object to the console for grading purposes!
After you've organized the graph data, you can start drawing graphs of it! Your program should graph the same data in three ways, drawn in a row for easy comparison!
1. Line graph
2. Bar graph
3. Pie graph
I recommend you start with the Line Graph, as it's probably simplest. Think about the area your graph will take up, and how to scale the data so that it fits into your space nicely.
- This may involve some simple linear interpolation. For example, if your dependent value ranges from 100 to 250, and you have 300 pixels of height to work with, you can figure out the height of value i using something like y = ((x-100)/(250-100))*300. Remember that the canvas y axis is inverted!
  
  You can use similar math to figure out the horizontal position.
- Also be sure and add appropriate axis and chart decorations (tick marks, labels, etc)! You might also draw a little circle or box at each data point, in addition to the line graph.
- Look at the moveTo() lineTo() and stroke() methods for drawing lines, and the fillText() method for drawing text labels.
Next up is the Bar Graph This will work a lot like the line graph, but you'll need to figure out the position for rectangles instead of just for line points. This will involve modifying your math a bit; can you possibly refactor to avoid code duplication?
- You should make sure to give each bar a different color. Note that you specify the fill color by setting the fillStyle fillStyle attribute (set an attribute, don't call a method!). You can set this to a Hex value for color, but you can use any CSS color value. This means you can use rgb(red,green,blue) to set the RGB values of a color, or hsl(hue,saturation,brightness) to set the HSV values of a color, etc. You can also use predefined color names (like 'Green').
  Since you don't know how many colors you might need, you could consider using an algorithmic process to pick a color for the n^th item. See here for an example.
  
  If you're interested, Tufte has a long but interesting analysis of the use of colors in graphs and visualizations.
- Don't forget to include labels! Is there a way to organize your code to reuse the labeling from your line graph?
The last graph to make is the Pie Graph. This one is a bit trickier, since you have to draw non-standard shapes (pie wedges).
- Look at making Paths on the canvas; this will let you specify the wedge as a "shape" that you can draw and fill. The arc() method will be particularly handy for specifying the curved portion of the wedge. Note that arc() works in radians. Thinking about things in terms of polar coordinates may also help you with the math for determining where to put text labels!
- You are welcome to make this an exploded pie chart or a donut chart if you think those look better!
- You'll want to reuse your coloring code to give each piece of the pie a different color.
For the last step in this assignment, you should add in your own data table to graph---really take ownership of your charts! Using the same format as provided, add a new .txt file to the assets/ folder that contains a table of data that you feel is worth graphing
- Note that these simple graphs only handle one dimension of data; if you want to graph more dimensions, you'll need to extend the assignment (which could be worth extra credit).
- You might consider graphing things like

Extensions

Once you've got the basics of your charts working, go all out! You can add in further decorations, interaction (e.g., bolding bars when you mouse over them), etc. Exceptional, creative submissions makes for a happy professor, and a happy professor may give you extra credit.

But be careful: it can be easy to get bogged down in these extra features; make sure you have the core components in first!

Submitting

BEFORE YOU SUBMIT: make sure your code is fully functional! If your code doesn't run, I can't give you credit! And yes, you should include comments explaining what your code and methods do (to help me as well as help you)! Exclamation point!

Upload your entire project (including the lib/ and asset/ folders) to the Hwk1 submission folder on vhedwig (see the instructions if you need help). Also include a filled-in copy of the README.txt file in your project directory!

The homework is due at midnight on Fri Sep 12.

Grading

This assignment will be graded out of 20 points:

[3pt] Parses the data table, produces a JSON object, and logs that to the console
[3pt] All graphs have titles and labels on both the x- and y- axes
[3pt] Draws a Line Graph of the data, with items labeled
[4pt] Draws a Bar Graph of the data, with appropriately colored bars
[4pt] Draws a Pie Graph of the data, with appropriately sized pieces
[1pt] Coding style (good readability, cohesion, comments, etc)
[1pt] Includes a new data source that can also be graphed
[1pt] README is complete