Skip to content

Replace SPM program-unit simplification with program-specific rules #1

@MaxGhenis

Description

@MaxGhenis

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:

  1. A source-normalized person graph: persons, households, parent pointers, spouse/partner links, age, relationship codes, disability flags, student flags, and source-specific metadata.
  2. Partition-style constructors where each person belongs to one unit, e.g. SNAP as an approximation when applicable.
  3. Ego-unit constructors where each focal person gets a membership set, e.g. Medicaid MAGI.
  4. Diagnostics comparing native IDs, SPM simplification, and program-specific outputs when source data provides references.
  5. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions