docs/source/optimization/constraints/constraints.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import pandas as pd"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# How to Specify Constraints\n",
    "\n",
    "\n",
    "## General Structure of Constraints\n",
    "\n",
    "Each type of constraint is described in more detail below.\n",
    "\n",
    "\n",
    "## Tutorial \n",
    "\n",
    "Below we show you how to specify constraints with simplified examples. \n",
    "\n",
    "For the simpler constraints, we re-use the completely made up params DataFrame we used to explain how to select parameters on the previous page. If you are unfamiliar with `DataFrame.loc` and `DataFrame.query` make sure that your read this explanation first!\n",
    "\n",
    "Some other examples are inspired by real projects. In any case, you don't have to understand any of the examples in detail. Just look at the index of their ``params`` DataFrame to see how you can use the constraints in your own projects. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th>value</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>category</th>\n",
       "      <th>number</th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th rowspan=\"3\" valign=\"top\">a</th>\n",
       "      <th>0</th>\n",
       "      <td>0.10</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>0.45</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>0.55</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th rowspan=\"3\" valign=\"top\">b</th>\n",
       "      <th>0</th>\n",
       "      <td>0.75</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>0.85</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>-1.00</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                 value\n",
       "category number       \n",
       "a        0        0.10\n",
       "         1        0.45\n",
       "         2        0.55\n",
       "b        0        0.75\n",
       "         1        0.85\n",
       "         2       -1.00"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "index = pd.MultiIndex.from_product(\n",
    "    [[\"a\", \"b\"], np.arange(3)], names=[\"category\", \"number\"]\n",
    ")\n",
    "\n",
    "df = pd.DataFrame(\n",
    "    data=[0.1, 0.45, 0.55, 0.75, 0.85, -1.0], index=index, columns=[\"value\"]\n",
    ")\n",
    "df"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## fixed constraints\n",
    "\n",
    "To diagnose what goes wrong in difficult optimizations you often want to fix some of the parameters. Of course, you could just remove them from your parameter vector, but again, it's very handy if the parameter vector that arrives in your utility function always looks exactly the same. Therefore, estimagic can fix the parameters for you. A good example of a parameter that is fixed is a discount factor in a structural model. Assume this parameter is called delta and we want to fix it at 0.95. Then, the constraint is"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "constraints = [{\"loc\": \"delta\", \"type\": \"fixed\", \"value\": 0.95}]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that ``\"value\"`` is optional. If it is not specified, the parameter is fixed at the value specified in the DataFrame.\n",
    "\n",
    "## probability constraints\n",
    "\n",
    "Probability constraints are similar to sum constraints, but they always sum to 1 and there is the additional constraint that they are all between zero and one. Probability constraints are therefore also pratical for shares or parameters of certain production functions. Let's assume we have a params DataFrame with \"shares\" in the fist index level. As you probably guess by now, the constraint will look as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "constraints = [{\"loc\": \"shares\", \"type\": \"probability\"}]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## increasing and decreasing constraints\n",
    "\n",
    "As the name suggests, increasing constraints ensure that the selected parameters are increasing. The prime example are cutoffs in ordered choice models as for example the ordered logit model [Ordered Logit Example](../../getting_started/ordered_logit_example.ipynb)\n",
    "\n",
    "The constraint then looks as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "constraints = [{\"loc\": \"cutoffs\", \"type\": \"increasing\"}]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Decreasing constraints are defined analogously."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## equality constraints\n",
    "\n",
    "Equality constraints ensure that all selected parameters are equal. This sounds useless because one could simply leave all but one parameters out. But it does very often make the parsing of the parameter vector much easier. For example in dynamic models where you sometimes want to keep parameters time-invariant and sometimes not. The code often becomes much easier if you do not need if-conditions to handle those two (or potentially many more) cases and instead let estimagic handle them for you. An example could be the simple DataFrame from the very beginning, where \"a\" could be the name of a parameter and \"number\" could enumerate periods in the model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th>value</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>category</th>\n",
       "      <th>number</th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th rowspan=\"3\" valign=\"top\">a</th>\n",
       "      <th>0</th>\n",
       "      <td>0.10</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>0.45</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>0.55</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th rowspan=\"3\" valign=\"top\">b</th>\n",
       "      <th>0</th>\n",
       "      <td>2.00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>2.00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>2.00</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                 value\n",
       "category number       \n",
       "a        0        0.10\n",
       "         1        0.45\n",
       "         2        0.55\n",
       "b        0        2.00\n",
       "         1        2.00\n",
       "         2        2.00"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# make sure the equality constraint is satisfied\n",
    "df = df.copy()\n",
    "df.loc[\"b\", \"value\"] = 2\n",
    "df"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Keeping the parameter group \"b\" time-invariant would be as simple as:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "constraints = [{\"loc\": \"b\", \"type\": \"equality\"}]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Under the hood this will optimize over just one b-parameter and set the other b-parameters equal to that one parameter."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## pairwise_equality constraints\n",
    "\n",
    "Pairwise equality constraints are different from all other constraints because they correspond to several sets of parameters. Let's assume we want to keep the parameters \"a\" and \"b\" pairwise equal, then the constraint looks like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "constraints = [{\"locs\": [\"a\", \"b\"], \"type\": \"pairwise_equality\"}]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively, you could have an entry \"queries\" where the corresponding value is a list of query strings. Both \"locs\" and \"queries\" can have any number of entries. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Covariance Constraints\n",
    "\n",
    "In maximum likelihood estimations, you often have to estimate a covariance matrix of a contribution. \n",
    "\n",
    "Of course, such a covariance matrix has to be a valid, i.e. positive semi-definite, covariance matrix. This is where the \"covariance\" constraint comes in handy. The covariance constraint assumes that the parameters selected by its ``\"loc\"`` or ``\"query\"`` field correspond to the lower triangle of a covariance matrix. The elements are ordered in C-order, i.e starting with the first and only non-zero element of the first row, then the first and second element of the second row and so on.\n",
    "\n",
    "It's easier to see this in an example taken from the [respy](https://github.com/OpenSourceEconomics/respy) package. The toy model represents the [Robinson Crusoe economy](https://en.wikipedia.org/wiki/Robinson_Crusoe_economy) in the setting of a discrete choice dynamic programming model. In the model, Robinson can choose between fishing, relaxing in a hammock, and improving his fishing skills by talking to Friday. The reward of each alternative is subject to a shock distributed according to a covariance matrix."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th>value</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>category</th>\n",
       "      <th>name</th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>delta</th>\n",
       "      <th>delta</th>\n",
       "      <td>0.950000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th rowspan=\"2\" valign=\"top\">wage_fishing</th>\n",
       "      <th>exp_fishing</th>\n",
       "      <td>0.100000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>contemplation_with_friday</th>\n",
       "      <td>0.400000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>nonpec_fishing</th>\n",
       "      <th>constant</th>\n",
       "      <td>-1.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th rowspan=\"2\" valign=\"top\">nonpec_friday</th>\n",
       "      <th>constant</th>\n",
       "      <td>-1.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>not_fishing_last_period</th>\n",
       "      <td>-1.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th rowspan=\"2\" valign=\"top\">nonpec_hammock</th>\n",
       "      <th>constant</th>\n",
       "      <td>2.500000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>not_fishing_last_period</th>\n",
       "      <td>-1.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th rowspan=\"6\" valign=\"top\">shocks_cov</th>\n",
       "      <th>var_fishing</th>\n",
       "      <td>1.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>cov_friday_fishing</th>\n",
       "      <td>0.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>var_friday</th>\n",
       "      <td>1.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>cov_hammock_fishing</th>\n",
       "      <td>-0.200000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>cov_hammock_friday</th>\n",
       "      <td>0.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>var_hammock</th>\n",
       "      <td>1.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>lagged_choice_1_hammock</th>\n",
       "      <th>constant</th>\n",
       "      <td>1.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>meas_error</th>\n",
       "      <th>sd_fishing</th>\n",
       "      <td>0.000001</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                                      value\n",
       "category                name                               \n",
       "delta                   delta                      0.950000\n",
       "wage_fishing            exp_fishing                0.100000\n",
       "                        contemplation_with_friday  0.400000\n",
       "nonpec_fishing          constant                  -1.000000\n",
       "nonpec_friday           constant                  -1.000000\n",
       "                        not_fishing_last_period   -1.000000\n",
       "nonpec_hammock          constant                   2.500000\n",
       "                        not_fishing_last_period   -1.000000\n",
       "shocks_cov               var_fishing               1.000000\n",
       "                        cov_friday_fishing         0.000000\n",
       "                        var_friday                 1.000000\n",
       "                        cov_hammock_fishing       -0.200000\n",
       "                        cov_hammock_friday         0.000000\n",
       "                        var_hammock                1.000000\n",
       "lagged_choice_1_hammock constant                   1.000000\n",
       "meas_error              sd_fishing                 0.000001"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "params = pd.read_csv(\"robinson-crusoe-covariance.csv\").set_index([\"category\", \"name\"])\n",
    "params"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The parameters that form the covariance matrix are the ones where category equals ``\"shocks_cov\"``. The constraint could not be easier to express:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "constraints = [{\"loc\": \"shocks_cov\", \"type\": \"covariance\"}]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "That's all. To look at the resulting covariance matrix, we can use another nice function from estimagic:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 1. ,  0. , -0.2],\n",
       "       [ 0. ,  1. ,  0. ],\n",
       "       [-0.2,  0. ,  1. ]])"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from estimagic.optimization.utilities import cov_params_to_matrix\n",
    "\n",
    "cov_params_to_matrix(params.loc[\"shocks_cov\", \"value\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the names in the index are not used at all to determine which element goes where. Otherwise estimagic would have to make assumptions on your index and we don't want to do that. \n",
    "\n",
    "Covariance constraints are not compatible with any other type of constraint, including box constraints. You don't have to add box constraints to keep the variances positive because estimagic does this for you.\n",
    "\n",
    "Some optimizers are more aggressive than others and test more extreme parameters. This is especially bad for variance-covariance matrices because they have to be positive semi-definite which might not be the case for every proposed parameterization. Internally, estimagic uses the Cholesky factor $C$, a lower-triangular matrix, of the variance-covariance matrix to do unconstrained optimization and rebuild the variance-covariance with $\\Omega = C C^T$. To ensure positive semi-definiteness, you can add ``{\"bounds_distance\": 1e-6}`` to your constraint to ensure that the diagonal elements of the Cholesky factor are farther away from zero. The complete constraint with distance to the bounds is"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "constraints = [{\n",
    "    \"loc\": \"shocks_cov\", \n",
    "    \"type\": \"covariance\",\n",
    "    \"bounds_distance\": 1e-6\n",
    "}]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## sdcorr Constraints\n",
    "\n",
    "Most of the time, it is more intuitive to look at standard deviations and correlations than at covariance matrices. If this is the case, you want to use an ``\"sdcorr\"`` constraint instead of the ``\"covariance\"`` constraint. The sdcorr constraint assumes that that the first elements are standard deviations and the rest is the lower triangle (excluding the diagonal) of a correlation matrix. Again, the names in the index are ignored by estimagic. \n",
    "\n",
    "Let's look at the same example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th>value</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>category</th>\n",
       "      <th>name</th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>delta</th>\n",
       "      <th>delta</th>\n",
       "      <td>0.950000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th rowspan=\"2\" valign=\"top\">wage_fishing</th>\n",
       "      <th>exp_fishing</th>\n",
       "      <td>0.100000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>contemplation_with_friday</th>\n",
       "      <td>0.400000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>nonpec_fishing</th>\n",
       "      <th>constant</th>\n",
       "      <td>-1.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th rowspan=\"2\" valign=\"top\">nonpec_friday</th>\n",
       "      <th>constant</th>\n",
       "      <td>-1.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>not_fishing_last_period</th>\n",
       "      <td>-1.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th rowspan=\"2\" valign=\"top\">nonpec_hammock</th>\n",
       "      <th>constant</th>\n",
       "      <td>2.500000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>not_fishing_last_period</th>\n",
       "      <td>-1.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th rowspan=\"6\" valign=\"top\">shocks_sdcorr</th>\n",
       "      <th>sd_fishing</th>\n",
       "      <td>1.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>sd_friday</th>\n",
       "      <td>1.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>sd_hammock</th>\n",
       "      <td>1.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>corr_friday_fishing</th>\n",
       "      <td>0.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>corr_hammock_fishing</th>\n",
       "      <td>-0.200000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>corr_hammock_friday</th>\n",
       "      <td>0.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>lagged_choice_1_hammock</th>\n",
       "      <th>constant</th>\n",
       "      <td>1.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>meas_error</th>\n",
       "      <th>sd_fishing</th>\n",
       "      <td>0.000001</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                                      value\n",
       "category                name                               \n",
       "delta                   delta                      0.950000\n",
       "wage_fishing            exp_fishing                0.100000\n",
       "                        contemplation_with_friday  0.400000\n",
       "nonpec_fishing          constant                  -1.000000\n",
       "nonpec_friday           constant                  -1.000000\n",
       "                        not_fishing_last_period   -1.000000\n",
       "nonpec_hammock          constant                   2.500000\n",
       "                        not_fishing_last_period   -1.000000\n",
       "shocks_sdcorr           sd_fishing                 1.000000\n",
       "                        sd_friday                  1.000000\n",
       "                        sd_hammock                 1.000000\n",
       "                        corr_friday_fishing        0.000000\n",
       "                        corr_hammock_fishing      -0.200000\n",
       "                        corr_hammock_friday        0.000000\n",
       "lagged_choice_1_hammock constant                   1.000000\n",
       "meas_error              sd_fishing                 0.000001"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "params = pd.read_csv(\"robinson-crusoe-sdcorr.csv\")\n",
    "params.set_index([\"category\", \"name\"], inplace=True)\n",
    "params"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The constraint is then just:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "constraints = [{\"loc\": \"shocks_sdcorr\", \"type\": \"sdcorr\"}]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And, of course, there is another helper function in the utilities module:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "from estimagic.optimization.utilities import sdcorr_params_to_sds_and_corr"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([1., 1., 1.])"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sds, corr = sdcorr_params_to_sds_and_corr(\n",
    "    params.loc[\"shocks_sdcorr\", \"value\"])\n",
    "sds"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 1. ,  0. , -0.2],\n",
       "       [ 0. ,  1. ,  0. ],\n",
       "       [-0.2,  0. ,  1. ]])"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "corr"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the ``\"bounds_distance\"`` option is also available for ``\"sdcorr\"`` constraints. See the previous section on covariance constraints for more information.\n",
    "\n",
    "## linear constraints\n",
    "\n",
    "\"linear\" constraints have many of the above constraints as special cases. They are a bit more complicated to write but can be very powerful. You should only write a linear constraint if your constraint can't be expressed as one of the special cases. \n",
    "\n",
    "They can be used to express constraints of the form:\n",
    "\n",
    "```ipython\n",
    "    lower <=  weights.dot(x) <= upper\n",
    "```\n",
    "or\n",
    "```ipython\n",
    "    weights.dot(x) = value\n",
    "```\n",
    ", where `x` are the selected parameters. \n",
    "\n",
    "Linear constraints have the following additional fields beside the `loc` or `query` and `type` field:\n",
    "\n",
    "- weights: This will be used to construct the vector `a`. It can be a numpy array, pandas Series, list or a float in which case the weigths for all selected parameters are equal to that number.\n",
    "- value: float\n",
    "- lower: float\n",
    "- upper: float\n",
    "\n",
    "You can specify either value or lower and upper bounds. Suppose you have the following params DataFrame:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th>value</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th rowspan=\"3\" valign=\"top\">a</th>\n",
       "      <th>0</th>\n",
       "      <td>2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th rowspan=\"3\" valign=\"top\">b</th>\n",
       "      <th>0</th>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>3</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>4</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th rowspan=\"3\" valign=\"top\">c</th>\n",
       "      <th>0</th>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "     value\n",
       "a 0      2\n",
       "  1      1\n",
       "  2      0\n",
       "b 0      1\n",
       "  1      3\n",
       "  2      4\n",
       "c 0      1\n",
       "  1      1\n",
       "  2      1"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "params = pd.DataFrame(\n",
    "    index=pd.MultiIndex.from_product([[\"a\", \"b\", \"c\"], [0, 1, 2]]), \n",
    "    data=[[2], [1], [0], [1], [3], [4], [1], [1], [1]],\n",
    "    columns=[\"value\"]\n",
    ")\n",
    "params"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Suppose you want to express the following constraints:\n",
    "\n",
    "1. The first parameter in the a category is two times the second parameter in that category.\n",
    "2. The mean of the b parameters is larger than 3\n",
    "3. The sum of the last three parameters is between 0 and 5\n",
    "\n",
    "Then the constraints would look as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [],
   "source": [
    "constraints = [\n",
    "    {\"loc\": \"a\", \"type\": \"linear\", \"weights\": [1, -2, 0], \"value\": 0},\n",
    "    {\"loc\": \"b\", \"type\": \"linear\", \"weights\": 1 / 3, \"lower\": 3},\n",
    "    {\"loc\": \"c\", \"type\": \"linear\", \"weights\": 1, \"lower\": 0, \"upper\": 5},\n",
    "]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Constraint killers\n",
    "\n",
    "All constraints can have an additional key called \"id\". An example could be:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "constraints = [\n",
    "    {\"loc\": \"a\", \"type\": \"equality\", \"id\": 0},\n",
    "    {\"loc\": \"b\", \"type\": \"increasing\", \"id\": 1}\n",
    "]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In structural economic models, the list of constraints can become quite large and cumbersome to write. Therefore, packages that implement such models will often write the constraints for you and only allow you to complement them with additional user constraints. But what if you want to relax some of the constraints they implement automatically? For this we have constraint killers. They take the following form:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [],
   "source": [
    "killer = {\"kill\": 0}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example, the following two lists of constraints will be equivalent:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [],
   "source": [
    "constraints1 = [\n",
    "    {\"loc\": \"a\", \"type\": \"equality\", \"id\": 0}, \n",
    "    {\"loc\": \"b\", \"type\": \"increasing\", \"id\": 1},\n",
    "    {\"kill\": 0}\n",
    "]\n",
    "constraints2 = [{\"loc\": \"b\", \"type\": \"increasing\", \"id\": 1}]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you write a package that implements constraints for the user, the following are best practices:\n",
    "\n",
    "1. Give the user the chance to add additional constraints.\n",
    "2. Add \"id\" entries to all constraints.\n",
    "3. Give the user the possibility to look at the constraints that were constructed automatically."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}