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⁻¹	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 × 10¹	coconut	three	15 mars 2015	15:45	2018-03-03 03:44	€1,39	grp_a
row_4	4,44 × 10²	durian	four	15 avril 2015	16:50	2018-04-04 15:55	€65 100,00	grp_a
row_5	5,55 × 10³		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 × 10⁵	grapefruit	seven		19:10	2018-07-07 05:22		grp_b
row_8	8,88 × 10⁶	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_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_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_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.
`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.