---
title: "Introduction to the voteogram package"
author: "Bob Rudis"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to the voteogram package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

Basic usage only requires this package and `ggplot2`:

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

## Getting Vote Data

The cartograms need data and the best way to do that is by obtaining roll call vote data from ProPublica via the `roll_call()` function. Data can be retrieved for any House or Senate vote by specificing the target vote parameters:

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

```{r real_data, echo=FALSE}
sen <- readRDS(system.file("extdata", "sen.rds", package="voteogram"))
rep <- readRDS(system.file("extdata", "rep.rds", package="voteogram"))
```

Their structures look the same and there is a print-method to make the console output easier on the eyes:

```{r}
str(sen)

sen$votes
```

```{r}
str(rep)

fortify(rep)
```

That data may be useful on its own (ouside of plotting).

Note, also, that `ggplot2`'s `fortify()` method uses the provided object class method for roll call objects to know how to extract the rectangular data necessary for plotting.

## Making Cartograms

These cartograms have a few style options:

### ProPublica

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

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

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

### GovTrack

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

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

### Tiny Cartograms

```{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)
```