---
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: source
knitr:
  opts_chunk: 
    collapse: true
    comment: "#" 
bibliography: DemographicTable.bib
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.

Package **`DemographicTable`** `Imports` packages

-   **`cli`** [@cli, v`r packageVersion('cli')`], for attractive command line interfaces
-   `r '\U1f5dd'` **`flextable`** [@flextable, v`r packageVersion('flextable')`] and **`officer`** [@officer, v`r packageVersion('officer')`], key dependencies, for flexible table
-   **`scales`** [@scales, v`r packageVersion('scales')`], for colour pallete


## Prerequisite

Packages **`DemographicTable`** requires R version 4.5.0 (released 2025-04-11) or higher ([macOS](https://cran.r-project.org/bin/macosx/), [Windows](https://cran.r-project.org/bin/windows/base/)). An Integrated Development Environment (IDE), e.g., [RStudio](https://posit.co/download/rstudio-desktop/) or [Positron](https://positron.posit.co/download.html), is not required, but highly recommended. This vignette is created under `r R.version$version.string` using packages **`knitr`** [@knitr, v`r packageVersion('knitr')`], **`quarto`** [@quarto, v`r packageVersion('quarto')` with [Quarto](https://quarto.org/docs/get-started/) v`r quarto::quarto_version()`] and **`rmarkdown`** [@rmarkdown, v`r packageVersion('rmarkdown')`].

```{r}
#| code-fold: true
#| code-summary: "Environment on author's computer"
Sys.info()[c('sysname', 'release', 'machine')]
R.version
```

Experimental (and maybe unstable) features are released *extremely frequently* to [Github](https://github.com/tingtingzhan/maxEff). Stable releases to [CRAN](https://CRAN.R-project.org/package=DemographicTable) are typically updated every 2 to 3 months.

```{r}
#| eval: false
remotes::install_github('tingtingzhan/DemographicTable')
```

```{r}
#| eval: false
utils::install.packages('DemographicTable')
```

## Getting Started

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

```{r}
library(DemographicTable)
library(flextable)
```

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 example `penguins` from package **`datasets`**

## Summary of all subjects

```{r}
datasets::penguins |>
  DemographicTable(include = c('species', 'island', 'bill_len')) |> 
  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}
datasets::penguins |>
  DemographicTable(groups = 'sex', include = c('species', 'bill_dep')) |> 
  as_flextable()
```

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

```{r}
datasets::penguins |>
  DemographicTable(groups = 'sex', include = c('species', 'bill_dep'), compare = FALSE) |>
  as_flextable()
```

## Summary by multiple `groups`

```{r}
datasets::penguins |>
  DemographicTable(groups = c('sex', 'island'), include = c('species', 'bill_dep'), compare = FALSE) |> 
  as_flextable()
```

# Combine multiple `DemographicTable`s

```{r}
tb1 = datasets::penguins |>
  subset(subset = (sex == 'male')) |>
  DemographicTable(groups = 'island', include = c('species', 'bill_dep'), data.name = 'Male Penguins', compare = FALSE)
```

```{r}
tb2 = datasets::penguins |>
  subset(subset = (sex == 'female')) |>
  DemographicTable(groups = 'island', include = c('species', 'bill_dep'), data.name = 'Female Penguins', compare = FALSE)
```

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

# Exception Handling

## Missing value in `groups`

```{r}
datasets::penguins |>
  DemographicTable(groups = c('sex'), include = c('body_mass', 'species')) |>
  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 = datasets::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}
#| warning: false
mtc |>
  DemographicTable(groups = 'am_manual', include = c('drat', 'vs_straight')) |>
  as_flextable()
```

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()
```