Update docs

Author: nikhilwoodruff

.gitignore

@@ -161,4 +161,4 @@ cython_debug/
 
 *.ipynb
 
-old/
+!docs/**/*.ipynb

docs/index.ipynb

@@ -0,0 +1,81 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# PolicyEngine Python interface\n",
+    "\n",
+    "Welcome to the documentation for PolicyEngine, a Python package for analyzing tax-benefit policies and estimating their societal impacts.\n",
+    "\n",
+    "## Overview\n",
+    "\n",
+    "This package enables users to create and simulate different scenarios of specific or representative households in a country, under different tax-benefit rules or economic assumptions.\n",
+    "\n",
+    "We currently support the UK and the US.\n",
+    "\n",
+    "## Quick start\n",
+    "\n",
+    "To install the package, run:\n",
+    "\n",
+    "```bash\n",
+    "pip install policyengine\n",
+    "```\n",
+    "\n",
+    "Then, for example:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "EconomyComparison(fiscal=FiscalComparison(baseline=FiscalSummary(tax_revenue=658911285719.5891, federal_tax=658911285719.5891, state_tax=0.0, government_spending=349760026840.3932, tax_benefit_programs={'income_tax': 333376287037.05945, 'national_insurance': 52985626776.773834, 'ni_employer': 126330649370.35953, 'vat': 211671832822.39133, 'council_tax': 49007055050.00724, 'fuel_duty': 26506672341.204205, 'tax_credits': -34929879.49872104, 'universal_credit': -73459549194.97665, 'child_benefit': -14311471487.935827, 'state_pension': -132795868621.44594, 'pension_credit': -6252358021.417119}, household_net_income=1566030461192.7288), reform=FiscalSummary(tax_revenue=637686731286.3723, federal_tax=637686731286.3723, state_tax=0.0, government_spending=349224353712.28815, tax_benefit_programs={'income_tax': 312151564998.6612, 'national_insurance': 52985626776.773834, 'ni_employer': 126330649370.35953, 'vat': 211671832822.39133, 'council_tax': 49007055050.00724, 'fuel_duty': 26506672341.204205, 'tax_credits': -34929879.49872104, 'universal_credit': -73099552696.20555, 'child_benefit': -14311471487.935827, 'state_pension': -132795868621.44594, 'pension_credit': -6181432287.167828}, household_net_income=1586719205744.2463), change=FiscalSummary(tax_revenue=-21224554433.216797, federal_tax=-21224554433.216797, state_tax=0.0, government_spending=-535673128.1050415, tax_benefit_programs={'income_tax': -21224722038.398254, 'national_insurance': 0.0, 'ni_employer': 0.0, 'vat': 0.0, 'council_tax': 0.0, 'fuel_duty': 0.0, 'tax_credits': 0.0, 'universal_credit': 359996498.7711029, 'child_benefit': 0.0, 'state_pension': 0.0, 'pension_credit': 70925734.24929142}, household_net_income=20688744551.51758), relative_change=FiscalSummary(tax_revenue=-0.03221155092227281, federal_tax=-0.03221155092227281, state_tax=0.0, government_spending=-0.0015315447363843167, tax_benefit_programs={'income_tax': -0.06366596204858095, 'national_insurance': 0.0, 'ni_employer': 0.0, 'vat': 0.0, 'council_tax': 0.0, 'fuel_duty': 0.0, 'tax_credits': -0.0, 'universal_credit': -0.004900608603186478, 'child_benefit': -0.0, 'state_pension': -0.0, 'pension_credit': -0.01134383763795021}, household_net_income=0.013210946443379206)), inequality=InequalityComparison(baseline=InequalitySummary(gini=0.36255338125570424, top_10_share=0.3260922885079385, top_1_share=0.1314559726417293), reform=InequalitySummary(gini=0.3621067195625373, top_10_share=0.3247068529020242, top_1_share=0.13003247918783417), change=InequalitySummary(gini=-0.0004466616931669276, top_10_share=-0.0013854356059142536, top_1_share=-0.0014234934538951416), relative_change=InequalitySummary(gini=-0.001231988767060768, top_10_share=-0.004248599720813472, top_1_share=-0.010828670811137177)), distributional=DecileImpacts(income=IncomeMeasureSpecificDecileImpacts(income_change=IncomeMeasureSpecificDecileIncomeChange(relative={1: 0.006888347426579352, 2: 0.01207019625644219, 3: 0.013627468842833087, 4: 0.016100481654779814, 5: 0.013748247907171681, 6: 0.01686883037766935, 7: 0.01753355131276628, 8: 0.016653942719361867, 9: 0.01676805576642017, 10: 0.007412181202749425}, average={1: 104.97431830321577, 2: 345.37333460917273, 3: 505.9344918602069, 4: 693.5160756480564, 5: 633.0329182433123, 6: 916.7939753239693, 7: 1160.9595929383368, 8: 1339.97187253835, 9: 1645.9437072259466, 10: 1555.8434910392261}), winners_and_losers=IncomeMeasureSpecificDecileWinnersLosers(deciles={1: IncomeMeasureSpecificDecileWinnersLosersGroupOutcomes(lose_more_than_5_percent_share=0.0, lose_less_than_5_percent_share=0.0001755859570557263, lose_share=0.0001682513537722099, no_change_share=0.7777594280562966, gain_share=0.22207232058993112, gain_less_than_5_percent_share=0.8921554326814847, gain_more_than_5_percent_share=0.1076689813614596), 2: IncomeMeasureSpecificDecileWinnersLosersGroupOutcomes(lose_more_than_5_percent_share=0.0, lose_less_than_5_percent_share=0.008308201427960779, lose_share=0.008308201427960779, no_change_share=0.3296747315922954, gain_share=0.6620170669797438, gain_less_than_5_percent_share=0.8919232634243426, gain_more_than_5_percent_share=0.09976853514769665), 3: IncomeMeasureSpecificDecileWinnersLosersGroupOutcomes(lose_more_than_5_percent_share=0.0, lose_less_than_5_percent_share=0.0025640225401700836, lose_share=7.961082321261601e-05, no_change_share=0.24144297964047653, gain_share=0.7584774095363108, gain_less_than_5_percent_share=0.8374155175602881, gain_more_than_5_percent_share=0.1600204598995418), 4: IncomeMeasureSpecificDecileWinnersLosersGroupOutcomes(lose_more_than_5_percent_share=0.0, lose_less_than_5_percent_share=0.0, lose_share=0.0, no_change_share=0.12752277174703963, gain_share=0.8724772282529604, gain_less_than_5_percent_share=0.9665865451338477, gain_more_than_5_percent_share=0.03341345486615228), 5: IncomeMeasureSpecificDecileWinnersLosersGroupOutcomes(lose_more_than_5_percent_share=0.0, lose_less_than_5_percent_share=0.0, lose_share=0.0, no_change_share=0.03956658976737942, gain_share=0.9604334102326206, gain_less_than_5_percent_share=0.9972436631437993, gain_more_than_5_percent_share=0.0027563368562006983), 6: IncomeMeasureSpecificDecileWinnersLosersGroupOutcomes(lose_more_than_5_percent_share=0.0, lose_less_than_5_percent_share=9.23312947542871e-08, lose_share=0.0, no_change_share=0.04739185313495122, gain_share=0.9526081468650488, gain_less_than_5_percent_share=0.950097303756789, gain_more_than_5_percent_share=0.04990260391191623), 7: IncomeMeasureSpecificDecileWinnersLosersGroupOutcomes(lose_more_than_5_percent_share=0.0, lose_less_than_5_percent_share=5.104037721866914e-07, lose_share=5.104037721866914e-07, no_change_share=0.018556113733354175, gain_share=0.9814433758628737, gain_less_than_5_percent_share=0.9532747831120698, gain_more_than_5_percent_share=0.046724706484157955), 8: IncomeMeasureSpecificDecileWinnersLosersGroupOutcomes(lose_more_than_5_percent_share=0.0, lose_less_than_5_percent_share=0.0, lose_share=0.0, no_change_share=0.0078485273494483, gain_share=0.9921514726505517, gain_less_than_5_percent_share=0.9864864572885578, gain_more_than_5_percent_share=0.013513542711442263), 9: IncomeMeasureSpecificDecileWinnersLosersGroupOutcomes(lose_more_than_5_percent_share=0.0, lose_less_than_5_percent_share=3.9720293329414453e-08, lose_share=0.0, no_change_share=0.015484773300234851, gain_share=0.9845152266997651, gain_less_than_5_percent_share=0.9942833742036897, gain_more_than_5_percent_share=0.00571658607601697), 10: IncomeMeasureSpecificDecileWinnersLosersGroupOutcomes(lose_more_than_5_percent_share=0.0, lose_less_than_5_percent_share=0.0, lose_share=0.0, no_change_share=0.09527409658848911, gain_share=0.9047259034115109, gain_less_than_5_percent_share=1.0, gain_more_than_5_percent_share=0.0)}, all=IncomeMeasureSpecificDecileWinnersLosersGroupOutcomes(lose_more_than_5_percent_share=0.0, lose_less_than_5_percent_share=0.0010924738666159373, lose_share=0.0008384108829899095, no_change_share=0.16458777279036807, gain_share=0.8345738163266421, gain_less_than_5_percent_share=0.947301858492644, gain_more_than_5_percent_share=0.051605667640740344))), wealth=IncomeMeasureSpecificDecileImpacts(income_change=IncomeMeasureSpecificDecileIncomeChange(relative={1: 0.008709359540639157, 2: 0.00905578708175186, 3: 0.012492298883059996, 4: 0.01152604162555258, 5: 0.013211680341905644, 6: 0.015499276808714067, 7: 0.015075628657318645, 8: 0.013872537910746014, 9: 0.014863082577873714, 10: 0.013423194473756452}, average={1: 369.702952145763, 2: 348.23782779938443, 3: 552.8656647582718, 4: 568.6862981673706, 5: 788.7199254212952, 6: 1082.0251273410129, 7: 995.5414649462065, 8: 980.0256472731063, 9: 1104.9136440223838, 10: 1148.3564641697874}), winners_and_losers=IncomeMeasureSpecificDecileWinnersLosers(deciles={1: IncomeMeasureSpecificDecileWinnersLosersGroupOutcomes(lose_more_than_5_percent_share=0.0, lose_less_than_5_percent_share=2.6883274101429057e-05, lose_share=2.6883274101429057e-05, no_change_share=0.4508804429091072, gain_share=0.5490926738167914, gain_less_than_5_percent_share=0.9848507184309168, gain_more_than_5_percent_share=0.015122398294981835), 2: IncomeMeasureSpecificDecileWinnersLosersGroupOutcomes(lose_more_than_5_percent_share=0.0, lose_less_than_5_percent_share=3.6190041582250956e-08, lose_share=0.0, no_change_share=0.494450094962446, gain_share=0.505549905037554, gain_less_than_5_percent_share=0.9931537493063021, gain_more_than_5_percent_share=0.006846214503656335), 3: IncomeMeasureSpecificDecileWinnersLosersGroupOutcomes(lose_more_than_5_percent_share=0.0, lose_less_than_5_percent_share=0.0, lose_share=0.0, no_change_share=0.02404055636315165, gain_share=0.9759594436368484, gain_less_than_5_percent_share=0.9891467785172058, gain_more_than_5_percent_share=0.010853221482794195), 4: IncomeMeasureSpecificDecileWinnersLosersGroupOutcomes(lose_more_than_5_percent_share=0.0, lose_less_than_5_percent_share=0.0021384901223377517, lose_share=8.272884193213454e-07, no_change_share=0.36369619644130957, gain_share=0.6363029762702711, gain_less_than_5_percent_share=0.9597482462129343, gain_more_than_5_percent_share=0.038113263664727975), 5: IncomeMeasureSpecificDecileWinnersLosersGroupOutcomes(lose_more_than_5_percent_share=0.0, lose_less_than_5_percent_share=0.0002447588006939626, lose_share=0.00024460254119754784, no_change_share=0.16613074345434808, gain_share=0.8336246540044544, gain_less_than_5_percent_share=0.9833489364919241, gain_more_than_5_percent_share=0.01640630470738194), 6: IncomeMeasureSpecificDecileWinnersLosersGroupOutcomes(lose_more_than_5_percent_share=0.0, lose_less_than_5_percent_share=0.0, lose_share=0.0, no_change_share=0.025790631489697343, gain_share=0.9742093685103027, gain_less_than_5_percent_share=0.9861761877807416, gain_more_than_5_percent_share=0.013823812219258384), 7: IncomeMeasureSpecificDecileWinnersLosersGroupOutcomes(lose_more_than_5_percent_share=0.0, lose_less_than_5_percent_share=0.00020866319896562508, lose_share=4.163438722119544e-05, no_change_share=0.08407934672412146, gain_share=0.9158790188886573, gain_less_than_5_percent_share=0.9021123857304735, gain_more_than_5_percent_share=0.09767895107056095), 8: IncomeMeasureSpecificDecileWinnersLosersGroupOutcomes(lose_more_than_5_percent_share=0.0, lose_less_than_5_percent_share=0.0, lose_share=0.0, no_change_share=0.056524409525954916, gain_share=0.9434755904740451, gain_less_than_5_percent_share=0.9366881433479168, gain_more_than_5_percent_share=0.06331185665208312), 9: IncomeMeasureSpecificDecileWinnersLosersGroupOutcomes(lose_more_than_5_percent_share=0.0, lose_less_than_5_percent_share=0.008053685714292545, lose_share=0.008053685714292545, no_change_share=0.027806404912023186, gain_share=0.9641399093736843, gain_less_than_5_percent_share=0.9371641387443307, gain_more_than_5_percent_share=0.05478217554137677), 10: IncomeMeasureSpecificDecileWinnersLosersGroupOutcomes(lose_more_than_5_percent_share=0.0, lose_less_than_5_percent_share=4.868756468537358e-08, lose_share=4.868756468537358e-08, no_change_share=0.06985295508301145, gain_share=0.9301469962294239, gain_less_than_5_percent_share=0.806768831589799, gain_more_than_5_percent_share=0.1932311197226364)}, all=IncomeMeasureSpecificDecileWinnersLosersGroupOutcomes(lose_more_than_5_percent_share=0.0, lose_less_than_5_percent_share=0.0010924738666159373, lose_share=0.0008384108829899095, no_change_share=0.16458777279036807, gain_share=0.8345738163266421, gain_less_than_5_percent_share=0.947301858492644, gain_more_than_5_percent_share=0.051605667640740344)))), poverty=[PovertyRateMetricComparison(age_group='child', racial_group='all', relative=True, poverty_rate='uk_hbai_bhc', baseline=0.0866740345954895, reform=0.08660321682691574, change=-7.081776857376099e-05, relative_change=-0.0008170586370447596), PovertyRateMetricComparison(age_group='child', racial_group='all', relative=True, poverty_rate='uk_hbai_bhc_half', baseline=0.005887233652174473, reform=0.005886665545403957, change=-5.681067705154419e-07, relative_change=-9.649808451302242e-05), PovertyRateMetricComparison(age_group='child', racial_group='all', relative=False, poverty_rate='uk_hbai_bhc', baseline=1636588.5, reform=1635251.25, change=-1337.25, relative_change=-0.0008170960507176972), PovertyRateMetricComparison(age_group='child', racial_group='all', relative=False, poverty_rate='uk_hbai_bhc_half', baseline=111163.3828125, reform=111152.65625, change=-10.7265625, relative_change=-9.649366750643566e-05), PovertyRateMetricComparison(age_group='working_age', racial_group='all', relative=True, poverty_rate='uk_hbai_bhc', baseline=0.08067396283149719, reform=0.07947173714637756, change=-0.001202225685119629, relative_change=-0.014902276309776728), PovertyRateMetricComparison(age_group='working_age', racial_group='all', relative=True, poverty_rate='uk_hbai_bhc_half', baseline=0.020408159121870995, reform=0.020407630130648613, change=-5.289912223815918e-07, relative_change=-2.5920575159308858e-05), PovertyRateMetricComparison(age_group='working_age', racial_group='all', relative=False, poverty_rate='uk_hbai_bhc', baseline=3613979.5, reform=3560123.0, change=-53856.5, relative_change=-0.014902270474970874), PovertyRateMetricComparison(age_group='working_age', racial_group='all', relative=False, poverty_rate='uk_hbai_bhc_half', baseline=914231.375, reform=914207.75, change=-23.625, relative_change=-2.584137959605685e-05), PovertyRateMetricComparison(age_group='senior', racial_group='all', relative=True, poverty_rate='uk_hbai_bhc', baseline=0.033274661749601364, reform=0.03287290409207344, change=-0.0004017576575279236, relative_change=-0.012073981714712297), PovertyRateMetricComparison(age_group='senior', racial_group='all', relative=True, poverty_rate='uk_hbai_bhc_half', baseline=0.0007299797143787146, reform=0.0007292248192243278, change=-7.548951543867588e-07, relative_change=-0.0010341316882062261), PovertyRateMetricComparison(age_group='senior', racial_group='all', relative=False, poverty_rate='uk_hbai_bhc', baseline=436230.6875, reform=430963.625, change=-5267.0625, relative_change=-0.01207403021136609), PovertyRateMetricComparison(age_group='senior', racial_group='all', relative=False, poverty_rate='uk_hbai_bhc_half', baseline=9570.03125, reform=9560.134765625, change=-9.896484375, relative_change=-0.0010341120228839378), PovertyRateMetricComparison(age_group='all', racial_group='all', relative=True, poverty_rate='uk_hbai_bhc', baseline=0.07405699789524078, reform=0.07326966524124146, change=-0.0007873326539993286, relative_change=-0.01063144167838224), PovertyRateMetricComparison(age_group='all', racial_group='all', relative=True, poverty_rate='uk_hbai_bhc_half', baseline=0.01347795594483614, reform=0.013477379456162453, change=-5.764886736869812e-07, relative_change=-4.277270797192756e-05), PovertyRateMetricComparison(age_group='all', racial_group='all', relative=False, poverty_rate='uk_hbai_bhc', baseline=5686796.5, reform=5626338.0, change=-60458.5, relative_change=-0.010631380954110104), PovertyRateMetricComparison(age_group='all', racial_group='all', relative=False, poverty_rate='uk_hbai_bhc_half', baseline=1034964.875, reform=1034920.625, change=-44.25, relative_change=-4.27550741758265e-05)], labor_supply=[])"
+      ]
+     },
+     "execution_count": 1,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "from policyengine import Simulation\n",
+    "\n",
+    "sim = Simulation({\n",
+    "    \"scope\": \"macro\",\n",
+    "    \"country\": \"uk\",\n",
+    "    \"time_period\": 2025,\n",
+    "    \"reform\": {\n",
+    "        \"gov.hmrc.income_tax.allowances.personal_allowance.amount\": 15000\n",
+    "    },\n",
+    "})\n",
+    "\n",
+    "sim.calculate_economy_comparison()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "base",
+   "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.10.14"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}