06-worked-examples

Worked Examples

Real analysis files from the ALARM fifty-states project, with annotations explaining each decision. Use these as ground-truth templates — this is actual passing code, not reconstructed examples.

Six analyses are shown. The first three cover simulation complexity tiers; the last three cover adjacency graph patterns:

**Simulation tiers:**

• **ME_cd_2020** — minimal: 2 districts, county constraint, compactness tweak
• **GA_cd_2020** — moderate: 17 districts, pseudocounties, BVAP hinge constraints
• **IL_cd_2020** — complex: 17 districts, pseudocounties (two large counties), BVAP + HVAP hinge constraints

**Adjacency patterns:**

• **ID_cd_2020** — highway-connectivity: `seam_rip()` removes county borders not crossed by a road
• **WA_cd_2020** — water barriers + ferries: `st_difference(water)` + `remove_edge()` + ferry/bridge/manual reconnects; also `seq_alpha = 0.9` and multi-target non-white VAP hinge
• **MD_cd_2010** — 2010 cycle + bay isolation: `subtract_edge()`/`add_edge()` for Chesapeake Bay pseudo-units; `year = 2010` data loading; GEOID `.x`/`.y` dedup fix
• **HI_cd_2020** — multi-island + partial SMC: block-level data aggregated to tracts; island connections for visualization only; `n_steps = 1` partial simulation; manual plan matrix construction with `redist_plans()`

---

Tier 1 — Simple State: ME_cd_2020

Maine: 2 congressional districts, 2020 cycle. Small state, no VRA, standard county constraint.

01_prep_ME_cd_2020.R

###############################################################################
# Download and prepare data for `ME_cd_2020` analysis
# © ALARM Project, December 2021
###############################################################################

suppressMessages({
    library(dplyr)
    library(readr)
    library(sf)
    library(redist)
    library(geomander)
    library(cli)
    library(here)
    devtools::load_all() # load utilities
})

# Download necessary files for analysis -----
cli_process_start("Downloading files for {.pkg ME_cd_2020}")

path_data <- download_redistricting_file("ME", "data-raw/ME")

cli_process_done()

# Compile raw data into a final shapefile for analysis -----
shp_path <- "data-out/ME_2020/shp_vtd.rds"
perim_path <- "data-out/ME_2020/perim.rds"

if (!file.exists(here(shp_path))) {
    cli_process_start("Preparing {.strong ME} shapefile")

    # NOTE: Maine uses census tracts (not VTDs) because 2020 VTDs don't cover
    # most of the state's geography. This is state-specific — most states use
    # join_vtd_shapefile() + read_csv() instead of the tract-level approach below.
    years <- c(2016, 2018, 2020)
    state <- "ME"
    el_l <- lapply(years, function(year) {
        get_vest(state, year)
    })

    block <- censable::build_dec("block", state, year = 2010)

    m_l <- lapply(el_l, function(x) {
        geo_match(from = block, to = x, method = "area")
    })

    el_l <- lapply(seq_along(el_l), function(x) {
        vest <- el_l[[x]]
        elec_at_2010 <- tibble(GEOID = block$GEOID)
        elections <- names(vest)[str_detect(names(vest), str_c("_", years[x] - 2000)) &
            (str_detect(names(vest), "_rep_") | str_detect(names(vest), "_dem_"))]
        for (election in elections) {
            elec_at_2010 <- elec_at_2010 %>%
                mutate(!!election := estimate_down(
                    value = vest[[election]], wts = block[["vap"]],
                    group = m_l[[x]]
                ))
        }
        elec_at_2010
    })
    elec_at_2010 <- purrr::reduce(el_l, left_join, by = "GEOID")
    vest_cw <- cvap::vest_crosswalk(state)
    rt <- PL94171::pl_retally(elec_at_2010, crosswalk = vest_cw)
    names(rt)[4:13] <- names(elec_at_2010)[2:11]

    tract <- rt %>%
        censable::breakdown_geoid() %>%
        censable::construct_geoid("tract") %>%
        select(GEOID, contains(paste(years - 2000))) %>%
        group_by(GEOID) %>%
        summarize(across(.fns = sum)) %>%
        mutate(
            arv_16 = rowMeans(select(., contains("_16_rep_")), na.rm = TRUE),
            adv_16 = rowMeans(select(., contains("_16_dem_")), na.rm = TRUE),
            arv_18 = rowMeans(select(., contains("_18_rep_")), na.rm = TRUE),
            adv_18 = rowMeans(select(., contains("_18_dem_")), na.rm = TRUE),
            arv_20 = rowMeans(select(., contains("_20_rep_")), na.rm = TRUE),
            adv_20 = rowMeans(select(., contains("_20_dem_")), na.rm = TRUE),
            nrv = rowMeans(select(., contains("_rep_")), na.rm = TRUE),
            ndv = rowMeans(select(., contains("_dem_")), na.rm = TRUE)
        )

    me_shp <- censable::build_dec("tract", state) %>%
        left_join(tract, by = "GEOID")
    me_shp <- me_shp %>%
        censable::breakdown_geoid() %>%
        mutate(state = censable::match_fips(state[1]))

    # NOTE: EPSG$ME is the standard state-specific projection from the project's
    # EPSG lookup table. Always use EPSG[[ST]] — never hardcode a projection number.
    me_shp <- me_shp %>%
        st_transform(EPSG$ME) %>%
        rename_with(function(x) gsub("[0-9.]", "", x), starts_with("GEOID"))

    me_shp <- me_shp %>% filter(!st_is_empty(geometry))

    # add municipalities (BAF = block assignment file)
    d_muni <- PL94171::pl_get_baf("ME")$INCPLACE_CDP %>%
        censable::breakdown_geoid("BLOCKID") %>%
        censable::construct_geoid("tract") %>%
        group_by(GEOID) %>%
        summarize(muni = Mode(PLACEFP))
    d_cd <- PL94171::pl_get_baf("ME")$CD %>%
        censable::breakdown_geoid("BLOCKID") %>%
        censable::construct_geoid("tract") %>%
        group_by(GEOID) %>%
        summarize(cd_2010 = Mode(DISTRICT))
    me_shp <- left_join(me_shp, d_muni, by = "GEOID") %>%
        left_join(d_cd, by = "GEOID") %>%
        mutate(county_muni = if_else(is.na(muni), county, str_c(county, muni))) %>%
        relocate(muni, county_muni, cd_2010, .after = county)

    # load the enacted plan from a public URL
    dists <- read_sf("https://redistrict2020.org/fi