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.
Usage
gt(
data,
rowname_col = "rowname",
groupname_col = dplyr::group_vars(data),
process_md = FALSE,
caption = NULL,
rownames_to_stub = FALSE,
auto_align = TRUE,
id = NULL,
locale = 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 therownames_to_stub
option isTRUE
then any column name provided torowname_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 inputdata
table has thegrouped_df
class (through use of thedplyr::group_by()
function or associatedgroup_by*()
functions) then any input here is ignored.- process_md
Should the contents of the
rowname_col
andgroupname_col
be interpreted as Markdown? By default this isFALSE
.- caption
An optional table caption to use for cross-referencing in R Markdown, Quarto, or bookdown.
- 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 callscols_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 therandom_id()
function. A custom table ID can be used with any single-length character vector.- locale
An optional locale ID that can be set as the default locale for all functions that take a
locale
argument. Examples of valid locales include"en_US"
for English (United States) and"fr_FR"
for French (France). Refer to the information provided by theinfo_locales()
to determine which locales are supported.- row_group.sep
The separator to use between consecutive group names (a possibility when providing
data
as agrouped_df
with multiple groups) in the displayed stub row group label.
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.
Examples
Create a gt table object using the exibble
dataset. Use the row
and
group
columns to add a stub and row groups via the rowname_col
and
groupname_col
arguments.
The resulting gt table object can be used in transformations with a
variety of tab_*()
, fmt_*()
, cols_*()
, and even more functions
available in the package.
tab_1 %>%
tab_header(
title = "Table Title",
subtitle = "Subtitle"
) %>%
fmt_number(
columns = num,
decimals = 2
) %>%
cols_label(num = "number")
See also
Other table creation functions:
gt_preview()