---
title: "Getting started with infereportR"
author: "Raban Heller"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Getting started with infereportR}
%\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 = "#>")
has_ggplot2 <- requireNamespace("ggplot2", quietly = TRUE)
```
infereportR presents statistical results that are already finished. It turns
them into tables, sentences for a manuscript and labels for a plot. It does not
run tests, fit models, compute intervals or adjust p-values. Those steps belong
to infercalcR, which stores every result in a common, plain-data format.
infereportR reads that format through `infercalcR::result_data()` and
`infercalcR::result_metadata()` and formats what it finds.
This vignette walks through one result from calculation to table, text and
plot. It uses the `PlantGrowth` data set that ships with R and runs offline.
```{r packages}
library(infercalcR)
library(infereportR)
```
## Compute a result with infercalcR
`PlantGrowth` holds the dried weight of 30 plants: 10 in a control condition
(`ctrl`) and 10 in each of two treatment conditions (`trt1`, `trt2`). The
analysis is chosen in advance: a Welch two-sample t-test comparing `trt2`
with `ctrl`. The method, sidedness and confidence level are fixed in the
specification before any data are seen.
```{r compute}
trt2 <- PlantGrowth$weight[PlantGrowth$group == "trt2"]
ctrl <- PlantGrowth$weight[PlantGrowth$group == "ctrl"]
welch <- run_inference(
method_spec("t_means_two_independent_welch"),
x = trt2, y = ctrl,
result_id = "trt2-vs-ctrl"
)
welch
```
The estimate is the difference in means, `x` minus `y`, here `trt2` minus
`ctrl`. All numbers are now final. Every step below only reads them.
## Report a table
`report_table()` returns an ordinary data frame with one row per stored result
row. The analytical columns keep their full precision:
```{r table-precision}
tab <- report_table(welch)
tab[, c("estimand", "estimate", "conf.low", "conf.high", "p.value", "n")]
```
Formatted values sit in separate columns ending in `_display`, so rounding
never replaces a stored number:
```{r table-display}
tab[, c("estimate_display", "interval_display", "p_display", "confidence_display")]
```
`p_selected` and `p_selection` record which stored p-value is shown. The
default is the reported p-value; `p = "raw"` and `p = "adjusted"` select the
other stored columns. The number of digits and the decimal mark change the
presentation only:
```{r table-settings}
report_table(welch, digits = 2, p_digits = 4, decimal_mark = ",")[
, c("estimate_display", "interval_display", "p_display")]
```
Because the result is a plain data frame, any table tool can print it. For
example, with `knitr::kable()`:
```{r table-kable}
knitr::kable(
tab[, c("estimand", "estimate_display", "interval_display", "p_display", "n")],
col.names = c("Estimand", "Estimate", "Interval", "p-value", "n")
)
```
## Report text
`report_text()` writes one neutral sentence per row. The full style names the
method, the estimand, the estimate, the interval with its confidence level and
method, the test statistic, the p-value together with which p-value it is, the
sample size and the number of excluded observations:
```{r text-full}
cat(report_text(welch), sep = "\n")
```
The sentence contains no interpretation. It does not call a result
significant or relevant; that judgment stays with the author.
Shorter presets suit tables and figure legends:
```{r text-styles}
cat(report_text(welch, style = "estimate_ci_p"), sep = "\n")
cat(report_text(welch, style = "p"), sep = "\n")
```
A template inserts stored fields into your own wording. The supported fields
are `estimate`, `ci`, `p`, `statistic`, `method`, `estimand`, `contrast`,
`status` and `n`. Templates are substituted, never evaluated, and an unknown
field is an error:
```{r text-template}
cat(report_text(welch,
template = "trt2 minus ctrl: {estimate} {ci}; {p}; n = {n}"), sep = "\n")
try(report_text(welch, template = "{mean}"))
```
## Annotate a plot
The optional ggplot2 integration draws brackets and labels from the same
stored result. The chunks in this section run only when ggplot2 is installed.
A positions data frame states where each annotation goes. It has one row per
result row, identified by `row_id`, and a `y_position` in data units. Named
endpoints (`group1`, `group2`) need the order of the groups on the discrete
axis, given in `groups`.
```{r plot-bracket, eval = has_ggplot2, fig.width = 6, fig.height = 4, fig.alt = "Box plots of dried plant weight for the groups ctrl, trt1 and trt2, with a bracket from ctrl to trt2 labeled with the estimate, its interval and the p-value."}
library(ggplot2)
positions <- data.frame(
row_id = result_data(welch)$row_id,
group1 = "ctrl", group2 = "trt2",
y_position = 6.6
)
ggplot(PlantGrowth, aes(group, weight)) +
geom_boxplot(width = 0.5) +
stat_inference(welch, positions, groups = levels(PlantGrowth$group),
label = "estimate_ci_p", tip_length = 0.1) +
labs(x = NULL, y = "Dried weight")
```
`stat_inference()` returns ordinary ggplot2 layers. No test runs while the plot
is built or drawn, and the label is the same text that `report_text()` gives
for `style = "estimate_ci_p"`. `tip_length` is also in data units.
## Keep the provenance
Tables and text carry the result metadata as an attribute.
`report_metadata()` retrieves it, for example to record the method, the
result identifier and the analysis population next to a table:
```{r metadata}
meta <- report_metadata(tab)
meta[c("method_id", "result_id", "kind")]
str(meta$population)
```
## Shared formatters
Tables, text and plot labels use the same three formatters, which are also
exported:
```{r formatters}
format_estimate(c(0.494, -1.23456, NA))
format_interval(c(0.00513, -Inf), c(0.983, 2))
format_p(c(0.0479, 0.0004, 0, NA))
```
A p-value below the display threshold, including a stored zero, is shown as
`p < 0.001` rather than `p = 0`. A missing p-value is shown as unavailable and
never as nonsignificant. Infinite interval limits stay infinite.
## Next steps
- `vignette("comparison-families", package = "infereportR")` combines several
comparisons, displays adjusted p-values and covers plot annotations in more
detail.
- `vignette("descriptive-tables", package = "infereportR")` describes data with
explicit denominators and joins supplied inference.
```{r acknowledgments, child = "children/_acknowledgments.Rmd"}
```