stuff

README.txt

+Please run git fetch
+
+
 algorithms directory:
     algorithms.py contains all the functions for constructing district plans by utilizing
         the efficiency gap
+        __name__=="__main__" Function works if no specialization is needed
+        if specialization is needed 
+            RUN [1] completed_result(state, initial_percent_of_people=60, goal=5,
+            special_name='', better=False)
+
     drawing.py (must be run using Python2) creates a basemap of the United States and maps color-
         coded tracts (the color corresponding to their district) onto the basemap using Networkx     
+    Colors.csv contains numbers and colors for drawing.py
 
 
-reading_shapes directory:
+reading_shapes directory: 
     get_combined.py contains functions to convert shapefiles of census tracts, determine which tracts
         are connected to each other, and analyze demographic data to estimate the number of Republicans and Democrats in each district
+        RUN: [1] get_shapeRecs(shapefile_path), [2] create_state_tracts(shapeRecs)
     location_api.py uses the GPS coordinates of census tracts to determine which state they are in 
         and sorts them accordingly, using the LocationIQ API 
+        RUN: [1] get_shapeRecs(shapefile_path), [2] create_state_tracts(shapeRecs)
     state_set_json_files contains the partially completed tracts as dictionaries created by
         location_api.py    
     state_tracts_full_json_files contains the completed tract dictionaries created by get_combined.py
-
-    shp_test1.py
-    state_num.csv
+    state_num.csv contains the state and number of districts
     States.csv
     states.json
-    tract.py
-    util.py
-
+    tract.py - example of tract dict
+    util.py - contains helper functions for reading and writing CSVs, JSON, and pickle files
+    tracts1.json JSON file for helping location_api.py fun
     
     
 

reading_shapes/get_combined.py

@@ -8,6 +8,11 @@ shapefile_path = "Census_tract/Tract_2010Census_DP1.shp"
 def get_shapeRecs(shapefile_path):
     '''
     Convert shapefiles into Python objects
+
+    Inputs:
+        shapefile_path: a string
+
+    Returns: a shapefile object
     '''
     sf = shapefile.Reader(shapefile_path)
     shapeRecs = sf.shapeRecords()
@@ -16,6 +21,12 @@ def get_shapeRecs(shapefile_path):
 def get_states_connects(shapeRecs, state_set):
     '''
     Find all tract connections in a given state
+
+    Inputs:
+        shapeRecs: a shapefile object
+        state_tracts: a set
+
+    Returns: a dictionary
     '''
     sf_connects = set()
     dict_points = {}
@@ -39,6 +50,11 @@ def get_states_connects(shapeRecs, state_set):
 def get_connects_tracts(sf_connect):
     '''
     Determine if two tracts are connected
+
+    Inputs:
+        sf_connect: a dictionary
+
+    Returns: a dictionary
     '''
     count = 0
     dict_tracts = {}
@@ -55,6 +71,13 @@ def get_connects_tracts(sf_connect):
 def get_full_connects_state(shapeRecs, state_set):
     '''
     Find all tract connections within a given state
+
+    Inputs:
+        shapeRecs: a shapefile object
+        state_tracts: a set
+
+    Returns: a dictionary
+
     '''
     dict_connect = get_states_connects(shapeRecs, state_set)
     dict_tracts = get_connects_traits(dict_connect)
@@ -66,6 +89,11 @@ def age_DR(record):
     Use age information in a tract to weight the number of Republicans and Democrats
     NOTE: We determined how to weight the predictive power of demographics using CNN's
     2012 exit poll data, found here: http://www.cnn.com/election/2012/results/race/president/
+
+    Inputs:
+        record: a list
+
+    Return: a float
     '''
     total_population = record[6]
     weight_R = 0
@@ -109,6 +137,11 @@ def race_RD(record):
     Use race information in a tract to weight the number of Republicans and Democrats
     NOTE: We determined how to weight the predictive power of demographics using CNN's
     2012 exit poll data, found here: http://www.cnn.com/election/2012/results/race/president/
+
+    Inputs:
+        record: a list
+
+    Return: a float
     '''
     total_population = record[6]
     weight_R = 0
@@ -145,6 +178,11 @@ def gender_RD(record):
     Use age information in a tract to weight the number of Republicans and Democrats
     NOTE: We determined how to weight the predictive power of demographics using CNN's
     2012 exit poll data, found here: http://www.cnn.com/election/2012/results/race/president/
+
+    Inputs:
+        record: a list
+
+    Return: a float
     '''
     total_population = record[6]
 
@@ -182,6 +220,13 @@ def get_populations_RD(shapeRecs, connect_tracts, state_set):
     '''
     Apply weighting for age, race, and gender to estimate the number of Republicans and Democrats
     in a tract and return the tract information as a dictionary
+
+    Inputs:
+        shapeRecs: a shapefile object
+        connect_tracts: a dictionary
+        state_tracts: a set
+
+    Returns: a dictionary
     '''
     tracts_dict = {}
     num_tracts_in_state = len(state_set)
@@ -228,6 +273,11 @@ def create_state_tracts(shapeRecs):
     Recover the json files created in location_api.py that have sorted tracts by state
     Create json files containing all tracts represented as dictionaries with their necessary
     data and grouped by state, storing them in state_tracts_full_json_files
+
+    Inputs:
+        shapeRecs: a shapefile object
+
+    Returns: a dictionary
     '''
     state_tracts = {}
     state_dict_of_sets = recover_json("state_set_json_files/" + "Master_tract_sets.json")
@@ -245,6 +295,11 @@ def state_tracts_hard_coded(Master_tract_dicts):
     '''
     Hard code connections for islands in certain states to ensure that there
     are not unconnected tracts  
+
+    Inputs:
+        Master_tract_dicts: a dictionary
+
+    Returns: a dictionary
     '''
     hc_islands = { "California": {"06075980401": "06041132200",
                     "06037599100": "06037990300" }, 

reading_shapes/location_api.py

@@ -9,6 +9,11 @@ def tracts_state(API_KEY):
     '''
     Use the GPS coordinates of tracts to determine which state they are in
     To translate GPS coordinates into states, we used the LocationIQ API, found here: http://locationiq.org/
+
+    Inputs:
+        API_KEY: a string
+
+    Return: a list, a dictionray
     '''
     dict_tracts = recover_json("tracts1.json")
     dict_states = recover_json("statesrun_5.json")
@@ -49,6 +54,11 @@ def tracts_state(API_KEY):
 def check_balance(API_KEY):
     '''
     Check how many more times we could use the LocationIQ API in a day
+
+    Inputs:
+        API_KEY: a string
+
+    Return: a interger
     '''
     request_URL = "http://locationiq.org/v1/balance.php?key=" + API_KEY
     balance_request = requests.get(request_URL)
@@ -60,7 +70,12 @@ def check_balance(API_KEY):
 
 def hard_code(output=False):
     '''
-    Hard code island tracts that were not properly attributed to their respective states
+    Hard code tracts that were not properly attributed to their respective states
+
+    Inputs:
+        output: a boolean
+
+    Returns: a dictionary
     '''
     dict_states = recover_json("statesrun_6.json")
     hc_dict = {
@@ -87,6 +102,8 @@ def create_state_sets(output=False):
     Create a json file with dictionaries for each tract as a Master file
     Create additional json files sorted by state
     Store files in state_set_json_files
+
+    Inputs: a boolean
     '''
     dict_states_w_tracts = {}
     dict_states = recover_json("states_hc.json")

reading_shapes/test_files/s_11au16.prj

+GEOGCS["GCS_North_American_1983",DATUM["D_North_American_1983",SPHEROID["GRS_1980",6378137.0,298.257222101]],PRIMEM["Greenwich",0.0],UNIT["Degree",0.0174532925199433]]
\ No newline at end of file

reading_shapes/util.py

@@ -5,6 +5,10 @@ import pickle
 
 
 def create_json_file(dictionary, path_file_name):
+    '''
+    dictionary: a dictionary
+    path_file_name: a string
+    '''
     if type(dictionary) != str:
         tract_str = str(dictionary)
     if type(dictionary) == str:
@@ -13,6 +17,9 @@ def create_json_file(dictionary, path_file_name):
         json.dump(tract_str, json_file)
 
 def recover_json(json_file):
+    '''
+    json_file: a JSON file
+    '''
     with open(json_file) as json_tracts:
         str_tracts = json.load(json_tracts)
     dict_tracts = ast.literal_eval(str_tracts)
@@ -20,10 +27,17 @@ def recover_json(json_file):
 
 
 def create_pickle_file(dictionary, path_file_name):
+    '''
+    dictionary: a dictionary
+    path_file_name: a string
+    '''
     with open(path_file_name + ".pickle", "wb") as pickle_file:
         pickle.dump(dictionary, pickle_file)
 
 def recover_pickle(pickle_file):
+    '''
+    pickle_file: a pickle file
+    '''
     with open(pickle_file, "rb") as pf:
         pickle.load(pf)
     return dict_tracts
@@ -31,6 +45,9 @@ def recover_pickle(pickle_file):
 
 
 def recover_json_special(json_file):
+    '''
+    json_file: a JSON file
+    '''
     with open(json_file) as json_tracts:
         dict_tracts = json.load(json_tracts)
     return dict_tracts
@@ -38,6 +55,10 @@ def recover_json_special(json_file):
 
 
 def read_csv(path, file_name):
+    '''
+    path: a string
+    file_name: a string
+    '''
     with open(path + file_name) as csvfile:
         num_districts_states = {}
         reader = csv.DictReader(csvfile)
@@ -46,6 +67,10 @@ def read_csv(path, file_name):
         return num_districts_states
 
 def color_csv(path, file_name):
+    '''
+    path: a string
+    file_name: a string
+    '''
     with open(path + file_name) as csvfile:
         colors_dict = {}
         reader = csv.DictReader(csvfile)