USsenateClass: Election Class given state and surname of a US Senator

Description

For all individuals in x with houseSenate == "Senate", look up their state and surname in the reference table senate and return their Class. For individuals not found in senate, return x[[district]].

Senate classes 1, 2 and 3 have their normal elections in 6-year cycles including 2000, 2002, and 2004 (or 2018, 2020, and 2022), respectively. When vacancies occur out of cycle, the vacancy is first filled with appointment by the governor of the state, and an election to fill that seat occurs in the next even-numbered year. In particular, the class of that seat does not change.

For example, South Carolina Senator Jim DeMint resigned effective January 1, 2013. South Carolina Governor Nikki Haley appointed Tim Scott to serve until a special election in 2014. This is a Class 3 seat, which means that another election for that seat would occur in 2016.

Usage

USsenateClass(x, senate=readUSsenate(),
   Office='Office', state='state',
   surname='surname', district='district', 
   senatePattern='^Senate')

Arguments

data.frame with character or factor columns Office, state, surname, and district.

senate

data.frame as returned by readUSsenate.

Office

name of a character or factor variable x in which the members of the US Senate can be identified by grep(senatePattern, x[, Office]).

state

Standard 2-letter abbreviation for the state of the US

surname

the name of a column of x containing the surname

district

name of a column of x containing the number of the district in the US House. For states with only one representative, this may be 0.

senatePattern

a regular expression for identifying the senators from x[, Office].

Value

a data.frame with one row for each row of x and the following columns:

incumbent

logical vector: NA if Office == 'house'. If Office == 'senate', then TRUE if state:surname found in senate and FALSE otherwise.

District

a character vector containing the desired Class for all US Senators found in senate or a guess at the Class for non-incumbents. For members of the House, this returned the previous content of x[[District]].

NOTES:

1. Incumbents can be missed if the spelling of the surname is different between x and senate. This can occur with, for example, Spanish surnames containing an accent.

2. If one but not two incumbents is found, others are currently assigned to the class of an incumbent not found. This could be a mistake, because the person could be a previous incumbent or could have lost to the incumbent in the last election.

Details

The current algorithm may fail if both senators in a state have the same surname.

Examples

Run this code

# NOT RUN {
tst <- data.frame(Office=factor(
            c("House", "Senate", "Senate", 'Senate')),
        state=factor(c('SC', 'SC', 'SC', 'NY')),
        surname=c("Jones", "DeMint", "Graham", 'Smith'),
        district=c("9", NA, NA, NA),
        stringsAsFactors=FALSE)
if(!fda::CRAN()){                  
tst. <- USsenateClass(tst)

chk <- data.frame(incumbent=c(NA, FALSE, TRUE, FALSE),
                  district=c("9", "3", "2", "1 or 3"),
                  stringsAsFactors=FALSE)
# }
# NOT RUN {
all.equal(tst., chk)
# }
# NOT RUN {
##
## test with names different from the default
##
tst2 <- tst
names(tst2) <- letters[1:4]
tst2. <- USsenateClass(tst2, Office='a',
           state='b', surname='c', district='d')
# }
# NOT RUN {
all.equal(tst., tst2.)
# }
# NOT RUN {
}
# }