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%"
)
```

# twoxtwo

<!-- badges: start -->
[![build status (main)](https://github.com/vpnagraj/twoxtwo/workflows/R-CMD-check-main/badge.svg)](https://github.com/vpnagraj/twoxtwo/actions)
[![build status (dev)](https://github.com/vpnagraj/twoxtwo/workflows/R-CMD-check-dev/badge.svg)](https://github.com/vpnagraj/twoxtwo/actions)
[![](https://cranlogs.r-pkg.org/badges/twoxtwo)](https://cran.r-project.org/package=twoxtwo)
<!-- badges: end -->

The `twoxtwo` package provides a collection of functions to display, summarize, and analyze data in two-by-two contingency tables. Statistical analysis functions are oriented towards epidemiological investigation of exposure/outcome relationships.

## Installation

To install the stable release from CRAN:

```{r, eval=FALSE}
install.packages("twoxtwo")
```

Or to install the development release from GitHub:

```{r, eval=FALSE}
## install.packages("devtools")
devtools::install_github("vpnagraj/twoxtwo", build_vignettes = TRUE)
```

## Features

- `twoxtwo()`: Construct `twoxtwo` object
- `odds_ratio()`: Estimate odds ratio and confidence interval
- `risk_ratio()`: Estimate risk ratio and confidence interval
- `risk_diff()`: Estimate risk difference and confidence interval
- `fisher()`: Perform Fisher's exact test
- `chisq()`: Perform Pearson's chi-squared test
- `arp()`: Estimate attributable risk proportion (ARP) and confidence interval
- `parp()`: Estimate population attributable risk proportion (PARP) and confidence interval
- `ein()`: Estimate exposure impact number (EIN) and confidence interval
- `cin()`: Estimate case impact number (CIN) and confidence interval
- `ecin()`: Estimate exposed cases impact number (ECIN) and confidence interval
- `summary.twoxtwo()`: Summarize `twoxtwo` object
- `print.twoxtwo()`: Print `twoxtwo` object
- `display()`: Render `twoxtwo` table contents as a `knitr::kable`

## Usage

### Example

First load `twoxtwo` and `dplyr` to help prep data:

```{r, message=FALSE, warning=FALSE}
library(twoxtwo)
library(dplyr)
```

Next create a object with S3 class `twoxtwo`. For this example, use the `twoxtwo::titanic` dataset. Note that "exposure" and "outcome" variables must each be binary variables:

```{r}
crew_2x2 <-
  titanic %>%
  twoxtwo(.data = ., exposure = Crew, outcome = Survived)

crew_2x2
```

The `twoxtwo` class has its own `summary.twoxtwo()` method that computes effect measures (odds ratio, risk ratio, and risk difference):

```{r}
summary(crew_2x2)
```

Individual measures of effect, hypothesis tests, and impact numbers can be calculated using the `twoxtwo` object. For example:

```{r}
crew_2x2 %>%
  odds_ratio()
```

```{r}
crew_2x2 %>%
  chisq()
```

Note that data analysis can also be performed without first creating the `twoxtwo` object:

```{r}
titanic %>%
  odds_ratio(.data = ., exposure = Crew, outcome = Survived)
```

```{r}
titanic %>%
  chisq(.data = ., exposure = Crew, outcome = Survived)
```

### Vignettes

The package includes vignettes to describe usage in more detail.

For details on the `twoxtwo` data structure and demonstration of basic usage: 

```{r, eval = FALSE}
vignette("basic-usage", package = "twoxtwo")
```

For formulas and examples of how to calculate measures of effect:

```{r, eval = FALSE}
vignette("measures-of-effect", package = "twoxtwo")
```

For information on hypothesis testing functionality in the package:

```{r, eval = FALSE}
vignette("hypothesis-testing", package = "twoxtwo")
```

For formulas and demonstration of attributable fraction and impact number calculations:

```{r, eval = FALSE}
vignette("af-impact", package = "twoxtwo")
```

## Contributing

Please use GitHub issues to report bugs or request features. Contributions will be reviewed via pull requests.