feat: add n_obs_aggregated column to aggregated AnnData output

docs/release-notes/3824.feat.md

@@ -0,0 +1 @@
+Add n\_obs\_aggregated to sc.get.aggregate output to show the total number of observations aggregated per group.

src/scanpy/get/_aggregated.py

@@ -295,6 +295,10 @@ def aggregate(  # noqa: PLR0912
 
     dim_df = getattr(adata, axis_name)
     categorical, new_label_df = _combine_categories(dim_df, by)
+
+    # Add number of obs aggregated into each group
+    group_sizes = pd.Series(categorical).value_counts().reindex(new_label_df.index)
+    new_label_df["n_obs_aggregated"] = group_sizes.values
     # Actual computation
     layers = _aggregate(
         data,

tests/test_aggregated.py

@@ -544,3 +544,38 @@ def test_factors():
 
     res = sc.get.aggregate(adata, by=["a", "b", "c", "d"], func="sum")
     np.testing.assert_equal(res.layers["sum"], adata.X)
+
+
+def test_aggregate_adds_n_obs_aggregated_single_key(pbmc_adata):
+    result = sc.get.aggregate(pbmc_adata, by="louvain", func="mean")
+    # Check column exists
+    assert "n_obs_aggregated" in result.obs
+    # Counts should be positive
+    assert (result.obs["n_obs_aggregated"] > 0).all()
+    # Total counts should equal original n_obs
+    assert result.obs["n_obs_aggregated"].sum() == pbmc_adata.n_obs
+
+
+def test_aggregate_adds_n_obs_aggregated_multiple_keys(pbmc_adata):
+    pbmc_adata.obs["percent_mito_binned"] = pd.cut(
+        pbmc_adata.obs["percent_mito"], bins=5
+    )
+    result = sc.get.aggregate(
+        pbmc_adata, by=["louvain", "percent_mito_binned"], func="mean"
+    )
+    assert "n_obs_aggregated" in result.obs
+    # Still sums back to the total number of obs
+    assert result.obs["n_obs_aggregated"].sum() == pbmc_adata.n_obs
+
+
+def test_aggregate_n_obs_aggregated_no_empty_groups(pbmc_adata):
+    # Force a categorical with unused categories
+    pbmc_adata.obs["fake_group"] = pd.Categorical(
+        ["A"] * (pbmc_adata.n_obs - 1) + ["B"], categories=["A", "B", "C"]
+    )
+    result = sc.get.aggregate(pbmc_adata, by="fake_group", func="mean")
+    assert "n_obs_aggregated" in result.obs
+    # Only groups with data should appear
+    assert set(result.obs["fake_group"]) == {"A", "B"}
+    # Count check
+    assert result.obs["n_obs_aggregated"].sum() == pbmc_adata.n_obs