R/data-objects.R

In eiballots: Ballot-Level Microdata and Summaries for Ecological Inference (Florida 2000)

# ----------------------------------------------------------------------------
# election_catalog
# ----------------------------------------------------------------------------

#' Election catalog
#'
#' A named list documenting all races available in the Florida 2000 general
#' election dataset. Each element is named by the election code used as a
#' column name in the county microdata files.
#'
#' @format A named list. Each element contains:
#' \describe{
#'   \item{`type`}{Race type: `"single_member"`, `"multi_member"`, or
#'     `"referendum"`.}
#'   \item{`office`}{Full name of the office or ballot measure.}
#'   \item{`level`}{Scope of the election: `"federal"`, `"state"`, `"county"`,
#'     `"district"`, or `"local"`.}
#'   \item{`counties`}{Character vector of county codes/names that include this
#'     race, or the string `"all"` if every county in the dataset
#'     participates.}
#'   \item{`vote_for`}{Maximum number of candidates the
#'     voter could select.}
#'   \item{`options`}{Character vector of individual candidate (voting options)
#'     abbreviations as they appear in the data (e.g.
#'     `c("Bau", "Duf")`), including observed combinations (e.g. `"BauDuf"`) as
#'     derived automatically from the microdata.}
#'   \item{`candidates`}{Character vector of individual candidate (voting options)
#'     (e.g. `c("Barret", "Bauchert", "Berkowitz", "Brown", "Duff", "Abstention", "Invalid vote")`).
#'     This field documents the individual candidates (options) on the ballot.}

#' }
#'
#' @details
#' In the microdata files, votes are recorded as follows:
#' \itemize{
#'   \item A candidate code or combination (e.g. `"R"`, `"D"`, `"BauDuf"`,
#'     `"Y"`) for a valid vote cast.
#'   \item `"A"` for a blank vote: the voter was eligible but did not mark a
#'     choice in this race. Treated as an active category in all summaries.
#'   \item `"I"` for an invalid vote: the voter's mark(s) was not counted.
#'     Treated as an active category in all summaries.
#'   \item `NA` for structural non-participation: the voter was not eligible
#'     to vote in this race (e.g. a race restricted to a specific district).
#'     `NA` values exclude the voter from the universe of that race.
#' }
#' The distinction between `"A"`, `"I"`, and `NA` is critical for ecological
#' inference: only `NA` values define the universe boundary.
#'
#' @seealso [county_catalog], [list_elections()], [list_counties()],
#'   [ei_summary()]
#'
#' @examples
#' # Inspect the presidential race entry
#' election_catalog[["PRE"]]
#'
#' # List all federal races
#' list_elections(level = "federal")
"election_catalog"


# ----------------------------------------------------------------------------
# county_catalog
# ----------------------------------------------------------------------------

#' County catalog
#'
#' A named list mapping each county data file to the race codes it contains.
#' Used internally to determine which county files must be loaded for a given
#' set of races.
#'
#' @format A named list. Each element is named by the county code (matching
#'   the `.RData` filename without extension) and contains a character vector
#'   of the race codes present in that county's file.
#'
#' @details
#' The county code is used to construct the filename: county `"Lee"` maps to
#' `Lee.RData`. This list is consulted by [get_election_data()] and
#' [ei_summary()] to determine which files to load.
#'
#' @seealso [election_catalog], [list_counties()], [get_county_data()]
#'
#' @examples
#' # Races available in Lee county
#' county_catalog[["Lee"]]
#'
#' # All counties in the dataset
#' names(county_catalog)
"county_catalog"

# ----------------------------------------------------------------------------
# example_ballots
# ----------------------------------------------------------------------------

#' Example ballot-level data
#'
#' A small simulated dataset used in examples and tests.
#' The dataset contains 100 simulated observations from five simulated precincts
#' in Lee county, with pre-election and U.S. Senate vote categories.
#'
#' @format A data frame with 100 rows and 4 variables:
#' \describe{
#'   \item{COUNTY}{County name.}
#'   \item{PRECINCT}{Precinct identifier.}
#'   \item{PRE}{Pre-election vote category.}
#'   \item{USS}{U.S. Senate vote category; may contain missing values.}
#' }
#'
#' @source Simulated data generated for examples.
#'
#' @usage data(example_ballots)
"example_ballots"