---
title: "Descriptive tables"
author: "Raban Heller"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Descriptive tables}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
resource_files:
- figures/logo.svg
- figures/logo-dark.svg
---
```{r setup, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```
A descriptive table summarizes the analyzed data, usually by group. In
infereportR such a table states its denominators and missing counts, contains
no hypothesis test by default, and keeps any added inference apart from the
descriptive summaries. This vignette uses the `ToothGrowth` data set that
ships with R.
```{r packages}
library(infercalcR)
library(infereportR)
```
## Describe raw data
`ToothGrowth` records the length of odontoblasts, the cells responsible for
tooth growth, in 60 guinea pigs. Each animal received vitamin C as orange juice
(`OJ`) or ascorbic acid (`VC`) at one of three daily doses. Two lengths are set
to missing here to show how denominators are reported, and the dose is treated
as an ordered category.
```{r data}
tg <- ToothGrowth
tg$dose <- factor(tg$dose, levels = c(0.5, 1, 2), ordered = TRUE)
tg$len[c(3, 41)] <- NA
```
Given a data frame, `report_descriptive()` asks `infercalcR::describe_data()`
for the summaries and formats the result. Labels and units are optional and
are matched by variable name:
```{r describe}
desc <- report_descriptive(tg, group = "supp",
labels = c(len = "Odontoblast length", dose = "Daily dose"),
units = c(dose = "mg/day"))
```
Continuous variables are summarized by mean, standard deviation, median,
quartiles, minimum and maximum. Each row reports the number of observations
used (`n`), the number missing (`n.missing`) and the group total (`n.total`):
```{r continuous}
continuous <- desc$variable_type == "continuous" &
desc$estimand %in% c("mean", "sd", "median")
desc[continuous, c("group", "label", "estimand", "estimate_display",
"n", "n.missing", "n.total")]
```
Categorical variables, including ordered factors, are reported as counts with
proportions of the nonmissing observations in each group:
```{r categorical}
desc[desc$variable_type == "categorical",
c("group", "label", "unit", "level", "estimate_display", "proportion", "n")]
```
The table is a plain data frame in long format. Base R can reshape it into the
familiar layout with one column per group:
```{r wide}
summary_rows <- desc[desc$estimand %in% c("mean", "sd"),
c("label", "estimand", "group", "estimate_display")]
reshape(summary_rows, idvar = c("label", "estimand"), timevar = "group",
direction = "wide")
```
No p-value columns are created and no test is chosen automatically.
## Report a stored description
A description can also be computed once with infercalcR and reported later.
In that case the selection and labeling arguments are not used, since they
already belong to the stored result:
```{r stored}
stored <- describe_data(tg, variables = "len", group = "supp")
report_descriptive(stored)[, c("group", "estimand", "estimate_display", "n")]
try(report_descriptive(stored, group = "supp"))
```
## Add supplied inference
A prespecified test can be shown next to the descriptive rows. It is computed
separately, here on the complete cases, and joined only through explicit
identifiers: the variable, the result and the result row. Display labels are
never used for matching, and the analysis population of the test must be named.
```{r inference}
complete <- !is.na(tg$len)
len_test <- run_inference(method_spec("t_means_two_independent_welch"),
x = tg$len[complete & tg$supp == "OJ"],
y = tg$len[complete & tg$supp == "VC"],
result_id = "len-oj-vs-vc")
mapping <- data.frame(
variable_id = "len",
result_id = "len-oj-vs-vc",
row_id = result_data(len_test)$row_id
)
joined <- report_descriptive(tg, group = "supp",
labels = c(len = "Odontoblast length", dose = "Daily dose"),
units = c(dose = "mg/day"),
inference = len_test, mapping = mapping,
inference_population = "Complete cases; OJ minus VC")
joined[joined$estimand == "mean",
c("group", "label", "estimate_display", "n", "inference_p_display",
"inference_n", "inference_population")]
```
All joined fields carry the prefix `inference_`. At most one inference row can
be attached to each variable. The metadata keeps the descriptive and the
inferential population separately:
```{r populations}
meta <- report_metadata(joined)
meta$inference_population
meta$inference_mapping
```
```{r acknowledgments, child = "children/_acknowledgments.Rmd"}
```