Context
microunit currently uses SPM units as the temporary simplification for program-specific units. This is intentional for the first Microplex integration: it keeps the unit pipeline moving while preserving a single relationship-based unit layer.
The current simplification appears in:
assign_program_partition_from_spm
assign_ego_units_from_spm
assign_snap_partition default fallback
medicaid_magi_from_spm
Why this needs to get better
SPM units are not the correct unit definition for many programs:
- SNAP households depend on food purchase/preparation, elderly/disabled exceptions, and disqualified members.
- Medicaid MAGI households are focal-person units and can overlap within the same physical household.
- SSI is closer to individual/couple units.
- TANF assistance units vary by state.
- ACA/PTC uses tax-family and coverage-household concepts.
- Housing assistance units can follow still different household rules.
Using SPM units for all of these will likely bias program eligibility and benefit simulations, especially in multi-family households, households with unrelated members, cohabiters, and mixed tax/SPM arrangements.
Proposed direction
Build program-specific constructors on top of shared primitives:
- A source-normalized person graph: persons, households, parent pointers, spouse/partner links, age, relationship codes, disability flags, student flags, and source-specific metadata.
- Partition-style constructors where each person belongs to one unit, e.g. SNAP as an approximation when applicable.
- Ego-unit constructors where each focal person gets a membership set, e.g. Medicaid MAGI.
- Diagnostics comparing native IDs, SPM simplification, and program-specific outputs when source data provides references.
- Microplex export helpers so
microplex-us can choose between spm_simplification and true program units explicitly.
Acceptance criteria
- Keep the SPM simplification available behind an explicit flag or named helper.
- Add at least one true program-specific constructor beyond SPM/tax.
- Add tests showing cases where SPM simplification and the true program unit differ.
- Add diagnostics that report how often the true constructor differs from SPM units within households.
- Wire
microplex-us to record which unit mode was used in generated artifacts.
Initial candidate scope
Start with SNAP or Medicaid MAGI:
- SNAP is likely easier as a partition-style constructor.
- Medicaid MAGI is more important for proving
EgoUnitMembership because units overlap by focal person.
Context
microunitcurrently uses SPM units as the temporary simplification for program-specific units. This is intentional for the first Microplex integration: it keeps the unit pipeline moving while preserving a single relationship-based unit layer.The current simplification appears in:
assign_program_partition_from_spmassign_ego_units_from_spmassign_snap_partitiondefault fallbackmedicaid_magi_from_spmWhy this needs to get better
SPM units are not the correct unit definition for many programs:
Using SPM units for all of these will likely bias program eligibility and benefit simulations, especially in multi-family households, households with unrelated members, cohabiters, and mixed tax/SPM arrangements.
Proposed direction
Build program-specific constructors on top of shared primitives:
microplex-uscan choose betweenspm_simplificationand true program units explicitly.Acceptance criteria
microplex-usto record which unit mode was used in generated artifacts.Initial candidate scope
Start with SNAP or Medicaid MAGI:
EgoUnitMembershipbecause units overlap by focal person.