docs: add warning for rank_genes_groups

docs/conf.py

@@ -136,6 +136,7 @@
     cycler=("https://matplotlib.org/cycler/", None),
     dask=("https://docs.dask.org/en/stable/", None),
     dask_ml=("https://ml.dask.org/", None),
+    decoupler=("https://decoupler.readthedocs.io/en/stable/", None),
     fast_array_utils=(
         "https://icb-fast-array-utils.readthedocs-hosted.com/en/stable/",
         None,
@@ -150,6 +151,7 @@
     networkx=("https://networkx.org/documentation/stable/", None),
     numpy=("https://numpy.org/doc/stable/", None),
     pandas=("https://pandas.pydata.org/pandas-docs/stable/", None),
+    pydeseq2=("https://pydeseq2.readthedocs.io/en/stable/", None),
     pynndescent=("https://pynndescent.readthedocs.io/en/latest/", None),
     pytest=("https://docs.pytest.org/en/latest/", None),
     python=(

docs/references.bib

@@ -829,6 +829,21 @@ @article{Soneson2018
   pages     = {255--261},
 }
 
+@article{Squair2021,
+  author    = {Squair, Jordan W. and Gautier, Matthieu and Kathe, Claudia and Anderson, Mark A. and James, Nicholas D. and Hutson, Thomas H. and Hudelle, Rémi and Qaiser, Taha and Matson, Kaya J. E. and Barraud, Quentin and Levine, Ariel J. and La Manno, Gioele and Skinnider, Michael A. and Courtine, Grégoire},
+  title     = {Confronting false discoveries in single-cell differential expression},
+  volume    = {12},
+  issn      = {2041-1723},
+  url       = {https://doi.org/10.1038/s41467-021-25960-2},
+  doi       = {10.1038/s41467-021-25960-2},
+  number    = {1},
+  journal   = {Nature Communications},
+  publisher = {Springer Science and Business Media LLC},
+  year      = {2021},
+  month     = {sep},
+  pages     = {5692},
+}
+
 @article{Stuart2019,
   author    = {Stuart, Tim and Butler, Andrew and Hoffman, Paul and Hafemeister, Christoph and Papalexi, Efthymia and Mauck, William M. and Hao, Yuhan and Stoeckius, Marlon and Smibert, Peter and Satija, Rahul},
   title     = {Comprehensive Integration of Single-Cell Data},

docs/release-notes/3700.feat.md

@@ -1 +1 @@
-Make {func}`scanpy.get.aggregate` `dask` compatible with all aggregations except median. {smaller}`I Gold`
+Make {func}`scanpy.get.aggregate` :doc:`dask:index` compatible with all aggregations except median. {smaller}`I Gold`

docs/release-notes/3792.docs.md

@@ -0,0 +1 @@
+Add a warning message to :func:`~scanpy.tl.rank_genes_groups` that it is not appropriate for most use-cases.

src/scanpy/tools/_rank_genes_groups.py

@@ -526,6 +526,15 @@ def rank_genes_groups(  # noqa: PLR0912, PLR0913, PLR0915
 
     Expects logarithmized data.
 
+    ..  warning::
+
+        Comparing between cells leads to highly inflated p-values,
+        since cells are not independent observations :cite:p`Squair2021`.
+        Especially in single-cell data, consider instead to use more appropriate methods such as combining pseudobulking with :doc:`pydeseq2:index`.
+
+        :func:`decoupler.pp.pseudobulk` or :func:`scanpy.get.aggregate` can be used to aggregate samples for pseudobulking.
+        Ours is a bit more verbose, but supports :doc:`dask:index` arrays for more effective memory usage.
+
     Parameters
     ----------
     adata