spm-calculator

Calculate Supplemental Poverty Measure (SPM) thresholds with published national inputs and conditional CE/ACS rolling forecasts. The package works offline for standalone calculations and supplies the same forecast artifact to optional PolicyEngine, Microcosm Frame and actual Axiom core integrations.

This checkout is the local 1.0.0 candidate. These instructions describe this source, not an announced PyPI release or production website, wrapper or API promotion.

Version 1.0 changes the public calculation API and removes the legacy modules. Existing PolicyEngine environments require coordinated dependency pins; read the 1.0 migration guide before upgrading.

Published 2025 inputs

The national reference family has two SPM adults and two children. The bundled 2025 thresholds and tenure-specific housing shares come from the BLS workbooks:

The BLS housing-share workbook supplies the shelter-plus-utilities fractions. The published-cell receipt links threshold cells to the source workbooks and rounded BLS page values. The source and validation guide distinguishes these published values from replicated or projected amounts. A published national base does not make a local 2025 estimate an official Census threshold: the selected area's rent input can be modeled.

Install this candidate locally

From this checkout, using Python 3.9 or newer:

python -m pip install -e .

A calculation needs no Census API key or source download. Optional integrations require their own runtime installations; see the linked guides below.

Calculate a threshold

from spm_calculator import SPMUnit, load_forecast

forecast = load_forecast()
result = forecast.calculate_unit(
    SPMUnit(
        unit_id="example-family",
        num_adults=2,
        num_children=2,
        tenure="renter",
        year=2025,
        geography_kind="national",
        resources=40_000,
    )
)
print(f"Threshold: ${result['threshold']:,.2f}")  # $41,700.56
print(result["is_in_poverty"])  # True
print(forecast.forecast_id, forecast.content_sha256)

Here resources means already measured annual SPM resources, not gross income. Omit it when only a threshold is needed. SPMUnit accepts already classified counts. In person-based integrations, an adult is a person aged at least 18, or aged at least 15 with an explicit SPM independence role. Native SPM membership and source roles determine those counts; household size alone does not.

For a county, resolve its assignment for the target year, then calculate with that SPM estimation area:

from spm_calculator import SPMUnit, load_forecast

forecast = load_forecast()
assignment = forecast.resolve_county(
    2026, "06037", county_vintage="2020", scenario="ce_trend"
)
result = forecast.calculate_unit(
    SPMUnit(
        "example-family", 2, 2, "renter", 2026,
        geography_kind=assignment["kind"],
        geography_id=assignment["area_id"],
    ),
    scenario="ce_trend",
)
print(result["threshold"], result["national_status"])
print(result["provenance"]["geography"])

County is an assignment input, not an estimation unit. Use forecast.areas_for_year(year, scenario=...) to list that year's supported areas and their statuses. metro is the API kind for named MSAs, state residual metro/nonmetro areas and explicitly modeled residual areas; inspect area_type and official_published_area rather than inferring official status from the kind. National calculations are an explicit location choice. Unknown locations, years and scenarios raise errors.

Conditional 2026–2035 forecasts

The default schema-2 artifact covers 2022–2035. It preserves published national values through 2025 and projects 2026–2035 using moving five-year Consumer Expenditure Survey and American Community Survey windows. ce_trend is the default real-spending scenario; zero_real provides zero real-spending growth. The artifact records price assumptions, their source vintage, housing shares, rent indices, source windows and diagnostics separately for each selected year.

These are conditional research estimates. Public-use rent allocation, unresolved CE sample policies, fixed future donors and weights, and unestimated forecast uncertainty limit interpretation. Relative rent indices stabilize from 2029 under the baseline donor and price assumptions even as windows advance; this is not evidence of persistent local growth differences. Read the rolling forecast methods and validation limits before comparing scenarios or historical geography series breaks.

Command line

After local installation:

spm-calculator info
spm-calculator verify
spm-calculator calculate --year 2025 --adults 2 --children 2 --tenure renter --national
spm-calculator --scenario ce_trend calculate --year 2026 --adults 2 --children 2 --county 06037
spm-calculator areas --year 2035
spm-calculator --scenario zero_real export --format csv

Global options (--forecast, --expect-sha256, --as-of, --scenario) precede the subcommand. Retain a reviewed content digest and supply it on replay; the reader does not obtain a newer artifact over the network. See the quickstart and artifact contract.

Integrations and local app

• PolicyEngine: the accompanying country candidate reads forecast configuration by default and retains its tax, benefit and resource formulas. Wrapper/API production adoption is not published by this documentation.
• Microcosm Frame: preserve native membership and typed weights, attach canonical results and summarize with Frame operations.
• Axiom core: execute person classification, native unit counts, bounded canonical scale lookup and threshold/housing/poverty arithmetic in real core. The dense Microcosm AxiomEngine does not support this bridge; exact decimal poverty boundaries can differ from Python float results.

Run the browser candidate locally from web with bun install --frozen-lockfile and bun run dev. Its export consumes the canonical artifact. A local build or this README does not establish production deployment.

Sources and research history

• Validation: published BLS cells and shares, Census geography anchors, forecast comparisons and reproducible checks.
• Methodology: threshold, housing and equivalence formulas.
• Current CE replication experiment: source policies, measured replication differences and unresolved approximations.
• 2026 BLS correction and frozen experiments: historical publication vintages and the immutable 2025 forecast commitment.
• API reference: current calculation and membership interfaces.

MIT license.