(feat): Aggregation via group-by in sc.get (#2590)

docs/api/get.md

@@ -19,5 +19,6 @@ useful formats.
    get.obs_df
    get.var_df
    get.rank_genes_groups_df
+   get.aggregate
 
 ```

docs/release-notes/1.10.0.md

@@ -15,6 +15,7 @@
 * Enhanced dask support for some internal utilities, paving the way for more extensive dask support {pr}`2696` {smaller}`P Angerer`
 * {func}`scanpy.pp.pca`, {func}`scanpy.pp.scale`, {func}`scanpy.pl.embedding`, and {func}`scanpy.experimental.pp.normalize_pearson_residuals_pca`
   now support a `mask` parameter {pr}`2272` {smaller}`C Bright, T Marcella, & P Angerer`
+* New function {func}`scanpy.get.aggregate` which allows grouped aggregations over your data. Useful for pseudobulking! {pr}`2590` {smaller}`Isaac Virshup` {smaller}`Ilan Gold` {smaller}`Jon Bloom`
 * {func}`scanpy.tl.rank_genes_groups` no longer warns that it's default was changed from t-test_overestim_var to t-test {pr}`2798` {smaller}`L Heumos`
 * {func}`scanpy.tl.leiden` now offers `igraph`'s implementation of the leiden algorithm via  via `flavor` when set to `igraph`.  `leidenalg`'s implementation is still default, but discouraged.  {pr}`2815` {smaller}`I Gold`
 * {func}`scanpy.pp.highly_variable_genes` has new flavor `seurat_v3_paper` that is in its implementation consistent with the paper description in Stuart et al 2018. {pr}`2792` {smaller}`E Roellin`

scanpy/_utils/__init__.py

@@ -874,3 +874,13 @@ def _choose_graph(adata, obsp, neighbors_key):
                 "to compute a neighborhood graph."
             )
         return neighbors["connectivities"]
+
+
+def _resolve_axis(
+    axis: Literal["obs", 0, "var", 1],
+) -> tuple[Literal[0], Literal["obs"]] | tuple[Literal[1], Literal["var"]]:
+    if axis in {0, "obs"}:
+        return (0, "obs")
+    if axis in {1, "var"}:
+        return (1, "var")
+    raise ValueError(f"`axis` must be either 0, 1, 'obs', or 'var', was {axis!r}")

scanpy/get/__init__.py

@@ -1,7 +1,6 @@
-# Public
-# Private
 from __future__ import annotations
 
+from ._aggregated import aggregate
 from .get import (
     _check_mask,
     _get_obs_rep,
@@ -15,6 +14,7 @@
     "_check_mask",
     "_get_obs_rep",
     "_set_obs_rep",
+    "aggregate",
     "obs_df",
     "rank_genes_groups_df",
     "var_df",