The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

data-preparation

Overview

This vignette shows you how to prepare the data needed to run a transformation audit with shellgame.

You need three things:

  1. Baseline data - ACS estimates at ZCTA level
  2. ZIP-ZCTA crosswalk - Association between ZIPs and ZCTAs
  3. HUD crosswalk - ZIP to County allocation ratios

1. Get a Census API Key

# Get your free key at: https://api.census.gov/data/key_signup.html
# Then install it:
tidycensus::census_api_key("YOUR_KEY_HERE", install = TRUE)

2. Identify Your ZCTAs

Use the zctaCrosswalk package to find ZCTAs for your county:

library(zctaCrosswalk)

# Replace with your county FIPS code
zctas <- get_zctas_by_county("27053") # Hennepin County, MN

3. Get Baseline ACS Data

library(geoDeltaAudit)

# Get total population (B01001_001)
baseline_data <- get_zcta_baseline(
    variable = "B01001_001",
    year = 2022,
    zctas = zctas
)

# Or try other variables:
# B19013_001 - Median household income
# B25001_001 - Total housing units
# B08201_001 - Households by vehicles available

4. Get ZIP-ZCTA Crosswalk

# https://github.com/chris-prener/uds-mapper

# Read the file
zip_zcta_raw <- read.csv("ZiptoZCTA-Table 1.csv")

# Clean and standardize
zip_zcta <- prep_zip_zcta(zip_zcta_raw)

What this does: - Standardizes column names - Pads GEOIDs to 5 digits - Removes duplicates and NAs

5. Get HUD Crosswalk

Download from: https://www.huduser.gov/portal/datasets/usps_crosswalk.html

Select the most recent quarter (e.g., Q4 2024).

# Read the file
hud_raw <- read.csv("ZIP_COUNTY_122024.csv")

# Clean and standardize
hud <- prep_hud_crosswalk(hud_raw)

# Optional: use different ratio
hud_res <- prep_hud_crosswalk(hud_raw, ratio_col = "RES_RATIO")

Available ratios: - TOT_RATIO - Total addresses (default) - RES_RATIO - Residential addresses only - BUS_RATIO - Business addresses only - OTH_RATIO - Other addresses

This is Decision #2: Which ratio you choose affects your results.

6. Run the Audit

result <- audit_transformation(
    baseline_data = baseline_data,
    zip_zcta_map = zip_zcta,
    hud_crosswalk = hud,
    county_fips = "27053",
    variable_name = "population",
    value_col = "estimate"
)

summary(result)

Copy-Paste Ready Code

Here’s the complete workflow in one block:

library(geoDeltaAudit)
library(zctaCrosswalk)
library(tidycensus)

# Set your Census API key (one time)
census_api_key("YOUR_KEY_HERE", install = TRUE)

# 1. Identify ZCTAs for your county
zctas <- get_zctas_by_county("YOUR_COUNTY_FIPS")

# 2. Get baseline data
baseline_data <- get_zcta_baseline(
    variable = "B01001_001", # Total population
    year = 2022,
    zctas = zctas
)

# 3. Prepare crosswalks
zip_zcta <- prep_zip_zcta(read.csv("path/to/ZiptoZCTA.csv"))
hud <- prep_hud_crosswalk(read.csv("path/to/ZIP_COUNTY.csv"))

# 4. Run audit
result <- audit_transformation(
    baseline_data = baseline_data,
    zip_zcta_map = zip_zcta,
    hud_crosswalk = hud,
    county_fips = "YOUR_COUNTY_FIPS",
    variable_name = "population"
)

# 5. View results
summary(result)
plot_transformation_perturbation(result)

Data Structure Requirements

Baseline Data

Must have columns: - zcta - 5-digit ZCTA code - estimate (or your specified value column) - Numeric value

ZIP-ZCTA Crosswalk

Must have columns: - ZIP_CODE or zip - ZIP code - zcta - ZCTA code

HUD Crosswalk

Must have columns: - ZIP - ZIP code - COUNTY - County FIPS code - TOT_RATIO (or other ratio) - Allocation ratio

Validation

The prep_* functions will validate your data and provide helpful error messages if something is wrong.

# Example error:
# Error: ZIP-ZCTA crosswalk is missing required columns: zcta

Next Steps

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.