Create a gt table object

The gt() function creates a gt table object when provided with table data. Using this function is the first step in a typical gt workflow. Once we have the gt table object, we can perform styling transformations before rendering to a display table of various formats.

gt(
  data,
  rowname_col = "rowname",
  groupname_col = dplyr::group_vars(data),
  caption = NULL,
  rownames_to_stub = FALSE,
  auto_align = TRUE,
  id = NULL,
  row_group.sep = getOption("gt.row_group.sep", " - ")
)

Arguments

data	A `data.frame` object or a tibble.
rowname_col	The column name in the input `data` table to use as row captions to be placed in the display table stub. If the `rownames_to_stub` option is `TRUE` then any column name provided to `rowname_col` will be ignored.
groupname_col	The column name in the input `data` table to use as group labels for generation of stub row groups. If the input `data` table has the `grouped_df` class (through use of the `dplyr::group_by()` function or associated `group_by*()` functions) then any input here is ignored.
caption	An optional table caption to use for cross-referencing in R Markdown documents and bookdown book projects.
rownames_to_stub	An option to take rownames from the input `data` table as row captions in the display table stub.
auto_align	Optionally have column data be aligned depending on the content contained in each column of the input `data`. Internally, this calls `cols_align(align = "auto")` for all columns.
id	The table ID. By default, with `NULL`, this will be a random, ten-letter ID as generated by using the `random_id()` function. A custom table ID can be used with any single-length character vector.
row_group.sep	The separator to use between consecutive group names (a possibility when providing `data` as a `grouped_df` with multiple groups) in the displayed stub row group label.

Value

An object of class gt_tbl.

Details

There are a few data ingest options we can consider at this stage. We can choose to create a table stub with rowname captions using the rowname_col argument. Further to this, stub row groups can be created with the groupname_col. Both arguments take the name of a column in the input table data. Typically, the data in the groupname_col will consist of categories of data in a table and the data in the rowname_col are unique labels (perhaps unique across the entire table or unique within groups).

Row groups can also be created by passing a grouped_df to gt() by using the dplyr::group_by() function on the table data. In this way, two or more columns of categorical data can be used to make row groups. The row_group.sep argument allows for control in how the row group label will appear in the display table.

Figures

Function ID

1-1

Examples

# Create a table object using the
# `exibble` dataset; use the `row`
# and `group` columns to add a stub
# and row groups
tab_1 <-
  exibble %>%
  gt(
    rowname_col = "row",
    groupname_col = "group"
  )

# The resulting object can be used
# in transformations (with `tab_*()`,
# `fmt_*()`, `cols_*()` functions)
tab_2 <-
  tab_1 %>%
  tab_header(
    title = "Table Title",
    subtitle = "Subtitle"
  ) %>%
  fmt_number(
    columns = num,
    decimals = 2
  ) %>%
  cols_label(num = "number")