From b0edc731c5cba4261d75bc293165e032f5ac7f23 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Mon, 30 Sep 2024 13:10:33 -0400 Subject: [PATCH 01/22] Add docstring for LocSourceNotes --- great_tables/_locations.py | 35 ++++++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/great_tables/_locations.py b/great_tables/_locations.py index 3274c2450..81aec501c 100644 --- a/great_tables/_locations.py +++ b/great_tables/_locations.py @@ -160,7 +160,40 @@ class LocFootnotes(Loc): @dataclass class LocSourceNotes(Loc): - """A location for targeting source notes.""" + """A location specification for targeting the source notes. + + The `loc.source_notes()` class is used to target the source notes in the table. The class can be + used to apply 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. + The 'source_notes' location is generated by + [`tab_source_note()`](`great_tables.GT.tab_source_note`). + + Returns + ------- + LocSourceNotes + A `LocSourceNotes` object, which is used for a `locations=` argument if specifying the + source notes. + + Examples + -------- + Let's use a subset of the [`gtcars`] dataset in a new table. Add a source note (with + [`tab_source_note()`](`great_tables.GT.tab_source_note`) and style the source notes section + inside [`tab_style()`](`great_tables.GT.tab_style`) with `locations=loc.source_notes()`. + + ```{python} + from great_tables import GT, style, loc + from great_tables.data import gtcars + + ( + GT(gtcars[["mfr", "model", "msrp"]].head(5)) + .tab_source_note(source_note="From edmunds.com") + .tab_style( + style=style.text(color="blue", size="small", weight="bold"), + locations=loc.source_notes() + ) + ) + ``` + """ # Utils ================================================================================ From 326e5237e21d154e0f0d7d3acb76ed0c29688497 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Mon, 30 Sep 2024 13:35:55 -0400 Subject: [PATCH 02/22] Add `loc.source_note` to API reference --- docs/_quarto.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 55f19de95..1029c660c 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -146,6 +146,7 @@ quartodoc: specification of the styling properties to be applied to the targeted locations. contents: - loc.body + - loc.source_note - style.fill - style.text - style.borders From 3d3f708b0f11697a6997fc97a888d68f3b7c7632 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Mon, 30 Sep 2024 13:41:33 -0400 Subject: [PATCH 03/22] Make correction to loc name --- docs/_quarto.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 1029c660c..8a4904d6f 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -146,7 +146,7 @@ quartodoc: specification of the styling properties to be applied to the targeted locations. contents: - loc.body - - loc.source_note + - loc.source_notes - style.fill - style.text - style.borders From a203fbc921390f814d15b050501ec28c6baa8b20 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Mon, 30 Sep 2024 14:06:48 -0400 Subject: [PATCH 04/22] Revise text in some Loc* docstrings --- great_tables/_locations.py | 50 +++++++++++++++++++++++++++++++------- 1 file changed, 41 insertions(+), 9 deletions(-) diff --git a/great_tables/_locations.py b/great_tables/_locations.py index 81aec501c..c4c36f093 100644 --- a/great_tables/_locations.py +++ b/great_tables/_locations.py @@ -114,9 +114,9 @@ class LocBody(Loc): # TODO: these can be tidyselectors """A location specification for targeting data cells in the table body. - The `loc.body()` class is used to target the data cells in the table body. The class can be used - to apply custom styling with the `tab_style()` method. That method has a `locations` argument - and this class should be used there to perform the targeting. + With `loc.body()`, we can target the data cells in the table body. This is useful for applying + 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. Parameters ---------- @@ -130,7 +130,7 @@ class LocBody(Loc): Returns ------- LocBody - A LocBody object, which is used for a `locations` argument if specifying the table body. + A LocBody object, which is used for a `locations=` argument if specifying the table body. Examples ------ @@ -150,7 +150,39 @@ class LocSummary(Loc): @dataclass class LocFooter(Loc): - """A location for targeting the footer.""" + """A location specification for targeting the table footer. + + With `loc.footer()` we can target the table's footer. This is useful when applying 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. The 'footer' + location is generated by [`tab_source_note()`](`great_tables.GT.tab_source_note`). + + Returns + ------- + LocFooter + A `LocFooter` object, which is used for a `locations=` argument if specifying the footer of + the table. + + Examples + -------- + Let's use a subset of the [`gtcars`] dataset in a new table. Add a source note (with + [`tab_source_note()`](`great_tables.GT.tab_source_note`) and style this footer section inside of + [`tab_style()`](`great_tables.GT.tab_style`) with `locations=loc.footer()`. + + ```{python} + from great_tables import GT, style, loc + from great_tables.data import gtcars + + ( + GT(gtcars[["mfr", "model", "msrp"]].head(5)) + .tab_source_note(source_note="From edmunds.com") + .tab_style( + style=style.text(color="blue", size="small", weight="bold"), + locations=loc.footer() + ) + ) + ``` + """ @dataclass @@ -162,10 +194,10 @@ class LocFootnotes(Loc): class LocSourceNotes(Loc): """A location specification for targeting the source notes. - The `loc.source_notes()` class is used to target the source notes in the table. The class can be - used to apply 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. - The 'source_notes' location is generated by + With `loc.source_notes()`, we can target the source notes in the table. This is useful when + applying custom 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. The + 'source_notes' location is generated by [`tab_source_note()`](`great_tables.GT.tab_source_note`). Returns From 6f7559f7e061df9a192ef7190ca8215792a914eb Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Mon, 30 Sep 2024 14:17:20 -0400 Subject: [PATCH 05/22] Add docstring for LocColumnLabels --- great_tables/_locations.py | 44 +++++++++++++++++++++++++++++++++++--- 1 file changed, 41 insertions(+), 3 deletions(-) diff --git a/great_tables/_locations.py b/great_tables/_locations.py index c4c36f093..1c3547ebe 100644 --- a/great_tables/_locations.py +++ b/great_tables/_locations.py @@ -82,6 +82,44 @@ class LocColumnHeader(Loc): @dataclass class LocColumnLabels(Loc): + """A location specification for targeting column labels. + + With `loc.column_labels()`, we can target the cells containing the column labels. This is useful + for applying 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. + + Parameters + ---------- + columns + The columns to target. Can either be a single column name or a series of column names + provided in a list. If no columns are specified, all columns are targeted. + + Returns + ------- + LocBody + A LocBody object, which is used for a `locations=` argument if specifying the table body. + + Examples + -------- + Let's use a subset of the `gtcars` dataset in a new table. We will style all three of the column + labels by using `locations=loc.column_labels()` within + [`tab_style()`](`great_tables.GT.tab_style`). Note that no specification of `columns=` is needed + here because we want to target all columns. + + ```{python} + from great_tables import GT, style, loc + from great_tables.data import gtcars + + ( + GT(gtcars[["mfr", "model", "msrp"]].head(5)) + .tab_style( + style=style.text(color="blue", size="large", weight="bold"), + locations=loc.column_labels() + ) + ) + ``` + """ + columns: SelectExpr = None @@ -133,7 +171,7 @@ class LocBody(Loc): A LocBody object, which is used for a `locations=` argument if specifying the table body. Examples - ------ + -------- See [`GT.tab_style()`](`great_tables.GT.tab_style`). """ @@ -165,7 +203,7 @@ class LocFooter(Loc): Examples -------- - Let's use a subset of the [`gtcars`] dataset in a new table. Add a source note (with + Let's use a subset of the `gtcars` dataset in a new table. Add a source note (with [`tab_source_note()`](`great_tables.GT.tab_source_note`) and style this footer section inside of [`tab_style()`](`great_tables.GT.tab_style`) with `locations=loc.footer()`. @@ -208,7 +246,7 @@ class LocSourceNotes(Loc): Examples -------- - Let's use a subset of the [`gtcars`] dataset in a new table. Add a source note (with + Let's use a subset of the `gtcars` dataset in a new table. Add a source note (with [`tab_source_note()`](`great_tables.GT.tab_source_note`) and style the source notes section inside [`tab_style()`](`great_tables.GT.tab_style`) with `locations=loc.source_notes()`. From 87f74072a50513c2e4509fe11b429e7d71abbef0 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Mon, 30 Sep 2024 14:17:49 -0400 Subject: [PATCH 06/22] Add loc.column_labels to API reference --- docs/_quarto.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 8a4904d6f..d039feee7 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -146,6 +146,7 @@ quartodoc: specification of the styling properties to be applied to the targeted locations. contents: - loc.body + - loc.column_labels - loc.source_notes - style.fill - style.text From e5255a938e66124c7a6190cb8d9aff768d68cfa1 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Mon, 30 Sep 2024 14:18:11 -0400 Subject: [PATCH 07/22] Add loc.footer to API reference --- docs/_quarto.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/_quarto.yml b/docs/_quarto.yml index d039feee7..dc41d261d 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -147,6 +147,7 @@ quartodoc: contents: - loc.body - loc.column_labels + - loc.footer - loc.source_notes - style.fill - style.text From 9a9c3d6068e8ce8b55d9316eea370814563f8ae3 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Mon, 30 Sep 2024 14:37:26 -0400 Subject: [PATCH 08/22] Make correction to 'Returns' section in docstring --- great_tables/_locations.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/great_tables/_locations.py b/great_tables/_locations.py index 1c3547ebe..5640e6177 100644 --- a/great_tables/_locations.py +++ b/great_tables/_locations.py @@ -167,8 +167,9 @@ class LocBody(Loc): Returns ------- - LocBody - A LocBody object, which is used for a `locations=` argument if specifying the table body. + LocColumnLabels + A LocColumnLabels object, which is used for a `locations=` argument if specifying the + table's column labels. Examples -------- From c4c281f8ed407ceed60c5f4c17248338831ec68b Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Mon, 30 Sep 2024 14:37:40 -0400 Subject: [PATCH 09/22] Add docstring for the LocTitle class --- docs/_quarto.yml | 1 + great_tables/_locations.py | 48 +++++++++++++++++++++++++++++++++----- 2 files changed, 43 insertions(+), 6 deletions(-) diff --git a/docs/_quarto.yml b/docs/_quarto.yml index dc41d261d..62107ead1 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -146,6 +146,7 @@ quartodoc: specification of the styling properties to be applied to the targeted locations. contents: - loc.body + - loc.title - loc.column_labels - loc.footer - loc.source_notes diff --git a/great_tables/_locations.py b/great_tables/_locations.py index 5640e6177..5c9476587 100644 --- a/great_tables/_locations.py +++ b/great_tables/_locations.py @@ -57,7 +57,43 @@ class LocHeader(Loc): @dataclass class LocTitle(Loc): - """A location for targeting the title.""" + """A location specification for targeting the table title. + + With `loc.title()`, we can target the part of table containing the title (within the table + header). This is useful for applying 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. + + Returns + ------- + LocTitle + A LocTitle object, which is used for a `locations=` argument if specifying the title of the + table. + + Examples + -------- + Let's use a subset of the `gtcars` dataset in a new table. We will style only the 'title' part + of the table header (leaving the 'subtitle' part unaffected). This can be done by using + `locations=loc.title()` within [`tab_style()`](`great_tables.GT.tab_style`). + + ```{python} + from great_tables import GT, style, loc + from great_tables.data import gtcars + + ( + GT(gtcars[["mfr", "model", "msrp"]].head(5)) + .tab_header( + title="Select Cars from the gtcars Dataset", + subtitle="Only the first five cars are displayed" + ) + .tab_style( + style=style.text(color="blue", size="large", weight="bold"), + locations=loc.title() + ) + .fmt_currency(columns="msrp", decimals=0) + ) + ``` + """ @dataclass @@ -96,8 +132,9 @@ class LocColumnLabels(Loc): Returns ------- - LocBody - A LocBody object, which is used for a `locations=` argument if specifying the table body. + LocColumnLabels + A LocColumnLabels object, which is used for a `locations=` argument if specifying the + table's column labels. Examples -------- @@ -167,9 +204,8 @@ class LocBody(Loc): Returns ------- - LocColumnLabels - A LocColumnLabels object, which is used for a `locations=` argument if specifying the - table's column labels. + LocBody + A LocBody object, which is used for a `locations=` argument if specifying the table body. Examples -------- From 617ac1010b85a1360390889d3a58c72c0d3c66fa Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Mon, 30 Sep 2024 14:49:35 -0400 Subject: [PATCH 10/22] Add docstring for LocSubTitle class --- docs/_quarto.yml | 1 + great_tables/_locations.py | 38 +++++++++++++++++++++++++++++++++++++- 2 files changed, 38 insertions(+), 1 deletion(-) diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 62107ead1..2e5f88731 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -147,6 +147,7 @@ quartodoc: contents: - loc.body - loc.title + - loc.subtitle - loc.column_labels - loc.footer - loc.source_notes diff --git a/great_tables/_locations.py b/great_tables/_locations.py index 5c9476587..96ca98968 100644 --- a/great_tables/_locations.py +++ b/great_tables/_locations.py @@ -98,7 +98,43 @@ class LocTitle(Loc): @dataclass class LocSubTitle(Loc): - """A location for targeting the subtitle.""" + """A location specification for targeting the table subtitle. + + With `loc.subtitle()`, we can target the part of table containing the subtitle (within the table + header). This is useful for applying 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. + + Returns + ------- + LocSubTitle + A LocSubTitle object, which is used for a `locations=` argument if specifying the subtitle + of the table. + + Examples + -------- + Let's use a subset of the `gtcars` dataset in a new table. We will style only the 'subtitle' + part of the table header (leaving the 'title' part unaffected). This can be done by using + `locations=loc.subtitle()` within [`tab_style()`](`great_tables.GT.tab_style`). + + ```{python} + from great_tables import GT, style, loc + from great_tables.data import gtcars + + ( + GT(gtcars[["mfr", "model", "msrp"]].head(5)) + .tab_header( + title="Select Cars from the gtcars Dataset", + subtitle="Only the first five cars are displayed" + ) + .tab_style( + style=style.fill(color="lightblue"), + locations=loc.subtitle() + ) + .fmt_currency(columns="msrp", decimals=0) + ) + ``` + """ @dataclass From b807c1427b3455e589f9b491ca11358690e661e5 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Mon, 30 Sep 2024 15:05:27 -0400 Subject: [PATCH 11/22] Add docstring for LocHeader class --- docs/_quarto.yml | 1 + great_tables/_locations.py | 38 +++++++++++++++++++++++++++++++++++++- 2 files changed, 38 insertions(+), 1 deletion(-) diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 2e5f88731..cb2a40650 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -148,6 +148,7 @@ quartodoc: - loc.body - loc.title - loc.subtitle + - loc.header - loc.column_labels - loc.footer - loc.source_notes diff --git a/great_tables/_locations.py b/great_tables/_locations.py index 96ca98968..ae9eeef23 100644 --- a/great_tables/_locations.py +++ b/great_tables/_locations.py @@ -52,7 +52,43 @@ class Loc: @dataclass class LocHeader(Loc): - """A location for targeting the table title and subtitle.""" + """A location specification for targeting the table header (title and subtitle). + + With `loc.header()`, we can target the table header which contains the title and the subtitle. + This is useful for applying 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. + + Returns + ------- + LocHeader + A LocHeader object, which is used for a `locations=` argument if specifying the title of the + table. + + Examples + -------- + Let's use a subset of the `gtcars` dataset in a new table. We will style the entire table header + (the 'title' and 'subtitle' parts. This can be done by using `locations=loc.header()` within + [`tab_style()`](`great_tables.GT.tab_style`). + + ```{python} + from great_tables import GT, style, loc + from great_tables.data import gtcars + + ( + GT(gtcars[["mfr", "model", "msrp"]].head(5)) + .tab_header( + title="Select Cars from the gtcars Dataset", + subtitle="Only the first five cars are displayed" + ) + .tab_style( + style=style.fill(color="lightblue"), + locations=loc.header() + ) + .fmt_currency(columns="msrp", decimals=0) + ) + ``` + """ @dataclass From a453212339b8959e38aba1fd5f75a378baede80f Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Mon, 30 Sep 2024 17:05:46 -0400 Subject: [PATCH 12/22] Add docstring for LocSpannerLabels class --- docs/_quarto.yml | 1 + great_tables/_locations.py | 51 +++++++++++++++++++++++++++++++++++++- 2 files changed, 51 insertions(+), 1 deletion(-) diff --git a/docs/_quarto.yml b/docs/_quarto.yml index cb2a40650..8d6d629a8 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -150,6 +150,7 @@ quartodoc: - loc.subtitle - loc.header - loc.column_labels + - loc.spanner_labels - loc.footer - loc.source_notes - style.fill diff --git a/great_tables/_locations.py b/great_tables/_locations.py index ae9eeef23..b21672bf3 100644 --- a/great_tables/_locations.py +++ b/great_tables/_locations.py @@ -234,7 +234,56 @@ class LocColumnLabels(Loc): @dataclass class LocSpannerLabels(Loc): - """A location for column spanners.""" + """A location specification for targeting spanner labels. + + With `loc.spanner_labels()`, we can target the cells containing the spanner labels. This is + useful for applying 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. + + Parameters + ---------- + ids: + The ID values for the spanner labels to target. A list of one or more ID values is required. + + Returns + ------- + LocSpannerLabels + A LocSpannerLabels object, which is used for a `locations=` argument if specifying the + table's spanner labels. + + Examples + -------- + Let's use a subset of the `gtcars` dataset in a new table. We create two spanner labels through + two separate calls of the [`tab_spanner()`](`great_tables.GT.tab_spanner`) method. In each of + those, the text supplied to `label=` argument is used as the ID value (though they have be + explicitly set via the `id=` argument). We will style only the spanner label with the text + `"performance"` by using `locations=loc.spanner_labels(ids=["performance"])` within + [`tab_style()`](`great_tables.GT.tab_style`). + + ```{python} + from great_tables import GT, style, loc + from great_tables.data import gtcars + + ( + GT(gtcars[["mfr", "model", "hp", "trq", "msrp"]].head(5)) + .tab_spanner( + label="performance", + columns=["hp", "trq"] + ) + .tab_spanner( + label="make and model", + columns=["mfr", "model"] + ) + .tab_style( + style=style.text(color="blue", weight="bold"), + locations=loc.spanner_labels(ids=["performance"]) + ) + .fmt_integer(columns=["hp", "trq"]) + .fmt_currency(columns="msrp", decimals=0) + ) + ``` + """ ids: SelectExpr = None From d1a357c01c8c7d876d759a9a5510fb546fd91484 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Mon, 30 Sep 2024 17:16:45 -0400 Subject: [PATCH 13/22] Make adjustments to text introducing example --- great_tables/_locations.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/great_tables/_locations.py b/great_tables/_locations.py index b21672bf3..8d7348e18 100644 --- a/great_tables/_locations.py +++ b/great_tables/_locations.py @@ -256,8 +256,8 @@ class LocSpannerLabels(Loc): -------- Let's use a subset of the `gtcars` dataset in a new table. We create two spanner labels through two separate calls of the [`tab_spanner()`](`great_tables.GT.tab_spanner`) method. In each of - those, the text supplied to `label=` argument is used as the ID value (though they have be - explicitly set via the `id=` argument). We will style only the spanner label with the text + those, the text supplied to `label=` argument is used as the ID value (though they have to be + explicitly set via the `id=` argument). We will style only the spanner label having the text `"performance"` by using `locations=loc.spanner_labels(ids=["performance"])` within [`tab_style()`](`great_tables.GT.tab_style`). From cc53a163c18df8dfb4befc3bb95949befa84409a Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 1 Oct 2024 09:32:22 -0400 Subject: [PATCH 14/22] Add docstring for LocColumnHeader --- docs/_quarto.yml | 1 + great_tables/_locations.py | 50 ++++++++++++++++++++++++++++++++++++-- 2 files changed, 49 insertions(+), 2 deletions(-) diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 8d6d629a8..d689d678b 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -151,6 +151,7 @@ quartodoc: - loc.header - loc.column_labels - loc.spanner_labels + - loc.column_header - loc.footer - loc.source_notes - style.fill diff --git a/great_tables/_locations.py b/great_tables/_locations.py index 8d7348e18..96ce186c2 100644 --- a/great_tables/_locations.py +++ b/great_tables/_locations.py @@ -180,12 +180,58 @@ class LocStubhead(Loc): @dataclass class LocStubheadLabel(Loc): - """A location for targetting the stubhead.""" + """A location specification for targetting the stubhead.""" @dataclass class LocColumnHeader(Loc): - """A location for column spanners and column labels.""" + """A location specification for column spanners and column labels. + + With `loc.column_header()`, we can target the column header which contains all of the column + labels and any spanner labels that are present. This is useful for applying 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. + + Returns + ------- + LocColumnHeader + A LocColumnHeader object, which is used for a `locations=` argument if specifying the column + header of the table. + + Examples + -------- + Let's use a subset of the `gtcars` dataset in a new table. We create spanner labels through + use of the [`tab_spanner()`](`great_tables.GT.tab_spanner`) method; this gives us a column + header with a mix of column labels and spanner labels. We will style the entire column header at + once by using `locations=loc.column_header()` within + [`tab_style()`](`great_tables.GT.tab_style`). + + ```{python} + from great_tables import GT, style, loc + from great_tables.data import gtcars + + ( + GT(gtcars[["mfr", "model", "hp", "trq", "msrp"]].head(5)) + .tab_spanner( + label="performance", + columns=["hp", "trq"] + ) + .tab_spanner( + label="make and model", + columns=["mfr", "model"] + ) + .tab_style( + style=[ + style.text(color="white", weight="bold"), + style.fill(color="steelblue") + ], + locations=loc.column_header() + ) + .fmt_integer(columns=["hp", "trq"]) + .fmt_currency(columns="msrp", decimals=0) + ) + ``` + """ @dataclass From 164cea6d83a90b5f076ba10db0bfaf182aebd348 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 1 Oct 2024 09:49:29 -0400 Subject: [PATCH 15/22] Add docstring for LocStubheadLabel --- docs/_quarto.yml | 1 + great_tables/_locations.py | 41 +++++++++++++++++++++++++++++++++++++- 2 files changed, 41 insertions(+), 1 deletion(-) diff --git a/docs/_quarto.yml b/docs/_quarto.yml index f275c1e9d..fb29bfd18 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -155,6 +155,7 @@ quartodoc: - loc.column_labels - loc.spanner_labels - loc.column_header + - loc.stubhead - loc.footer - loc.source_notes - style.fill diff --git a/great_tables/_locations.py b/great_tables/_locations.py index 96ce186c2..922d6b569 100644 --- a/great_tables/_locations.py +++ b/great_tables/_locations.py @@ -180,7 +180,46 @@ class LocStubhead(Loc): @dataclass class LocStubheadLabel(Loc): - """A location specification for targetting the stubhead.""" + """A location specification for targeting the stubhead. + + With `loc.stubhead_label()`, we can target the part of table that resides both at the top of the + stub and also beside the column header. This is useful for applying 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. + + Returns + ------- + LocStubheadLabel + A LocStubheadLabel object, which is used for a `locations=` argument if specifying the + stubhead of the table. + + Examples + -------- + Let's use a subset of the `gtcars` dataset in a new table. This table contains a stub (produced + by setting `rowname_col="model"` in the initial `GT()` call). The stubhead is given a label by + way of the [`tab_stubhead()`](`great_tables.GT.tab_stubhead`) method and this label can be + styled by using `locations=loc.stubhead()` within [`tab_style()`](`great_tables.GT.tab_style`). + + ```{python} + from great_tables import GT, style, loc + from great_tables.data import gtcars + + ( + GT( + gtcars[["mfr", "model", "hp", "trq", "msrp"]].head(5), + rowname_col="model", + groupname_col="mfr" + ) + .tab_stubhead(label="car") + .tab_style( + style=style.text(color="red", weight="bold"), + locations=loc.stubhead() + ) + .fmt_integer(columns=["hp", "trq"]) + .fmt_currency(columns="msrp", decimals=0) + ) + ``` + """ @dataclass From 0e91b1dfe217cfbf30efdad07788dbc5fba60004 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 1 Oct 2024 10:21:52 -0400 Subject: [PATCH 16/22] Document LocStubhead instead of LocStubheadLabel --- great_tables/_locations.py | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/great_tables/_locations.py b/great_tables/_locations.py index 922d6b569..903217785 100644 --- a/great_tables/_locations.py +++ b/great_tables/_locations.py @@ -175,23 +175,18 @@ class LocSubTitle(Loc): @dataclass class LocStubhead(Loc): - """A location for targeting the table stubhead and stubhead label.""" - - -@dataclass -class LocStubheadLabel(Loc): """A location specification for targeting the stubhead. - With `loc.stubhead_label()`, we can target the part of table that resides both at the top of the + With `loc.stubhead()`, we can target the part of table that resides both at the top of the stub and also beside the column header. This is useful for applying 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. Returns ------- - LocStubheadLabel - A LocStubheadLabel object, which is used for a `locations=` argument if specifying the - stubhead of the table. + LocStubhead + A LocStubhead object, which is used for a `locations=` argument if specifying the stubhead + of the table. Examples -------- @@ -222,6 +217,11 @@ class LocStubheadLabel(Loc): """ +@dataclass +class LocStubheadLabel(Loc): + """A location for targeting the stubhead label""" + + @dataclass class LocColumnHeader(Loc): """A location specification for column spanners and column labels. From 4f14979ba592af857e58eee158e5826ed3dff509 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 1 Oct 2024 10:28:28 -0400 Subject: [PATCH 17/22] Add docstring for LocStub class --- docs/_quarto.yml | 1 + great_tables/_locations.py | 48 +++++++++++++++++++++++++++++++++++++- 2 files changed, 48 insertions(+), 1 deletion(-) diff --git a/docs/_quarto.yml b/docs/_quarto.yml index fb29bfd18..a42ef00de 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -156,6 +156,7 @@ quartodoc: - loc.spanner_labels - loc.column_header - loc.stubhead + - loc.stub - loc.footer - loc.source_notes - style.fill diff --git a/great_tables/_locations.py b/great_tables/_locations.py index 903217785..e549af3ea 100644 --- a/great_tables/_locations.py +++ b/great_tables/_locations.py @@ -375,7 +375,53 @@ class LocSpannerLabels(Loc): @dataclass class LocStub(Loc): - """A location for targeting the table stub, row group labels, summary labels, and body.""" + """A location specification for targeting rows of the table stub. + + With `loc.stub()` we can target the cells containing the row labels, which reside in the table + stub. This is useful for applying 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. + + Parameters + ---------- + rows + The rows to target within the stub. Can either be a single row name or a series of row names + provided in a list. If no rows are specified, all rows are targeted. + + Returns + ------- + LocStub + A LocStub object, which is used for a `locations=` argument if specifying the table's stub. + + Examples + -------- + Let's use a subset of the `gtcars` dataset in a new table. We will style the entire table stub + (the row labels) by using `locations=loc.stub()` within + [`tab_style()`](`great_tables.GT.tab_style`). + + ```{python} + from great_tables import GT, style, loc + from great_tables.data import gtcars + + ( + GT( + gtcars[["mfr", "model", "hp", "trq", "msrp"]].head(5), + rowname_col="model", + groupname_col="mfr" + ) + .tab_stubhead(label="car") + .tab_style( + style=[ + style.text(color="crimson", weight="bold"), + style.fill(color="lightgray") + ], + locations=loc.stub() + ) + .fmt_integer(columns=["hp", "trq"]) + .fmt_currency(columns="msrp", decimals=0) + ) + ``` + """ rows: RowSelectExpr = None From 8c82aefa63db1bef74c60dad56e6525b1a0d33f6 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 1 Oct 2024 10:36:02 -0400 Subject: [PATCH 18/22] Add docstring for LocRowGroups class --- docs/_quarto.yml | 1 + great_tables/_locations.py | 49 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+) diff --git a/docs/_quarto.yml b/docs/_quarto.yml index a42ef00de..605c95e45 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -157,6 +157,7 @@ quartodoc: - loc.column_header - loc.stubhead - loc.stub + - loc.row_groups - loc.footer - loc.source_notes - style.fill diff --git a/great_tables/_locations.py b/great_tables/_locations.py index e549af3ea..d9923e1c8 100644 --- a/great_tables/_locations.py +++ b/great_tables/_locations.py @@ -428,6 +428,55 @@ class LocStub(Loc): @dataclass class LocRowGroups(Loc): + """A location specification for targeting row groups. + + With `loc.row_groups()` we can target the cells containing the row group labels, which span + across the table body. This is useful for applying 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. + + Parameters + ---------- + rows + The row groups to target. Can either be a single group name or a series of group names + provided in a list. If no groups are specified, all are targeted. + + Returns + ------- + LocRowGroups + A LocRowGroups object, which is used for a `locations=` argument if specifying the table's + row groups. + + Examples + -------- + Let's use a subset of the `gtcars` dataset in a new table. We will style all of the cells + comprising the row group labels by using `locations=loc.row_groups()` within + [`tab_style()`](`great_tables.GT.tab_style`). + + ```{python} + from great_tables import GT, style, loc + from great_tables.data import gtcars + + ( + GT( + gtcars[["mfr", "model", "hp", "trq", "msrp"]].head(5), + rowname_col="model", + groupname_col="mfr" + ) + .tab_stubhead(label="car") + .tab_style( + style=[ + style.text(color="crimson", weight="bold"), + style.fill(color="lightgray") + ], + locations=loc.row_groups() + ) + .fmt_integer(columns=["hp", "trq"]) + .fmt_currency(columns="msrp", decimals=0) + ) + ``` + """ + rows: RowSelectExpr = None From c1fcebe5b5029fb25a8dbb247e8a1bb58891b2fe Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 1 Oct 2024 10:41:33 -0400 Subject: [PATCH 19/22] Add example to LocBody docstring --- great_tables/_locations.py | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/great_tables/_locations.py b/great_tables/_locations.py index d9923e1c8..05373254f 100644 --- a/great_tables/_locations.py +++ b/great_tables/_locations.py @@ -510,7 +510,31 @@ class LocBody(Loc): Examples -------- - See [`GT.tab_style()`](`great_tables.GT.tab_style`). + Let's use a subset of the `gtcars` dataset in a new table. We will style all of the body cells + by using `locations=loc.body()` within [`tab_style()`](`great_tables.GT.tab_style`). + + ```{python} + from great_tables import GT, style, loc + from great_tables.data import gtcars + + ( + GT( + gtcars[["mfr", "model", "hp", "trq", "msrp"]].head(5), + rowname_col="model", + groupname_col="mfr" + ) + .tab_stubhead(label="car") + .tab_style( + style=[ + style.text(color="darkblue", weight="bold"), + style.fill(color="gainsboro") + ], + locations=loc.body() + ) + .fmt_integer(columns=["hp", "trq"]) + .fmt_currency(columns="msrp", decimals=0) + ) + ``` """ columns: SelectExpr = None From 606cf68943f44efb2519953ee20788e3f326be78 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 1 Oct 2024 10:46:04 -0400 Subject: [PATCH 20/22] Reorder loc methods in API reference --- docs/_quarto.yml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 605c95e45..98be15cc1 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -148,16 +148,16 @@ quartodoc: [`tab_style()`](`great_tables.GT.tab_style`) method). The styling classes allow for the specification of the styling properties to be applied to the targeted locations. contents: - - loc.body + - loc.header - loc.title - loc.subtitle - - loc.header - - loc.column_labels - - loc.spanner_labels - - loc.column_header - loc.stubhead + - loc.column_header + - loc.spanner_labels + - loc.column_labels - loc.stub - loc.row_groups + - loc.body - loc.footer - loc.source_notes - style.fill From 236a6d2a4c505fc1ccf9bbe3667ec61a0eee3f4c Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 1 Oct 2024 11:05:34 -0400 Subject: [PATCH 21/22] Add note about future 'footnotes' loc in LocFooter --- great_tables/_locations.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/great_tables/_locations.py b/great_tables/_locations.py index 05373254f..b9fb2472a 100644 --- a/great_tables/_locations.py +++ b/great_tables/_locations.py @@ -552,7 +552,8 @@ class LocSummary(Loc): class LocFooter(Loc): """A location specification for targeting the table footer. - With `loc.footer()` we can target the table's footer. This is useful when applying custom + With `loc.footer()` we can target the table's footer, which currently contains the source notes + (and may contain a 'footnotes' location in the future). This is useful when applying 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. The 'footer' location is generated by [`tab_source_note()`](`great_tables.GT.tab_source_note`). From e9fc9e38be997d061ff88b2bb6837a15b5949176 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 1 Oct 2024 15:11:09 -0400 Subject: [PATCH 22/22] Tweak docstring titles for Loc* classes --- great_tables/_locations.py | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/great_tables/_locations.py b/great_tables/_locations.py index b9fb2472a..11c52d40f 100644 --- a/great_tables/_locations.py +++ b/great_tables/_locations.py @@ -52,7 +52,7 @@ class Loc: @dataclass class LocHeader(Loc): - """A location specification for targeting the table header (title and subtitle). + """Target the table header (title and subtitle). With `loc.header()`, we can target the table header which contains the title and the subtitle. This is useful for applying custom styling with the @@ -93,7 +93,7 @@ class LocHeader(Loc): @dataclass class LocTitle(Loc): - """A location specification for targeting the table title. + """Target the table title. With `loc.title()`, we can target the part of table containing the title (within the table header). This is useful for applying custom styling with the @@ -134,7 +134,7 @@ class LocTitle(Loc): @dataclass class LocSubTitle(Loc): - """A location specification for targeting the table subtitle. + """Target the table subtitle. With `loc.subtitle()`, we can target the part of table containing the subtitle (within the table header). This is useful for applying custom styling with the @@ -175,7 +175,7 @@ class LocSubTitle(Loc): @dataclass class LocStubhead(Loc): - """A location specification for targeting the stubhead. + """Target the stubhead. With `loc.stubhead()`, we can target the part of table that resides both at the top of the stub and also beside the column header. This is useful for applying custom styling with the @@ -219,12 +219,12 @@ class LocStubhead(Loc): @dataclass class LocStubheadLabel(Loc): - """A location for targeting the stubhead label""" + """Target the stubhead label.""" @dataclass class LocColumnHeader(Loc): - """A location specification for column spanners and column labels. + """Target column spanners and column labels. With `loc.column_header()`, we can target the column header which contains all of the column labels and any spanner labels that are present. This is useful for applying custom styling with @@ -275,7 +275,7 @@ class LocColumnHeader(Loc): @dataclass class LocColumnLabels(Loc): - """A location specification for targeting column labels. + """Target column labels. With `loc.column_labels()`, we can target the cells containing the column labels. This is useful for applying custom styling with the [`tab_style()`](`great_tables.GT.tab_style`) method. That @@ -319,7 +319,7 @@ class LocColumnLabels(Loc): @dataclass class LocSpannerLabels(Loc): - """A location specification for targeting spanner labels. + """Target spanner labels. With `loc.spanner_labels()`, we can target the cells containing the spanner labels. This is useful for applying custom styling with the [`tab_style()`](`great_tables.GT.tab_style`) method. @@ -375,7 +375,7 @@ class LocSpannerLabels(Loc): @dataclass class LocStub(Loc): - """A location specification for targeting rows of the table stub. + """Target the table stub. With `loc.stub()` we can target the cells containing the row labels, which reside in the table stub. This is useful for applying custom styling with the @@ -428,7 +428,7 @@ class LocStub(Loc): @dataclass class LocRowGroups(Loc): - """A location specification for targeting row groups. + """Target row groups. With `loc.row_groups()` we can target the cells containing the row group labels, which span across the table body. This is useful for applying custom styling with the @@ -488,7 +488,7 @@ class LocSummaryLabel(Loc): @dataclass class LocBody(Loc): # TODO: these can be tidyselectors - """A location specification for targeting data cells in the table body. + """Target data cells in the table body. With `loc.body()`, we can target the data cells in the table body. This is useful for applying custom styling with the [`tab_style()`](`great_tables.GT.tab_style`) method. That method has a @@ -550,7 +550,7 @@ class LocSummary(Loc): @dataclass class LocFooter(Loc): - """A location specification for targeting the table footer. + """Target the table footer. With `loc.footer()` we can target the table's footer, which currently contains the source notes (and may contain a 'footnotes' location in the future). This is useful when applying custom @@ -588,12 +588,12 @@ class LocFooter(Loc): @dataclass class LocFootnotes(Loc): - """A location for targeting footnotes.""" + """Target the footnotes.""" @dataclass class LocSourceNotes(Loc): - """A location specification for targeting the source notes. + """Target the source notes. With `loc.source_notes()`, we can target the source notes in the table. This is useful when applying custom with the [`tab_style()`](`great_tables.GT.tab_style`) method. That method has a