/election-data-source-countypres

name: election-data-source-countypres
description: >-
  County Presidential Returns 2000-2024 (MIT MEDSL). Vote shares, party trends, turnout by county_fips (joins census/education data). Requires HARVARD_DATAVERSE_API_KEY. Critical: mode='TOTAL' drops ~1K counties post-2020 — use 3-pattern reconstruction
metadata:
  audience: any-agent
  domain: data-source
  skill-authored: "2026-02-23"
  skill-last-updated: "2026-02-24"

County Presidential Data Source Reference

County Presidential Election Returns 2000-2024 from MIT Election Data and Science Lab (MEDSL). Use when analyzing county-level presidential vote shares, party trends, turnout, or geographic voting patterns. Key join column county_fips enables linking to census, education (CCD/SAIPE), and demographic datasets. Requires Harvard Dataverse API key (HARVARD_DATAVERSE_API_KEY env var). Categorical variables use uppercase strings, not Portal integer codes. Critical caveat: naive mode='TOTAL' filtering silently drops ~1,000 counties in 2020+ data — use 3-pattern reconstruction.

The authoritative source for county-level U.S. presidential election returns spanning 2000-2024. Provides candidate-level vote counts across all 50 states and DC, enabling vote share analysis, partisan trend mapping, and cross-domain geographic research via FIPS code joins.

> **CRITICAL: Value Encoding** > > This dataset uses **uppercase string codes** for categorical variables (party, mode, > candidate, state) rather than integer codes. Empty strings (`""`) appear as > undocumented values in `party` (501 rows, 2024) and `mode` (2,795 rows, 2024). > > | Context | party | mode | candidate | > |---------|-------|------|-----------| > | **Standard values** | `DEMOCRAT`, `REPUBLICAN` | `TOTAL` | `BARACK OBAMA` | > | **Aggregate/meta values** | `OTHER`, `""` | `""`, `ELECTION DAY` | `OTHER`, `UNDERVOTES` | > > See `./references/variable-definitions.md` for complete encoding tables.

Prerequisites

> **API Key Required:** This data source requires a **Harvard Dataverse API key** to fetch data. > Unlike education data sources (which use the Urban Institute's free, unauthenticated API), > election data is hosted on Harvard Dataverse and requires authentication. > > **Setup instructions:** > 1. Create a free Harvard Dataverse account at https://dataverse.harvard.edu/ > 2. Log in, navigate to your account name (top-right) → API Token > 3. Click "Create Token" and copy it > 4. Set the environment variable **before launching Claude Code**: > ```bash > export HARVARD_DATAVERSE_API_KEY="your_token_here" > ``` > For Docker users: run this inside the container after `docker compose exec daaf-docker bash` > but before `claude`. To make it persistent across sessions, add it to `~/.bashrc`. > > **If the key is missing**, any fetch script will fail with a `KeyError: 'HARVARD_DATAVERSE_API_KEY'`. > The orchestrator should check for this variable's existence before dispatching Stage 5 fetch tasks > that use this data source.

What is the MEDSL County Presidential Returns Dataset?

• **Producer:** MIT Election Data and Science Lab (MEDSL)
• **Coverage:** County-level presidential election returns, 50 states + DC
• **Frequency:** Every 4 years (presidential election cycle)
• **Available years:** 2000, 2004, 2008, 2012, 2016, 2020, 2024
• **Primary identifier:** `county_fips` (5-digit FIPS code, stored as integer)
• **Record unit:** One row per county-year-candidate-party-mode combination
• **Total records:** 94,151 rows x 12 columns (~8.4 MB). Note: rows per year vary dramatically — 2020/2024 have ~2x rows due to mode breakdowns (~22K vs ~9.5K for earlier years)
• **Source:** Harvard Dataverse (DOI: 10.7910/DVN/VOQCHQ)

Reference File Structure

| File | Purpose | When to Read | |------|---------|--------------| | `variable-definitions.md` | Complete column specs, party/mode/candidate value tables | Interpreting specific columns or coded values | | `coded-values.md` | All categorical value mappings with frequencies | Filtering or recoding party, mode, candidate | | `columns.md` | Detailed per-column profiling (types, nulls, ranges) | Understanding column characteristics | | `quality-notes.md` | Known issues, anomalies, duplicates, null patterns | Assessing data reliability | | `mode-reconstruction.md` | 3-pattern TOTAL mode reconstruction for 2020+ data | Cleaning any 2020+ analysis (CRITICAL) | | `interpretations.md` | Preliminary semantic interpretations (flagged for review) | Understanding column meanings |

Decision Trees

What analysis do I need?

Analyzing presidential election data?
├─ County-level vote shares → Use 3-pattern mode reconstruction (./references/mode-reconstruction.md)
│   └─ Longitudinal (cross-year) → MUST reconstruct TOTAL for 2020+ (naive filter drops ~1,000 counties)
│   └─ Single year (pre-2020) → Safe to filter mode='TOTAL'
│   └─ Single year (2020/2024) → Reconstruct unless analyzing a known TOTAL-only state
├─ Party trends → Group by year + party, use party column (not candidate name)
│   └─ Third parties → See ./references/coded-values.md (GREEN/LIBERTARIAN vary by year)
├─ Turnout analysis → Use totalvotes column (dedup per county-year before summing!)
├─ Joining with other data → Use county_fips as join key (zero-pad to 5 chars first!)
│   └─ Census/ACS data → Join on county_fips (standard 5-digit string)
│   └─ Education data (CCD/SAIPE) → Join on county_fips
│   └─ Null FIPS? → See ./references/quality-notes.md (CT, ME, RI)
└─ Voting method analysis → 2020 and 2024 only, see mode breakdown

Is this a data quality issue?

Unexpected values?
├─ county_fips is null → CT/ME/RI in pre-2020 years (52 rows)
├─ county_fips > 72999 → Kansas City MO (FIPS 2938000, non-standard)
├─ county_fips join failures → Zero-pad to 5 chars! (AR codes = 4 digits as int)
├─ AR FIPS 5135 has two counties → Source data error: St. Francis under Sharp County
│   └─ See ./references/quality-notes.md #arkansas-fips-conta