[1] - added Budgetary Impact docs

docs/Budgetary/byprogram.md

@@ -0,0 +1,94 @@
+# By program
+
+## Overview
+
+The Budgetary Impact by Program metrics provide detailed insights into how a policy reform affects various government revenue and expenditure programs. These metrics are part of the `EconomicImpact` class and can be calculated for different tax and benefit programs.
+
+## Available Metrics
+
+1. `budgetary/by_program/income_tax`: Income Tax revenue
+2. `budgetary/by_program/national_insurance`: National Insurance contributions
+3. `budgetary/by_program/vat`: Value Added Tax (VAT) revenue
+4. `budgetary/by_program/council_tax`: Council Tax revenue
+5. `budgetary/by_program/fuel_duty`: Fuel Duty revenue
+6. `budgetary/by_program/tax_credits`: Tax Credits expenditure
+7. `budgetary/by_program/universal_credits`: Universal Credit expenditure
+8. `budgetary/by_program/child_benefits`: Child Benefits expenditure
+9. `budgetary/by_program/state_pension`: State Pension expenditure
+10. `budgetary/by_program/pension_credit`: Pension Credit expenditure
+
+## Metric Structure
+
+Each metric returns a dictionary with the following keys:
+- `baseline`: The amount before the reform (in GBP).
+- `reform`: The amount after the reform (in GBP).
+- `change`: The percentage change due to the reform.
+
+All values are rounded to 2 decimal places for the baseline and reform, and to 1 decimal place for the change.
+
+## Example Usage
+
+```python
+from policyengine import EconomicImpact
+
+# Initialize the EconomicImpact class with a reform
+impact = EconomicImpact(reform={
+  "gov.hmrc.income_tax.rates.uk[0].rate": {
+    "2024-01-01.2100-12-31": 0.55
+  }
+}, country="uk")
+
+# Calculate budgetary impact for each program
+income_tax = impact.calculate("budgetary/by_program/income_tax")
+national_insurance = impact.calculate("budgetary/by_program/national_insurance")
+vat = impact.calculate("budgetary/by_program/vat")
+council_tax = impact.calculate("budgetary/by_program/council_tax")
+fuel_duty = impact.calculate("budgetary/by_program/fuel_duty")
+tax_credits = impact.calculate("budgetary/by_program/tax_credits")
+universal_credits = impact.calculate("budgetary/by_program/universal_credits")
+child_benefits = impact.calculate("budgetary/by_program/child_benefits")
+state_pension = impact.calculate("budgetary/by_program/state_pension")
+pension_credit = impact.calculate("budgetary/by_program/pension_credit")
+
+# Print the results
+print(f"Income Tax: {income_tax}")
+print(f"National Insurance: {national_insurance}")
+print(f"VAT: {vat}")
+print(f"Council Tax: {council_tax}")
+print(f"Fuel Duty: {fuel_duty}")
+print(f"Tax Credits: {tax_credits}")
+print(f"Universal Credit: {universal_credits}")
+print(f"Child Benefits: {child_benefits}")
+print(f"State Pension: {state_pension}")
+print(f"Pension Credit: {pension_credit}")
+
+```
+
+## Output 
+
+```
+Income Tax: {'baseline': 291090070166.62, 'reform': 496242053771.2, 'change': 70.5}
+National Insurance: {'baseline': 50826792606.89, 'reform': 50826792606.89, 'change': 0.0}
+VAT: {'baseline': 175581776889.21, 'reform': 175581776889.21, 'change': 0.0}
+Council Tax: {'baseline': 47861314826.79, 'reform': 47861314826.79, 'change': 0.0}
+Fuel Duty: {'baseline': 28019829809.09, 'reform': 28019829809.09, 'change': 0.0}
+Tax Credits: {'baseline': -208150256.01, 'reform': -308166663.98, 'change': 48.1}
+Universal Credit: {'baseline': -72209672284.1, 'reform': -73780445681.08, 'change': 2.2}
+Child Benefits: {'baseline': -15975002346.41, 'reform': -15975002346.41, 'change': -0.0}
+State Pension: {'baseline': -127240166697.26, 'reform': -127240166697.26, 'change': -0.0}
+Pension Credit: {'baseline': -2000983943.05, 'reform': -2181135212.4, 'change': 9.0}
+```
+
+## Interpretation
+
+In this example:
+
+- Income Tax revenue increases significantly by 70.5%, from £291.1 billion to £496.2 billion.
+- National Insurance, VAT, Council Tax, and Fuel Duty revenues remain unchanged.
+- Tax Credits expenditure increases by 48.1%, from £208.2 million to £308.2 million.
+- Universal Credit expenditure increases slightly by 2.2%, from £72.2 billion to £73.8 billion.
+- Child Benefits and State Pension expenditures remain unchanged.
+- Pension Credit expenditure increases by 9.0%, from £2.0 billion to £2.2 billion.
+
+These metrics provide a comprehensive view of how the reform affects various government revenue streams and expenditure programs. They can help policymakers understand the fiscal implications of proposed reforms across different sectors of the budget.
+Note: Negative values for benefits (e.g., Tax Credits, Universal Credit) indicate government expenditure.

docs/Budgetary/index.md

@@ -0,0 +1,24 @@
+# Budgetary Impact
+
+## Overview
+
+The Budgetary Impact metrics provide comprehensive insights into how policy reforms affect government finances. These metrics are part of the `EconomicImpact` class and offer detailed analysis at both program-specific and overall levels.
+
+## Table of Contents
+
+1. Budgetary Impact Overall
+   - Overall Budgetary Impact
+   - Benefit Spending Impact
+   - Tax Revenue Impact
+
+2. Budgetary Impact by Program
+   - Income Tax
+   - National Insurance
+   - Value Added Tax (VAT)
+   - Council Tax
+   - Fuel Duty
+   - Tax Credits
+   - Universal Credit
+   - Child Benefits
+   - State Pension
+   - Pension Credit

docs/Budgetary/overall.md

@@ -0,0 +1,88 @@
+# Overall
+
+## Overview
+
+The Budgetary Impact Overall metrics provide a high-level summary of how a policy reform affects government finances. These metrics are part of the `EconomicImpact` class and offer insights into the overall budgetary impact, changes in benefit spending, and changes in tax revenue.
+
+## Available Metrics
+
+1. `budgetary/overall/budgetary_impact`: Overall budgetary impact of the reform
+2. `budgetary/overall/benefit_spending_impact`: Impact on total benefit spending
+3. `budgetary/overall/tax_revenue_impact`: Impact on total tax revenue
+
+## Metric Structure
+
+Each metric returns a dictionary with specific keys:
+
+### Budgetary Impact
+- `budgetary_impact`: The overall budgetary impact (in GBP)
+
+### Benefit Spending Impact
+- `baseline_total_benefits`: Total benefits before the reform (in GBP)
+- `reformed total benefits`: Total benefits after the reform (in GBP)
+- `benefit_spending_impact`: The difference in benefit spending (in GBP)
+
+### Tax Revenue Impact
+- `baseline total tax`: Total tax revenue before the reform (in GBP)
+- `reformed total tax`: Total tax revenue after the reform (in GBP)
+- `tax_revenue_impact`: The difference in tax revenue (in GBP)
+
+## Example Usage
+
+```python
+from policyengine import EconomicImpact
+
+# Initialize the EconomicImpact class with a reform
+impact = EconomicImpact(reform={
+  "gov.hmrc.income_tax.rates.uk[0].rate": {
+    "2024-01-01.2100-12-31": 0.55
+  }
+}, country="uk")
+
+# Calculate overall budgetary impacts
+budgetary_impact = impact.calculate("budgetary/overall/budgetary_impact")
+benefit_spending_impact = impact.calculate("budgetary/overall/benefit_spending_impact")
+tax_revenue_impact = impact.calculate("budgetary/overall/tax_revenue_impact")
+
+# Print the results
+print(f"Budgetary Impact: {budgetary_impact}")
+print(f"Benefit Spending Impact: {benefit_spending_impact}")
+print(f"Tax Revenue Impact: {tax_revenue_impact}")
+
+```
+
+## output
+
+```
+Budgetary Impact: {'budgetary_impact': 203274712297.14}
+Benefit Spending Impact: {'baseline_total_benefits': 247160184562.67, 'reformed total benefits': 249032006583.15, 'benefit spending impact': 1871822020.49}
+Tax Revenue Impact: {'baseline total tax': 447861864968.89, 'reformed total tax': 653008399286.52, 'tax revenue impact': 205146534317.63}
+```
+
+## Interpretation
+
+In this example:
+
+1. Overall Budgetary Impact:
+
+- The reform results in a positive budgetary impact of approximately £203.27 billion. This represents the net fiscal effect of the reform, combining changes in both tax revenue and benefit spending.
+
+
+2. Benefit Spending Impact:
+
+- Baseline total benefits: £247.16 billion
+- Reformed total benefits: £249.03 billion
+- The reform increases benefit spending by £1.87 billion
+
+
+3. Tax Revenue Impact:
+
+- Baseline total tax: £447.86 billion
+- Reformed total tax: £653.01 billion
+- The reform increases tax revenue by £205.15 billion
+
+
+
+The reform significantly increases tax revenue (by £205.15 billion) while slightly increasing benefit spending (by £1.87 billion). The net effect is a substantial positive budgetary impact of £203.27 billion.
+These metrics provide a comprehensive overview of the fiscal implications of the proposed reform. They can help policymakers understand the overall financial impact on government finances, including changes in both revenue and expenditure.
+Note: All monetary values are in GBP (British Pounds).

docs/EconomicImpact/index.md

@@ -0,0 +1,53 @@
+# EconomicImpact Class
+
+## Overview
+
+The `EconomicImpact` class is designed to evaluate the economic impact of a given reform on a specified country. It provides methods to calculate various economic metrics, such as inequality and income distribution, before and after the reform.
+
+## Class Initialization
+
+### `EconomicImpact(reform, country)`
+
+Initializes the `EconomicImpact` class with a specified reform and country.
+
+**Parameters:**
+- `reform` (dict): A dictionary defining the economic reform. The structure of the dictionary should match the expected format for the `Reform` class.
+- `country` (str): The country for which the reform's impact is to be evaluated. Supported values are `"uk"` and `"us"`.
+
+**Example:**
+```python
+from policyengine import EconomicImpact
+
+impact = EconomicImpact(
+    reform={"gov.hmrc.income_tax.rates.uk[0].rate": {"2024-01-01": 0.25}},
+    country="uk"
+)
+```
+
+
+## Example Usage
+
+```python
+from policyengine import EconomicImpact
+
+# Initialize the EconomicImpact class
+impact = EconomicImpact(
+    reform={"gov.hmrc.income_tax.rates.uk[0].rate": {"2024-01-01": 0.25}},
+    country="uk"
+)
+
+# Calculate the Gini coefficient
+result_gini = impact.calculate("inequality/gini")
+print(result_gini)
+# Output: {'baseline': 0.4288962129322326, 'reform': 0.42720356179075414, 'change': -0.001692651141478485}
+
+# Calculate the top 1% income share
+result_top_1 = impact.calculate("inequality/top_1_pct_share")
+print(result_top_1)
+# Output: {'baseline': 0.09121853588608866, 'reform': 0.09301056461517446, 'change': 0.0017920287290857928}
+
+# Calculate the top 10% income share
+result_top_10 = impact.calculate("inequality/top_10_pct_share")
+print(result_top_10)
+# Output: {'baseline': 0.3101681771998754, 'reform': 0.31214840219992496, 'change': 0.0019802250000495736}
+```

docs/Poverty/deep/byage.md

@@ -0,0 +1,66 @@
+# By age
+
+## Overview
+
+The deep poverty by age group metrics provide insights into how a policy reform affects deep poverty rates for different age categories. These metrics are part of the `EconomicImpact` class and can be calculated for children, adults, seniors, and the overall population.
+
+## Available Metrics
+
+1. `poverty/deep/child`: Calculates the deep poverty rate for children.
+2. `poverty/deep/adult`: Calculates the deep poverty rate for adults.
+3. `poverty/deep/senior`: Calculates the deep poverty rate for seniors.
+4. `poverty/deep/age/all`: Calculates the overall deep poverty rate.
+
+## Metric Structure
+
+Each metric returns a dictionary with the following keys:
+- `baseline`: The deep poverty rate before the reform.
+- `reform`: The deep poverty rate after the reform.
+- `change`: The percentage change in the deep poverty rate due to the reform.
+
+All values are rounded to 1 decimal place for the baseline, reform, and change.
+
+## Example Usage
+
+```python
+from policyengine import EconomicImpact
+
+# Initialize the EconomicImpact class with a reform
+impact = EconomicImpact(reform={
+  "gov.hmrc.income_tax.rates.uk[0].rate": {
+    "2024-01-01.2100-12-31": 0.55
+  }
+}, country="uk")
+
+# Calculate deep poverty rates by age group
+child_deep_poverty = impact.calculate("poverty/deep/child")
+adult_deep_poverty = impact.calculate("poverty/deep/adult")
+senior_deep_poverty = impact.calculate("poverty/deep/senior")
+overall_deep_poverty = impact.calculate("poverty/deep/age/all")
+
+# Print the results
+print(f"Child deep poverty: {child_deep_poverty}")
+print(f"Adult deep poverty: {adult_deep_poverty}")
+print(f"Senior deep poverty: {senior_deep_poverty}")
+print(f"Overall deep poverty: {overall_deep_poverty}")
+
+```
+
+## output
+
+```
+Child deep poverty: {'baseline': 2.4, 'reform': 2.5, 'change': 0.7}
+Adult deep poverty: {'baseline': 2.6, 'reform': 2.7, 'change': 3.9}
+Senior deep poverty: {'baseline': 1.8, 'reform': 1.8, 'change': 0.5}
+Overall deep poverty: {'baseline': 2.4, 'reform': 2.5, 'change': 2.7}
+
+```
+
+## Interpretation
+
+In this example:
+
+- The child deep poverty rate increases slightly from 2.4% to 2.5%, a 0.7% increase.
+- The adult deep poverty rate increases from 2.6% to 2.7%, a 3.9% increase.
+- The senior deep poverty rate remains stable at 1.8%, with a minimal 0.5% increase.
+- The overall deep poverty rate increases from 2.4% to 2.5%, a 2.7% increase.

docs/Poverty/deep/bygender.md

@@ -0,0 +1,61 @@
+# By gender
+
+## Overview
+
+The deep poverty by gender metrics provide insights into how a policy reform affects deep poverty rates for different genders. These metrics are part of the `EconomicImpact` class and can be calculated for males, females, and the overall population.
+
+## Available Metrics
+
+1. `poverty/deep/male`: Calculates the deep poverty rate for males.
+2. `poverty/deep/female`: Calculates the deep poverty rate for females.
+3. `poverty/deep/gender/all`: Calculates the overall deep poverty rate.
+
+## Metric Structure
+
+Each metric returns a dictionary with the following keys:
+- `baseline`: The deep poverty rate before the reform.
+- `reform`: The deep poverty rate after the reform.
+- `change`: The percentage change in the deep poverty rate due to the reform.
+
+All values are rounded to 2 decimal places for the baseline and reform, and to 1 decimal place for the change.
+
+## Example Usage
+
+```python
+from policyengine import EconomicImpact
+
+# Initialize the EconomicImpact class with a reform
+impact = EconomicImpact(reform={
+  "gov.hmrc.income_tax.rates.uk[0].rate": {
+    "2024-01-01.2100-12-31": 0.55
+  }
+}, country="uk")
+
+# Calculate deep poverty rates by gender
+male_deep_poverty = impact.calculate("poverty/deep/male")
+female_deep_poverty = impact.calculate("poverty/deep/female")
+overall_deep_poverty = impact.calculate("poverty/deep/gender/all")
+
+# Print the results
+print(f"Male deep poverty: {male_deep_poverty}")
+print(f"Female deep poverty: {female_deep_poverty}")
+print(f"Overall deep poverty: {overall_deep_poverty}")
+
+```
+
+## output 
+
+```
+Male deep poverty: {'baseline': 2.66, 'reform': 2.73, 'change': 2.5}
+Female deep poverty: {'baseline': 2.16, 'reform': 2.23, 'change': 2.9}
+Overall deep poverty: {'baseline': 2.41, 'reform': 2.47, 'change': 2.7}
+
+```
+
+## Interpretation
+
+In this example:
+
+- The baseline male deep poverty rate is 2.66%, which increases to 2.73% after the reform, representing a 2.5% increase.
+- The baseline female deep poverty rate is 2.16%, which increases to 2.23% after the reform, representing a 2.9% increase.
+- The overall deep poverty rate increases from 2.41% to 2.47%, a change of 2.7%.