Changes in the documentation

development/tests/reliability/reliability.py

@@ -7,8 +7,6 @@
 
 import matplotlib.pyplot as plt
 import statsmodels.api as sm
-from os.path import join
-from shutil import move
 import pandas as pd
 import numpy as np
 
@@ -148,7 +146,7 @@ def create_plots(effects, true):
         ax.yaxis.get_major_ticks()[0].set_visible(False)
         plt.title(title)
         plt.legend()
-        file_name = 'fig_{}_average_effect_estimation.png'.format(strategy)
+        file_name = 'fig-{}-average-effect-estimation.png'.format(strategy)
         plt.savefig(file_name)
 
 
@@ -158,6 +156,3 @@ def create_plots(effects, true):
     x = monte_carlo('reliability.grmpy.ini', 10)
     ATE = get_effect_grmpy('aer-simulation-mock.pkl')
     create_plots(x, ATE)
-    for type_ in ['grmpy', 'ols']:
-        filename = 'fig_{}_average_effect_estimation.png'.format(type_)
-        move(join(directory, filename), join(target, filename))

docs/economics.rst

@@ -1,7 +1,3 @@
-.. todo::
-
-    Please revisit the proper formatting of the headers that follow the structure in my manuscript. Also, please revamp the whole doc so that we are using Atx-style headers, see here https://daringfireball.net/projects/markdown/syntax#header
-
 Economics
 =========
 
@@ -10,17 +6,7 @@ This section provides a general discussion of the generalized Roy model and sele
 Generalized Roy Model
 ---------------------
 
-.. todo::
-
-    Multiple citations are sometimes separated by comma sometimes by semicolon. Please determine the proper way and impose it throughout.
-
-Economics
-
-The generalized Roy model (:cite:`Roy1951`, :cite:`HecVyr05`) provides a coherent framework to explore the econometrics of policy evaluation. Its is characterized by the following set of equations.
-
-.. todo::
-
-    Please ensure a proper left alignment of the labels for the equation groups. Also please put them in boldface.
+The generalized Roy model (:cite:`Roy1951`, :cite:`HecVyr05`) provides a coherent framework to  explore the econometrics of policy evaluation. Its is characterized by the following set of equations.
 
 .. math::
     :nowrap:
@@ -33,13 +19,13 @@ The generalized Roy model (:cite:`Roy1951`, :cite:`HecVyr05`) provides a coheren
     & \textbf{Choice} & &  \\
     & & C & = \mu_C(Z) - V \\
     & & D & = I[C  > 0 ] \\
-    & & S & = E[Y_1 - Y_0 - C \mid \mathcal{I}] \\
+    & & S & = E[Y_1 - Y_0 \mid \mathcal{I}] \\
     & & & \\
     & \textbf{Observed Outcome} & &  \\
     & & Y & = D Y_1 + (1 - D) Y_0
     \end{align*}
 
-:math:`(Y_1, Y_0)` are objective outcomes associated with each potential treatment state :math:`D` and realized after the treatment decision. :math:`Y_1` refers to the outcome in the treated state and :math:`Y_0` in the untreated state. :math:`C` denotes the propensity for treatment participation. Any subjective benefits, e.g. job amenities, are included (as a negative contribution) in the subjective cost of treatment. Agents take up treatment :math:`D` if they expect the objective benefit to outweigh the subjective cost. In that case, their subjective evaluation, i.e. the expected surplus from participation :math:`S`, is positive. I denotes the agent’s information set at the time of the participation decision. The observed outcome :math:`Y` is determined in a switching-regime fashion (:cite:`Quandt1958`, :cite:`Quandt1972`). If agents take up treatment, then the observed outcome :math:`Y` corresponds to the outcome in the presence of treatment :math:`Y_1`. Otherwise, :math:`Y_0` is observed. The unobserved potential outcome is referred to as the counterfactual outcome. If costs are identically zero for all agents, there are no observed regressors, and :math:`(U_1, U_0) \sim N (0, \Sigma)`, then the generalized Roy model corresponds to the original
+:math:`(Y_1, Y_0)` are objective outcomes associated with each potential treatment state :math:`D` and realized after the treatment decision. :math:`Y_1` refers to the outcome in the treated state and :math:`Y_0` in the untreated state. :math:`C` denotes the propensity for treatment participation. Any subjective benefits, e.g. job amenities, and costs, e.g. tuition costs, are included in the subjective propensity of treatment. Agents take up treatment :math:`D` if their propensity :math:`C` is positive. I denotes the agent’s information set at the time of the participation decision. The observed outcome :math:`Y` is determined in a switching-regime fashion (:cite:`Quandt1958`, :cite:`Quandt1972`). If agents take up treatment, then the observed outcome :math:`Y` corresponds to the outcome in the presence of treatment :math:`Y_1`. Otherwise, :math:`Y_0` is observed. The unobserved potential outcome is referred to as the counterfactual outcome. If costs are identically zero for all agents, there are no observed regressors, and :math:`(U_1, U_0) \sim N (0, \Sigma)`, then the generalized Roy model corresponds to the original
 Roy model (:cite:`Roy1951`).
 
 From the perspective of the econometrician, :math:`(X, Z)` are observable while :math:`(U_1, U_0, V)` are not. :math:`X` are the observed determinants of potential outcomes :math:`(Y_1, Y_0)`, and :math:`Z` are the observed determinants of the cost of treatment :math:`C`. Potential outcomes and cost are decomposed into their means :math:`(\mu_1(X), \mu_0(X), \mu_C(Z))` and their deviations from the mean :math:`(U_1, U_0, V)`. :math:`(X, Z)` might have common elements. Observables and unobservables jointly determine program participation :math:`D`.
@@ -82,15 +68,11 @@ Objects of Interest
 
 Treatment effect heterogeneity requires to be precise about the effect being discussed. There is no single effect of neither a policy nor a treatment. For each specific policy question, the object of interest must be carefully defined (:cite:`HecVyr05`, :cite:`HecVyr07a`, :cite:`HecVyr07b`). We present several potential objects of interest and discuss what question they are suited to answer. We start with the average effect parameters. However, these neglect possible effect heterogeneity. Therefore, we explore their distributional counterparts as well.
 
-.. todo::
-
-    I want ALL objects of interest  written like this  :math:`B^{ATE}` for ATE. This requires to iterate through the whole document.
-
 Conventional Average Treatment Effects
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-It is common to summarize the average benefits of treatment for different subsets of the population. In general, the focus is on the average effect in the whole population, the average treatment effect (:math:`B^{ATE}`), or the average effect on the
-treated (:math:`B^{TT}`) or untreated (:math:`B^{TUT}`).
+It is common to summarize the average benefits of treatment for different subsets of the population. In general, the focus is on the average effect in the whole population, the average treatment effect :math:`\left(B^{ATE}\right)`, or the average effect on the
+treated :math:`\left(B^{TT}\right)` or untreated :math:`\left(B^{TUT}\right)`.
 
   .. math::
       &B^{ATE} & = E [Y_1 - Y_0]\\
@@ -111,7 +93,7 @@ compulsory participation, then the TUT is the policy relevant parameter.
 
 
 To ensure a tight link between the posed policy question and the parameter of interest, Heckman
-and Vytlacil (:cite:`HecVyr01`) propose the policy-relevant treatment effect (:math:`B^{PRTE}`). They consider policies that do not change potential outcomes, but only affect individual choices. Thus, they account for voluntary program participation.
+and Vytlacil (:cite:`HecVyr01`) propose the policy-relevant treatment effect :math:`\left(B^{PRTE}\right)`. They consider policies that do not change potential outcomes, but only affect individual choices. Thus, they account for voluntary program participation.
 
 Policy-Relevant Average Treatment Effect
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -123,7 +105,7 @@ respectively. Then, observed outcomes are determined as
     Y_B & = D_BY_1 + (1 - D_B)Y_0\\
     Y_A & = D_AY_1 + (1 - D_A)Y_0.
 
-A policy change induces some agents to change their treatment status (DB != DA), while others are unaffected. More formally, the :math:`B^{PRTE}` is then defined as
+A policy change induces some agents to change their treatment status :math:`\left(D_B \neq D_A\right)`:, while others are unaffected. More formally, the :math:`B^{PRTE}` is then defined as
 
 .. math::
       B^{PRTE}  = E[D_A] - E[D_B](E[Y_A] - E[Y_B]).
@@ -134,7 +116,7 @@ the previously (un-)treated.
 Local Average Treatment Effect
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The Local Average Treatment Effect (:math:`B^{LATE}`) was introduced by Imbens and Angrist (:cite:`Imbens94`). They show that instrumental variable estimator identify :math:`B^{LATE}`, which measures the mean gross return to treatment for individuals induced into treatment by a change in an instrument.
+The Local Average Treatment Effect :math:`\left(B^{LATE}\right)` was introduced by Imbens and Angrist (:cite:`Imbens94`). They show that instrumental variable estimator identify :math:`B^{LATE}`, which measures the mean gross return to treatment for individuals induced into treatment by a change in an instrument.
 
 .. figure:: ../docs/figures/fig-local-average-treatment.png
    :align: center
@@ -143,12 +125,12 @@ The Local Average Treatment Effect (:math:`B^{LATE}`) was introduced by Imbens a
 
 Unfortunately, the people induced to go into state 1 :math:`(D=1)` by a change in any particular instrument need not to be the same as the people induced to to go to state 1 by policy changes other than those corresponding exactly to the variation in the instrument. A desired policy effect may bot be directly correspond to the variation in the IV. Moreover, if there is a vector of instruments that generates choice and the components of the vector are intercorrelated, IV estimates using the components of :math:`Z` as the instruments, one at a time, do not, in general, identify the policy effect corresponding to varying that instruments, keeping all other instruments fixed, the ceteris paribus effect of the change in the instrument. Heckman develops this argument in detail (:cite:`Heckman10`).
 
-The average effect of a policy and the average effect of a treatment are linked by the marginal treatment effect (:math:`B^{MTE}`). The :math:`B^{MTE}` was introduced into the literature by Björklund and Moffitt (:cite:`BjöMof87`) and extended by Heckman and Vytlacil (:cite:`HecVyr01`, :cite:`HecVyr05`, :cite:`HecVyr07b`).
+The average effect of a policy and the average effect of a treatment are linked by the marginal treatment effect :math:`\left(B^{MTE}\right)`. The :math:`B^{MTE}` was introduced into the literature by Björklund and Moffitt (:cite:`BjöMof87`) and extended by Heckman and Vytlacil (:cite:`HecVyr01`, :cite:`HecVyr05`, :cite:`HecVyr07b`).
 
 Marginal Treatment Effect
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The MTE is the treatment effect parameter that conditions on the unobserved desire to select into treatment. Let :math:`V = E[U_C - (U_1 - U_0) | I ]` summarize the expectations about all unobservables determining treatment choice and let :math:`U_S = F_V (V)`. Then, the :math:`B^{MTE}` is defined as
+The :math:`B^{MTE}` is the treatment effect parameter that conditions on the unobserved desire to select into treatment. Let :math:`V` be the heterogeneity/error effect that impacts the propensity for treatment and let :math:`U_S = F_V (V)`. Then, the :math:`B^{MTE}` is defined as
 
 .. math::
       B^{MTE}(x, u_S)  = E [ Y_1 - Y_0 | X = x, U_S = u_S] .
@@ -162,11 +144,6 @@ Parameter :math:`j, \Delta j (x)`, can be written as
     \Delta j (x) = \int_{0}^{1} MTE(x, u_S) \omega^{j}(x, u_S) du_S,
 
 
-.. todo::
-
-    The notation for the weights does not match the figures.
-
-
 where the weights :math:`\omega^{j} (x, u_S)` are specific to parameter j, integrate to one, and can be constructed from data.
 
 .. figure:: ../docs/figures/fig-weights-marginal-effect.png
@@ -179,7 +156,7 @@ All parameters are identical only in the absence of essential heterogeneity. The
 .. figure:: ../docs/figures/fig-eh-marginal-effect.png
    :align: center
 
-   MTE in the presence and absence of essential heterogeneity.
+   :math:`B^{MTE}` in the presence and absence of essential heterogeneity.
 
 
 
@@ -190,10 +167,22 @@ Distribution of Potential Outcomes
 -----------------------------------
 
 Several interesting aspects of policies cannot be evaluated without knowing the joint distribution of potential outcomes (see :cite:`AbbHec07` and :cite:`HeSmCl97`). The joint distribution of :math:`(Y_1, Y_0)` allows to calculate the whole distribution of benefits. Based on it, the average treatment and policy effects can be
-constructed just as the median and all other quantiles. In addition, the portion of people that benefit from treatment can be calculated for the overall population :math:`Pr(Y_1 - Y_0 > 0)` or among any subgroup of particular interest to policy makers :math:`Pr(Y_1 - Y_0 > 0 | X)`. This is important as a treatment which is beneficial for agents on average can still be harmful for some. The absence of an average effect might be the result of part of the population having a positive effect, which is just offset by a negative effect on the rest of the population. This kind of treatment effect heterogeneity is informative as it provides the starting point for an adaptive research strategy that tries to understand the driving force behind these differences (:cite:`HSMV96`, :cite:`HSMV97`).
+constructed just as the median and all other quantiles. In addition, the portion of people that benefit from treatment can be calculated for the overall population :math:`Pr(Y_1 - Y_0 > 0)` or among any subgroup of particular interest to policy makers :math:`Pr(Y_1 - Y_0 > 0 | X)`. This is important as a treatment which is beneficial for agents on average can still be harmful for some. For a comprehensive overview on related work see :cite:`AbbHec07` and the work they cite. The survey by :cite:`Fortin2011` provides an overview about the alternative approaches to the construction of conterfactual observed outcome distributions. See :cite:`Firpo2007`, :cite:`AbAnIm2002` and :cite:`Chernozhukov2005` for their studies of quantile treatment effects.
 
-.. todo::
+The absence of an average effect might be the result of part of the population having a positive effect, which is just offset by a negative effect on the rest of the population. This kind of treatment effect heterogeneity is informative as it provides the starting point for an adaptive research strategy that tries to understand the driving force behind these differences (:cite:`HSMV96`, :cite:`HSMV97`).
+
+.. figure:: ../docs/figures/fig-distribution-joint-potential.png
+   :align: center
 
-    * Integrate a version of this figure https://github.com/HumanCapitalEconomics/economics/blob/master/distribution/04_static_model.pdf slide 44-45 in the documentation , this includes its reference in the text with a brief description.
+   Distribution of potential Outcomes
+
+
+.. figure:: ../docs/figures/fig-distribution-joint-surplus.png
+  :align: center
+
+  Distribution of benefits and surplus
+
+
+.. todo::
 
     * add fotnote 5 from my manuscript into text

docs/figures/create.py

@@ -21,4 +21,3 @@ def create_figures():
 if __name__ == '__main__':
 
     create_figures()
-

docs/figures/scripts/__init__.py

@@ -0,0 +1,20 @@
+"""The module allows to run tests from inside the interpreter."""
+import os
+
+import pytest
+
+from grmpy.simulate.simulate import simulate
+from grmpy.estimate.estimate import estimate
+
+
+def test():
+    """The function allows to run the tests from inside the interpreter."""
+
+    package_directory = os.path.dirname(os.path.realpath(__file__))
+    current_directory = os.getcwd()
+
+    os.chdir(package_directory)
+
+    pytest.main()
+
+    os.chdir(current_directory)

docs/figures/scripts/fig-distribution-joint.py

@@ -20,7 +20,7 @@
 
 ax = plt.figure().add_subplot(111)
 
-levels = np.linspace(0.1, 1.0, 10,  endpoint=True)
+levels = np.linspace(0.1, 1.0, 10, endpoint=True)
 cns = plt.contourf(X, Y, rv.pdf(pos) / np.max(rv.pdf(pos)), levels=levels)
 
 ax.set_ylabel('$Y_1$')
@@ -37,7 +37,7 @@
 
 ax.text(3.3, 3.3, r'$45^o$')
 
-plt.savefig(OUTPUT_DIR + 'fig-distribution-joint-potential.png')
+plt.savefig(OUTPUT_DIR + '/fig-distribution-joint-potential.png')
 
 # This plot shows the joint distribution of surplus and benefits.
 x = np.linspace(y_min, y_max, 100)
@@ -53,7 +53,7 @@
 
 ax = plt.figure().add_subplot(111)
 
-levels = np.linspace(0.1, 1.0, 10,  endpoint=True)
+levels = np.linspace(0.1, 1.0, 10, endpoint=True)
 cns = plt.contourf(X, Y, rv.pdf(pos) / np.max(rv.pdf(pos)), levels=levels)
 
 ax.set_ylabel('$B$')
@@ -81,4 +81,4 @@
 
 ax.text(x=-3.5, y=-3.5, s='IV')
 
-plt.savefig(OUTPUT_DIR + 'fig-distribution-joint-surplus.png')
+plt.savefig(OUTPUT_DIR + '/fig-distribution-joint-surplus.png')

docs/figures/scripts/fig-eh-marginal-effect.py

@@ -0,0 +1,56 @@
+"""The script creates a figure to illustrate the appearance of the marginal treatment effect in the
+abscence and presence of individual heterogeneity.
+"""
+import matplotlib.pyplot as plt
+import numpy as np
+
+from grmpy.simulate.simulate_auxiliary import construct_covariance_matrix
+from grmpy.simulate.simulate_auxiliary import mte_information
+from grmpy.simulate.simulate import simulate
+from grmpy.test.auxiliary import cleanup
+from fig_config import RESOURCE_DIR
+from fig_config import OUTPUT_DIR
+from grmpy.read.read import read
+
+filename = "/tutorial.grmpy.ini"
+
+GRID = np.linspace(0.01, 0.99, num=99, endpoint=True)
+init_dict = read(RESOURCE_DIR + filename)
+
+
+def plot_marginal_treatment_effect(pres, abs_):
+    ax = plt.figure().add_subplot(111)
+
+    ax.set_ylabel(r"$B^{MTE}$")
+    ax.set_xlabel("$u_S$")
+    ax.plot(GRID, pres, label='Presence')
+    ax.plot(GRID, abs_, label='Absence', linestyle='--')
+
+    ax.set_ylim([1.5, 4.5])
+
+    plt.legend()
+
+    plt.tight_layout()
+    plt.savefig(OUTPUT_DIR + '/fig-eh-marginal-effect.png')
+
+
+if __name__ == '__main__':
+    coeffs_untreated = init_dict['UNTREATED']['all']
+    coeffs_treated = init_dict['TREATED']['all']
+    cov = construct_covariance_matrix(init_dict)
+    df = simulate(RESOURCE_DIR + filename)
+    x = df[[init_dict['varnames'][i - 1] for i in init_dict['TREATED']['order']]]
+    MTE_pres = mte_information(coeffs_treated, coeffs_untreated, cov, GRID, x, init_dict)
+
+    para_diff = coeffs_treated - coeffs_untreated
+
+    MTE_abs = []
+    for i in GRID:
+        if cov[2, 2] == 0.00:
+            MTE_abs += ['---']
+        else:
+            MTE_abs += [
+                np.mean(np.dot(para_diff, x.T))]
+
+    plot_marginal_treatment_effect(MTE_pres, MTE_abs)
+    cleanup()