Skip to main content

homeafford icon

homeafford

PyPI version Python versions pipeline status License: MIT DOI Downloads

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.2},
  doi     = {10.5281/zenodo.24235556},
  year    = {2026},
  url     = {https://gitlab.com/geophilo1/homeafford_sdk}
}

and the original sources of the measures you report.

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

License

MIT. See LICENSE.

Metadata

Release files for homeafford 0.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for homeafford 0.1.2
File Size Uploaded Provenance Actions
homeafford-0.1.2.tar.gz 35.8 kB Without provenance Details for homeafford-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for homeafford 0.1.2
File Interpreter ABI Platform Actions
homeafford-0.1.2-py3-none-any.whl Python 3 none any Details for homeafford-0.1.2-py3-none-any.whl

Total release size: 65.5 kB

Release files / homeafford-0.1.2.tar.gz

Download URL homeafford-0.1.2.tar.gz
Size 35.8 kB
Tags Source
SHA-256 checksum
How to use checksums
c6791687da30f4c43d568cab0ccef1fb2a4c24e1ee6360655ec6f47675a80355
BLAKE2b-256 checksum
How to use checksums
42803da140a3dbeeb8944f26bcb9488729c5dde65d6ace89d6a83d8a17fa2668
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.2-py3-none-any.whl

Download URL homeafford-0.1.2-py3-none-any.whl
Size 29.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
df5594949ac80e5fcdf7ae39c3e69ba7e291998039b2e3ad0cfe7fa5945eb40d
BLAKE2b-256 checksum
How to use checksums
effe9c02b024c5c91b4046114de1267d9a015d1cc21d0ff371c643d3ea06d61f
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.2

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page