GT

GT(
    self,
    data,
    rowname_col=None,
    groupname_col=None,
    auto_align=True,
    id=None,
    locale=None,
)

Create a Great Tables object.

The GT() class creates the GT object when provided with tabular data. Using this class is the the first step in a typical Great Tables workflow. Once we have this object, we can take advantage of numerous methods to get the desired display table for publication.

There are a few table structuring options we can consider at this stage. We can choose to create a table stub containing row labels through the use of the rowname_col= argument. Further to this, row groups can be created with the groupname_col= argument. Both arguments take the name of a column in the input table data. Typically, the data in the groupname_col= column will consist of categorical text whereas the data in the rowname_col= column will often contain unique labels (perhaps being unique across the entire table or unique only within the different row groups).

Parameters

data : Any

A DataFrame object.

rowname_col : str | None = None

The column name in the input data= table to use as row labels to be placed in the table stub.

groupname_col : str | None = None

The column name in the input data= table to use as group labels for generation of row groups.

auto_align : bool = True

Optionally have column data be aligned depending on the content contained in each column of the input data=.

id : str | None = None

By default (with None) the table ID will be a random, ten-letter string as generated through internal use of the random_id() function. A custom table ID can be used here by providing a string.

locale : str | None = None

An optional locale identifier that can be set as the default locale for all functions that take a locale argument. Examples include "en" for English (United States) and "fr" for French (France).

Returns

: GT

A GT object is returned.

Examples

Let’s use the exibble dataset for the next few examples, we’ll learn how to make simple output tables with the GT() class. The most basic thing to do is to just use GT() with the dataset as the input.

from great_tables import GT, exibble

GT(exibble)
num char fctr date time datetime currency row group
0.1111 apricot one 2015-01-15 13:35 2018-01-01 02:22 49.95 row_1 grp_a
2.222 banana two 2015-02-15 14:40 2018-02-02 14:33 17.95 row_2 grp_a
33.33 coconut three 2015-03-15 15:45 2018-03-03 03:44 1.39 row_3 grp_a
444.4 durian four 2015-04-15 16:50 2018-04-04 15:55 65100.0 row_4 grp_a
5550.0 five 2015-05-15 17:55 2018-05-05 04:00 1325.81 row_5 grp_b
fig six 2015-06-15 2018-06-06 16:11 13.255 row_6 grp_b
777000.0 grapefruit seven 19:10 2018-07-07 05:22 row_7 grp_b
8880000.0 honeydew eight 2015-08-15 20:20 0.44 row_8 grp_b

This dataset has the row and group columns. The former contains unique values that are ideal for labeling rows, and this often happens in what is called the ‘stub’ (a reserved area that serves to label rows). With the GT() class, we can immediately place the contents of the row column into the stub column. To do this, we use the rowname_col= argument with the appropriate column name.

from great_tables import GT, exibble

GT(exibble, rowname_col="row")
num char fctr date time datetime currency group
row_1 0.1111 apricot one 2015-01-15 13:35 2018-01-01 02:22 49.95 grp_a
row_2 2.222 banana two 2015-02-15 14:40 2018-02-02 14:33 17.95 grp_a
row_3 33.33 coconut three 2015-03-15 15:45 2018-03-03 03:44 1.39 grp_a
row_4 444.4 durian four 2015-04-15 16:50 2018-04-04 15:55 65100.0 grp_a
row_5 5550.0 five 2015-05-15 17:55 2018-05-05 04:00 1325.81 grp_b
row_6 fig six 2015-06-15 2018-06-06 16:11 13.255 grp_b
row_7 777000.0 grapefruit seven 19:10 2018-07-07 05:22 grp_b
row_8 8880000.0 honeydew eight 2015-08-15 20:20 0.44 grp_b

This sets up a table with a stub, the row labels are placed within the stub column, and a vertical dividing line has been placed on the right-hand side.

The group column contains categorical values that are ideal for grouping rows. We can use the groupname_col= argument to place these values into row groups.

from great_tables import GT, exibble

GT(exibble, rowname_col="row", groupname_col="group")
num char fctr date time datetime currency
grp_a
row_1 0.1111 apricot one 2015-01-15 13:35 2018-01-01 02:22 49.95
row_2 2.222 banana two 2015-02-15 14:40 2018-02-02 14:33 17.95
row_3 33.33 coconut three 2015-03-15 15:45 2018-03-03 03:44 1.39
row_4 444.4 durian four 2015-04-15 16:50 2018-04-04 15:55 65100.0
grp_b
row_5 5550.0 five 2015-05-15 17:55 2018-05-05 04:00 1325.81
row_6 fig six 2015-06-15 2018-06-06 16:11 13.255
row_7 777000.0 grapefruit seven 19:10 2018-07-07 05:22
row_8 8880000.0 honeydew eight 2015-08-15 20:20 0.44

By default, values in the body of a table (and their column labels) are automatically aligned. The alignment is governed by the types of values in a column. If you’d like to disable this form of auto-alignment, the auto_align=False option can be taken.

from great_tables import GT, exibble

GT(exibble, rowname_col="row", auto_align=False)
num char fctr date time datetime currency group
row_1 0.1111 apricot one 2015-01-15 13:35 2018-01-01 02:22 49.95 grp_a
row_2 2.222 banana two 2015-02-15 14:40 2018-02-02 14:33 17.95 grp_a
row_3 33.33 coconut three 2015-03-15 15:45 2018-03-03 03:44 1.39 grp_a
row_4 444.4 durian four 2015-04-15 16:50 2018-04-04 15:55 65100.0 grp_a
row_5 5550.0 five 2015-05-15 17:55 2018-05-05 04:00 1325.81 grp_b
row_6 fig six 2015-06-15 2018-06-06 16:11 13.255 grp_b
row_7 777000.0 grapefruit seven 19:10 2018-07-07 05:22 grp_b
row_8 8880000.0 honeydew eight 2015-08-15 20:20 0.44 grp_b

What you’ll get from that is center-alignment of all table body values and all column labels. Note that row labels in the the stub are still left-aligned; and auto_align= has no effect on alignment within the table stub.

However which way you generate the initial table object, you can modify it with a huge variety of methods to further customize the presentation. Formatting body cells is commonly done with the family of formatting methods (e.g., fmt_number(), fmt_date(), etc.). The package supports formatting with internationalization (‘i18n’ features) and so locale-aware methods all come with a locale= argument. To avoid having to use that argument repeatedly, the GT() class has its own locale= argument. Setting a locale in that will make it available globally. Here’s an example of how that works in practice when setting locale = "fr" in GT() prior to using formatting methods:

from great_tables import GT, exibble

(
    GT(exibble, rowname_col="row", locale="fr")
    .fmt_currency(columns="currency")
    .fmt_scientific(columns="num")
    .fmt_date(columns="date", date_style="day_month_year")
)
num char fctr date time datetime currency group
row_1 1,11 × 10−1 apricot one 15 janvier 2015 13:35 2018-01-01 02:22 €49,95 grp_a
row_2 2,22 banana two 15 février 2015 14:40 2018-02-02 14:33 €17,95 grp_a
row_3 3,33 × 101 coconut three 15 mars 2015 15:45 2018-03-03 03:44 €1,39 grp_a
row_4 4,44 × 102 durian four 15 avril 2015 16:50 2018-04-04 15:55 €65 100,00 grp_a
row_5 5,55 × 103 five 15 mai 2015 17:55 2018-05-05 04:00 €1 325,81 grp_b
row_6 fig six 15 juin 2015 2018-06-06 16:11 €13,26 grp_b
row_7 7,77 × 105 grapefruit seven 19:10 2018-07-07 05:22 grp_b
row_8 8,88 × 106 honeydew eight 15 août 2015 20:20 €0,44 grp_b

In this example, the fmt_currency(), fmt_scientific(), and fmt_date() methods understand that the locale for this table is "fr" (French), so the appropriate formatting for that locale is apparent in the currency, num, and date columns.

Methods

Name Description
as_latex Output a GT object as LaTeX
as_raw_html Get the HTML content of a GT object.
cols_align Set the alignment of one or more columns.
cols_hide Hide one or more columns.
cols_label Relabel one or more columns.
cols_move Move one or more columns.
cols_move_to_end Move one or more columns to the end.
cols_move_to_start Move one or more columns to the start.
cols_unhide Unhide one or more columns.
cols_width Set the widths of columns.
data_color Perform data cell colorization.
fmt Set a column format with a formatter function.
fmt_bytes Format values as bytes.
fmt_currency Format values as currencies.
fmt_date Format values as dates.
fmt_datetime Format values as datetimes.
fmt_flag Generate flag icons for countries from their country codes.
fmt_icon Use icons within a table’s body cells.
fmt_image Format image paths to generate images in cells.
fmt_integer Format values as integers.
fmt_markdown Format Markdown text.
fmt_nanoplot Format data for nanoplot visualizations.
fmt_number Format numeric values.
fmt_percent Format values as a percentage.
fmt_roman Format values as Roman numerals.
fmt_scientific Format values to scientific notation.
fmt_time Format values as times.
fmt_units Format measurement units.
opt_align_table_header Option to align the table header.
opt_all_caps Option to use all caps in select table locations.
opt_footnote_marks Option to modify the set of footnote marks
opt_horizontal_padding Option to scale the horizontal padding of the table.
opt_row_striping Option to add or remove row striping.
opt_stylize Stylize your table with a colorful look.
opt_table_font Options to define font choices for the entire table.
opt_table_outline Option to wrap an outline around the entire table.
opt_vertical_padding Option to scale the vertical padding of the table.
pipe Provide a structured way to chain a function for a GT object.
save Produce a high-resolution image file or PDF of the table.
show Display the table in a notebook or a web browser.
sub_missing Substitute missing values in the table body.
sub_zero Substitute zero values in the table body.
tab_header Add a table header.
tab_options Modify the table output options.
tab_source_note Add a source note citation.
tab_spanner Insert a spanner above a selection of column headings.
tab_stub Add a table stub, to emphasize row and group information.
tab_stubhead Add label text to the stubhead.
tab_style Add custom style to one or more cells
with_id Set the id for this table.
with_locale Set a column to be the default locale.
write_raw_html Write the table to an HTML file.