<< All versions
1.
2.
Skill v1.0.1
currentAutomated scan100/100majiayu000/claude-skill-registry-data/policyengine-aggregation-majiayu000-claude-skill-registr
3 files
──Details
PublishedMay 26, 2026 at 09:40 AM
Content Hashsha256:ec8e8cba63ad25e0...
Git SHAcb443017503a
Bump Typepatch
──Files
Files (1 file, 8.6 KB)
SKILL.md8.6 KBactive
SKILL.md · 330 lines · 8.6 KB
version: "1.0.1" name: policyengine-aggregation description: PolicyEngine aggregation patterns - using adds attribute and add() function for summing variables across entities
PolicyEngine Aggregation Patterns
Essential patterns for summing variables across entities in PolicyEngine.
Quick Decision Guide
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.)
Quick Reference
| Need | Use | Example | |
|---|---|---|---|
| Simple sum | adds | adds = ["var1", "var2"] | |
| Sum from parameters | adds | adds = "gov.path.to.list" | |
| Sum + max_() | add() | max_(0, add(...)) | |
| Sum + where() | add() | where(cond, add(...), 0) | |
| Sum + conditions | add() | if cond: add(...) | |
| Count booleans | adds | adds = ["is_eligible"] |
1. adds Class Attribute (Preferred When Possible)
When to Use
Use adds when a variable is ONLY the sum of other variables with NO additional logic.
Syntax
python
class variable_name(Variable):value_type = floatentity = Entitydefinition_period = PERIOD# Option 1: List of variablesadds = ["variable1", "variable2", "variable3"]# Option 2: Parameter tree pathadds = "gov.path.to.parameter.list"
Key Points
- ✅ No
formula()method needed - ✅ Automatically handles entity aggregation (person → household/tax_unit/spm_unit)
- ✅ Clean and declarative
Example: Simple Income Sum
python
class tanf_gross_earned_income(Variable):value_type = floatentity = SPMUnitlabel = "TANF gross earned income"unit = USDdefinition_period = MONTHadds = ["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
Example: Using Parameter List
python
class income_tax_refundable_credits(Variable):value_type = floatentity = TaxUnitdefinition_period = YEARadds = "gov.irs.credits.refundable"# Parameter file contains list like:# - earned_income_tax_credit# - child_tax_credit# - additional_child_tax_credit
Example: Counting Boolean Values
python
class count_eligible_people(Variable):value_type = intentity = SPMUnitdefinition_period = YEARadds = ["is_eligible_person"]# Automatically sums True (1) and False (0) across members
2. add() Function (When Logic Needed)
When to Use
Use add() inside a formula() when you need:
- To apply
max_(),where(), or conditions - To combine with other operations
- To modify values before/after summing
Syntax
python
from 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 path
Example: With max_() to Prevent Negatives
python
class adjusted_earned_income(Variable):value_type = floatentity = SPMUnitdefinition_period = MONTHdef formula(spm_unit, period, parameters):# Need max_() to clip negative valuesgross = add(spm_unit, period, ["employment_income", "self_employment_income"])return max_(0, gross) # Prevent negative income
Example: With Additional Logic
python
class household_benefits(Variable):value_type = floatentity = Householddefinition_period = YEARdef formula(household, period, parameters):# Sum existing benefitsBENEFITS = ["snap", "tanf", "ssi", "social_security"]existing = add(household, period, BENEFITS)# Add new benefit conditionallynew_benefit = household("special_benefit", period)p = parameters(period).gov.special_benefitif p.include_in_total:return existing + new_benefitreturn existing
Example: Building on Previous Variables
python
class total_deductions(Variable):value_type = floatentity = TaxUnitdefinition_period = YEARdef formula(tax_unit, period, parameters):p = parameters(period).gov.irs.deductions# Get standard deductions using parameter liststandard = add(tax_unit, period, p.standard_items)# Apply phase-out logicincome = tax_unit("adjusted_gross_income", period)phase_out_rate = p.phase_out_ratephase_out_start = p.phase_out_startreduction = max_(0, (income - phase_out_start) * phase_out_rate)return max_(0, standard - reduction)
3. Common Anti-Patterns to Avoid
❌ NEVER: Manual Summing
python
# WRONG - Never do this!def formula(spm_unit, period, parameters):person = spm_unit.membersemployment = person("employment_income", period)self_emp = person("self_employment_income", period)return spm_unit.sum(employment + self_emp) # ❌ BAD
✅ CORRECT: Use adds
python
# RIGHT - Clean and simpleadds = ["employment_income", "self_employment_income"] # ✅ GOOD
❌ WRONG: Using add() When adds Suffices
python
# WRONG - Unnecessary complexitydef formula(spm_unit, period, parameters):return add(spm_unit, period, ["income1", "income2"]) # ❌ Overkill
✅ CORRECT: Use adds
python
# RIGHT - Simpleradds = ["income1", "income2"] # ✅ GOOD
4. Entity Aggregation Explained
When using adds or add(), PolicyEngine automatically handles entity aggregation:
python
class household_total_income(Variable):entity = Household # Higher-level entitydefinition_period = YEARadds = ["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:
- Person → Tax Unit
- Person → SPM Unit
- Person → Household
- Tax Unit → Household
- SPM Unit → Household
5. Parameter Lists
Parameters can define lists of variables to sum:
Parameter file (gov/irs/credits/refundable.yaml):
yaml
description: List of refundable tax creditsvalues:2024-01-01:- earned_income_tax_credit- child_tax_credit- additional_child_tax_credit
Usage in variable:
python
adds = "gov.irs.credits.refundable"# Automatically sums all credits in the list
6. Decision Matrix
| Scenario | Solution | Code | |
|---|---|---|---|
| Sum 2-3 variables | adds attribute | adds = ["var1", "var2"] | |
| Sum many variables | Parameter list | adds = "gov.path.list" | |
| Sum + prevent negatives | add() with max_() | max_(0, add(...)) | |
| Sum + conditional | add() with where() | where(eligible, add(...), 0) | |
| Sum + phase-out | add() with calculation | add(...) - reduction | |
| Count people/entities | adds with boolean | adds = ["is_child"] |
7. Key Principles
- Default to `adds` attribute when variable is only a sum
- Use `add()` function only when additional logic is needed
- Never manually sum with
entity.sum(person(...) + person(...)) - Let PolicyEngine handle entity aggregation automatically
- Use parameter lists for maintainable, configurable sums
Related Skills
- policyengine-period-patterns-skill: For period conversion when summing across different time periods
- policyengine-core-skill: For understanding entity hierarchies and relationships
For Agents
When implementing or reviewing code:
- Check if `adds` can be used before writing a formula
- Prefer declarative over imperative when possible
- Follow existing patterns in the codebase
- Test entity aggregation carefully in YAML tests
- Document parameter lists clearly for
addsreferences
Common Use Cases
Earned Income
python
adds = ["employment_income", "self_employment_income"]
Unearned Income
python
adds = ["interest_income", "dividend_income", "rental_income"]
Total Benefits
python
adds = ["snap", "tanf", "wic", "ssi", "social_security"]
Tax Credits
python
adds = "gov.irs.credits.refundable"
Counting Children
python
adds = ["is_child"] # Returns count of children