docs/intro.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# ParamTools\n",
    "\n",
    "**Define, update, and validate your model's parameters.**\n",
    "\n",
    "Install using pip:\n",
    "\n",
    "```\n",
    "pip install paramtools\n",
    "```\n",
    "\n",
    "Install using conda:\n",
    "\n",
    "```\n",
    "conda install -c conda-forge paramtools\n",
    "```\n",
    "\n",
    "\n",
    "## Usage\n",
    "\n",
    "Subclass `paramtools.Parameters` and define your model's [parameters](https://paramtools.dev/parameters):\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import paramtools\n",
    "\n",
    "\n",
    "class Params(paramtools.Parameters):\n",
    "    defaults = {\n",
    "        \"schema\": {\n",
    "            \"labels\": {\n",
    "                \"date\": {\n",
    "                    \"type\": \"date\",\n",
    "                    \"validators\": {\n",
    "                        \"range\": {\n",
    "                            \"min\": \"2020-01-01\",\n",
    "                            \"max\": \"2021-01-01\",\n",
    "                            \"step\": {\"months\": 1}\n",
    "                        }\n",
    "                    }\n",
    "                }\n",
    "            },\n",
    "        },\n",
    "        \"a\": {\n",
    "            \"title\": \"A\",\n",
    "            \"type\": \"int\",\n",
    "            \"value\": [\n",
    "                {\"date\": \"2020-01-01\", \"value\": 2},\n",
    "                {\"date\": \"2020-10-01\", \"value\": 8},\n",
    "            ],\n",
    "            \"validators\": {\n",
    "                \"range\" : {\n",
    "                    \"min\": 0, \"max\": \"b\"\n",
    "                }\n",
    "            }\n",
    "        },\n",
    "        \"b\": {\n",
    "            \"title\": \"B\",\n",
    "            \"type\": \"float\",\n",
    "            \"value\": [{\"date\": \"2020-01-01\", \"value\": 10.5}]\n",
    "        }\n",
    "    }"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Access parameter values\n",
    "\n",
    "Access values using `.sel`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Values([\n",
       "  {'date': datetime.date(2020, 1, 1), 'value': 2},\n",
       "  {'date': datetime.date(2020, 10, 1), 'value': 8},\n",
       "])"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "params = Params()\n",
    "\n",
    "params.sel[\"a\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Look up parameter values using a pandas-like api:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "QueryResult([\n",
       "  {'date': datetime.date(2020, 1, 1), 'value': 2}\n",
       "])"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from datetime import date\n",
    "\n",
    "result = params.sel[\"a\"][\"date\"] == date(2020, 1, 1)\n",
    "result"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "result.isel[0][\"value\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Adjust and validate parameter values\n",
    "\n",
    "Add a new value:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Values([\n",
       "  {'date': datetime.date(2020, 1, 1), 'value': 2},\n",
       "  {'date': datetime.date(2020, 10, 1), 'value': 8},\n",
       "  {'date': datetime.date(2020, 11, 1), 'value': 22},\n",
       "])"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "params.adjust({\"a\": [{\"date\": \"2020-11-01\", \"value\": 22}]})\n",
    "\n",
    "params.sel[\"a\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Update an existing value:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Values([\n",
       "  {'date': datetime.date(2020, 1, 1), 'value': 3},\n",
       "  {'date': datetime.date(2020, 10, 1), 'value': 8},\n",
       "  {'date': datetime.date(2020, 11, 1), 'value': 22},\n",
       "])"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "params.adjust({\"a\": [{\"date\": \"2020-01-01\", \"value\": 3}]})\n",
    "\n",
    "params.sel[\"a\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Update all values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Values([\n",
       "  {'date': datetime.date(2020, 1, 1), 'value': 7},\n",
       "  {'date': datetime.date(2020, 10, 1), 'value': 7},\n",
       "  {'date': datetime.date(2020, 11, 1), 'value': 7},\n",
       "])"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "params.adjust({\"a\": 7})\n",
    "\n",
    "params.sel[\"a\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Errors on values that are out of range:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "ename": "ValidationError",
     "evalue": "{\n    \"errors\": {\n        \"a\": [\n            \"a -1 < min 0 \"\n        ]\n    }\n}",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mValidationError\u001b[0m                           Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-9-f8f1b7f6cd9a>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0mparams\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0madjust\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m{\u001b[0m\u001b[0;34m\"a\"\u001b[0m\u001b[0;34m:\u001b[0m \u001b[0;34m-\u001b[0m\u001b[0;36m1\u001b[0m\u001b[0;34m}\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;32m~/Paramtools/paramtools/parameters.py\u001b[0m in \u001b[0;36madjust\u001b[0;34m(self, params_or_path, ignore_warnings, raise_errors, extend_adj, clobber)\u001b[0m\n\u001b[1;32m    253\u001b[0m             \u001b[0mleast\u001b[0m \u001b[0mone\u001b[0m \u001b[0mexisting\u001b[0m \u001b[0mvalue\u001b[0m \u001b[0mitem\u001b[0m\u001b[0;31m'\u001b[0m\u001b[0ms\u001b[0m \u001b[0mcorresponding\u001b[0m \u001b[0mlabel\u001b[0m \u001b[0mvalues\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    254\u001b[0m         \"\"\"\n\u001b[0;32m--> 255\u001b[0;31m         return self._adjust(\n\u001b[0m\u001b[1;32m    256\u001b[0m             \u001b[0mparams_or_path\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    257\u001b[0m             \u001b[0mignore_warnings\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mignore_warnings\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;32m~/Paramtools/paramtools/parameters.py\u001b[0m in \u001b[0;36m_adjust\u001b[0;34m(self, params_or_path, ignore_warnings, raise_errors, extend_adj, is_deserialized, clobber)\u001b[0m\n\u001b[1;32m    371\u001b[0m             \u001b[0;32mnot\u001b[0m \u001b[0mignore_warnings\u001b[0m \u001b[0;32mand\u001b[0m \u001b[0mhas_warnings\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    372\u001b[0m         ):\n\u001b[0;32m--> 373\u001b[0;31m             \u001b[0;32mraise\u001b[0m \u001b[0mself\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mvalidation_error\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m    374\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    375\u001b[0m         \u001b[0;31m# Update attrs for params that were adjusted.\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;31mValidationError\u001b[0m: {\n    \"errors\": {\n        \"a\": [\n            \"a -1 < min 0 \"\n        ]\n    }\n}"
     ]
    }
   ],
   "source": [
    "params.adjust({\"a\": -1})"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "ename": "ValidationError",
     "evalue": "{\n    \"errors\": {\n        \"a\": [\n            \"a[date=2020-01-01] 11 > max 10.5 b[date=2020-01-01]\"\n        ]\n    }\n}",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mValidationError\u001b[0m                           Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-10-cc8a21f044d8>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m\n\u001b[1;32m      1\u001b[0m \u001b[0mparams\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mParams\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      2\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 3\u001b[0;31m \u001b[0mparams\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0madjust\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m{\u001b[0m\u001b[0;34m\"a\"\u001b[0m\u001b[0;34m:\u001b[0m \u001b[0;34m[\u001b[0m\u001b[0;34m{\u001b[0m\u001b[0;34m\"date\"\u001b[0m\u001b[0;34m:\u001b[0m \u001b[0;34m\"2020-01-01\"\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m\"value\"\u001b[0m\u001b[0;34m:\u001b[0m \u001b[0;36m11\u001b[0m\u001b[0;34m}\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m}\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;32m~/Paramtools/paramtools/parameters.py\u001b[0m in \u001b[0;36madjust\u001b[0;34m(self, params_or_path, ignore_warnings, raise_errors, extend_adj, clobber)\u001b[0m\n\u001b[1;32m    253\u001b[0m             \u001b[0mleast\u001b[0m \u001b[0mone\u001b[0m \u001b[0mexisting\u001b[0m \u001b[0mvalue\u001b[0m \u001b[0mitem\u001b[0m\u001b[0;31m'\u001b[0m\u001b[0ms\u001b[0m \u001b[0mcorresponding\u001b[0m \u001b[0mlabel\u001b[0m \u001b[0mvalues\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    254\u001b[0m         \"\"\"\n\u001b[0;32m--> 255\u001b[0;31m         return self._adjust(\n\u001b[0m\u001b[1;32m    256\u001b[0m             \u001b[0mparams_or_path\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    257\u001b[0m             \u001b[0mignore_warnings\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mignore_warnings\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;32m~/Paramtools/paramtools/parameters.py\u001b[0m in \u001b[0;36m_adjust\u001b[0;34m(self, params_or_path, ignore_warnings, raise_errors, extend_adj, is_deserialized, clobber)\u001b[0m\n\u001b[1;32m    371\u001b[0m             \u001b[0;32mnot\u001b[0m \u001b[0mignore_warnings\u001b[0m \u001b[0;32mand\u001b[0m \u001b[0mhas_warnings\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    372\u001b[0m         ):\n\u001b[0;32m--> 373\u001b[0;31m             \u001b[0;32mraise\u001b[0m \u001b[0mself\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mvalidation_error\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m    374\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    375\u001b[0m         \u001b[0;31m# Update attrs for params that were adjusted.\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;31mValidationError\u001b[0m: {\n    \"errors\": {\n        \"a\": [\n            \"a[date=2020-01-01] 11 > max 10.5 b[date=2020-01-01]\"\n        ]\n    }\n}"
     ]
    }
   ],
   "source": [
    "params = Params()\n",
    "\n",
    "params.adjust({\"a\": [{\"date\": \"2020-01-01\", \"value\": 11}]})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Errors on invalid values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "ename": "ValidationError",
     "evalue": "{\n    \"errors\": {\n        \"b\": [\n            \"Not a valid number: abc.\"\n        ]\n    }\n}",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mValidationError\u001b[0m                           Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-11-8373a2715e38>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m\n\u001b[1;32m      1\u001b[0m \u001b[0mparams\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mParams\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      2\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 3\u001b[0;31m \u001b[0mparams\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0madjust\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m{\u001b[0m\u001b[0;34m\"b\"\u001b[0m\u001b[0;34m:\u001b[0m \u001b[0;34m\"abc\"\u001b[0m\u001b[0;34m}\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;32m~/Paramtools/paramtools/parameters.py\u001b[0m in \u001b[0;36madjust\u001b[0;34m(self, params_or_path, ignore_warnings, raise_errors, extend_adj, clobber)\u001b[0m\n\u001b[1;32m    253\u001b[0m             \u001b[0mleast\u001b[0m \u001b[0mone\u001b[0m \u001b[0mexisting\u001b[0m \u001b[0mvalue\u001b[0m \u001b[0mitem\u001b[0m\u001b[0;31m'\u001b[0m\u001b[0ms\u001b[0m \u001b[0mcorresponding\u001b[0m \u001b[0mlabel\u001b[0m \u001b[0mvalues\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    254\u001b[0m         \"\"\"\n\u001b[0;32m--> 255\u001b[0;31m         return self._adjust(\n\u001b[0m\u001b[1;32m    256\u001b[0m             \u001b[0mparams_or_path\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    257\u001b[0m             \u001b[0mignore_warnings\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mignore_warnings\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;32m~/Paramtools/paramtools/parameters.py\u001b[0m in \u001b[0;36m_adjust\u001b[0;34m(self, params_or_path, ignore_warnings, raise_errors, extend_adj, is_deserialized, clobber)\u001b[0m\n\u001b[1;32m    371\u001b[0m             \u001b[0;32mnot\u001b[0m \u001b[0mignore_warnings\u001b[0m \u001b[0;32mand\u001b[0m \u001b[0mhas_warnings\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    372\u001b[0m         ):\n\u001b[0;32m--> 373\u001b[0;31m             \u001b[0;32mraise\u001b[0m \u001b[0mself\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mvalidation_error\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m    374\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    375\u001b[0m         \u001b[0;31m# Update attrs for params that were adjusted.\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;31mValidationError\u001b[0m: {\n    \"errors\": {\n        \"b\": [\n            \"Not a valid number: abc.\"\n        ]\n    }\n}"
     ]
    }
   ],
   "source": [
    "params = Params()\n",
    "\n",
    "params.adjust({\"b\": \"abc\"})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Extend parameter values using label definitions\n",
    "\n",
    "Extend values using `label_to_extend`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = Params(label_to_extend=\"date\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Values([\n",
       "  {'date': datetime.date(2020, 1, 1), 'value': 2},\n",
       "  {'date': datetime.date(2020, 2, 1), 'value': 2, '_auto': True},\n",
       "  {'date': datetime.date(2020, 3, 1), 'value': 2, '_auto': True},\n",
       "  {'date': datetime.date(2020, 4, 1), 'value': 2, '_auto': True},\n",
       "  {'date': datetime.date(2020, 5, 1), 'value': 2, '_auto': True},\n",
       "  {'date': datetime.date(2020, 6, 1), 'value': 2, '_auto': True},\n",
       "  {'date': datetime.date(2020, 7, 1), 'value': 2, '_auto': True},\n",
       "  {'date': datetime.date(2020, 8, 1), 'value': 2, '_auto': True},\n",
       "  {'date': datetime.date(2020, 9, 1), 'value': 2, '_auto': True},\n",
       "  {'date': datetime.date(2020, 10, 1), 'value': 8},\n",
       "  {'date': datetime.date(2020, 11, 1), 'value': 8, '_auto': True},\n",
       "  {'date': datetime.date(2020, 12, 1), 'value': 8, '_auto': True},\n",
       "  {'date': datetime.date(2021, 1, 1), 'value': 8, '_auto': True},\n",
       "])"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "params.sel[\"a\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Updates to values are carried through to future dates:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Values([\n",
       "  {'date': datetime.date(2020, 1, 1), 'value': 2},\n",
       "  {'date': datetime.date(2020, 2, 1), 'value': 2, '_auto': True},\n",
       "  {'date': datetime.date(2020, 3, 1), 'value': 2, '_auto': True},\n",
       "  {'date': datetime.date(2020, 4, 1), 'value': 9},\n",
       "  {'date': datetime.date(2020, 5, 1), 'value': 9, '_auto': True},\n",
       "  {'date': datetime.date(2020, 6, 1), 'value': 9, '_auto': True},\n",
       "  {'date': datetime.date(2020, 7, 1), 'value': 9, '_auto': True},\n",
       "  {'date': datetime.date(2020, 8, 1), 'value': 9, '_auto': True},\n",
       "  {'date': datetime.date(2020, 9, 1), 'value': 9, '_auto': True},\n",
       "  {'date': datetime.date(2020, 10, 1), 'value': 9, '_auto': True},\n",
       "  {'date': datetime.date(2020, 11, 1), 'value': 9, '_auto': True},\n",
       "  {'date': datetime.date(2020, 12, 1), 'value': 9, '_auto': True},\n",
       "  {'date': datetime.date(2021, 1, 1), 'value': 9, '_auto': True},\n",
       "])"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "params.adjust({\"a\": [{\"date\": \"2020-4-01\", \"value\": 9}]})\n",
    "\n",
    "params.sel[\"a\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Use `clobber` to only update values that were set automatically:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Values([\n",
       "  {'date': datetime.date(2020, 1, 1), 'value': 2},\n",
       "  {'date': datetime.date(2020, 2, 1), 'value': 2, '_auto': True},\n",
       "  {'date': datetime.date(2020, 3, 1), 'value': 2, '_auto': True},\n",
       "  {'date': datetime.date(2020, 4, 1), 'value': 9},\n",
       "  {'date': datetime.date(2020, 5, 1), 'value': 9, '_auto': True},\n",
       "  {'date': datetime.date(2020, 6, 1), 'value': 9, '_auto': True},\n",
       "  {'date': datetime.date(2020, 7, 1), 'value': 9, '_auto': True},\n",
       "  {'date': datetime.date(2020, 8, 1), 'value': 9, '_auto': True},\n",
       "  {'date': datetime.date(2020, 9, 1), 'value': 9, '_auto': True},\n",
       "  {'date': datetime.date(2020, 10, 1), 'value': 8},\n",
       "  {'date': datetime.date(2020, 11, 1), 'value': 8, '_auto': True},\n",
       "  {'date': datetime.date(2020, 12, 1), 'value': 8, '_auto': True},\n",
       "  {'date': datetime.date(2021, 1, 1), 'value': 8, '_auto': True},\n",
       "])"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "params = Params(label_to_extend=\"date\")\n",
    "params.adjust(\n",
    "    {\"a\": [{\"date\": \"2020-4-01\", \"value\": 9}]},\n",
    "    clobber=False,\n",
    ")\n",
    "\n",
    "# Sort parameter values by date for nicer output\n",
    "params.sort_values()\n",
    "params.sel[\"a\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### NumPy integration\n",
    "\n",
    "Access values as NumPy arrays with `array_first`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([2, 2, 2, 2, 2, 2, 2, 2, 2, 8, 8, 8, 8])"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "params = Params(label_to_extend=\"date\", array_first=True)\n",
    "\n",
    "params.a"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([21., 21., 21., 21., 21., 21., 21., 21., 21., 84., 84., 84., 84.])"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "params.a * params.b"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Only get the values that you want:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([2, 8])"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "arr = params.to_array(\"a\", date=[\"2020-01-01\", \"2020-11-01\"])\n",
    "arr"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Go back to a list of dictionaries:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'date': datetime.date(2020, 1, 1), 'value': 2},\n",
       " {'date': datetime.date(2020, 11, 1), 'value': 8}]"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "params.from_array(\"a\", arr, date=[\"2020-01-01\", \"2020-11-01\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Documentation\n",
    "----------------\n",
    "Full documentation available at [paramtools.dev](https://paramtools.dev).\n",
    "\n",
    "Contributing\n",
    "-------------------------\n",
    "Contributions are welcome! Checkout [CONTRIBUTING.md][3] to get started.\n",
    "\n",
    "Credits\n",
    "---------\n",
    "ParamTools is built on top of the excellent [marshmallow][1] JSON schema and validation framework. I encourage everyone to check out their repo and documentation. ParamTools was modeled off of [Tax-Calculator's][2] parameter processing and validation engine due to its maturity and sophisticated capabilities.\n",
    "\n",
    "[1]: https://github.com/marshmallow-code/marshmallow\n",
    "[2]: https://github.com/PSLmodels/Tax-Calculator\n",
    "[3]: https://github.com/PSLmodels/ParamTools/blob/master/CONTRIBUTING.md\n"
   ]
  }
 ],
 "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.8.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}