Update README.md (#77)

* Update README.md

Reflect code changes, update references and publication sections.

* Updated docs

* Fixed reference.

* Updated bootstrap example

Author: Miruna Oprescu

README.md

@@ -23,19 +23,19 @@ consult the documentation at https://econml.azurewebsites.net/.
 <details>
 <summary><strong><em>Table of Contents</em></strong></summary>
 
-- [Introduction](#introduction)
-  - [About Treatment Effect Estimation](#about-treatment-effect-estimation)
-  - [Example Applications](#example-applications)
-- [News](#news)
-- [Getting Started](#getting-started)
-  - [Installation](#installation)
-  - [Usage Examples](#usage-examples)
-- [For Developers](#for-developers)
-  - [Running the tests](#running-the-tests)
-  - [Generating the documentation](#generating-the-documentation)
-- [Blogs and Publications](#blogs-and-publications)
-- [Contributing and Feedback](#contributing-and-feedback)
-- [References](#references)
+- [Introduction](#Introduction)
+  - [About Treatment Effect Estimation](#About-Treatment-Effect-Estimation)
+  - [Example Applications](#Example-Applications)
+- [News](#News)
+- [Getting Started](#Getting-Started)
+  - [Installation](#Installation)
+  - [Usage Examples](#Usage-Examples)
+- [For Developers](#For-Developers)
+  - [Running the tests](#Running-the-tests)
+  - [Generating the documentation](#Generating-the-documentation)
+- [Blogs and Publications](#Blogs-and-Publications)
+- [Contributing and Feedback](#Contributing-and-Feedback)
+- [References](#References)
 
 </details>
 
@@ -113,9 +113,9 @@ To install from source, see [For Developers](#for-developers) section below.
   from econml.dml import DMLCateEstimator
   from sklearn.linear_model import LassoCV
 
-  est = DMLCateEstimator(model_y=LassoCV(), model_t=LassoCV)
+  est = DMLCateEstimator(model_y=LassoCV(), model_t=LassoCV())
   est.fit(Y, T, X, W) # W -> high-dimensional confounders, X -> features
-  treatment_effects = est.const_marginal_effect(X_test)
+  treatment_effects = est.effect(X_test)
   ```
 
 * [Orthogonal Random Forests](#references)
@@ -130,7 +130,7 @@ To install from source, see [For Developers](#for-developers) section below.
                                        model_T=LassoCV(cv=3), model_Y=LassoCV(cv=3)
                                        )
   est.fit(Y, T, X, W)
-  treatment_effects = est.const_marginal_effect(X_test)
+  treatment_effects = est.effect(X_test)
     ```
 
 * [Deep Instrumental Variables](#references)
@@ -164,12 +164,11 @@ To install from source, see [For Developers](#for-developers) section below.
 
 * Bootstrap Confidence Intervals
   ```Python
-  from econml.bootstrap import BootstrapEstimator
-
-  # Bootstrap estimator wrapper
-  boot_est = BootstrapEstimator(est, n_bootstrap_samples=10)
-  boot_est.fit(Y, T, X, W)
-  treatment_effect_interval = boot_est.const_marginal_effect_interval(X_test, lower=1, upper=99)
+  from econml.dml import DMLCateEstimator
+  
+  est = DMLCateEstimator(model_y=LassoCV(), model_t=LassoCV(), inference='bootstrap')
+  est.fit(Y, T, X, W)
+  treatment_effect_interval = est.effect_interval(X_test, lower=1, upper=99)
   ```
 
 To see more complex examples, go to the [notebooks](https://github.com/Microsoft/EconML/tree/master/notebooks) section of the repository. For a more detailed description of the treatment effect estimation algorithms, see the EconML [documentation](https://econml.azurewebsites.net/).
@@ -196,9 +195,11 @@ The reStructuredText files that make up the documentation are stored in the [doc
 
 # Blogs and Publications
 
+* June 2019: [Treatment Effects with Instruments paper](https://arxiv.org/pdf/1905.10176.pdf)
+
 * May 2019: [Open Data Science Conference Workshop](https://staging5.odsc.com/training/portfolio/machine-learning-estimation-of-heterogeneous-treatment-effect-the-microsoft-econml-library) 
 
-* 2018: [Orthogonal Random Forests paper](https://arxiv.org/abs/1806.03467)
+* 2018: [Orthogonal Random Forests paper](http://proceedings.mlr.press/v97/oprescu19a.html)
 
 * 2017: [DeepIV paper](http://proceedings.mlr.press/v70/hartford17a/hartford17a.pdf)
 
@@ -218,9 +219,13 @@ contact [[email protected]](mailto:[email protected]) with any additio
 
 # References
 
+V. Syrgkanis, V. Lei, M. Oprescu, M. Hei, K. Battocchi, G. Lewis.
+**Machine Learning Estimation of Heterogeneous Treatment Effects with Instruments**
+[*ArXiv preprint arXiv:1905.10176*](https://arxiv.org/abs/1905.10176)
+
 M. Oprescu, V. Syrgkanis and Z. S. Wu.
 **Orthogonal Random Forest for Causal Inference.**
-[*ArXiv preprint arXiv:1806.03467*](http://arxiv.org/abs/1806.03467), 2018.
+[*Proceedings of the 36th International Conference on Machine Learning*](http://proceedings.mlr.press/v97/oprescu19a.html), 2019.
 
 Jason Hartford, Greg Lewis, Kevin Leyton-Brown, and Matt Taddy. **Deep IV: A flexible approach for counterfactual prediction.** [*Proceedings of the 34th International Conference on Machine Learning*](http://proceedings.mlr.press/v70/hartford17a/hartford17a.pdf), 2017.
 

doc/spec/estimation/dml.rst

@@ -311,7 +311,7 @@ matrix of cross price elasticities as:
     est.fit(Y, T, None, W)
 
     # a_hat[i,j] contains the elasticity of the demand of product i on the price of product j
-    a_hat = est.const_marginal_effect()
+    a_hat = est.effect()
 
 If we have too many products then the cross-price elasticity matrix contains many parameters and we need
 to regularize. Given that we want to estimate a matrix, it makes sense in this application to consider
@@ -335,7 +335,7 @@ lightning package implements such a class:
                         model_final=FistaRegressor(penalty='trace', C=0.0001),
                         featurizer=PolynomialFeatures(degree=1, include_bias=False))
     est.fit(Y, T, X, W)
-    te_pred = est.const_marginal_effect(np.array([[np.median(X)]]))
+    te_pred = est.effect(np.array([[np.median(X)]]))
     print(te_pred)
     print(np.linalg.svd(te_pred[0]))
 
@@ -350,9 +350,9 @@ Similarly we can get heterogeneous cross-price elasticities with respect to some
     est.fit(Y, T, X, W)
 
     # est.coef(1) contains the cross-price elasticities when X=1, i.e. during christmas. 
-    a_christmas = est.const_marginal_effect([[1]])
+    a_christmas = est.effect([[1]])
     # Similarly est.coef(0) contains the cross price elasticities when it is not christmas.
-    a_non_christmas = est.const_marginal_effect([[0]])
+    a_non_christmas = est.effect([[0]])
 
 We can create even more complex conditional statements, such as store specific elasticities during christmas:
 
@@ -365,7 +365,7 @@ We can create even more complex conditional statements, such as store specific e
     est.fit(Y, T, X, W)
 
     # est.coef(1, 1) contains the cross-price elasticities in the online store during christmas. 
-    a_christmas = est.const_marginal_effect([[1, 1]])
+    a_christmas = est.effect([[1, 1]])
     # est.coef(0, 1) contains the cross price elasticities in the online store
     # when it is not christmas, etc.
     a_non_christmas = est.const_marginal_effect([[0, 1]])

doc/spec/estimation/forest.rst

@@ -6,7 +6,7 @@ Forest Based Estimators
 Orthogonal Random Forests
 -------------------------
 
-Orthogonal Random Forests [Oprescu2018]_ are a combination of causal forests and double machine learning that allow
+Orthogonal Random Forests [Oprescu2019]_ are a combination of causal forests and double machine learning that allow
 for controlling for a high-dimensional set of confounders :math:`W`, while at the same time estimating non-parametrically
 the heterogeneous treatment effect :math:`\theta(X)`, on a lower dimensional set of variables :math:`X`. 
 Moreover, the estimates are asymptotically normal and hence have theoretical properties
@@ -69,7 +69,7 @@ first approach is applicable.
 
 In the case of discrete treatments (see :py:class:`~econml.ortho_forest.DiscreteTreatmentOrthoForest`) the
 method estimates :math:`\theta(x)` for some target :math:`x` by solving a slightly different
-set of equations (see [Oprescu2018]_ for a theoretical exposition of why a different set of
+set of equations (see [Oprescu2019]_ for a theoretical exposition of why a different set of
 estimating equations is used). In particular, suppose that the treatment :math:`T` takes
 values in :math:`\{0, 1, \ldots, k\}`, then to estimate the treatment effect :math:`\theta_t(x)` of
 treatment :math:`t` as compared to treatment :math:`0`, the method finds the solution to the
@@ -113,7 +113,7 @@ and what the returned values correspond to in a simple data generating process:
     ...                                      model_T=sklearn.linear_model.LinearRegression(),
     ...                                      model_Y=sklearn.linear_model.LinearRegression())
     >>> est.fit(Y, T, W, W)
-    >>> print(est.const_marginal_effect(W[:2]))
+    >>> print(est.effect(W[:2]))
     [[1. ]
      [1.2]]
 
@@ -126,7 +126,7 @@ Similarly, we can call :py:class:`~econml.ortho_forest.DiscreteTreatmentOrthoFor
     ...                                    propensity_model=sklearn.linear_model.LogisticRegression(),
     ...                                    model_Y=sklearn.linear_model.LinearRegression())
     >>> est.fit(Y, T, W, W)
-    >>> print(est.const_marginal_effect(W[:2]))
+    >>> print(est.effect(W[:2]))
     [[1. ]
      [1.2]]
 
@@ -143,7 +143,7 @@ both the treatment and the outcome regressions, in the case of continuous treatm
     >>> est = ContinuousTreatmentOrthoForest()
     >>> est.fit(Y, T, X, W)
     >>> X_test = np.linspace(-1, 1, 30).reshape(-1, 1)
-    >>> treatment_effects = est.const_marginal_effect(X_test)
+    >>> treatment_effects = est.effect(X_test)
     >>> plt.plot(X_test, y, label='ORF estimate')
     >>> plt.plot(X_test[:, 0], np.exp(2*X_test[:, 0]), 'b--', label='True effect')
     >>> plt.legend()

doc/spec/motivation.rst

@@ -21,7 +21,7 @@ It implements techniques from recent academic works, several of which produced i
 the ALICE project of Microsoft Research, and many others from leading groups in the field.
 Examples include Double Machine Learning (see e.g. [Chernozhukov2016]_, [Chernozhukov2017]_,
 [Mackey2017]_, [Nie2017]_, [Chernozhukov2018]_, [Foster2019]_), Causal Forests (see e.g. [Wager2018]_, [Athey2019]_
-[Oprescu2018]_),
+[Oprescu2019]_),
 Deep Instrumental Variables (see e.g. [Hartford2017]_), Non-parametric Instrumental Variables [Newey2003]_,
 meta-learners (see e.g. [Kunzel2017]_).
 The library brings together all these diverse techniques under a common

doc/spec/references.rst

@@ -62,11 +62,11 @@ References
     Generalized Random Forests.
     *Annals of Statistics*, 2019
 
-.. [Oprescu2018]
+.. [Oprescu2019]
     M. Oprescu, V. Syrgkanis and Z. S. Wu.
     Orthogonal Random Forest for Causal Inference.
-    *arXiv preprint arXiv:1806.03467*, 2018.
-    URL http://arxiv.org/abs/1806.03467.
+    *Proceedings of the 36th International Conference on Machine Learning*, 2019.
+    URL http://proceedings.mlr.press/v97/oprescu19a.html.
 
 .. [Nie2017]
     X. Nie and S. Wager.

econml/ortho_forest.py

@@ -17,7 +17,7 @@
 - The `DiscreteTreatmentOrthoForest`, a two-forest approach for learning discrete treatment effects
   using kernel two stage estimation.
 
-For more details on these methods, see our paper [Oprescu2018]_.
+For more details on these methods, see our paper [Oprescu2019]_.
 """
 
 import abc