Add firm-level VAT implementation

docs/book/programs/gov/dcms/bbc/tv-licence.ipynb

@@ -128,10 +128,12 @@
     "\n",
     "df = pd.DataFrame()\n",
     "df[\"Date\"] = [\n",
-    "    parameter.instant_str for parameter in dcms.bbc.tv_licence.colour.values_list\n",
+    "    parameter.instant_str\n",
+    "    for parameter in dcms.bbc.tv_licence.colour.values_list\n",
     "]\n",
     "df[\"Full TV Licence Fee\"] = [\n",
-    "    f\"£{parameter.value:.2f}\" for parameter in dcms.bbc.tv_licence.colour.values_list\n",
+    "    f\"£{parameter.value:.2f}\"\n",
+    "    for parameter in dcms.bbc.tv_licence.colour.values_list\n",
     "]\n",
     "df[\"Blind TV Licence Fee\"] = [\n",
     "    f\"£{0.5 * parameter.value:.2f}\"\n",
@@ -332,7 +334,9 @@
     "    aged_discount[\"Change against current\"] += [\n",
     "        f\"{aged_discount['Reformed value'][i] - 1:.0%}\"\n",
     "    ]\n",
-    "    aged_discount[\"Reformed value\"][i] = f\"{aged_discount['Reformed value'][i]:.0%}\"\n",
+    "    aged_discount[\"Reformed value\"][\n",
+    "        i\n",
+    "    ] = f\"{aged_discount['Reformed value'][i]:.0%}\"\n",
     "    aged_discount[\"Reference\"] += [\n",
     "        f'<a href=\"{reference_list_ad[i]}\">Budgetary impact of changing aged discount to {aged_discount[\"Reformed value\"][i]}</a>'\n",
     "    ]\n",

docs/book/programs/gov/dwp/pension-credit.ipynb

@@ -167,8 +167,12 @@
     "\n",
     "parameters = system.parameters\n",
     "\n",
-    "carer_addition = parameters.gov.dwp.pension_credit.guarantee_credit.carer.addition\n",
-    "child_addition = parameters.gov.dwp.pension_credit.guarantee_credit.child.addition\n",
+    "carer_addition = (\n",
+    "    parameters.gov.dwp.pension_credit.guarantee_credit.carer.addition\n",
+    ")\n",
+    "child_addition = (\n",
+    "    parameters.gov.dwp.pension_credit.guarantee_credit.child.addition\n",
+    ")\n",
     "disabled_child = (\n",
     "    parameters.gov.dwp.pension_credit.guarantee_credit.child.disability.addition\n",
     ")\n",
@@ -1502,8 +1506,12 @@
     "\n",
     "parameters = system.parameters\n",
     "\n",
-    "threshold_single = parameters.gov.dwp.pension_credit.savings_credit.threshold.SINGLE\n",
-    "threshold_couple = parameters.gov.dwp.pension_credit.savings_credit.threshold.COUPLE\n",
+    "threshold_single = (\n",
+    "    parameters.gov.dwp.pension_credit.savings_credit.threshold.SINGLE\n",
+    ")\n",
+    "threshold_couple = (\n",
+    "    parameters.gov.dwp.pension_credit.savings_credit.threshold.COUPLE\n",
+    ")\n",
     "\n",
     "elements = [threshold_single, threshold_couple]  # [...]\n",
     "\n",

docs/book/programs/gov/dwp/universal-credit.ipynb

@@ -194,7 +194,9 @@
     "disabled_child_amount = (\n",
     "    parameters.gov.dwp.universal_credit.elements.child.disabled.amount\n",
     ")\n",
-    "higher_amount = parameters.gov.dwp.universal_credit.elements.child.first.higher_amount\n",
+    "higher_amount = (\n",
+    "    parameters.gov.dwp.universal_credit.elements.child.first.higher_amount\n",
+    ")\n",
     "\n",
     "elements = [\n",
     "    carer_amount,\n",

docs/book/programs/gov/hmrc/child-benefit.ipynb

@@ -175,7 +175,9 @@
     "        data[\"Reference\"] += [\"\"]\n",
     "\n",
     "\n",
-    "for parameter in parameters.gov.hmrc.child_benefit.amount.additional.values_list:\n",
+    "for (\n",
+    "    parameter\n",
+    ") in parameters.gov.hmrc.child_benefit.amount.additional.values_list:\n",
     "    data[\"Date\"] += [parameter.instant_str]\n",
     "    data[\"Name\"] += [\"Additional\"]\n",
     "    data[\"Value\"] += [f\"£{parameter.value:.2f}\"]\n",
@@ -187,9 +189,9 @@
     "        data[\"Reference\"] += [\"\"]\n",
     "\n",
     "\n",
-    "pd.DataFrame(data).sort_values(\"Date\").set_index([\"Date\", \"Name\"]).style.format(\n",
-    "    lambda x: x\n",
-    ")"
+    "pd.DataFrame(data).sort_values(\"Date\").set_index(\n",
+    "    [\"Date\", \"Name\"]\n",
+    ").style.format(lambda x: x)"
    ]
   },
   {
@@ -300,7 +302,9 @@
     "pd.DataFrame(\n",
     "    {\n",
     "        \"Number of children\": list(range(1, 7)),\n",
-    "        \"Child Benefit (Annual)\": list(map(get_cb_for_n_children, range(1, 7))),\n",
+    "        \"Child Benefit (Annual)\": list(\n",
+    "            map(get_cb_for_n_children, range(1, 7))\n",
+    "        ),\n",
     "    }\n",
     ").set_index(\"Number of children\")"
    ]

docs/book/programs/gov/hmrc/fuel-duty.ipynb

@@ -126,10 +126,12 @@
     "df = pd.DataFrame()\n",
     "\n",
     "df[\"Date of change\"] = [\n",
-    "    parameter.instant_str for parameter in hmrc.fuel_duty.petrol_and_diesel.values_list\n",
+    "    parameter.instant_str\n",
+    "    for parameter in hmrc.fuel_duty.petrol_and_diesel.values_list\n",
     "]\n",
     "df[\"Fuel duty rate (£/litre)\"] = [\n",
-    "    parameter.value for parameter in hmrc.fuel_duty.petrol_and_diesel.values_list\n",
+    "    parameter.value\n",
+    "    for parameter in hmrc.fuel_duty.petrol_and_diesel.values_list\n",
     "]\n",
     "df.sort_values(\"Date of change\", inplace=True)\n",
     "df.set_index(\"Date of change\")"
@@ -1070,7 +1072,11 @@
     "    height=600,\n",
     "    width=800,\n",
     "    template=\"plotly_white\",\n",
-    ").update_xaxes(tickangle=45, tickfont={\"size\": 10}).update_traces(line_shape=\"hv\")"
+    ").update_xaxes(\n",
+    "    tickangle=45, tickfont={\"size\": 10}\n",
+    ").update_traces(\n",
+    "    line_shape=\"hv\"\n",
+    ")"
    ]
   }
  ],

docs/book/programs/gov/hmrc/income-tax.ipynb

@@ -207,7 +207,9 @@
     "from policyengine_uk import Simulation\n",
     "\n",
     "\n",
-    "def calculate_taxes(employment_income, dividend_income, savings_interest_income):\n",
+    "def calculate_taxes(\n",
+    "    employment_income, dividend_income, savings_interest_income\n",
+    "):\n",
     "    simulation = Simulation(\n",
     "        situation={\n",
     "            \"people\": {\n",
@@ -220,7 +222,9 @@
     "        }\n",
     "    )\n",
     "    income_tax = simulation.calculate(\"income_tax\")[0]\n",
-    "    dividend_income_tax = simulation.calculate(\"dividend_income_tax\")[0]  # Added\n",
+    "    dividend_income_tax = simulation.calculate(\"dividend_income_tax\")[\n",
+    "        0\n",
+    "    ]  # Added\n",
     "    savings_income_tax = simulation.calculate(\"savings_income_tax\")[0]  # Added\n",
     "\n",
     "    return income_tax, dividend_income_tax, savings_income_tax\n",
@@ -241,7 +245,9 @@
     "    data[\"Dividend Income (£)\"],\n",
     "    data[\"Savings Interest Income (£)\"],\n",
     "):\n",
-    "    income_tax, div_tax, sav_tax = calculate_taxes(emp_income, div_income, sav_income)\n",
+    "    income_tax, div_tax, sav_tax = calculate_taxes(\n",
+    "        emp_income, div_income, sav_income\n",
+    "    )\n",
     "    data[\"Income Tax (£)\"].append(income_tax)\n",
     "    data[\"Dividend Income Tax (£)\"].append(div_tax)\n",
     "    data[\"Savings Income Tax (£)\"].append(sav_tax)\n",
@@ -518,8 +524,12 @@
     "from policyengine_uk.system import system\n",
     "import pandas as pd\n",
     "\n",
-    "default = system.parameters.gov.hmrc.income_tax.allowances.annual_allowance.default\n",
-    "minimum = system.parameters.gov.hmrc.income_tax.allowances.annual_allowance.minimum\n",
+    "default = (\n",
+    "    system.parameters.gov.hmrc.income_tax.allowances.annual_allowance.default\n",
+    ")\n",
+    "minimum = (\n",
+    "    system.parameters.gov.hmrc.income_tax.allowances.annual_allowance.minimum\n",
+    ")\n",
     "reduction_rate = (\n",
     "    system.parameters.gov.hmrc.income_tax.allowances.annual_allowance.reduction_rate\n",
     ")\n",
@@ -549,7 +559,9 @@
     "\n",
     "\n",
     "max = system.parameters.gov.hmrc.income_tax.allowances.marriage_allowance.max\n",
-    "rounding_increment = system.parameters.gov.hmrc.income_tax.allowances.marriage_allowance.rounding_increment\n",
+    "rounding_increment = (\n",
+    "    system.parameters.gov.hmrc.income_tax.allowances.marriage_allowance.rounding_increment\n",
+    ")\n",
     "takeup_rate = (\n",
     "    system.parameters.gov.hmrc.income_tax.allowances.marriage_allowance.takeup_rate\n",
     ")\n",
@@ -574,7 +586,9 @@
     "}\n",
     "\n",
     "\n",
-    "deduction_rate = system.parameters.gov.hmrc.income_tax.allowances.married_couples_allowance.deduction_rate\n",
+    "deduction_rate = (\n",
+    "    system.parameters.gov.hmrc.income_tax.allowances.married_couples_allowance.deduction_rate\n",
+    ")\n",
     "married_couples_allowance_data = {\n",
     "    \"Attribute\": [\"Married Couples Allowance\"],\n",
     "    \"Type\": [\"Deduction Rate\"],\n",
@@ -584,7 +598,9 @@
     "}\n",
     "\n",
     "\n",
-    "amount = system.parameters.gov.hmrc.income_tax.allowances.personal_allowance.amount\n",
+    "amount = (\n",
+    "    system.parameters.gov.hmrc.income_tax.allowances.personal_allowance.amount\n",
+    ")\n",
     "values = [item.value for item in amount.values_list]\n",
     "dates = [item.instant_str for item in amount.values_list]\n",
     "personal_allowance_data = {\n",
@@ -596,7 +612,9 @@
     "}\n",
     "\n",
     "\n",
-    "addtional_threshold = system.parameters.gov.hmrc.income_tax.allowances.personal_savings_allowance.additional\n",
+    "addtional_threshold = (\n",
+    "    system.parameters.gov.hmrc.income_tax.allowances.personal_savings_allowance.additional\n",
+    ")\n",
     "basic_threshold = (\n",
     "    system.parameters.gov.hmrc.income_tax.allowances.personal_savings_allowance.basic\n",
     ")\n",
@@ -624,7 +642,9 @@
     "}\n",
     "\n",
     "\n",
-    "dividend_allowance = system.parameters.gov.hmrc.income_tax.allowances.dividend_allowance\n",
+    "dividend_allowance = (\n",
+    "    system.parameters.gov.hmrc.income_tax.allowances.dividend_allowance\n",
+    ")\n",
     "dividend_allowance_data = {\n",
     "    \"Attribute\": [\"Dividend Allowance\"],\n",
     "    \"Type\": [\"Dividend Allowance\"],\n",
@@ -634,7 +654,9 @@
     "}\n",
     "\n",
     "\n",
-    "property_allowance = system.parameters.gov.hmrc.income_tax.allowances.property_allowance\n",
+    "property_allowance = (\n",
+    "    system.parameters.gov.hmrc.income_tax.allowances.property_allowance\n",
+    ")\n",
     "property_allowance_data = {\n",
     "    \"Attribute\": [\"Property Allowance\"],\n",
     "    \"Type\": [\"Property Allowance\"],\n",
@@ -644,7 +666,9 @@
     "}\n",
     "\n",
     "\n",
-    "trading_allowance = system.parameters.gov.hmrc.income_tax.allowances.trading_allowance\n",
+    "trading_allowance = (\n",
+    "    system.parameters.gov.hmrc.income_tax.allowances.trading_allowance\n",
+    ")\n",
     "trading_allowance_data = {\n",
     "    \"Attribute\": [\"Trading Allowance\"],\n",
     "    \"Type\": [\"Trading Allowance\"],\n",

docs/book/programs/gov/hmrc/stamp-duty.ipynb

@@ -6287,7 +6287,9 @@
     "stamp_duty = sim.calculate(\"stamp_duty_land_tax\")\n",
     "home_price = sim.calculate(\"main_residential_property_purchased\")\n",
     "\n",
-    "marginal_rate = (stamp_duty[1:] - stamp_duty[:-1]) / (home_price[1:] - home_price[:-1])\n",
+    "marginal_rate = (stamp_duty[1:] - stamp_duty[:-1]) / (\n",
+    "    home_price[1:] - home_price[:-1]\n",
+    ")\n",
     "home_price = home_price[:-1]\n",
     "\n",
     "df = pd.DataFrame(\n",
@@ -6303,10 +6305,14 @@
     "\n",
     "# left shows marginal rate, right shows total SDLT\n",
     "\n",
-    "fig = make_subplots(rows=1, cols=2, subplot_titles=(\"Marginal SDLT rate\", \"Total SDLT\"))\n",
+    "fig = make_subplots(\n",
+    "    rows=1, cols=2, subplot_titles=(\"Marginal SDLT rate\", \"Total SDLT\")\n",
+    ")\n",
     "\n",
     "fig.add_trace(\n",
-    "    px.line(df, x=\"Home price\", y=\"Marginal SDLT rate\", title=\"Marginal SDLT rate\")\n",
+    "    px.line(\n",
+    "        df, x=\"Home price\", y=\"Marginal SDLT rate\", title=\"Marginal SDLT rate\"\n",
+    "    )\n",
     "    .update_traces(line_shape=\"hv\")\n",
     "    .data[0],\n",
     "    row=1,\n",

docs/book/programs/gov/ofgem/energy-price-guarantee.ipynb

@@ -1011,7 +1011,9 @@
     "\n",
     "df = pd.DataFrame()\n",
     "\n",
-    "df[\"Date\"] = [parameter.instant_str for parameter in ofgem.energy_price_cap.values_list]\n",
+    "df[\"Date\"] = [\n",
+    "    parameter.instant_str for parameter in ofgem.energy_price_cap.values_list\n",
+    "]\n",
     "df[\"Energy price cap\"] = [\n",
     "    parameter.value for parameter in ofgem.energy_price_cap.values_list\n",
     "]\n",
@@ -1105,9 +1107,9 @@
          "xaxis": "x",
          "y": [
           8.373929949593731e-10,
-          1.674785989918746e-9,
-          2.512178984878119e-9,
-          3.3495719798374923e-9,
+          1.674785989918746e-09,
+          2.512178984878119e-09,
+          3.3495719798374923e-09,
           1.2009600411861108,
           2.40192007902265,
           3.602880116859188,
@@ -1996,7 +1998,9 @@
     "    *[f\"2023-{month:02d}\" for month in range(1, 13)],\n",
     "]\n",
     "\n",
-    "epg_costs = [sim.calc(\"monthly_epg_subsidy\", period).sum() for period in time_periods]\n",
+    "epg_costs = [\n",
+    "    sim.calc(\"monthly_epg_subsidy\", period).sum() for period in time_periods\n",
+    "]\n",
     "\n",
     "df = pd.DataFrame(\n",
     "    {\n",

docs/book/programs/gov/revenue_scotland/land-and-buildings-transaction-tax.ipynb

@@ -1217,7 +1217,9 @@
     "        color=\"Label\",\n",
     "        title=\"Land and Buildings Transaction Tax (LBTT) rates over property price thresholds\",\n",
     "    )\n",
-    "    .update_layout(yaxis_tickformat=\",.0%\", xaxis_tickprefix=\"£\", legend_title=\"\")\n",
+    "    .update_layout(\n",
+    "        yaxis_tickformat=\",.0%\", xaxis_tickprefix=\"£\", legend_title=\"\"\n",
+    "    )\n",
     "    .update_traces(line_shape=\"hv\")\n",
     ")\n",
     "fig = format_fig(fig)\n",
@@ -6239,7 +6241,9 @@
     "lbtt_sim = sim.calculate(\"land_and_buildings_transaction_tax\")\n",
     "home_price = sim.calculate(\"main_residential_property_purchased\")\n",
     "\n",
-    "marginal_rate = (lbtt_sim[1:] - lbtt_sim[:-1]) / (home_price[1:] - home_price[:-1])\n",
+    "marginal_rate = (lbtt_sim[1:] - lbtt_sim[:-1]) / (\n",
+    "    home_price[1:] - home_price[:-1]\n",
+    ")\n",
     "home_price = home_price[:-1]\n",
     "\n",
     "df = pd.DataFrame(\n",
@@ -6255,10 +6259,14 @@
     "\n",
     "# left shows marginal rate, right shows total LBTT\n",
     "\n",
-    "fig = make_subplots(rows=1, cols=2, subplot_titles=(\"Marginal LBTT rate\", \"Total LBTT\"))\n",
+    "fig = make_subplots(\n",
+    "    rows=1, cols=2, subplot_titles=(\"Marginal LBTT rate\", \"Total LBTT\")\n",
+    ")\n",
     "\n",
     "fig.add_trace(\n",
-    "    px.line(df, x=\"Home price\", y=\"Marginal LBTT rate\", title=\"Marginal LBTT rate\")\n",
+    "    px.line(\n",
+    "        df, x=\"Home price\", y=\"Marginal LBTT rate\", title=\"Marginal LBTT rate\"\n",
+    "    )\n",
     "    .update_traces(line_shape=\"hv\")\n",
     "    .data[0],\n",
     "    row=1,\n",

docs/book/programs/gov/wra/land-transaction-tax.ipynb

@@ -1153,7 +1153,9 @@
     "        color=\"Label\",\n",
     "        title=\"Land Transaction Tax (LTT) rates over property price thresholds\",\n",
     "    )\n",
-    "    .update_layout(yaxis_tickformat=\",.0%\", xaxis_tickprefix=\"£\", legend_title=\"\")\n",
+    "    .update_layout(\n",
+    "        yaxis_tickformat=\",.0%\", xaxis_tickprefix=\"£\", legend_title=\"\"\n",
+    "    )\n",
     "    .update_traces(line_shape=\"hv\")\n",
     ")\n",
     "fig = format_fig(fig)\n",

docs/book/validation/validation.ipynb

@@ -1901,7 +1901,9 @@
     "    return (\n",
     "        np.array(\n",
     "            [\n",
-    "                get_parameter(calibration_parameters, parameter)(f\"{year}-01-01\")\n",
+    "                get_parameter(calibration_parameters, parameter)(\n",
+    "                    f\"{year}-01-01\"\n",
+    "                )\n",
     "                for year in range(2023, 2026)\n",
     "            ]\n",
     "        )\n",

policyengine_uk/entities.py

@@ -43,4 +43,19 @@
     is_person=True,
 )
 
-entities = [Household, BenUnit, Person]
+Firm = build_entity(
+    key="firm",
+    plural="firms",
+    label="Firm",
+    doc="A business entity that may be subject to VAT and other business taxes.",
+    roles=[
+        {
+            "key": "owner",
+            "plural": "owners",
+            "label": "Owner",
+            "doc": "A person who owns or has an interest in the firm.",
+        }
+    ],
+)
+
+entities = [Household, BenUnit, Person, Firm]