README.Rmd

---
output: github_document
---

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

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# freqtables <img style="padding: 15px;" align="left" src="man/figures/freqtables_hex/freqtables.png" alt="freqtables hex logo" width="250" height="289">

<!-- badges: start -->
[![CRAN status](https://www.r-pkg.org/badges/version/freqtables)](https://cran.r-project.org/package=freqtables)
[![Downloads](http://cranlogs.r-pkg.org/badges/grand-total/freqtables)](https://www.r-pkg.org/pkg/freqtables)
<!-- badges: end -->

The goal of `freqtables` is to quickly make tables of descriptive statistics for categorical variables (i.e., counts, percentages, confidence intervals). This package is designed to work in a `tidyverse` pipeline, and consideration has been given to get results from R to Microsoft Word ® with minimal pain.

## Installation

You can install the released version of `freqtables` from [CRAN](https://CRAN.R-project.org) with:

``` r
install.packages("freqtables")
```

And the development version from [GitHub](https://github.com/) with:

``` r
# install.packages("devtools")
devtools::install_github("brad-cannell/freqtables")
```
## Example

Because `freqtables` is intended to be used in a `dplyr` pipeline, loading `dplyr` into your current R session is recommended.

```{r message=FALSE}
library(dplyr)
library(freqtables)
```

The examples below will use R's built-in `mtcars` data set.

```{r}
data("mtcars")
```

### freq_table()

The `freq_table()` function produces one-way and two-way frequency tables for categorical variables. In addition to frequencies, the `freq_table()` function displays percentages, and the standard errors and confidence intervals of the percentages. For two-way tables only, `freq_table()` also displays row (subgroup) percentages, standard errors, and confidence intervals.

For one-way tables, the default 95 percent confidence intervals displayed are logit transformed confidence intervals equivalent to those used by Stata. Additionally, `freq_table()` will return Wald ("linear") confidence intervals if the argument to ci_type = "wald".

For two-way tables, `freq_table()` returns logit transformed confidence intervals equivalent to those used by Stata.

Here is an example of using `freq_table()` to create a one-way frequency table with all function arguments left at their default values:

```{r}
mtcars %>% 
  freq_table(am)
```

Here is an example of using `freq_table()` to create a two-way frequency table with all function arguments left at their default values:

```{r}
mtcars %>% 
  freq_table(am, cyl)
```

You can learn more about the `freq_table()` function and ways to adjust default behaviors in vignette("descriptive_analysis").

### freq_test()

The `freq_test()` function is an S3 generic. It currently has methods for conducting hypothesis tests on one-way and two-way frequency tables. Further, it is made to work in a dplyr pipeline with the `freq_table()` function.

For the `freq_table_two_way` class, the methods used are Pearson's chi-square test of independence Fisher's exact test. When cell counts are <= 5, Fisher's Exact Test is considered more reliable.

Here is an example of using `freq_test()` to test the equality of proportions on a one-way frequency table with all function arguments left at their default values:

```{r}
mtcars %>%
  freq_table(am) %>%
  freq_test() %>%
  select(var:percent, p_chi2_pearson)
```

Here is an example of using `freq_test()` to conduct a chi-square test of independence on a two-way frequency table with all function arguments left at their default values:

```{r}
mtcars %>%
  freq_table(am, vs) %>%
  freq_test() %>%
  select(row_var:n, percent_row, p_chi2_pearson)
```

You can learn more about the `freq_table()` function and ways to adjust default behaviors in vignette("using_freq_test").

### freq_format()

The freq_format function is intended to make it quick and easy to format the output of the freq_table function for tables that may be used for publication. For example, a proportion and 95% confidence interval could be formatted as "24.00 (21.00 - 27.00)."

```{r}
mtcars %>%
  freq_table(am) %>%
  freq_format(
    recipe = "percent (lcl - ucl)",
    name = "percent_95",
    digits = 2
  ) %>%
  select(var, cat, percent_95)
```

You can learn more about the `freq_format()` function by reading the function documentation.