Merge pull request #484 from posit-dev/fix-locations

Fix locations: row and group selection

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:

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
 ---

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"),
+)
+```

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.
 

docs/get-started/targeted-styles.qmd

@@ -1,13 +1,13 @@
 ---
-title: Targeted styles
+title: Styling the whole table
 jupyter: python3
 ---
 
 In [Styling the Table Body](./basic-styling), we discussed styling table data with `.tab_style()`.
 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.
 :::
 
 

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)

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"""  <tr class="{group_class}">
     <th class="gt_group_heading" colspan="{colspan_value}"{group_styles}>{group_label}</th>