update doc strings

open_IO/calibrate.py

@@ -74,6 +74,8 @@ class parameters(object):
     This function sets the values of parameters used in the model.
 
     Args:
+        d (data class): Class of data for use in CGE model
+        ind (list): List of industry names
 
     Returns:
         parameters (parameters class): Class of parameters for use in CGE model.

open_IO/equations.py

@@ -5,7 +5,7 @@
 
 def eqpy(pf, beta):
     '''
-    Price of value added
+    Equation determining the price of value added
 
     .. math::
         py_{j} = \sum_{h}F_{h,j}{\\beta_{h,j}}
@@ -23,10 +23,9 @@ def eqpy(pf, beta):
     return py
 
 
-
 def eqX(ax, Z):
     '''
-    Demand for intermediate inputs.
+    Equation representing the demand for intermediate inputs.
 
     .. math::
         X_{i,j} = ax_{i,j}Z_{j}
@@ -46,7 +45,7 @@ def eqX(ax, Z):
 
 def eqY(ay, Z):
     '''
-    Value added.
+    Equation representing the production of value added.
 
     .. math::
         Y_{j} = ay_{j}Z_{j}
@@ -65,7 +64,7 @@ def eqY(ay, Z):
 
 def eqpz(ay, ax, py, pq):
     '''
-    Domestic Production/Output prices.
+    Equation representing domestic Production/Output prices.
 
     .. math::
         pz_{j} = ay_{j}py_{j} + \sum_{i}ax_{i,j}pq_{i}
@@ -87,7 +86,7 @@ def eqpz(ay, ax, py, pq):
 
 def eqTd(taud, pf, Ff):
     '''
-    Direct tax revenue.
+    Equation defining total direct tax revenue.
 
     .. math::
         Td = \tau d \sum_{h}pf_{h}FF_{h}
@@ -106,7 +105,7 @@ def eqTd(taud, pf, Ff):
 
 def eqTrf(tautr, pf, Ff):
     '''
-    Total transfers to households.
+    Equation defining total transfers to households.
 
     .. math::
         Trf = \tau^{tr} \sum_{h}pf_{h}FF_{h}
@@ -125,7 +124,7 @@ def eqTrf(tautr, pf, Ff):
 
 def eqTz(tauz, pz, Z):
     '''
-    Production tax revenue from each commodity.
+    Equation representing production tax revenue from each commodity.
 
     .. math::
         Tz_{j} = \tau^{z}_{j} pz_{j}Z_{j}
@@ -144,7 +143,7 @@ def eqTz(tauz, pz, Z):
 
 def eqTm(taum, pm, M):
     '''
-    Tariff revenue from each commodity.
+    Equation representing tariff revenue from each commodity.
 
     .. math::
         Tm_{j} = \tau^{m}_{j} pm_{j}M_{j}
@@ -163,7 +162,7 @@ def eqTm(taum, pm, M):
 
 def eqXg(mu, XXg):
     '''
-    Government expenditures on commodity j
+    Equation representing government expenditures on commodity j
 
     .. math::
         X^{g}_{j} = \mu_{j}XX_{g}
@@ -182,7 +181,7 @@ def eqXg(mu, XXg):
 
 def eqXv(lam, XXv):
     '''
-    Investment demand for each good j
+    Equation representing investment demand for each good j
 
     .. math::
         Xv_{j} = \lambda_{j}XXv
@@ -200,7 +199,7 @@ def eqXv(lam, XXv):
 
 def eqXXv(g, Kk):
     '''
-    Total investment.
+    Equation representing total investment.
 
     .. math::
         XXv = g \cdot KK
@@ -218,7 +217,7 @@ def eqXXv(g, Kk):
 
 def eqSp(ssp, pf, Ff, Fsh, Trf):
     '''
-    Total household savings.
+    Equation representing total household savings.
 
     .. math::
         Sp = ssp \cdot \left(\sum_{h}pf_{h}FF_{h} \\right)
@@ -239,7 +238,7 @@ def eqSp(ssp, pf, Ff, Fsh, Trf):
 
 def eqSg(mu, Td, Tz, Tm, XXg, Trf, pq):
     '''
-    Total government savings.
+    Equation representing total government savings.
 
     .. math::
         Sg = Td + \sum_{j}Tz_{j} + \sum_{j}Tm_{j} - (Trf + \sum_{j}Xg_{j})
@@ -263,7 +262,7 @@ def eqSg(mu, Td, Tz, Tm, XXg, Trf, pq):
 
 def eqFsh(R, Kf, er):
     '''
-    Domestic profits that are repatriated to foreign owners of capital.
+    Equation representing domestic profits that are repatriated to foreign owners of capital.
 
     .. math::
         FSH = R \cdot KF \cdot \\varepsilon
@@ -282,7 +281,7 @@ def eqFsh(R, Kf, er):
 
 def eqKd(g, Sp, lam, pq):
     '''
-    Domestic capital holdings.
+    Equation representing domestic capital holdings.
 
     .. math::
         K^{d} = \\frac{S^{p}}{g\sum_{j}\lambda_{j}pq_{j}}
@@ -302,7 +301,7 @@ def eqKd(g, Sp, lam, pq):
 
 def eqKf(Kk, Kd):
     '''
-    Foreign holdings of domestically used capital.
+    Equation representing foreign holdings of domestically used capital.
 
     .. math::
         K^{f} = KK - K^{d}
@@ -320,7 +319,7 @@ def eqKf(Kk, Kd):
 
 def eqKk(pf, Ff, R, lam, pq):
     '''
-    Capital market clearing equation.
+    Equation describing the capital market clearing equation.
 
     .. math::
         KK = \\frac{pf * FF}{R \sum_{j}\lambda_{j}pq_{j}}
@@ -342,7 +341,7 @@ def eqKk(pf, Ff, R, lam, pq):
 
 def eqXp(alpha, pf, Ff, Sp, Td, Fsh, Trf, pq):
     '''
-    Demand for production good i by consumers.
+    Equation for demand for production good i by consumers.
 
     .. math::
         X^{p}_{i}= \\frac{}\\alpha_{i}}{pq_{i}}\left(\sum_{h}pf_{h}Ff_{h} - S^{p} - T^{d}- FSH - TRF\\right)
@@ -366,7 +365,7 @@ def eqXp(alpha, pf, Ff, Sp, Td, Fsh, Trf, pq):
 
 def eqpe(er, pWe):
     '''
-    Export prices.
+    Equation defining export prices.
 
     .. math::
         pe_{i} = \\varepsilon \cdot pWe_{i}
@@ -384,7 +383,7 @@ def eqpe(er, pWe):
 
 def eqpm(er, pWm):
     '''
-    Import prices.
+    Equation defining import prices.
 
     .. math::
         pm_{i} = \\varepsilon \cdot pWm_{i}
@@ -626,6 +625,22 @@ def eqpq(deltam, taum, tauz, pm, pz, pq):
 
 
 def eqpqbar(deltam, taum, tauz, pm, pz):
+    '''
+    Equation describing the price of the Armington good.
+
+    .. math::
+        pq_{j} = deltam_{j}pm_{j}(1+\\tau^{m}_{i}) + (1-deltam_{j})pz_{j}(1+\\tau^{z}_{i})
+
+    Args:
+        deltam (1D numpy array): import propensity for good j
+        tauz (1D numpy array): Ad valorem tax rate on commodity i
+        taum (1D numpy array): Tariff rate on commodity i
+        pm (1D numpy array): The price of commodity i imports in domestic currency.
+        pz (1D numpy array): price of output good i
+
+    Returns:
+        pq (1D numpy array): price of the Armington good (domestic + imports) for each good i
+    '''
     pq = deltam * pm * (1 + taum) + (1 - deltam) * pz * (1 + tauz)
     return pq
 

open_IO/simpleIO.py

@@ -14,7 +14,7 @@
 sam_path = os.path.join(current_path, 'SAM.xlsx')
 sam = pd.read_excel(sam_path)
 
-# declare sets
+# declare sets of variables
 u = ('AGR', 'OIL', 'IND', 'SER', 'LAB', 'CAP', 'LAND', 'NTR',
      'DTX', 'IDT', 'ACT', 'HOH', 'GOV', 'INV', 'EXT')
 ind = ('AGR', 'OIL', 'IND', 'SER')
@@ -35,15 +35,15 @@ def io_system(pvec, args):
         p_error (Numpy array): Errors from IO equations
     '''
     (p, d, ind, h, er, pf) = args
-	
+
     pq = pvec[0:len(ind)]
     pq = Series(pq, index=list(ind))
     pm = eq.eqpm(er, d.pWm)
     py = eq.eqpy(pf, p.beta)
     pz = eq.eqpz(p.ay, p.ax, py, pq)
     pq_error = eq.eqpq(p.deltam, p.taum, p.tauz, pm, pz, pq)
     pq_error = pq_error.values
-	
+
     return pq_error
 
 
@@ -88,18 +88,18 @@ def io_system(pvec, args):
     pprime = results.x
     pqprime = pprime[0:len(ind)]
     pqprime = Series(pqprime, index=list(ind))
-	
+
     pvec = pprime
     pq_error = io_system(pvec, io_args)
 
     dist = (((pq_error) ** 2 ) ** (1 / 2)).sum()
     print('Distance at iteration ', tpi_iter, ' is ', dist)
 
 
-pm = eq.eqpm(er, d.pWm)	
+pm = eq.eqpm(er, d.pWm)
 py = eq.eqpy(pf, p.beta)
 pz = eq.eqpz(p.ay, p.ax, py, pqprime)
 pqbar = eq.eqpqbar(p.deltam, p.taum, p.tauz, pm, pz)
-   
+
 print('Model solved, pq = ', pqbar)
 

open_cge/aggregates.py

@@ -176,7 +176,6 @@ def eqpk(F, Kk, Kk0, Ff0):
 
     ..math:: \sum_{i}F_{h,i} - \\frac{Kk}{\\Kk0} \cdot Ff0
 
-
     Args:
         F (2D numpy array): The use of factor h in the production of
             good i

open_cge/calibrate.py

@@ -10,12 +10,14 @@ class model_data(object):
 
     Args:
         sam (DataFrame): DataFrame containing social and economic data
+        h (list): List of factors of production
+        ind (list): List of industries
 
     Returns:
         model_data (data class): Data used in the CGE model
     '''
 
-    def __init__(self, sam, h, u, ind):
+    def __init__(self, sam, h, ind):
         # foreign saving
         self.Sf0 = DataFrame(sam, index=['INV'], columns=['EXT'])
         # private saving
@@ -109,6 +111,8 @@ class parameters(object):
     This function sets the values of parameters used in the model.
 
     Args:
+        d (data class): Class of data for use in CGE model
+        ind (list): List of industries
 
     Returns:
         parameters (parameters class): Class of parameters for use in

open_cge/execute.py

@@ -6,16 +6,15 @@
 from open_cge import government as gov
 from open_cge import household as hh
 from open_cge import aggregates as agg
-from open_cge import firms
-from open_cge import calibrate
+from open_cge import firms, calibrate
 from open_cge import simpleCGE as cge
 
 # load social accounting matrix
 current_path = os.path.abspath(os.path.dirname(__file__))
 sam_path = os.path.join(current_path, 'SAM.xlsx')
 sam = pd.read_excel(sam_path, index_col=0, header=0)
 
-# declare sets
+# declare sets of variables
 u = ('AGR', 'OIL', 'IND', 'SER', 'LAB', 'CAP', 'LAND', 'NTR',
      'DTX', 'IDT', 'ACT', 'HOH', 'GOV', 'INV', 'EXT')
 ind = ('AGR', 'OIL', 'IND', 'SER')
@@ -33,9 +32,10 @@ def check_square():
     if not sam_small.shape[0] == sam_small.shape[1]:
         raise ValueError(f"SAM is not square. It has {sam_small.shape[0]} rows and {sam_small.shape[0]} columns")
 
+
 def row_total():
     '''
-    this function tests whether the row sums
+    This function tests whether the row sums
     of the SAM equal the expected value.
     '''
     sam_small = sam.iloc[:, :-3]
@@ -44,9 +44,10 @@ def row_total():
     row_sum = pd.Series(row_sum)
     return row_sum
 
+
 def col_total():
     '''
-    this function tests whether column sums
+    This function tests whether column sums
     of the SAM equal the expected values.
     '''
     sam_small = sam.iloc[:, :-3]
@@ -55,9 +56,10 @@ def col_total():
     col_sum = pd.Series(col_sum)
     return col_sum
 
+
 def row_col_equal():
     '''
-    this function tests whether row sums
+    This function tests whether row sums
     and column sums of the SAM are equal.
     '''
     sam_small = sam.iloc[:, :-3]
@@ -66,9 +68,10 @@ def row_col_equal():
     col_sum = sam_small.sum(axis=1)
     np.testing.assert_allclose(row_sum, col_sum)
 
+
 def runner():
     '''
-    this function runs the cge model
+    This function solves the CGE model
     '''
 
     # solve cge_system