Coding
PromptBeginner5 minmarkdown
Markdown Converter
Agent skill for markdown-converter
7
PolicyEngine aggregation patterns - using adds attribute and add() function for summing variables across entities
Sign in to like and favorite skills
Essential patterns for summing variables across entities in PolicyEngine.
Is the variable ONLY a sum of other variables? │ ├─ YES → Use `adds` attribute (NO formula needed!) │ adds = ["var1", "var2"] │ └─ NO → Use `add()` function in formula (when you need max_, where, conditions, etc.)
| Need | Use | Example |
|---|---|---|
| Simple sum | | |
| Sum from parameters | | |
| Sum + max_() | | |
| Sum + where() | | |
| Sum + conditions | | |
| Count booleans | | |
adds Class Attribute (Preferred When Possible)Use
adds when a variable is ONLY the sum of other variables with NO additional logic.
class variable_name(Variable): value_type = float entity = Entity definition_period = PERIOD # Option 1: List of variables adds = ["variable1", "variable2", "variable3"] # Option 2: Parameter tree path adds = "gov.path.to.parameter.list"
formula() method neededclass tanf_gross_earned_income(Variable): value_type = float entity = SPMUnit label = "TANF gross earned income" unit = USD definition_period = MONTH adds = ["employment_income", "self_employment_income"] # NO formula needed! Automatically: # 1. Gets each person's employment_income # 2. Gets each person's self_employment_income # 3. Sums all values across SPM unit members
class income_tax_refundable_credits(Variable): value_type = float entity = TaxUnit definition_period = YEAR adds = "gov.irs.credits.refundable" # Parameter file contains list like: # - earned_income_tax_credit # - child_tax_credit # - additional_child_tax_credit
class count_eligible_people(Variable): value_type = int entity = SPMUnit definition_period = YEAR adds = ["is_eligible_person"] # Automatically sums True (1) and False (0) across members
add() Function (When Logic Needed)Use
add() inside a formula() when you need:
max_(), where(), or conditionsfrom policyengine_us.model_api import * def formula(entity, period, parameters): result = add(entity, period, variable_list)
Parameters:
entity: The entity to operate onperiod: The time period for calculationvariable_list: List of variable names or parameter pathclass adjusted_earned_income(Variable): value_type = float entity = SPMUnit definition_period = MONTH def formula(spm_unit, period, parameters): # Need max_() to clip negative values gross = add(spm_unit, period, ["employment_income", "self_employment_income"]) return max_(0, gross) # Prevent negative income
class household_benefits(Variable): value_type = float entity = Household definition_period = YEAR def formula(household, period, parameters): # Sum existing benefits BENEFITS = ["snap", "tanf", "ssi", "social_security"] existing = add(household, period, BENEFITS) # Add new benefit conditionally new_benefit = household("special_benefit", period) p = parameters(period).gov.special_benefit if p.include_in_total: return existing + new_benefit return existing
class total_deductions(Variable): value_type = float entity = TaxUnit definition_period = YEAR def formula(tax_unit, period, parameters): p = parameters(period).gov.irs.deductions # Get standard deductions using parameter list standard = add(tax_unit, period, p.standard_items) # Apply phase-out logic income = tax_unit("adjusted_gross_income", period) phase_out_rate = p.phase_out_rate phase_out_start = p.phase_out_start reduction = max_(0, (income - phase_out_start) * phase_out_rate) return max_(0, standard - reduction)
# WRONG - Never do this! def formula(spm_unit, period, parameters): person = spm_unit.members employment = person("employment_income", period) self_emp = person("self_employment_income", period) return spm_unit.sum(employment + self_emp) # ❌ BAD
# RIGHT - Clean and simple adds = ["employment_income", "self_employment_income"] # ✅ GOOD
# WRONG - Unnecessary complexity def formula(spm_unit, period, parameters): return add(spm_unit, period, ["income1", "income2"]) # ❌ Overkill
# RIGHT - Simpler adds = ["income1", "income2"] # ✅ GOOD
When using
adds or add(), PolicyEngine automatically handles entity aggregation:
class household_total_income(Variable): entity = Household # Higher-level entity definition_period = YEAR adds = ["employment_income", "self_employment_income"] # employment_income is defined for Person (lower-level) # PolicyEngine automatically: # 1. Gets employment_income for each person in household # 2. Gets self_employment_income for each person # 3. Sums all values to household level
This works across all entity hierarchies:
Parameters can define lists of variables to sum:
Parameter file (
gov/irs/credits/refundable.yaml):
description: List of refundable tax credits values: 2024-01-01: - earned_income_tax_credit - child_tax_credit - additional_child_tax_credit
Usage in variable:
adds = "gov.irs.credits.refundable" # Automatically sums all credits in the list
| Scenario | Solution | Code |
|---|---|---|
| Sum 2-3 variables | attribute | |
| Sum many variables | Parameter list | |
| Sum + prevent negatives | with | |
| Sum + conditional | with | |
| Sum + phase-out | with calculation | |
| Count people/entities | with boolean | |
adds attribute when variable is only a sumadd() function only when additional logic is neededentity.sum(person(...) + person(...))When implementing or reviewing code:
adds can be used before writing a formulaadds referencesadds = ["employment_income", "self_employment_income"]
adds = ["interest_income", "dividend_income", "rental_income"]
adds = ["snap", "tanf", "wic", "ssi", "social_security"]
adds = "gov.irs.credits.refundable"
adds = ["is_child"] # Returns count of children