The gt()
function creates a gt table object when provided with tabledata. Using this function is the first step in a typical gt workflow.Once we have the gt table object, we can perform styling transformationsbefore 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, row_group_as_column = FALSE, auto_align = TRUE, id = NULL, locale = NULL, row_group.sep = getOption("gt.row_group.sep", " - "))
Arguments
- data
Input data table
obj:<data.frame>|obj:<tbl_df>
// requiredA
data.frame
object or a tibble (tbl_df
).- rowname_col
Column for row names/labels from
data
scalar<character>
// default:NULL
(optional
)The column name in the input
data
table to use as row labels to be placedin the table stub. If therownames_to_stub
option isTRUE
then anycolumn name provided torowname_col
will be ignored.- groupname_col
Column for group names/labels from
data
scalar<character>
// default:NULL
(optional
)The column name in the input
data
table to use as group labels forgeneration of row groups. If the inputdata
table has thegrouped_df
class (through use ofdplyr::group_by()
or associatedgroup_by*()
functions) then any input here is ignored.- process_md
Process Markdown in
rowname_col
andgroupname_col
scalar<logical>
// default:FALSE
Should the contents of the
rowname_col
andgroupname_col
be interpretedas Markdown? By default this won't happen.- caption
Table caption text
scalar<character>
// default:NULL
(optional
)An optional table caption to use for cross-referencing in R Markdown,Quarto, or bookdown.
- rownames_to_stub
Use data frame row labels in the stub
scalar<logical>
// default:FALSE
An option to take rownames from the input
data
table (should they beavailable) as row labels in the display table stub.- row_group_as_column
Mode for displaying row group labels in the stub
scalar<logical>
// default:FALSE
An option that alters the display of row group labels. By default this is
FALSE
and row group labels will appear in dedicated rows above theirrespective groups of rows. IfTRUE
row group labels will occupy asecondary column in the table stub.- auto_align
Automatic alignment of column values and labels
scalar<logical>
// default:TRUE
Optionally have column data be aligned depending on the content containedin each column of the input
data
. Internally, this callscols_align(align = "auto")
for all columns.- id
The table ID
scalar<character>
// default:NULL
(optional
)By default (with
NULL
) this will be a random, ten-letter ID as generatedby usingrandom_id()
. A custom table ID can be used here byproviding a character value.- locale
Locale identifier
scalar<character>
// default:NULL
(optional
)An optional locale identifier that can be set as the default locale for allfunctions that take a
locale
argument. Examples include"en"
forEnglish (United States) and"fr"
for French (France). We can callinfo_locales()
as a useful reference for all of the locales that are supported.- row_group.sep
Separator text for multiple row group labels
scalar<character>
// default:getOption("gt.row_group.sep", " - ")
The separator to use between consecutive group names (a possibility whenproviding
data
as agrouped_df
with multiple groups) in the displayedrow group label.
Value
An object of class gt_tbl
.
Details
There are a few data ingest options we can consider at this stage. We canchoose to create a table stub containing row labels through the use of therowname_col
argument. Further to this, stub row groups can be created withthe groupname_col
argument. Both arguments take the name of a column in theinput table data. Typically, the data in the groupname_col
column willconsist of categorical text whereas the data in the rowname_col
column willcontain unique labels (could be unique across the entire table or uniquewithin the different row groups).
Row groups can also be created by passing a grouped_df
to gt()
by usingdplyr::group_by()
on the table data. In this way, two or morecolumns of categorical data can be used to make row groups. Therow_group.sep
argument allows for control in how the row group labels willappear in the display table.
Examples
Let's use the exibble
dataset for the next few examples, we'll learn howto make simple gt tables with the gt()
function. The most basic thingto do is to just use gt()
with the dataset as the input.
exibble |> gt()
This dataset has the row
and group
columns. The former contains uniquevalues that are ideal for labeling rows, and this often happens in what iscalled the 'stub' (a reserved area that serves to label rows). With thegt()
function, we can immediately place the contents of the row
columninto the stub column. To do this, we use the rowname_col
argument with thename of the column to use in quotes.
exibble |> gt(rowname_col = "row")
This sets up a table with a stub, the row labels are placed within the stubcolumn, and a vertical dividing line has been placed on the right-hand side.
The group
column can be used to divide the rows into discrete groups.Within that column, we see repetitions of the values grp_a
and grp_b
.These serve both as ID values and the initial label for the groups. With thegroupname_col
argument in gt()
, we can set up the row groups immediatelyupon creation of the table.
exibble |> gt( rowname_col = "row", groupname_col = "group" )
If you'd rather perform the set up of row groups later (i.e., not in thegt()
call), this is possible with tab_row_group()
(and row_group_order()
can help with the arrangement of row groups).
One more thing to consider with row groups is their layout. By default, rowgroup labels reside in separate rows the appear above the group. However,we can use row_group_as_column = TRUE
to put the row group labels within asecondary column within the table stub.
exibble |> gt( rowname_col = "row", groupname_col = "group", row_group_as_column = TRUE )
This could be done later if need be, and usingtab_options(row_group.as_column = TRUE)
would be the way to do it outsideof the gt()
call.
Some datasets have rownames built in; mtcars
famously has the car modelnames as the rownames. To use those rownames as row labels in the stub, therownames_to_stub = TRUE
option will prove to be useful.
head(mtcars, 10) |> gt(rownames_to_stub = TRUE)
By default, values in the body of a gt table (and their column labels)are automatically aligned. The alignment is governed by the types of valuesin a column. If you'd like to disable this form of auto-alignment, theauto_align = FALSE
option can be taken.
exibble |> gt(rowname_col = "row", auto_align = FALSE)
What you'll get from that is center-alignment of all table body values andall column labels. Note that row labels in the stub are stillleft-aligned; and auto_align
has no effect on alignment within the tablestub.
However which way you generate the initial gt table object, you can useit with a huge variety of functions in the package to further customize thepresentation. Formatting body cells is commonly done with the family offormatting functions (e.g., fmt_number()
, fmt_date()
, etc.). The packagesupports formatting with internationalization ('i18n' features) and solocale-aware functions come with a locale
argument. To avoid having to usethat argument repeatedly, the gt()
function has its own locale
argument.Setting a locale in that will make it available globally. Here's an exampleof how that works in practice when setting locale = "fr"
in gt()
andusing formatting functions:
exibble |> gt( rowname_col = "row", groupname_col = "group", locale = "fr" ) |> fmt_number() |> fmt_date( columns = date, date_style = "yMEd" ) |> fmt_datetime( columns = datetime, format = "EEEE, MMMM d, y", locale = "en" )
In this example, fmt_number()
and fmt_date()
understand that the localefor this table is "fr"
(French), so the appropriate formatting for thatlocale is apparent in the num
, currency
, and date
columns. However infmt_datetime()
, we explicitly use the "en"
(English) locale. Thisoverrides the "fr"
default set for this table and the end result isdates formatted with the English locale in the datetime
column.
Function ID
1-1
Function Introduced
v0.2.0.5
(March 31, 2020)
See also
Other table creation functions:gt_preview()