Skip to content

brycewang-stanford/Auto-Empirical-Research-Skills / skills/22-christopherkenny-skills/skills/redistricting-analysis

redistricting-analysis

Verified

Redistricting analysis in R using the redistverse ecosystem. Use whenever the user is working with redist, redistmetrics, ggredist, geomander, adj, alarmdata, PL94171, censable, easycensus, tinytiger, baf, rict, or redistio. Covers the complete pipeline: Census and spatial data loading, adjacency graph construction, SMC/MCMC simulation, constraints (population balance, county splits, VRA compliance), convergence diagnostics, plan metrics (compactness, partisan fairness, splits), visualization, summary tables, and interactive plan drawing. Invoke whenever the user mentions redistricting, gerrymandering, district plans, simulation ensembles, or any redistverse package by name.

references/08-adj.md

View on GitHub
# adj — Adjacency Graphs

## Overview

`adj` is an S3 vector class representing precinct adjacency graphs. Each element is a zero-indexed integer vector of neighbors. The adjacency graph is stored as the `adj` column of a `redist_map`, and is central to all tree-based simulation algorithms. Use `adj` functions when you need to construct, inspect, or modify the adjacency structure.

## Construction

### From a Shapefile

The most common approach: compute adjacency from shared boundaries in an `sf` object.

```r
library(adj)

# Build adjacency from shared polygon boundaries
adjacency <- adj_from_shp(shp)      # sf object with polygon geometry

# Equivalent using the map directly
adjacency <- adj_from_shp(map)
```

### From ALARM Pre-built Data

The `alarm_50state_map()` function returns a `redist_map` with the `adj` column pre-built:

```r
map <- alarm_50state_map('MD')
adj_graph <- map$adj     # already computed
```

### Manual Construction

```r
# Create from a list of neighbor index vectors (zero-indexed)
adj_graph <- adj(list(
  c(1L, 2L),    # precinct 0 is adjacent to precincts 1 and 2
  c(0L, 2L),    # precinct 1 is adjacent to 0 and 2
  c(0L, 1L)     # precinct 2 is adjacent to 0 and 1
))
```

## Inspecting the Graph

```r
length(adj_graph)              # number of precincts (nodes)
adj_graph[[i]]                 # neighbors of precinct i (0-indexed)
plot(adj_graph, map)           # visualize the graph overlaid on the map geometry
```

## Modifying Edges

### Remove Edges

Use to disconnect precincts separated by water bodies, mountain ranges, or other barriers that make adjacency legally or geographically incorrect.

```r
# Remove the edge between precincts 42 and 107
adj_graph <- adj_subtract_edges(adj_graph, v1 = 42L, v2 = 107L)

# Remove multiple edges at once (vectorized)
adj_graph <- adj_subtract_edges(adj_graph,
                                v1 = c(42L, 58L, 91L),
                                v2 = c(107L, 59L, 92L))
```

### Add Edges

Add connections for precincts linked by ferry, bridge, or tunnel:

```r
adj_graph <- adj_add_edges(adj_graph, v1 = 204L, v2 = 312L)
```

## Storing Modified Adjacency Back in the Map

```r
map <- map |> mutate(adj = list(adj_graph))
# Or directly:
attr(map, 'adj') <- adj_graph
```

## District-Level Adjacency

Build a district-level adjacency graph from a plan assignment vector. Useful for checking contiguity of merged regions or computing district-level graph properties.

```r
district_adj <- adj_quotient(adj_graph, plan = map$cd_2020)
# Returns an adj object with one node per district
```

## Graph Coloring

Assign colors to precincts/districts so no two adjacent units share a color. Uses the DSatur algorithm; typically requires 4–5 colors for U.S. states.

```r
# Color districts for map visualization
colors <- adj_color(adj_graph)        # returns integer vector of color assignments
colors <- adj_color(district_adj)     # color the district-level graph

# Use in ggplot
map$color <- adj_color(map$adj[[1]])
ggplot(map, aes(fill = factor(color), group = cd_2020)) + geom_district()
```

## Graph Laplacian

The Laplacian matrix encodes graph structure and is used internally by `redist` to weight spanning trees (controlling compactness). You rarely need this directly, but it's available for advanced analyses.

```r
L <- adj_laplacian(adj_graph)    # sparse matrix (Matrix package)
# Number of spanning trees = product of nonzero eigenvalues / n
```

## Common Workflow: Fixing Water Adjacency

```r
library(redistverse)

map <- alarm_50state_map('MD')

# Identify and remove spurious water-crossing edges
# (Chesapeake Bay separates Eastern and Western Shore)
# Use geomander::seam_rip() or manually identify edge pairs to remove
# (see 09-geomander-adjacency.md)

map <- map |>
  mutate(adj = list(
    adj_subtract_edges(map$adj[[1]],
                       v1 = water_edge_from,
                       v2 = water_edge_to)
  ))

# Verify the graph is still connected
# redist_map() will warn if adj yields disconnected units
```

## See Also

- Geographic edge removal utilities: [09-geomander-adjacency.md](09-geomander-adjacency.md)
- How adjacency is used in simulation: [01-redist-simulation.md](01-redist-simulation.md)
- District coloring in ggredist: [07-ggredist.md](07-ggredist.md)
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 323kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall