---
title: "Demographic Table"
author: Tingting Zhan
format: 
  html:
    page-layout: full
    html-math-method: katex
toc: true
toc-location: left
toc-depth: 4
toc-title: ''
editor: visual
vignette: >
  %\VignetteIndexEntry{intro}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
---

# Introduction

This vignette of package **`DemographicTable`** ([CRAN](https://cran.r-project.org/package=DemographicTable), [Github](https://github.com/tingtingzhan/DemographicTable)) presents an idiot-proof interface to create a summary table of simple statistics, often known as a demographic table.

## Note to Users

Examples in this vignette require that the `search` path has

```{r}
#| message: false
library(DemographicTable)
library(flextable)
set_flextable_defaults(font.size = 9)
```

```{r}
#| echo: false
library(knitr) # for tables in this vignette
#options(mc.cores = 1L) # for CRAN submission
```

Users may remove the last pipe `|> as_flextable()` from all examples. This is required in the vignette to make **`quarto`** rendering work.

# Demographic Table

Data preparation

```{r}
tgr = ToothGrowth |> 
  within.data.frame(expr = {
    dose = factor(dose) 
  })
```

## Summary of all subjects

```{r}
tgr |>
  DemographicTable(include = c('supp', 'len', 'dose')) |> 
  as_flextable()
```

## Summary by one `group`

Color of each individual `group` is determined by `scales::pal_hue()`, which is the default color pallete used in package **`ggplot2`**.

```{r}
tgr |>
  DemographicTable(groups = 'supp', include = c('len', 'dose')) |> 
  as_flextable()
```

User may choose to hide the $p$-values with option `compare = FALSE`.

```{r}
tgr |>
  DemographicTable(groups = 'supp', include = c('len', 'dose'), compare = FALSE) |> 
  as_flextable()
```

## Summary by multiple `groups`

```{r}
tgr |>
  DemographicTable(groups = c('supp', 'dose'), include = c('len', 'supp')) |>
  as_flextable()
```

# Contatenate multiple `DemographicTable`s

```{r}
tb1 = CO2 |>
  DemographicTable(groups = 'Type', include = c('conc', 'uptake'))
```

```{r}
tb2 = CO2 |>
  subset(subset = (Treatment == 'nonchilled')) |> 
  DemographicTable(groups = 'Type', include = c('conc', 'uptake'), data.name = 'CO2_nonchilled')
```

```{r}
c(tb1, tb2) |> as_flextable()
```

# Exception Handling

## Missing value in `groups`

```{r}
MASS::survey |>
  DemographicTable(groups = c('M.I'), include = c('Pulse', 'Fold')) |>
  as_flextable()
```

## Use of `logical` values

Using `logical` values is discouraged, as this practice is proved confusing to scientists without a strong data background.

```{r}
mtc = mtcars |>
  within.data.frame(expr = {
    vs_straight = as.logical(vs)
    am_manual = as.logical(am)
  })
```

A warning message will be printed if `logical` variables are used in `groups` and/or `include`.

```{r}
tryCatch(DemographicTable(mtc, groups = 'am_manual', include = c('drat', 'vs_straight')), warning = identity)
```

Instead of using `logical` variables

```{r}
mtc |>
  DemographicTable(groups = 'am_manual', include = c('drat', 'vs_straight')) |>
  as_flextable() |>
  suppressWarnings()
```

We recommend using 2-`level` `factor`s.

```{r}
mtcars |>
  within.data.frame(expr = {
    vs = ifelse(vs, yes = 'Straight', no = 'V-shaped')
    am = ifelse(am, yes = 'manual', no = 'automatic')
  }) |> 
  DemographicTable(groups = 'am', include = c('drat', 'vs'), data.name = 'mtcars') |>
  as_flextable()
```