Thank you for helping test DownBallotR! This guide walks
you through installation and a set of test calls. We’re looking for
feedback on anything that’s confusing, broken, or could work better — no
particular experience level required.
Questions or issues? Email grahamchickering@gmail.com or file a GitHub issue at https://github.com/gchickering21/DownBallotR/issues
What is DownBallotR?
DownBallotR is an R package that downloads and
standardizes election results from 15 US states. It pulls data live from
official state sources and returns clean data frames — no manual
downloading required. All data retrieval goes through a single function:
scrape_elections().
Step 1: Make sure R is installed
R version 4.1.0 or higher is required. Check your version by running:
R.version$version.stringIf you don’t have R (or need to update), download it from https://cran.r-project.org. We also recommend RStudio as a friendlier interface: https://posit.co/download/rstudio-desktop
Step 2: Install the package and set up Python
Follow the installation instructions in the README: https://github.com/gchickering21/DownBallotR
For a more detailed walkthrough of the Python setup step, see the
Python setup vignette:
vignette("python-setup", package = "DownBallotR")
Step 3: Review the documentation
Before running any code, we’d love feedback on whether the documentation is clear and easy to follow. Please take a look at any of the following and note anything confusing, incomplete, or missing:
README — the main package overview, installation instructions, and quick-start examples: https://github.com/gchickering21/DownBallotR
Vignettes — detailed guides for each state and topic:
- Python setup — environment installation and troubleshooting
- Datasheet — data composition, limitations, and responsible use
- Data dictionary — all columns returned across all states
-
Scraping
data — overview of
scrape_elections()and how routing works - ElectionStats states — VA, MA, CO, NH, ID, SC, NM, NY, VT
- North Carolina
- Connecticut
- Georgia
- Indiana
- Louisiana
- Utah
Some questions to keep in mind as you read:
- Is it clear what the package does and what states/years are covered?
- Are the installation steps easy to follow for your level of R experience?
- Is there anything you expected to find in the docs that wasn’t there?
- Are the column descriptions in the data dictionary clear and useful?
Step 4: Run the tests
Below are test calls grouped by state. You don’t need to run all of them — pick a few states you’re interested in, or work through them in order. Each call fetches a single recent year to keep things fast, but feel free to adjust the years, input variables, or any other areas of interest (note: keep year ranges minimal — we are working on a downloadable dataset so these sites do not need to be constantly scraped). Do your best to try to break things and report any issues.
After each call, look at what comes back and note anything surprising, confusing, or broken.
Note: In your R Global Environment you should see different data frames appear related to state, county, and (if available) precinct data.
Virginia (ElectionStats)
va <- scrape_elections(state = "virginia", year_from = 2023, year_to = 2023)Colorado (includes precinct data)
co <- scrape_elections(state = "colorado", year_from = 2022, year_to = 2022)Massachusetts
level = "state" returns only candidate-level results.
Omit it to get county data as well.
ma <- scrape_elections(state = "massachusetts", year_from = 2022, year_to = 2022, level = "state")Idaho (includes precinct data)
id <- scrape_elections(state = "idaho", year_from = 2024, year_to = 2024)New York
New York uses a headless browser to render JavaScript — expect this call to take 1–2 minutes.
ny <- scrape_elections(state = "new_york", year_from = 2024, year_to = 2024)New Mexico (includes precinct data)
New Mexico uses a headless browser to render JavaScript — expect this call to take 1–2 minutes.
nm <- scrape_elections(state = "new_mexico", year_from = 2024, year_to = 2024)South Carolina
South Carolina uses a headless browser to render JavaScript — expect this call to take 1–2 minutes.
sc <- scrape_elections(state = "south_carolina", year_from = 2024, year_to = 2024)What to look for
As you test, please note anything in these categories:
Installation and setup
- Did any installation step fail? What was the error message?
- What operating system are you on (Windows / macOS / Linux)?
Documentation
- Was anything in the README or vignettes unclear or hard to follow?
- Is there anything you expected to find in the docs that wasn’t there?
- Were the column descriptions in the data dictionary useful?
Errors or crashes
- Did any
scrape_elections()call return an error? Please copy the full error message. - Did it hang or take unexpectedly long (more than 5 minutes for a single year)?
Data quality
- Do the results look roughly correct for the state and year? (You can spot-check against a quick Google search for that election.)
- Are any columns missing values you’d expect?
- Are column names confusing or inconsistent across states?
Usability
- Is there data you wished the package returned but doesn’t?
- Is there a state or time period you tried that didn’t work?
- Any other suggestions for improvement?
Sharing your feedback
Please send feedback to grahamchickering@gmail.com or Chris Warshaw, chris.warshaw@georgetown.edu. The most helpful reports include:
- What you ran (the exact code or a brief description)
- What happened (error message, unexpected output, or something confusing)
- Your operating system (Windows, Mac, Linux, etc.) and R version
(
R.version$version.string)
You’re also welcome to file issues directly at https://github.com/gchickering21/DownBallotR/issues
Thank you — your feedback is genuinely valuable at this stage.