spm-calculator 0.1.0__tar.gz

spm_calculator-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 PolicyEngine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spm_calculator-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: spm-calculator
+Version: 0.1.0
+Summary: Calculate SPM (Supplemental Poverty Measure) thresholds for any US geography and year
+Author-email: PolicyEngine <hello@policyengine.org>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/PolicyEngine/spm-calculator
+Project-URL: Repository, https://github.com/PolicyEngine/spm-calculator
+Project-URL: Issues, https://github.com/PolicyEngine/spm-calculator/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=2.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: requests>=2.28
+Requires-Dist: census>=0.8
+Requires-Dist: us>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Provides-Extra: app
+Requires-Dist: streamlit>=1.30; extra == "app"
+Dynamic: license-file
+
+# spm-calculator
+
+Calculate [Supplemental Poverty Measure (SPM)](https://www.census.gov/topics/income-poverty/supplemental-poverty-measure.html) thresholds for any US geography and year.
+
+[![Try the Calculator](https://img.shields.io/badge/Try-Calculator-teal)](https://policyengine.github.io/spm-calculator)
+[![Documentation](https://img.shields.io/badge/docs-online-green)](https://policyengine.github.io/spm-calculator)
+
+## Interactive Calculator
+
+**[Try the SPM Threshold Calculator](https://policyengine.github.io/spm-calculator)** - A static web app that walks you through calculating your SPM threshold based on your household characteristics.
+
+The calculator runs entirely in your browser with no server required - all data is pre-computed and bundled.
+
+### Run Locally
+
+**Static React App (recommended):**
+```bash
+cd web
+npm install
+npm run dev
+```
+
+**Streamlit App (alternative):**
+```bash
+pip install spm-calculator[app]
+streamlit run app/streamlit_app.py
+```
+
+## Overview
+
+The SPM threshold is calculated as:
+
+```
+threshold = base_threshold[tenure] × equivalence_scale × geoadj
+```
+
+Where:
+- **base_threshold** varies by housing tenure (renter, owner with mortgage, owner without mortgage), calculated from 5-year rolling Consumer Expenditure Survey data
+- **equivalence_scale** adjusts for family composition using the SPM three-parameter scale
+- **geoadj** adjusts for local housing costs based on ACS median rents
+
+## Installation
+
+```bash
+pip install spm-calculator
+```
+
+## Quick Start
+
+```python
+from spm_calculator import SPMCalculator
+
+# Initialize calculator for a specific year
+calc = SPMCalculator(year=2024)
+
+# Get base thresholds by tenure (national, before geographic adjustment)
+base = calc.get_base_thresholds()
+# {'renter': 39430, 'owner_with_mortgage': 39068, 'owner_without_mortgage': 32586}
+
+# Get GEOADJ for a specific geography
+geoadj = calc.get_geoadj("congressional_district", "0612")  # CA-12
+# 1.24 (24% above national average due to high housing costs)
+
+# Calculate threshold for a specific family in a specific location
+threshold = calc.calculate_threshold(
+    num_adults=2,
+    num_children=2,
+    tenure="renter",
+    geography_type="congressional_district",
+    geography_id="0612"
+)
+# ~$48,893 (base $39,430 × equiv_scale 1.0 × geoadj 1.24)
+```
+
+## Supported Geographies
+
+- `nation` - National average
+- `state` - 50 states + DC
+- `county` - ~3,200 counties
+- `metro_area` - Metropolitan statistical areas
+- `congressional_district` - 435 congressional districts
+- `puma` - Public Use Microdata Areas
+- `tract` - Census tracts (limited availability)
+
+## Data Sources
+
+- **Base thresholds**: [BLS Consumer Expenditure Survey](https://www.bls.gov/cex/) - 5-year rolling FCSUti (Food, Clothing, Shelter, Utilities, telephone, internet)
+- **Geographic adjustment**: [ACS 5-Year Estimates](https://www.census.gov/programs-surveys/acs) - Table B25031 (Median Gross Rent by Bedrooms)
+- **Methodology**: [Census SPM Technical Documentation](https://www2.census.gov/programs-surveys/supplemental-poverty-measure/datasets/spm/spm_techdoc.pdf)
+
+## Methodology
+
+### Base Threshold Calculation
+
+Following BLS methodology (updated September 2021):
+1. Download 5 years of CE Survey PUMD (Public Use Microdata)
+2. Filter to consumer units with children
+3. Calculate FCSUti expenditures
+4. Convert to reference family (2 adults, 2 children) using equivalence scale
+5. Calculate 83% of median (47th-53rd percentile average) by tenure type
+
+### Geographic Adjustment (GEOADJ)
+
+Following Census methodology:
+```
+GEOADJ = (local_median_rent / national_median_rent) × 0.492 + 0.508
+```
+
+Where 0.492 is the housing portion of the SPM threshold for renters.
+
+### Equivalence Scale
+
+The SPM uses a three-parameter equivalence scale:
+- First adult: 1.0
+- Additional adults: 0.5 each
+- Children: 0.3 each
+- Normalized to reference family (2A2C = 1.0)
+
+## Validation
+
+Base thresholds are validated against [BLS published values](https://www.bls.gov/pir/spm/spm_thresholds_2024.htm):
+
+| Tenure | 2024 BLS | Calculator |
+|--------|----------|------------|
+| Renter | $39,430 | $39,430 |
+| Owner w/ mortgage | $39,068 | $39,068 |
+| Owner w/o mortgage | $32,586 | $32,586 |
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

spm_calculator-0.1.0/README.md

@@ -0,0 +1,135 @@
+# spm-calculator
+
+Calculate [Supplemental Poverty Measure (SPM)](https://www.census.gov/topics/income-poverty/supplemental-poverty-measure.html) thresholds for any US geography and year.
+
+[![Try the Calculator](https://img.shields.io/badge/Try-Calculator-teal)](https://policyengine.github.io/spm-calculator)
+[![Documentation](https://img.shields.io/badge/docs-online-green)](https://policyengine.github.io/spm-calculator)
+
+## Interactive Calculator
+
+**[Try the SPM Threshold Calculator](https://policyengine.github.io/spm-calculator)** - A static web app that walks you through calculating your SPM threshold based on your household characteristics.
+
+The calculator runs entirely in your browser with no server required - all data is pre-computed and bundled.
+
+### Run Locally
+
+**Static React App (recommended):**
+```bash
+cd web
+npm install
+npm run dev
+```
+
+**Streamlit App (alternative):**
+```bash
+pip install spm-calculator[app]
+streamlit run app/streamlit_app.py
+```
+
+## Overview
+
+The SPM threshold is calculated as:
+
+```
+threshold = base_threshold[tenure] × equivalence_scale × geoadj
+```
+
+Where:
+- **base_threshold** varies by housing tenure (renter, owner with mortgage, owner without mortgage), calculated from 5-year rolling Consumer Expenditure Survey data
+- **equivalence_scale** adjusts for family composition using the SPM three-parameter scale
+- **geoadj** adjusts for local housing costs based on ACS median rents
+
+## Installation
+
+```bash
+pip install spm-calculator
+```
+
+## Quick Start
+
+```python
+from spm_calculator import SPMCalculator
+
+# Initialize calculator for a specific year
+calc = SPMCalculator(year=2024)
+
+# Get base thresholds by tenure (national, before geographic adjustment)
+base = calc.get_base_thresholds()
+# {'renter': 39430, 'owner_with_mortgage': 39068, 'owner_without_mortgage': 32586}
+
+# Get GEOADJ for a specific geography
+geoadj = calc.get_geoadj("congressional_district", "0612")  # CA-12
+# 1.24 (24% above national average due to high housing costs)
+
+# Calculate threshold for a specific family in a specific location
+threshold = calc.calculate_threshold(
+    num_adults=2,
+    num_children=2,
+    tenure="renter",
+    geography_type="congressional_district",
+    geography_id="0612"
+)
+# ~$48,893 (base $39,430 × equiv_scale 1.0 × geoadj 1.24)
+```
+
+## Supported Geographies
+
+- `nation` - National average
+- `state` - 50 states + DC
+- `county` - ~3,200 counties
+- `metro_area` - Metropolitan statistical areas
+- `congressional_district` - 435 congressional districts
+- `puma` - Public Use Microdata Areas
+- `tract` - Census tracts (limited availability)
+
+## Data Sources
+
+- **Base thresholds**: [BLS Consumer Expenditure Survey](https://www.bls.gov/cex/) - 5-year rolling FCSUti (Food, Clothing, Shelter, Utilities, telephone, internet)
+- **Geographic adjustment**: [ACS 5-Year Estimates](https://www.census.gov/programs-surveys/acs) - Table B25031 (Median Gross Rent by Bedrooms)
+- **Methodology**: [Census SPM Technical Documentation](https://www2.census.gov/programs-surveys/supplemental-poverty-measure/datasets/spm/spm_techdoc.pdf)
+
+## Methodology
+
+### Base Threshold Calculation
+
+Following BLS methodology (updated September 2021):
+1. Download 5 years of CE Survey PUMD (Public Use Microdata)
+2. Filter to consumer units with children
+3. Calculate FCSUti expenditures
+4. Convert to reference family (2 adults, 2 children) using equivalence scale
+5. Calculate 83% of median (47th-53rd percentile average) by tenure type
+
+### Geographic Adjustment (GEOADJ)
+
+Following Census methodology:
+```
+GEOADJ = (local_median_rent / national_median_rent) × 0.492 + 0.508
+```
+
+Where 0.492 is the housing portion of the SPM threshold for renters.
+
+### Equivalence Scale
+
+The SPM uses a three-parameter equivalence scale:
+- First adult: 1.0
+- Additional adults: 0.5 each
+- Children: 0.3 each
+- Normalized to reference family (2A2C = 1.0)
+
+## Validation
+
+Base thresholds are validated against [BLS published values](https://www.bls.gov/pir/spm/spm_thresholds_2024.htm):
+
+| Tenure | 2024 BLS | Calculator |
+|--------|----------|------------|
+| Renter | $39,430 | $39,430 |
+| Owner w/ mortgage | $39,068 | $39,068 |
+| Owner w/o mortgage | $32,586 | $32,586 |
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

spm_calculator-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spm-calculator"
+version = "0.1.0"
+description = "Calculate SPM (Supplemental Poverty Measure) thresholds for any US geography and year"
+readme = "README.md"
+license = "MIT"
+authors = [
+    {name = "PolicyEngine", email = "hello@policyengine.org"}
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "pandas>=2.0",
+    "numpy>=1.24",
+    "requests>=2.28",
+    "census>=0.8",
+    "us>=3.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "black>=23.0",
+    "ruff>=0.1",
+]
+app = [
+    "streamlit>=1.30",
+]
+
+[project.urls]
+Homepage = "https://github.com/PolicyEngine/spm-calculator"
+Repository = "https://github.com/PolicyEngine/spm-calculator"
+Issues = "https://github.com/PolicyEngine/spm-calculator/issues"
+
+[tool.setuptools]
+packages = ["spm_calculator"]
+
+[tool.black]
+line-length = 79
+
+[tool.ruff]
+line-length = 79
+select = ["E", "F", "I"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

spm_calculator-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spm_calculator-0.1.0/spm_calculator/__init__.py

@@ -0,0 +1,52 @@
+"""
+SPM Calculator - Calculate Supplemental Poverty Measure thresholds.
+
+This package calculates SPM thresholds for any US geography and year using:
+- Base thresholds from BLS Consumer Expenditure Survey (by tenure type)
+- Geographic adjustments (GEOADJ) from ACS median rents
+- SPM three-parameter equivalence scale for family composition
+
+Example:
+    >>> from spm_calculator import SPMCalculator
+    >>> calc = SPMCalculator(year=2024)
+    >>> threshold = calc.calculate_threshold(
+    ...     num_adults=2,
+    ...     num_children=2,
+    ...     tenure="renter",
+    ...     geography_type="congressional_district",
+    ...     geography_id="0612"
+    ... )
+"""
+
+from .calculator import SPMCalculator
+from .ce_threshold import calculate_base_thresholds, get_published_thresholds
+from .geoadj import get_geoadj, create_geoadj_lookup
+from .equivalence_scale import spm_equivalence_scale
+from .fcsuti_cpi import get_fcsuti_cpi, get_fcsuti_inflation_factor
+from .forecast import (
+    forecast_thresholds,
+    get_thresholds,
+    get_threshold_with_metadata,
+    get_available_years,
+    get_latest_published_year,
+    HISTORICAL_THRESHOLDS,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "SPMCalculator",
+    "calculate_base_thresholds",
+    "get_published_thresholds",
+    "get_geoadj",
+    "create_geoadj_lookup",
+    "spm_equivalence_scale",
+    "get_fcsuti_cpi",
+    "get_fcsuti_inflation_factor",
+    "forecast_thresholds",
+    "get_thresholds",
+    "get_threshold_with_metadata",
+    "get_available_years",
+    "get_latest_published_year",
+    "HISTORICAL_THRESHOLDS",
+]

spm_calculator-0.1.0/spm_calculator/calculator.py

@@ -0,0 +1,248 @@
+"""
+Main SPMCalculator class for calculating SPM thresholds.
+
+The full SPM threshold calculation is:
+    threshold = base_threshold[tenure] × equivalence_scale × geoadj
+
+Where:
+- base_threshold varies by housing tenure (from CE Survey)
+- equivalence_scale adjusts for family composition
+- geoadj adjusts for local housing costs
+"""
+
+from typing import Union, Optional, Sequence
+
+import numpy as np
+
+from .ce_threshold import get_published_thresholds, calculate_base_thresholds
+from .equivalence_scale import spm_equivalence_scale
+from .geoadj import get_geoadj, create_geoadj_lookup, SUPPORTED_GEOGRAPHIES
+
+
+VALID_TENURE_TYPES = [
+    "renter",
+    "owner_with_mortgage",
+    "owner_without_mortgage",
+]
+
+
+class SPMCalculator:
+    """
+    Calculator for Supplemental Poverty Measure thresholds.
+
+    Calculates SPM thresholds for any US geography and year using:
+    - Base thresholds from BLS Consumer Expenditure Survey
+    - Geographic adjustments from ACS median rents
+    - SPM three-parameter equivalence scale
+
+    Example:
+        >>> calc = SPMCalculator(year=2024)
+        >>> threshold = calc.calculate_threshold(
+        ...     num_adults=2,
+        ...     num_children=2,
+        ...     tenure="renter",
+        ...     geography_type="congressional_district",
+        ...     geography_id="0612"
+        ... )
+    """
+
+    def __init__(
+        self,
+        year: int,
+        use_published_thresholds: bool = True,
+    ):
+        """
+        Initialize SPMCalculator for a specific year.
+
+        Args:
+            year: Target year for threshold calculation
+            use_published_thresholds: If True, use published BLS thresholds
+                when available. If False, calculate from CE Survey data.
+        """
+        self.year = year
+        self.use_published_thresholds = use_published_thresholds
+        self._base_thresholds: Optional[dict[str, float]] = None
+
+    def get_base_thresholds(self) -> dict[str, float]:
+        """
+        Get base SPM thresholds by tenure type.
+
+        Returns thresholds for the reference family (2 adults, 2 children)
+        before geographic adjustment.
+
+        Returns:
+            Dict with keys 'renter', 'owner_with_mortgage',
+            'owner_without_mortgage' and threshold values in dollars.
+        """
+        if self._base_thresholds is not None:
+            return self._base_thresholds.copy()
+
+        if self.use_published_thresholds:
+            try:
+                self._base_thresholds = get_published_thresholds(self.year)
+            except ValueError:
+                # Published not available, forecast from latest available
+                # Use simple CPI-U projection from 2024 for now
+                # TODO: Implement proper CE-based forecasting
+                latest_thresholds = get_published_thresholds(2024)
+                years_ahead = self.year - 2024
+                # Assume ~3% annual inflation
+                inflation_factor = 1.03**years_ahead
+                self._base_thresholds = {
+                    k: v * inflation_factor
+                    for k, v in latest_thresholds.items()
+                }
+        else:
+            self._base_thresholds = calculate_base_thresholds(
+                target_year=self.year,
+                use_published_fallback=False,
+            )
+
+        return self._base_thresholds.copy()
+
+    def get_geoadj(
+        self,
+        geography_type: str,
+        geography_id: str,
+    ) -> float:
+        """
+        Get geographic adjustment factor for a specific location.
+
+        Args:
+            geography_type: Type of geography (nation, state, county,
+                congressional_district, etc.)
+            geography_id: Geography identifier (FIPS code, etc.)
+
+        Returns:
+            GEOADJ value (typically 0.84 to 1.27)
+        """
+        # Use year - 1 for ACS data (lag)
+        acs_year = min(self.year - 1, 2022)  # TODO: Update as data available
+        return get_geoadj(geography_type, geography_id, acs_year)
+
+    def calculate_threshold(
+        self,
+        num_adults: int,
+        num_children: int,
+        tenure: str,
+        geography_type: str,
+        geography_id: str,
+    ) -> float:
+        """
+        Calculate SPM threshold for a specific SPM unit and location.
+
+        Args:
+            num_adults: Number of adults (18+) in the SPM unit
+            num_children: Number of children (under 18) in the SPM unit
+            tenure: Housing tenure type ('renter', 'owner_with_mortgage',
+                'owner_without_mortgage')
+            geography_type: Type of geography (nation, state, county, etc.)
+            geography_id: Geography identifier
+
+        Returns:
+            SPM threshold in dollars
+
+        Raises:
+            ValueError: If tenure type invalid or geography not found
+        """
+        # Validate inputs
+        if tenure not in VALID_TENURE_TYPES:
+            raise ValueError(
+                f"Invalid tenure type: {tenure}. "
+                f"Must be one of: {VALID_TENURE_TYPES}"
+            )
+
+        if num_adults < 0 or num_children < 0:
+            raise ValueError("Number of persons cannot be negative")
+
+        # Zero persons = zero threshold
+        if num_adults == 0 and num_children == 0:
+            return 0.0
+
+        # Get components
+        base = self.get_base_thresholds()[tenure]
+        equiv_scale = spm_equivalence_scale(num_adults, num_children)
+        geoadj = self.get_geoadj(geography_type, geography_id)
+
+        return base * equiv_scale * geoadj
+
+    def calculate_thresholds(
+        self,
+        num_adults: Union[int, np.ndarray, Sequence[int]],
+        num_children: Union[int, np.ndarray, Sequence[int]],
+        tenure: Union[str, Sequence[str]],
+        geography_type: str,
+        geography_ids: Union[str, Sequence[str]],
+    ) -> np.ndarray:
+        """
+        Calculate SPM thresholds for multiple SPM units (vectorized).
+
+        Args:
+            num_adults: Number of adults for each unit
+            num_children: Number of children for each unit
+            tenure: Tenure type(s) - single value or per-unit
+            geography_type: Type of geography (same for all)
+            geography_ids: Geography ID(s) - single value or per-unit
+
+        Returns:
+            Array of SPM thresholds
+        """
+        # Convert to arrays
+        num_adults = np.atleast_1d(num_adults)
+        num_children = np.atleast_1d(num_children)
+        n = len(num_adults)
+
+        # Handle tenure
+        if isinstance(tenure, str):
+            tenure = [tenure] * n
+        tenure = list(tenure)
+
+        # Handle geography_ids
+        if isinstance(geography_ids, str):
+            geography_ids = [geography_ids] * n
+        geography_ids = list(geography_ids)
+
+        # Validate lengths
+        if not (
+            len(num_adults)
+            == len(num_children)
+            == len(tenure)
+            == len(geography_ids)
+        ):
+            raise ValueError("All input arrays must have same length")
+
+        # Validate tenure types
+        for t in tenure:
+            if t not in VALID_TENURE_TYPES:
+                raise ValueError(
+                    f"Invalid tenure type: {t}. "
+                    f"Must be one of: {VALID_TENURE_TYPES}"
+                )
+
+        # Get base thresholds
+        base_thresholds = self.get_base_thresholds()
+
+        # Calculate equivalence scales (vectorized)
+        equiv_scales = spm_equivalence_scale(num_adults, num_children)
+
+        # Get GEOADJ values
+        # Cache unique geographies
+        unique_geos = set(geography_ids)
+        geo_to_geoadj = {}
+        for geo_id in unique_geos:
+            geo_to_geoadj[geo_id] = self.get_geoadj(geography_type, geo_id)
+
+        geoadj_values = np.array([geo_to_geoadj[g] for g in geography_ids])
+
+        # Get base values by tenure
+        base_values = np.array([base_thresholds[t] for t in tenure])
+
+        # Calculate thresholds
+        thresholds = base_values * equiv_scales * geoadj_values
+
+        return thresholds
+
+    @property
+    def supported_geographies(self) -> list[str]:
+        """List of supported geography types."""
+        return list(SUPPORTED_GEOGRAPHIES.keys())