Merge pull request #64 from OpenSourceEconomics/ex1

changes to estimation

Author: MaxBlesch

.gitignore

@@ -22,6 +22,7 @@ ruspy.rst
 modules.rst
 _generated
 *.db
+*.DS_Store
 results_ipopt.txt
 get_iskhakov_results
 

docs/source/api.rst

@@ -4,7 +4,6 @@ API
 
 Here the API of ruspy is documented.
 
-
 .. autosummary::
    :toctree: _generated
    :template: custom-module-template.rst

docs/source/conf.py

@@ -52,6 +52,7 @@
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
     "numpydoc",
+    "nbsphinx",
 ]
 
 autosummary_mock_imports = [

docs/source/credits.rst

@@ -21,7 +21,8 @@ Contributors
 ------------
 
 `Sebastian Becker <https://github.com/sebecker>`_, `Pascal Heid <https://github
-.com/Pascalheid>`_
+.com/Pascalheid>`_, `Viktoria Kleinschmidt <https://github.com/viktoriakleinschmidt>`_
+
 
 
 Master Theses

docs/source/economics.rst

@@ -233,7 +233,7 @@ looking like the following:
 
     \begin{equation}
       \max_{(\theta, EV)} \; log \; l^f_{aug}(a_1, ..., a_T, x_1, ...., x_T | a_0, x_0, \theta, EV) \\
-      \text{subject to } \; EV = T(EV, \theta).
+      \text{ subject to } \; EV = T(EV, \theta).
     \end{equation}
 
 The constraints are generally nonlinear functions which restricts the use of

docs/source/estimation.rst

@@ -40,20 +40,10 @@ ruspy can be installed via conda with:
 
 
 After installing ruspy, you can familiarize yourself with ruspy's tools and
-interface by exploring multiple tutorial notebooks. Note that for a full
+interface by exploring multiple tutorial notebooks, which can be found
+`here <tutorials.html>`_. 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.
-
+section of this documentation.
 
 
 .. toctree::
@@ -64,6 +54,7 @@ using ruspy.
    model_code
    estimation
    simulation
+   tutorials
    references
    credits
    api

docs/source/index.rst

@@ -105,7 +105,7 @@ hyperbolic cost function
 ---------------
 Cost parameters
 ---------------
-The second in put are the cost parameters, which are stored as a one dimensional
+The second input are the cost parameters, which are stored as a one dimensional
 *numpy.array*. At the first position always the replacement cost :math:`RC` is stored.
 The next positions are subsequently filled with :math:`\theta_{11}, \theta_{12}, ...`.
 The exact number depends on the functional form.
@@ -181,17 +181,18 @@ allow to specify, when the algorithm switches from contraction to Newton-Kantoro
 iterations and general parameters, which let the algorithm stop. So far, there is no
 switching back implemented.
 
-**max_cont_steps :** *(int)* The maximum number of contraction iterations before
-switching to Newton-Kantorovich iterations. Default is 20.
+- **max_cont_steps :** *(int)* The maximum number of contraction iterations before
+  switching to Newton-Kantorovich iterations. Default is 20.
 
-**switch_tol :** *(float)* If this threshold is reached by contraction iterations, then
-the algorithm switches to Newton-Kantorovich iterations. Default is :math:`10^{-3}`.
+- **switch_tol :** *(float)* If this threshold is reached by contraction iterations,
+  then the algorithm switches to Newton-Kantorovich iterations. Default is
+  :math:`10^{-3}`.
 
-**max_newt_kant_steps :** *(int)* The maximum number of Newton-Kantorovich iterations
-before the algorithm stops. Default is 20.
+- **max_newt_kant_steps :** *(int)* The maximum number of Newton-Kantorovich iterations
+  before the algorithm stops. Default is 20.
 
-**threshold :** *(float)* If this threshold is reached by Newton-Kantorovich iterations,
-then the algorithm stops. Default is :math:`10^{-12}`.
+- **threshold :** *(float)* If this threshold is reached by Newton-Kantorovich
+  iterations, then the algorithm stops. Default is :math:`10^{-12}`.
 
 .. _ev:
 
@@ -276,8 +277,9 @@ the following inputs:
 Initialization Dictionairy
 ---------------------------
 
-This is the :ref:`init_dict` needed for the ``estimate`` function. The ``get_demand``
-function draws the model specifications needed to calculate demand from this.
+This is the :ref:`init_dict` needed for the function ``get_criterion_function``.
+The ``get_demand`` function draws the model specifications needed to calculate
+demand from this.
 
 
 .. _demand_dict:
@@ -291,23 +293,22 @@ This dictionairy provides all the necessary information about how the demand
 function is supposed to look like and how precisely it is supposed to be calculated.
 It has to hold the following keys:
 
-**RC_lower_bound :** *(float)* The lowest replacement cost for which the demand
-is supposed to be calculated.
+- **RC_lower_bound :** *(float)* The lowest replacement cost for which the demand is
+  supposed to be calculated.
 
-**RC_upper_bound :** *(float)* The highest replacement cost for which the demand
-is supposed to be calculated.
+- **RC_upper_bound :** *(float)* The highest replacement cost for which the demand is
+  supposed to be calculated.
 
-**demand_evaluations :** *(int)* The grid size of the replacement cost between
-RC_lower_bound and RC_upper_bound for which the demand level shall be calculated.
+- **demand_evaluations :** *(int)* The grid size of the replacement cost between
+  RC_lower_bound and RC_upper_bound for which the demand level shall be calculated.
 
-**tolerance :** *(float)* The stopping tolerance for the fixed point calculation
-needed to obtain each demand level.
+- **tolerance :** *(float)* The stopping tolerance for the fixed point calculation
+  needed to obtain each demand level.
 
-**num_periods :** *(int)* Number of months :math:`T` for which the expected demand
-is derived. Consequently, set it to 12 if you want to get the annual expected demand.
+- **num_periods :** *(int)* Number of months :math:`T` for which the expected demand
+  is derived. Consequently, set it to 12 if you want to get the annual expected demand.
 
-**num_buses :** *(int)* Number of buses :math:`M` for which the demand is
-calculated.
+- **num_buses :** *(int)* Number of buses :math:`M` for which the demand is calculated.
 
 
 .. _demand_params:
@@ -339,6 +340,6 @@ and for the amount of buses in the fleet. It also contains a column *success*
 which indicates whether the fixed point algorithm converged successfully.
 
 
+
 The use of the ``get_demand`` function is shown in the following `replication
-<https://github.com/OpenSourceEconomics/ruspy/blob/kantevorich/promotion
-/replication/replication.ipynb>`_ notebook.
+<tutorials/replication/replication.ipynb>`_ notebook.

docs/source/model_code.rst

@@ -11,7 +11,8 @@ Iskhakov, F., Lee, J., Rust, J., Schjerning, B., & Seo, K. (2016). `Comment on
 Kantorovich, L. (1948). On Newton’s method for functional equations. *Doklady Akademii
 Nauk SSSR, 71* (1), 1237– 1240.
 
-Kraft, D. (1994). `Algorithm 733: TOMP–Fortran modules for optimal control calculations <https://doi.org/10.1145/192115.192124>`_
+Kraft, D. (1994). `Algorithm 733: TOMP–Fortran modules for optimal control calculations
+<https://doi.org/10.1145/192115.192124>`_
 *ACM Transactions on Mathematical Software, vol. 20*, no. 3, pp. 262-281.
 
 McFadden, D. (1973). `Conditional logit analysis of qualitative choice behavior

docs/source/references.rst

@@ -29,14 +29,15 @@ Simulation initialization dictionary
 
 The initialization dictionary contains the following keys:
 
-**seed :** *(int)* A positive integer setting the random seed for drawing random
-numbers. If none given, some random seed is drawn.
+- **seed :** *(int)* A positive integer setting the random seed for drawing random
+  numbers. If none given, some random seed is drawn.
 
-**discount_factor :** *(float)* See :ref:`disc_fac` for more details.
+- **discount_factor :** *(float)* See :ref:`disc_fac` for more details.
 
-**buses :** *(int)* The number of buses to be simulated.
+- **buses :** *(int)* The number of buses to be simulated.
+
+- **periods :** *(int)* The number of periods to be simulated.
 
-**periods :** *(int)* The number of periods to be simulated.
 
 
 The simulation process
@@ -76,14 +77,13 @@ The simulation
 --------------
 After the simulation process the observed states, decisions and mileage uses are
 returned. Additionally the agent's utility. They are all stored in pandas.DataFrame with
-column names **states**, **decisions**, **utilities** and **usage**.Hence, the observed
+column names **states**, **decisions**, **utilities** and **usage**. Hence, the observed
 data is a subset of the returned Dataframe.
 
 Demonstration
 -------------
 
-In the promotion folder of the repository are two demonstration jupyter notebooks. The
-`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.
+The `simulation notebook <tutorials/simulation/simulation_convergence.ipynb>`_ allows to
+easily experiment with the estimation methods described here. The notebook can be
+downloaded from the `simulation folder <tutorials/simulation>`_ in the tutorials of
+ruspy. If you have have everything setup, then it should be easy to run it.