How to Launch This

A simple python server is used here.

1. make sure you have python3
   Linux and macOS: to check the version type python --version¹ in your terminal
   Windows press windows + r and type cmd to open your terminal, and then type python --version
   If the terminal shows something like Python 3.x.x, ignore the step 2

2. If you do not see Python 3.x.x, download Python3, and follow the instruction to install it.

3. Now open your terminal and move to current directory to GardenRootsWeb/build
   You can do it by typing cd followed by the path of the directory.

4. Now type python -m http.server 8982² Now, you should see:Serving HTTP on 0.0.0.0 port 8982 (http://0.0.0.0:8982/) ...
   And, you can go to http://0.0.0.0:8982/ to see the website.

5. Shut down the server press ctrl+c in the same terminal.

---

1: could be python3 --version
2: could be python3 -m http.server 8982

Functionality of Each Module

This visualization has 3 parts: controller, model, and view.

controller

Controller.js contains the controller class. A instance of controller manages how view can interact with model.
Things to know:

1. the 1st parameter of setUpBackGroundMap and setUpPoints is a one-parameter callback function.
2. call setCurrentDataSet and setCurrentContaminant before calling setUpPoints
3. setCurrentCounty is optional.
4. the 2nd parameter of setUpPoints is a filter function, whose type is defined by JsDoc called filterPoints in Histogram.js

model

There are 7 files under the model directory.

1. APIReader.js contains the code that interacts with API. There are several functions defined in the class. Other classes can just call them to get data from API. Currently, APIReader is not used in the visualization. In the future, the visualization should use data from APIReader instead of data from local file.

2. BackGroundMap.js contains the code that loads the map of Arizona. The file should be in topojson format. Other classes can just call setUp function with a county and a callback. The callback function will be called with the map data.

3. ColorScales.js contains the code that calculates the color scales. Other classes can just call its calculateColor function to get correct color.

4. DataPoints.js represents a circle/point in the map. getData is the function that should be called from other files. It will return a js object (or someone calls it dictionary) that contains info needed by the visualization.

5. DataSet.js represents a data set. It manages DataPoints. Most of its functions are used in Controller.js

6. Model.js just contains most hard code values. They are either file paths or enumerated variables. It also keeps records of current data set, contaminant, and county. Call functions in this class to get instances of other model classes.

7. SizeScales.js contains code that calculate size.

Things to know:
Overall, each circle of the visualization is represented by a instance of DataPoint. All circles are managed by DataSet. ColorScales and SizeScales provides methods that convert data to values that view can use. Model is like a factory class. All other classes in model should be indirectly constructed by calling methods in Model.js to avoid unexpected behavior caused by constructing multiple times.

view

There are 9 files in view.

View.js is the top class that organizes other classes in view. Because it is complex, here is explanation of the purposes of each function. Further explanation of how-it-works can be find in the comments of code.

• static methods:
  • selectDataSet, selectContaminant, and selectCounty are called when user selects corresponding variables. See index.html
  • call launch to start this visualization. See index.html
• instance methods
  • selectDataSet, selectContaminant, and selectCounty are the instance version called by their corresponding static methods. the reason of doing this is to make sure there is only one instance of view (and this is how JavaFx did).
  • erasePreviousDrawing will erase the visualization.
  • drawDataPointsAndLegends will draw the visualization.
  • setUpWhiteColorLegend is called after the visualization launches and before user selects a data set and a contamination.
  • setUpBackGroundMap sets up the back ground map
  • setUpSvg sets up SVG and relevant zooming functions.

Histogram.js, SmallHistogram.js, and HistogramGroup.js are classes dealing with histograms.

• Histogram.js draws the big histogram when user selects a data set and a contamination.
• SmallHistogram.js extends Histogram.js and is managed by HistogramGroup.js to show small multiple histograms.
• SmallHistogram.js overrides some functions in Histogram.js and just throws error for them.
• Small multiple histograms will be shown when user only select a data set.
• HistogramGroup.js manages both Histogram.js and SmallHistogram.js, and View.js only deals with HistogramGroup.js
• When user clicks a bar in big histogram. A filter will be applied to circles (by passing the filter to model to get a new set of points) and new circles will be drawn in the map.
• Histogram.boundToMap takes 2 functions. The 1st one will erase all circles in the map (Points.erase). The 2nd takes 1 parameter and will setup points based on the given data (Points.callbackDrawPoints).

BackGround.js sets up the map of Arizona. It supports zooming.

Points.js depicts the circles (points) in the map. It supports zooming.

DataPointPrompt.js manages the prompt when user's is on a circle. Points.js takes care of it, so View.js do not know its existence

ColorLegend.js sets up the color legend, It does not support zooming, and there is no way to erase it. All it can do is recover to an all-white legend.

SizeLegend.js sets up the size legend. It supports zooming since the legend should be changed when the size of map and circles changes

Things to know:

• User cannot select none of the bars in the histogram since there is no reason to show an empty map when they have already selected a data set and a contamination. If they try, the selection will be reset.
• The object returned by DataPoint.js should have enough info for coloring and sizing points, but the controller still has a function to calculate color for histogram and a deprecated function to calculate size.

index.html

index.html is the page for the visualization. View.lunch() should be called after the website is loaded.

test.html

This is a proof-of-concept web page. It contains the code to deal with tract and census blocks. In the future, the visualization should be able to color these blocks by contamination level.

JsDoc

There are many types and function signatures defined in JsDoc. Make sure to read them before modifying the code and revise them after modifying relevant code.