# gtsummary + Quarto/R Markdown

The {gtsummary} package was written to be a companion to the {gt} package from RStudio. But not all output types are supported by the {gt} package. Therefore, we have made it possible to print {gtsummary} tables with various engines.

## Output Types

Here’s a summary of the various Quarto and R Markdown output types and the print engines that support them.

Print Engine | Function | HTML | PDF | RTF | Word
--- | --- | --- | --- | --- | ---
gt | `as_gt()` |  |  |  |
flextable | `as_flex_table()` |  |  |  |
huxtable | `as_hux_table()` |  |  |  |
kableExtra | `as_kable_extra()` |  |  |  |
kable | `as_kable()` |  |  |  |
tibble | `as_tibble()` |  |  |  |
| Output fully supported
| Missing indentation, footnotes, spanning headers
| No formatted output
| Output not supported
| Under development: missing indentation (RTF) or irregular headers (Word)

Any {gtsummary} table can be converted to one of the types in the table above. For example, the code below prints a {gtsummary} table as a {flextable} table, instead of the default {gt} table.

    tbl_summary(trial) %>%
      as_flex_table()

## Default Printer

Tables printed with {gtsummary} can be seamlessly integrated into R markdown documents. Currently, {gt} supports HTML output, with LaTeX and RTF planned for the future. The table below summarizes the default print engine utilized for {gtsummary} tables for various R Markdown output formats.

Output Type | Default Engine | Details
--- | --- | ---
HTML | {gt} | {gt} output is fully supported with HTML output.
PDF | kable | You may force printing with {gt} by converting a {gtsummary} object to {gt} with `as_gt()`, e.g. `tbl_summary(trial) %>% as_gt()`. PDF output is under development in the {gt} package. You may get a gorgeous table, but you may also get an error or a malformed table.
RTF | kable | You may force printing with {gt} by converting a {gtsummary} object to {gt} with `as_gt()`, e.g. `tbl_summary(trial) %>% as_gt()`. RTF output is under development in the {gt} package. You may get a gorgeous table, but you may also get an error or a malformed table.
Word | flextable | {flextable} is the default print engine for Word output, as {gt} does not support Word. If {flextable} is not installed, kable is used.

When a table is printed with `knitr::kable()` the resulting table is less full featured compared to a table printed with {gt}. For example, the table will not contain footnotes, spanning headers, or row indentation.

## Example R Markdown Report

An example R markdown report using {gtsummary} has been included with the package. To open the example file, run the following command in the R console.

    library(gtsummary)
    system.file(package = "gtsummary") %>%
      file.path("rmarkdown_example/gtsummary_rmarkdown_html.Rmd") %>%
      file.edit()

## LaTeX

To print {gtsummary} tables using LaTeX, utilize one of the supporting print engines.

    # build gtsummary table
    tbl <- tbl_summary(trial)

    # using the {gt} package
    as_gt(tbl) %>% gt::as_latex()

    # using the {huxtable} package
    as_hux_table(tbl) %>% huxtable::to_latex()

    # using the {kableExtra} package
    as_kable_extra(tbl, format = "latex")

    # using the knitr::kable function
    as_kable(tbl, format = "latex")

## Images

Use the {gt} package’s `gt::gtsave()` function to save images of {gtsummary} tables.

    tbl_summary(trial) %>% # build gtsummary table
      as_gt() %>% # convert to gt table
      gt::gtsave( # save table as image
        filename = "my_table_image.png"
      )

## Tips

When printing {gt} or {gtsummary} tables in a loop, use `print()` and `results = 'asis'` in the R markdown chunk.

    ```{r loop_print, results = 'asis'}
    for (i in 1) {
      tbl <- tbl_summary(trial)   # build gtsummary table
      print(tbl)                  # print table
    }
    ```

If `print(tbl)` does not work for you, try either `knitr::knit_print(tbl)` or `cat(knitr::knit_print(tbl))`.

Icons from icons8