Merge pull request #1 from masterismail/PovertyDocs

Poverty docs

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%.

docs/Poverty/deep/index.md

@@ -0,0 +1,32 @@
+# Deep poverty
+
+## Overview
+
+Deep poverty metrics focus on measuring severe economic hardship, typically defined as living below 50% of the poverty line. These metrics provide critical information about the most economically vulnerable segments of the population.
+
+## Available Metrics
+
+Our deep poverty analysis includes the following categories:
+
+1. **Deep Poverty by Age Group**
+   - Child Deep Poverty
+   - Adult Deep Poverty
+   - Senior Deep Poverty
+   - Overall Deep Poverty
+
+2. **Deep Poverty by Gender**
+   - Male Deep Poverty
+   - Female Deep Poverty
+   - Overall Deep Poverty
+
+## Significance
+
+Deep poverty metrics are crucial for:
+- Identifying the most economically vulnerable populations
+- Assessing the severity of poverty beyond standard poverty measures
+- Evaluating the impact of policies on extreme poverty
+- Guiding targeted interventions for those in severe economic distress
+
+## Usage
+
+These metrics can be accessed using the `EconomicImpact` class. For detailed information on each metric, please refer to the respective documentation pages.

docs/Poverty/index.md

@@ -0,0 +1 @@
+# Poverty impact

docs/Poverty/regular/byage.md

@@ -0,0 +1,63 @@
+# By age
+
+## Overview
+
+The regular poverty by age group metrics provide insights into how a policy reform affects 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/regular/child`: Calculates the poverty rate for children.
+2. `poverty/regular/adult`: Calculates the poverty rate for adults.
+3. `poverty/regular/senior`: Calculates the poverty rate for seniors.
+4. `poverty/regular/all`: Calculates the overall poverty rate.
+
+## Metric Structure
+
+Each metric returns a dictionary with the following keys:
+- `baseline`: The poverty rate before the reform.
+- `reform`: The poverty rate after the reform.
+- `change`: The percentage change in the 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 poverty rates by age group
+child_poverty = impact.calculate("poverty/regular/child")
+adult_poverty = impact.calculate("poverty/regular/adult")
+senior_poverty = impact.calculate("poverty/regular/senior")
+overall_poverty = impact.calculate("poverty/regular/all")
+
+# Print the results
+print(f"Child poverty: {child_poverty}")
+print(f"Adult poverty: {adult_poverty}")
+print(f"Senior poverty: {senior_poverty}")
+print(f"Overall poverty: {overall_poverty}")
+
+```
+## Example Output
+
+```
+Child poverty: {'baseline': 0.32, 'reform': 0.36, 'change': 10.1}
+Adult poverty: {'baseline': 0.17, 'reform': 0.19, 'change': 8.4}
+Senior poverty: {'baseline': 0.13, 'reform': 0.17, 'change': 30.5}
+Overall poverty: {'baseline': 0.20, 'reform': 0.22, 'change': 11.7}
+```
+## Interpretation
+
+In this example:
+
+- The child poverty rate increases from 32% to 36%, a 10.1% increase.
+- The adult poverty rate increases from 17% to 19%, an 8.4% increase.
+- The senior poverty rate increases from 13% to 17%, a significant 30.5% increase.
+- The overall poverty rate increases from 20% to 22%, an 11.7% increase.

docs/Poverty/regular/bygender.md

@@ -0,0 +1,58 @@
+# By gender
+
+## Overview
+The regular poverty by gender metrics provide insights into how a policy reform affects 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
+- `poverty/regular/male`: Calculates the poverty rate for males.
+- `poverty/regular/female`: Calculates the poverty rate for females.
+- `poverty/regular/gender/all`: Calculates the overall poverty rate.
+
+## Metric Structure
+Each metric returns a dictionary with the following keys:
+- `baseline`: The poverty rate before the reform.
+- `reform`: The poverty rate after the reform.
+- `change`: The percentage change in the 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 poverty rates by gender
+male_poverty = impact.calculate("poverty/regular/male")
+female_poverty = impact.calculate("poverty/regular/female")
+overall_poverty = impact.calculate("poverty/regular/gender/all")
+
+# Print the results
+print(f"Male poverty: {male_poverty}")
+print(f"Female poverty: {female_poverty}")
+print(f"Overall poverty: {overall_poverty}")
+```
+
+## Example output 
+
+```
+Male poverty: {'baseline': 0.18, 'reform': 0.21, 'change': 12.9}
+Female poverty: {'baseline': 0.21, 'reform': 0.23, 'change': 10.7}
+Overall poverty: {'baseline': 0.20, 'reform': 0.22, 'change': 11.7}
+
+```
+
+## Interpretation
+
+In this example:
+
+- The baseline male poverty rate is 18%, which increases to 21% after the reform, representing a 12.9% increase.
+- The baseline female poverty rate is 21%, which increases to 23% after the reform, representing a 10.7% increase.
+- The overall poverty rate increases from 20% to 22%, a change of 11.7%.
+
+These metrics can help policymakers understand the differential impact of a reform on poverty rates across genders.

docs/Poverty/regular/index.md

@@ -0,0 +1,32 @@
+# Regular poverty
+
+## Overview
+
+Regular poverty metrics measure the proportion of individuals living below the standard poverty line. These metrics provide crucial insights into the effectiveness of economic policies and their impact on different demographic groups.
+
+## Available Metrics
+
+Our regular poverty analysis includes the following categories:
+
+1. **Poverty by Age Group**
+   - Child Poverty
+   - Adult Poverty
+   - Senior Poverty
+   - Overall Poverty
+
+2. **Poverty by Gender**
+   - Male Poverty
+   - Female Poverty
+   - Overall Poverty
+
+## Importance
+
+Regular poverty metrics are essential for:
+- Assessing the overall economic well-being of a population
+- Identifying vulnerable groups most affected by poverty
+- Evaluating the effectiveness of poverty reduction policies
+- Comparing poverty rates across different demographics
+
+## Usage
+
+These metrics can be accessed using the `EconomicImpact` class. For detailed information on each metric, please refer to the respective documentation pages.