Merge branch 'main' into DistributionalImpactW

Author: masterismail

docs/Distributional/ByIncomeDecile/average.md

@@ -0,0 +1,52 @@
+# Income Distribution by Average
+
+## Overview
+
+The income distribution by average metrics provide insights into how a policy reform affects the average income across different income deciles. These metrics are part of the `EconomicImpact` class and measure the average change in household net income due to the reform.
+
+## Available Metrics
+
+1. `distributional/by_income/average`: Calculates the average change in household net income by income decile.
+
+## Metric Structure
+
+Each metric returns a dictionary with the following keys:
+- `average`: A dictionary where the key is the income decile, and the value is the average change in income for that decile.
+
+The values represent the change in income due to the policy reform, rounded to several decimal places.
+
+## 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 average income change by income decile
+average_income_change = impact.calculate("distributional/by_income/average")
+
+# Print the result
+print(f"Average income change: {average_income_change}")
+```
+
+## Output
+
+```
+Average income change: {'average': {1: -1542.53, 2: -1982.53, 3: -4556.84, 4: -5370.20, 5: -7216.05, 6: -7591.30, 7: -9211.03, 8: -9648.62, 9: -11506.89, 10: -14378.30, 11: -13195.00}}
+```
+
+## Interpretation
+
+In this example:
+
+- The average income change is negative across all deciles, indicating a reduction in household net income due to the policy reform.
+- The change is most significant in the higher deciles, with the highest decrease observed in the top decile (11), at -13,195.00.
+- The impact is progressively less severe in lower deciles, with the smallest decrease observed in the lowest decile (1), at -1,542.53.
+
+---
+
+Let me know if you need any further adjustments!

docs/Distributional/ByIncomeDecile/index.md

@@ -0,0 +1 @@
+# By income

docs/Distributional/ByIncomeDecile/relative.md

@@ -0,0 +1,49 @@
+# Income Decile by Relative Change
+
+## Overview
+
+The income decile by relative change metrics provide insights into how a policy reform affects household net income across different income deciles in relative terms. These metrics are part of the `EconomicImpact` class and measure the relative change in income due to the reform, expressed as a percentage of the baseline income.
+
+## Available Metrics
+
+1. `distributional/by_income/relative`: Calculates the relative change in household net income by income decile.
+
+## Metric Structure
+
+Each metric returns a dictionary with the following keys:
+- `relative`: A dictionary where the key is the income decile, and the value is the relative change in income for that decile. The relative change is expressed as a percentage of the baseline income.
+
+The values are rounded to several decimal places.
+
+## 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 relative income change by income decile
+relative_income_change = impact.calculate("distributional/by_income/relative")
+
+# Print the result
+print(f"Relative income change: {relative_income_change}")
+```
+
+## Output
+
+```
+Relative income change: {'relative': {1: -0.0704, 2: -0.0809, 3: -0.1465, 4: -0.1559, 5: -0.1784, 6: -0.1823, 7: -0.1986, 8: -0.1832, 9: -0.1960, 10: -0.1392, 11: -0.0281}}
+```
+
+## Interpretation
+
+In this example:
+
+- The relative income change is negative across all deciles, indicating a reduction in household net income as a percentage of the baseline.
+- The highest relative decrease is observed in the 7th decile, with a reduction of approximately 19.86%.
+- The smallest relative decrease is in the 11th decile, at about 2.81%.
+- The relative changes vary by decile, reflecting the impact of the policy reform on different income groups.

docs/Distributional/ByWealthDecile/average.md

@@ -0,0 +1,48 @@
+# Average
+
+## Overview
+
+The wealth distribution by average metrics provide insights into how a policy reform affects the average wealth across different wealth deciles. These metrics are part of the `EconomicImpact` class and measure the average change in household net wealth due to the reform.
+
+## Available Metrics
+
+1. `distributional/by_wealth/average`: Calculates the average change in household net wealth by wealth decile.
+
+## Metric Structure
+
+Each metric returns a dictionary with the following keys:
+- `average`: A dictionary where the key is the wealth decile, and the value is the average change in wealth for that decile.
+
+The values represent the change in wealth due to the policy reform, rounded to several decimal places.
+
+## 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 average wealth change by wealth decile
+average_wealth_change = impact.calculate("distributional/by_wealth/average")
+
+# Print the result
+print(f"Average wealth change: {average_wealth_change}")
+```
+
+## Output
+
+```
+Average wealth change: {'average': {1: -1542.53, 2: -1982.53, 3: -4556.84, 4: -5370.20, 5: -7216.05, 6: -7591.30, 7: -9211.03, 8: -9648.62, 9: -11506.89, 10: -14378.30, 11: -13195.00}}
+```
+
+## Interpretation
+
+In this example:
+
+- The average wealth change is negative across all deciles, indicating a reduction in household net wealth due to the policy reform.
+- The impact is most severe in the highest deciles, with the highest decrease observed in the top decile (11), at -13,195.00.
+- The decrease in wealth is progressively less severe in lower deciles, with the smallest decrease observed in the lowest decile (1), at -1,542.53.

docs/Distributional/ByWealthDecile/index.md

@@ -0,0 +1 @@
+# by wealth

docs/Distributional/ByWealthDecile/relative.md

@@ -0,0 +1,48 @@
+# Relative 
+
+## Overview
+
+The wealth distribution by relative change metrics provide insights into how a policy reform affects the relative change in household net income across different wealth deciles. These metrics are part of the `EconomicImpact` class and measure the proportional change in income due to the reform.
+
+## Available Metrics
+
+1. `distributional/by_wealth/relative`: Calculates the relative change in household net income by wealth decile.
+
+## Metric Structure
+
+Each metric returns a dictionary with the following keys:
+- `relative`: A dictionary where the key is the wealth decile, and the value is the relative change in income for that decile.
+
+The relative change is calculated as the ratio of the change in income to the baseline income, providing a measure of how income changes proportionally within each decile.
+
+## 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 relative income change by wealth decile
+relative_income_change = impact.calculate("distributional/by_wealth/relative")
+
+# Print the result
+print(f"Relative income change: {relative_income_change}")
+```
+
+## Output
+
+```
+Relative income change: {'relative': {1: -0.0704, 2: -0.0809, 3: -0.1465, 4: -0.1559, 5: -0.1784, 6: -0.1823, 7: -0.1986, 8: -0.1832, 9: -0.1960, 10: -0.1392, 11: -0.0281}}
+```
+
+## Interpretation
+
+In this example:
+
+- The relative income change is negative across all wealth deciles, indicating a proportional decrease in household net income due to the policy reform.
+- The relative change is highest in the higher deciles, with the most significant decrease observed in the top decile (11), at -0.0281 (2.81% decrease).
+- The impact is also noticeable in the lower deciles, with the smallest relative decrease observed in the lowest decile (1), at -0.0704 (7.04% decrease).

docs/Distributional/index.md

@@ -0,0 +1 @@
+# Distributional

docs/Inequality/index.md

@@ -0,0 +1 @@
+# Inequality

docs/Inequality/inequality.md

@@ -0,0 +1,63 @@
+# Inequality Impact
+
+## Overview
+
+The inequality impact metrics provide insights into how a policy reform affects income distribution. These metrics are part of the `EconomicImpact` class and include measures of income inequality and concentration of income among the top earners.
+
+## Available Metrics
+
+1. **`inequality/gini`**: Calculates the Gini coefficient, which measures income inequality.
+2. **`inequality/top_1_pct_share`**: Calculates the income share of the top 1% of earners.
+3. **`inequality/top_10_pct_share`**: Calculates the income share of the top 10% of earners.
+
+## Metric Structure
+
+Each metric returns a dictionary with the following keys:
+- **`baseline`**: The metric value before the reform.
+- **`reform`**: The metric value after the reform.
+- **`change`**: The absolute change in the metric value due to the reform.
+- **`change_percentage`**: The percentage change in the metric value due to the reform (only for Gini coefficient and top 1% share).
+
+All values are rounded to 2 decimal places for baseline, reform, change, and change percentage.
+
+## 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": 0.25}},
+    country="uk"
+)
+
+# Calculate Gini coefficient impact
+gini_impact = impact.calculate("inequality/gini")
+
+# Calculate top 1% income share impact
+top_1_pct_share = impact.calculate("inequality/top_1_pct_share")
+
+# Calculate top 10% income share impact
+top_10_pct_share = impact.calculate("inequality/top_10_pct_share")
+
+# Print the results
+print(f"Gini coefficient impact: {gini_impact}")
+print(f"Top 1% income share impact: {top_1_pct_share}")
+print(f"Top 10% income share impact: {top_10_pct_share}")
+```
+
+## Output
+
+```
+Gini coefficient impact: {'baseline': 0.43, 'reform': 0.43, 'change': -0.00, 'change_percentage': -0.39}
+Top 1% income share impact: {'baseline': 0.09, 'reform': 0.09, 'change': 0.00, 'change_percentage': 1.96}
+Top 10% income share impact: {'baseline': 0.31, 'reform': 0.31, 'change': 0.00, 'change_percentage': 0.64}
+```
+
+## Interpretation
+
+In this example:
+
+- The Gini coefficient decreases slightly from 0.43 to 0.43, indicating a small reduction in income inequality.
+- The income share of the top 1% increases from 9.12% to 9.30%, reflecting a slight rise in concentration among the highest earners.
+- The income share of the top 10% increases from 31.02% to 31.21%, showing a minor rise in the share of income held by the top 10% of earners.

docs/WinnersAndLosers/byincomedecile.md

@@ -0,0 +1,78 @@
+# by Income Decile
+
+## Overview
+
+The winners and losers by income decile metrics provide insights into how a policy reform affects income changes across different income deciles. These metrics help to understand the distribution of income gains and losses among various income groups. The analysis is categorized based on the percentage change in income and provides a breakdown for each decile.
+
+## Available Metrics
+
+1. `winners_and_losers/by_income_decile`: Evaluates the income changes across income deciles and categorizes the population based on the magnitude of income gain or loss.
+
+## Metric Structure
+
+Each metric returns a dictionary with the following keys:
+- `result`: Contains two sub-dictionaries:
+  - `deciles`: Breakdown of the population within each decile into categories based on income change.
+  - `all`: Summary statistics showing the average percentage of the population in each category across all deciles.
+
+### Income Change Categories
+
+The categories used for income change are:
+- **Lose more than 5%**: Percentage of the population experiencing an income loss greater than 5%.
+- **Lose less than 5%**: Percentage of the population experiencing an income loss less than 5%.
+- **No change**: Percentage of the population experiencing no change in income.
+- **Gain less than 5%**: Percentage of the population experiencing an income gain less than 5%.
+- **Gain more than 5%**: Percentage of the population experiencing an income gain greater than 5%.
+
+## 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 income change metrics by income decile
+by_income = impact.calculate("winners_and_losers/by_income_decile")
+by_wealth = impact.calculate("winners_and_losers/by_wealth_decile")
+
+# Print the results
+print(f"By Income Decile: {by_income}")
+print(f"By Wealth Decile: {by_wealth}")
+```
+
+## Output
+
+### By Income Decile
+
+```python
+{
+    'result': {
+        'deciles': {
+            'Lose more than 5%': [16.8, 21.8, 28.9, 52.2, 72.4, 85.4, 91.9, 93.0, 98.0, 95.4],
+            'Lose less than 5%': [2.7, 4.8, 5.8, 9.0, 5.2, 0.3, 0.6, 0.1, 0.0, 1.4],
+            'No change': [80.5, 73.4, 65.3, 38.8, 22.4, 14.3, 7.5, 6.9, 1.9, 3.1],
+            'Gain less than 5%': [0.0, 0.1, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
+            'Gain more than 5%': [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
+        },
+        'all': {
+            'Lose more than 5%': 65.6,
+            'Lose less than 5%': 3.0,
+            'No change': 31.4,
+            'Gain less than 5%': 0.0,
+            'Gain more than 5%': 0.0
+        }
+    }
+}
+```
+
+## Interpretation
+
+In this example:
+
+- For income deciles, the percentage of people losing more than 5% increases from the lower deciles to the higher deciles, with a substantial concentration of losses in the top deciles. The majority of the population experiences no change in income, with very few gaining or losing within small ranges.
+- For wealth deciles, a similar pattern is observed, with a significant proportion of the population in higher deciles experiencing losses greater than 5%, while most people in lower deciles experience no change.
+