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
Name
Type
Description
Default
data
Any
A DataFrame object.
required
rowname_col
str | None
The column name in the input data= table to use as row labels to be placed in the table stub.
None
groupname_col
str | None
The column name in the input data= table to use as group labels for generation of row groups.
None
auto_align
bool
Optionally have column data be aligned depending on the content contained in each column of the input data=.
True
id
str | 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.
None
locale
str | 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).
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, exibbleGT(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, exibbleGT(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, exibbleGT(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, exibbleGT(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:
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.
The cols_align() method sets the alignment of one or more columns. The align argument can be set to one of "left", "center", or "right" and the columns argument can be used to specify which columns to apply the alignment to. If columns is not specified, the alignment is applied to all columns.
Parameters
Name
Type
Description
Default
align
str
The alignment to apply. Must be one of "left", "center", or "right".
'left'
columns
SelectExpr
The columns to target. Can either be a single column name or a series of column names provided in a list. If None, the alignment is applied to all columns.
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Examples
Let’s use the countrypops to create a small table. We can change the alignment of the population column with cols_align(). In this example, the column label and body cells of population will be aligned to the left.
The cols_hide() method allows us to hide one or more columns from appearing in the final output table. While it’s possible and often desirable to omit columns from the input table data before introduction to the GT() class, there can be cases where the data in certain columns is useful (as a column reference during formatting of other columns) but the final display of those columns is not necessary.
Parameters
Name
Type
Description
Default
columns
SelectExpr
The columns to hide in the output display table. Can either be a single column name or a series of column names provided in a list.
The hiding of columns is internally a rendering directive, so, all columns that are ‘hidden’ are still accessible and useful in any expression provided to a rows argument. Furthermore, the cols_hide() method (as with many of the methods available in Great Tables) can be placed anywhere in a chain of calls (acting as a promise to hide columns when the timing is right). However there’s perhaps greater readability when placing this call closer to the end of such a chain. The cols_hide() method quietly changes the visible state of a column and doesn’t yield warnings when changing the state of already-invisible columns.
cols_label
GT.cols_label(self, **kwargs)
Relabel one or more columns.
There are three important pieces to labelling:
Each argument has the form: {name in data} = {new label}.
Multiple columns may be given the same label.
Labels may use curly braces to apply special formatting, called unit notation. For example, “area ({{ft^2}})” would appear as “area (ft²)”.
We can also use unit notation to format the column labels. In this example, we’ll use {cm^3 molecules^-1 s^-1} for part of the label for the OH_k298 column.
On those occasions where you need to move columns this way or that way, we can make use of the cols_move() method. While it’s true that the movement of columns can be done upstream of Great Tables, it is much easier and less error prone to use the method provided here. The movement procedure here takes one or more specified columns (in the columns argument) and places them to the right of a different column (the after argument). The ordering of the columns to be moved is preserved, as is the ordering of all other columns in the table.
The columns supplied in columns must all exist in the table and none of them can be in the after argument. The after column must also exist and only one column should be provided here. If you need to place one more or columns at the beginning of the column series, the cols_move_to_start() method should be used. Similarly, if those columns to move should be placed at the end of the column series then use cols_move_to_end().
Parameters
Name
Type
Description
Default
columns
SelectExpr
The columns to target. Can either be a single column name or a series of column names provided in a list.
required
after
str
The column after which the columns should be placed. This can be any column name that exists in the table.
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Examples
Let’s use the countrypops dataset to create a table. We’ll choose to position the population column after the country_name column by using the cols_move() method.
We can easily move set of columns to the beginning of the column series and we only need to specify which columns. It’s possible to do this upstream of Great Tables, however, it is easier with this method and it presents less possibility for error. The ordering of the columns that are moved to the end is preserved (same with the ordering of all other columns in the table).
Parameters
Name
Type
Description
Default
columns
SelectExpr
The columns to target. Can either be a single column name or a series of column names provided in a list.
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Examples
For this example, we’ll use a portion of the countrypops dataset to create a simple table. Let’s move the year column, which is the middle column, to the end of the column series with the cols_move_to_end() method.
We can also move multiple columns at a time. With the same countrypops-based table (countrypops_mini), let’s move both the year and country_name columns to the end of the column series.
We can easily move set of columns to the beginning of the column series and we only need to specify which columns. It’s possible to do this upstream of Great Tables, however, it is easier with this method and it presents less possibility for error. The ordering of the columns that are moved to the start is preserved (same with the ordering of all other columns in the table).
The columns supplied in columns must all exist in the table. If you need to place one or columns at the end of the column series, the cols_move_to_end() method should be used. More control is offered with the cols_move() method, where columns could be placed after a specific column.
Parameters
Name
Type
Description
Default
columns
SelectExpr
The columns to target. Can either be a single column name or a series of column names provided in a list.
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Examples
For this example, we’ll use a portion of the countrypops dataset to create a simple table. Let’s move the year column, which is the middle column, to the start of the column series with the cols_move_to_start() method.
We can also move multiple columns at a time. With the same countrypops-based table (countrypops_mini), let’s move both the year and population columns to the start of the column series.
Manual specifications of column widths can be performed using the cols_width() method. We choose which columns get specific widths. This can be in units of pixels or as percentages. Width assignments are supplied inside of a dictionary where columns are the keys and the corresponding width is the value.
Parameters
Name
Type
Description
Default
cases
dict[str, str]
A dictionary where the keys are column names and the values are the widths. Widths can be specified in pixels (e.g., "50px") or as percentages (e.g., "20%").
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Examples
Let’s use select columns from the exibble dataset to create a new table. We can specify the widths of columns with cols_width(). This is done by specifying the exact widths for table columns in a dictionary. In this example, we’ll set the width of the num column to "150px", the char column to "100px", the date column to "300px". All other columns won’t be affected (their widths will be automatically set by their content).
We can also specify the widths of columns as percentages. In this example, we’ll set the width of the num column to "20%", the char column to "10%", and the date column to "30%". Note that the percentages are relative and don’t need to sum to 100%.
We can also mix and match pixel and percentage widths. In this example, we’ll set the width of the num column to "150px", the char column to "10%", and the date column to "30%".
If we set the width of all columns, the table will be forced to use the specified widths (i.e., a column width less than the content width will be honored). In this next example, we’ll set widths for all columns. This is a good way to ensure that the widths you specify are fully respected (and not overridden by automatic width calculations).
Notice that in the above example, the num column is very small (only 30px) and the content overflows. When not specifying the width of all columns, the table will automatically adjust the column widths based on the content (and you wouldn’t get the overflowing behavior seen in the previous example).
It’s possible to add color to data cells according to their values with the data_color() method. There is a multitude of ways to perform data cell colorizing here:
targeting: we can constrain which columns should receive the colorization treatment through the columns= argument)
color palettes: with palette= we could supply a list of colors composed of hexadecimal values or color names
value domain: we can either opt to have the range of values define the domain, or, specify one explicitly with the domain= argument
text autocoloring: data_color() will automatically recolor the foreground text to provide the best contrast (can be deactivated with autocolor_text=False)
Parameters
Name
Type
Description
Default
columns
SelectExpr
The columns to target. Can either be a single column name or a series of column names provided in a list.
None
rows
RowSelectExpr
In conjunction with columns=, we can specify which rows should be colored. By default, all rows in the targeted columns will be colored. Alternatively, we can provide a list of row indices.
None
palette
str | list[str] | None
The color palette to use. This should be a list of colors (e.g., ["#FF0000", "#00FF00", "#0000FF"]). A ColorBrewer palette could also be used, just supply the name (reference available in the Color palette access from ColorBrewer section). If None, then a default palette will be used.
None
domain
list[str] | list[int] | list[float] | None
The domain of values to use for the color scheme. This can be a list of floats, integers, or strings. If None, then the domain will be inferred from the data values.
None
na_color
str | None
The color to use for missing values. If None, then the default color ("#808080") will be used.
None
alpha
int | float | None
An optional, fixed alpha transparency value that will be applied to all color palette values.
None
reverse
bool
Should the colors computed operate in the reverse order? If True then colors that normally change from red to blue will change in the opposite direction.
False
autocolor_text
bool
Whether or not to automatically color the text of the data values. If True, then the text will be colored according to the background color of the cell.
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Color Palette Access From Colorbrewer And Viridis
All palettes from the ColorBrewer package can be accessed by providing the palette name in palette=. There are 35 available palettes:
Palette Name
Colors
Category
Colorblind Friendly
1
"BrBG"
11
Diverging
Yes
2
"PiYG"
11
Diverging
Yes
3
"PRGn"
11
Diverging
Yes
4
"PuOr"
11
Diverging
Yes
5
"RdBu"
11
Diverging
Yes
6
"RdYlBu"
11
Diverging
Yes
7
"RdGy"
11
Diverging
No
8
"RdYlGn"
11
Diverging
No
9
"Spectral"
11
Diverging
No
10
"Dark2"
8
Qualitative
Yes
11
"Paired"
12
Qualitative
Yes
12
"Set1"
9
Qualitative
No
13
"Set2"
8
Qualitative
Yes
14
"Set3"
12
Qualitative
No
15
"Accent"
8
Qualitative
No
16
"Pastel1"
9
Qualitative
No
17
"Pastel2"
8
Qualitative
No
18
"Blues"
9
Sequential
Yes
19
"BuGn"
9
Sequential
Yes
20
"BuPu"
9
Sequential
Yes
21
"GnBu"
9
Sequential
Yes
22
"Greens"
9
Sequential
Yes
23
"Greys"
9
Sequential
Yes
24
"Oranges"
9
Sequential
Yes
25
"OrRd"
9
Sequential
Yes
26
"PuBu"
9
Sequential
Yes
27
"PuBuGn"
9
Sequential
Yes
28
"PuRd"
9
Sequential
Yes
29
"Purples"
9
Sequential
Yes
30
"RdPu"
9
Sequential
Yes
31
"Reds"
9
Sequential
Yes
32
"YlGn"
9
Sequential
Yes
33
"YlGnBu"
9
Sequential
Yes
34
"YlOrBr"
9
Sequential
Yes
35
"YlOrRd"
9
Sequential
Yes
We can also use the viridis and associated color palettes by providing to palette= any of the following string values: "viridis", "plasma", "inferno", "magma", or "cividis".
Examples
The data_color() method can be used without any supplied arguments to colorize a table. Let’s do this with the exibble dataset:
from great_tables import GTfrom great_tables.data import exibbleGT(exibble).data_color()
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
What’s happened is that data_color() applies background colors to all cells of every column with the palette of eight colors. Numeric columns will use ‘numeric’ methodology for color scaling whereas string-based columns will use the ‘factor’ methodology. The text color undergoes an automatic modification that maximizes contrast (since autocolor_text=True by default).
We can target specific colors and apply color to just those columns. Let’s do that and also supply palette= values of "red" and "green".
With those options in place we see that only the numeric columns num and currency received color treatments. Moreover, the palette colors were mapped to the lower and upper limits of the data in each column; interpolated colors were used for the values in between the numeric limits of the two columns.
We can manually set the limits of the data with the domain= argument (which is preferable in most cases). Let’s colorize just the currency column and set domain=[0, 50]. Any values that are either missing or lie outside of the domain will be colorized with the na_color= color (so we’ll set that to "lightgray").
The fmt() method provides a way to execute custom formatting functionality with raw data values in a way that can consider all output contexts.
Along with the columns and rows arguments that provide some precision in targeting data cells, the fns argument allows you to define one or more functions for manipulating the raw data.
Parameters
Name
Type
Description
Default
fns
FormatFn | FormatFns
Either a single formatting function or a named list of functions.
required
columns
SelectExpr
The columns to target. Can either be a single column name or a series of column names provided in a list.
None
rows
int | list[int] | None
In conjunction with columns=, we can specify which of their rows should undergo formatting. The default is all rows, resulting in all rows in columns being formatted. Alternatively, we can supply a list of row indices.
None
is_substitution
bool
Whether the formatter is a substitution. Substitutions are run last, after other formatters.
With numeric values in a table, we can transform those to values of bytes with human readable units. The fmt_bytes() method allows for the formatting of byte sizes to either of two common representations: (1) with decimal units (powers of 1000, examples being "kB" and "MB"), and (2) with binary units (powers of 1024, examples being "KiB" and "MiB"). It is assumed the input numeric values represent the number of bytes and automatic truncation of values will occur. The numeric values will be scaled to be in the range of 1 to <1000 and then decorated with the correct unit symbol according to the standard chosen. For more control over the formatting of byte sizes, we can use the following options:
decimals: choice of the number of decimal places, option to drop trailing zeros, and a choice of the decimal symbol
digit grouping separators: options to enable/disable digit separators and provide a choice of separator symbol
pattern: option to use a text pattern for decoration of the formatted values
locale-based formatting: providing a locale ID will result in number formatting specific to the chosen locale
Parameters
Name
Type
Description
Default
columns
SelectExpr
The columns to target. Can either be a single column name or a series of column names provided in a list.
None
rows
int | list[int] | None
In conjunction with columns=, we can specify which of their rows should undergo formatting. The default is all rows, resulting in all rows in targeted columns being formatted. Alternatively, we can supply a list of row indices.
None
standard
str
The form of expressing large byte sizes is divided between: (1) decimal units (powers of 1000; e.g., "kB" and "MB"), and (2) binary units (powers of 1024; e.g., "KiB" and "MiB"). The default is to use decimal units with the "decimal" option. The alternative is to use binary units with the "binary" option.
'decimal'
decimals
int
This corresponds to the exact number of decimal places to use. A value such as 2.34 can, for example, be formatted with 0 decimal places and it would result in "2". With 4 decimal places, the formatted value becomes "2.3400". The trailing zeros can be removed with drop_trailing_zeros=True.
1
drop_trailing_zeros
bool
A boolean value that allows for removal of trailing zeros (those redundant zeros after the decimal mark).
True
drop_trailing_dec_mark
bool
A boolean value that determines whether decimal marks should always appear even if there are no decimal digits to display after formatting (e.g., 23 becomes 23. if False). By default trailing decimal marks are not shown.
True
use_seps
bool
The use_seps option allows for the use of digit group separators. The type of digit group separator is set by sep_mark and overridden if a locale ID is provided to locale. This setting is True by default.
True
pattern
str
A formatting pattern that allows for decoration of the formatted value. The formatted value is represented by the {x} (which can be used multiple times, if needed) and all other characters will be interpreted as string literals.
'{x}'
sep_mark
str
The string to use as a separator between groups of digits. For example, using sep_mark="," with a value of 1000 would result in a formatted value of "1,000". This argument is ignored if a locale is supplied (i.e., is not None).
','
dec_mark
str
The string to be used as the decimal mark. For example, using dec_mark="," with the value 0.152 would result in a formatted value of "0,152"). This argument is ignored if a locale is supplied (i.e., is not None).
'.'
force_sign
bool
Should the positive sign be shown for positive values (effectively showing a sign for all values except zero)? If so, use True for this option. The default is False, where only negative numbers will display a minus sign.
False
incl_space
bool
An option for whether to include a space between the value and the currency symbol. The default is to not introduce a space character.
True
locale
str | None
An optional locale identifier that can be used for formatting values according the locale’s rules. Examples include "en" for English (United States) and "fr" for French (France).
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Adapting Output To A Specific Locale
This formatting method can adapt outputs according to a provided locale value. Examples include "en" for English (United States) and "fr" for French (France). The use of a valid locale ID here means separator and decimal marks will be correct for the given locale. Should any values be provided in sep_mark or dec_mark, they will be overridden by the locale’s preferred values.
Note that a locale value provided here will override any global locale setting performed in GT()’s own locale argument (it is settable there as a value received by all other methods that have a locale argument).
Examples
Let’s use a single column from the exibble dataset and create a new table. We’ll format the num column to display as byte sizes in the decimal standard through use of the fmt_bytes() method.
from great_tables import GT, exibble( GT(exibble[["num"]]) .fmt_bytes(columns="num", standard="decimal"))
num
0 B
2 B
33 B
444 B
5.5 kB
777 kB
8.9 MB
See Also
The functional version of this method, val_fmt_bytes(), allows you to format a single numerical value (or a list of them).
With numeric values in a gt table, we can perform currency-based formatting with the fmt_currency() method. This supports both automatic formatting with a three-letter currency code. We have fine control over the conversion from numeric values to currency values, where we could take advantage of the following options:
the currency: providing a currency code or common currency name will procure the correct currency symbol and number of currency subunits
currency symbol placement: the currency symbol can be placed before or after the values
decimals/subunits: choice of the number of decimal places, and a choice of the decimal symbol, and an option on whether to include or exclude the currency subunits (the decimal portion)
digit grouping separators: options to enable/disable digit separators and provide a choice of separator symbol
scaling: we can choose to scale targeted values by a multiplier value
pattern: option to use a text pattern for decoration of the formatted currency values
locale-based formatting: providing a locale ID will result in currency formatting specific to the chosen locale; it will also retrieve the locale’s currency if none is explicitly given
Parameters
Name
Type
Description
Default
columns
SelectExpr
The columns to target. Can either be a single column name or a series of column names provided in a list.
None
rows
int | list[int] | None
In conjunction with columns=, we can specify which of their rows should undergo formatting. The default is all rows, resulting in all rows in targeted columns being formatted. Alternatively, we can supply a list of row indices.
None
currency
str | None
The currency to use for the numeric value. This input can be supplied as a 3-letter currency code (e.g., "USD" for U.S. Dollars, "EUR" for the Euro currency).
None
use_subunits
bool
An option for whether the subunits portion of a currency value should be displayed. For example, with an input value of 273.81, the default formatting will produce "$273.81". Removing the subunits (with use_subunits = False) will give us "$273".
True
decimals
int | None
The decimals values corresponds to the exact number of decimal places to use. This value is optional as a currency has an intrinsic number of decimal places (i.e., the subunits). A value such as 2.34 can, for example, be formatted with 0 decimal places and if the currency used is "USD" it would result in "$2". With 4 decimal places, the formatted value becomes "$2.3400".
None
drop_trailing_dec_mark
bool
A boolean value that determines whether decimal marks should always appear even if there are no decimal digits to display after formatting (e.g., 23 becomes 23. if False). By default trailing decimal marks are not shown.
True
use_seps
bool
The use_seps option allows for the use of digit group separators. The type of digit group separator is set by sep_mark and overridden if a locale ID is provided to locale. This setting is True by default.
True
scale_by
float
All numeric values will be multiplied by the scale_by value before undergoing formatting. Since the default value is 1, no values will be changed unless a different multiplier value is supplied.
1
pattern
str
A formatting pattern that allows for decoration of the formatted value. The formatted value is represented by the {x} (which can be used multiple times, if needed) and all other characters will be interpreted as string literals.
'{x}'
sep_mark
str
The string to use as a separator between groups of digits. For example, using sep_mark="," with a value of 1000 would result in a formatted value of "1,000". This argument is ignored if a locale is supplied (i.e., is not None).
','
dec_mark
str
The string to be used as the decimal mark. For example, using dec_mark="," with the value 0.152 would result in a formatted value of "0,152"). This argument is ignored if a locale is supplied (i.e., is not None).
'.'
force_sign
bool
Should the positive sign be shown for positive values (effectively showing a sign for all values except zero)? If so, use True for this option. The default is False, where only negative numbers will display a minus sign.
False
placement
str
The placement of the currency symbol. This can be either be "left" (as in "$450") or "right" (which yields "450$").
'left'
incl_space
bool
An option for whether to include a space between the value and the currency symbol. The default is to not introduce a space character.
False
locale
str | None
An optional locale identifier that can be used for formatting values according the locale’s rules. Examples include "en" for English (United States) and "fr" for French (France).
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Adapting Output To A Specific Locale
This formatting method can adapt outputs according to a provided locale value. Examples include "en" for English (United States) and "fr" for French (France). The use of a valid locale ID here means separator and decimal marks will be correct for the given locale. Should any values be provided in sep_mark or dec_mark, they will be overridden by the locale’s preferred values. In addition to number formatting, providing a locale value and not providing a currency allows Great Tables to obtain the currency code from the locale’s territory.
Note that a locale value provided here will override any global locale setting performed in GT()’s own locale argument (it is settable there as a value received by all other methods that have a locale argument).
Examples
Let’s use the exibble dataset to create a table. With the fmt_currency() method, we’ll format the currency column to display monetary values.
Format input values to time values using one of 17 preset date styles. Input can be in the form of date type or as a ISO-8601 string (in the form of YYYY-MM-DD HH:MM:SS or YYYY-MM-DD).
Parameters
Name
Type
Description
Default
columns
SelectExpr
The columns to target. Can either be a single column name or a series of column names provided in a list.
None
rows
int | list[int] | None
In conjunction with columns=, we can specify which of their rows should undergo formatting. The default is all rows, resulting in all rows in targeted columns being formatted. Alternatively, we can supply a list of row indices.
None
date_style
DateStyle
The date style to use. By default this is the short name "iso" which corresponds to ISO 8601 date formatting. There are 41 date styles in total and their short names can be viewed using info_date_style().
'iso'
pattern
str
A formatting pattern that allows for decoration of the formatted value. The formatted value is represented by the {x} (which can be used multiple times, if needed) and all other characters will be interpreted as string literals.
'{x}'
locale
str | None
An optional locale identifier that can be used for formatting values according the locale’s rules. Examples include "en" for English (United States) and "fr" for French (France).
None
Formatting With The Date_Style Argument
We need to supply a preset date style to the date_style argument. The date styles are numerous and can handle localization to any supported locale. The following table provides a listing of all date styles and their output values (corresponding to an input date of 2000-02-29).
Date Style
Output
1
"iso"
"2000-02-29"
2
"wday_month_day_year"
"Tuesday, February 29, 2000"
3
"wd_m_day_year"
"Tue, Feb 29, 2000"
4
"wday_day_month_year"
"Tuesday 29 February 2000"
5
"month_day_year"
"February 29, 2000"
6
"m_day_year"
"Feb 29, 2000"
7
"day_m_year"
"29 Feb 2000"
8
"day_month_year"
"29 February 2000"
9
"day_month"
"29 February"
10
"day_m"
"29 Feb"
11
"year"
"2000"
12
"month"
"February"
13
"day"
"29"
14
"year.mn.day"
"2000/02/29"
15
"y.mn.day"
"00/02/29"
16
"year_week"
"2000-W09"
17
"year_quarter"
"2000-Q1"
We can use the info_date_style() function within the console to view a similar table of date styles with example output.
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Adapting Output To A Specific Locale
This formatting method can adapt outputs according to a provided locale value. Examples include "en" for English (United States) and "fr" for French (France). Note that a locale value provided here will override any global locale setting performed in GT()’s own locale argument (it is settable there as a value received by all other methods that have a locale argument).
Examples
Let’s use the exibble dataset to create a simple, two-column table (keeping only the date and time columns). With the fmt_date() method, we’ll format the date column to display dates formatted with the "month_day_year" date style.
Format input values to datetime values using one of 17 preset date styles and one of 5 preset time styles. Input can be in the form of datetime values, or strings in the ISO 8601 forms of YYYY-MM-DD HH:MM:SS or YYYY-MM-DD.
Parameters
Name
Type
Description
Default
columns
SelectExpr
The columns to target. Can either be a single column name or a series of column names provided in a list.
None
rows
int | list[int] | None
In conjunction with columns=, we can specify which of their rows should undergo formatting. The default is all rows, resulting in all rows in targeted columns being formatted. Alternatively, we can supply a list of row indices.
None
date_style
DateStyle
The date style to use. By default this is the short name "iso" which corresponds to ISO 8601 date formatting. There are 41 date styles in total and their short names can be viewed using info_date_style().
'iso'
time_style
TimeStyle
The time style to use. By default this is the short name "iso" which corresponds to how times are formatted within ISO 8601 datetime values. There are 5 time styles in total and their short names can be viewed using info_time_style().
'iso'
Formatting With The Date_Style And Time_Style Arguments
We need to supply a preset date style to the date_style argument and a preset time style to the time_style argument. The date styles are numerous and can handle localization to any supported locale. The following table provides a listing of all date styles and their output values (corresponding to an input date of 2000-02-29 14:35:00).
Date Style
Output
1
"iso"
"2000-02-29"
2
"wday_month_day_year"
"Tuesday, February 29, 2000"
3
"wd_m_day_year"
"Tue, Feb 29, 2000"
4
"wday_day_month_year"
"Tuesday 29 February 2000"
5
"month_day_year"
"February 29, 2000"
6
"m_day_year"
"Feb 29, 2000"
7
"day_m_year"
"29 Feb 2000"
8
"day_month_year"
"29 February 2000"
9
"day_month"
"29 February"
10
"day_m"
"29 Feb"
11
"year"
"2000"
12
"month"
"February"
13
"day"
"29"
14
"year.mn.day"
"2000/02/29"
15
"y.mn.day"
"00/02/29"
16
"year_week"
"2000-W09"
17
"year_quarter"
"2000-Q1"
The time styles are numerous and can handle localization to any supported locale. The following table provides a listing of all time styles and their output values (corresponding to an input time of 2000-02-29 14:35:00).
Time Style
Output
Notes
1
"iso"
"14:35:00"
ISO 8601, 24h
2
"iso-short"
"14:35"
ISO 8601, 24h
3
"h_m_s_p"
"2:35:00 PM"
12h
4
"h_m_p"
"2:35 PM"
12h
5
"h_p"
"2 PM"
12h
We can use the info_date_style() and info_time_style() functions within the console to view similar tables of date and time styles with example output.
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Examples
Let’s use the exibble dataset to create a simple, two-column table (keeping only the date and time columns). With the fmt_datetime() method, we’ll format the date column to display dates formatted with the "month_day_year" date style and the time column to display times formatted with the "h_m_s_p" time style.
To more easily insert graphics into body cells, we can use the fmt_image() method. This allows for one or more images to be placed in the targeted cells. The cells need to contain some reference to an image file, either: (1) complete http/https or local paths to the files; (2) the file names, where a common path can be provided via path=; or (3) a fragment of the file name, where the file_pattern= argument helps to compose the entire file name and path= provides the path information. This should be expressly used on columns that contain only references to image files (i.e., no image references as part of a larger block of text). Multiple images can be included per cell by separating image references by commas. The sep= argument allows for a common separator to be applied between images.
Parameters
Name
Type
Description
Default
columns
SelectExpr
The columns to target. Can either be a single column name or a series of column names provided in a list.
None
rows
int | list[int] | None
In conjunction with columns=, we can specify which of their rows should undergo formatting. The default is all rows, resulting in all rows in targeted columns being formatted. Alternatively, we can supply a list of row indices.
None
height
str | int | None
The height of the rendered images.
None
width
str | int | None
The width of the rendered images.
None
sep
str
In the output of images within a body cell, sep= provides the separator between each image.
' '
path
str | Path | None
An optional path to local image files (this is combined with all filenames).
None
file_pattern
str
The pattern to use for mapping input values in the body cells to the names of the graphics files. The string supplied should use "{}" in the pattern to map filename fragments to input strings.
'{}'
encode
bool
The option to always use Base64 encoding for image paths that are determined to be local. By default, this is True.
True
Examples
Using a small portion of metro dataset, let’s create a new table. We will only include a few columns and rows from that table. The lines column has comma-separated listings of numbers corresponding to lines served at each station. We have a directory of SVG graphics for all of these lines in the package (the path for the image directory can be accessed via files("great_tables") / "data/metro_images", using the importlib_resources package). The filenames roughly corresponds to the data in the lines column. The fmt_image() method can be used with these inputs since the path= and file_pattern= arguments allow us to compose complete and valid file locations. What you get from this are sequences of images in the table cells, taken from the referenced graphics files on disk.
With numeric values in one or more table columns, we can perform number-based formatting so that the targeted values are always rendered as integer values.
We can have fine control over integer formatting with the following options:
digit grouping separators: options to enable/disable digit separators and provide a choice of separator symbol
scaling: we can choose to scale targeted values by a multiplier value
large-number suffixing: larger figures (thousands, millions, etc.) can be autoscaled and decorated with the appropriate suffixes
pattern: option to use a text pattern for decoration of the formatted values
locale-based formatting: providing a locale ID will result in number formatting specific to the chosen locale
Parameters
Name
Type
Description
Default
columns
SelectExpr
The columns to target. Can either be a single column name or a series of column names provided in a list.
None
rows
int | list[int] | None
In conjunction with columns=, we can specify which of their rows should undergo formatting. The default is all rows, resulting in all rows in targeted columns being formatted. Alternatively, we can supply a list of row indices.
None
use_seps
bool
The use_seps option allows for the use of digit group separators. The type of digit group separator is set by sep_mark and overridden if a locale ID is provided to locale. This setting is True by default.
True
scale_by
float
All numeric values will be multiplied by the scale_by value before undergoing formatting. Since the default value is 1, no values will be changed unless a different multiplier value is supplied.
1
compact
bool
A boolean value that allows for compact formatting of numeric values. Values will be scaled and decorated with the appropriate suffixes (e.g., 1230 becomes 1K, and 1230000 becomes 1M). The compact option is False by default.
False
pattern
str
A formatting pattern that allows for decoration of the formatted value. The formatted value is represented by the {x} (which can be used multiple times, if needed) and all other characters will be interpreted as string literals.
'{x}'
sep_mark
str
The string to use as a separator between groups of digits. For example, using sep_mark="," with a value of 1000 would result in a formatted value of "1,000". This argument is ignored if a locale is supplied (i.e., is not None).
','
force_sign
bool
Should the positive sign be shown for positive values (effectively showing a sign for all values except zero)? If so, use True for this option. The default is False, where only negative numbers will display a minus sign.
False
locale
str | None
An optional locale identifier that can be used for formatting values according the locale’s rules. Examples include "en" for English (United States) and "fr" for French (France).
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Adapting Output To A Specific Locale
This formatting method can adapt outputs according to a provided locale value. Examples include "en" for English (United States) and "fr" for French (France). The use of a valid locale ID here means separator marks will be correct for the given locale. Should any value be provided in sep_mark, it will be overridden by the locale’s preferred value.
Note that a locale value provided here will override any global locale setting performed in GT()’s own locale argument (it is settable there as a value received by all other methods that have a locale argument).
Examples
For this example, we’ll use the exibble dataset as the input table. With the fmt_integer() method, we’ll format the num column as integer values having no digit separators (with the use_seps=False option).
from great_tables import GT, exibble( GT(exibble) .fmt_integer(columns="num", use_seps=False))
num
char
fctr
date
time
datetime
currency
row
group
0
apricot
one
2015-01-15
13:35
2018-01-01 02:22
49.95
row_1
grp_a
2
banana
two
2015-02-15
14:40
2018-02-02 14:33
17.95
row_2
grp_a
33
coconut
three
2015-03-15
15:45
2018-03-03 03:44
1.39
row_3
grp_a
444
durian
four
2015-04-15
16:50
2018-04-04 15:55
65100.0
row_4
grp_a
5550
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
grapefruit
seven
19:10
2018-07-07 05:22
row_7
grp_b
8880000
honeydew
eight
2015-08-15
20:20
0.44
row_8
grp_b
See Also
The fmt_number() method might be more of what you need if you’d like decimal values in your outputs. Need to do integer-based formatting on a value or list of values? Take a look at the functional version of this method: val_fmt_integer().
fmt_markdown
GT.fmt_markdown(self, columns=None, rows=None)
Format Markdown text.
Any Markdown-formatted text in the incoming cells will be transformed during render when using the fmt_markdown() method.
Parameters
Name
Type
Description
Default
columns
SelectExpr
The columns to target. Can either be a single column name or a series of column names provided in a list.
None
rows
int | list[int] | None
In conjunction with columns=, we can specify which of their rows should undergo formatting. The default is all rows, resulting in all rows in targeted columns being formatted. Alternatively, we can supply a list of row indices.
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Examples:
Let’s first create a DataFrame containing some text that is Markdown-formatted and then introduce that to GT(). We’ll then transform the md column with the fmt_markdown() method.
import pandas as pdfrom great_tables import GTfrom great_tables.data import townytext_1 ="""### This is Markdown.Markdown’s syntax is comprised entirely ofpunctuation characters, which punctuationcharacters have been carefully chosen so asto look like what they mean... assumingyou’ve ever used email."""text_2 ="""Info on Markdown syntax can be found[here](https://daringfireball.net/projects/markdown/)."""df = pd.DataFrame({"md": [text_1, text_2]})(GT(df).fmt_markdown("md"))
md
This is Markdown.
Markdown’s syntax is comprised entirely of
punctuation characters, which punctuation
characters have been carefully chosen so as
to look like what they mean... assuming
you’ve ever used email.
The fmt_nanoplot() method is used to format data for nanoplot visualizations. This method allows for the creation of a variety of different plot types, including line, bar, and scatter plots.
Warning
fmt_nanoplot() is still experimental.
Parameters
Name
Type
Description
Default
columns
str | None
The columns to target. Can either be a single column name or a series of column names provided in a list.
None
rows
int | list[int] | None
In conjunction with columns=, we can specify which of their rows should undergo formatting. The default is all rows, resulting in all rows in targeted columns being formatted. Alternatively, we can supply a list of row indices.
None
plot_type
PlotType
Nanoplots can either take the form of a line plot (using "line") or a bar plot (with "bar"). A line plot, by default, contains layers for a data line, data points, and a data area. With a bar plot, the always visible layer is that of the data bars.
'line'
plot_height
str
The height of the nanoplots. The default here is a sensible value of "2em".
'2em'
missing_vals
MissingVals
If missing values are encountered within the input data, there are three strategies available for their handling: (1) "gap" will show data gaps at the sites of missing data, where data lines will have discontinuities and bar plots will have missing bars; (2) "marker" will behave like "gap" but show prominent visual marks at the missing data locations; (3) "zero" will replace missing values with zero values; and (4) "remove" will remove any incoming missing values.
'marker'
autoscale
bool
Using autoscale=True will ensure that the bounds of all nanoplots produced are based on the limits of data combined from all input rows. This will result in a shared scale across all of the nanoplots (for y- and x-axis data), which is useful in those cases where the nanoplot data should be compared across rows.
False
reference_line
str | int | float | None
A reference line requires a single input to define the line. It could be a numeric value, applied to all nanoplots generated. Or, the input can be one of the following for generating the line from the underlying data: (1) "mean", (2) "median", (3) "min", (4) "max", (5) "q1", (6) "q3", (7) "first", or (8) "last".
None
reference_area
list[Any] | None
A reference area requires a list of two values for defining bottom and top boundaries (in the y direction) for a rectangular area. The types of values supplied are the same as those expected for reference_line=, which is either a numeric value or one of the following keywords for the generation of the value: (1) "mean", (2) "median", (3) "min", (4) "max", (5) "q1", (6) "q3", (7) "first", or (8) "last". Input can either be a vector or list with two elements.
Should you need to have plots expand in the x direction, provide one or more values to expand_x=. Any values provided that are outside of the range of x-value data provided to the plot will result in a x-scale expansion.
Similar to expand_x=, one can have plots expand in the y direction. To make this happen, provide one or more values to expand_y=. If any of the provided values are outside of the range of y-value data provided, the plot will result in a y-scale expansion.
None
options
dict[str, Any] | None
By using the nanoplot_options() helper function here, you can alter the layout and styling of the nanoplots in the new column.
None
Details
Nanoplots try to show individual data with reasonably good visibility. Interactivity is included as a basic feature so one can hover over the data points and vertical guides will display the value ascribed to each data point. Because Great Tables knows all about numeric formatting, values will be compactly formatted so as to not take up valuable real estate.
While basic customization options are present in fmt_nanoplot(), many more opportunities for customizing nanoplots on a more granular level are possible with the aforementioned nanoplot_options() helper function. With that, layers of the nanoplots can be selectively removed and the aesthetics of the remaining plot components can be modified.
Examples
Let’s create a nanoplot from a Polars DataFrame containing multiple numbers per cell. The numbers are represented here as strings, where spaces separate the values, and the same values are present in two columns: lines and bars. We will use the fmt_nanoplot() method twice to create a line plot and a bar plot from the data in their respective columns.
We can always represent the input DataFrame in a different way (with list columns) and fmt_nanoplot() will still work. While the input data is the same as in the previous example, we’ll take the opportunity here to add a reference line and a reference area to the line plot and also to the bar plot.
Single-value bar plots and line plots can be made with fmt_nanoplot(). These run in the horizontal direction, which is ideal for tabular presentation. The key thing here is that fmt_nanoplot() expects a column of numeric values. These plots are meant for comparison across rows so the method automatically scales the horizontal bars to facilitate this type of display. The following example shows how fmt_nanoplot() can be used to create single-value bar and line plots.
With numeric values within a table’s body cells, we can perform number-based formatting so that the targeted values are rendered with a higher consideration for tabular presentation. Furthermore, there is finer control over numeric formatting with the following options:
decimals: choice of the number of decimal places, option to drop trailing zeros, and a choice of the decimal symbol
digit grouping separators: options to enable/disable digit separators and provide a choice of separator symbol
scaling: we can choose to scale targeted values by a multiplier value
large-number suffixing: larger figures (thousands, millions, etc.) can be autoscaled and decorated with the appropriate suffixes
pattern: option to use a text pattern for decoration of the formatted values
locale-based formatting: providing a locale ID will result in number formatting specific to the chosen locale
Parameters
Name
Type
Description
Default
columns
SelectExpr
The columns to target. Can either be a single column name or a series of column names provided in a list.
None
rows
int | list[int] | None
In conjunction with columns=, we can specify which of their rows should undergo formatting. The default is all rows, resulting in all rows in targeted columns being formatted. Alternatively, we can supply a list of row indices.
None
decimals
int
The decimals values corresponds to the exact number of decimal places to use. A value such as 2.34 can, for example, be formatted with 0 decimal places and it would result in "2". With 4 decimal places, the formatted value becomes "2.3400". The trailing zeros can be removed with drop_trailing_zeros=True. If you always need decimals = 0, the fmt_integer() method should be considered.
2
n_sigfig
int | None
A option to format numbers to n significant figures. By default, this is None and thus number values will be formatted according to the number of decimal places set via decimals. If opting to format according to the rules of significant figures, n_sigfig must be a number greater than or equal to 1. Any values passed to the decimals and drop_trailing_zeros arguments will be ignored.
None
drop_trailing_zeros
bool
A boolean value that allows for removal of trailing zeros (those redundant zeros after the decimal mark).
False
drop_trailing_dec_mark
bool
A boolean value that determines whether decimal marks should always appear even if there are no decimal digits to display after formatting (e.g., 23 becomes 23. if False). By default trailing decimal marks are not shown.
True
use_seps
bool
The use_seps option allows for the use of digit group separators. The type of digit group separator is set by sep_mark and overridden if a locale ID is provided to locale. This setting is True by default.
True
scale_by
float
All numeric values will be multiplied by the scale_by value before undergoing formatting. Since the default value is 1, no values will be changed unless a different multiplier value is supplied.
1
compact
bool
A boolean value that allows for compact formatting of numeric values. Values will be scaled and decorated with the appropriate suffixes (e.g., 1230 becomes 1.23K, and 1230000 becomes 1.23M). The compact option is False by default.
False
pattern
str
A formatting pattern that allows for decoration of the formatted value. The formatted value is represented by the {x} (which can be used multiple times, if needed) and all other characters will be interpreted as string literals.
'{x}'
sep_mark
str
The string to use as a separator between groups of digits. For example, using sep_mark="," with a value of 1000 would result in a formatted value of "1,000". This argument is ignored if a locale is supplied (i.e., is not None).
','
dec_mark
str
The string to be used as the decimal mark. For example, using dec_mark="," with the value 0.152 would result in a formatted value of "0,152"). This argument is ignored if a locale is supplied (i.e., is not None).
'.'
force_sign
bool
Should the positive sign be shown for positive values (effectively showing a sign for all values except zero)? If so, use True for this option. The default is False, where only negative numbers will display a minus sign.
False
locale
str | None
An optional locale identifier that can be used for formatting values according the locale’s rules. Examples include "en" for English (United States) and "fr" for French (France).
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Adapting Output To A Specific Locale
This formatting method can adapt outputs according to a provided locale value. Examples include "en" for English (United States) and "fr" for French (France). The use of a valid locale ID here means separator and decimal marks will be correct for the given locale. Should any values be provided in sep_mark or dec_mark, they will be overridden by the locale’s preferred values.
Note that a locale value provided here will override any global locale setting performed in GT()’s own locale argument (it is settable there as a value received by all other methods that have a locale argument).
Examples
Let’s use the exibble dataset to create a table. With the fmt_number() method, we’ll format the num column to have three decimal places (with decimals=3) and omit the use of digit separators (with use_seps=False).
from great_tables import GT, exibble( GT(exibble) .fmt_number(columns="num", decimals=3, use_seps=False))
num
char
fctr
date
time
datetime
currency
row
group
0.111
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.330
coconut
three
2015-03-15
15:45
2018-03-03 03:44
1.39
row_3
grp_a
444.400
durian
four
2015-04-15
16:50
2018-04-04 15:55
65100.0
row_4
grp_a
5550.000
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.000
grapefruit
seven
19:10
2018-07-07 05:22
row_7
grp_b
8880000.000
honeydew
eight
2015-08-15
20:20
0.44
row_8
grp_b
See Also
The fmt_integer() method might be more useful if you really need to format numeric values to appear as integers (i.e., no decimals will be shown and input values are rounded as necessary). Need to do numeric formatting on a value or list of values? Take a look at the functional version of this method: val_fmt_number().
With numeric values in a gt table, we can perform percentage-based formatting. It is assumed the input numeric values are proportional values and, in this case, the values will be automatically multiplied by 100 before decorating with a percent sign (the other case is accommodated though setting scale_values to False). For more control over percentage formatting, we can use the following options:
percent sign placement: the percent sign can be placed after or before the values and a space can be inserted between the symbol and the value.
decimals: choice of the number of decimal places, option to drop trailing zeros, and a choice of the decimal symbol
digit grouping separators: options to enable/disable digit separators and provide a choice of separator symbol
value scaling toggle: choose to disable automatic value scaling in the situation that values are already scaled coming in (and just require the percent symbol)
pattern: option to use a text pattern for decoration of the formatted values
locale-based formatting: providing a locale ID will result in number formatting specific to the chosen locale
Parameters
Name
Type
Description
Default
columns
SelectExpr
The columns to target. Can either be a single column name or a series of column names provided in a list.
None
rows
int | list[int] | None
In conjunction with columns=, we can specify which of their rows should undergo formatting. The default is all rows, resulting in all rows in targeted columns being formatted. Alternatively, we can supply a list of row indices.
None
decimals
int
The decimals values corresponds to the exact number of decimal places to use. A value such as 2.34 can, for example, be formatted with 0 decimal places and it would result in "2". With 4 decimal places, the formatted value becomes "2.3400". The trailing zeros can be removed with drop_trailing_zeros=True.
2
drop_trailing_zeros
bool
A boolean value that allows for removal of trailing zeros (those redundant zeros after the decimal mark).
False
drop_trailing_dec_mark
bool
A boolean value that determines whether decimal marks should always appear even if there are no decimal digits to display after formatting (e.g., 23 becomes 23. if False). By default trailing decimal marks are not shown.
True
scale_values
bool
Should the values be scaled through multiplication by 100? By default this scaling is performed since the expectation is that incoming values are usually proportional. Setting to False signifies that the values are already scaled and require only the percent sign when formatted.
True
use_seps
bool
The use_seps option allows for the use of digit group separators. The type of digit group separator is set by sep_mark and overridden if a locale ID is provided to locale. This setting is True by default.
True
pattern
str
A formatting pattern that allows for decoration of the formatted value. The formatted value is represented by the {x} (which can be used multiple times, if needed) and all other characters will be interpreted as string literals.
'{x}'
sep_mark
str
The string to use as a separator between groups of digits. For example, using sep_mark="," with a value of 1000 would result in a formatted value of "1,000". This argument is ignored if a locale is supplied (i.e., is not None).
','
dec_mark
str
The string to be used as the decimal mark. For example, using dec_mark="," with the value 0.152 would result in a formatted value of "0,152"). This argument is ignored if a locale is supplied (i.e., is not None).
'.'
force_sign
bool
Should the positive sign be shown for positive values (effectively showing a sign for all values except zero)? If so, use True for this option. The default is False, where only negative numbers will display a minus sign.
False
placement
str
This option governs the placement of the percent sign. This can be either be "right" (the default) or "left".
'right'
incl_space
bool
An option for whether to include a space between the value and the percent sign. The default is to not introduce a space character.
False
locale
str | None
An optional locale identifier that can be used for formatting values according the locale’s rules. Examples include "en" for English (United States) and "fr" for French (France).
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Adapting Output To A Specific Locale
This formatting method can adapt outputs according to a provided locale value. Examples include "en" for English (United States) and "fr" for French (France). The use of a valid locale ID here means separator and decimal marks will be correct for the given locale. Should any values be provided in sep_mark or dec_mark, they will be overridden by the locale’s preferred values.
Note that a locale value provided here will override any global locale setting performed in GT()’s own locale argument (it is settable there as a value received by all other methods that have a locale argument).
Examples
Let’s use the towny dataset as the input table. With the fmt_percent() method, we’ll format the pop_change_2016_2021_pct column to to display values as percentages (to two decimal places).
With numeric values in a gt table we can transform those to Roman numerals, rounding values as necessary.
Parameters
Name
Type
Description
Default
columns
SelectExpr
The columns to target. Can either be a single column name or a series of column names provided in a list.
None
rows
int | list[int] | None
In conjunction with columns=, we can specify which of their rows should undergo formatting. The default is all rows, resulting in all rows in targeted columns being formatted. Alternatively, we can supply a list of row indices.
None
case
str
Should Roman numerals should be rendered as uppercase ("upper") or lowercase ("lower") letters? By default, this is set to "upper".
'upper'
pattern
str
A formatting pattern that allows for decoration of the formatted value. The formatted value is represented by the {x} (which can be used multiple times, if needed) and all other characters will be interpreted as string literals.
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Examples
Let’s first create a DataFrame containing small numeric values and then introduce that to GT(). We’ll then format the roman column to appear as Roman numerals with the fmt_roman() method.
With numeric values in a table, we can perform formatting so that the targeted values are rendered in scientific notation, where extremely large or very small numbers can be expressed in a more practical fashion. Here, numbers are written in the form of a mantissa (m) and an exponent (n) with the construction m x 10^n or mEn. The mantissa component is a number between 1 and 10. For instance, 2.5 x 10^9 can be used to represent the value 2,500,000,000 in scientific notation. In a similar way, 0.00000012 can be expressed as 1.2 x 10^-7. Due to its ability to describe numbers more succinctly and its ease of calculation, scientific notation is widely employed in scientific and technical domains.
We have fine control over the formatting task, with the following options:
decimals: choice of the number of decimal places, option to drop trailing zeros, and a choice of the decimal symbol
scaling: we can choose to scale targeted values by a multiplier value
pattern: option to use a text pattern for decoration of the formatted values
locale-based formatting: providing a locale ID will result in formatting specific to the chosen locale
Parameters
Name
Type
Description
Default
columns
SelectExpr
The columns to target. Can either be a single column name or a series of column names provided in a list.
None
rows
int | list[int] | None
In conjunction with columns=, we can specify which of their rows should undergo formatting. The default is all rows, resulting in all rows in targeted columns being formatted. Alternatively, we can supply a list of row indices.
None
decimals
int
The decimals values corresponds to the exact number of decimal places to use. A value such as 2.34 can, for example, be formatted with 0 decimal places and it would result in "2". With 4 decimal places, the formatted value becomes "2.3400". The trailing zeros can be removed with drop_trailing_zeros=True.
2
n_sigfig
int | None
A option to format numbers to n significant figures. By default, this is None and thus number values will be formatted according to the number of decimal places set via decimals. If opting to format according to the rules of significant figures, n_sigfig must be a number greater than or equal to 1. Any values passed to the decimals and drop_trailing_zeros arguments will be ignored.
None
drop_trailing_zeros
bool
A boolean value that allows for removal of trailing zeros (those redundant zeros after the decimal mark).
False
drop_trailing_dec_mark
bool
A boolean value that determines whether decimal marks should always appear even if there are no decimal digits to display after formatting (e.g., 23 becomes 23. if False). By default trailing decimal marks are not shown.
True
scale_by
float
All numeric values will be multiplied by the scale_by value before undergoing formatting. Since the default value is 1, no values will be changed unless a different multiplier value is supplied.
1
exp_style
str
Style of formatting to use for the scientific notation formatting. By default this is "x10n" but other options include using a single letter (e.g., "e", "E", etc.), a letter followed by a "1" to signal a minimum digit width of one, or "low-ten" for using a stylized "10" marker.
'x10n'
pattern
str
A formatting pattern that allows for decoration of the formatted value. The formatted value is represented by the {x} (which can be used multiple times, if needed) and all other characters will be interpreted as string literals.
'{x}'
sep_mark
str
The string to use as a separator between groups of digits. For example, using sep_mark="," with a value of 1000 would result in a formatted value of "1,000". This argument is ignored if a locale is supplied (i.e., is not None).
','
dec_mark
str
The string to be used as the decimal mark. For example, using dec_mark="," with the value 0.152 would result in a formatted value of "0,152"). This argument is ignored if a locale is supplied (i.e., is not None).
'.'
force_sign_m
bool
Should the plus sign be shown for positive values of the mantissa (first component)? This would effectively show a sign for all values except zero on the first numeric component of the notation. If so, use True (the default for this is False), where only negative numbers will display a sign.
False
force_sign_n
bool
Should the plus sign be shown for positive values of the exponent (second component)? This would effectively show a sign for all values except zero on the second numeric component of the notation. If so, use True (the default for this is False), where only negative numbers will display a sign.
False
locale
str | None
An optional locale identifier that can be used for formatting values according the locale’s rules. Examples include "en" for English (United States) and "fr" for French (France).
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Adapting Output To A Specific Locale
This formatting method can adapt outputs according to a provided locale value. Examples include "en" for English (United States) and "fr" for French (France). The use of a valid locale ID here means separator and decimal marks will be correct for the given locale. Should any values be provided in sep_mark or dec_mark, they will be overridden by the locale’s preferred values.
Note that a locale value provided here will override any global locale setting performed in GT()’s own locale argument (it is settable there as a value received by all other methods that have a locale argument).
Examples
For this example, we’ll use the exibble dataset as the input table. With the fmt_scientific() method, we’ll format the num column to contain values in scientific formatting.
from great_tables import GT, exibble( GT(exibble) .fmt_scientific(columns="num"))
num
char
fctr
date
time
datetime
currency
row
group
1.11 × 10−1
apricot
one
2015-01-15
13:35
2018-01-01 02:22
49.95
row_1
grp_a
2.22
banana
two
2015-02-15
14:40
2018-02-02 14:33
17.95
row_2
grp_a
3.33 × 101
coconut
three
2015-03-15
15:45
2018-03-03 03:44
1.39
row_3
grp_a
4.44 × 102
durian
four
2015-04-15
16:50
2018-04-04 15:55
65100.0
row_4
grp_a
5.55 × 103
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
7.77 × 105
grapefruit
seven
19:10
2018-07-07 05:22
row_7
grp_b
8.88 × 106
honeydew
eight
2015-08-15
20:20
0.44
row_8
grp_b
See Also
The functional version of this method, val_fmt_scientific(), allows you to format a single numerical value (or a list of them).
Format input values to time values using one of 5 preset time styles. Input can be in the form of time values, or strings in the ISO 8601 forms of HH:MM:SS or YYYY-MM-DD HH:MM:SS.
Parameters
Name
Type
Description
Default
columns
SelectExpr
The columns to target. Can either be a single column name or a series of column names provided in a list.
None
rows
int | list[int] | None
In conjunction with columns=, we can specify which of their rows should undergo formatting. The default is all rows, resulting in all rows in targeted columns being formatted. Alternatively, we can supply a list of row indices.
None
time_style
TimeStyle
The time style to use. By default this is the short name "iso" which corresponds to how times are formatted within ISO 8601 datetime values. There are 5 time styles in total and their short names can be viewed using info_time_style().
'iso'
pattern
str
A formatting pattern that allows for decoration of the formatted value. The formatted value is represented by the {x} (which can be used multiple times, if needed) and all other characters will be interpreted as string literals.
'{x}'
locale
str | None
An optional locale identifier that can be used for formatting values according the locale’s rules. Examples include "en" for English (United States) and "fr" for French (France).
None
Formatting With The Time_Style Argument
We need to supply a preset time style to the time_style argument. The time styles are numerous and can handle localization to any supported locale. The following table provides a listing of all time styles and their output values (corresponding to an input time of 14:35:00).
Time Style
Output
Notes
1
"iso"
"14:35:00"
ISO 8601, 24h
2
"iso-short"
"14:35"
ISO 8601, 24h
3
"h_m_s_p"
"2:35:00 PM"
12h
4
"h_m_p"
"2:35 PM"
12h
5
"h_p"
"2 PM"
12h
We can use the info_time_style() function within the console to view a similar table of time styles with example output.
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Adapting Output To A Specific Locale
This formatting method can adapt outputs according to a provided locale value. Examples include "en" for English (United States) and "fr" for French (France). Note that a locale value provided here will override any global locale setting performed in GT()’s own locale argument (it is settable there as a value received by all other methods that have a locale argument).
Examples
Let’s use the exibble dataset to create a simple, two-column table (keeping only the date and time columns). With the fmt_time() method, we’ll format the time column to display times formatted with the "h_m_s_p" time style.
The fmt_units() method lets you better format measurement units in the table body. These must conform to the Great Tablesunits notation; as an example of this, "J Hz^-1 mol^-1" can be used to generate units for the molar Planck constant. The notation here provides several conveniences for defining units, so as long as the values to be formatted conform to this syntax, you’ll obtain nicely-formatted inline units. Details pertaining to units notation can be found in the section entitled How to use units notation.
Parameters
Name
Type
Description
Default
columns
SelectExpr
The columns to target. Can either be a single column name or a series of column names provided in a list.
None
rows
int | list[int] | None
In conjunction with columns=, we can specify which of their rows should undergo formatting. The default is all rows, resulting in all rows in targeted columns being formatted. Alternatively, we can supply a list of row indices.
None
pattern
str
A formatting pattern that allows for decoration of the formatted value. The formatted value is represented by the {x} (which can be used multiple times, if needed) and all other characters will be interpreted as string literals.
'{x}'
How To Use Units Notation
The Great Tables units notation involves a shorthand of writing units that feels familiar and is fine-tuned for the task at hand. Each unit is treated as a separate entity (parentheses and other symbols included) and the addition of subscript text and exponents is flexible and relatively easy to formulate. This is all best shown with examples:
"m/s" and "m / s" both render as "m/s"
"m s^-1" will appear with the "-1" exponent intact
"m /s" gives the the same result, as "/<unit>" is equivalent to "<unit>^-1"
"E_h" will render an "E" with the "h" subscript
"t_i^2.5" provides a t with an "i" subscript and a "2.5" exponent
"m[_0^2]" will use overstriking to set both scripts vertically
"g/L %C6H12O6%" uses a chemical formula (enclosed in a pair of "%" characters) as a unit partial, and the formula will render correctly with subscripted numbers
Common units that are difficult to write using ASCII text may be implicitly converted to the correct characters (e.g., the "u" in "ug", "um", "uL", and "umol" will be converted to the Greek mu symbol; "degC" and "degF" will render a degree sign before the temperature unit)
We can transform shorthand symbol/unit names enclosed in ":" (e.g., ":angstrom:", ":ohm:", etc.) into proper symbols
Greek letters can added by enclosing the letter name in ":"; you can use lowercase letters (e.g., ":beta:", ":sigma:", etc.) and uppercase letters too (e.g., ":Alpha:", ":Zeta:", etc.)
The components of a unit (unit name, subscript, and exponent) can be fully or partially italicized/emboldened by surrounding text with "*" or "**"
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Examples
Let’s use the illness dataset and create a new table. The units column happens to contain string values in units notation (e.g., "x10^9 / L"). Using the fmt_units() method here will improve the formatting of those measurement units.
The constants dataset contains values for hundreds of fundamental physical constants. We’ll take a subset of values that have some molar basis and generate a new display table from that. Like the illness dataset, this one has a units column so, again, the fmt_units() method will be used to format those units. Here, the preference for typesetting measurement units is to have positive and negative exponents (e.g., not "<unit_1> / <unit_2>" but rather "<unit_1> <unit_2>^-1").
from great_tables.data import constantsimport polars as plimport polars.selectors as csconstants_mini = ( pl.from_pandas(constants) .filter(pl.col("name").str.contains("molar")).sort("value") .with_columns( name=pl.col("name") .str.to_titlecase() .str.replace("Kpa", "kpa") .str.replace("Of", "of") ))( GT(constants_mini) .cols_hide(columns=["uncert", "sf_value", "sf_uncert"]) .fmt_units(columns="units") .fmt_scientific(columns="value", decimals=3) .tab_header(title="Physical Constants Having a Molar Basis") .tab_options(column_labels_hidden=True))
Physical Constants Having a Molar Basis
Molar Planck Constant
3.990 × 10−10
J Hz−1 mol−1
Electron Molar Mass
5.486 × 10−7
kg mol−1
Molar Volume of Silicon
1.206 × 10−5
m3 mol−1
Muon Molar Mass
1.134 × 10−4
kg mol−1
Molar Mass Constant
1.000 × 10−3
kg mol−1
Proton Molar Mass
1.007 × 10−3
kg mol−1
Neutron Molar Mass
1.009 × 10−3
kg mol−1
Tau Molar Mass
1.908 × 10−3
kg mol−1
Deuteron Molar Mass
2.014 × 10−3
kg mol−1
Helion Molar Mass
3.015 × 10−3
kg mol−1
Triton Molar Mass
3.016 × 10−3
kg mol−1
Alpha Particle Molar Mass
4.002 × 10−3
kg mol−1
Molar Mass of Carbon-12
1.200 × 10−2
kg mol−1
Molar Volume of Ideal Gas (273.15 K, 101.325 kpa)
2.241 × 10−2
m3 mol−1
Molar Volume of Ideal Gas (273.15 K, 100 kpa)
2.271 × 10−2
m3 mol−1
Molar Gas Constant
8.314
J mol−1 K−1
See Also
The define_units() function can be used as a standalone utility for working with units notation. It can parses strings in units notation and can emit formatted units with its .to_html() method.
opt_align_table_header
GT.opt_align_table_header(self, align='center')
Option to align the table header.
By default, an added table header will have center alignment for both the title and the subtitle elements. This method allows us to easily set the horizontal alignment of the title and subtitle to the left, right, or center by using the "align" argument. This method serves as a convenient shortcut for gt.tab_options(heading_align=<align>).
Parameters
Name
Type
Description
Default
align
str
The alignment of the title and subtitle elements in the table header. Options are "center" (the default), "left", or "right".
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Examples
Using select columns from the exibble dataset, let’s create a table with a number of components added. Following that, we’ll align the header contents (consisting of the title and the subtitle) to the left with the opt_align_table_header() method.
from great_tables import GT, exibble, md( GT( exibble[["num", "char", "currency", "row", "group"]], rowname_col="row", groupname_col="group" ) .tab_header( title=md("Data listing from **exibble**"), subtitle=md("`exibble` is a **Great Tables** dataset.") ) .fmt_number(columns="num") .fmt_currency(columns="currency") .tab_source_note(source_note="This is only a subset of the dataset.") .opt_align_table_header(align="left"))
Sometimes an all-capitalized look is suitable for a table. By using opt_all_caps(), we can transform characters in the column labels, the stub, and in all row groups in this way (and there’s control over which of these locations are transformed). This method serves as a convenient shortcut for tab_options(<location>_text_transform="uppercase", <location>_font_size="80%", <location>_font_weight="bolder") (for all locations selected).
Parameters
Name
Type
Description
Default
all_caps
bool
Indicates whether the text transformation to all caps should be performed (True, the default) or reset to default values (False) for the locations targeted.
True
locations
str | list[str]
Which locations should undergo this text transformation? By default it includes all of the "column_labels", the "stub", and the "row_group" locations. However, we could just choose one or two of those.
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Examples
Using select columns from the exibble dataset, let’s create a table with a number of components added. Following that, we’ll ensure that all text in the column labels, the stub, and in all row groups is transformed to all caps using the opt_all_caps() method.
from great_tables import GT, exibble, md( GT( exibble[["num", "char", "currency", "row", "group"]], rowname_col="row", groupname_col="group" ) .tab_header( title=md("Data listing from **exibble**"), subtitle=md("`exibble` is a **Great Tables** dataset.") ) .fmt_number(columns="num") .fmt_currency(columns="currency") .tab_source_note(source_note="This is only a subset of the dataset.") .opt_all_caps())
Data listing from exibble
exibble is a Great Tables dataset.
num
char
currency
grp_a
row_1
0.11
apricot
$49.95
row_2
2.22
banana
$17.95
row_3
33.33
coconut
$1.39
row_4
444.40
durian
$65,100.00
grp_b
row_5
5,550.00
$1,325.81
row_6
fig
$13.26
row_7
777,000.00
grapefruit
row_8
8,880,000.00
honeydew
$0.44
This is only a subset of the dataset.
opt_footnote_marks
GT.opt_footnote_marks(self, marks='numbers')
Option to modify the set of footnote marks Alter the footnote marks for any footnotes that may be present in the table. Either a list of marks can be provided (including Unicode characters), or, a specific keyword could be used to signify a preset sequence. This method serves as a shortcut for using tab_options(footnotes_marks=<marks>)
We can supply a list of strings will represent the series of marks. The series of footnote marks is recycled when its usage goes beyond the length of the set. At each cycle, the marks are simply doubled, tripled, and so on (e.g., * -> ** -> ***). The option exists for providing keywords for certain types of footnote marks. The keywords are
"numbers": numeric marks, they begin from 1 and these marks are not subject to recycling behavior
"letters": lowercase alphabetic marks. Same as using the gt.letters() function which produces a list of 26 lowercase letters from the Roman alphabet
"LETTERS": uppercase alphabetic marks. Same as using the gt.LETTERS() function which produces a list of 26 uppercase letters from the Roman alphabet
"standard": symbolic marks, four symbols in total
"extended": symbolic marks, extends the standard set by adding two more symbols, making six
Parameters
Name
Type
Description
Default
marks
str | list[str]
Either a list of strings that will represent the series of marks or a keyword string that represents a preset sequence of marks. The valid keywords are: "numbers" (for numeric marks), "letters" and "LETTERS" (for lowercase and uppercase alphabetic marks), "standard" (for a traditional set of four symbol marks), and "extended" (which adds two more symbols to the standard set).
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
opt_horizontal_padding
GT.opt_horizontal_padding(self, scale=1.0)
Option to scale the horizontal padding of the table.
This method allows us to scale the horizontal padding of the table by a factor of scale. The default value is 1.0 and this method serves as a convenient shortcut for gt.tab_options( heading_padding_horizontal=<new_val>, column_labels_padding_horizontal=<new_val>, data_row_padding_horizontal=<new_val>, row_group_padding_horizontal=<new_val>, source_notes_padding_horizontal=<new_val>).
Parameters
Name
Type
Description
Default
scale
float
The factor by which to scale the horizontal padding. The default value is 1.0. A value less than 1.0 will reduce the padding, and a value greater than 1.0 will increase the padding. The value must be between 0 and 3.
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Examples
Using select columns from the exibble dataset, let’s create a table with a number of components added. Following that, we’ll scale the horizontal padding of the table by a factor of 3 using the opt_horizontal_padding() method.
from great_tables import GT, exibble, mdgt_tbl = ( GT( exibble[["num", "char", "currency", "row", "group"]], rowname_col="row", groupname_col="group" ) .tab_header( title=md("Data listing from **exibble**"), subtitle=md("`exibble` is a **Great Tables** dataset.") ) .fmt_number(columns="num") .fmt_currency(columns="currency") .tab_source_note(source_note="This is only a subset of the dataset."))gt_tbl.opt_horizontal_padding(scale=3)
Data listing from exibble
exibble is a Great Tables dataset.
num
char
currency
grp_a
row_1
0.11
apricot
$49.95
row_2
2.22
banana
$17.95
row_3
33.33
coconut
$1.39
row_4
444.40
durian
$65,100.00
grp_b
row_5
5,550.00
$1,325.81
row_6
fig
$13.26
row_7
777,000.00
grapefruit
row_8
8,880,000.00
honeydew
$0.44
This is only a subset of the dataset.
The overall effect of scaling the horizontal padding is that the table will appear wider or and there will added buffer space between the table elements. The overall look of the table will be more spacious and neigboring pieces of text will be less cramped.
Let’s go the other way and scale the horizontal padding of the table by a factor of 0.5 using the opt_horizontal_padding() method.
gt_tbl.opt_horizontal_padding(scale=0.5)
Data listing from exibble
exibble is a Great Tables dataset.
num
char
currency
grp_a
row_1
0.11
apricot
$49.95
row_2
2.22
banana
$17.95
row_3
33.33
coconut
$1.39
row_4
444.40
durian
$65,100.00
grp_b
row_5
5,550.00
$1,325.81
row_6
fig
$13.26
row_7
777,000.00
grapefruit
row_8
8,880,000.00
honeydew
$0.44
This is only a subset of the dataset.
What you get in this case is more condensed text across the horizontal axis. This may not always be desired when cells consist mainly of text, but it could be useful when the table is more visual and the cells are filled with graphics or other non-textual elements.
opt_row_striping
GT.opt_row_striping(self, row_striping=True)
Option to add or remove row striping.
By default, a gt*table does not have row striping enabled. However, this method allows us to easily enable or disable striped rows in the table body. It’s a convenient shortcut for gt.tab_options(row_striping_include_table_body=<True|False>).
Parameters
Name
Type
Description
Default
row_striping
bool
A boolean that indicates whether row striping should be added or removed. Defaults to True.
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
opt_stylize
GT.opt_stylize(self, style=1, color='blue')
Stylize your table with a colorful look.
With the opt_stylize() method you can quickly style your table with a carefully curated set of background colors, line colors, and line styles. There are six styles to choose from and they largely vary in the extent of coloring applied to different table locations. Some have table borders applied, some apply darker colors to the table stub and summary sections, and, some even have vertical lines. In addition to choosing a style preset, there are six color variations that each use a range of five color tints. Each of the color tints have been fine-tuned to maximize the contrast between text and its background. There are 36 combinations of style and color to choose from. For examples of each style, see the Premade Themes section of the Get Started guide.
Parameters
Name
Type
Description
Default
style
int
Six numbered styles are available. Simply provide a number from 1 (the default) to 6 to choose a distinct look.
1
color
str
The color scheme of the table. The default value is "blue". The valid values are "blue", "cyan", "pink", "green", "red", and "gray".
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Examples
Using select columns from the exibble dataset, let’s create a table with a number of components added. Following that, we’ll apply a predefined style to the table using the opt_stylize() method.
from great_tables import GT, exibble, mdgt_tbl = ( GT( exibble[["num", "char", "currency", "row", "group"]], rowname_col="row", groupname_col="group" ) .tab_header( title=md("Data listing from **exibble**"), subtitle=md("`exibble` is a **Great Tables** dataset.") ) .fmt_number(columns="num") .fmt_currency(columns="currency") .tab_source_note(source_note="This is only a subset of the dataset.") .opt_stylize() )gt_tbl
Data listing from exibble
exibble is a Great Tables dataset.
num
char
currency
grp_a
row_1
0.11
apricot
$49.95
row_2
2.22
banana
$17.95
row_3
33.33
coconut
$1.39
row_4
444.40
durian
$65,100.00
grp_b
row_5
5,550.00
$1,325.81
row_6
fig
$13.26
row_7
777,000.00
grapefruit
row_8
8,880,000.00
honeydew
$0.44
This is only a subset of the dataset.
The table has been stylized with the default style and color. The default style is 1 and the default color is "blue". The resulting table style is a combination of color and border settings that are applied to the table.
We can modify the overall style and choose a different color theme by providing different values to the style= and color= arguments.
Options to define font choices for the entire table.
The opt_table_font() method makes it possible to define fonts used for an entire table. Any font names supplied in font= will (by default, with add=True) be placed before the names present in the existing font stack (i.e., they will take precedence). You can choose to base the font stack on those provided by the system_fonts() helper function by providing a valid keyword for a themed set of fonts. Take note that you could still have entirely different fonts in specific locations of the table. To make that possible you would need to use tab_style() in conjunction with style.text().
Parameters
Name
Type
Description
Default
font
str | list[str] | None
One or more font names available on the user system. This can be a string or a list of strings. The default value is None since you could instead opt to use stack to define a list of fonts.
None
stack
FontStackName | None
A name that is representative of a font stack (obtained via internally via the system_fonts() helper function. If provided, this new stack will replace any defined fonts and any font= values will be prepended.
None
style
str | None
An option to modify the text style. Can be one of either "normal", "italic", or "oblique".
None
weight
str | int | float | None
Option to set the weight of the font. Can be a text-based keyword such as "normal", "bold", "lighter", "bolder", or, a numeric value between 1 and 1000. Please note that typefaces have varying support for the numeric mapping of weight.
None
add
bool
Should fonts be added to the beginning of any already-defined fonts for the table? By default, this is True and is recommended since those fonts already present can serve as fallbacks when everything specified in font is not available. If a stack= value is provided, then add will automatically set to False.
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Possibilities For The Stack Argument
There are several themed font stacks available via the system_fonts() helper function. That function can be used to generate all or a segment of a list supplied to the font= argument. However, using the stack= argument with one of the 15 keywords for the font stacks available in system_fonts(), we could be sure that the typeface class will work across multiple computer systems. Any of the following keywords can be used with stack=:
"system-ui"
"transitional"
"old-style"
"humanist"
"geometric-humanist"
"classical-humanist"
"neo-grotesque"
"monospace-slab-serif"
"monospace-code"
"industrial"
"rounded-sans"
"slab-serif"
"antique"
"didone"
"handwritten"
Examples
Let’s use a subset of the sp500 dataset to create a small table. With opt_table_font() we can add some preferred font choices for modifying the text of the entire table. Here we’ll use the "Superclarendon" and "Georgia" fonts (the second font serves as a fallback).
In practice, both of these fonts are not likely to be available on all systems. The opt_table_font() method safeguards against this by prepending the fonts in the font= list to the existing font stack. This way, if both fonts are not available, the table will fall back to using the list of default table fonts. This behavior is controlled by the add= argument, which is True by default.
With the sza dataset we’ll create a two-column, eleven-row table. Within opt_table_font(), the stack= argument will be supplied with the “rounded-sans” font stack. This sets up a family of fonts with rounded, curved letterforms that should be locally available in different computing environments.
Option to wrap an outline around the entire table.
The opt_table_outline() method puts an outline of consistent style=, width=, and color= around the entire table. It’ll write over any existing outside lines so long as the width= value is larger that of the existing lines. The default value of style= ("solid") will draw a solid outline, whereas using "none" will remove any present outline.
Parameters
Name
Type
Description
Default
style
str
The style of the table outline. The default value is "solid". The valid values are "solid", "dashed", "dotted", and "none".
'solid'
width
str
The width of the table outline. The default value is "3px". The value must be in pixels and it must be an integer value.
'3px'
color
str
The color of the table outline, where the default is "#D3D3D3". The value must either a hexadecimal color code or a color name.
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Examples
Using select columns from the exibble dataset, let’s create a table with a number of components added. Following that, we’ll put an outline around the entire table using the opt_table_outline() method.
from great_tables import GT, exibble, md( GT( exibble[["num", "char", "currency", "row", "group"]], rowname_col="row", groupname_col="group" ) .tab_header( title=md("Data listing from **exibble**"), subtitle=md("`exibble` is a **Great Tables** dataset.") ) .fmt_number(columns="num") .fmt_currency(columns="currency") .tab_source_note(source_note="This is only a subset of the dataset.") .opt_table_outline())
Data listing from exibble
exibble is a Great Tables dataset.
num
char
currency
grp_a
row_1
0.11
apricot
$49.95
row_2
2.22
banana
$17.95
row_3
33.33
coconut
$1.39
row_4
444.40
durian
$65,100.00
grp_b
row_5
5,550.00
$1,325.81
row_6
fig
$13.26
row_7
777,000.00
grapefruit
row_8
8,880,000.00
honeydew
$0.44
This is only a subset of the dataset.
opt_vertical_padding
GT.opt_vertical_padding(self, scale=1.0)
Option to scale the vertical padding of the table.
This method allows us to scale the vertical padding of the table by a factor of scale. The default value is 1.0 and this method serves as a convenient shortcut for gt.tab_options(heading_padding=<new_val>, column_labels_padding=<new_val>, data_row_padding=<new_val>, row_group_padding=<new_val>, source_notes_padding=<new_val>).
Parameters
Name
Type
Description
Default
scale
float
The factor by which to scale the vertical padding. The default value is 1.0. A value less than 1.0 will reduce the padding, and a value greater than 1.0 will increase the padding. The value must be between 0 and 3.
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Examples
Using select columns from the exibble dataset, let’s create a table with a number of components added. Following that, we’ll scale the vertical padding of the table by a factor of 3 using the opt_vertical_padding() method.
from great_tables import GT, exibble, mdgt_tbl = ( GT( exibble[["num", "char", "currency", "row", "group"]], rowname_col="row", groupname_col="group" ) .tab_header( title=md("Data listing from **exibble**"), subtitle=md("`exibble` is a **Great Tables** dataset.") ) .fmt_number(columns="num") .fmt_currency(columns="currency") .tab_source_note(source_note="This is only a subset of the dataset."))gt_tbl.opt_vertical_padding(scale=3)
Data listing from exibble
exibble is a Great Tables dataset.
num
char
currency
grp_a
row_1
0.11
apricot
$49.95
row_2
2.22
banana
$17.95
row_3
33.33
coconut
$1.39
row_4
444.40
durian
$65,100.00
grp_b
row_5
5,550.00
$1,325.81
row_6
fig
$13.26
row_7
777,000.00
grapefruit
row_8
8,880,000.00
honeydew
$0.44
This is only a subset of the dataset.
Now that’s a tall table! The overall effect of scaling the vertical padding is that the table will appear taller and there will be more buffer space between the table elements. A value of 3 is pretty extreme and is likely to be too much in most cases, so, feel free to experiment with different values when looking to increase the vertical padding.
Let’s go the other way (using a value less than 1) and try to condense the content vertically with a scale factor of 0.5. This will reduce the top and bottom padding globally and make the table appear more compact.
gt_tbl.opt_vertical_padding(scale=0.5)
Data listing from exibble
exibble is a Great Tables dataset.
num
char
currency
grp_a
row_1
0.11
apricot
$49.95
row_2
2.22
banana
$17.95
row_3
33.33
coconut
$1.39
row_4
444.40
durian
$65,100.00
grp_b
row_5
5,550.00
$1,325.81
row_6
fig
$13.26
row_7
777,000.00
grapefruit
row_8
8,880,000.00
honeydew
$0.44
This is only a subset of the dataset.
A value of 0.5 provides a reasonable amount of vertical padding and the table will appear more compact. This is useful when space is limited and, in such a situation, this is a practical solution to that problem.
Produce a high-resolution image file or PDF of the table.
The output file is created by taking a screenshot of the table using a headless browser.
Parameters
Name
Type
Description
Default
file
str
The name of the file to save the image to. Accepts names ending with .png, .bmp, and other image extensions. Also accepts the extension .pdf.
required
selector
str
(NOT IMPLEMENTED) The HTML element name used to select table. Defaults to the whole table.
'table'
scale
float
The scaling factor that will be used when generating the image. Lower values decrease resolution. A scale of 2 is equivalent to doubling the width of the table in pixels. Note that higher resolution results in larger file sizes.
1.0
expand
int
(NOT IMPLEMENTED) The number of pixels to expand the screenshot by. This can be increased to capture more of the surrounding area, or decreased to capture less.
5
web_driver
WebDrivers
The webdriver to use when taking the screenshot. By default, uses Google Chrome. Supports "firefox" (Mozilla Firefox), "safari" (Apple Safari), and "edge" (Microsoft Edge). Specified browser must be installed.
'chrome'
window_size
tuple[int, int]
The size of the browser window to use when laying out the table. This shouldn’t be necessary to capture a table, but may affect the tables appearance.
(6000, 6000)
debug_port
None | int
Port number to use for debugging. By default no debugging port is opened.
None
_debug_dump
DebugDumpOptions | None
Whether the saved image should be a big browser window, with key elements outlined. This is helpful for debugging this function’s resizing, cropping heuristics. This is an internal parameter and subject to change.
None
Returns
Type
Description
None
This function does not return anything; it simply saves the image to the specified file path.
Details
We create the output file based on the HTML version of the table.
This process is facilitated by two libraries:
selenium, which is used to control the Chrome browser and take a screenshot of the table.
PIL, which is used to crop the screenshot to only include the table element of the page.
Both of these packages needs to be installed before attempting to save any table as an image file. The selenium package also requires the Chrome browser to be installed on the system.
A pip-based reinstallation of Great Tables through the following command will install these required packages:
pip install great_tables[extra]
show
GT.show(self, target='auto')
Display the table in a notebook or a web browser.
Note that this function is often unecessary in a notebook. However, it’s sometimes useful for manually triggering display within a code cell.
Parameters
Name
Type
Description
Default
target
Literal[‘auto’, ‘notebook’, ‘browser’]
Where to show the table. If “auto”, infer whether the table can be displayed inline (e.g. in a notebook), or whether a browser is needed (e.g. in a console).
'auto'
Examples
The example below when in the Great Tables documentation, should appear on the page.
from great_tables import GT, exibbleGT(exibble.head(2)).show()GT(exibble.tail(2)).show()
Wherever there is missing data (i.e., None values) customizable content may present better than the standard representation of missing values that would otherwise appear. The sub_missing() method allows for this replacement through its missing_text= argument. And by not supplying anything to missing_text=, an em dash will serve as a default indicator of missingness.
Parameters
Name
Type
Description
Default
columns
SelectExpr
The columns to target. Can either be a single column name or a series of column names provided in a list.
None
rows
int | list[int] | None
In conjunction with columns=, we can specify which of their rows should be scanned for missing values. The default is all rows, resulting in all rows in all targeted columns being considered for this substitution. Alternatively, we can supply a list of row indices.
None
missing_text
str | Text | None
The text to be used in place of missing values in the rendered table. We can optionally use the md() or html() helper functions to style the text as Markdown or to retain HTML elements in the text.
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Examples
Using a subset of the exibble dataset, let’s create a new table. The missing values in two selections of columns will be given different variations of replacement text (across two separate calls of sub_missing()).
Wherever there is numerical data that are zero in value, replacement text may be better for explanatory purposes. The sub_zero() function allows for this replacement through its zero_text= argument.
Parameters
Name
Type
Description
Default
columns
SelectExpr
The columns to target. Can either be a single column name or a series of column names provided in a list.
None
rows
int | list[int] | None
In conjunction with columns=, we can specify which of their rows should be scanned for zeros. The default is all rows, resulting in all rows in all targeted columns being considered for this substitution. Alternatively, we can supply a list of row indices.
None
zero_text
str
The text to be used in place of zero values in the rendered table. We can optionally use the md() or html() functions to style the text as Markdown or to retain HTML elements in the text.
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Examples
Let’s generate a simple table that contains an assortment of values that could potentially undergo some substitution via the sub_zero() method (i.e., there are two 0 values). The ordering of the fmt_scientific() and sub_zero() calls in the example below doesn’t affect the final result since any sub_*() method won’t interfere with the formatting of the table.
from great_tables import GTimport polars as plsingle_vals_df = pl.DataFrame( {"i": range(1, 8),"numbers": [2.75, 0, -3.2, 8, 1e-10, 0, 2.6e9] })GT(single_vals_df).fmt_scientific(columns="numbers").sub_zero()
We can add a table header to the output table that contains a title and even a subtitle with the tab_header() method. A table header is an optional table component that is positioned above the column labels. We have the flexibility to use Markdown or HTML formatting for the header’s title and subtitle with the md() and html() helper functions.
Parameters
Name
Type
Description
Default
title
str | Text
Text to be used in the table title. We can elect to use the md() and html() helper functions to style the text as Markdown or to retain HTML elements in the text.
required
subtitle
str | Text | None
Text to be used in the table subtitle. We can elect to use the md() and html() helper functions to style the text as Markdown or to retain HTML elements in the text.
None
preheader
str | list[str] | None
Optional preheader content that is rendered above the table. Can be supplied as a list of strings.
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Examples
Let’s use a small portion of the gtcars dataset to create a table. A header part can be added to the table with the tab_header() method. We’ll add a title and the optional subtitle as well. With the md() helper function, we can make sure the Markdown formatting is interpreted and transformed.
from great_tables import GT, mdfrom great_tables.data import gtcarsgtcars_mini = gtcars[["mfr", "model", "msrp"]].head(5)( GT(gtcars_mini) .tab_header( title=md("Data listing from **gtcars**"), subtitle=md("`gtcars` is an R dataset") ))
Data listing from gtcars
gtcars is an R dataset
mfr
model
msrp
Ford
GT
447000.0
Ferrari
458 Speciale
291744.0
Ferrari
458 Spider
263553.0
Ferrari
458 Italia
233509.0
Ferrari
488 GTB
245400.0
We can alternatively use the html() helper function to retain HTML elements in the text.
Modify the options available in a table. These options are named by the components, the subcomponents, and the element that can adjusted.
Parameters
Name
Type
Description
Default
container_width
str | None
The width of the table’s container. Can be specified as a single-length character with units of pixels or as a percentage. If provided as a scalar numeric value, it is assumed that the value is given in units of pixels.
None
container_height
str | None
The height of the table’s container.
None
container_overflow_x
str | None
An option to enable scrolling in the horizontal direction when the table content overflows the container dimensions. Using True (the default) means that horizontal scrolling is enabled to view the entire table in those directions. With False, the table may be clipped if the table width or height exceeds the container_width.
None
container_overflow_y
str | None
An option to enable scrolling in the vertical direction when the table content overflows. Same rules apply as for container_overflow_x; the dependency here is that of the table height (container_height).
None
table_width
str | None
The width of the table. Can be specified as a string with units of pixels or as a percentage. If provided as a numeric value, it is assumed that the value is given in units of pixels.
None
table_layout
str | None
The value for the table-layout CSS style in the HTML output context. By default, this is "fixed" but another valid option is "auto".
None
table_margin_left
str | None
The size of the margins on the left of the table within the container. Can be specified as a single-length value with units of pixels or as a percentage. If provided as a numeric value, it is assumed that the value is given in units of pixels. Using table_margin_left will overwrite any values set by table_align.
None
table_margin_right
str | None
The size of the margins on the right of the table within the container. Same rules apply as for table_margin_left. Using table_margin_right will overwrite any values set by table_align.
None
table_background_color
str | None
The background color for the table. A color name or a hexadecimal color code should be provided.
None
table_font_names
str | list[str] | None
The names of the fonts used for the table. This should be provided as a list of font names. If the first font isn’t available, then the next font is tried (and so on).
None
table_font_size
str | None
The font size for the table. Can be specified as a string with units of pixels or as a percentage. If provided as a numeric value, it is assumed that the value is given in units of pixels.
None
table_font_weight
str | int | float | None
The font weight of the table. Can be a text-based keyword such as "normal", "bold", "lighter", "bolder", or, a numeric value between 1 and 1000, inclusive. Note that only variable fonts may support the numeric mapping of weight.
None
table_font_style
str | None
The font style for the table. Can be one of either "normal", "italic", or "oblique".
None
table_font_color
str | None
The text color used throughout the table. A color name or a hexadecimal color code should be provided.
None
table_font_color_light
str | None
The text color used throughout the table when the background color is dark. A color name or a hexadecimal color code should be provided.
None
table_border_top_style
str | None
The style of the table’s absolute top border. Can be one of either "solid", "dotted", "dashed", "double", "groove", "ridge", "inset", or "outset".
None
table_border_top_width
str | None
The width of the table’s absolute top border. Can be specified as a string with units of pixels or as a percentage. If provided as a numeric value, it is assumed that the value is given in units of pixels.
None
table_border_top_color
str | None
The color of the table’s absolute top border. A color name or a hexadecimal color code should be provided.
None
table_border_bottom_style
str | None
The style of the table’s absolute bottom border.
None
table_border_bottom_width
str | None
The width of the table’s absolute bottom border.
None
table_border_bottom_color
str | None
The color of the table’s absolute bottom border.
None
table_border_left_style
str | None
The style of the table’s absolute left border.
None
table_border_left_width
str | None
The width of the table’s absolute left border.
None
table_border_left_color
str | None
The color of the table’s absolute left border.
None
table_border_right_style
str | None
The style of the table’s absolute right border.
None
table_border_right_width
str | None
The width of the table’s absolute right border.
None
table_border_right_color
str | None
The color of the table’s absolute right border.
None
heading_background_color
str | None
The background color for the heading. A color name or a hexadecimal color code should be provided.
None
heading_align
str | None
Controls the horizontal alignment of the heading title and subtitle. We can either use "center", "left", or "right".
None
heading_title_font_size
str | None
The font size for the heading title element.
None
heading_title_font_weight
str | int | float | None
The font weight of the heading title.
None
heading_subtitle_font_size
str | None
The font size for the heading subtitle element.
None
heading_subtitle_font_weight
str | int | float | None
The font weight of the heading subtitle.
None
heading_padding
str | None
The amount of vertical padding to incorporate in the heading (title and subtitle). Can be specified as a string with units of pixels or as a percentage. If provided as a numeric value, it is assumed that the value is given in units of pixels.
None
heading_padding_horizontal
str | None
The amount of horizontal padding to incorporate in the heading (title and subtitle). Can be specified as a string with units of pixels or as a percentage. If provided as a numeric value, it is assumed that the value is given in units of pixels.
None
heading_border_bottom_style
str | None
The style of the header’s bottom border.
None
heading_border_bottom_width
str | None
The width of the header’s bottom border. If the width of this border is larger, then it will be the visible border.
None
heading_border_bottom_color
str | None
The color of the header’s bottom border.
None
heading_border_lr_style
str | None
The style of the left and right borders of the heading location.
None
heading_border_lr_width
str | None
The width of the left and right borders of the heading location. If the width of this border is larger, then it will be the visible border.
None
heading_border_lr_color
str | None
The color of the left and right borders of the heading location.
None
column_labels_background_color
str | None
The background color for the column labels. A color name or a hexadecimal color code should be provided.
None
column_labels_font_size
str | None
The font size to use for all column labels.
None
column_labels_font_weight
str | int | float | None
The font weight of the table’s column labels.
None
column_labels_text_transform
str | None
The text transformation for the column labels. Either of the "uppercase", "lowercase", or "capitalize" keywords can be used.
None
column_labels_padding
str | None
The amount of vertical padding to incorporate in the column_labels (this includes the column spanners).
None
column_labels_padding_horizontal
str | None
The amount of horizontal padding to incorporate in the column_labels (this includes the column spanners).
None
column_labels_vlines_style
str | None
The style of all vertical lines (‘vlines’) of the column_labels.
None
column_labels_vlines_width
str | None
The width of all vertical lines (‘vlines’) of the column_labels.
None
column_labels_vlines_color
str | None
The color of all vertical lines (‘vlines’) of the column_labels.
None
column_labels_border_top_style
str | None
The style of the top border of the column_labels location.
None
column_labels_border_top_width
str | None
The width of the top border of the column_labels location. If the width of this border is larger, then it will be the visible border.
None
column_labels_border_top_color
str | None
The color of the top border of the column_labels location.
None
column_labels_border_bottom_style
str | None
The style of the bottom border of the column_labels location.
None
column_labels_border_bottom_width
str | None
The width of the bottom border of the column_labels location. If the width of this border is larger, then it will be the visible border.
None
column_labels_border_bottom_color
str | None
The color of the bottom border of the column_labels location.
None
column_labels_border_lr_style
str | None
The style of the left and right borders of the column_labels location.
None
column_labels_border_lr_width
str | None
The width of the left and right borders of the column_labels location. If the width of this border is larger, then it will be the visible border.
None
column_labels_border_lr_color
str | None
The color of the left and right borders of the column_labels location.
None
column_labels_hidden
bool | None
An option to hide the column labels. If providing True then the entire column_labels location won’t be seen and the table header (if present) will collapse downward.
None
row_group_background_color
str | None
The background color for the row group labels. A color name or a hexadecimal color code should be provided.
None
row_group_font_weight
str | int | float | None
The font weight for all row group labels present in the table.
None
row_group_font_size
str | None
The font size to use for all row group labels.
None
row_group_padding
str | None
The amount of vertical padding to incorporate in the row group labels.
None
row_group_border_top_style
str | None
The style of the top border of the row_group location.
None
row_group_border_top_width
str | None
The width of the top border of the row_group location. If the width of this border is larger, then it will be the visible border.
None
row_group_border_top_color
str | None
The color of the top border of the row_group location.
None
row_group_border_bottom_style
str | None
The style of the bottom border of the row_group location.
None
row_group_border_bottom_width
str | None
The width of the bottom border of the row_group location. If the width of this border is larger, then it will be the visible border.
None
row_group_border_bottom_color
str | None
The color of the bottom border of the row_group location.
None
row_group_border_left_style
str | None
The style of the left border of the row_group location.
None
row_group_border_left_width
str | None
The width of the left border of the row_group location. If the width of this border is larger, then it will be the visible border.
None
row_group_border_left_color
str | None
The color of the left border of the row_group location.
None
row_group_border_right_style
str | None
The style of the right border of the row_group location.
None
row_group_border_right_width
str | None
The width of the right border of the row_group location. If the width of this border is
None
row_group_border_right_color
str | None
The color of the right border of the row_group location.
None
row_group_as_column
bool | None
An option to render the row group labels as a column. If True, then the row group labels will be rendered as a column to the left of the table body. If False, then the row group labels will be rendered as a separate row above the grouping of rows.
None
table_body_hlines_style
str | None
The style of all horizontal lines (‘hlines’) in the table_body.
None
table_body_hlines_width
str | None
The width of all horizontal lines (‘hlines’) in the table_body.
None
table_body_hlines_color
str | None
The color of all horizontal lines (‘hlines’) in the table_body.
None
table_body_vlines_style
str | None
The style of all vertical lines (‘vlines’) in the table_body.
None
table_body_vlines_width
str | None
The width of all vertical lines (‘vlines’) in the table_body.
None
table_body_vlines_color
str | None
The color of all vertical lines (‘vlines’) in the table_body.
None
table_body_border_top_style
str | None
The style of the top border of the table_body location.
None
table_body_border_top_width
str | None
The width of the top border of the table_body location. If the width of this border is larger, then it will be the visible border.
None
table_body_border_top_color
str | None
The color of the top border of the table_body location.
None
table_body_border_bottom_style
str | None
The style of the bottom border of the table_body location.
None
table_body_border_bottom_width
str | None
The width of the bottom border of the table_body location. If the width of this border
None
table_body_border_bottom_color
str | None
The color of the bottom border of the table_body location.
None
stub_background_color
str | None
The background color for the stub. A color name or a hexadecimal color code should be provided.
None
stub_font_size
str | None
The font size to use for all row labels present in the table stub.
None
stub_font_weight
str | int | float | None
The font weight for all row labels present in the table stub.
None
stub_text_transform
str | None
The text transformation for the row labels present in the table stub.
None
stub_border_style
str | None
The style of the vertical border of the table stub.
None
stub_border_width
str | None
The width of the vertical border of the table stub.
None
stub_border_color
str | None
The color of the vertical border of the table stub.
None
stub_row_group_font_size
str | None
The font size for the row group column in the stub.
None
stub_row_group_font_weight
str | int | float | None
The font weight for the row group column in the stub.
None
stub_row_group_text_transform
str | None
The text transformation for the row group column in the stub.
None
stub_row_group_border_style
str | None
The style of the vertical border of the row group column in the stub.
None
stub_row_group_border_width
str | None
The width of the vertical border of the row group column in the stub.
None
stub_row_group_border_color
str | None
The color of the vertical border of the row group column in the stub.
None
data_row_padding
str | None
The amount of vertical padding to incorporate in the body/stub rows.
None
data_row_padding_horizontal
str | None
The amount of horizontal padding to incorporate in the body/stub rows.
None
source_notes_background_color
str | None
The background color for the source notes. A color name or a hexadecimal color code should be provided.
None
source_notes_font_size
str | None
The font size to use for all source note text.
None
source_notes_padding
str | None
The amount of vertical padding to incorporate in the source notes.
None
source_notes_padding_horizontal
str | None
The amount of horizontal padding to incorporate in the source notes.
None
source_notes_multiline
bool | None
An option to either put source notes in separate lines (the default, or True) or render them as a continuous line of text with source_notes_sep providing the separator (by default " ") between notes.
None
source_notes_sep
str | None
The separating characters between adjacent source notes when rendered as a continuous line of text (when source_notes_multiline is False). The default value is a single space character (" ").
None
source_notes_border_bottom_style
str | None
The style of the bottom border of the source_notes location.
None
source_notes_border_bottom_width
str | None
The width of the bottom border of the source_notes location. If the width of this border is larger, then it will be the visible border.
None
source_notes_border_bottom_color
str | None
The color of the bottom border of the source_notes location.
None
source_notes_border_lr_style
str | None
The style of the left and right borders of the source_notes location.
None
source_notes_border_lr_width
str | None
The width of the left and right borders of the source_notes location. If the width of this border is larger, then it will be the visible border.
None
source_notes_border_lr_color
str | None
The color of the left and right borders of the source_notes location.
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Examples
Using select columns from the exibble dataset, let’s create a new table with a number of table components added. We can use this object going forward to demonstrate some of the features available in the tab_options() method.
from great_tables import GT, exibble, mdgt_tbl = ( GT( exibble[["num", "char", "currency", "row", "group"]], rowname_col="row", groupname_col="group" ) .tab_header( title=md("Data listing from **exibble**"), subtitle=md("`exibble` is a **Great Tables** dataset.") ) .fmt_number(columns="num") .fmt_currency(columns="currency") .tab_source_note(source_note="This is only a subset of the dataset."))gt_tbl
Data listing from exibble
exibble is a Great Tables dataset.
num
char
currency
grp_a
row_1
0.11
apricot
$49.95
row_2
2.22
banana
$17.95
row_3
33.33
coconut
$1.39
row_4
444.40
durian
$65,100.00
grp_b
row_5
5,550.00
$1,325.81
row_6
fig
$13.26
row_7
777,000.00
grapefruit
row_8
8,880,000.00
honeydew
$0.44
This is only a subset of the dataset.
We can modify the table width to be set as "100%“. In effect, this spans the table to entirely fill the content width area. This is done with the table_width option.
gt_tbl.tab_options(table_width="100%")
Data listing from exibble
exibble is a Great Tables dataset.
num
char
currency
grp_a
row_1
0.11
apricot
$49.95
row_2
2.22
banana
$17.95
row_3
33.33
coconut
$1.39
row_4
444.40
durian
$65,100.00
grp_b
row_5
5,550.00
$1,325.81
row_6
fig
$13.26
row_7
777,000.00
grapefruit
row_8
8,880,000.00
honeydew
$0.44
This is only a subset of the dataset.
With the table_background_color option, we can modify the table’s background color. Here, we want that to be "lightcyan".
The data rows of a table typically take up the most physical space but we have some control over the extent of that. With the data_row_padding option, it’s possible to modify the top and bottom padding of data rows. We’ll do just that in the following example, reducing the padding to a value of "3px".
gt_tbl.tab_options(data_row_padding="3px")
Data listing from exibble
exibble is a Great Tables dataset.
num
char
currency
grp_a
row_1
0.11
apricot
$49.95
row_2
2.22
banana
$17.95
row_3
33.33
coconut
$1.39
row_4
444.40
durian
$65,100.00
grp_b
row_5
5,550.00
$1,325.81
row_6
fig
$13.26
row_7
777,000.00
grapefruit
row_8
8,880,000.00
honeydew
$0.44
This is only a subset of the dataset.
The size of the title and the subtitle text in the header of the table can be altered with the heading_title_font_size and heading_subtitle_font_size options. Here, we’ll use the "small" and "x-small" keyword values.
Add a source note to the footer part of the table. A source note is useful for citing the data included in the table. Several can be added to the footer, simply use the tab_source_note() method multiple times and they will be inserted in the order provided. We can use Markdown formatting for the note, or, if the table is intended for HTML output, we can include HTML formatting.
Parameters
Name
Type
Description
Default
source_note
str | Text
Text to be used in the source note. We can optionally use the md() or html() helper functions to style the text as Markdown or to retain HTML elements in the text.
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Examples
With three columns from the gtcars dataset, let’s create a new table. We can use the tab_source_note() method to add a source note to the table footer. Here we are citing the data source but this method can be used for any text you’d prefer to display in the footer component of the table.
Insert a spanner above a selection of column headings.
This part of the table contains, at a minimum, column labels and, optionally, an unlimited number of levels for spanners. A spanner will occupy space over any number of contiguous column labels and it will have an associated label and ID value. This method allows for mapping to be defined by column names, existing spanner ID values, or a mixture of both.
The spanners are placed in the order of calling tab_spanner() so if a later call uses the same columns in its definition (or even a subset) as the first invocation, the second spanner will be overlaid atop the first. Options exist for forcibly inserting a spanner underneath others (with level as space permits) and with replace, which allows for full or partial spanner replacement.
Parameters
Name
Type
Description
Default
label
str | Text
The text to use for the spanner label. We can optionally use the md() and html() helper functions to style the text as Markdown or to retain HTML elements in the text. Alternatively, units notation can be used (see define_units() for details).
required
columns
SelectExpr
The columns to target. Can either be a single column name or a series of column names provided in a list.
None
spanners
str | list[str] | None
The spanners that should be spanned over, should they already be defined. One or more spanner ID values (in quotes) can be supplied here. This argument works in tandem with the columns argument.
None
level
int | None
An explicit level to which the spanner should be placed. If not provided, Great Tables will choose the level based on the inputs provided within columns and spanners, placing the spanner label where it will fit. The first spanner level (right above the column labels) is 0.
None
id
str | None
The ID for the spanner. When accessing a spanner through the spanners argument of tab_spanner() the id value is used as the reference (and not the label). If an id is not explicitly provided here, it will be taken from the label value. It is advisable to set an explicit id value if you plan to access this cell in a later call and the label text is complicated (e.g., contains markup, is lengthy, or both). Finally, when providing an id value you must ensure that it is unique across all ID values set for spanner labels (the method will throw an error if id isn’t unique).
None
gather
bool
An option to move the specified columns such that they are unified under the spanner. Ordering of the moved-into-place columns will be preserved in all cases. By default, this is set to True.
True
replace
bool
Should new spanners be allowed to partially or fully replace existing spanners? (This is a possibility if setting spanners at an already populated level.) By default, this is set to False and an error will occur if some replacement is attempted.
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Examples
Let’s create a table using a small portion of the gtcars dataset. Over several columns (hp, hp_rpm, trq, trq_rpm, mpg_c, mpg_h) we’ll use tab_spanner() to add a spanner with the label "performance". This effectively groups together several columns related to car performance under a unifying label.
Add a label to the stubhead of a table. The stubhead is the lone element that is positioned left of the column labels, and above the stub. If a stub does not exist, then there is no stubhead (so no change will be made when using this method in that case). We have the flexibility to use Markdown formatting for the stubhead label (through use of the md() helper function). Furthermore, we can use HTML for the stubhead label so long as we also use the html() helper function.
Parameters
Name
Type
Description
Default
label
str | Text
The text to be used as the stubhead label. We can optionally use the md() and html() helper functions to style the text as Markdown or to retain HTML elements in the text.
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Examples
Using a small subset of the gtcars dataset, we can create a table with row labels. Since we have row labels in the stub (via use of rowname_col="model" in the GT() call) we have a stubhead, so, let’s add a stubhead label ("car") with the tab_stubhead() method to describe what’s in the stub.
With the tab_style() method we can target specific cells and apply styles to them. We do this with the combination of the style and location arguments. The style argument requires use of styling classes (e.g., style.fill(color="red")) and the location argument needs to be an expression of the cells we want to target using location targeting classes (e.g., loc.body(columns=<column_name>)). With the available suite of styling classes, here are some of the styles we can apply:
the background color of the cell (style.fill()’s color)
the cell’s text color, font, and size (style.text()’s color, font, and size)
the text style (style.text()’s style), enabling the use of italics or oblique text.
the text weight (style.text()’s weight), allowing the use of thin to bold text (the degree of choice is greater with variable fonts)
the alignment of text (style.text()’s align)
cell borders with the style.borders() class
Parameters
Name
Type
Description
Default
style
CellStyle | list[CellStyle]
The styles to use for the cells at the targeted locations. The style.text(), style.fill(), and style.borders() classes can be used here to more easily generate valid styles.
required
locations
Loc | list[Loc]
The cell or set of cells to be associated with the style. The loc.body() class can be used here to easily target body cell locations.
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
Examples
Let’s use a small subset of the exibble dataset to demonstrate how to use tab_style() to target specific cells and apply styles to them. We’ll start by creating the exibble_sm table (a subset of the exibble table) and then use tab_style() to apply a light cyan background color to the cells in the num column for the first two rows of the table. We’ll then apply a larger font size to the cells in the fctr column for the last four rows of the table.
Let’s use exibble once again to create a simple, two-column output table (keeping only the num and currency columns). With the tab_style() method (called thrice), we’ll add style to the values already formatted by fmt_number() and fmt_currency(). In the style argument of the first two tab_style() call, we can define multiple types of styling with the style.fill() and style.text() classes (enclosing these in a list). The cells to be targeted for styling require the use of loc.body(), which is used here with different columns being targeted. For the final tab_style() call, we demonstrate the use of style.borders() class as the style argument, which is employed in conjunction with loc.body() to locate the row to be styled.
Note that this is a shortcut for the table_id= argument in GT.tab_options().
with_locale
GT.with_locale(self, locale=None)
Set a column to be the default locale.
Setting a default locale affects formatters like .fmt_number, and .fmt_date, by having them default to locale-specific features (e.g. representing one thousand as 1.000,00)
