---
title: "summarizeByVisitSCI"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{summarizeByVisitSCI}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.height = 5,
  fig.width = 8,
  fig.align = "center"
)
```

`summarizeByVisitSCI()` is the counterpart of `summarizeSCI()` for data
collected over several visits. It produces the table of `summaryByVisit()` and
one plot per variable over the visits: a line plot (or boxplots) for continuous
variables and stacked barplots for categorical ones.

## Setup and data

```{r, message = FALSE}
library(summarySCI)
data(hemoglobin_data)

hb <- hemoglobin_data
hb$hb_cat <- cut(hb$hb, c(-Inf, 120, 140, Inf),
                 labels = c("< 120", "120-140", "> 140"))
```

## Table and plots

The arguments are those of `summaryByVisit()`. The visits appear in the order
of the table; with `order`, its values also set the spacing of the visits in
the line plot.

```{r, message = FALSE, warning = FALSE}
res <- summarizeByVisitSCI(hb, vars = c("hb", "hb_cat"), group = "Arm",
                           visit = "visit", order = "visit_nr",
                           stat_cont = "median_IQR",
                           labels = list(hb_cat = "Hemoglobin category"),
                           plot_args = list(risk_table = TRUE,
                                            group_names_short = c("A", "B")))
res$table
```

```{r}
res$plots$hb
res$plots$hb_cat
```

As in `summarizeSCI()`, `type = "table"` or `"plot"` returns only one of them,
the table's settings (labels, `missing`, `missing_percent`, `stat_cat`) carry
over to the plots, and further plot options go into `plot_args`
(see `?lineplotSCI`, `?boxplotSCI` and `?stackedbarplotSCI`).

## The plots show the numbers of the table

The line plots and stacked bars are drawn from the numbers printed in the
table, as `plotByVisit()` does: they show exactly what the table shows, with
its rounding, its visits and its N columns as the risk table. `stat_cont`
decides what the line plot shows:

| `stat_cont`      | Point             | Error bars                 |
|------------------|-------------------|----------------------------|
| `"median_range"` | median            | minimum to maximum         |
| `"median_IQR"`   | median            | first to third quartile    |
| `"mean_sd"`      | mean              | +/- one standard deviation |
| `"mean_se"`      | mean              | +/- one standard error     |
| `"geomMean_sd"`  | geometric mean    | ÷ and × geometric SD    |

The geometric mean needs positive values: the table shows `NA` for visits with
values of zero or below, and the line plot leaves those points out.
`plot_args = list(stat_footnote = TRUE)` names the statistic in a footnote
under each plot.

`plot_cont = "boxplot"` draws boxplots per visit instead of the line plot.
A boxplot shows more than the table holds, so it is drawn from the data: from
the rows the table summarizes, with the box at the quartiles as the table
computes them. It always shows the median and quartiles, whatever `stat_cont`
the table uses; with `"median_IQR"` the two agree.

```{r, message = FALSE, warning = FALSE}
res_box <- summarizeByVisitSCI(hb, vars = "hb", group = "Arm",
                               visit = "visit", order = "visit_nr",
                               stat_cont = "mean_sd", plot_cont = "boxplot",
                               plot_args = list(cex_axis = 0.8))
res_box$plots$hb
```

## Saving the table and plots

`word_output = TRUE` (with `file_path`) and `save_plots()` work as described
in `vignette("summarizeSCI")`:

```{r}
basename(save_plots(res, file_name = "visit", file_path = tempdir(),
                    width = 9, height = 5.5))
```