PolicyEngine aggregation patterns - using adds attribute and add() function for summing variables across entities
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 | `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"]` |
---
Use `adds` when a variable is **ONLY** the sum of other variables with **NO additional logic**.
```python
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"
```
```python
class 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
```
```python
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
```
```python
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
```
---
Use `add()` inside a `formula()` when you need:
```python
from policyengine_us.model_api import *
def formula(entity, period, parameters):
result = add(entity, period, variable_list)
```
**Parameters:**
```python
class 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
```
```python
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
```
```python
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)
```
---
```python
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
```
```python
adds = ["employment_income", "self_employment_income"] # ✅ GOOD
```
```python
def formula(spm_unit, period, parameters):
return add(spm_unit, period, ["income1", "income2"]) # ❌ Overkill
```
```python
adds = ["income1", "income2"] # ✅ GOOD
```
---
When using `adds` or `add()`, PolicyEngine automatically handles entity aggregation:
```python
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`):
```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**:
```python
adds = "gov.irs.credits.refundable"
```
---
| 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"]` |
---
1. **Default to `adds` attribute** when variable is only a sum
2. **Use `add()` function** only when additional logic is needed
3. **Never manually sum** with `entity.sum(person(...) + person(...))`
4. **Let PolicyEngine handle** entity aggregation automatically
5. **Use parameter lists** for maintainable, configurable sums
---
---
When implementing or reviewing code:
1. **Check if `adds` can be used** before writing a formula
2. **Prefer declarative over imperative** when possible
3. **Follow existing patterns** in the codebase
4. **Test entity aggregation** carefully in YAML tests
5. **Document parameter lists** clearly for `adds` references
---
```python
adds = ["employment_income", "self_employment_income"]
```
```python
adds = ["interest_income", "dividend_income", "rental_income"]
```
```python
adds = ["snap", "tanf", "wic", "ssi", "social_security"]
```
```python
adds = "gov.irs.credits.refundable"
```
```python
adds = ["is_child"] # Returns count of children
```
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/policyengine-aggregation/raw