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
pip install homeafford
Requires Python 3.9 or newer.
Quickstart
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
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):
@software{eminoglu_homeafford,
author = {Eminoğlu, Yusuf},
title = {homeafford: housing affordability metrics},
version = {0.1.0},
year = {2026},
url = {https://gitlab.com/geophilo1/homeafford_sdk}
}
and the original sources of the measures you report.
License
MIT. See LICENSE.
Metadata
Release files for homeafford 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| homeafford-0.1.0.tar.gz | 34.5 kB | Without provenance | Details for homeafford-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| homeafford-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for homeafford-0.1.0-py3-none-any.whl |
Total release size: 63.8 kB
Release files / homeafford-0.1.0.tar.gz
| Download URL | homeafford-0.1.0.tar.gz |
|---|---|
| Size | 34.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
af493d9923446fbe97d6acf400af2b12906c5481f08272482229321d949ff745
|
|
BLAKE2b-256 checksum How to use checksums |
29c2c28ae2f3e4e3a5280507e054c1adcd916f6d0357c1ab9025003566131e2d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Release files / homeafford-0.1.0-py3-none-any.whl
| Download URL | homeafford-0.1.0-py3-none-any.whl |
|---|---|
| Size | 29.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
244e248dbc73340d4bbf196cd67c5432ae32869e75b216312dca92e496e0d85e
|
|
BLAKE2b-256 checksum How to use checksums |
42f5764953caa82b15277b6d793e9df993a6d00c804d7498d1ba8ed9dca233bc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Security for homeafford 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.