Add liquid asset variables for SSI modeling (#7329)

* Add liquid asset variables for SSI modeling

Adds three input variables imputed from SIPP in policyengine-us-data:
- bank_account_assets: checking, savings, money market
- stock_assets: stocks and mutual funds
- bond_assets: bonds and government securities

Updates ssi_countable_resources to calculate from these asset categories,
enabling realistic asset-based eligibility testing for SSI.

Co-Authored-By: Claude Opus 4.5 <[email protected]>

* Use adds pattern for ssi_countable_resources

Replace formula with adds attribute referencing parameter file that lists
the asset sources. This separates policy logic (which assets count) from
variable implementation.

Co-Authored-By: Claude Opus 4.5 <[email protected]>

* Fix references to use POMS sections that explicitly list countable resources

The USC only lists exclusions, not what counts. POMS SI 01140.xxx
explicitly defines bank accounts, stocks, and bonds as countable.

Co-Authored-By: Claude Opus 4.5 <[email protected]>

* Add spm_unit_cash_assets aggregation from person-level assets

spm_unit_cash_assets now sums bank_account_assets, stock_assets, and
bond_assets across the SPM unit. This flows through to IL AABD and
MA EAEDC which use spm_unit_cash_assets.

Co-Authored-By: Claude Opus 4.5 <[email protected]>

* Use actual imputed assets for SSI resource test

Remove microsimulation bypass that used random pass rate. Now that
liquid assets are imputed from SIPP, the resource test can use real
calculated values.

- Remove pass_rate.yaml parameter (no longer needed)
- Update README to reflect new methodology
- meets_ssi_resource_test now always uses ssi_countable_resources

Co-Authored-By: Claude Opus 4.5 <[email protected]>

* Add SSI takeup variable and apply in benefit calculation

- Add takes_up_ssi_if_eligible with default_value=True
- Apply takeup multiplier in ssi.py for microsimulation
- Follows new pattern from PR #7326 (no random() in country package)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

* Trigger CI

* Trigger CI

* Add POMS references to asset variables

Co-Authored-By: Claude Opus 4.5 <[email protected]>

---------

Co-authored-by: Claude Opus 4.5 <[email protected]>

Author: MaxGhenis

changelog_entry.yaml

@@ -0,0 +1,8 @@
+- bump: minor
+  changes:
+    added:
+      - Add liquid asset input variables (bank_account_assets, stock_assets, bond_assets), ssi_countable_resources, and spm_unit_cash_assets aggregation
+      - Add takes_up_ssi_if_eligible variable for SSI takeup modeling
+    changed:
+      - SSI resource test now uses actual imputed assets instead of random pass rate
+      - SSI benefit now applies takeup in microsimulation

policyengine_us/parameters/gov/ssa/ssi/eligibility/resources/README.md

@@ -1,10 +1,16 @@
 # Resources
 
-[SSA reported $5.293 billion in SSI expenditures in February 2023](https://www.ssa.gov/policy/docs/quickfacts/stat_snapshot/#table3).
-Adjust `pass_rate.yaml` to match this for SSI in 2023 ($5.293 billion * 12 = $63.5 billion).
+SSI countable resources are now calculated from imputed liquid assets
+(bank accounts, stocks, bonds) rather than using a random pass rate.
+
+The assets are imputed from SIPP in policyengine-us-data and flow through
+to the SSI resource test via `ssi_countable_resources`.
 
-Check with this code:
+Check SSI expenditures with:
 ```python
 from policyengine_us import Microsimulation
 Microsimulation().calc("ssi", map_to="person", period=2023).sum() / 1e9
 ```
+
+[SSA reported $5.293 billion in SSI expenditures in February 2023](https://www.ssa.gov/policy/docs/quickfacts/stat_snapshot/#table3).
+Annual target: $5.293 billion * 12 = $63.5 billion.

policyengine_us/parameters/gov/ssa/ssi/eligibility/resources/countable.yaml

@@ -0,0 +1,20 @@
+description: >-
+  The US counts these asset types as countable resources for SSI eligibility.
+  Excludes home, one vehicle, household goods, burial plots, and retirement accounts.
+values:
+  1975-01-01:
+    # Liquid assets counted as resources
+    - bank_account_assets  # Checking, savings, money market
+    - stock_assets  # Stocks and mutual funds
+    - bond_assets  # Bonds and government securities
+metadata:
+  label: SSI countable resource sources
+  reference:
+    - title: SSA POMS SI 01140.200 - Checking and Savings Accounts
+      href: https://secure.ssa.gov/poms.nsf/lnx/0501140200
+    - title: SSA POMS SI 01140.220 - Stocks
+      href: https://secure.ssa.gov/poms.nsf/lnx/0501140220
+    - title: SSA POMS SI 01140.240 - U.S. Savings Bonds
+      href: https://secure.ssa.gov/poms.nsf/lnx/0501140240
+    - title: SSA POMS SI 01140.250 - Municipal, Corporate and Government Bonds
+      href: https://secure.ssa.gov/poms.nsf/lnx/0501140250

policyengine_us/parameters/gov/ssa/ssi/eligibility/resources/pass_rate.yaml

@@ -5,8 +5,8 @@ class meets_ssi_resource_test(Variable):
     value_type = bool
     entity = Person
     label = "Meets SSI resource test"
-    unit = USD
     definition_period = YEAR
+    reference = "https://secure.ssa.gov/poms.nsf/lnx/0501110000"
 
     def formula(person, period, parameters):
         p = parameters(period).gov.ssa.ssi

policyengine_us/variables/gov/ssa/ssi/eligibility/resources/meets_ssi_resource_test.py

@@ -5,5 +5,15 @@ class ssi_countable_resources(Variable):
     value_type = float
     entity = Person
     label = "SSI countable resources"
+    documentation = (
+        "Countable resources for SSI eligibility. Includes liquid assets "
+        "(bank accounts, stocks, bonds) but excludes home, one vehicle, "
+        "household goods, and retirement accounts per SSI rules."
+    )
     unit = USD
     definition_period = YEAR
+    reference = (
+        "https://secure.ssa.gov/poms.nsf/lnx/0501140000",  # POMS SI 01140.000 - Types of Countable Resources
+    )
+
+    adds = "gov.ssa.ssi.eligibility.resources.countable"

policyengine_us/variables/gov/ssa/ssi/eligibility/resources/ssi_countable_resources.py

@@ -30,8 +30,11 @@ def formula(person, period, parameters):
         individual_max = p.individual * MONTHS_IN_YEAR
         capped_benefit = min_(benefit, individual_max)
 
-        return where(
+        final_benefit = where(
             deeming_applies,
             capped_benefit,
             benefit,
         )
+
+        takes_up = person("takes_up_ssi_if_eligible", period)
+        return final_benefit * takes_up

policyengine_us/variables/gov/ssa/ssi/ssi.py

@@ -0,0 +1,9 @@
+from policyengine_us.model_api import *
+
+
+class takes_up_ssi_if_eligible(Variable):
+    value_type = bool
+    entity = Person
+    label = "Takes up SSI if eligible"
+    definition_period = YEAR
+    default_value = True

policyengine_us/variables/gov/ssa/ssi/takes_up_ssi_if_eligible.py

@@ -0,0 +1,15 @@
+from policyengine_us.model_api import *
+
+
+class bank_account_assets(Variable):
+    value_type = float
+    entity = Person
+    label = "Bank account assets"
+    documentation = (
+        "Value of checking, savings, and money market accounts. "
+        "Imputed from SIPP TVAL_BANK."
+    )
+    unit = USD
+    definition_period = YEAR
+    uprating = "gov.bls.cpi.cpi_u"
+    reference = "https://secure.ssa.gov/poms.nsf/lnx/0501140200"

policyengine_us/variables/household/assets/bank_account_assets.py

@@ -0,0 +1,18 @@
+from policyengine_us.model_api import *
+
+
+class bond_assets(Variable):
+    value_type = float
+    entity = Person
+    label = "Bond assets"
+    documentation = (
+        "Value of bonds and government securities. "
+        "Imputed from SIPP TVAL_BOND."
+    )
+    unit = USD
+    definition_period = YEAR
+    uprating = "gov.bls.cpi.cpi_u"
+    reference = (
+        "https://secure.ssa.gov/poms.nsf/lnx/0501140240",
+        "https://secure.ssa.gov/poms.nsf/lnx/0501140250",
+    )