API 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).
| GT | Create a Great Tables object. |
Creating or modifying parts of a table
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_stub | Add a table stub, to emphasize row and group information. |
| GT.tab_stubhead | Add label text to the stubhead. |
| 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.
| GT.fmt_number | Format numeric values. |
| GT.fmt_integer | Format values as integers. |
| GT.fmt_percent | Format values as a percentage. |
| GT.fmt_scientific | Format values to scientific notation. |
| GT.fmt_currency | Format values as currencies. |
| GT.fmt_bytes | Format values as bytes. |
| GT.fmt_roman | Format values as Roman numerals. |
| GT.fmt_date | Format values as dates. |
| GT.fmt_time | Format values as times. |
| GT.fmt_datetime | Format values as datetimes. |
| 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_icon | Use icons within a table’s body cells. |
| GT.fmt_flag | Generate flag icons for countries from their country codes. |
| GT.fmt_nanoplot | Format data for nanoplot visualizations. |
| GT.fmt | Set a column format with a formatter function. |
| GT.data_color | Perform data cell colorization. |
| GT.sub_missing | Substitute missing values in the table body. |
| GT.sub_zero | Substitute zero values in the table body. |
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_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_hide | Hide one or more columns. |
| GT.cols_unhide | Unhide one or more columns. |
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.stub | Target the table stub. |
| loc.row_groups | Target row groups. |
| 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 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_align_table_header | Option to align the table header. |
| GT.opt_row_striping | Option to add or remove row striping. |
| GT.opt_all_caps | Option to use all caps in select table locations. |
| 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_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_stylize | Stylize your table with a colorful look. |
Export
There may come a day when you need to export a table to some specific format. A great method for that is save(), which allows us to save the table as a standalone image file. You can also get the table code as an HTML fragment with the *_raw_html() methods.
| GT.save | Produce a high-resolution image file or PDF of the table. |
| 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_percent | Format values as a percentage. |
| vals.fmt_currency | Format values as currencies. |
| vals.fmt_roman | Format values as Roman numerals. |
| vals.fmt_bytes | Format values as bytes. |
| vals.fmt_date | Format values as dates. |
| vals.fmt_time | Format values as times. |
| 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 thoughout the help docs use these datasets to quickly demonstrate the awesome features of the package! Please note that using any of these datasets requires the Pandas library to be installed.
| 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. |