further extended the readme by an example

Author: MalteKurz

README.md

@@ -3,9 +3,9 @@
 This repo contains a prototype implementation **DoubleML-Serverless** of distributed double machine learning with a serverless infrastructure
 using [AWS Lambda](https://aws.amazon.com/lambda).
 A detailed discussion of this prototype can be found in the paper "Distributed Double Machine Learning with a  Serverless Architecture" (Kurz, 2021).
-**DoubleML-Serverless** is an extension for serverless cloud computing of the Python package **DoubleML**.
-**DoubleML** is available via PyPI [https://pypi.org/project/DoubleML](https://pypi.org/project/DoubleML) and on GitHub [https://github.com/DoubleML/doubleml-for-py](https://github.com/DoubleML/doubleml-for-py).
-Also see [https://docs.doubleml.org](https://docs.doubleml.org) for a detailed documentation and user guide for the **DoubleML** package.
+DoubleML-Serverless is an extension for serverless cloud computing of the Python package **DoubleML**.
+DoubleML is available via PyPI [https://pypi.org/project/DoubleML](https://pypi.org/project/DoubleML) and on GitHub [https://github.com/DoubleML/doubleml-for-py](https://github.com/DoubleML/doubleml-for-py).
+Also see [https://docs.doubleml.org](https://docs.doubleml.org) for a detailed documentation and user guide for the DoubleML package.
 
 ## Getting started
 
@@ -47,19 +47,74 @@ There are two options for deployment:
 
 2. The second option for deployment is based on AWS Serverless Application Model (AWS SAM).
 
-2.1 Setup the AWS SAM CLI as described here: [https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-getting-started.html](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-getting-started.html)
+    2.1 Setup the AWS SAM CLI as described here: [https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-getting-started.html](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-getting-started.html)
 
-2.2 To deploy the application use the following commands (for more information see [https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/what-is-sam.html](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/what-is-sam.html))
+    2.2 To deploy the application use the following commands (for more information see [https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/what-is-sam.html](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/what-is-sam.html))
+    ```
+    cd aws_lambda_app
+    sam build
+    sam deploy --guided
+    ```
 
+### Estimating a partially linear regression model with double machine learning and serverless scaling using AWS Lambda
+
+To demonstrate the functionality of DoubleML-Serverless we revisit the Pennsylvania  Reemployment Bonus experiment
+and estimate the effect of provisioning a cash bonus on the unemployment duration as studied in Chernozhukov et al. (2018).
+This example is also discussed in the accompanying paper to the DoubleML-Serverless package (Kurz, 2021).
+
+We first load the data using functionalities from the DoubleML package.
+```python
+from doubleml.datasets import fetch_bonus
+df_bonus = fetch_bonus('DataFrame')
 ```
-cd aws_lambda_app
-sam build
-sam deploy --guided
+
+The class `DoubleMLDataS3` serves as data-backend for DoubleML-Serverless model classes.
+It is inherited from the `DoubleML` class `DoubleMLData`.
+We initialize an object of the `DoubleMLDataS3` for the bonus data and upload it to the S3 bucket `doubleml-serverless-data` used for the data transfer to AWS Lambda.
+```python
+from doubleml_serverless import DoubleMLDataS3
+
+dml_data_bonus = DoubleMLDataS3(
+    'doubleml-serverless-data', 'bonus_data.csv',
+    df_bonus,
+    y_col='inuidur1',
+    d_cols='tg',
+    x_cols=['female', 'black', 'othrace',
+       'dep1', 'dep2', 'q2', 'q3',
+       'q4', 'q5', 'q6', 'agelt35',
+       'agegt54', 'durable', 'lusd', 'husd'])
+dml_data_bonus.store_and_upload_to_s3()
 ```
 
-### Estimating a partially linear regression model with double machine learning and serverless scaling using AWS Lambda
+To estimate the nuisance functions we use a random forest regressor which averages over 500 trees.
+We further apply repeated cross-fitting with 5 folds and 100 repetitions/splits.
+```python
+from doubleml_serverless import DoubleMLPLRServerless
+from sklearn.base import clone
+from sklearn.ensemble import RandomForestRegressor
+
+ml = RandomForestRegressor(n_estimators = 500)
+ml_g = clone(ml)
+ml_m = clone(ml)
+dml_lambda_plr_bonus = DoubleMLPLRServerless(
+    'LambdaCVPredict', 'eu-central-1',
+    dml_data_bonus, ml_g, ml_m,
+    n_folds=5, n_rep=100)
+```
 
+To estimate the model locally we can call `dml_lambda_plr_bonus.fit()`.
+Estimation on AWS Lambda is achieved via `dml_lambda_plr_bonus.fit_aws_lambda()`.
+Note that you will be charged for all used resources in the AWS account you deployed the serverless application to.
+```python
+dml_lambda_plr_bonus.fit_aws_lambda()
+```
 
+A summary of the estimation result is available via the property `dml_lambda_plr_bonus.summary`.
+Some metrics about the estimation on AWS Lambda can be obtained via the property  `dml_lambda_plr_bonus.aws_lambda_metrics`.
 
 ## References
+
+Chernozhukov, V., Chetverikov, D., Demirer, M., Duflo, E., Hansen, C., Newey, W. and Robins, J. (2018),
+Double/debiased machine learning for treatment and structural parameters. The Econometrics Journal, 21: C1-C68. doi:[10.1111/ectj.12097](https://doi.org/10.1111/ectj.12097).
+
 Kurz, M.S. 2020. "Distributed Double Machine Learning with a  Serverless Architecture". Unpublished Working Paper.