From a638f796abbf5bce95ffb31d60e4d86a93697b1f Mon Sep 17 00:00:00 2001 From: Boqiang Date: Wed, 4 Nov 2026 13:27:55 -0500 Subject: [PATCH 1/6] fix(histogram): wrap grouping details in histogram titles to a second line --- src/spac/templates/histogram_template.py | 2 +- tests/templates/test_histogram_template.py | 23 +++++++++++++--------- 2 files changed, 15 insertions(+), 10 deletions(-) diff --git a/src/spac/templates/histogram_template.py b/src/spac/templates/histogram_template.py index 2f282b75..a2d1199c 100644 --- a/src/spac/templates/histogram_template.py +++ b/src/spac/templates/histogram_template.py @@ -382,7 +382,7 @@ def run_from_json( histogram_title += f' (table: "{layer}")' if group_by: organizing_label = "faceted by" if facet else "grouped by" - histogram_title += f' {organizing_label} "{group_by}"' + histogram_title += f'\n{organizing_label} "{group_by}"' filter_metadata = df_counts.attrs.get("spac_histogram_filter", {}) if filter_metadata.get("filtered"): filter_label = "facets" if facet else "groups" diff --git a/tests/templates/test_histogram_template.py b/tests/templates/test_histogram_template.py index 49ba99f2..09b7bbc7 100644 --- a/tests/templates/test_histogram_template.py +++ b/tests/templates/test_histogram_template.py @@ -133,7 +133,8 @@ def test_histogram_title_variants(self) -> None: ) self.assertEqual( fig._suptitle.get_text(), - 'Histogram of "cell_type" faceted by "batch"', + 'Histogram of "cell_type"\n' + 'faceted by "batch"', ) fig, _ = self._run_with_params( @@ -147,7 +148,8 @@ def test_histogram_title_variants(self) -> None: ) self.assertEqual( fig.axes[0].get_title(), - 'Histogram of "Gene_0" grouped by "cell_type"', + 'Histogram of "Gene_0"\n' + 'grouped by "cell_type"', ) fig, _ = self._run_with_params( @@ -160,7 +162,8 @@ def test_histogram_title_variants(self) -> None: ) self.assertEqual( fig.axes[0].get_title(), - 'Histogram of "cell_type" grouped by "batch"', + 'Histogram of "cell_type"\n' + 'grouped by "batch"', ) fig, _ = self._run_with_params( @@ -173,7 +176,8 @@ def test_histogram_title_variants(self) -> None: ) self.assertEqual( fig._suptitle.get_text(), - 'Histogram of "cell_type" grouped by "batch"', + 'Histogram of "cell_type"\n' + 'grouped by "batch"', ) def test_filtered_histogram_titles_include_suffixes(self) -> None: @@ -189,8 +193,8 @@ def test_filtered_histogram_titles_include_suffixes(self) -> None: ) self.assertEqual( fig.axes[0].get_title(), - 'Histogram of "cell_type" grouped by "batch" ' - '(top 1 of 2 groups)', + 'Histogram of "cell_type"\n' + 'grouped by "batch" (top 1 of 2 groups)', ) fig, _ = self._run_with_params( @@ -203,8 +207,8 @@ def test_filtered_histogram_titles_include_suffixes(self) -> None: ) self.assertEqual( fig.axes[0].get_title(), - 'Histogram of "cell_type" faceted by "batch" ' - '(top 1 of 2 facets)', + 'Histogram of "cell_type"\n' + 'faceted by "batch" (top 1 of 2 facets)', ) def test_unfiltered_histogram_titles_omit_suffix(self) -> None: @@ -221,7 +225,8 @@ def test_unfiltered_histogram_titles_omit_suffix(self) -> None: ) self.assertEqual( fig.axes[0].get_title(), - 'Histogram of "cell_type" grouped by "batch"', + 'Histogram of "cell_type"\n' + 'grouped by "batch"', ) From cd33090433b01ebe01c8c9edd4d7a11dbd97148b Mon Sep 17 00:00:00 2001 From: Boqiang Date: Wed, 4 Nov 2026 13:28:47 -0500 Subject: [PATCH 2/6] test(histogram): assign explicit cell IDs to resolve pytest warning --- tests/templates/test_histogram_template.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/templates/test_histogram_template.py b/tests/templates/test_histogram_template.py index 09b7bbc7..da39a028 100644 --- a/tests/templates/test_histogram_template.py +++ b/tests/templates/test_histogram_template.py @@ -35,7 +35,7 @@ def _make_tiny_adata() -> ad.AnnData: obs = pd.DataFrame({ "cell_type": ["A", "B", "A", "B"], "batch": ["X", "X", "Y", "Y"], - }) + }, index=["cell_0", "cell_1", "cell_2", "cell_3"]) var = pd.DataFrame(index=["Gene_0", "Gene_1"]) return ad.AnnData(X=X, obs=obs, var=var) From 509c17aca008a08838cb8a8067e3a1e0936481f6 Mon Sep 17 00:00:00 2001 From: Boqiang Date: Wed, 4 Nov 2026 13:52:23 -0500 Subject: [PATCH 3/6] test(histogram): add test for template title of grouped data with custom layer --- tests/templates/test_histogram_template.py | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/tests/templates/test_histogram_template.py b/tests/templates/test_histogram_template.py index da39a028..0052d2df 100644 --- a/tests/templates/test_histogram_template.py +++ b/tests/templates/test_histogram_template.py @@ -37,7 +37,9 @@ def _make_tiny_adata() -> ad.AnnData: "batch": ["X", "X", "Y", "Y"], }, index=["cell_0", "cell_1", "cell_2", "cell_3"]) var = pd.DataFrame(index=["Gene_0", "Gene_1"]) - return ad.AnnData(X=X, obs=obs, var=var) + adata = ad.AnnData(X=X, obs=obs, var=var) + adata.layers["transformed"] = X.copy() + return adata class TestHistogramTemplate(unittest.TestCase): @@ -180,6 +182,21 @@ def test_histogram_title_variants(self) -> None: 'grouped by "batch"', ) + def test_grouped_feature_title_includes_named_table(self) -> None: + """Keep the named table and grouping on separate title lines.""" + fig, _ = self._run_with_params( + Plot_By="Feature", + Feature="Gene_0", + Table_="transformed", + Group_by="cell_type", + Together=True, + ) + self.assertEqual( + fig.axes[0].get_title(), + 'Histogram of "Gene_0" (table: "transformed")\n' + 'grouped by "cell_type"', + ) + def test_filtered_histogram_titles_include_suffixes(self) -> None: """Filtered grouped and faceted titles show the displayed counts.""" # The fixture has exactly two batch annotations, X and Y. From f46729465bf1c5b5a21202df173ee002d4afea7d Mon Sep 17 00:00:00 2001 From: Boqiang Date: Sun, 8 Nov 2026 18:01:34 -0500 Subject: [PATCH 4/6] feat(histogram_template): support custom figure titles --- src/spac/templates/histogram_template.py | 36 ++++++++++++---------- tests/templates/test_histogram_template.py | 36 +++++++++++++++++++++- 2 files changed, 55 insertions(+), 17 deletions(-) diff --git a/src/spac/templates/histogram_template.py b/src/spac/templates/histogram_template.py index a2d1199c..766d1574 100644 --- a/src/spac/templates/histogram_template.py +++ b/src/spac/templates/histogram_template.py @@ -100,6 +100,7 @@ def run_from_json( group_by = text_to_value(params.get("Group_by", "None")) max_groups = params.get("Max_Groups", 20) together = params.get("Together", True) + fig_title = text_to_value(params.get("Figure_Title")) fig_width = params.get("Figure_Width", "auto") fig_height = params.get("Figure_Height", "auto") font_size = params.get("Font_Size", 12) @@ -373,23 +374,26 @@ def run_from_json( label.set_rotation_mode('anchor') label.set_horizontalalignment('right') - # Set figure-level titles base on data type, table and group_by. + # Set the overall Histogram title. # Multi-axis panel titles are handled by core as it may filter groups. - histogram_title = f'Histogram of "{x_var}"' - if feature: - layer = text_to_value(layer, "Original") - if layer: - histogram_title += f' (table: "{layer}")' - if group_by: - organizing_label = "faceted by" if facet else "grouped by" - histogram_title += f'\n{organizing_label} "{group_by}"' - filter_metadata = df_counts.attrs.get("spac_histogram_filter", {}) - if filter_metadata.get("filtered"): - filter_label = "facets" if facet else "groups" - histogram_title += ( - f' (top {filter_metadata["shown"]} of ' - f'{filter_metadata["total"]} {filter_label})' - ) + histogram_title = fig_title + if histogram_title is None: + # Generate the default title from the plot and filtering settings. + histogram_title = f'Histogram of "{x_var}"' + if feature: + layer = text_to_value(layer, "Original") + if layer: + histogram_title += f' (table: "{layer}")' + if group_by: + organizing_label = "faceted by" if facet else "grouped by" + histogram_title += f'\n{organizing_label} "{group_by}"' + filter_metadata = df_counts.attrs.get("spac_histogram_filter", {}) + if filter_metadata.get("filtered"): + filter_label = "facets" if facet else "groups" + histogram_title += ( + f' (top {filter_metadata["shown"]} of ' + f'{filter_metadata["total"]} {filter_label})' + ) if len(axes) == 1: axes[0].set_title(histogram_title) else: diff --git a/tests/templates/test_histogram_template.py b/tests/templates/test_histogram_template.py index 0052d2df..e6223d01 100644 --- a/tests/templates/test_histogram_template.py +++ b/tests/templates/test_histogram_template.py @@ -57,7 +57,6 @@ def setUp(self) -> None: "Annotation": "cell_type", "Table_to_Visualize": "Original", "Feature_s_to_Plot": ["All"], - "Figure_Title": "Test Histogram", "Legend_Title": "Cell Type", "Figure_Width": 6, "Figure_Height": 4, @@ -246,6 +245,41 @@ def test_unfiltered_histogram_titles_omit_suffix(self) -> None: 'grouped by "batch"', ) + def test_custom_title_replaces_grouped_title(self) -> None: + """A custom title is used for a grouped figure.""" + fig, _ = self._run_with_params( + Plot_By="Feature", + Feature="Gene_0", + Group_by="cell_type", + Together=True, + Max_Groups=1, + Figure_Title="My histogram", + ) + self.assertEqual(fig.axes[0].get_title(), "My histogram") + + def test_custom_title_replaces_faceted_figure_title(self) -> None: + """A custom title is used for a figure with multiple facets.""" + fig, _ = self._run_with_params( + Plot_By="Annotation", + Annotation="cell_type", + Group_by="batch", + Together=False, + Facet=True, + Figure_Title="My faceted histogram", + ) + self.assertEqual(fig._suptitle.get_text(), "My faceted histogram") + + def test_none_like_custom_title_uses_generated_title(self) -> None: + """None-like figure titles fall back to the default title.""" + for title in (None, "None", "", " "): + with self.subTest(title=title): + fig, _ = self._run_with_params( + Plot_By="Feature", + Feature="Gene_0", + Figure_Title=title, + ) + self.assertEqual(fig.axes[0].get_title(), 'Histogram of "Gene_0"') + if __name__ == "__main__": unittest.main() From 4cd485e8d0af4c482dc0313da5ba9b38ed9d7d6e Mon Sep 17 00:00:00 2001 From: Boqiang Date: Sun, 8 Nov 2026 21:38:26 -0500 Subject: [PATCH 5/6] docs(histogram): clarify the policy of group filtering and titles --- src/spac/templates/histogram_template.py | 6 ++++++ src/spac/visualization.py | 5 +++-- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/src/spac/templates/histogram_template.py b/src/spac/templates/histogram_template.py index 766d1574..a00fc281 100644 --- a/src/spac/templates/histogram_template.py +++ b/src/spac/templates/histogram_template.py @@ -71,6 +71,12 @@ def run_from_json( dict or tuple If save_to_disk=True: Dictionary of saved file paths If save_to_disk=False: Tuple of (figure, dataframe) + + Notes + ----- + If ``Group_by`` has more than ``Max_Groups`` groups (default 20), only + the ``Max_Groups`` most frequent groups are plotted. This filtering is + indicated in the default title. """ # Set up logging logging.basicConfig(level=logging.INFO) diff --git a/src/spac/visualization.py b/src/spac/visualization.py index 6d1afc46..bdc264e5 100644 --- a/src/spac/visualization.py +++ b/src/spac/visualization.py @@ -502,8 +502,9 @@ def histogram(adata, feature=None, annotation=None, layer=None, - `max_groups`: Controls the group-count filter for grouped plots. Pass a positive integer, or omit it to use the default threshold of 20 groups. - If the number of groups exceeds this threshold, only the most - frequent groups are plotted and a warning is emitted. + If the number of groups exceeds this threshold, only the + `max_groups` most frequent groups are plotted and a warning + is emitted. When `facet=True`, these optional keys can be passed via `kwargs` to customize FacetGrid layout (they are ignored otherwise): From 10b448db3e4c53f0f641014007e3b47e25ec34dd Mon Sep 17 00:00:00 2001 From: Boqiang Date: Sun, 8 Nov 2026 21:38:40 -0500 Subject: [PATCH 6/6] style(histogram): wrap template test assertion --- tests/templates/test_histogram_template.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tests/templates/test_histogram_template.py b/tests/templates/test_histogram_template.py index e6223d01..b928436e 100644 --- a/tests/templates/test_histogram_template.py +++ b/tests/templates/test_histogram_template.py @@ -278,7 +278,9 @@ def test_none_like_custom_title_uses_generated_title(self) -> None: Feature="Gene_0", Figure_Title=title, ) - self.assertEqual(fig.axes[0].get_title(), 'Histogram of "Gene_0"') + self.assertEqual( + fig.axes[0].get_title(), 'Histogram of "Gene_0"' + ) if __name__ == "__main__":