ECE 242 Project 2

Prof. Tilman Wolf and Prof. Lixin Gao Due: Thursday 10/6/11 at 11:30 p.m.
[...] if people put data onto the web government data, scientic data, community data, whatever it is it will be used by other people to do wonderful things, in ways that they never could have imagined. Sir Tim Berners-Lee, TED talk, February 2010.

Introduction
In this project assignment, you will implement a program that computes which cities are in range of current earthquakes. The program will use real data source: a database that contains information about all populated places on the entire globe and a real-time feed of the most recent earthquakes that have been observed. Your program will read information from these sources and store it in linked lists. Then, the linked lists are processed to nd which populated areas are within the range of a particular earthquake.

Overview
The project will use the following information that is available publicly on the Internet: The GeoNames geographical database that contains place names from all countries. For this project, we will use the complete name database that can be found at http://download.geonames.org/ export/dump/allCountries.zip . Please note that this database is very large (206MB zipped, 914MB unzipped). We provide code to read this database and extract all cities with a population above a certain threshold. (Your program will ignore smaller cities and towns to keep the problem tractable. You can change this threshold as discussed below.) The up-to-date data on earthquakes provided by the Unites States Geological Survey. For this project, we will use the list of all earthquakes of magnitude 2.5 and above from the previous 7 days available at http://earthquake.usgs.gov/earthquakes/catalogs/eqs7day-M2.5.txt . Note that this le is updated continuously as new earthquakes are recorded. The geographical location of both cities and earthquakes is available in both data sources as latitude and longitude. Therefore, it is possible to calculate the distance between an earthquake and any city. For this assignment, we consider a city to be in range of an earthquake if the distances between the two is at most the earthquakes magnitude times 100 miles. (Note that this denition of range is somewhat arbitrary. It is not based on geological principles or related to the eect an earthquake has on a populated area.) The goal of the project is to determine how many people are within the range of each earthquake by determining the cities that are within range and adding their population. The program output should report the following: 1. For each earthquake, print out in one line the earthquake information, how many cities are within range, and the sum of the population in those cities. The order in which the earthquakes are printed does not matter. An example of one earthquake output line is: Wednesday, September 21, 2011 23:43:10 UTC (Izu Islands, Japan region, mag: 4.4, coord: 33.753/139.653) cities in range: 11 population in range: 25442120

2. For the one earthquake that has the highest number of people within range, print out the earthquake information and the list of cities within range and their information. An example of this output is: Wednesday, September 21, 2011 22:18:32 UTC (Taiwan, mag: 5.1, coord: 24.0338/121.6957) cities in range: 9 population in range: 43371874 list of cities: Shenzhen (CN, pop: 3000000, coord: 22.54554/114.0683) Shanghai (CN, pop: 14608512, coord: 31.22222/121.45806) Puyang (CN, pop: 3590000, coord: 29.46028/119.88611) Nanchang (CN, pop: 1871351, coord: 28.68333/115.88333) Hangzhou (CN, pop: 1878129, coord: 30.29365/120.16142) Kowloon (HK, pop: 2019533, coord: 22.31667/114.18333) Hong Kong (HK, pop: 7012738, coord: 22.28552/114.15769) Taipei (TW, pop: 7871900, coord: 25.04776/121.53185) Kaohsiung (TW, pop: 1519711, coord: 22.61626/120.31333)

Details
Your program should take in one command line argument that states the population threshold. For example, if the argument is the string 1000000, then only cities with a population of 1 million and above are used in your linked list. Using smaller thresholds will cause your program to use more cities and be more accurate in its estimation of people within the earthquake. Your program should work correctly for any valid population threshold. Your program should work with the full geographic location database. For convenience, we provide a le containing only the rst one hundred thousand entries of this database so you can test your program with a smaller le. Reading the entire database may take a few minutes depending on the speed of the computer. Your program should work with the online earthquake information. For convenience, we provide a le containing a snapshot of earthquakes for oine use. Please see the sample code in the main() method for switching between online and oine data. Your program should use one linked list to store all earthquakes as well as one linked list to store all cities that exceed the population threshold. (Do not store cities that are below the population threshold there are over 3 million populated places in the database and storing all of them may make your program very, very slow.) The information of what cities are within the range of a specic earthquake should be stored as a linked list that is attached to that earthquake. Since earthquakes are also stored as a linked list, you will create a list of lists. Note that a city may appear multiple times across lists (since there may be multiple earthquakes that have one particular city within its range). The linked list data structure and all its methods should be implemented by you. While it is unavoidable that there are some overlaps between the code provided in class and your code, you really should code the linked list functionality from scratch. To calculate the distance between two locations on the globe that are represented by latitude and longitude, you should use the Haversine formula (http://en.wikipedia.org/wiki/Haversine_formula). For an example how to implement this formula in JavaScript, see http://www.movable-type.co.uk/ scripts/latlong.html . Please verify the correctness of your implementation carefully, since incorrect distance results lead to an incorrect nal result. As stated above, a city is considered to be within the range of an earthquake if the distances between the two is at most the earthquakes magnitude times 100 miles. You may make any modications to the classes provided to you for this project.

How to Start?
We are providing you with a set of classes that can read in the databases and print some of the information in them. Download these classes and put them into your Eclipse project. In addition, you need the allCountries.txt le, which you can download from the link provided above. Alternatively, you can download the allCountries.100000.txt le from the course web site and use this smaller le for testing. (Note that you need to rename the le to allCountries.txt or change the code in the main() method. Also note that the geographic database le needs to be unzipped and located in the project directory for Eclipse to nd it.) As a rst step, run the code in the EarthQuakeMonitor class to see the output of the program. Examine the code to understand its operation. You will need to make considerable changes to the main() method for your project. As a second step, decide how you want to implement the linked lists that contain the earthquakes and the cities. Then gure out how you can associate a list of cities with each earthquake in your list. Third, change the code to read the earthquakes and cities into the data structures you have created. Use print() methods to verify correct operation. Finally, identify the cities that are within the range of an earthquake and create the linked list that associates them with the earthquake, etc. Experiment rst with a smaller geographic location database since reading the entire database takes a lot of time. Once you are condent that your program works, try it for the full database and dierent population thresholds.

Grading
You should submit your complete code in a .zip le on SPARK. This zip le should also contain a le named output.txt that contains the output of your program for one run with a population threshold of 1 million (using the full location database). You will receive 75 points for your code running correctly and 25 points for the thoroughness and usefulness of the comments included in your code. The breakdown of points is: Program uses command line parameter for population threshold: 5 Implementation of the linked lists: 10 Program reads databases into linked lists: 5 Correct implementation of distance function: 5 Program determines correct set of cities within range of earthquake and stores them in linked list: 20 Program prints out correct number of cities within range and population total: 15 Program prints out correct earthquake with highest amount of population and correct list of cities: 15 Comments describing your design decisions and how the code operates: 25 Note that all submissions must adhere to the course policies posted on the course web site.

Remarks
You may want to consider implementing a linked list class that uses a generic type so you can use it for both earthquakes and cities. (Not necessary, but may make things simpler.) You may want to implement an iterator for your linked list. (Not necessary, but may make things simpler.) Feel free to play with your working program to see how changing the population threshold changes the population total within the range of an earthquake (and, of course, the running time of your program). No extra points for that just for your own intellectual stimulation.