One row, taken apart
This is one real row from the release: the heating allowance for a 2-bedroom house heated with natural gas, from the schedule of the Norfolk Redevelopment & Housing Authority, in effect from February 1, 2026. Every amount in the dataset is a row like this, with the same columns.
| Column | Value | Meaning |
|---|
agency_id | VA006 | HUD code of the housing authority (for example VA006) |
agency_name | Norfolk Redevelopment & Housing Authority | as in HUD's data |
state | VA | as in HUD's data |
schedule_id | VA006-HCV-2026-02-01 | one schedule = one authority + program + effective date + area |
program | HCV | HCV (vouchers), public housing, both, or other (a schedule that names another program or none), as the schedule states. |
effective_date | 2026-02-01 | the date the schedule takes effect, ISO format (year-month or year only, where that is all the source gives); the same for every row of a schedule and in schedules.csv |
effective_date_basis | printed on the schedule | where the effective date comes from: printed on the schedule; stated on the page (the web page that holds the table); stated on the agency page (the authority's page that links the file); file name only; archive date only; or proposed notice (a schedule published for comment, with the date it was to take effect; it counts toward years covered only with later evidence that it was in force). Empty where no date could be established. |
area | empty | region, county or ZIP area, when the authority publishes several area schedules, as printed on the schedule or on the page that holds the table |
variant | empty | a named set inside a schedule (for example energy-efficient units), as printed |
building_type | single_family_detached | single_family_detached, semi_detached_duplex, row_townhouse, low_rise_apartment, high_rise_apartment, apartment_unspecified, manufactured_home, sro, all_types, other; several joined with + when one column covers them. Empty where the table names no building type it could be mapped to; building_type_as_printed is the reference. |
building_type_as_printed | Single-Family (Detached House) | the label on the schedule |
utility | heating | heating, cooking, other_electric, air_conditioning, water_heating, water, sewer, water_sewer, trash, range_microwave, refrigerator, gas_customer_charge, electric_customer_charge, other_fixed_charge, other, combined. combined is one amount that covers several utilities: simplified schedules that give one amount per combination of tenant-paid utilities, or one electric or gas amount for several end uses ("Electricity (L&A,F,C)"); the group as printed is in utility_as_printed. A printed Total row that adds up the separate lines above it is left out |
utility_as_printed | Heating / Natural Gas | the row label on the schedule |
fuel | natural_gas | natural_gas, bottled_gas, electric, electric_heat_pump, fuel_oil, coal_other, or none for items that use no fuel (water, sewer, trash, appliances); several joined with +. Empty where a heating, cooking or water-heating line does not state its fuel (those amounts are flagged). |
part | empty | empty, except where a page prints several amounts on one line for the same size (for example two utility providers side by side): each amount is kept, numbered in reading order, and flagged |
bedrooms | 2 | SRO, 0 to 8 |
amount_usd | 62 | monthly allowance in dollars, as printed |
qa_status | ok | ok, or flagged when a check failed (see the method page) |
qa_note | empty | why the amount is flagged: one or more short reason codes, separated by semicolons; empty when the amount passes every check. The method page lists the reasons in plain words. |
read_method | text layer | how the amount was read: text layer (typed PDFs), OCR (scanned pages), image consensus (poor scans, where OCR and two independent image reads agree), spreadsheet (cell values), or html (web pages and Word files). |
second_read | empty | result of the independent second read, where the page was in it: agrees; differs (the amount is flagged); resolved (which of the OCR readings was kept); not read (the second read did not see this amount). Empty where the page was not second-read. |
source_file | files/VA006/2026-Utility-Allowance-Schedules-NRHA__live.pdf | the file in files/ the amount was read from |
page | 3 | the page of the source file the amount was read from (1 is the first page). |
value_id | VA006-60f1fafdcb-p3-t1-r1-c3 | unique id of the row: authority, file, page, table, row and column of the amount |
The five files
A release is five CSV files and a folder of source files. Each file has a header row.
| File | One row per | What it is for |
|---|
values.csv | amount | the full table, one amount per row |
values_wide.csv | printed line of one table (schedule × area × building type × utility line × fuel, with its file and page) | the layout of the printed schedule (HUD form 52667): bedroom sizes as columns |
schedules.csv | schedule | effective date; the latest date it is shown in effect and the evidence (the authority's page in an archived capture, the file's archive date, or live today); program, area, building types, number of amounts, source URLs |
files.csv | source file | original URL, archive copy, retrieval date, SHA-256 |
agencies.csv | authority (all 2,117) | status, website, schedule page, newest effective date, years covered |
files/<authority>/ | source file | the files as published (PDF, spreadsheet, web page) |
Columns of each file
| File | Columns |
|---|
values.csv | agency_id, agency_name, state, schedule_id, program, effective_date, effective_date_basis, area, variant, building_type, building_type_as_printed, utility, utility_as_printed, fuel, part, bedrooms, amount_usd, qa_status, qa_note, read_method, second_read, source_file, page, value_id |
values_wide.csv | agency_id, agency_name, state, schedule_id, program, effective_date, area, variant, building_type, building_type_as_printed, utility, utility_as_printed, fuel, part, source_file, page, SRO, 0, 1, 2, 3, 4, 5, 6, 7, 8, flagged_sizes |
schedules.csv | agency_id, agency_name, state, schedule_id, program, effective_date, effective_date_basis, evidenced_until, evidenced_by, area, building_types_as_printed, collection, n_files, n_values, n_values_flagged, source_urls, archive_urls, notes |
files.csv | agency_id, schedule_id, source_file, format, pages, source_url, archive_url, retrieved_date, sha256, is_schedule, notes |
agencies.csv | agency_id, agency_name, state, city, county, metro_area, vouchers, rank_by_vouchers, website, schedule_page_url, posts_schedule_online, newest_effective_date, years_covered_2019_2026, n_schedules, n_values, in_dataset, notes |
Values in use
Counts are amounts in the November 5, 2026 release.
utility
| Value | Amounts |
|---|
heating | 269,505 |
water_heating hot water | 208,726 |
cooking | 179,928 |
water | 67,773 |
sewer | 63,819 |
other_electric lights and appliances | 62,809 |
trash | 57,739 |
air_conditioning | 56,089 |
refrigerator | 55,757 |
range_microwave range or microwave | 54,540 |
gas_customer_charge | 20,090 |
electric_customer_charge | 15,937 |
other | 14,473 |
combined several utilities in one amount | 6,909 |
other_fixed_charge | 3,706 |
water_sewer water and sewer in one amount | 2,867 |
fuel
| Value | Amounts |
|---|
none | 361,540 |
electric | 300,799 |
natural_gas | 181,704 |
bottled_gas | 147,175 |
fuel_oil | 73,479 |
electric_heat_pump | 52,856 |
| empty | 11,089 |
coal_other | 6,271 |
5,754 amounts name two or more fuels joined with +, where one printed line covers them, for example bottled_gas+fuel_oil. An empty fuel means the line does not state one; those amounts are flagged.
building_type
| Value | Amounts |
|---|
single_family_detached | 377,439 |
apartment_unspecified | 313,891 |
row_townhouse | 213,915 |
low_rise_apartment | 170,587 |
manufactured_home | 160,872 |
semi_detached_duplex | 149,309 |
high_rise_apartment | 98,849 |
| empty | 28,730 |
all_types | 25,915 |
sro | 1,273 |
other | 1,260 |
bedrooms
| Value | Amounts |
|---|
SRO single room | 2,670 |
0 | 175,683 |
1 | 181,420 |
2 | 182,090 |
3 | 180,979 |
4 | 179,551 |
5 | 172,263 |
6 | 32,351 |
7 | 21,672 |
8 | 11,988 |
program
| Value | Amounts |
|---|
HCV Housing Choice Voucher | 1,122,560 |
public housing | 12,133 |
both voucher and public housing | 4,715 |
other | 1,259 |
- CSV, UTF-8, comma-separated, one header row.
- Dates are ISO 8601:
2026-01-01, or 2025-04 and 2026 where the source gives only a month or a year.
- Amounts are monthly US dollars, as printed.
- Source files keep their published format: PDF, spreadsheet, Word or web page.
Loading it
Read every column as text first. Some codes look like numbers, and empty cells mean “not printed”.
import pandas as pd
rows = pd.read_csv("values.csv", dtype=str, keep_default_na=False)
rows["amount_usd"] = rows["amount_usd"].astype(float)
-- DuckDB
SELECT agency_id, utility, fuel, bedrooms, amount_usd
FROM read_csv('values.csv', all_varchar = true)
WHERE agency_id = 'VA006';
The data dictionary
Every column of the five files, with its type, its meaning and the values in use, to download: data-dictionary.csv · data-dictionary.json.