diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 98be15cc1..344e9a837 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -34,19 +34,24 @@ website: - get-started/basic-header.qmd - get-started/basic-stub.qmd - get-started/basic-column-labels.qmd - - section: Format and Style + - section: Format contents: - get-started/basic-formatting.qmd + - get-started/nanoplots.qmd + - section: Style + contents: - get-started/basic-styling.qmd + - get-started/targeted-styles.qmd - get-started/colorizing-with-data.qmd + - section: Theming + contents: - get-started/table-theme-options.qmd - get-started/table-theme-premade.qmd - - section: Extra Topics + - section: Selecting table parts contents: - get-started/column-selection.qmd - get-started/row-selection.qmd - - get-started/nanoplots.qmd - - get-started/targeted-styles.qmd + - get-started/loc-selection.qmd format: html: diff --git a/docs/get-started/basic-styling.qmd b/docs/get-started/basic-styling.qmd index 1e1d9c713..2d0bbae32 100644 --- a/docs/get-started/basic-styling.qmd +++ b/docs/get-started/basic-styling.qmd @@ -1,5 +1,5 @@ --- -title: Stying the Table Body +title: Styling the Table Body jupyter: python3 html-table-processing: none --- diff --git a/docs/get-started/loc-selection.qmd b/docs/get-started/loc-selection.qmd new file mode 100644 index 000000000..31e2c03b3 --- /dev/null +++ b/docs/get-started/loc-selection.qmd @@ -0,0 +1,179 @@ +--- +title: Location selection +jupyter: python3 +--- + +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. + +```{python} +# | echo: false +import polars as pl +from great_tables import GT + +data = [ + ["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()", ""], +] + +df = pl.DataFrame(data, schema=["table part", "name", "selection"], orient="row") + +GT(df) +``` + +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). + +```{python} +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 +``` + +## Simple locations + +Simple locations don't take any arguments. + +For example, styling the title uses `loc.title()`. + +```{python} +( + GT(pl_exibble) + .tab_header("A title", "A subtitle") + .tab_style( + style.fill("yellow"), + loc.title(), + ) +) +``` + +## Composite locations + +Composite locations target multiple simple locations. + +For example, `loc.header()` includes both `loc.title()` and `loc.subtitle()`. + +```{python} +( + GT(pl_exibble) + .tab_header("A title", "A subtitle") + .tab_style( + style.fill("yellow"), + loc.header(), + ) +) +``` + +## Body columns and rows + +Use `loc.body()` to style specific cells in the table body. + +```{python} +( + GT(pl_exibble).tab_style( + style.fill("yellow"), + loc.body( + columns=cs.starts_with("cha"), + rows=pl.col("char").str.contains("a"), + ), + ) +) +``` + +This is discussed in detail in [Styling the Table Body](./basic-styling.qmd). + +## 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. + +```{python} +GT(pl_exibble).tab_style( + style.fill("yellow"), + loc.column_labels( + cs.starts_with("cha"), + ), +) +``` + +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 + +```{python} +gt = GT(pl_exibble).tab_stub( + rowname_col="char", + groupname_col="group", +) + +gt.tab_style(style.fill("yellow"), loc.stub()) +``` + + +```{python} +gt.tab_style(style.fill("yellow"), loc.stub("banana")) +``` + +```{python} +gt.tab_style(style.fill("yellow"), loc.stub(["apricot", 2])) +``` + +### 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. + +```{python} +gt.tab_style( + style.fill("yellow"), + loc.row_groups(1), +) +``` + +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: + +```{python} +gt.tab_style( + style.fill("yellow"), + loc.row_groups(pl.col("group") == "grp_b"), +) +``` + +You can also specify group names using a string (or list of strings). + +```{python} +gt.tab_style( + style.fill("yellow"), + loc.row_groups("grp_b"), +) +``` diff --git a/docs/get-started/table-theme-options.qmd b/docs/get-started/table-theme-options.qmd index b8ac0f693..00811d5bf 100644 --- a/docs/get-started/table-theme-options.qmd +++ b/docs/get-started/table-theme-options.qmd @@ -5,7 +5,7 @@ jupyter: python3 Great Tables exposes options to customize the appearance of tables via two methods: -* [](`~great_tables.GT.tab_style`) - targeted styles (e.g. color a specific cell of data). +* [](`~great_tables.GT.tab_style`) - targeted styles (e.g. color a specific cell of data, or a specific group label). * [](`~great_tables.GT.tab_options`) - broad styles (e.g. color the header and source notes). Both methods target parts of the table, as shown in the diagram below. @@ -14,7 +14,6 @@ Both methods target parts of the table, as shown in the diagram below. This page covers how to style and theme your table using `GT.tab_options()`, which is meant to quickly set a broad range of styles. -In the future, even more granular options will become available via `GT.tab_style()`. We'll use the basic GT object below for most examples, since it marks some of the table parts. diff --git a/docs/get-started/targeted-styles.qmd b/docs/get-started/targeted-styles.qmd index a3394ec75..2b02e4aac 100644 --- a/docs/get-started/targeted-styles.qmd +++ b/docs/get-started/targeted-styles.qmd @@ -1,5 +1,5 @@ --- -title: Targeted styles +title: Styling the whole table jupyter: python3 --- @@ -7,7 +7,7 @@ In [Styling the Table Body](./basic-styling), we discussed styling table data wi In this article we'll cover how the same method can be used to style many other parts of the table, like the header, specific spanner labels, the footer, and more. :::{.callout-warning} -This feature is currently a work in progress, and not yet released. Great Tables must be installed from github in order to try it. +This feature is new, and this page of documentation is still in development. ::: diff --git a/great_tables/_locations.py b/great_tables/_locations.py index 11c52d40f..b21b4aa21 100644 --- a/great_tables/_locations.py +++ b/great_tables/_locations.py @@ -751,6 +751,7 @@ def resolve_rows_i( data: GTData | list[str], expr: RowSelectExpr = None, null_means: Literal["everything", "nothing"] = "everything", + row_name_attr: Literal["rowname", "group_id"] = "rowname", ) -> list[tuple[str, int]]: """Return matching row numbers, based on expr @@ -766,13 +767,13 @@ def resolve_rows_i( expr: list[str | int] = [expr] if isinstance(data, GTData): - row_names = [row.rowname for row in data._stub] + row_names = [getattr(row, row_name_attr) for row in data._stub] else: row_names = data if expr is None: if null_means == "everything": - return [(row.rowname, ii) for ii, row in enumerate(data._stub)] + return [(name, ii) for ii, name in enumerate(row_names)] else: return [] @@ -844,18 +845,17 @@ def _(loc: LocSpannerLabels, spanners: Spanners) -> LocSpannerLabels: @resolve.register -def _(loc: LocColumnLabels, data: GTData) -> list[CellPos]: - cols = resolve_cols_i(data=data, expr=loc.columns) - cell_pos = [CellPos(col[1], 0, colname=col[0]) for col in cols] - return cell_pos +def _(loc: LocColumnLabels, data: GTData) -> list[tuple[str, int]]: + name_pos = resolve_cols_i(data=data, expr=loc.columns) + return name_pos @resolve.register def _(loc: LocRowGroups, data: GTData) -> set[int]: # TODO: what are the rules for matching row groups? # TODO: resolve_rows_i will match a list expr to row names (not group names) - group_pos = set(pos for _, pos in resolve_rows_i(data, loc.rows)) - return list(group_pos) + group_pos = set(name for name, _ in resolve_rows_i(data, loc.rows, row_name_attr="group_id")) + return group_pos @resolve.register @@ -939,17 +939,16 @@ def _( @set_style.register def _(loc: LocColumnLabels, data: GTData, style: list[CellStyle]) -> GTData: - positions: list[CellPos] = resolve(loc, data) + selected = resolve(loc, data) # evaluate any column expressions in styles styles = [entry._evaluate_expressions(data._tbl_data) for entry in style] all_info: list[StyleInfo] = [] - for col_pos in positions: + for name, pos in selected: crnt_info = StyleInfo( locname=loc, - colname=col_pos.colname, - rownum=col_pos.row, + colname=name, styles=styles, ) all_info.append(crnt_info) diff --git a/great_tables/_utils_render_html.py b/great_tables/_utils_render_html.py index 4abd55ec7..9bdc97fd3 100644 --- a/great_tables/_utils_render_html.py +++ b/great_tables/_utils_render_html.py @@ -479,7 +479,11 @@ def create_body_component_h(data: GTData) -> str: "gt_empty_group_heading" if group_label == "" else "gt_group_heading_row" ) - _styles = [style for style in styles_row_group_label if i in style.grpname] + _styles = [ + style + for style in styles_row_group_label + if group_info.group_id in style.grpname + ] group_styles = _flatten_styles(_styles, wrap=True) group_row = f""" {group_label} diff --git a/tests/test_locations.py b/tests/test_locations.py index cd10f7940..3dbc75d5a 100644 --- a/tests/test_locations.py +++ b/tests/test_locations.py @@ -7,7 +7,11 @@ from great_tables._locations import ( CellPos, LocBody, + LocColumnLabels, LocSpannerLabels, + LocRowGroups, + LocSpannerLabels, + LocStub, LocTitle, resolve, resolve_cols_i, @@ -176,6 +180,80 @@ def test_resolve_loc_spanner_label_error_missing(): resolve(loc, spanners) +@pytest.mark.parametrize( + "rows, res", + [ + (2, {"b"}), + ([2], {"b"}), + ("b", {"b"}), + (["a", "c"], {"a", "c"}), + ([0, 1], {"a"}), + (None, {"a", "b", "c"}), + (pl.col("group") == "b", {"b"}), + ], +) +def test_resolve_loc_row_groups(rows, res): + df = pl.DataFrame({"group": ["a", "a", "b", "c"]}) + loc = LocRowGroups(rows=rows) + new_loc = resolve(loc, GT(df, groupname_col="group")) + + assert isinstance(new_loc, set) + assert new_loc == res + + +@pytest.mark.parametrize( + "rows, res", + [ + (2, {2}), + ([2], {2}), + ("b", {2}), + (["a", "c"], {0, 1, 3}), + ([0, 1], {0, 1}), + (pl.col("row") == "a", {0, 1}), + ], +) +def test_resolve_loc_stub(rows, res): + df = pl.DataFrame({"row": ["a", "a", "b", "c"]}) + loc = LocStub(rows=rows) + new_loc = resolve(loc, GT(df, rowname_col="row")) + + assert isinstance(new_loc, set) + assert new_loc == res + + +@pytest.mark.parametrize( + "cols, res", + [ + (["b"], [("b", 1)]), + ([0, 2], [("a", 0), ("c", 2)]), + (cs.by_name("a"), [("a", 0)]), + ], +) +def test_resolve_loc_column_labels(cols, res): + df = pl.DataFrame({"a": [0], "b": [1], "c": [2]}) + loc = LocColumnLabels(columns=cols) + + selected = resolve(loc, GT(df)) + assert selected == res + + +@pytest.mark.parametrize( + "ids, res", + [ + (["b"], ["b"]), + (["a", "b"], ["a", "b"]), + pytest.param(cs.by_name("a"), ["a"], marks=pytest.mark.xfail), + ], +) +def test_resolve_loc_spanner_labels(ids, res): + df = pl.DataFrame({"x": [0], "y": [1], "z": [2]}) + gt = GT(df).tab_spanner("a", ["x", "y"]).tab_spanner("b", ["z"]) + loc = LocSpannerLabels(ids=ids) + + new_loc = resolve(loc, gt._spanners) + assert new_loc.ids == res + + @pytest.mark.parametrize( "expr", [