Census surname field guide
How Surname Time Machine checks and preserves the data
A polished chart is only as trustworthy as the path from source file to screen. This project makes that path inspectable: each official artifact is registered, every vintage has its own parsing contract, and the released dataset is tied to an immutable snapshot.
Begin with exact official artifacts
The source register records the U.S. Census Bureau URL, retrieval time, expected byte length, SHA-256 digest, source role, parser version, and record count for every data and methodology artifact. A downloaded file is accepted only when its bytes match the registered evidence.
This protects against silent source changes, partial downloads, and accidentally parsing the wrong file. It also makes the research cutoff meaningful: the site can identify exactly which version supported the current publication instead of merely saying that Census data was used.
Parse each vintage according to its own structure
The 1990 source is fixed-width text. The 2000 and 2010 releases are archives containing CSV files with documented headers. The 2020 source is an XLSX workbook with its own sheet and header positions. One generic parser would blur important differences, so each structure has explicit validation.
The parsers check headers, field types, record counts, aggregate rows, suppression markers, and numeric relationships. “ALL OTHER NAMES” is verified where present and excluded from the surname entity set because it is an aggregate, not a searchable surname.
Harmonize labels without harmonizing away meaning
The canonical model gives the application stable field names, but each observation retains a method identifier, source references, count semantics, noise status, caveat codes, and publication status. The 1990 frequency percentage is not relabeled as a later rate. A 2020 derived total is not relabeled as a source-provided count.
Missing observations are created as explicit unpublished-or-ineligible states at read time. Suppressed fields stay null with their status. These rules prevent convenient display code from turning missingness into zero or mixing unlike measures in one series.
Lock a reproducible snapshot
After validation, canonical surname records are written in deterministic order and compressed into a versioned snapshot. The manifest records the source and method digests, entity totals, observation totals, exclusions, and the digest of the generated artifact. Re-running generation from the same inputs must reproduce the same output.
Runtime data and the bounded search-index cohort are generated from that snapshot rather than from live third-party requests. A result page therefore does not change because an upstream page changed during a visit. A future data update must create a new reviewed snapshot rather than mutating the old evidence in place.
Verify the public result, not just the build
Automated checks cover source hashes, schemas, normalization, search privacy, publication gaps, comparison rules, metadata, accessibility, and representative browser journeys. Deployment checks confirm that Preview remains noindex and that Production serves the expected commit, canonical URLs, robots policy, and sitemap.
These controls do not make the data infallible. They make errors easier to detect, reproduce, and correct. The data-sources page publishes the active snapshot identity and a correction channel so a reader can cite the evidence or report a specific concern.
- Source identity is verified before parsing.
- Vintage rules are preserved in every observation.
- Generated data is deterministic and versioned.
- Release checks cover both code and the deployed public behavior.
Research basis
Official sources used for this guide
The interpretation above is original editorial work. Factual claims about the Census products are grounded in these first-party data and methodology artifacts.
- 1990 Census Frequently Occurring Surnames (dist.all.last)U.S. Census Bureau. Sample-based file; it supplies frequency percent, cumulative frequency percent, and rank, but no national count.Read the methodology
- Documentation and Methodology for Frequently Occurring Names in the U.S. - 1990U.S. Census Bureau. Documents the 1990 Post-Enumeration Survey Search Area sample, editing, missingness, coverage, and limitations.
- Census 2000 Surname Table archiveU.S. Census Bureau. The archive also contains an XLSX rendering. The deterministic parser uses app_c.csv and preserves (S) as suppression, never zero.Read the methodology
- Demographic Aspects of Surnames from Census 2000U.S. Census Bureau. Documents the Census 2000 surname universe, the 100-occurrence publication threshold, editing, and cell suppression for values from 1 through 4.
- 2010 Census Surname Table archiveU.S. Census Bureau. The deterministic parser uses Names_2010Census.csv. The ALL OTHER NAMES aggregate is validated separately and excluded from surname entities.Read the methodology
- Frequently Occurring Surnames in the 2010 CensusU.S. Census Bureau. Documents 2010 edits, comparison limits, and the 162,253-name public table covering names with frequency at least 100.
- Frequently Occurring Last Names in the 2020 Census by Race and Hispanic OriginU.S. Census Bureau. Sheet1 has a title row, blank row, header row 3, 156,621 named rows, and one ALL OTHER NAMES aggregate. Total count and proportions are derived from noise-affected race and Hispanic-origin components.Read the methodology
- Last Name Data From the 2020 CensusU.S. Census Bureau. Documents the 2010-and-2020 cohort rule, noise infusion into race and Hispanic-origin counts, derived totals, optimization against negatives, and the possibility of published totals below 100.