Reference

Table Creation

All tables created in Great Tables begin by using GT(). With this class, we supply the input data table and some basic options for creating a stub and row groups (with the rowname_col= and groupname_col= arguments). All GT methods are documented on their own pages.

GT: Create a Great Tables object.

Major structural table parts

A table can contain a few useful components for conveying additional information. These include a header (with a titles and subtitle), a footer (with source notes), and additional areas for labels (row group labels, column spanner labels, the stubhead label). We can perform styling on targeted table locations with the tab_style() method.

GT.tab_header(): Add a table header.
GT.tab_spanner(): Insert a spanner above a selection of column headings.
GT.tab_spanner_delim(): Insert spanners by splitting column names with a delimiter.
GT.tab_stub(): Add a table stub, to emphasize row and group information.
GT.tab_stubhead(): Add label text to the stubhead.
GT.tab_footnote(): Add a table footnote.
GT.tab_source_note(): Add a source note citation.
GT.tab_style(): Add custom style to one or more cells
GT.tab_options(): Modify the table output options.

Formatting column data

Columns of data can be formatted with the fmt_*() methods. We can specify the rows of these columns quite precisely with the rows argument. We get to apply these methods exactly once to each data cell (last call wins). Need to do custom formatting? Use the fmt() method and define your own formatter. The sub_*() methods allow you to perform substitution operations and data_color() provides a lot of power for colorizing body cells based on their data values.

GT.fmt_number(): Format numeric values.
GT.fmt_integer(): Format values as integers.
GT.fmt_scientific(): Format values to scientific notation.
GT.fmt_engineering(): Format values to engineering notation.
GT.fmt_percent(): Format values as a percentage.
GT.fmt_partsper(): Format values as parts-per quantities.
GT.fmt_currency(): Format values as currencies.
GT.fmt_roman(): Format values as Roman numerals.
GT.fmt_bytes(): Format values as bytes.
GT.fmt_date(): Format values as dates.
GT.fmt_time(): Format values as times.
GT.fmt_datetime(): Format values as datetimes.
GT.fmt_duration(): Format numeric or duration values as styled time duration strings.
GT.fmt_tf(): Format True and False values
GT.fmt_markdown(): Format Markdown text.
GT.fmt_units(): Format measurement units.
GT.fmt_image(): Format image paths to generate images in cells.
GT.fmt_flag(): Generate flag icons for countries from their country codes.
GT.fmt_icon(): Use icons within a table’s body cells.
GT.fmt_nanoplot(): Format data for nanoplot visualizations.
GT.fmt(): Set a column format with a formatter function.
GT.sub_missing(): Substitute missing values in the table body.
GT.sub_zero(): Substitute zero values in the table body.
GT.sub_small_vals(): Substitute small values in the table body.
GT.sub_large_vals(): Substitute large values in the table body.
GT.sub_values(): Substitute targeted values in the table body.
GT.data_color(): Perform data cell colorization.

Text transformation

The text_*() method take cell data that are solidified into strings and allow for flexible transformations of those string values. Whereas the fmt_*() and sub_*() methods are phases 1 and 2 of cell data metamorphoses, the text transformation functions are the final phase, acting on strings generated by formatting and substitution functions with no reference to the source values.

GT.text_replace(): Perform targeted text replacement with a regex pattern.
GT.text_case_when(): Perform text replacements using a case-when approach.
GT.text_case_match(): Perform text replacements with a switch-like approach.
GT.text_transform(): Apply a custom text transformation to cells at specified locations.

Modifying columns

The cols_*() methods allow for modifications that act on entire columns. This includes alignment of the data in columns (cols_align()), hiding columns from view (cols_hide()), re-labeling the column labels (cols_label()), and moving columns around (with the cols_move*() methods).

GT.cols_align(): Set the alignment of one or more columns.
GT.cols_width(): Set the widths of columns.
GT.cols_label(): Relabel one or more columns.
GT.cols_label_with(): Relabel one or more columns using a function.
GT.cols_label_rotate(): Rotate the column label for one or more columns.
GT.cols_move(): Move one or more columns.
GT.cols_move_to_start(): Move one or more columns to the start.
GT.cols_move_to_end(): Move one or more columns to the end.
GT.cols_reorder(): Reorder all columns in a specified order.
GT.cols_hide(): Hide one or more columns.
GT.cols_unhide(): Unhide one or more columns.
GT.cols_merge(): Merge data from two or more columns into a single column.
GT.cols_merge_uncert(): Merge columns to a value-with-uncertainty column.
GT.cols_merge_range(): Merge two columns to a value range column.
GT.cols_merge_n_pct(): Merge two columns to combine counts and percentages.

Adding rows

The summary_rows() function adds rows to summarize data within each row group, while grand_summary_rows() summarizes across the entire table.

GT.summary_rows(): Add group-wise summary rows to the table.
GT.grand_summary_rows(): Add grand summary rows to the table.

Location Targeting and Styling Classes

Location targeting is a powerful feature of Great Tables. It allows for the precise selection of table locations for styling (using the tab_style() method). The styling classes allow for the specification of the styling properties to be applied to the targeted locations.

loc.header: Target the table header (title and subtitle).
loc.title: Target the table title.
loc.subtitle: Target the table subtitle.
loc.stubhead: Target the stubhead.
loc.column_header: Target column spanners and column labels.
loc.spanner_labels: Target spanner labels.
loc.column_labels: Target column labels.
loc.grand_summary_stub: Target the grand summary stub.
loc.stub: Target the table stub.
loc.row_groups: Target row groups.
loc.grand_summary: Target the data cells in grand summary rows.
loc.body: Target data cells in the table body.
loc.footer: Target the table footer.
loc.source_notes: Target the source notes.
style.fill: A style specification for the background fill of targeted cells.
style.text: A style specification for cell text.
style.borders: A style specification for cell borders.
style.css: A style specification for custom CSS rules.

Helper Functions

An assortment of helper functions is available in the Great Tables package. The md() and html() helper functions can be used during label creation with the tab_header(), tab_spanner(), tab_stubhead(), and tab_source_note() methods.

GT.with_id(): Set the id for this table.
GT.with_locale(): Set a column to be the default locale.
md(): Interpret input text as Markdown-formatted text.
html(): Interpret input text as HTML-formatted text.
from_column: Specify that a style value should be fetched from a column in the data.
google_font(): Specify a font from the Google Fonts service.
system_fonts(): Get a themed font stack that works well across systems.
define_units(): With define_units() you can work with a specially-crafted units notation string and emit the
nanoplot_options(): Helper for setting the options for a nanoplot.

Table options

With the opt_*() functions, we have an easy way to set commonly-used table options without having to use tab_options() directly.

GT.opt_stylize(): Stylize your table with a colorful look.
GT.opt_footnote_marks(): Option to modify the set of footnote marks.
GT.opt_row_striping(): Option to add or remove row striping.
GT.opt_align_table_header(): Option to align the table header.
GT.opt_vertical_padding(): Option to scale the vertical padding of the table.
GT.opt_horizontal_padding(): Option to scale the horizontal padding of the table.
GT.opt_all_caps(): Option to use all caps in select table locations.
GT.opt_table_outline(): Option to wrap an outline around the entire table.
GT.opt_table_font(): Options to define font choices for the entire table.
GT.opt_css(): Option to add custom CSS for the table.

Export

There may come a day when you need to export a table to some specific format. A great method for that is gtsave(), which allows us to save the table as a standalone image file or PDF. You can also get the table code as an HTML fragment with the *_raw_html() methods.

GT.gtsave(): Save a GT table to a file (PNG, JPEG, WebP, or PDF).
GT.show(): Display the table in a notebook or a web browser.
GT.as_raw_html(): Get the HTML content of a GT object.
GT.write_raw_html(): Write the table to an HTML file.
GT.as_latex(): Output a GT object as LaTeX

Pipeline

Sometimes, you might want to programmatically manipulate the table while still benefiting from the chained API that Great Tables offers. pipe() is designed to tackle this issue.

GT.pipe(): Provide a structured way to chain a function for a GT object.

Value Formatting Functions

If you have single values (or lists of them) in need of formatting, we have a set of val_fmt_*() functions that have been adapted from the corresponding fmt_*() methods.

vals.fmt_number(): Format numeric values.
vals.fmt_integer(): Format values as integers.
vals.fmt_scientific(): Format values to scientific notation.
vals.fmt_engineering(): Format values to engineering notation.
vals.fmt_percent(): Format values as a percentage.
vals.fmt_partsper(): Format values as parts-per quantities.
vals.fmt_currency(): Format values as currencies.
vals.fmt_roman(): Format values as Roman numerals.
vals.fmt_bytes(): Format values as bytes.
vals.fmt_duration(): Format values as time duration strings.
vals.fmt_date(): Format values as dates.
vals.fmt_time(): Format values as times.
vals.fmt_duration(): Format values as time duration strings.
vals.fmt_markdown(): Format Markdown text.
vals.fmt_image(): Format image paths to generate images in cells.

Built-in Datasets

The Great Tables package is equipped with sixteen datasets that come in all shapes and sizes. Many examples throughout the help docs use these datasets to quickly demonstrate the features of the package.

data.countrypops: Yearly populations of countries from 1960 to 2022.
data.sza: Twice hourly solar zenith angles by month & latitude.
data.gtcars: Deluxe automobiles from the 2014-2017 period.
data.sp500: Daily S&P 500 Index data from 1950 to 2015.
data.pizzaplace: A year of pizza sales from a pizza place.
data.exibble: A toy example table for testing with great_tables: exibble.
data.towny: Populations of all municipalities in Ontario from 1996 to 2021.
data.peeps: A table of personal information for people all over the world.
data.films: Feature films in competition at the Cannes Film Festival.
data.metro: The stations of the Paris Metro.
data.gibraltar: Weather conditions in Gibraltar, May 2023.
data.constants: The fundamental physical constants.
data.illness: Lab tests for one suffering from an illness.
data.reactions: Reaction rates for gas-phase atmospheric reactions of organic compounds.
data.photolysis: Data on photolysis rates for gas-phase organic compounds.
data.nuclides: Nuclide data.