---
title: "toplines"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{toplines}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r setup}
library(pollster)
library(dplyr)
library(knitr)
library(ggplot2)
```

The default topline table comes with columns for response category, frequency count, percent, valid percent, and cumulative percent.

```{r}
topline(df = illinois, variable = voter, weight = weight) %>%
  kable()
```

Because the output is a `tibble`, it's simple to manipulate it in any way you want after creating it. Use `dplyr::select` to remove columns or `dplyr::filter` to remove rows. For convenience, the `topline` function also provides ways to do this within the function call. For example, the `remove` argument accepts a character vector of response values to be removed from the table *after* all statistics are calculated. This is especially useful for survey data with a "refused" category.

```{r}
topline(df = illinois, variable = voter, weight = weight, 
        remove = c("(Missing)"), pct = FALSE) %>%
  mutate(Frequency = prettyNum(Frequency, big.mark = ",")) %>%
  kable(digits = 0)
```

Refer to the [`kableExtra` package](https://CRAN.R-project.org/package=kableExtra) for lots of examples on how to format the appearance of these tables in either HTML or PDF latex formats. I recommend the vignettes "Create Awesome HTML Table with knitr::kable and kableExtra" and "Create Awesome PDF Table with knitr::kable and kableExtra.

## Graphs

```{r, fig.width=4}
topline(df = illinois, variable = voter, weight = weight) %>%
  ggplot(aes(Response, Percent, fill = Response)) +
  geom_bar(stat = "identity")
```

## Margin of error

Get at topline table with the margin of error in a separate column using the `moe_topline` function. By default, a z-score of 1.96 (95% confidence interval is used). Supply your own desired z-score using the `zscore` argument.

```{r}
moe_topline(df = illinois, variable = educ6, weight = weight)
```

The margin of error is calculated including the design effect of the sample weights, using the following formula:

`sqrt(design effect)*zscore*sqrt((pct*(1-pct))/(n-1))*100`

The design effect is calculated using the formula `length(weights)*sum(weights^2)/(sum(weights)^2)`.