docs: update the related docs about mask= parameter in loc.body() (…

…#589) * Update `basic-styling.qmd` * Update `loc-selection.qmd` * Fix error messages * Move `mask=` experimental callout to the top --------- Co-authored-by: Michael Chow <[email protected]>
posit-dev · Jan 27, 2025 · 3290208 · 3290208
1 parent d71ee99
commit 3290208
Show file tree

Hide file tree

Showing 3 changed files with 29 additions and 9 deletions.
diff --git a/docs/get-started/basic-styling.qmd b/docs/get-started/basic-styling.qmd
@@ -228,6 +228,17 @@ gt_pl_air.tab_style(
 )
 ```
 
+Lastly, you can use **Polars** selectors or expressions to conditionally select rows on a per-column basis.
+```{python}
+import polars.selectors as cs
+
+gt_pl_air.tab_style(
+    style=style.fill(color="yellow"),
+    locations=loc.body(mask=cs.all().eq(cs.all().max())),
+)
+```
+
+
 ## Learning more
 
 * API Docs:

diff --git a/docs/get-started/loc-selection.qmd b/docs/get-started/loc-selection.qmd
@@ -84,10 +84,9 @@ For example, `loc.header()` includes both `loc.title()` and `loc.subtitle()`.
 )
 ```
 
-## Body columns and rows
-
-Use `loc.body()` to style specific cells in the table body.
+## Body columns, rows and mask
 
+Use `columns=` and `rows=` in `loc.body()` to style specific cells in the table body.
 ```{python}
 (
     GT(pl_exibble).tab_style(
@@ -100,6 +99,16 @@ Use `loc.body()` to style specific cells in the table body.
 )
 ```
 
+Alternatively, use `mask=` in `loc.body()` to apply conditional styling to rows on a per-column basis.
+```{python}
+(
+    GT(pl_exibble).tab_style(
+        style.fill("yellow"),
+        loc.body(mask=cs.string().str.contains("p")),
+    )
+)
+```
+
 This is discussed in detail in [Styling the Table Body](./basic-styling.qmd).
 
 ## Column labels

diff --git a/great_tables/_locations.py b/great_tables/_locations.py
@@ -494,6 +494,10 @@ class LocBody(Loc):
     custom styling with the [`tab_style()`](`great_tables.GT.tab_style`) method. That method has a
     `locations=` argument and this class should be used there to perform the targeting.
 
+    :::{.callout-warning}
+    `mask=` is still experimental.
+    :::
+
     Parameters
     ----------
     columns
@@ -507,10 +511,6 @@ class LocBody(Loc):
         you can pass a Polars expression for cell-based selection. This argument must be used
         exclusively and cannot be combined with the `columns=` or `rows=` arguments.
 
-    :::{.callout-warning}
-    `mask=` is still experimental.
-    :::
-
     Returns
     -------
     LocBody
@@ -864,8 +864,8 @@ def resolve_mask(
     if masked.height != frame.height:
         raise ValueError(
             "The DataFrame length after applying `mask` differs from the original."
-            "\n\n* Original length: {frame.height}"
-            "\n* Mask length: {masked.height}"
+            f"\n\n* Original length: {frame.height}"
+            f"\n* Mask length: {masked.height}"
         )
 
     cellpos_data: list[tuple[int, int, str]] = []  # column, row, colname for `CellPos`