From 699316938a403095c74738a685be34197d8d4ec3 Mon Sep 17 00:00:00 2001 From: Boqiang Date: Tue, 9 Jun 2026 14:36:46 +0200 Subject: [PATCH 1/3] fix(histogram): filter excess groups with warning - keep the most frequent groups when `max_groups` is exceeded - surface the warning through the histogram template logger - update histogram tests for the filtering path --- src/spac/templates/histogram_template.py | 32 +++++++----- src/spac/visualization.py | 34 ++++++++++--- tests/test_visualization/test_histogram.py | 58 ++++++++++++++++++---- 3 files changed, 92 insertions(+), 32 deletions(-) diff --git a/src/spac/templates/histogram_template.py b/src/spac/templates/histogram_template.py index 16294020..bb24fecd 100644 --- a/src/spac/templates/histogram_template.py +++ b/src/spac/templates/histogram_template.py @@ -12,6 +12,7 @@ """ import json import sys +import warnings from pathlib import Path from typing import Any, Dict, Union, Optional, Tuple, List import pandas as pd @@ -305,19 +306,24 @@ def run_from_json( hist_kwargs["facet_fig_height"] = fig_height hist_kwargs["facet_tick_rotation"] = x_rotate - result = histogram( - adata=adata, - feature=feature, - annotation=annotation, - layer=text_to_value(layer, "Original"), - group_by=group_by, - together=together, - ax=None, - x_log_scale=take_X_log, - y_log_scale=take_Y_log, - facet=facet, - **hist_kwargs, - ) + with warnings.catch_warnings(record=True) as caught_warnings: + warnings.simplefilter("always") + result = histogram( + adata=adata, + feature=feature, + annotation=annotation, + layer=text_to_value(layer, "Original"), + group_by=group_by, + together=together, + ax=None, + x_log_scale=take_X_log, + y_log_scale=take_Y_log, + facet=facet, + **hist_kwargs, + ) + for warning in caught_warnings: + if issubclass(warning.category, UserWarning): + logger.warning(str(warning.message)) fig = result["fig"] axs = result["axs"] diff --git a/src/spac/visualization.py b/src/spac/visualization.py index 6bfefed2..d8033e24 100644 --- a/src/spac/visualization.py +++ b/src/spac/visualization.py @@ -499,9 +499,11 @@ def histogram(adata, feature=None, annotation=None, layer=None, When `group_by` is provided, this optional key can be passed via `kwargs` (it is ignored otherwise): - - `max_groups`: Controls the group-count guardrail for grouped plots. + - `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. When `facet=True`, these optional keys can be passed via `kwargs` to customize FacetGrid layout (they are ignored otherwise): @@ -635,6 +637,10 @@ def cal_bin_num( # Parse max_groups only for grouped plots; otherwise ignore it entirely. if group_by: max_groups = 20 if max_groups_raw is None else max_groups_raw + if max_groups <= 0: + raise ValueError( + f'`max_groups` should be a positive integer. Received "{max_groups}".' + ) else: max_groups = None @@ -799,20 +805,32 @@ def resolve_hist_axis_labels(data_column, x_log_scale, y_log_scale, stat): # Dispatch to grouped-together, grouped-separate, faceted, or # ungrouped plotting. if group_by: - groups = df[group_by].dropna().unique().tolist() + groups = plot_data[group_by].dropna().unique().tolist() n_groups = len(groups) if n_groups == 0: raise ValueError("There must be at least one group to create a" " histogram.") elif n_groups > max_groups: - raise ValueError( - "The number of groups in `group_by` exceeds `max_groups`: " - f"found {n_groups}, threshold {max_groups}.\n" - "Please reduce/bucket groups or use another grouping column, or " - "pass a larger `max_groups`.\n" - "See `kwargs` documentation for more details." + # Filter plot_data to the `max_groups` most frequent groups + group_counts = plot_data[group_by].value_counts( + sort=False + ).reindex(groups) + groups = group_counts.sort_values( + ascending=False, + kind='mergesort', + ).head(max_groups).index.tolist() + omitted_count = n_groups - max_groups + omitted_label = "group" if omitted_count == 1 else "groups" + warning_message = ( + f'The number of groups in "{group_by}" exceeds "max_groups": ' + f'found "{n_groups}", threshold "{max_groups}". ' + f'Plotting the {max_groups} most frequent groups and ' + f'omitting {omitted_count} {omitted_label}.' ) + warnings.warn(warning_message, UserWarning) + n_groups = len(groups) + plot_data = plot_data[plot_data[group_by].isin(groups)] if together: # 1) Grouped together on the same axes diff --git a/tests/test_visualization/test_histogram.py b/tests/test_visualization/test_histogram.py index d27c4f0e..cdc326b0 100644 --- a/tests/test_visualization/test_histogram.py +++ b/tests/test_visualization/test_histogram.py @@ -52,6 +52,23 @@ def _make_many_groups_adata(self, n_groups=25): var = pd.DataFrame(index=['marker1']) return anndata.AnnData(X, obs=obs, var=var) + def _make_ranked_many_groups_adata(self): + """Create uneven group sizes for max_groups filtering tests.""" + groups = ( + ['g2'] * 3 + + ['g0'] * 5 + + ['g3'] * 2 + + ['g1'] * 4 + + ['g4'] + ) + X = np.arange(1, len(groups) + 1, dtype=np.float32).reshape(-1, 1) + obs = pd.DataFrame( + {'many_groups': groups}, + index=[f'cell_{i}' for i in range(len(groups))], + ) + var = pd.DataFrame(index=['marker1']) + return anndata.AnnData(X, obs=obs, var=var) + def _make_long_label_facet_adata(self, include_short=False): """Create small categorical facet fixtures for long-label geometry tests.""" obs = { @@ -344,16 +361,28 @@ def test_group_by_separate_with_y_log_scale(self): self.assertEqual(ax.get_yscale(), 'log') self.assertEqual(ax.get_ylabel(), 'log(Count)') - def test_group_by_max_groups_default_guardrail_rejects_excess_groups(self): - """Default threshold should reject excessive grouped facet plotting.""" - adata = self._make_many_groups_adata(n_groups=25) - with self.assertRaisesRegex(ValueError, "exceeds `max_groups`"): - histogram( + def test_group_by_max_groups_filters_to_most_frequent_groups(self): + """Excessive grouped plots should keep the most frequent groups.""" + adata = self._make_ranked_many_groups_adata() + + with self.assertWarnsRegex( + UserWarning, + 'Plotting the 3 most frequent groups and omitting 2 groups.', + ): + fig, axs, df = histogram( adata, feature='marker1', group_by='many_groups', facet=True, - ) + max_groups=3, + ).values() + + axs = axs if isinstance(axs, (list, np.ndarray)) else [axs] + self.assertEqual(len(axs), 3) + self.assertEqual( + sorted(df['many_groups'].dropna().unique().tolist()), + ['g0', 'g1', 'g2'], + ) def test_group_by_max_groups_override_allows_grouped_plot(self): """Custom positive max_groups should allow larger grouped plots.""" @@ -370,17 +399,24 @@ def test_group_by_max_groups_override_allows_grouped_plot(self): axs = axs if isinstance(axs, (list, np.ndarray)) else [axs] self.assertEqual(len(axs), n_groups) - def test_group_by_max_groups_none_uses_default_threshold(self): - """Explicit None should resolve to default threshold behavior.""" + def test_group_by_max_groups_none_uses_default_filter_threshold(self): + """Explicit None should resolve to default filtering behavior.""" adata = self._make_many_groups_adata(n_groups=25) - with self.assertRaisesRegex(ValueError, "exceeds `max_groups`"): - histogram( + + with self.assertWarnsRegex( + UserWarning, + 'Plotting the 20 most frequent groups and omitting 5 groups.', + ): + fig, ax, df = histogram( adata, feature='marker1', group_by='many_groups', together=True, max_groups=None, - ) + ).values() + + self.assertIsInstance(ax, mpl.axes.Axes) + self.assertEqual(df['many_groups'].dropna().nunique(), 20) def test_non_grouped_max_groups_is_ignored(self): """Non-grouped calls should ignore grouped-only max_groups hints.""" From af99c25df2440e6eb502922baf6aff7daaf5020d Mon Sep 17 00:00:00 2001 From: Boqiang Date: Tue, 30 Jun 2026 15:04:48 -0400 Subject: [PATCH 2/3] fix(histogram): align title ownership - Use compact table-aware histogram titles in core and template paths - Preserve core-owned panel titles for multi-axis outputs - Add template smoke coverage for figure title output - Update core title expectations for the revised wording --- src/spac/templates/histogram_template.py | 44 +++++++--------------- src/spac/visualization.py | 22 ++++++----- tests/templates/test_histogram_template.py | 12 ++++++ tests/test_visualization/test_histogram.py | 15 ++++++-- 4 files changed, 51 insertions(+), 42 deletions(-) diff --git a/src/spac/templates/histogram_template.py b/src/spac/templates/histogram_template.py index bb24fecd..c39c72bc 100644 --- a/src/spac/templates/histogram_template.py +++ b/src/spac/templates/histogram_template.py @@ -373,37 +373,21 @@ def run_from_json( label.set_rotation_mode('anchor') label.set_horizontalalignment('right') - # Set titles based on group_by and facet - if text_to_value(group_by): - if together: - for ax in axes: - ax.set_title( - f'Histogram of "{x_var}" grouped by "{group_by}"' - ) - else: - # compute unique groups directly from adata.obs. - unique_groups = adata.obs[ - text_to_value(group_by) - ].dropna().unique() - if len(axes) != len(unique_groups): - logger.warning( - "Number of axes does not match number of " - "groups. Titles may not correspond correctly." - ) - if facet: - fig.suptitle( - f'Histogram of "{x_var}" faceted by "{group_by}"' - ) - ax_title_prefix = f'Group' - else: - ax_title_prefix = f'Histogram of "{x_var}" for group' - for ax, grp in zip(axes, unique_groups): - ax.set_title( - f'{ax_title_prefix}: "{grp}"' - ) + # Set figure-level titles base on data type, table and group_by. + # 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 and together: + histogram_title += f' grouped by "{group_by}"' + elif facet: + histogram_title += f' faceted by "{group_by}"' + if len(axes) == 1: + axes[0].set_title(histogram_title) else: - for ax in axes: - ax.set_title(f'Count plot of "{x_var}"') + fig.suptitle(histogram_title) # Adjust layout to prevent title overlap if facet: diff --git a/src/spac/visualization.py b/src/spac/visualization.py index d8033e24..5c0f5b39 100644 --- a/src/spac/visualization.py +++ b/src/spac/visualization.py @@ -862,9 +862,16 @@ def resolve_hist_axis_labels(data_column, x_log_scale, y_log_scale, stat): **kwargs, ) - # If plotting feature specify which layer if feature: - ax.set_title(f'Layer: {layer}') + ax.set_title( + f'Histogram of "{data_column}" (table: "{layer}") ' + f'grouped by "{group_by}"' + ) + else: + ax.set_title( + f'Histogram of annotation "{data_column}" grouped by ' + f'"{group_by}"' + ) axs.append(ax) else: @@ -892,11 +899,7 @@ def resolve_hist_axis_labels(data_column, x_log_scale, y_log_scale, stat): sns.histplot(data=hist_data, x="bin_center", ax=ax_i, weights='count', **kwargs) - # If plotting feature specify which layer - if feature: - ax_i.set_title(f'{groups[i]} with Layer: {layer}') - else: - ax_i.set_title(f'{groups[i]}') + ax_i.set_title(f'{groups[i]}') axs.append(ax_i) else: @@ -995,9 +998,10 @@ def resolve_hist_axis_labels(data_column, x_log_scale, y_log_scale, stat): **kwargs ) - # If plotting feature specify which layer + ax_title = f'Histogram of "{data_column}"' if feature: - ax.set_title(f'Layer: {layer}') + ax_title += f' (table: "{layer}")' + ax.set_title(ax_title) axs.append(ax) # Determine axis labels based on scale and stat settings. diff --git a/tests/templates/test_histogram_template.py b/tests/templates/test_histogram_template.py index 426e386f..b7fd6e34 100644 --- a/tests/templates/test_histogram_template.py +++ b/tests/templates/test_histogram_template.py @@ -110,6 +110,18 @@ def test_histogram_produces_expected_outputs(self) -> None: self.assertTrue(csv_path.exists()) self.assertGreater(csv_path.stat().st_size, 0) + def test_histogram_returns_figure_title(self) -> None: + """Verify in-memory template output includes a figure title.""" + fig, _ = run_from_json( + self.json_file, + save_to_disk=False, + show_plot=False, + output_dir=self.tmp_dir.name, + ) + + self.assertIsNotNone(fig._suptitle) + self.assertTrue(fig._suptitle.get_text()) + if __name__ == "__main__": unittest.main() diff --git a/tests/test_visualization/test_histogram.py b/tests/test_visualization/test_histogram.py index cdc326b0..1ac69dc6 100644 --- a/tests/test_visualization/test_histogram.py +++ b/tests/test_visualization/test_histogram.py @@ -258,21 +258,30 @@ def test_title(self): self.adata, feature='marker1' ).values() - self.assertEqual(ax.get_title(), 'Layer: Original') + self.assertEqual( + ax.get_title(), + 'Histogram of "marker1" (table: "Original")' + ) fig, ax, df = histogram( self.adata, feature='marker1', layer='Default' ).values() - self.assertEqual(ax.get_title(), f'Layer: Default') + self.assertEqual( + ax.get_title(), + 'Histogram of "marker1" (table: "Default")' + ) fig, ax, df = histogram( self.adata, annotation='annotation1', layer='Default' ).values() - self.assertEqual(ax.get_title(), '') + self.assertEqual( + ax.get_title(), + 'Histogram of "annotation1"' + ) def test_y_log_scale_axis(self): """Test that y_log_scale sets y-axis to log scale.""" From 60a36188daf45c4e7d0ed346c27bde4b3c1a4924 Mon Sep 17 00:00:00 2001 From: Boqiang Date: Mon, 3 Aug 2026 12:30:56 -0400 Subject: [PATCH 3/3] feat(histogram): add filtered title context - Pass filtering metadata from core histogram output to templates. - Add grouped and faceted top-N title suffixes. - Expand title examples and filtering assertions. --- src/spac/templates/histogram_template.py | 14 ++- src/spac/visualization.py | 19 ++- tests/templates/test_histogram_template.py | 128 ++++++++++++++++++--- tests/test_visualization/test_histogram.py | 11 ++ 4 files changed, 154 insertions(+), 18 deletions(-) diff --git a/src/spac/templates/histogram_template.py b/src/spac/templates/histogram_template.py index c39c72bc..2f282b75 100644 --- a/src/spac/templates/histogram_template.py +++ b/src/spac/templates/histogram_template.py @@ -380,10 +380,16 @@ def run_from_json( layer = text_to_value(layer, "Original") if layer: histogram_title += f' (table: "{layer}")' - if group_by and together: - histogram_title += f' grouped by "{group_by}"' - elif facet: - histogram_title += f' faceted by "{group_by}"' + if group_by: + organizing_label = "faceted by" if facet else "grouped by" + histogram_title += f' {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/src/spac/visualization.py b/src/spac/visualization.py index 5c0f5b39..6d1afc46 100644 --- a/src/spac/visualization.py +++ b/src/spac/visualization.py @@ -526,6 +526,8 @@ def histogram(adata, feature=None, annotation=None, layer=None, df : pandas.DataFrame DataFrame containing the data used for plotting the histogram. + When groups are filtered, ``df.attrs['spac_histogram_filter']`` + contains the displayed and original group counts. """ @@ -804,6 +806,7 @@ def resolve_hist_axis_labels(data_column, x_log_scale, y_log_scale, stat): # Dispatch to grouped-together, grouped-separate, faceted, or # ungrouped plotting. + filter_metadata = None if group_by: groups = plot_data[group_by].dropna().unique().tolist() n_groups = len(groups) @@ -820,6 +823,9 @@ def resolve_hist_axis_labels(data_column, x_log_scale, y_log_scale, stat): ascending=False, kind='mergesort', ).head(max_groups).index.tolist() + plot_data = plot_data[plot_data[group_by].isin(groups)] + + # Emit a warning about the group filtering omitted_count = n_groups - max_groups omitted_label = "group" if omitted_count == 1 else "groups" warning_message = ( @@ -829,8 +835,15 @@ def resolve_hist_axis_labels(data_column, x_log_scale, y_log_scale, stat): f'omitting {omitted_count} {omitted_label}.' ) warnings.warn(warning_message, UserWarning) + + # Store metadata about the filtering for downstream use + filter_metadata = { + "filtered": True, + "shown": max_groups, + "total": n_groups, + "group_by": group_by, + } n_groups = len(groups) - plot_data = plot_data[plot_data[group_by].isin(groups)] if together: # 1) Grouped together on the same axes @@ -1031,6 +1044,10 @@ def resolve_hist_axis_labels(data_column, x_log_scale, y_log_scale, stat): fig.supxlabel(xlabel) fig.supylabel(ylabel) + # Add metadata to the histogram DataFrame if groups were filtered + if filter_metadata is not None: + hist_data.attrs["spac_histogram_filter"] = filter_metadata + if len(axs) == 1: return {"fig": fig, "axs": axs[0], "df": hist_data} else: diff --git a/tests/templates/test_histogram_template.py b/tests/templates/test_histogram_template.py index b7fd6e34..49ba99f2 100644 --- a/tests/templates/test_histogram_template.py +++ b/tests/templates/test_histogram_template.py @@ -2,7 +2,7 @@ """ Real (non-mocked) unit test for the Histogram template. -Validates template I/O behaviour only. +Validates template I/O and title behaviour. No mocking. Uses real data, real filesystem, and tempfile. """ @@ -29,10 +29,13 @@ def _make_tiny_adata() -> ad.AnnData: - """Minimal AnnData: 4 cells, 2 genes for histogram plotting.""" + """Minimal AnnData with separate plotted and grouping annotations.""" rng = np.random.default_rng(42) X = rng.integers(1, 10, size=(4, 2)).astype(float) - obs = pd.DataFrame({"cell_type": ["A", "B", "A", "B"]}) + obs = pd.DataFrame({ + "cell_type": ["A", "B", "A", "B"], + "batch": ["X", "X", "Y", "Y"], + }) var = pd.DataFrame(index=["Gene_0", "Gene_1"]) return ad.AnnData(X=X, obs=obs, var=var) @@ -50,8 +53,6 @@ def setUp(self) -> None: params = { "Upstream_Analysis": self.in_file, "Annotation": "cell_type", - "Group_by": "cell_type", - "Together": False, "Table_to_Visualize": "Original", "Feature_s_to_Plot": ["All"], "Figure_Title": "Test Histogram", @@ -61,8 +62,6 @@ def setUp(self) -> None: "Figure_DPI": 72, "Font_Size": 10, "Number_of_Bins": 20, - "Facet": True, - "Facet_Ncol": 1, "Output_Directory": self.tmp_dir.name, "outputs": { "dataframe": {"type": "file", "name": "dataframe.csv"}, @@ -110,17 +109,120 @@ def test_histogram_produces_expected_outputs(self) -> None: self.assertTrue(csv_path.exists()) self.assertGreater(csv_path.stat().st_size, 0) - def test_histogram_returns_figure_title(self) -> None: - """Verify in-memory template output includes a figure title.""" - fig, _ = run_from_json( - self.json_file, + def _run_with_params(self, **updates): + with open(self.json_file) as f: + params = json.load(f) + params.update(updates) + return run_from_json( + params, save_to_disk=False, show_plot=False, output_dir=self.tmp_dir.name, ) - self.assertIsNotNone(fig._suptitle) - self.assertTrue(fig._suptitle.get_text()) + def test_histogram_title_variants(self) -> None: + """Cover feature, annotation, and grouping title variants.""" + # Plot the cell-type annotation, separated into one facet per batch. + fig, _ = self._run_with_params( + Plot_By="Annotation", + Annotation="cell_type", + Group_by="batch", + Together=False, + Facet=True, + Max_Groups=2, + ) + self.assertEqual( + fig._suptitle.get_text(), + 'Histogram of "cell_type" faceted by "batch"', + ) + + fig, _ = self._run_with_params( + Plot_By="Feature", + Feature="Gene_0", + Annotation="None", + Group_by="cell_type", + Together=True, + Facet=False, + Max_Groups=2, + ) + self.assertEqual( + fig.axes[0].get_title(), + 'Histogram of "Gene_0" grouped by "cell_type"', + ) + + fig, _ = self._run_with_params( + Plot_By="Annotation", + Annotation="cell_type", + Group_by="batch", + Facet=False, + Together=True, + Max_Groups=2, + ) + self.assertEqual( + fig.axes[0].get_title(), + 'Histogram of "cell_type" grouped by "batch"', + ) + + fig, _ = self._run_with_params( + Plot_By="Annotation", + Annotation="cell_type", + Group_by="batch", + Facet=False, + Together=False, + Max_Groups=2, + ) + self.assertEqual( + fig._suptitle.get_text(), + 'Histogram of "cell_type" grouped by "batch"', + ) + + 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. + fig, _ = self._run_with_params( + Plot_By="Annotation", + Annotation="cell_type", + Group_by="batch", + Facet=False, + Together=True, + Max_Groups=1, + ) + self.assertEqual( + fig.axes[0].get_title(), + 'Histogram of "cell_type" grouped by "batch" ' + '(top 1 of 2 groups)', + ) + + fig, _ = self._run_with_params( + Plot_By="Annotation", + Annotation="cell_type", + Group_by="batch", + Together=False, + Facet=True, + Max_Groups=1, + ) + self.assertEqual( + fig.axes[0].get_title(), + 'Histogram of "cell_type" faceted by "batch" ' + '(top 1 of 2 facets)', + ) + + def test_unfiltered_histogram_titles_omit_suffix(self) -> None: + """Titles omit the suffix when all available groups are shown.""" + # The fixture has exactly two batch annotations, X and Y. + + fig, _ = self._run_with_params( + Plot_By="Annotation", + Annotation="cell_type", + Group_by="batch", + Facet=False, + Together=True, + Max_Groups=2, + ) + self.assertEqual( + fig.axes[0].get_title(), + 'Histogram of "cell_type" grouped by "batch"', + ) if __name__ == "__main__": diff --git a/tests/test_visualization/test_histogram.py b/tests/test_visualization/test_histogram.py index 1ac69dc6..ddd89b87 100644 --- a/tests/test_visualization/test_histogram.py +++ b/tests/test_visualization/test_histogram.py @@ -392,6 +392,15 @@ def test_group_by_max_groups_filters_to_most_frequent_groups(self): sorted(df['many_groups'].dropna().unique().tolist()), ['g0', 'g1', 'g2'], ) + self.assertEqual( + df.attrs['spac_histogram_filter'], + { + 'filtered': True, + 'shown': 3, + 'total': 5, + 'group_by': 'many_groups', + }, + ) def test_group_by_max_groups_override_allows_grouped_plot(self): """Custom positive max_groups should allow larger grouped plots.""" @@ -426,6 +435,8 @@ def test_group_by_max_groups_none_uses_default_filter_threshold(self): self.assertIsInstance(ax, mpl.axes.Axes) self.assertEqual(df['many_groups'].dropna().nunique(), 20) + self.assertEqual(df.attrs['spac_histogram_filter']['shown'], 20) + self.assertEqual(df.attrs['spac_histogram_filter']['total'], 25) def test_non_grouped_max_groups_is_ignored(self): """Non-grouped calls should ignore grouped-only max_groups hints."""