Methods

Tech stack

• Sources. Raw files archived & unchanged, Census population estimates, State Department visa reports, DHS tables, ICE detention statistics, the Deportation Data Project, USCIS H-1B hub and NCES enrollment data, Manifest records each file and checksum.
• Processing. Python (pandas, openpyxl, pyshp) reshape each source into JSON: rows read, and file dates. Nothing is rounded or imputed, and estimates are labelled.
• Geography. Census cartographic boundaries and Gazetteer points. County dots sit on census tracts in proportion to foreign-born residents (American Community Survey 2020–2024).
• Rendering. HTML, CSS and JavaScript, WebGL, Canvas, and SVG.
• Hosting. GitHub
• AI. Claude Code

Data forensics

AI strategy

We used Claude Code as a supervised analyst, not for narrative or strategy. We required that it work only from raw source data files. Source files were referenced to create JSONs with source file information and checksums for validation.

Auditing AI data manipulation

Following the Chain of Custody Audit Card, we archived raw files unaltered with a manifest of their origins and checksums. Every transformation runs through a script that logs what it did: which row it read as the header, which columns it left as text, and which source file each year came from. Nothing was rounded or imputed, and we audited outputs. We compared each new graph against the previous one, and ensured that parts add up to their totals: states to national figures, counties to states, and visa classes to their categories.

Mitigating bias and hallucination

Our audit caught one problem directly. AI swapped the Census’s April–June 2020 figure for a full-year number from an older release, and that changed the shape of the graph. We reverted it and began flagging partial years instead of altering them.

Methodologies behind the visuals

• Migration: Census net international migration, years ending 1 July. Data for 2001–2009 come from the 2009 estimates release, 2010–2019 from the 2020 release and 2020–2025 from the 2025 release. 2010 and 2020 cover April–June only. On the US map, one dot = one person.
• Visas: State Department visas issued. On the globes, 2024, one dot = 50 visas. Arcs route through likely ports of entry and illustrate, but do not record, journeys. The graphs show yearly totals by category for 2001–2025 and every visa class for FY2018–2025, summed from the monthly reports, which agree with the annual totals to within 2%.
• Green cards: DHS data for the 200 busiest counties plus state totals by country of birth. 99.3% of 2024’s 1.36 million are mapped, one dot per person.
• Detention: ICE average daily detention by facility, plotted at ZIP code centres, one dot per person held.
• Removals: ICE removals are those that began with an ICE arrest, by state of arrest and country, counted by calendar year of departure (2022: October–December only). BPS removals follow a border arrest. Their split by Border Patrol sector, and their destination countries on the globe, are estimates.

Limitations. Dots are placed approximately around ZIP code, tract and county centres. Visa, green-card and ICE detention data run on fiscal years, ICE removals on calendar years, and the Census counts years ending 1 July.