fix: raise ValueError when combat batch has fewer than 2 cells

Previously, `sc.pp.combat` would silently produce NaN values when a
batch contained only 1 cell, because within-batch variance cannot be
estimated from a single observation. This adds input validation to
raise a clear error before computation begins.

Closes #1175

Author: LiudengZhang

docs/release-notes/1175.fix.md

@@ -0,0 +1 @@
+{func}`scanpy.pp.combat` now raises a {class}`ValueError` when a batch contains fewer than 2 cells, instead of silently producing NaN values in the corrected data {smaller}`L Zhang`

src/scanpy/preprocessing/_combat.py

@@ -206,6 +206,22 @@ def combat(  # noqa: PLR0915
     batch_info = model.groupby(key, observed=True).indices.values()
     n_batch = len(batch_info)
     n_batches = np.array([len(v) for v in batch_info])
+
+    # check for batches with fewer than 2 cells
+    small_batches = [
+        batch
+        for batch, size in zip(
+            model.groupby(key, observed=True).indices, n_batches, strict=True
+        )
+        if size < 2
+    ]
+    if small_batches:
+        msg = (
+            f"Batches {small_batches!r} have fewer than 2 cells. "
+            "ComBat requires at least 2 cells per batch to estimate "
+            "within-batch variance. Filter these batches before running combat."
+        )
+        raise ValueError(msg)
     n_array = float(sum(n_batches))
 
     # standardize across genes using a pooled variance estimator

tests/test_combat.py

@@ -75,6 +75,20 @@ def test_combat_obs_names():
     assert_equal(a, b)
 
 
+def test_combat_single_cell_batch():
+    """Test that combat raises an error when a batch has fewer than 2 cells.
+
+    Regression test for https://github.com/scverse/scanpy/issues/1175
+    """
+    adata = sc.datasets.blobs()
+    # Create a batch where one category has only 1 cell
+    batch = pd.Categorical(["single"] + ["other"] * (adata.n_obs - 1))
+    adata.obs["batch"] = batch
+
+    with pytest.raises(ValueError, match="fewer than 2 cells"):
+        sc.pp.combat(adata, key="batch")
+
+
 def test_silhouette():
     # this test checks wether combat can align data from several gaussians
     # it checks this by computing the silhouette coefficient in a pca embedding