Merge pull request #72 from edwardoughton/update_docs

Update docs

README.md

@@ -140,9 +140,9 @@ First run the following initial preprocessing script to extract the necessary fi
 
     python scripts/preprocess.py
 
-Then
+Then:
 
-    python scripts/core.py
+    python scripts/run.py
 
 
 Thanks for the support

scripts/run.py

@@ -50,6 +50,11 @@ def define_geotype(x):
     """
     Allocate geotype given a specific population density.
 
+    Parameters
+    ----------
+    x : pandas df
+        The column we wish to apply the geotype definition to.
+
     """
     if x['population_km2'] > 5000:
         return 'urban'
@@ -71,6 +76,17 @@ def define_geotype(x):
 
 def read_capacity_lookup(path):
     """
+    Load the capacity lookup table.
+
+    Parameters
+    ----------
+    path : string
+        Directory path to the capacity lookup table, generated by pysim5g.
+
+    Return
+    ------
+    capacity_lookup_table : dict
+        The loaded and processed capacity lookup table.
 
     """
     capacity_lookup_table = {}
@@ -109,57 +125,19 @@ def read_capacity_lookup(path):
     return capacity_lookup_table
 
 
-def lookup_cost(lookup, strategy, environment):
-    """
-    Find cost of network.
-
-    """
-    if (strategy, environment) not in lookup:
-        raise KeyError("Combination %s not found in lookup table",
-                       (strategy, environment))
-
-    density_capacities = lookup[
-        (strategy, environment)
-    ]
-
-    return density_capacities
-
-
-def find_country_list(continent_list):
-    """
-
-    """
-    path_processed = os.path.join(DATA_INTERMEDIATE,'global_countries.shp')
-    countries = geopandas.read_file(path_processed)
-
-    subset = countries.loc[countries['continent'].isin(continent_list)]
-
-    country_list = []
-    country_regional_levels = []
-
-    for name in subset.GID_0.unique():
-
-        country_list.append(name)
-
-        if name in ['ESH', 'LBY', 'LSO'] :
-            regional_level =  1
-        else:
-            regional_level = 2
-
-        country_regional_levels.append({
-            'country': name,
-            'regional_level': regional_level,
-        })
-
-    return country_list, country_regional_levels
-
-
 def load_cluster(path, iso3):
     """
     Load cluster number. You need to make sure the
     R clustering script (pytal/vis/clustering/clustering.r)
     has been run first.
 
+    Parameters
+    ----------
+    path : string
+        Directory path to the capacity lookup table, generated by pysim5g.
+    iso3 : string
+        The ISO 3-digital country code for the country being modeled.
+
     """
     with open(path, 'r') as source:
         reader = csv.DictReader(source)
@@ -172,6 +150,11 @@ def load_penetration(path):
     """
     Load penetration forecast.
 
+    Parameters
+    ----------
+    path : string
+        Directory path to the capacity lookup table, generated by pysim5g.
+
     """
     output = {}
 
@@ -183,12 +166,14 @@ def load_penetration(path):
     return output
 
 
-def load_smartphones(country, path):
+def load_smartphones(path):
     """
-    Load phone types forecast. The function either uses the specific data
-    for the country being modeled, or data from another country in the same
-    cluster. If no data are present for the country of the cluster, it
-    defaults to the mean values across all surveyed countries.
+    Load phone types forecast.
+
+    Parameters
+    ----------
+    path : string
+        Directory path to the smartphone forecast data.
 
     """
     output = {}
@@ -210,6 +195,12 @@ def load_smartphones(country, path):
 
 def load_core_lut(path):
     """
+    Loads the core network lookup table.
+
+    Parameters
+    ----------
+    path : string
+        Directory path to the core network lookup table.
 
     """
     interim = []
@@ -248,6 +239,16 @@ def allocate_deciles(data):
     """
     Convert to pandas df, define deciles, and then return as a list of dicts.
 
+    Parameters
+    ----------
+    data : list of dicts
+        The data for all regions being modeled.
+
+    Returns
+    -------
+    data : list of dicts
+        The data for all regions being modeled, with deciles allocated.
+
     """
     data = pd.DataFrame(data)
 
@@ -318,8 +319,7 @@ def allocate_deciles(data):
         'discount_rate': 5,
         'opex_percentage_of_capex': 10,
         'sectorization': 3,
-        'confidence': [50], #[5, 50, 95],
-        # 'networks': 3,
+        'confidence': [50],
         'local_node_spacing_km2': 40,
         'io_n2_n3': 1,
         'cots_processing_split_urban': 2,
@@ -356,9 +356,9 @@ def allocate_deciles(data):
 
     all_results = []
 
-    for decision_option in decision_options:#[:1]:
+    for decision_option in decision_options:
 
-        options = OPTIONS[decision_option]#[:1]
+        options = OPTIONS[decision_option]
 
         regional_annual_demand = []
         regional_results = []
@@ -380,7 +380,7 @@ def allocate_deciles(data):
 
             folder = os.path.join(DATA_INTERMEDIATE, iso3, 'smartphones')
             filename = 'smartphone_forecast.csv'
-            smartphone_lut = load_smartphones(country, os.path.join(folder, filename))
+            smartphone_lut = load_smartphones(os.path.join(folder, filename))
 
             folder = os.path.join(DATA_INTERMEDIATE, iso3)
             filename = 'core_lut.csv'
@@ -398,8 +398,6 @@ def allocate_deciles(data):
 
                 for ci in confidence_intervals:
 
-                    # print('CI: {}'.format(ci))
-
                     path = os.path.join(DATA_INTERMEDIATE, iso3, 'regional_data.csv')
                     data = load_regions(path)