README.Rmd

---
output: rmarkdown::github_document
editor_options: 
  chunk_output_type: console
---
```{r include=FALSE}
knitr::opts_chunk$set(fig.retina=2)
```

# voteogram

U.S. House and Senate Voting Cartogram Generators

## Description

'ProPublica' <https://projects.propublica.org/represent/> makes United States Congress member votes available and has developed their own unique cartogram to visually represent this data as has 'GovTrack' <URL_AT_SOME_POINT> . Tools are provided to retrieve voting data, prepare voting data for plotting with 'ggplot2', create vote cartograms and theme them.
    
Ref: (these are replicated below)

- <https://projects.propublica.org/represent/votes/115/senate/1/110>
- <https://projects.propublica.org/represent/votes/115/house/1/256>
- <https://www.govtrack.us/congress/votes/115-2017/h256>

You can grab the results of a roll call vote (House or Senate) with `roll_call()`. It returns a `list` with a ton of information that you can use outside this package. One
element of that list is the `data.frame` of vote results. You can pass in the _entire_
object to either `_carto()` function and it'll "fortify" it before shunting it off
to ggplot2. Try to cache this data (I do, below, in R markdown chunk) as you're ticking credits off of ProPublica's monthly free S3 allotment each call. Consider donating to them if you're too lazy to cache the data). 

## TODO

- <strike>House cartogram generator</strike>
- <strike>Param bulletproofing (param checking, et al)</strike>
- <strike>Add in ability to retrieve votes from ProPublica.</strike>
- <strike>Make a `voteogram` theme</strike>
- <strike>GovTrack Senate cartogram polygons</strike> (this is pretty much covered in [`ggparliament`](https://github.com/leeper/ggparliament) since GT only has the seat view for the Senate)
- <strike>"Independent" colors for "not voting" & "present"</strike>
- <strike>Vignette</strike>
- `htmlwidget` version

## What's In The Tin

The following functions are implemented:

- `house_carto`:	Produce a ProPublica- or GovTrack-style House roll call vote cartogram
- `senate_carto`:	Produce a Senate cartogram
- `roll_call`:	Get Voting Record for House or Senate By Number, Session & Roll Call Number

Helpers: 

- `theme_voteogram`: voteogram ggplot2 theme
- `print.pprc`:	Better default 'print' function for `roll_call()` (`pprc`) objects
- `fortify.pprc` : In case you want to use the voting data frame from a `roll_call()` (`pprc`) object in your own plots and forget to just `$votes` it out. #helping

## Working with `voteogram`

### Installation

```{r eval=FALSE}
remotes::install_github("hrbrmstr/voteogram")
```

```{r message=FALSE, warning=FALSE, error=FALSE, include=FALSE}
options(width=120)
```

### Basic Usage

```{r message=FALSE, warning=FALSE, error=FALSE}
library(voteogram)
library(hrbrthemes)
library(ggplot2)

# current verison
packageVersion("voteogram")
```

```{r cache=TRUE}
sen <- roll_call("senate", 115, 1, 110)
rep <- roll_call("house", 115, 1, 256)
```

```{r}
str(sen)

sen$votes
```

```{r}
str(rep)

fortify(rep)
```

### ProPublica

```{r sen, fig.width=10, fig.height=7}
senate_carto(sen) +
  labs(title="Senate Vote 110 - Invokes Cloture on Neil Gorsuch Nomination") +
  theme_ipsum_rc(plot_title_size = 24) +
  theme_voteogram()
```

```{r rep_pp_square, fig.width=10, fig.height=7}
house_carto(rep, pp_square=TRUE) +
  labs(x=NULL, y=NULL, 
       title="House Vote 256 - Passes American Health Care Act,\nRepealing Obamacare") +
  theme_ipsum_rc(plot_title_size = 24) +
  theme_voteogram()
```

```{r rep_pp_orig, fig.width=10, fig.height=7}
house_carto(rep, pp_square=FALSE) +
  labs(x=NULL, y=NULL, 
       title="House Vote 256 - Passes American Health Care Act,\nRepealing Obamacare") +
  theme_ipsum_rc(plot_title_size = 24) +
  theme_voteogram()
```

### GovTrack

```{r rep_gt, fig.width=10, fig.height=7}
house_carto(rep, "gt") +
  labs(x=NULL, y=NULL, 
       title="House Vote 256 - Passes American Health Care Act,\nRepealing Obamacare") +
  theme_ipsum_rc(plot_title_size = 24) +
  theme_voteogram()
```

### Tiny Cartograms

They can be shrunk down well (though that means annotating them in some other way):

```{r sen_small, fig.width=3, fig.height=2.1}
senate_carto(sen) + theme_voteogram(legend=FALSE)
```

```{r rep_small, fig.width=3, fig.height=2.1}
house_carto(rep) + theme_voteogram(legend=FALSE)
```

```{r rep_small_1, fig.width=3, fig.height=2.1}
house_carto(rep, pp_square=TRUE) + theme_voteogram(legend=FALSE)
```

### Test Results

```{r message=FALSE, warning=FALSE, error=FALSE}
library(voteogram)
library(testthat)

date()

test_dir("tests/")
```

## Code of Conduct

Please note that this project is released with a [Contributor Code of Conduct](CONDUCT.md). By participating in this project you agree to abide by its terms.