Merge pull request #50 from OpenSourceEconomics/contributing

Working on documentation.

Author: MaxBlesch

docs/source/credits.rst

@@ -0,0 +1,68 @@
+Contributing
+============
+
+Team
+----
+
+----
+BDFL
+----
+
+`Philipp Eisenhauer <https://github.com/peisenha>`_
+
+----------------
+Development Lead
+----------------
+
+`Maximilian Blesch <https://github.com/MaxBlesch>`_
+
+------------
+Contributors
+------------
+
+`Sebastian Becker <https://github.com/sebecker>`_, `Pascal Heid <https://github
+.com/Pascalheid>`_
+
+
+Master Theses
+-------------
+
+Below you find a list with past Master Theses, that used ruspy. If you think of using
+ruspy in your Master Thesis, please reach out to us and view the issues with a
+Master-Thesis tag on `github. <https://github.com/OpenSourceEconomics/ruspy/issues>`_
+
+------------------------------------------------------
+Decision rule performance under model misspecification
+------------------------------------------------------
+by `Maximilian Blesch <https://github.com/MaxBlesch>`_
+
+I incorporate techniques from distributionally robust optimization into a dynamic
+investment model. This allows to explicitly account for ambiguity in the decision-
+making process. I outline an economic, mathematical, and computational model
+to study the seminal bus replacement problem (Rust, 1987) under potential model
+misspecification. I specify ambiguity sets for the transition dynamics of the model.
+These are based on empirical estimates, statistically meaningful, and computation-
+ally tractable. I analyze alternative policies in a series of computational exper-
+iments. I find that, given the structure of the model and the available data on
+past transitions, a policy simply ignoring model misspecification often outperforms
+its alternatives that are designed to explicitly account for it.
+
+
+---------------------------------------------------------------------------------
+Mathematical Programming with Equilibrium Constraints: An Uncertainty Perspective
+---------------------------------------------------------------------------------
+by `Pascal Heid <https://github.com/Pascalheid>`_
+
+This thesis explores to which extent the Nested Fixed Point Algorithm (NFXP) as
+suggested by Rust (1987) differs from the Mathematical Programming with Equilibrium
+Constraints as introduced by Su and Judd (2012) by revisiting the Optimal Bus Engine
+Replacement Problem posed by the previous author. While previous studies focus on
+quantitative measures of speed and convergence rate, my focus lies on how the two
+approaches actually recover the true model when the simulation setup is less clean
+and more closely to what applied researchers typically face. For this comparison I
+draw on some techniques from the Uncertainty Quantification literature. I run a large
+scale simulation study in which I compare the two approaches among different model
+specifications by checking how accurate their counterfactual demand level predictions
+are. I can show that under realistic circumstances, the two approaches can yield
+considerably different predictions suggesting that they should be regarded as
+complements rather than competitors.

docs/source/estimation.rst

@@ -424,11 +424,10 @@ Demonstration
 ****************
 
 In the promotion folder of the repository are two demonstration jupyter notebooks. The
-`replication <https://github.com/OpenSourceEconomics/ruspy/blob/kantevorich/promotion
+`replication <https://github.com/OpenSourceEconomics/ruspy/blob/master/promotion
 /replication/replication.ipynb>`_ notebook allows to easily experiment with the
 methods described here as well as the implied demand function. If you have have
 everything setup, then it should be easy to run it. For a more advanced set up have
 a look at the `replication of Iskhakov et al. (2016)
-<https://github.com/OpenSourceEconomics/ruspy/
-blob/replication_notebook_and_documentation/promotion/replication/
-replication_iskhakov_et_al_2016.ipynb>`_.
+<https://github.com/OpenSourceEconomics/ruspy/blob/master/promotion/replication
+/replication_iskhakov_et_al_2016.ipynb>`_.

docs/source/index.rst

@@ -27,9 +27,9 @@ as well as the comment by Iskakhov et al. (2016) on Su and Judd (2012):
   “constrained optimization approaches to estimation of structural models”. <https://doi.org/10.3982/ECTA12605>`_
   *Econometrica, 84* (1), 365-370.
 
-So far, there has been only one research project based on this code. Numerical
-experiments for a robust decision rule for Harold Zurcher can be found in this online
-`organisation. <https://github.com/robustzurcher>`_
+So far, there has been only one research project based on this code. The promotional
+material for this project can be found
+`here. <https://github.com/robustzurcher/promotion>`_
 
 ruspy can be installed via conda with:
 
@@ -39,6 +39,21 @@ ruspy can be installed via conda with:
       $ conda install -c opensourceeconomics ruspy
 
 
+After installing ruspy, you can familiarize yourself with ruspy's tools and
+interface by exploring multiple tutorial notebooks. Note that for a full
+comprehension, you should read the papers above or study at least the economics
+section of this documentation. We provide a `simulation <https://github
+.com/OpenSourceEconomics/ruspy/blob/master/promotion
+/simulation/simulation_convergence.ipynb>`_ and `replication <https://
+github.com/OpenSourceEconomics/ruspy/blob/master/promotion
+/replication/replication.ipynb>`_. The first one puts more focus on the simulation
+function of ruspy while the latter has a closer look at the estimation function.
+Lastly, for a combination of both you can further dive into the `replication of
+Iskhakov et al. (2016) <https://github
+.com/OpenSourceEconomics/ruspy/blob/master/promotion/replication
+/replication_iskhakov_et_al_2016.ipynb>`_ notebook which allows to replicate this paper
+using ruspy.
+
 
 
 .. toctree::
@@ -50,3 +65,4 @@ ruspy can be installed via conda with:
    estimation
    simulation
    references
+   credits

docs/source/simulation.rst

@@ -83,7 +83,7 @@ Demonstration
 -------------
 
 In the promotion folder of the repository are two demonstration jupyter notebooks. The
-`simulation <https://github.com/OpenSourceEconomics/ruspy/blob/kantevorich/
-promotion/simulation/simulation_convergence.ipynb>`_ notebook allows to easily
+`simulation <https://github.com/OpenSourceEconomics/ruspy/blob/master/promotion
+/simulation/simulation_convergence.ipynb>`_ notebook allows to easily
 experiment with the estimation methods described here. If you have have everything
 setup, then it should be easy to run it.

setup.py

@@ -14,7 +14,7 @@
 
 setup(
     name=NAME,
-    version="1.0",
+    version="1.1",
     description=DESCRIPTION,
     author=AUTHOR,
     author_email=EMAIL,