DAAF-Contribution-Community/daaf / .claude/skills/election-data-source-countypres
election-data-source-countypres
VerifiedCounty Presidential Returns 2000-2024 (MIT MEDSL). Vote shares, party trends, turnout by county_fips (joins census/education data). Requires HARVARD_DATAVERSE_API_KEY set via environment_settings.txt. Critical: naive mode='TOTAL' filtering silently drops every county in breakdown-only states in 2020-and-later data (848 county-equivalents across the 10 such states in 2020), which report by vote mode (absentee, election-day, provisional) instead of totals — use 3-pattern reconstruction (TOTAL-present rows kept, breakdown-only counties summed across modes, empty-string mode rows reclassified). Categorical variables use uppercase strings, not Portal integer codes.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 22.3 KB |
| references/coded-values.md | markdown | 5.1 KB |
| references/columns.md | markdown | 5.7 KB |
| references/interpretations.md | markdown | 5.0 KB |
| references/mode-reconstruction.md | markdown | 11.8 KB |
| references/quality-notes.md | markdown | 10.1 KB |
| references/variable-definitions.md | markdown | 6.3 KB |
| scripts/01_structural_profile.py | script | 5.8 KB |
| scripts/02_column_profile.py | script | 11.9 KB |
| scripts/03_quality_profile.py | script | 22.2 KB |
| scripts/04_semantic_interpretation.py | script | 17.2 KB |
| scripts/05_reconcile_docs.py | script | 19.6 KB |
references/variable-definitions.md
View on GitHub# Variable Definitions: County Presidential Returns 2000-2024
Complete encoding tables and formal definitions for all 12 columns.
## Source Information
- **Dataset:** County Presidential Election Returns 2000-2024
- **Producer:** MIT Election Data and Science Lab (MEDSL)
- **Harvard Dataverse DOI:** 10.7910/DVN/VOQCHQ
- **Citation:** MIT Election Data and Science Lab, 2018, "County Presidential Election Returns 2000-2024", https://doi.org/10.7910/DVN/VOQCHQ, Harvard Dataverse, V20, UNF:6:xvsJJxrfXMIvzAuDYlfvVw== [fileUNF]
- **License / version:** CC0 1.0; Dataverse V20 released 2026-02-25 (file version stamp 20260211)
- **Data version:** 20260211 (February 11, 2026)
- **Codebook date:** 2025-07-12
- **Related methods paper (precinct-level, not this county file):** Baltz, S., et al. (2022). American election results at the precinct level. *Scientific Data*, 9, 651. https://doi.org/10.1038/s41597-022-01745-0
## Column Definitions
### year
- **Type:** Int64
- **Description:** Year of the presidential general election
- **Values:** {2000, 2004, 2008, 2012, 2016, 2020, 2024}
- **Codebook:** "election year"
### state
- **Type:** String
- **Description:** Full name of the U.S. state or territory
- **Values:** 51 unique (50 states + District of Columbia)
- **Format:** ALL UPPERCASE
- **Codebook:** "state name"
### state_po
- **Type:** String (2-char)
- **Description:** USPS postal abbreviation for the state
- **Values:** 51 unique, exact 1:1 mapping with `state`
- **Codebook:** "U.S. postal code state abbreviation"
### county_name
- **Type:** String
- **Description:** Name of the county or county-equivalent
- **Values:** 1,921 unique
- **Format:** ALL UPPERCASE, generally no "County" suffix
- **Codebook:** "county name"
### county_fips
- **Type:** Int64 (nullable)
- **Description:** Federal Information Processing Standards county code
- **Format:** SSCCC where SS = state FIPS, CCC = county code (stored as integer, not zero-padded)
- **Range:** 1001 - 56045 (standard); 2938000 (Kansas City MO, non-standard)
- **Nulls:** 52 (CT, ME, RI in certain years)
- **Codebook:** "county FIPS code"
- **Special cases:**
- Alaska 2004: Uses 2001-2099 (state FIPS 02 + district number, not county codes)
- Kansas City, MO: Uses 2938000 (not a standard 5-digit FIPS)
### office
- **Type:** String
- **Description:** Office being contested
- **Values:** {"US PRESIDENT"} (constant, all rows)
- **Codebook:** "President" (note: actual value is "US PRESIDENT")
### candidate
- **Type:** String
- **Description:** Candidate name or ballot-related category
- **Named candidates:** AL GORE, GEORGE W. BUSH, RALPH NADER, JOHN KERRY, BARACK OBAMA, JOHN MCCAIN, MITT ROMNEY, HILLARY CLINTON, DONALD TRUMP, DONALD J TRUMP, JOSEPH R BIDEN JR, JO JORGENSEN, KAMALA D HARRIS, CHASE OLIVER
- **Aggregate/meta values:** OTHER, TOTAL VOTES CAST, UNDERVOTES, OVERVOTES, SPOILED
- **Codebook:** "name of the candidate"
### party
- **Type:** String
- **Description:** Political party affiliation of the candidate
- **Values:** {DEMOCRAT, REPUBLICAN, LIBERTARIAN, GREEN, OTHER, ""(empty)}
- **Codebook:** "party of the candidate; takes form of DEMOCRAT, REPUBLICAN, GREEN, LIBERTARIAN, or OTHER"
- **Note:** Empty string appears only in 2024 (501 rows); LIBERTARIAN named only in 2020-2024; GREEN only in 2000 and 2020
### candidatevotes
- **Type:** Int64 (nullable)
- **Description:** Number of votes received by this candidate for this party in this county-year-mode
- **Range:** 0 - 3,028,885
- **Nulls:** 37 (NM 2024 mode breakdown rows)
- **Zeros:** 3,908 (4.15%, mostly minor parties)
- **Codebook:** "votes received by this candidate for this particular party"
### totalvotes
- **Type:** Int64
- **Description:** Total number of votes cast in this county-year-mode combination
- **Range:** 0 - 4,264,365
- **Zeros:** 50 (0.05%)
- **Codebook:** "total number of votes cast in this county-year"
- **Note:** Codebook says "county-year" but value actually varies by mode within county-year
- **Deduplication warning:** `totalvotes` is repeated for every candidate row within a
county-year-mode. When aggregating to state or national level, **deduplicate to one row
per (county_fips, year) BEFORE summing** to avoid inflating totals by the number of
candidates per county.
```python
# WRONG: sums totalvotes once per candidate row (~3-4x inflation)
state_totals = df.group_by("state_po", "year").agg(pl.col("totalvotes").sum())
# CORRECT: deduplicate first, then sum
state_totals = (
df.unique(subset=["county_fips", "year"])
.group_by("state_po", "year")
.agg(pl.col("totalvotes").sum())
)
```
```r
# WRONG: sums totalvotes once per candidate row (~3-4x inflation)
state_totals <- df |> group_by(state_po, year) |> summarise(totalvotes = sum(totalvotes))
# CORRECT: deduplicate first, then sum
state_totals <- df |>
distinct(county_fips, year, .keep_all = TRUE) |>
group_by(state_po, year) |>
summarise(totalvotes = sum(totalvotes))
```
### version
- **Type:** Int64
- **Description:** Date when dataset was finalized, in YYYYMMDD format
- **Values:** {20260211} (single value across all rows)
- **Codebook:** "date when dataset was finalized"
### mode
- **Type:** String
- **Description:** Ballot counting mode or method of voting
- **Values:** 20 unique values (see coded-values.md for complete list)
- **Default:** "TOTAL" (76.38% of all rows)
- **Codebook:** "mode of ballots cast; default is TOTAL, with different modes specified for 2020"
- **Note:** Codebook says "modes specified for 2020" but 2024 also has mode breakdowns
## Composite Key Analysis
No single column serves as a unique row identifier. The closest composite key is
`(year, state_po, county_name, party, candidate, mode)` with 93,010 unique combinations
vs 94,151 rows. The 1,141 non-unique rows include 83 exact duplicates and cases where
null `county_fips` values create ambiguity.
## Derived Metrics
| Metric | Formula | Notes |
|--------|---------|-------|
| Vote share | `candidatevotes / totalvotes` | Reconstruct TOTAL first (3-pattern, see `mode-reconstruction.md`) and require `totalvotes > 0`; a bare `mode='TOTAL'` filter drops ~850 counties in 2020 (2024 count not verified) |
| Two-party share | `candidatevotes / (dem_votes + rep_votes)` | Requires pivot; common for swing analysis |
| Turnout proxy | `totalvotes` | Not true turnout (no denominator of eligible voters in this dataset) |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |