Location selection

Great Tables uses the loc module to specify locations for styling in tab_style(). Some location specifiers also allow selecting specific columns and rows of data.

For example, you might style a particular row name, group, column, or spanner label.

The table below shows the different location specifiers, along with the types of column or row selection they allow.

table part	name	selection
header	loc.header()	composite
	loc.title()
	loc.subtitle()
boxhead	loc.column_header()	composite
	loc.spanner_labels()	columns
	loc.column_labels()	columns
row stub	loc.stub()	rows
	loc.row_groups()	rows
table body	loc.body()	columns and rows
footer	loc.footer()	composite
	loc.source_notes()

Note that composite specifiers are ones that target multiple locations. For example, loc.header() specifies both loc.title() and loc.subtitle().

Setting up data

The examples below will use this small dataset to show selecting different locations, as well as specific rows and columns within a location (where supported).

import polars as pl
import polars.selectors as cs

from great_tables import GT, loc, style, exibble

pl_exibble = pl.from_pandas(exibble)[[0, 1, 4], ["num", "char", "group"]]

pl_exibble

shape: (3, 3)

num	char	group
f64	str	str
0.1111	"apricot"	"grp_a"
2.222	"banana"	"grp_a"
5550.0	null	"grp_b"

Simple locations

Simple locations don’t take any arguments.

For example, styling the title uses loc.title().

(
    GT(pl_exibble)
    .tab_header("A title", "A subtitle")
    .tab_style(
        style.fill("yellow"),
        loc.title(),
    )
)

num	char	group
A title
A subtitle
0.1111	apricot	grp_a
2.222	banana	grp_a
5550.0	None	grp_b

Composite locations

Composite locations target multiple simple locations.

For example, loc.header() includes both loc.title() and loc.subtitle().

(
    GT(pl_exibble)
    .tab_header("A title", "A subtitle")
    .tab_style(
        style.fill("yellow"),
        loc.header(),
    )
)

num	char	group
A title
A subtitle
0.1111	apricot	grp_a
2.222	banana	grp_a
5550.0	None	grp_b

Body columns, rows and mask

Use columns= and rows= in loc.body() to style specific cells in the table body.

(
    GT(pl_exibble).tab_style(
        style.fill("yellow"),
        loc.body(
            columns=cs.starts_with("cha"),
            rows=pl.col("char").str.contains("a"),
        ),
    )
)

num	char	group
0.1111	apricot	grp_a
2.222	banana	grp_a
5550.0	None	grp_b

Alternatively, use mask= in loc.body() to apply conditional styling to rows on a per-column basis.

(
    GT(pl_exibble).tab_style(
        style.fill("yellow"),
        loc.body(mask=cs.string().str.contains("p")),
    )
)

num	char	group
0.1111	apricot	grp_a
2.222	banana	grp_a
5550.0	None	grp_b

This is discussed in detail in Styling the Table Body.

Column labels

Locations like loc.spanner_labels() and loc.column_labels() can select specific column and spanner labels.

You can use name strings, index position, or polars selectors.

GT(pl_exibble).tab_style(
    style.fill("yellow"),
    loc.column_labels(
        cs.starts_with("cha"),
    ),
)

num	char	group
0.1111	apricot	grp_a
2.222	banana	grp_a
5550.0	None	grp_b

However, note that loc.spanner_labels() currently only accepts list of string names.

Row and group names

Row and group names in loc.stub() and loc.row_groups() may be specified three ways:

by name
by index
by polars expression

gt = GT(pl_exibble).tab_stub(
    rowname_col="char",
    groupname_col="group",
)

gt.tab_style(style.fill("yellow"), loc.stub())

	num
grp_a
apricot	0.1111
banana	2.222
grp_b
None	5550.0

gt.tab_style(style.fill("yellow"), loc.stub("banana"))

	num
grp_a
apricot	0.1111
banana	2.222
grp_b
None	5550.0

gt.tab_style(style.fill("yellow"), loc.stub(["apricot", 2]))

	num
grp_a
apricot	0.1111
banana	2.222
grp_b
None	5550.0

Groups by name and position

Note that for specifying row groups, the group corresponding to the group name or row number in the original data is used.

For example, the code below styles the group corresponding to the row at index 1 (i.e. the second row) in the data.

gt.tab_style(
    style.fill("yellow"),
    loc.row_groups(1),
)

	num
grp_a
apricot	0.1111
banana	2.222
grp_b
None	5550.0

Since the second row (starting with “banana”) is in “grp_a”, that is the group that gets styled.

This means you can use a polars expression to select groups:

gt.tab_style(
    style.fill("yellow"),
    loc.row_groups(pl.col("group") == "grp_b"),
)

	num
grp_a
apricot	0.1111
banana	2.222
grp_b
None	5550.0

You can also specify group names using a string (or list of strings).

gt.tab_style(
    style.fill("yellow"),
    loc.row_groups("grp_b"),
)

	num
grp_a
apricot	0.1111
banana	2.222
grp_b
None	5550.0