Simulate outcomes for a large population

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.

from policyengine import Simulation

sim = Simulation(
    scope="macro",
    country="us",
    time_period=2025,
)

result = sim.calculate_single_economy()

/opt/hostedtoolcache/Python/3.11.12/x64/lib/python3.11/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html
  from .autonotebook import tqdm as notebook_tqdm

Using Hugging Face for download.

Output schema

calculate_single_economy or calculate (when scope=macro and reform=None) return the following schema.

from policyengine.outputs.macro.single.calculate_single_economy import SingleEconomy

SingleEconomy.model_json_schema()

{'properties': {'total_net_income': {'title': 'Total Net Income',
   'type': 'number'},
  'employment_income_hh': {'items': {'type': 'number'},
   'title': 'Employment Income Hh',
   'type': 'array'},
  'self_employment_income_hh': {'items': {'type': 'number'},
   'title': 'Self Employment Income Hh',
   'type': 'array'},
  'total_tax': {'title': 'Total Tax', 'type': 'number'},
  'total_state_tax': {'title': 'Total State Tax', 'type': 'number'},
  'total_benefits': {'title': 'Total Benefits', 'type': 'number'},
  'household_net_income': {'items': {'type': 'number'},
   'title': 'Household Net Income',
   'type': 'array'},
  'equiv_household_net_income': {'items': {'type': 'number'},
   'title': 'Equiv Household Net Income',
   'type': 'array'},
  'household_income_decile': {'items': {'type': 'integer'},
   'title': 'Household Income Decile',
   'type': 'array'},
  'household_market_income': {'items': {'type': 'number'},
   'title': 'Household Market Income',
   'type': 'array'},
  'household_wealth_decile': {'anyOf': [{'items': {'type': 'integer'},
     'type': 'array'},
    {'type': 'null'}],
   'title': 'Household Wealth Decile'},
  'household_wealth': {'anyOf': [{'items': {'type': 'number'},
     'type': 'array'},
    {'type': 'null'}],
   'title': 'Household Wealth'},
  'in_poverty': {'items': {'type': 'boolean'},
   'title': 'In Poverty',
   'type': 'array'},
  'person_in_poverty': {'items': {'type': 'boolean'},
   'title': 'Person In Poverty',
   'type': 'array'},
  'person_in_deep_poverty': {'items': {'type': 'boolean'},
   'title': 'Person In Deep Poverty',
   'type': 'array'},
  'poverty_gap': {'title': 'Poverty Gap', 'type': 'number'},
  'deep_poverty_gap': {'title': 'Deep Poverty Gap', 'type': 'number'},
  'person_weight': {'items': {'type': 'number'},
   'title': 'Person Weight',
   'type': 'array'},
  'household_weight': {'items': {'type': 'number'},
   'title': 'Household Weight',
   'type': 'array'},
  'household_count_people': {'items': {'type': 'integer'},
   'title': 'Household Count People',
   'type': 'array'},
  'gini': {'title': 'Gini', 'type': 'number'},
  'top_10_percent_share': {'title': 'Top 10 Percent Share', 'type': 'number'},
  'top_1_percent_share': {'title': 'Top 1 Percent Share', 'type': 'number'},
  'is_male': {'items': {'type': 'boolean'},
   'title': 'Is Male',
   'type': 'array'},
  'race': {'anyOf': [{'items': {'type': 'string'}, 'type': 'array'},
    {'type': 'null'}],
   'title': 'Race'},
  'age': {'items': {'type': 'integer'}, 'title': 'Age', 'type': 'array'},
  'substitution_lsr': {'title': 'Substitution Lsr', 'type': 'number'},
  'income_lsr': {'title': 'Income Lsr', 'type': 'number'},
  'budgetary_impact_lsr': {'title': 'Budgetary Impact Lsr', 'type': 'number'},
  'income_lsr_hh': {'items': {'type': 'number'},
   'title': 'Income Lsr Hh',
   'type': 'array'},
  'substitution_lsr_hh': {'items': {'type': 'number'},
   'title': 'Substitution Lsr Hh',
   'type': 'array'},
  'weekly_hours': {'anyOf': [{'type': 'number'}, {'type': 'null'}],
   'title': 'Weekly Hours'},
  'weekly_hours_income_effect': {'anyOf': [{'type': 'number'},
    {'type': 'null'}],
   'title': 'Weekly Hours Income Effect'},
  'weekly_hours_substitution_effect': {'anyOf': [{'type': 'number'},
    {'type': 'null'}],
   'title': 'Weekly Hours Substitution Effect'},
  'type': {'enum': ['general', 'cliff'], 'title': 'Type', 'type': 'string'},
  'programs': {'anyOf': [{'additionalProperties': {'type': 'number'},
     'type': 'object'},
    {'type': 'null'}],
   'title': 'Programs'},
  'cliff_gap': {'anyOf': [{'type': 'number'}, {'type': 'null'}],
   'default': None,
   'title': 'Cliff Gap'},
  'cliff_share': {'anyOf': [{'type': 'number'}, {'type': 'null'}],
   'default': None,
   'title': 'Cliff Share'}},
 'required': ['total_net_income',
  'employment_income_hh',
  'self_employment_income_hh',
  'total_tax',
  'total_state_tax',
  'total_benefits',
  'household_net_income',
  'equiv_household_net_income',
  'household_income_decile',
  'household_market_income',
  'household_wealth_decile',
  'household_wealth',
  'in_poverty',
  'person_in_poverty',
  'person_in_deep_poverty',
  'poverty_gap',
  'deep_poverty_gap',
  'person_weight',
  'household_weight',
  'household_count_people',
  'gini',
  'top_10_percent_share',
  'top_1_percent_share',
  'is_male',
  'race',
  'age',
  'substitution_lsr',
  'income_lsr',
  'budgetary_impact_lsr',
  'income_lsr_hh',
  'substitution_lsr_hh',
  'weekly_hours',
  'weekly_hours_income_effect',
  'weekly_hours_substitution_effect',
  'type',
  'programs'],
 'title': 'SingleEconomy',
 'type': 'object'}