README.Rmd

---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)
```

# Rvoteview
[![Travis-CI Build Status](https://travis-ci.org/voteview/Rvoteview.svg?branch=master)](https://travis-ci.org/voteview/Rvoteview) [![AppVeyor Build status](https://ci.appveyor.com/api/projects/status/n13u8s0tnfsau1o6?svg=true)](https://ci.appveyor.com/project/lukesonnet/rvoteview)

**WARNING: This package is under construction. Please be patient and leave issues here on Github or contact [Luke Sonnet](mailto:luke.sonnet@gmail.com) with any questions.**

This is a package that enables you to query the Voteview database for roll calls and work with data frames or a `pscl` `rollcall` object.

To install this package, run the following (note you have to have devtools installed first):
```{r github-install, eval = F}
# install.packages('devtools')
devtools::install_github("voteview/Rvoteview")
```

For more thorough documentation, see the help files for individual functions and the vignette [at this link here](https://github.com/voteview/Rvoteview/tree/master/vignettes).

## Quick Start: Using Rvoteview

To use `Rvoteview`, you generally want to search the database to get a list of vote ids and then use those to return the individual votes. We query the database with a search term and some parameters to constrain the search. The default behavior is to search any words as key words, returning the roll calls that best match any key words you enter. Again, there are further examples in the [vignette](https://github.com/voteview/Rvoteview/tree/master/vignettes).

So let's start with a search for roll calls with the key word "Iraq".
```{r search}
library(Rvoteview)
  
res <- voteview_search("Iraq")
names(res)
  
## I will drop description since it is a very long field
res[1:5, 1:5]
```
Using `res$id` we can get a `rollcall` object (from the [`pscl` package](https://cran.r-project.org/web/packages/pscl/index.html)) that contains the full set of votes and data for each roll call. 

```{r download, results='hide'}
## Get a rollcall object using the ids, please limit to a few ids for now!
rc <- voteview_download(res$id[1:10])
```
```{r pscl-sum}
## Now this object can be used in many 'pscl' methods
summary(rc)
```

You also have lots of metadata on roll calls and legislators in various data frames. For example, we can see some legislator metadata:

```{r metadata}
rc$legis.long.dynamic[1:5, 1:5]
```

You can also search by start and end date, congress, and chamber. Please see the help files for each function after you install the package to see a little more about how they work.

```{r search-options}
## Voteview search with options
res <- voteview_search(
  "Iraq", 
  chamber = "House",
  congress = 110:112,
  enddate = "2013-04-20"
  )
res[1:5, 1:5]
```

We can print out the exact query that the function builds using all of these arguments by retrieving the 'qstring' attribute of the returned data frame:

```{r attribute}
attr(res, "qstring")
```

We can assemble and use these complex queries ourselves. Here's one example where we look for all roll calls with the key words "estate", "death", or "tax" and was held in the 100th to the 114th Congress.

```{r search-adv}
## Voteview search with options
res <- voteview_search("(alltext:estate death tax congress:[100 to 114])")
res[1:5, 1:5]
```

You can also search for member data using the `member_search` function.

```{r member-search}
res <- member_search("Paul", state = "KY")

res[1:5, 1:5]
```