Commented up spreadsheet generator

data/csv2js.py

@@ -1,5 +1,13 @@
 #!/usr/bin/env python
 
+# Author: Bryan J. Brown
+# Email:  [email protected]
+# Date:   Spring semester, 2014
+# 
+# Script for pulling historical metadata from Google spreadsheets and parsing into Leaflet JS
+# Created for the 'Globalization of the US, 1775-1861' project w/ Konstantin Dierks
+
+
 import sys
 sys.dont_write_bytecode = True
 import urllib2
@@ -8,7 +16,7 @@
 import time
 import subprocess
 
-# ./settings.py, controls automation options
+# ./settings.py, controls various script options
 import settings
 
 
@@ -23,7 +31,7 @@
 if os.path.exists(cwd + "/data.js"):
   os.rename(cwd + "/data.js", cwd + "/backups/data_" + tf + ".js")
 
-# Grab CSV data from Google Docs spreadsheet and save to data.csv 
+# Grab remote CSV data from Google Docs spreadsheet and save to local file 'data.csv'
 csv_local = open("data.csv", 'w')
 csv_link = "https://docs.google.com/feeds/download/spreadsheets/Export?key={0}&exportFormat=csv&gid=0".format(settings.gdoc_id)
 csv_data = urllib2.urlopen(csv_link).read()
@@ -34,10 +42,13 @@
 csv_input = open("data.csv", "r")
 reader = csv.DictReader(csv_input, delimiter=',')
 
+# Initialize empty arrays to hold each metadata record according to record type
+# (each individual record will be stored as its own hash inside these arrays)
 map_list = []
 marker_list = []
 shape_list = []
 
+# Sort records by type
 for line in reader:
 
   if line["Type"] == "Map":
@@ -94,13 +105,20 @@
 js_output = open("data.js", "w")
 js_output.write("// Leaflet data, compiled on " + tf + "\n")
 
+# Create marker cluster var so that individual objects can be appended to it as they come
 js_output.write("\nvar cluster = new L.MarkerClusterGroup();\n")
 
+# Initialize empty hashes to store array of records by key
+# This is to generate the list of everything that should turn on/off by layer
+# such as categories (cat_dict), records with only a start date (start_dict),
+# records that only exist for one year in time (iso_dict) and records that only
+# exist between a start year and end year (range_dict)
 cat_dict = {}
 start_dict = {}
 iso_dict = {}
 range_dict = {}
 
+# Generate all js map vars, write to 'data.js' and store a copy in base_layer array
 js_output.write("\n")
 base_layer = []
 for index, map in enumerate(map_list):
@@ -110,6 +128,10 @@
   base = "'{0}': map{1},".format(map['title'], index) 
   base_layer.append(base)
 
+# Generate all js marker vars and write to 'data.js'
+# Also generate pop-up to display relevant metadata and bind to marker var
+# Next, append marker var to cluster layer
+# Finally, store record data in relevant hash depending on category and year metadata
 js_output.write("\n")
 for index, marker in enumerate(marker_list):
   marker_name = "marker{0}".format(index)
@@ -171,6 +193,9 @@
     cat_dict[marker["cat"]][marker["subcat"]] = []
   cat_dict[marker["cat"]][marker["subcat"]].append(marker_name)
 
+# Generate all js shape vars and write to 'data.js'
+# Also generate pop-up to display relevant metadata and bind to shape var
+# Finally, store record data in relevant hash depending on category and year metadata
 js_output.write("\n")
 for index, shape in enumerate(shape_list):
   js_output.write("var json{0} = {1}; ".format(index, shape["json"]))
@@ -209,9 +234,6 @@
   pop_text = "\"" + title + year_range + desc + hist_loc + pres_loc + src + "</p>\""
   js_output.write("shape{0}.bindPopup({1});\n".format(index, pop_text))
 
-
-
-
   if not shape["cat"] in cat_dict:
     cat_dict[shape["cat"]] = {}
   if not shape["subcat"] in cat_dict[shape["cat"]]:
@@ -234,7 +256,7 @@
       range_dict[key].append("shape{0}".format(index))
 
 
-# Create chronological layers
+# Create layers of objects with related years
 js_output.write("\n")
 for year in start_dict:
   js_output.write("var start{0}Layer = L.layerGroup([".format(year))
@@ -285,6 +307,8 @@
   js_output.write("]);\n")
 
 
+# Set styling options for category/subcategory icons and shapes, and search the images folder
+# for filenames that match category/subcategory names
 if settings.style_refresh == True:
   style_file = open("style.js", "w")
   images = os.listdir("../images")
@@ -317,31 +341,32 @@
   style_file.close()
 
 
+# Set all category/subcategory layers to be toggleable from control panel
 js_output.write("var overlays = {")
 for overlay in overlayer:
   js_output.write(overlay)
 js_output.write("};\n")
 
 js_output.write("\n")
 
-# Create basemap layer, map and control panel
+# Set all basemaps to be selectable from control panel
 js_output.write("var baseLayers = {")
 for base in base_layer:
   js_output.write(base)
 js_output.write("};\n")
 
-
+# Set boundaries for map
 js_output.write("var southWest = L.latLng(-68.13885, -178.59385)\n")
 js_output.write("var northEast = L.latLng(79.68718, 189.14063)\n")
 js_output.write("var bounds = L.latLngBounds(southWest, northEast);\n")
 
+# Initialize map and append cluster layer group
 js_output.write("\n")
 js_output.write("var map = L.map('map', {{ center: {0}, zoom: {1}, maxBounds: bounds }});\n".format(settings.init_center, settings.init_zoom))
 js_output.write("L.control.layers(baseLayers, overlays).addTo(map);\n\n")
 js_output.write("\nmap.addLayer(cluster);\n\n")
 
-
-# setBasemap funtion
+# create 'setBasemap' function which switches basemaps on trigger years
 js_output.write("function setBasemap(time) {\n")
 for index, map in enumerate(map_list):
   removed = removals[:]
@@ -353,7 +378,7 @@
   js_output.write("\t}\n")
 js_output.write("};\n\n")
 
-# setStarts function
+# create 'setStarts' function which triggers objects on their start year
 js_output.write("function setStarts(time) {\n")
 for year in start_dict:
   js_output.write("\tif (time >= {0}) {{\n".format(year))
@@ -363,7 +388,7 @@
   js_output.write("\t}\n")
 js_output.write("};\n\n")
 
-# setIsos function
+# create 'setIsos' function which triggers objects that last only one year and remove the following year
 js_output.write("function setIsos(time) {\n")
 for year in iso_dict:
   js_output.write("\tif (time === {0}) {{\n".format(year))
@@ -373,7 +398,7 @@
   js_output.write("\t}\n")
 js_output.write("};\n\n")
 
-# setRanges function
+# create 'setRanges' function which triggers objects on start year and removes on end year
 js_output.write("function setRanges(time) {\n")
 for year in range_dict:
   s = year.split("_")
@@ -384,7 +409,7 @@
   js_output.write("\t}\n")
 js_output.write("};\n\n")
 
-# setData function
+# create 'setData' function which triggers all other functions at once
 js_output.write("function setData(time) {\n")
 js_output.write("\tsetBasemap(time);\n")
 js_output.write("\tsetStarts(time);\n")

data/settings.py

@@ -1,7 +1,7 @@
 # App's location/URL
 app_path = "http://www.indiana.edu/~kdglobal/worldmap-dev/"
 
-# Link to Google Doc
+# Link to Google Doc (Make sure the correct gdoc_id is active so that the correct spreadsheet is pulled from)
 #gdoc_id = "1QoUlncYbfQi50y9TO20LvlPaox8JjHkBNaSujl-D_EE" #Main
 gdoc_id = "17EabushNWBxGeNpWNBAJp2E97eZt08k7Z5m-G7eqQmk" #Dev