PolicyEngine · nikhilwoodruff · Jan 31, 2025 · Jan 30, 2025 · Jan 30, 2025 · Jan 30, 2025
diff --git a/.github/workflows/versioning.yaml b/.github/workflows/versioning.yaml
@@ -4,10 +4,11 @@ name: Versioning updates
 on:
   push:
       branches:
-          - main
+        - main
 
       paths:
-          - changelog_entry.yaml
+        - changelog_entry.yaml
+        - "!pyproject.toml"
 
 jobs:
     Versioning:

diff --git a/Makefile b/Makefile
@@ -3,6 +3,7 @@ all: build
 documentation:
 	jb clean docs
 	jb build docs
+	python docs/add_plotly_to_book.py docs/
 
 install:
 	pip install -e .[dev]

diff --git a/changelog_entry.yaml b/changelog_entry.yaml
@@ -0,0 +1,4 @@
+- bump: minor
+  changes:
+    added:
+    - Chart generation for macro charts.
diff --git a/docs/_toc.yml b/docs/_toc.yml
@@ -4,4 +4,9 @@ parts:
   - caption: Reference
     chapters:
     - file: reference/simulation
+    - file: reference/calculate_single_household
+    - file: reference/calculate_household_comparison
+    - file: reference/calculate_single_economy
+    - file: reference/calculate_economy_comparison
+    - file: reference/create_charts
 
diff --git a/docs/add_plotly_to_book.py b/docs/add_plotly_to_book.py
@@ -0,0 +1,27 @@
+import argparse
+from pathlib import Path
+
+# This command-line tools enables Plotly charts to show in the HTML files for the Jupyter Book documentation.
+
+parser = argparse.ArgumentParser()
+parser.add_argument("book_path", help="Path to the Jupyter Book.")
+
+args = parser.parse_args()
+
+# Find every HTML file in the Jupyter Book. Then, add a script tag to the start of the <head> tag in each file, with the contents:
+# <script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"></script>
+
+book_folder = Path(args.book_path)
+
+for html_file in book_folder.glob("**/*.html"):
+    with open(html_file, "r") as f:
+        html = f.read()
+
+    # Add the script tag to the start of the <head> tag.
+    html = html.replace(
+        "<head>",
+        '<head><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"></script>',
+    )
+
+    with open(html_file, "w") as f:
+        f.write(html)
diff --git a/docs/reference/calculate_economy_comparison.ipynb b/docs/reference/calculate_economy_comparison.ipynb
diff --git a/docs/reference/calculate_household_comparison.ipynb b/docs/reference/calculate_household_comparison.ipynb
diff --git a/docs/reference/calculate_single_economy.ipynb b/docs/reference/calculate_single_economy.ipynb
@@ -0,0 +1,157 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Simulate outcomes for a large population\n",
+    "\n",
+    "Use `Simulation.calculate_single_economy()` to use PolicyEngine's tax-benefit model to compute taxes, benefits and other household properties for a large dataset (usually representing a country). This notebook demonstrates how to use this function."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "SingleEconomy(fiscal=FiscalSummary(tax_revenue=658911285719.5891, federal_tax=658911285719.5891, federal_balance=309089098855.4849, state_tax=0.0, government_spending=349822186864.1042, 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=1566028514855.0789), inequality=InequalitySummary(gini=0.36255397405553097, top_10_share=0.3260927004295773, top_1_share=0.13145609415091833), poverty=[PovertyRateMetric(age_group='child', racial_group='all', gender='male', relative=True, poverty_rate='regular', value=0.0937829241156578), PovertyRateMetric(age_group='child', racial_group='all', gender='male', relative=True, poverty_rate='deep', value=0.006947669200599194), PovertyRateMetric(age_group='child', racial_group='all', gender='male', relative=False, poverty_rate='regular', value=770371.125), PovertyRateMetric(age_group='child', racial_group='all', gender='male', relative=False, poverty_rate='deep', value=57070.984375), PovertyRateMetric(age_group='child', racial_group='all', gender='female', relative=True, poverty_rate='regular', value=0.08119998127222061), PovertyRateMetric(age_group='child', racial_group='all', gender='female', relative=True, poverty_rate='deep', value=0.005070670507848263), PovertyRateMetric(age_group='child', racial_group='all', gender='female', relative=False, poverty_rate='regular', value=866217.375), PovertyRateMetric(age_group='child', racial_group='all', gender='female', relative=False, poverty_rate='deep', value=54092.4140625), PovertyRateMetric(age_group='child', racial_group='all', gender='all', relative=True, poverty_rate='regular', value=0.0866740345954895), PovertyRateMetric(age_group='child', racial_group='all', gender='all', relative=True, poverty_rate='deep', value=0.005887233652174473), PovertyRateMetric(age_group='child', racial_group='all', gender='all', relative=False, poverty_rate='regular', value=1636588.5), PovertyRateMetric(age_group='child', racial_group='all', gender='all', relative=False, poverty_rate='deep', value=111163.3828125), PovertyRateMetric(age_group='working_age', racial_group='all', gender='male', relative=True, poverty_rate='regular', value=0.09058031439781189), PovertyRateMetric(age_group='working_age', racial_group='all', gender='male', relative=True, poverty_rate='deep', value=0.0320294052362442), PovertyRateMetric(age_group='working_age', racial_group='all', gender='male', relative=False, poverty_rate='regular', value=2207394.25), PovertyRateMetric(age_group='working_age', racial_group='all', gender='male', relative=False, poverty_rate='deep', value=780539.625), PovertyRateMetric(age_group='working_age', racial_group='all', gender='female', relative=True, poverty_rate='regular', value=0.06885619461536407), PovertyRateMetric(age_group='working_age', racial_group='all', gender='female', relative=True, poverty_rate='deep', value=0.006544755306094885), PovertyRateMetric(age_group='working_age', racial_group='all', gender='female', relative=False, poverty_rate='regular', value=1406585.625), PovertyRateMetric(age_group='working_age', racial_group='all', gender='female', relative=False, poverty_rate='deep', value=133695.4375), PovertyRateMetric(age_group='working_age', racial_group='all', gender='all', relative=True, poverty_rate='regular', value=0.08067396283149719), PovertyRateMetric(age_group='working_age', racial_group='all', gender='all', relative=True, poverty_rate='deep', value=0.02040824294090271), PovertyRateMetric(age_group='working_age', racial_group='all', gender='all', relative=False, poverty_rate='regular', value=3613979.5), PovertyRateMetric(age_group='working_age', racial_group='all', gender='all', relative=False, poverty_rate='deep', value=914235.1875), PovertyRateMetric(age_group='senior', racial_group='all', gender='male', relative=True, poverty_rate='regular', value=0.019906071946024895), PovertyRateMetric(age_group='senior', racial_group='all', gender='male', relative=True, poverty_rate='deep', value=0.0001492029696237296), PovertyRateMetric(age_group='senior', racial_group='all', gender='male', relative=False, poverty_rate='regular', value=120630.84375), PovertyRateMetric(age_group='senior', racial_group='all', gender='male', relative=False, poverty_rate='deep', value=904.1703491210938), PovertyRateMetric(age_group='senior', racial_group='all', gender='female', relative=True, poverty_rate='regular', value=0.04476610943675041), PovertyRateMetric(age_group='senior', racial_group='all', gender='female', relative=True, poverty_rate='deep', value=0.0012297447538003325), PovertyRateMetric(age_group='senior', racial_group='all', gender='female', relative=False, poverty_rate='regular', value=315600.8125), PovertyRateMetric(age_group='senior', racial_group='all', gender='female', relative=False, poverty_rate='deep', value=8669.693359375), PovertyRateMetric(age_group='senior', racial_group='all', gender='all', relative=True, poverty_rate='regular', value=0.03327473625540733), PovertyRateMetric(age_group='senior', racial_group='all', gender='all', relative=True, poverty_rate='deep', value=0.0007302720914594829), PovertyRateMetric(age_group='senior', racial_group='all', gender='all', relative=False, poverty_rate='regular', value=436231.65625), PovertyRateMetric(age_group='senior', racial_group='all', gender='all', relative=False, poverty_rate='deep', value=9573.8642578125), PovertyRateMetric(age_group='all', racial_group='all', gender='male', relative=True, poverty_rate='regular', value=0.08017819374799728), PovertyRateMetric(age_group='all', racial_group='all', gender='male', relative=True, poverty_rate='deep', value=0.021698515862226486), PovertyRateMetric(age_group='all', racial_group='all', gender='male', relative=False, poverty_rate='regular', value=3098396.25), PovertyRateMetric(age_group='all', racial_group='all', gender='male', relative=False, poverty_rate='deep', value=838514.75), PovertyRateMetric(age_group='all', racial_group='all', gender='female', relative=True, poverty_rate='regular', value=0.06785593926906586), PovertyRateMetric(age_group='all', racial_group='all', gender='female', relative=True, poverty_rate='deep', value=0.005150204990059137), PovertyRateMetric(age_group='all', racial_group='all', gender='female', relative=False, poverty_rate='regular', value=2588403.75), PovertyRateMetric(age_group='all', racial_group='all', gender='female', relative=False, poverty_rate='deep', value=196457.53125), PovertyRateMetric(age_group='all', racial_group='all', gender='all', relative=True, poverty_rate='regular', value=0.07405701279640198), PovertyRateMetric(age_group='all', racial_group='all', gender='all', relative=True, poverty_rate='deep', value=0.013478054665029049), PovertyRateMetric(age_group='all', racial_group='all', gender='all', relative=False, poverty_rate='regular', value=5686797.5), PovertyRateMetric(age_group='all', racial_group='all', gender='all', relative=False, poverty_rate='deep', value=1034972.5)])"
+      ]
+     },
+     "execution_count": 1,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "from policyengine import Simulation\n",
+    "\n",
+    "sim = Simulation({\n",
+    "    \"scope\": \"macro\", # Required for this\n",
+    "    \"country\": \"uk\", # or \"us\"\n",
+    "    \"time_period\": 2025,\n",
+    "})\n",
+    "\n",
+    "sim.calculate()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Output schema\n",
+    "\n",
+    "`calculate_single_economy` or `calculate` (when `scope=macro` and `reform=None`) return the following schema."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'$defs': {'FiscalSummary': {'properties': {'tax_revenue': {'title': 'Tax Revenue',\n",
+       "     'type': 'number'},\n",
+       "    'federal_tax': {'title': 'Federal Tax', 'type': 'number'},\n",
+       "    'federal_balance': {'title': 'Federal Balance', 'type': 'number'},\n",
+       "    'state_tax': {'title': 'State Tax', 'type': 'number'},\n",
+       "    'government_spending': {'title': 'Government Spending', 'type': 'number'},\n",
+       "    'tax_benefit_programs': {'additionalProperties': {'type': 'number'},\n",
+       "     'title': 'Tax Benefit Programs',\n",
+       "     'type': 'object'},\n",
+       "    'household_net_income': {'title': 'Household Net Income',\n",
+       "     'type': 'number'}},\n",
+       "   'required': ['tax_revenue',\n",
+       "    'federal_tax',\n",
+       "    'federal_balance',\n",
+       "    'state_tax',\n",
+       "    'government_spending',\n",
+       "    'tax_benefit_programs',\n",
+       "    'household_net_income'],\n",
+       "   'title': 'FiscalSummary',\n",
+       "   'type': 'object'},\n",
+       "  'InequalitySummary': {'properties': {'gini': {'title': 'Gini',\n",
+       "     'type': 'number'},\n",
+       "    'top_10_share': {'title': 'Top 10 Share', 'type': 'number'},\n",
+       "    'top_1_share': {'title': 'Top 1 Share', 'type': 'number'}},\n",
+       "   'required': ['gini', 'top_10_share', 'top_1_share'],\n",
+       "   'title': 'InequalitySummary',\n",
+       "   'type': 'object'},\n",
+       "  'PovertyRateMetric': {'properties': {'age_group': {'enum': ['child',\n",
+       "      'working_age',\n",
+       "      'senior',\n",
+       "      'all'],\n",
+       "     'title': 'Age Group',\n",
+       "     'type': 'string'},\n",
+       "    'racial_group': {'enum': ['white', 'black', 'hispanic', 'other', 'all'],\n",
+       "     'title': 'Racial Group',\n",
+       "     'type': 'string'},\n",
+       "    'gender': {'enum': ['male', 'female', 'all'],\n",
+       "     'title': 'Gender',\n",
+       "     'type': 'string'},\n",
+       "    'relative': {'title': 'Relative', 'type': 'boolean'},\n",
+       "    'poverty_rate': {'enum': ['regular',\n",
+       "      'deep',\n",
+       "      'uk_hbai_bhc',\n",
+       "      'uk_hbai_bhc_half',\n",
+       "      'us_spm',\n",
+       "      'us_spm_half'],\n",
+       "     'title': 'Poverty Rate',\n",
+       "     'type': 'string'},\n",
+       "    'value': {'title': 'Value', 'type': 'number'}},\n",
+       "   'required': ['age_group',\n",
+       "    'racial_group',\n",
+       "    'gender',\n",
+       "    'relative',\n",
+       "    'poverty_rate',\n",
+       "    'value'],\n",
+       "   'title': 'PovertyRateMetric',\n",
+       "   'type': 'object'}},\n",
+       " 'properties': {'fiscal': {'$ref': '#/$defs/FiscalSummary'},\n",
+       "  'inequality': {'$ref': '#/$defs/InequalitySummary'},\n",
+       "  'poverty': {'items': {'$ref': '#/$defs/PovertyRateMetric'},\n",
+       "   'title': 'Poverty',\n",
+       "   'type': 'array'}},\n",
+       " 'required': ['fiscal', 'inequality', 'poverty'],\n",
+       " 'title': 'SingleEconomy',\n",
+       " 'type': 'object'}"
+      ]
+     },
+     "execution_count": 2,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "from policyengine.outputs.macro.single.calculate_single_economy import SingleEconomy\n",
+    "\n",
+    "SingleEconomy.model_json_schema()"
+   ]
+  }
+ ],
+ "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
+}