Feat: add grand_summary_rows() method

docs/_quarto.yml

@@ -165,6 +165,13 @@ quartodoc:
         - GT.cols_move_to_end
         - GT.cols_hide
         - GT.cols_unhide
+    - title: Adding rows
+      desc: >
+        The [`grand_summary_rows()`](`great_tables.GT.grand_summary_rows`) function will add rows to
+        summarize data in your table, such as totals or averages.
+      contents:
+        - GT.grand_summary_rows
+
     - title: Location Targeting and Styling Classes
       desc: >
         Location targeting is a powerful feature of **Great Tables**. It allows for the precise
@@ -179,8 +186,10 @@ quartodoc:
         - loc.column_header
         - loc.spanner_labels
         - loc.column_labels
+        - loc.grand_summary_stub
         - loc.stub
         - loc.row_groups
+        - loc.grand_summary
         - loc.body
         - loc.footer
         - loc.source_notes

docs/get-started/loc-selection.qmd

@@ -23,7 +23,11 @@ data = [
     ["", "loc.column_labels()", "columns"],
     ["row stub", "loc.stub()", "rows"],
     ["", "loc.row_groups()", "rows"],
+    # ["", "loc.summary_stub()", "rows"],
+    ["", "loc.grand_summary_stub()", "rows"],
     ["table body", "loc.body()", "columns and rows"],
+    # ["", "loc.summary_rows()", "columns and rows"],
+    ["", "loc.grand_summary_rows()", "columns and rows"],
     ["footer", "loc.footer()", "composite"],
     ["", "loc.source_notes()", ""],
 ]

docs/get-started/table-theme-options.qmd

@@ -25,6 +25,7 @@ gt_ex = (
     .tab_header("THE HEADING", "(a subtitle)")
     .tab_stubhead("THE STUBHEAD")
     .tab_source_note("THE SOURCE NOTE")
+    .grand_summary_rows({"GRAND SUMMARY ROW": lambda df: df.sum(numeric_only=True)})
 )
 
 gt_ex
@@ -48,6 +49,7 @@ The code below illustrates the table parts `~~GT.tab_options()` can target, by s
         row_group_background_color="lightyellow",
         stub_background_color="lightgreen",
         source_notes_background_color="#f1e2af",
+        grand_summary_row_background_color="lightpink",
     )
 )
 ```

docs/get-started/targeted-styles.qmd

@@ -18,7 +18,7 @@ Below is a big example that shows all possible `loc` specifiers being used.
 ```{python}
 from great_tables import GT, exibble, loc, style
 
-# https://colorbrewer2.org/#type=qualitative&scheme=Paired&n=12
+# https://colorbrewer2.org/#type=qualitative&scheme=Paired&n=12 and grey
 brewer_colors = [
     "#a6cee3",
     "#1f78b4",
@@ -32,6 +32,7 @@ brewer_colors = [
     "#6a3d9a",
     "#ffff99",
     "#b15928",
+    "#808080",
 ]
 
 c = iter(brewer_colors)
@@ -43,6 +44,7 @@ gt = (
     .tab_source_note("yo")
     .tab_spanner("spanner", ["char", "fctr"])
     .tab_stubhead("stubhead")
+    .grand_summary_rows(fns={"Total": lambda x: x.sum(numeric_only=True)})
 )
 
 (
@@ -64,6 +66,9 @@ gt = (
     .tab_style(style.borders(weight="3px"), loc.stub(rows=1))
     .tab_style(style.fill(next(c)), loc.stub())
     .tab_style(style.fill(next(c)), loc.stubhead())
+    # Summary Rows --------------
+    .tab_style(style.fill(next(c)), loc.grand_summary())
+    .tab_style(style.fill(next(c)), loc.grand_summary_stub())
 )
 ```
 
@@ -129,3 +134,17 @@ gt.tab_style(style.fill("yellow"), loc.body())
 ```{python}
 gt.tab_style(style.fill("yellow"), loc.stubhead())
 ```
+
+## Grand Summary Rows
+
+```{python}
+(
+    gt.tab_style(
+        style.fill("yellow"),
+        loc.grand_summary_stub(),
+    ).tab_style(
+        style.fill("lightblue"),
+        loc.grand_summary(),
+    )
+)
+```

great_tables/_gt_data.py

@@ -2,7 +2,7 @@
 
 import copy
 import re
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 from dataclasses import dataclass, field, replace
 from enum import Enum, auto
 from itertools import chain, product
@@ -75,6 +75,8 @@ class GTData:
     _spanners: Spanners
     _heading: Heading
     _stubhead: Stubhead
+    _summary_rows: SummaryRows
+    _summary_rows_grand: SummaryRows
     _source_notes: SourceNotes
     _footnotes: Footnotes
     _styles: Styles
@@ -122,6 +124,8 @@ def from_data(
             _spanners=Spanners([]),
             _heading=Heading(),
             _stubhead=None,
+            _summary_rows=SummaryRows(),
+            _summary_rows_grand=SummaryRows(_is_grand_summary=True),
             _source_notes=[],
             _footnotes=[],
             _styles=[],
@@ -510,10 +514,12 @@ def _get_number_of_visible_data_columns(self) -> int:
 
     # Obtain the number of visible columns in the built table; this should
     # account for the size of the stub in the final, built table
-    def _get_effective_number_of_columns(self, stub: Stub, options: Options) -> int:
+    def _get_effective_number_of_columns(
+        self, stub: Stub, has_summary_rows: bool, options: Options
+    ) -> int:
         n_data_cols = self._get_number_of_visible_data_columns()
 
-        stub_layout = stub._get_stub_layout(options=options)
+        stub_layout = stub._get_stub_layout(has_summary_rows=has_summary_rows, options=options)
         # Once the stub is defined in the package, we need to account
         # for the width of the stub at build time to fully obtain the number
         # of visible columns in the built table
@@ -674,7 +680,7 @@ def _stub_group_names_has_column(self, options: Options) -> bool:
 
         return row_group_as_column
 
-    def _get_stub_layout(self, options: Options) -> list[str]:
+    def _get_stub_layout(self, has_summary_rows: bool, options: Options) -> list[str]:
         # Determine which stub components are potentially present as columns
         stub_rownames_is_column = "row_id" in self._get_stub_components()
         stub_groupnames_is_column = self._stub_group_names_has_column(options=options)
@@ -684,14 +690,12 @@ def _get_stub_layout(self, options: Options) -> list[str]:
 
         # Resolve the layout of the stub (i.e., the roles of columns if present)
         if n_stub_cols == 0:
-            # TODO: If summary rows are present, we will use the `rowname` column
-            # # for the summary row labels
-            # if _summary_exists(data=data):
-            #     stub_layout = ["rowname"]
-            # else:
-            #     stub_layout = []
-
-            stub_layout = []
+            # If summary rows are present, we will use the `rowname` column
+            # for the summary row labels
+            if has_summary_rows:
+                stub_layout = ["rowname"]
+            else:
+                stub_layout = []
 
         else:
             stub_layout = [
@@ -719,7 +723,7 @@ class GroupRowInfo:
     indices: list[int] = field(default_factory=list)
     # row_start: int | None = None
     # row_end: int | None = None
-    has_summary_rows: bool = False
+    # has_summary_rows: bool = False  # TODO: remove
     summary_row_side: str | None = None
 
     def defaulted_label(self) -> str:
@@ -972,6 +976,141 @@ def __init__(self, func: FormatFns, cols: list[str], rows: list[int]):
 Formats = list
 
 
+# Summary Rows ---
+
+# This can't conflict with actual group ids since we have a
+# seperate data structure for grand summary row infos
+
+
+@dataclass(frozen=True)
+class SummaryRowInfo:
+    """Information about a single summary row"""
+
+    id: str
+    label: str  # For now, label and id are identical
+    # The motivation for values as a dict is to ensure cols_* functions don't have to consider
+    # the implications on existing SummaryRowInfo objects
+    values: dict[str, Any]  # TODO: consider datatype, series?
+    side: Literal["top", "bottom"]  # TODO: consider enum
+
+
+class SummaryRows(Mapping[str, list[SummaryRowInfo]]):
+    """A sequence of summary rows
+
+    The following strctures should always be true about summary rows:
+        - The id is also the label (often the same as the function name)
+        - There is at most 1 row for each group and id pairing
+        - If a summary row is added and no row exists for that group and id, add it
+        - If a summary row is added and a row exists for that group and id pairing,
+            then replace all cells (in values) that are numeric in the new version
+    """
+
+    _d: dict[str, list[SummaryRowInfo]]
+    _is_grand_summary: bool
+
+    GRAND_SUMMARY_KEY = "grand"
+
+    def __init__(self, _is_grand_summary: bool = False):
+        self._d = {}
+        self._is_grand_summary = _is_grand_summary
+
+    def __bool__(self) -> bool:
+        """Return True if there are any summary rows, False otherwise."""
+        return len(self._d) > 0
+
+    def __getitem__(self, key: str | None) -> list[SummaryRowInfo]:
+        if self._is_grand_summary:
+            key = SummaryRows.GRAND_SUMMARY_KEY
+
+        if not key:
+            raise KeyError("Summary row group key must not be None for group summary rows.")
+
+        if key not in self._d:
+            raise KeyError(f"Group '{key}' not found in summary rows.")
+
+        return self._d[key]
+
+    def add_summary_row(self, summary_row: SummaryRowInfo, group_id: str | None = None) -> None:
+        """Add a summary row following the merging rules in the class docstring."""
+
+        if self._is_grand_summary:
+            group_id = SummaryRows.GRAND_SUMMARY_KEY
+
+        existing_group = self.get(group_id)
+
+        if not existing_group:
+            self._d[group_id] = [summary_row]
+            return
+
+        else:
+            existing_index = None
+            for i, existing_row in enumerate(existing_group):
+                if existing_row.id == summary_row.id:
+                    existing_index = i
+                    break
+
+            new_rows = existing_group
+
+            if existing_index is None:
+                # No existing row for this group and id, add it
+                new_rows.append(summary_row)
+            else:
+                # Replace existing row, but merge numeric values from new version
+                existing_row = new_rows[existing_index]
+
+                # Start with existing values
+                merged_values = existing_row.values.copy()
+
+                # Replace with numeric values from new row
+                for key, new_value in summary_row.values.items():
+                    if isinstance(new_value, (int, float)):
+                        merged_values[key] = new_value
+
+                # Create merged row with new row's properties but merged values
+                merged_row = SummaryRowInfo(
+                    id=summary_row.id,
+                    label=summary_row.label,
+                    values=merged_values,
+                    # Setting this to existing row instead of summary_row means original
+                    # side is fixed by whatever side is first assigned to this row
+                    side=existing_row.side,
+                )
+
+                new_rows[existing_index] = merged_row
+
+        self._d[group_id] = new_rows
+
+        return
+
+    def get_summary_rows(
+        self, group_id: str | None = None, side: str | None = None
+    ) -> list[SummaryRowInfo]:
+        """Get list of summary rows for that group. If side is None, do not filter by side.
+        Sorts result with 'top' side first, then 'bottom'."""
+
+        result: list[SummaryRowInfo] = []
+
+        if self._is_grand_summary:
+            group_id = SummaryRows.GRAND_SUMMARY_KEY
+
+        summary_row_group = self.get(group_id)
+
+        if summary_row_group:
+            for summary_row in summary_row_group:
+                if side is None or summary_row.side == side:
+                    result.append(summary_row)
+
+        # Sort: 'top' first, then 'bottom'
+        result.sort(key=lambda r: 0 if r.side == "top" else 1)  # TODO: modify if enum for side
+        return result
+
+    def __iter__(self):
+        raise NotImplementedError
+
+    def __len__(self):
+        raise NotImplementedError
+
+
 # Options ----
 
 default_fonts_list = [
@@ -1130,25 +1269,25 @@ class Options:
     # summary_row_border_style: OptionsInfo = OptionsInfo(True, "summary_row", "value", "solid")
     # summary_row_border_width: OptionsInfo = OptionsInfo(True, "summary_row", "px", "2px")
     # summary_row_border_color: OptionsInfo = OptionsInfo(True, "summary_row", "value", "#D3D3D3")
-    # grand_summary_row_padding: OptionsInfo = OptionsInfo(True, "grand_summary_row", "px", "8px")
-    # grand_summary_row_padding_horizontal: OptionsInfo = OptionsInfo(
-    #    True, "grand_summary_row", "px", "5px"
-    # )
-    # grand_summary_row_background_color: OptionsInfo = OptionsInfo(
-    #    True, "grand_summary_row", "value", None
-    # )
-    # grand_summary_row_text_transform: OptionsInfo = OptionsInfo(
-    #    True, "grand_summary_row", "value", "inherit"
-    # )
-    # grand_summary_row_border_style: OptionsInfo = OptionsInfo(
-    #    True, "grand_summary_row", "value", "double"
-    # )
-    # grand_summary_row_border_width: OptionsInfo = OptionsInfo(
-    #    True, "grand_summary_row", "px", "6px"
-    # )
-    # grand_summary_row_border_color: OptionsInfo = OptionsInfo(
-    #    True, "grand_summary_row", "value", "#D3D3D3"
-    # )
+    grand_summary_row_padding: OptionsInfo = OptionsInfo(True, "grand_summary_row", "px", "8px")
+    grand_summary_row_padding_horizontal: OptionsInfo = OptionsInfo(
+        True, "grand_summary_row", "px", "5px"
+    )
+    grand_summary_row_background_color: OptionsInfo = OptionsInfo(
+        True, "grand_summary_row", "value", None
+    )
+    grand_summary_row_text_transform: OptionsInfo = OptionsInfo(
+        True, "grand_summary_row", "value", "inherit"
+    )
+    grand_summary_row_border_style: OptionsInfo = OptionsInfo(
+        True, "grand_summary_row", "value", "double"
+    )
+    grand_summary_row_border_width: OptionsInfo = OptionsInfo(
+        True, "grand_summary_row", "px", "6px"
+    )
+    grand_summary_row_border_color: OptionsInfo = OptionsInfo(
+        True, "grand_summary_row", "value", "#D3D3D3"
+    )
     # footnotes_font_size: OptionsInfo = OptionsInfo(True, "footnotes", "px", "90%")
     # footnotes_padding: OptionsInfo = OptionsInfo(True, "footnotes", "px", "4px")
     # footnotes_padding_horizontal: OptionsInfo = OptionsInfo(True, "footnotes", "px", "5px")