---
title: "Building a manuscript table end to end"
author: "John Ehrlinger"
date: today
format: html
vignette: >
  %\VignetteIndexEntry{Building a manuscript table end to end}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```

```{r setup}
library(hvtiRtables)
```

This walks one complete manuscript table, from a data frame to a
checked `.docx`, and then lays the same table out to describe its groups
side by side. The report path is shorter and covered in `?hv_man_table`.

## 1. Summarize the data

`hv_tbl_summary()` takes a grouped, ordered variable list and type
buckets, the way the SAS `%summarytable` macro does. Every variable in
`groups` appears in exactly one of `continuous`, `binary`, or
`categorical`.

```{r}
tbl <- hv_tbl_summary(
  gtsummary::trial,
  by = "trt",
  groups = list(
    Demography = c("age", "marker"),
    Disease = c("stage", "grade")
  ),
  continuous = c("age", "marker"),
  categorical = c("stage", "grade"),
  compare = "pvalue"
)
```

The result records what the manuscript style reads: the statistic it
shows and the comparison column.

```{r}
attr(tbl, "hv_stat_label")
attr(tbl, "hv_trailing")
```

## 2. Shape the manuscript table

```{r}
ft <- hv_man_table(tbl, style = "manuscript")
```

The `"compare"` layout, the default, for groups the table compares: one
overall `n` column, the grouping spanning its levels, and the P column.

## 3. Or describe the groups side by side

```{r}
ft2 <- hv_man_table(tbl, style = "manuscript", layout = "describe")
```

The `"describe"` layout gives each group its own count, for separate
cohorts or repeated measures. The P column stays, because the table
carries it. Either layout names the tests behind the p-values in its
dagger note, so there is no separate step for test footnotes.

## 4. Save and check

```{r}
out <- tempfile(fileext = ".docx")
hv_man_table_save(
  ft, out,
  caption = "Table 1. Baseline Characteristics",
  abbreviations = c(SMD = "standardized mean difference")
)
```

Neither saver checks its own output, so run `hv_check_docx()` on the
path, as the style that wrote it. Zero rows means clean.

```{r}
hv_check_docx(out, style = "manuscript")
```

```{r, include = FALSE}
unlink(out)
```

## What the package refuses

Every public function rejects out-of-spec input with a message naming
the fix, rather than letting it reach `gtsummary` or `flextable`.

```{r, error = TRUE}
hv_man_table(
  gtsummary::tbl_summary(gtsummary::trial, by = "trt", include = "age"),
  style = "manuscript"
)
```

```{r, error = TRUE}
hv_tbl_summary(
  gtsummary::trial, groups = list(D = "age"),
  continuous = "age", binary = "age"
)
```