What the Numbers Actually Do

Throughout, P is a place (municipality or census-designated place), T a census tract, b an AMI band, and t a tenure in {renter, owner}. CHAS bands are the five the source publishes: ≤30, 31–50, 51–80, 81–100, >100 percent of area median income.

One convention governs everything else and is stated first because it changes what the other formulas mean: a quantity that cannot be measured is null, and null is never coerced to zero. In the formulas below, any sum or quotient with a null operand is null, not a value computed as though the operand were zero. §07 gives the propagation rules precisely, because they are where most of the system's defects have lived.

HUD's CHAS tables are the only public source crossing cost burden with AMI band and tenure. They publish at tract level. Municipal boundaries do not follow tracts, so every place-level figure in this system is an apportionment, and the weight is the whole argument.

The assumption underneath both shares is uniform distribution of households within a tract. It is poorest for slivers — tracts contributing under roughly a tenth of their area — which are flagged rather than silently included, and it is exactly where max does the most work.

Apportionment is geometrically defensible and demographically optimistic. Summed across overlapping tracts it overcounts households in roughly 31% of Colorado places, and under the max rule it must. The correction anchors each place's tenure totals to an independent source — the American Community Survey's occupied-unit counts — and scales the bands to fit.

Cost burden follows HUD's definition: a household is burdened above 30% of gross income for housing, severely burdened above 50%. Both are counted directly in CHAS rather than derived, so the apportionment above carries them without further assumption.

The structure is a closed-form solve rather than a search: every cost that scales with price is collected into k, the cost per dollar of price per month, and the budget is divided by it. Fixed monthly costs are subtracted from the budget first, precisely because they do not scale. The inverse — income required for a given home value — is a binary search, because f(size) and the PMI gate make the forward function piecewise.

The ranking index reduces every jurisdiction to one number. This section writes out the whole chain, because a composite score is the easiest place in a system like this to hide an arbitrary choice, and the only defence is publishing every weight.

Two properties are worth stating before the formulas. First, almost every input enters as a percentile rank within its own geography type, not as a raw value — counties are ranked against counties, places against places. Second, the percentile convention is rank / (n − 1) · 100, so the lowest-ranked geography in each pool scores exactly 0 and the highest exactly 100 by construction. Scores are therefore positional, not absolute: a place cannot improve its score by improving, only by improving relative to its peers.

The confidence multiplier deducts 0.03 per imputed score factor and 0.01 per approximated field, with further deductions for low-confidence home values and for opportunity data resolved only at county level. It is floored at 0.85, so the maximum total penalty is 15%.

The rules below are the ones that make the rest of this document mean what it says. They exist because Number(null) is 0 and 0 is finite, so a coercion upstream of any formula here produces a value that passes every downstream validity check.

A missing factor is dropped and the remaining weights are renormalised, rather than the factor entering as zero. The difference is not subtle: as a zero, a missing overcrowding rate would push a jurisdiction's need score down by a tenth of its value and look like measured absence of overcrowding. Renormalised, it means “this score was computed from the other four factors” — which is a weaker claim, correctly stated.

The other rules, in the order they bite:

• Rate denominators have a floor. A rate computed on fewer than 50 households is not published. Small denominators produce rates of 0% and 100% that are arithmetically correct and substantively meaningless.
• Sentinels are rejected before arithmetic. The Census API returns -666666666 for unavailable variables. It is finite, so every naive check passes it through; it is caught at parse.
• Guard ≤ 0, not < 0. Wherever zero is not a meaningful value — a price, a rent, an income — exactly zero means unknown rather than free.
• Negative inputs yield null, not 0. The affordability solve returns null for missing or negative income, and 0 only for the distinct case where fixed monthly costs consume the entire budget — a real finding, not a missing one.
• Reasons travel with values. Every metric carries source, vintage, geography level and confidence, so a consumer can distinguish “not published by the source” from “below the reporting threshold” from “measured.”

Share denominators are rounded before division (§04), which removes the float-tie instability. Generated files are rebuilt in continuous integration and a pull request whose outputs drift from what its inputs would produce fails. The constants in this document are extracted from source rather than transcribed, so this page cannot drift from the program without failing the build.

Writing out the specification located four disagreements between code and documentation:

1. The apportionment weight is min(1.0, max(area, population)) while the file header and its output-schema example both said area-weighted (§02). Both corrected and now guarded. The string actually emitted into the data file was incomplete rather than wrong — it omitted the max — and is also corrected, though the published file carries the older text until the build is re-run.
2. The working paper described one affordability model where 7 exist, and described the non-default one (§05).
3. Affordability defaults are declared in six places, not two. Down payment takes three values — one of them a whole-number percentage rather than a fraction — and insurance is declared in two different units: flat annual dollars in one file, a rate of home value in another. On a $250,000 home those differ by roughly 2.7×, crossing near $686,000. test/affordability-defaults-inventory.test.js now pins all of them and fails when a new competing default appears (§05).
4. A tenure label in the working paper's tractability table inverted its two zero-cases, publishing a jurisdiction with 266 burdened renters and no burdened owners as “owner only.” Fixed, and now guarded against the counts rather than against the function that produced them.

• The max weight is not a partition. It can attribute a household to more than one place. The ACS anchor bounds the consequence at the place level but nothing bounds it statewide, so summing place-level counts across Colorado is not a valid operation and the interface should say so more loudly than it does.
• Double percentiling compresses the need axis and puts it on a different scale from opportunity in the same weighted blend (§06).
• Uniform within-tract density is assumed by both shares and is weakest exactly where max is doing the most work.
• Cost burden and unit gap use different income bases — burden against area medians, gap against household-size-adjusted limits. Both are correct against their own definitions and they are not comparable band-for-band, which is a trap for any reader who assumes a shared denominator.
• The 30%/43% divide is unresolved by design and should be resolved by the user, not by the system picking one.