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

# jfbr: A Package of Miscellaneous Workflow Functions

<!-- badges: start -->
[![R-CMD-check](https://github.com/jbetz-jhu/impart/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/jbetz-jhu/impart/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/jbetz-jhu/jfbr/graph/badge.svg)](https://app.codecov.io/gh/jbetz-jhu/jfbr)
<!-- badges: end -->

The `jfbr` package is meant to test and share miscellaneous functions for quantitative workflows.

## Installation

You can install the development version of jfbr from [GitHub](https://github.com/) with:

```{r Install Impart, eval = FALSE, echo = TRUE}
# install.packages("devtools") # Install devtools if not already installed
devtools::install_github("jbetz-jhu/jfbr")
```


## Examples: 

### Tabulation {.tabset}

Convenience functions have been added for the `table1::table1()` function to make it easier to do different summaries and add hypothesis testing.

```{r Load-Packages}
library(jfbr)
library(table1)
library(knitr)
```

The package includes an example dataset `jfbr_test` which is used in the examples below:

```{r}
head(jfbr_test)
```


#### `table1()`: Default

The default for `table1::table1()` is to produce Mean (SD) and Median [Min, Max]
for numeric values, and `NA` is treated as a level of a factor for categorical
variables.

**Note: saving the result of `table1::table1()` and using `knitr::kable()`is only
necessary when HTML output is not possible (e.g. `output: github_document` in R
Markdown)**

```{r table1-Defaults}
# table1() defaults
my_table <-
  table1(
    x = ~ continuous + numbers + ordered + binary_factor + categorical |
      two_level_group,
    data = jfbr_test
  )

kable(my_table)
```




#### `table1()` + `table1_numeric` + `table1_categorical`

Using the argument `render.continuous = table1_numeric` adds Median [IQR] and [Max, Min], while `render.categorical = table1_categorical` summarizes the observed frequencies and tabulates the proportion of missing values separately:

```{r table1-table1_numeric-Default}
my_table <-
  table1(
    x = ~ continuous + numbers | two_level_group,
    data = jfbr_test,
    render.continuous = table1_numeric,
    render.categorical = table1_categorical
  )

kable(my_table)
```

The arguments `mean_sd`, `median_iqr`, and `range` control which summaries are computed. Quantiles can be added optionally with the `quantiles` argment:

```{r table1-table1_numeric}
# Only Mean/SD
my_table <-
  table1(
    x = ~ continuous + numbers | two_level_group,
    data = jfbr_test,
    render.continuous = 
      function(x)
        table1_numeric(
          x = x,
          mean_sd = TRUE, median_iqr = FALSE, range = FALSE,
          quantiles = NULL
        )
  )

kable(my_table)

# Only Mean/SD, 5% and 95% Quantiles
my_table <-
  table1(
    x = ~ continuous + numbers | two_level_group,
    data = jfbr_test,
    render.continuous = 
      function(x)
        table1_numeric(
          x = x,
          mean_sd = TRUE, median_iqr = FALSE, range = FALSE,
          quantiles = c(0.05, 0.95)
        )
  )

kable(my_table)
```




#### `table1()` + `table1_pvalue`

Hypothesis tests can be added to `table1` using the `extra.col` argument: there is a worked example of including `t.test` and `chisq.test` in the [table1 documentation](https://cran.r-project.org/web/packages/table1/vignettes/table1-examples.html#example-a-column-of-p-values). The `table1_pvalue` function is a convenience function that allows users to supply their own tests to be computed in `table1`. The defaults include `t.test` and ANOVA omnibus test (via a `lm` and `anova` wrapper) for continuous variables, and `chisq.test` for categorical variables:

```{r table1-pvalues-defaults}
my_table <-
  table1::table1(
    x = ~ numbers + continuous + binary + ordered + binary_factor +
      categorical | two_level_group,
    data = jfbr_test,
    overall = FALSE,
    extra.col =
      list("p-value" = table1_pvalue)
  )

kable(my_table)

my_table <-
  table1::table1(
    x = ~ numbers + continuous + binary + ordered + binary_factor +
      categorical | three_level_group,
    data = jfbr_test,
    overall = FALSE,
    extra.col =
      list("p-value" = table1_pvalue)
  )

kable(my_table)
```

Any function that returns an element `p.value` can be passed as an argument, allowing users to customize which tests are performed:

```{r table1-pvalues-custom}
my_table <-
  table1::table1(
    x = ~ numbers + continuous + binary + ordered + binary_factor +
      categorical | two_level_group,
    data = jfbr_test,
    overall = FALSE,
    extra.col =
      list("p-value" =
             function(x, value) table1_pvalue(
               x = x,
               variable = variable,
               test_numeric_2_levels = wilcox.test,
               test_numeric_more_than_2_levels = kruskal.test,
               test_categorical_2_levels = fisher.test,
               test_categorical_more_than_2_levels = fisher.test
             )
      )
  )

kable(my_table)
```