Preparation for conda update.

Author: MaxBlesch

.conda/bld.bat

@@ -0,0 +1,2 @@
+"%PYTHON%" setup.py install
+if errorlevel 1 exit 1

.conda/build.sh

@@ -0,0 +1 @@
+$PYTHON setup.py install     # Python command to install the script.

.conda/meta.yaml

@@ -0,0 +1,27 @@
+{% set data = load_setup_py_data() %}
+
+package:
+  name: ruspy
+  version: {{ data.get('version') }}
+
+source:
+  # git_url is nice in that it won't capture devenv stuff.  However, it only captures
+  # committed code, so pay attention.
+  git_url: ../
+
+build:
+  number: 0
+  noarch: python
+
+requirements:
+  host:
+    - python >=3.6,<3.8
+  run:
+    - python >=3.6,<3.8
+    - statsmodels
+    - numba >=0.42
+    - numpy
+    - pandas = 1.0.0
+    - pytest
+    - pytest-xdist
+    - scipy

.github/workflows/continuous-integration-workflow.yml

@@ -0,0 +1,42 @@
+name: Continuous Integration Workflow
+on:
+  push:
+    branches:
+    - master
+  pull_request:
+    branches:
+    - '*'
+
+jobs:
+  run-tests:
+    name: Run tests for ${{ matrix.os }} on ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ['ubuntu-latest', 'macos-latest', 'windows-latest']
+        python-version: ['3.6', '3.7']
+    steps:
+      - uses: actions/checkout@v2
+      - uses: goanpeca/setup-miniconda@v1
+        with:
+          activate-environment: ruspy
+          auto-update-conda: true
+          environment-file: environment.yml
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run pytest.
+        shell: bash -l {0}
+        run: pytest --cov-report=xml --cov=./
+
+      - name: Upload coverage report.
+        if: runner.os == 'Linux' && matrix.python-version == '3.7'
+        uses: codecov/codecov-action@v1
+        with:
+          token: df3e71e7-316d-4a04-b4d1-f76b90dfced7
+
+      - name: Run pre-commits.
+        shell: bash -l {0}
+        run: |
+          pre-commit install -f --install-hooks
+          pre-commit run --all-files

README.md

@@ -0,0 +1,47 @@
+ruspy
+======
+
+.. image:: https://readthedocs.org/projects/ruspy/badge/?version=latest
+    :target: https://ruspy.readthedocs.io/en/latest/?badge=latest
+
+.. image:: https://img.shields.io/badge/License-MIT-yellow.svg
+    :target: https://opensource.org/licenses/MIT
+
+.. image:: https://github.com/OpenSourceEconomics/ruspy/workflows/Continuous%20Integration%20Workflow/badge.svg
+    :target: https://github.com/OpenSourceEconomics/ruspy/actions
+
+.. image:: https://codecov.io/gh/OpenSourceEconomics/robupy/branch/master/graph/badge.svg
+  :target: https://codecov.io/gh/OpenSourceEconomics/robupy
+
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://github.com/psf/black
+
+``ruspy`` is an open-source package for the simulation and estimation of a prototypical
+infinite-horizon dynamic discrete choice model based on
+
+    Rust, J. (1987). [Optimal replacement of GMC bus engines: An empirical model of Harold Zurcher.](https://doi.org/10.2307/1911259) *Econometrica, 55* (5), 999-1033.
+
+You can install ``ruspy`` via conda with
+
+.. code-block:: bash
+
+    $ conda config --add channels conda-forge
+    $ conda install -c opensourceeconomics ruspy
+
+Please visit our `online documentation <https://ruspy.readthedocs.io/>`_ for
+tutorials and other information.
+
+
+Citation
+--------
+
+If you use ruspy for your research, do not forget to cite it with
+
+.. code-block:: bash
+
+    @Unpublished{ruspy-1.0,
+        Author = {Maximilian Blesch},
+        Title  = {robupy - An open-source package for the simulation and estimation of a prototypical infinite-horizon dynamic discrete choice model based on Rust (1987)},
+        Year   = {2019},
+        Url    = {https://github.com/OpenSourceEconomics/ruspy},
+        }

README.rst

@@ -0,0 +1,14 @@
+coverage:
+  range: 50...100
+  precision: 2
+  round: down
+  status:
+    project:
+      threshold: 5%
+    patch:
+      threshold: 5%
+
+ignore:
+  - "setup.py"
+  - "respy/config.py"
+  - "ruspy/tests/**/*"

codecov.yml

@@ -14,29 +14,30 @@ his expected total discounted utility with respect to the expected mileage usage
 bus. Each month :math:`t`, a bus arrives at the bus depot in state :math:`s_t = (x_t,
 \epsilon_t(a_t))` containing the mileage since last engine replacement :math:`x_t` and
 other signs of wear and tear plus decision specific information :math:`\epsilon_t(a_t)`.
-Harold Zurcher is faced with the decision to either conduct a complete engine replacement
-:math:`(a_t = 1)` or to perform basic maintenance work :math:`(a_t = 0)`. The cost of
-maintenance :math:`c(x_t, \theta_1)` increases with the mileage state, while the cost of
-replacement :math:`RC` remains constant. Notationwise :math:`\theta_1` captures the
-structural parameters shaping the maintenance cost function. In the case of an engine
-replacement, the mileage state is reset to zero.
+Harold Zurcher is faced with the decision to either conduct a complete engine
+replacement :math:`(a_t = 1)` or to perform basic maintenance work :math:`(a_t = 0)`.
+The cost of maintenance :math:`c(x_t, \theta_1)` increases with the mileage state,
+while the cost of replacement :math:`RC` remains constant. Notationwise
+:math:`\theta_1` captures the structural parameters shaping the maintenance cost
+function. In the case of an engine replacement, the mileage state is reset to zero.
 
 The immediate utility of each action in month :math:`t` is assumed to be additively
 separable and given by:
 
 .. math::
 
     \begin{align}
-    u(a_t, x_t, \theta_1, RC) + \epsilon_t(a_t) \quad \text{with} \quad u(a_t, x_t, \theta_1, RC) = \begin{cases}
+    u(a_t, x_t, \theta_1, RC) + \epsilon_t(a_t) \quad \text{with} \quad u(a_t, x_t,
+    \theta_1, RC) = \begin{cases}
     -RC - c(0, \theta_1)   & a_t = 1 \\
     -c(x_t, \theta_1) & a_t = 0.
     \end{cases}
     \end{align}
 
 
 The objective of Harold Zurcher is to choose a strategy :math:`\pi` of all strategies
-:math:`\Pi` to maximize the utility over infinite horizon and therefore the current value
-in period :math:`t` and state :math:`s_t` is given by:
+:math:`\Pi` to maximize the utility over infinite horizon and therefore the current
+value in period :math:`t` and state :math:`s_t` is given by:
 
 .. math::
 
@@ -47,9 +48,9 @@ in period :math:`t` and state :math:`s_t` is given by:
 The discount factor :math:`\delta` weighs the utilities over all periods and therefore
 captures the preference of utility in current and future time periods. As the model
 assumes stationary utility, as well as stationary transition probabilities the future
-looks the same, whether the agent is at time :math:`t` in state :math:`s` or at any other
-time. Therefore the optimal decision in every period can be interferred by the Bellman
-equation:
+looks the same, whether the agent is at time :math:`t` in state :math:`s` or at any
+other time. Therefore the optimal decision in every period can be interferred by the
+Bellman equation:
 
 .. math::
 
@@ -85,8 +86,8 @@ observable and unobservable state variables, i.e.
     \end{equation}
 
 and furthermore assumes that the unobservables :math:`\epsilon_t(a_t)` are independent
-and identically distributed according to an extreme value distribution with mean zero and
-scale parameter one, i.e.:
+and identically distributed according to an extreme value distribution with mean zero
+and scale parameter one, i.e.:
 
 .. math::
 
@@ -99,14 +100,14 @@ where :math:`\theta_2 = 0.577216`, i.e. the Euler-Mascheroni constant.
 
 Rust (1988) shows that these two assumptions, together with the additive separability
 between the observed and unobserved state variables in the immediate utilities, imply
-that :math:`EV_\theta` is a function independent of :math:`\epsilon_t` and the unique fix
-point of a contraction mapping on the reduced space of all state action pairs :math:`(x,
-a)`. Furthermore, the regenerative property of the process yields for all states
-:math:`x`, that the expected value of replacement corresponds to the expected value of
-maintenance in state :math:`0`, i.e. :math:`EV_\theta(x, 1) = EV_\theta(0, 0)`. Thus
-:math:`EV_\theta` is the unique fixed point on the observed mileage state :math:`x` only.
-Therefore in the following :math:`EV_\theta(x)` refers to :math:`EV_\theta(x, 0)`. The
-contraction mapping is then given by:
+that :math:`EV_\theta` is a function independent of :math:`\epsilon_t` and the unique
+fix point of a contraction mapping on the reduced space of all state action pairs
+:math:`(x,a)`. Furthermore, the regenerative property of the process yields for all
+states :math:`x`, that the expected value of replacement corresponds to the expected
+value of maintenance in state :math:`0`, i.e. :math:`EV_\theta(x, 1) = EV_\theta(0,
+0)`. Thus :math:`EV_\theta` is the unique fixed point on the observed mileage state
+:math:`x` only. Therefore in the following :math:`EV_\theta(x)` refers to
+:math:`EV_\theta(x, 0)`. The contraction mapping is then given by:
 
 .. math::
 
@@ -122,15 +123,15 @@ closed-form solution given by the multinomial logit formula (McFadden, 1973):
 
     \begin{equation}
     P(a|x, \theta) = \frac{\exp(u(a, x, RC, \theta_1) + \delta EV_\theta((a-1) \cdot
-    x))}{\sum_{i \in \{0, 1\}} \exp(u(i, x, RC, \theta_1) + \delta EV_\theta((i - 1) x))}
+    x))}{\sum_{i \in \{0, 1\}} \exp(u(i, x, RC, \theta_1) + \delta EV_\theta((i - 1)x))}
     \end{equation}
 
-These closed form solutions allow to estimate the structural parameters driving Zurcher's
-decisions. Given the data :math:`\{a_0, ....a_T, x_0, ..., x_T\}` for a single bus, one
-can form the likelihood function :math:`l^f(a_1, ..., a_T, x_1, ...., x_T | a_0, x_0,
-\theta)` and estimate the parameter vector $\theta$ by maximum likelihood. Rust (1988)
-proofs that this function has due to the conditional independence assumption a simple
-form:
+These closed form solutions allow to estimate the structural parameters driving
+Zurcher's decisions. Given the data :math:`\{a_0, ....a_T, x_0, ..., x_T\}` for a
+single bus, one can form the likelihood function :math:`l^f(a_1, ..., a_T, x_1, ....,
+x_T | a_0, x_0, \theta)` and estimate the parameter vector $\theta$ by maximum
+likelihood. Rust (1988) proofs that this function has due to the conditional
+independence assumption a simple form:
 
 .. math::
 

docs/source/economics.rst

@@ -36,9 +36,9 @@ If you want to replicate Rust (1987) you can download the raw data from John Rus
 `website <https://editorialexpress.com/jrust/research.html>`_ and prepare it yourself it
 the desired manner. Or you can use the functions in `zurcher-data
 <https://github.com/OpenSourceEconomics/zurcher-data>`_ which are provided by the
-`OpenSourceEconomics <https://github.com/OpenSourceEconomics>`_ community and tailored to
-the ruspy package. In the demonstration section these functions are used to replicate the
-results documented.
+`OpenSourceEconomics <https://github.com/OpenSourceEconomics>`_ community and
+tailored to the ruspy package. In the demonstration section these functions are used
+to replicate the results documented.
 
 
 The estimation function
@@ -61,11 +61,11 @@ Estimation initialization dictionary
 ------------------------------------
 
 The initialization dictionary contains model, optimizer and algorithmic specific
-information. The information on theses three categories is saved in subdictionaries under
-the keys **model_specifications**, **optimizer** and **alg_details**.  The model specific
-information is mandatory, while the others are optional. If not given, just the default
-values are selected. See :ref:`alg_details` for the possible keys and the default values.
-The mandatory model specific information keys are:
+information. The information on theses three categories is saved in subdictionaries
+under the keys **model_specifications**, **optimizer** and **alg_details**.  The
+model specific information is mandatory, while the others are optional. If not given,
+just the default values are selected. See :ref:`alg_details` for the possible keys
+and the default values. The mandatory model specific information keys are:
 
 **discount_factor :** *(float)* The discount factor. See :ref:`disc_fac` for details.
 
@@ -79,8 +79,10 @@ details.
 
 
 
-The dictionary under **optimizer** allows to specify the optimizer from the `scipy library
-<http://lagrange.univ-lyon1.fr/docs/scipy/0.17.1/generated/scipy.optimize.minimize.html>`_. The entries of the dictionary are all *strings* and the following keys are so far possible:
+The dictionary under **optimizer** allows to specify the optimizer from the `scipy
+library <http://lagrange.univ-lyon1.fr/docs/scipy/0.17.1/generated/scipy.optimize
+.minimize.html>`_. The entries of the dictionary are all *strings* and the following
+keys are so far possible:
 
 **optimizer_name :** The name of the optimizer. See `scipy library
 <http://lagrange.univ-lyon1.fr/docs/scipy/0.17.1/generated/
@@ -154,8 +156,8 @@ corresponding function in the code is:
 
 
 The ``estimate_transitions`` function minimizes now the ``loglike_trans`` function by
-calling a minimize routine from the `scipy library
-<http://lagrange.univ-lyon1.fr/docs/scipy/0.17.1/generated/scipy.optimize.minimize.html>`_.
+calling a minimize routine from the `scipy library <http://lagrange.univ-lyon1
+.fr/docs/scipy/0.17.1/generated/scipy.optimize.minimize.html>`_.
 Even though transition probabilities need to add up to 1 and have to be positive, there
 are no constraints on the minimized parameters. The constraints are applied inside
 ``loglike_trans`` by a reparametrization function:
@@ -222,7 +224,10 @@ The transition matrix is then used for the cost parameter estimation.
 Cost parameter estimation
 -------------------------
 
-The cost parameters are estimated directly by minimizing the log-likelihood and the corresponding jacobian function with a minimize function from the `scipy library <http://lagrange.univ-lyon1.fr/docs/scipy/0.17.1/generated/scipy.optimize.minimize.html>`_ . The functions can be found in ``ruspy.estimation.est_cost_params``:
+The cost parameters are estimated directly by minimizing the log-likelihood and the
+corresponding jacobian function with a minimize function from the `scipy library
+<http://lagrange.univ-lyon1.fr/docs/scipy/0.17.1/generated/scipy.optimize.minimize
+.html>`_ . The functions can be found in ``ruspy.estimation.est_cost_params``:
 
 
 .. currentmodule:: ruspy.estimation.est_cost_params
@@ -246,8 +251,8 @@ calculation of the same fixed point is avoided by the following function:
     get_ev
 
 After successful minimization, some results of the `scipy result dictionary
-<https://docs.scipy.org/doc/scipy-0.14.0/reference/generated/scipy.optimize.OptimizeResult.html>`_
-are used to construct ruspys cost parameter results:
+<https://docs.scipy.org/doc/scipy-0.14.0/reference/generated/scipy.optimize
+.OptimizeResult.html>`_ are used to construct ruspys cost parameter results:
 
 
 .. _result_costs:
@@ -264,8 +269,9 @@ The dictionary containing the cost parameter results has the following keys:
 
 **jac :** *(numpy.array)* The value of the estimates' jacobian.
 
-**95_conf_interv :** *(numpy.array)* :math:`2 \times num\_states` dimensional numpy.array
-containing the bootstrapped (1000 replications) 95% confidence interval bounds.
+**95_conf_interv :** *(numpy.array)* :math:`2 \times num\_states` dimensional
+numpy.array containing the bootstrapped (1000 replications) 95% confidence interval
+bounds.
 
 **std_errors :** *(numpy.array)* :math:`num\_states` dimensional numpy.array with
 bootstrapped standard errors for each parameter.
@@ -308,7 +314,7 @@ Demonstration
 -------------
 
 In the promotion folder of the repository are two demonstration jupyter notebooks. The
-`replication
-<https://github.com/OpenSourceEconomics/ruspy/blob/kantevorich/promotion/replication/replication.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.
+`replication <https://github.com/OpenSourceEconomics/ruspy/blob/kantevorich/promotion
+/replication/replication.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.