Metadata-Version: 2.4
Name: homeafford
Version: 0.1.2
Summary: Housing affordability metrics: price-to-income and median multiple, rent-to-income and cost burden, residual income, mortgage affordability, a NAR-style affordability index, housing plus transportation share and distributional measures across households.
Author-email: Yusuf Eminoğlu <geospacephilo@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/geophilo1/homeafford_sdk
Project-URL: Repository, https://gitlab.com/geophilo1/homeafford_sdk
Project-URL: Documentation, https://gitlab.com/geophilo1/homeafford_sdk#readme
Project-URL: Issues, https://gitlab.com/geophilo1/homeafford_sdk/-/work_items
Project-URL: Changelog, https://gitlab.com/geophilo1/homeafford_sdk/-/blob/main/CHANGELOG.md
Project-URL: SDK dashboard, https://geophilo.com/sdk-dashboard/
Project-URL: DOI, https://doi.org/10.5281/zenodo.24235556
Keywords: housing-affordability,price-to-income,median-multiple,cost-burden,rent-burden,residual-income,shelter-poverty,mortgage,affordability-index,housing-transportation,h-t-index,housing-policy,urban-planning
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Office/Business :: Financial
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Other Audience
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <a href="https://geophilo.com/sdk-dashboard/"><img src="https://geophilo.com/assets/sdk_icons/homeafford_sdk.svg" width="120" height="120" alt="homeafford icon"></a>
</p>

# homeafford

[![PyPI version](https://img.shields.io/pypi/v/homeafford.svg)](https://pypi.org/project/homeafford/)
[![Python versions](https://img.shields.io/pypi/pyversions/homeafford.svg)](https://pypi.org/project/homeafford/)
[![pipeline status](https://gitlab.com/geophilo1/homeafford_sdk/badges/main/pipeline.svg)](https://gitlab.com/geophilo1/homeafford_sdk/-/pipelines)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://gitlab.com/geophilo1/homeafford_sdk/-/blob/main/LICENSE)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.24235556.svg)](https://doi.org/10.5281/zenodo.24235556)
[![Downloads](https://static.pepy.tech/badge/homeafford/month)](https://pepy.tech/project/homeafford)

**Housing affordability metrics for markets and household samples.**

`homeafford` computes the affordability measures used in housing needs assessments,
housing market reports and planning studies:

- **Ratios**: price-to-income, the median multiple with the Demographia category table
  (or your own bands), rent-to-income.
- **Cost burden**: HUD's cost-burdened (> 30 % of income) and severely cost-burdened
  (> 50 %) categories, the affordable cost at a threshold, and per-household cost and
  income gaps.
- **Residual income** (Stone 2006): residual income after housing, maximum affordable
  housing cost and shelter poverty against a non-housing standard you supply.
- **Mortgage affordability**: annuity payment, loan size from a payment, amortisation
  schedule, maximum affordable price under loan-to-value and debt-to-income limits (with
  taxes, insurance, fees, other debt and a cash down payment), and the income required for
  a given price.
- **Housing Affordability Index** in the style of the National Association of REALTORS.
- **Housing + Transportation share** (CNT H+T, 45 % benchmark).
- **Distribution across households**: weighted shares burdened, median and upper-quartile
  ratios, aggregate and mean affordability gaps, summaries by group or income quintile, and
  the share of households able to afford a given price.

It needs only NumPy. Every function is vectorised; household-level functions accept
survey weights. A command-line tool reads household tables from CSV or JSON.

## Installation

```bash
pip install homeafford
```

Requires Python 3.9 or newer.

## Quickstart

```python
import homeafford as ha

# Market level
ha.median_multiple(prices, incomes)            # median price / median household income
ha.classify_multiple(4.6)                      # "seriously unaffordable"
ha.housing_affordability_index(250_000, 80_000, 0.06).hai   # 138.99

# Households (monthly cost and income, optional weights)
cost = [300, 600, 900, 100]
income = [1000, 1500, 1600, 0]
ha.burden_category(cost, income)               # [0, 1, 2, -1]  (-1: income <= 0)
ha.burden_summary(cost, income)
# {'share_burdened': 0.667, 'share_severely_burdened': 0.333, 'median_ratio': 0.4,
#  'aggregate_gap': 570.0, 'mean_gap_burdened': 285.0, ...}
ha.burden_by_group(cost, income, ["rent", "own", "rent", "own"])

# Residual income with a non-housing standard of your choice
res = ha.residual_analysis(income=[3000, 4000], housing_cost=[1200, 1200],
                           standard=1800, taxes=[300, 500])
res.shelter_poor, res.shortfall                # [True, False], [300, 0]

# Mortgages
ha.payment(200_000, 0.06, 30)                  # 1199.10 per month
best = ha.max_affordable_price(120_000, 0.06, 30, ltv=0.8, front_end_ratio=0.28,
                               back_end_ratio=0.36, other_debt=500,
                               tax_insurance_rate=0.012, down_payment=40_000)
best.price, best.binding                       # price and the limit that sets it
ha.required_income(400_000, 0.06, 30, ltv=0.8, front_end_ratio=0.28)

# Housing + transportation
ha.ht_analysis(housing_cost, transport_cost, income).share_ht_unaffordable
```

All money amounts passed together must refer to the same period (monthly with monthly,
annual with annual). The mortgage functions take gross annual income and return amounts
per payment period (monthly by default).

## Features

| Area | Functions |
| --- | --- |
| Ratios | `price_to_income`, `median_multiple`, `classify_multiple`, `rent_to_income`, `DEMOGRAPHIA_BANDS`, `DEMOGRAPHIA_BANDS_FOUR` |
| Cost burden | `cost_burden_ratio`, `burden_category`, `burden_label`, `affordable_cost`, `cost_gap`, `income_gap` |
| Residual income | `residual_income`, `max_affordable_cost`, `residual_analysis`, `standard_for_sizes` |
| Mortgage | `periodic_rate`, `annuity_factor`, `payment`, `loan_amount`, `amortization_schedule`, `max_affordable_price`, `required_income` |
| Indices | `housing_affordability_index`, `ht_share`, `ht_analysis` |
| Distribution | `burden_summary`, `burden_by_group`, `income_quantile_groups`, `share_able_to_afford`, `weighted_median`, `weighted_quantile` |
| I/O | `read_records`, `column`, `text_column`, `write_csv`, `write_json` |

## Methods and sources

| Measure | Definition | Source |
| --- | --- | --- |
| Median multiple | median house price / median gross annual household income | Demographia International Housing Affordability (Cox 2025) |
| Demographia categories | affordable <= 3.0; moderately unaffordable 3.1-4.0; seriously unaffordable 4.1-5.0; severely unaffordable 5.1-8.9; impossibly unaffordable >= 9.0 (one decimal; the four-category table of editions before 2024 is `DEMOGRAPHIA_BANDS_FOUR`) | Demographia International Housing Affordability (Cox 2025) |
| Cost burden | housing cost / income; burdened > 30 %, severely burdened > 50 %; income <= 0 not computed | HUD, CHAS data documentation |
| Affordability gap | `max(cost - threshold x income, 0)`, summed over households | ratio approach, HUD thresholds |
| Residual income | `income - taxes - housing cost`; shelter poor when below the non-housing standard | Stone (2006); Stone (1993) |
| Annuity payment | `P r / (1 - (1 + r)^-n)`, `r` periodic rate | standard present-value formula (e.g. Brueggeman & Fisher) |
| Maximum price | largest price whose payment (P&I + taxes/insurance + fees) fits the front-end and back-end limits, within the LTV cap | lender ratio method; limits are user inputs |
| HAI | `100 x median family income / (12 x P&I / 0.25)`, loan = 80 % of median price, 30-year term | National Association of REALTORS, HAI methodology |
| H+T share | `(housing + transportation) / income`; affordable at <= 45 % (housing alone <= 30 %) | Center for Neighborhood Technology, H+T Index |

Values built in, and the only ones: HUD's 30 % and 50 % thresholds, the Demographia
category bands, the NAR HAI settings (20 % down payment, 25 % qualifying ratio, 30-year
term) and CNT's 45 % / 30 % benchmarks. All of them are parameters that can be changed.
Values that vary by lender, country or household are never assumed and must be given:
loan-to-value and debt-to-income limits, tax and insurance rates, the non-housing standard
for residual income, and transportation costs.

References:

- Brueggeman, W.B. and Fisher, J.D. *Real Estate Finance and Investments*. McGraw-Hill.
- Center for Neighborhood Technology. *H+T Affordability Index*, methods documentation (htaindex.cnt.org).
- Cox, W. (2025). *Demographia International Housing Affordability, 2025 Edition*. Center for Demographics and Policy, Chapman University, and Frontier Centre for Public Policy.
- National Association of REALTORS. *Housing Affordability Index: Methodology* (nar.realtor, Research and Statistics).
- Stone, M.E. (1993) *Shelter Poverty: New Ideas on Housing Affordability*. Temple University Press.
- Stone, M.E. (2006) What is housing affordability? The case for the residual income approach. *Housing Policy Debate* 17(1), 151-184.
- U.S. Department of Housing and Urban Development, Office of Policy Development and Research. *Comprehensive Housing Affordability Strategy (CHAS) data documentation*.

## Command line

```bash
homeafford burden households.csv --income income --cost cost --weight wgt \
    --group tenure --csv burden_by_household.csv -o burden.json
homeafford residual households.csv --standard 1800 --taxes taxes
homeafford ht tracts.csv --housing h_cost --transport t_cost --income med_income
homeafford mortgage --rate 0.065 --years 30 --principal 320000
homeafford mortgage --rate 0.065 --years 30 --income 95000 --ltv 0.9 \
    --front-end 0.28 --back-end 0.36 --other-debt 450 --tax-insurance 0.012
homeafford hai --price 412000 --income 98000 --rate 0.068
homeafford ratio --price 520000 --income 85000
homeafford ratio sales_and_incomes.csv --bands "low:4,mid:6,high:inf"
```

Results are printed as JSON or written with `-o`; `--csv` writes per-household results.
Use `--income-factor 0.0833333` (or `--cost-factor 12`) in `burden` when income and cost
are recorded for different periods.

## Citation

If you use `homeafford` in your work, please cite it (see `CITATION.cff`):

```bibtex
@software{eminoglu_homeafford,
  author  = {Eminoğlu, Yusuf},
  title   = {homeafford: housing affordability metrics},
  version = {0.1.2},
  doi     = {10.5281/zenodo.24235556},
  year    = {2026},
  url     = {https://gitlab.com/geophilo1/homeafford_sdk}
}
```

and the original sources of the measures you report.

## Related Geophilo SDKs

- [shiftshare](https://pypi.org/project/shiftshare/): location quotients, shift-share decompositions and economic base multipliers.
- [segstats](https://pypi.org/project/segstats/): residential segregation and diversity indices, including spatial and multigroup measures.
- [cohortproj](https://pypi.org/project/cohortproj/): cohort-component population projection, life tables and Leslie matrices.
- [urbanscaling](https://pypi.org/project/urbanscaling/): urban scaling laws `Y = Y0 N^beta` with OLS, RMA, robust fits and SAMIs.

## License

MIT. See `LICENSE`.
