Python setup for DownBallotR

1. Install the package

You can install the development version from GitHub:

install.packages("pak")
pak::pak("gchickering21/Downballot")

Or using remotes:

install.packages("remotes")
remotes::install_github("gchickering21/Downballot")

Then load the package:

library(DownBallotR)

2. First-time setup (required once)

After installing the R package, you must set up the Python environment used by DownBallotR.

Step 1: Install Python dependencies

Run the following once:

downballot_install_python()

This command:

• Creates a dedicated Python virtual environment for DownBallotR
• Installs required Python packages
• Installs Playwright and its Chromium browser
  (this may download ~100–200MB the first time)

This step may take a few minutes.

---

Step 2: Verify the setup

After installation completes, check the status:

downballot_python_status()

You should see output indicating:

• The virtual environment exists
• Required Python packages are installed
• Playwright Chromium is available

At this point, Python is installed but not yet active in your R session.

---

3. Normal usage (each R session)

Each R session must explicitly activate the Python environment once per session.

Activate Python for the session

At the start of any R session where you plan to use DownBallotR, run:

downballot_use_python()

This:

• Pins reticulate to the correct Python virtual environment
• Safely initializes Python for the current R session

You only need to run this once per session.

---

Optional: check status

At any time, you can check the current state of the Python environment:

downballot_python_status()

This reports:

• Whether Python is initialized
• Which Python interpreter is active
• Whether required packages are available

---

4. Using DownBallotR in future or concurrent sessions

New R session?

If you restart R, open a new RStudio window, or start a separate R process, simply run:

downballot_use_python()

You do not need to reinstall Python.

---

Multiple R sessions at the same time

If you have multiple R sessions open concurrently:

• Each session must call downballot_use_python() once
• All sessions can safely share the same virtual environment

---

5. Common issues and fixes

Python is not initialized or packages appear missing

Run:

downballot_use_python()
downballot_python_status()

If packages are still missing:

downballot_install_python(reinstall = TRUE)

---

“reticulate is already initialized to a different Python interpreter”

This occurs when Python is initialized before calling downballot_use_python().

Fix:

1. Restart your R session
2. Immediately run:

downballot_use_python()

Then continue using the package.

Reinstall everything from scratch

If the environment becomes corrupted or inconsistent:

downballot_install_python(reinstall = TRUE)
downballot_use_python()
downballot_python_status()

---

6. Recommended workflow summary

First-time setup:

downballot_install_python()
downballot_use_python()

Every new R session:

downballot_use_python()

Check environment status:

downballot_python_status()