Printing (HTML)"

In surveytable: Streamlining Complex Survey Estimation and Reliability Assessment in R

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

Basic printing

If a tabulation function is called from the top level, it should print out its table(s) on its own.

As usual, first, let's start up the package and pick a survey to analyze:

library(surveytable)
set_survey(namcs2019sv)

Now, when a tabulation function is called from the top level, it prints. You don't need to do anything extra.

tab("AGER")

If a tabulation function is called not from the top level, such as from within a loop or another function, you do need to call print() explicitly for it to print. For example:

for (vr in c("AGER", "SEX")) {
  print( tab_subset(vr, "MAJOR", "Preventive care") )
}

Create HTML or PDF tables

Using a Quarto document, you can create tables in many different formats, such as HTML or PDF. Here is a straightforward example of what a Quarto document might look like:

---
title: "My tables"
author: "Me"
format: html
---

# Welcome 

As usual, first, let's start up the package and pick a survey to analyze:

```r
library(surveytable)
set_survey(namcs2019sv)
```

# Tables

Take a look at this table:

```r
tab("AGER")
```

Note the format setting, which specifies that this document will create HTML tables. Also note that you do have to add the results='asis' argument to the code chunks that print tables.

Print using various table-making packages

Use the output argument of set_opts() to select a table-making package. By default (output = "auto"), surveytable automatically selects a package depending on whether the output is to the screen (huxtable), HTML (gt), or PDF (kableExtra). You can also explicitly select one of these packages.

Changing the table-making package has a couple of uses:

• It allows you to generate tables in the way that you prefer.
• It allows you to print those tables to a variety of destinations, including the screen, HTML files, or PDF files.

huxtable

set_opts(output = "huxtable")

This is what printing to the screen looks like.

tab("AGER")

print(tab("AGER"), destination = "")

To create HTML tables from an R Markdown notebook or a Quarto document, add the results='asis' argument to the code chunk, like so:

```r
tab("AGER")
```

tab("AGER")

gt

set_opts(output = "gt")

With gt, printing to the screen and to HTML look the same. Here is what printing to the screen looks like:

tab("AGER")

print(tab("AGER"), destination = "")

Here is HTML:

```r
tab("AGER")
```

tab("AGER")

kableExtra

set_opts(output = "kableExtra")

We have not implemented screen printing with kableExtra yet. Try one of the other packages.

Here is HTML:

```r
tab("AGER")
```

tab("AGER")

auto

auto is the default option. It automatically selects one of the above packages depending on whether the output is to the screen (huxtable), HTML (gt), or PDF (kableExtra).

set_opts(output = "auto")

Screen output (this should use huxtable):

tab("AGER")

print(tab("AGER"), destination = "")

HTML output (this should use gt):

```r
tab("AGER")
```

tab("AGER")

Generate unformatted output

Some analysts might wish to compare the output from surveytable to the output from other statistical software, such as SAS / SUDAAN. In this situation, set_opts(output = "raw") might be useful. This command tells surveytable to print unformatted and unrounded tables.

set_opts(output = "raw")

tab("AGER")

print(tab("AGER"), destination = "")

set_opts(output = "auto")

Save the tables

Save tables and charts to an Excel workbook

Before using Excel printing, please be sure to install these packages: openxlsx2 and mschart.

To save tables and charts to an Excel file, turn on Excel printing with set_opts( output = "Excel", file = "my_workbook" ). Set the file argument to the name of an Excel file.

set_opts(output = "excel", file = "my_workbook")

set_opts(output = "excel", file = "my_workbook", .file_temp = TRUE)

Generate some tables:

total()
tab("AGER")

To turn off Excel printing, set the output argument to a value other than "Excel", such as "auto":

set_opts(output = "auto")

Save to a CSV file

To save tables to a CSV file, turn on CSV printing with set_opts( output = "CSV", file = "my_output" ). Set the file argument to the name of a CSV file.

set_opts(output = "csv", file = "my_output")

set_opts(output = "csv", file = "my_output", .file_temp = TRUE)

Generate some tables:

total()
tab("AGER")

To turn off CSV printing, set the output argument to a value other than "CSV", such as "auto":

set_opts(output = "auto")

Save to an R data file

Use the built-in saveRDS() function to save a table to an R data file:

tab("AGER") |> saveRDS("myfile.rds")

You can later load this data file back into R. To print the table, just load the file, like so:

readRDS("myfile.rds")

tab("AGER")

Advanced printing

The proper approach

Advanced users can add functionality to use any table-making package that they want. For more information, see help("surveytable-options").

The "quick-and-dirty" approach

The tabulation functions return either:

• for a single table, which is basically a data frame, with certain attributes set; or
• for more than one table, a list of such tables.

You can convert a single table to a data.frame with as.data.frame(), like so:

tab("AGER") |> as.data.frame()

Note that this produces a data.frame with unique column names, which improves its usability.

Alternatively, you can pass this data.frame to your favorite table-making package. This example passes a table to gt. To ensure unique column names, pass the table through as.data.frame() first.

tab("AGER") |> as.data.frame() |> gt::gt()

The reason that this is the "quick-and-dirty" approach is that the output it creates is not as nice as conventional tables, described above. The output does not have table title (which has important information about the variable and the survey), table footer (which has important information about sample size and low-precision estimates), and it does not format the estimates. Nevertheless, there could be situations in which this approach is helpful, such as

• extracting an exact value from a table using as.data.frame(); or
• quickly using your favorite table-making package.

surveytable documentation built on Aug. 26, 2025, 1:07 a.m.