diff --git a/src/spac/templates/histogram_template.py b/src/spac/templates/histogram_template.py index 16294020..2f282b75 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"] @@ -367,37 +373,27 @@ 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: + 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: - 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 6bfefed2..6d1afc46 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): @@ -524,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. """ @@ -635,6 +639,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 @@ -798,21 +806,44 @@ 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 = 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() + 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 = ( + 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) + + # 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) if together: # 1) Grouped together on the same axes @@ -844,9 +875,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: @@ -874,11 +912,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: @@ -977,9 +1011,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. @@ -1009,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 426e386f..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,6 +109,121 @@ def test_histogram_produces_expected_outputs(self) -> None: self.assertTrue(csv_path.exists()) self.assertGreater(csv_path.stat().st_size, 0) + 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, + ) + + 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__": unittest.main() diff --git a/tests/test_visualization/test_histogram.py b/tests/test_visualization/test_histogram.py index d27c4f0e..ddd89b87 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 = { @@ -241,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.""" @@ -344,16 +370,37 @@ 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'], + ) + 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.""" @@ -370,17 +417,26 @@ 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) + 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."""