zboldyga · Oct 6, 2026 · Oct 6, 2026 · Oct 6, 2026 · Oct 6, 2026 · Oct 6, 2026
diff --git a/docs/api/deprecated.md b/docs/api/deprecated.md
@@ -13,8 +13,11 @@
    pp.recipe_weinreb17
    tl.louvain
    tl.sim
+   tl.rank_genes_groups
+   tl.filter_rank_genes_groups
    pl.sim
    queries.gene_coordinates
+   get.rank_genes_groups_df
    datasets.toggleswitch
    logging.print_versions
    read_loom

diff --git a/docs/api/get.md b/docs/api/get.md
@@ -19,7 +19,6 @@ useful formats.
    get.obs_df
    get.var_df
    get.pca
-   get.rank_genes_groups_df
    get.aggregate
 
 ```
diff --git a/docs/api/tools.md b/docs/api/tools.md
@@ -61,16 +61,50 @@ Compute densities on embeddings.
 
 ## Marker genes
 
+| Question | Use |
+| --- | --- |
+| Which genes distinguish a cluster or cell type from the others? | {mod}`scanpy.tl.markers` |
+| Which genes change between conditions (e.g. treated vs. control) within a cell type? | {func}`scanpy.tl.de.deseq2`, see {doc}`/tutorials/basics/differential-expression` |
+
+Rank genes that distinguish groups of cells (e.g. clusters), for example to annotate them.
+These fast tests treat every cell as an independent observation,
+so their p-values are only useful to order genes {cite:p}`Squair2021`.
+To plot the results, pass them to e.g. {func}`scanpy.pl.rank_genes_groups_dotplot` as `results=`.
+
+```{eval-rst}
+.. module:: scanpy.tl.markers
+.. currentmodule:: scanpy
+```
+
 ```{eval-rst}
 .. autosummary::
    :nosignatures:
    :toctree: generated/
 
-   tl.rank_genes_groups
-   tl.filter_rank_genes_groups
+   tl.markers.wilcoxon
+   tl.markers.ttest
+   tl.markers.logreg
    tl.marker_gene_overlap
 ```
 
+## Differential expression
+
+Test for expression changes between conditions (e.g. treated vs. control),
+using samples (e.g. donors) rather than cells as replicates.
+
+```{eval-rst}
+.. module:: scanpy.tl.de
+.. currentmodule:: scanpy
+```
+
+```{eval-rst}
+.. autosummary::
+   :nosignatures:
+   :toctree: generated/
+
+   tl.de.deseq2
+```
+
 ## Gene scores, Cell cycle
 
 ```{eval-rst}

diff --git a/docs/conf.py b/docs/conf.py
@@ -218,6 +218,9 @@
     "tl.ingest": (["np", "sp"], []),
     "tl.leiden": (["np", "sp"], []),  # only uses graph in obsp
     "tl.louvain": (["np", "sp"], []),  # only uses graph in obsp
+    "tl.markers.logreg": (["np", "sp"], []),
+    "tl.markers.ttest": (["np", "sp"], []),
+    "tl.markers.wilcoxon": (["np", "sp"], []),
     "tl.paga": (["np", "sp"], []),
     "tl.rank_genes_groups": (["np", "sp"], []),
     "tl.score_genes": (["np", "sp"], []),

diff --git a/docs/references.bib b/docs/references.bib
@@ -180,6 +180,21 @@ @article{Coifman2005
   pages     = {7426--7431},
 }
 
+@article{Crowell2020,
+  author    = {Crowell, Helena L. and Soneson, Charlotte and Germain, Pierre-Luc and Calini, Daniela and Collin, Ludovic and Raposo, Catarina and Malhotra, Dheeraj and Robinson, Mark D.},
+  title     = {muscat detects subpopulation-specific state transitions from multi-sample multi-condition single-cell transcriptomics data},
+  volume    = {11},
+  issn      = {2041-1723},
+  url       = {https://doi.org/10.1038/s41467-020-19894-4},
+  doi       = {10.1038/s41467-020-19894-4},
+  number    = {1},
+  journal   = {Nature Communications},
+  publisher = {Springer Science and Business Media LLC},
+  year      = {2020},
+  month     = {nov},
+  pages     = {6077},
+}
+
 @article{Csardi2006,
   author   = {Csárdi, G. and Nepusz, T.},
   added-at = {2011-03-14T01:02:14.000+0100},
@@ -416,6 +431,20 @@ @misc{Kang2018
   howpublished = {\url{https://github.com/chriscainx/mnnpy}},
 }
 
+@article{KangHM2018,
+  author    = {Kang, Hyun Min and Subramaniam, Meena and Targ, Sasha and Nguyen, Michelle and Maliskova, Lenka and McCarthy, Elizabeth and Wan, Eunice and Wong, Simon and Byrnes, Lauren and Lanata, Cristina M and Gate, Rachel E and Mostafavi, Sara and Marson, Alexander and Zaitlen, Noah and Criswell, Lindsey A and Ye, Chun Jimmie},
+  title     = {Multiplexed droplet single-cell RNA-sequencing using natural genetic variation},
+  volume    = {36},
+  issn      = {1546-1696},
+  url       = {https://doi.org/10.1038/nbt.4042},
+  doi       = {10.1038/nbt.4042},
+  number    = {1},
+  journal   = {Nature Biotechnology},
+  publisher = {Springer Science and Business Media LLC},
+  year      = {2018},
+  pages     = {89--94},
+}
+
 @article{Korsunsky2019,
   author    = {Korsunsky, Ilya and Millard, Nghia and Fan, Jean and Slowikowski, Kamil and Zhang, Fan and Wei, Kevin and Baglaenko, Yuriy and Brenner, Michael and Loh, Po-ru and Raychaudhuri, Soumya},
   title     = {Fast, sensitive and accurate integration of single-cell data with Harmony},
@@ -530,6 +559,21 @@ @article{Lotfollahi2019
   pages     = {715--721},
 }
 
+@article{Love2014,
+  author    = {Love, Michael I and Huber, Wolfgang and Anders, Simon},
+  title     = {Moderated estimation of fold change and dispersion for RNA-seq data with DESeq2},
+  volume    = {15},
+  issn      = {1474-760X},
+  url       = {https://doi.org/10.1186/s13059-014-0550-8},
+  doi       = {10.1186/s13059-014-0550-8},
+  number    = {12},
+  journal   = {Genome Biology},
+  publisher = {Springer Science and Business Media LLC},
+  year      = {2014},
+  month     = {dec},
+  pages     = {550},
+}
+
 @inproceedings{Luecken2021,
   author    = {Luecken, Malte and Burkhardt, Daniel and Cannoodt, Robrecht and Lance, Christopher and Agrawal, Aditi and Aliee, Hananeh and Chen, Ann and Deconinck, Louise and Detweiler, Angela and Granados, Alejandro and Huynh, Shelly and Isacco, Laura and Kim, Yang and Klein, Dominik and De Kumar, Bony and Kuppasani, Sunil and Lickert, Heiko and McGeever, Aaron and Melgarejo, Joaquin and Mekonen, Honey and Morri, Maurizio and Müller, Michaela and Neff, Norma and Paul, Sheryl and Rieck, Bastian and Schneider, Kaylie and Steelman, Scott and Sterr, Michael and Treacy, Daniel and Tong, Alexander and Villani, Alexandra-Chloe and Wang, Guilin and Yan, Jia and Zhang, Ce and Pisco, Angela and Krishnaswamy, Smita and Theis, Fabian and Bloom, Jonathan M},
   editor    = {Vanschoren, J. and Yeung, S.},
@@ -627,6 +671,21 @@ @article{Muraro2016
   pages     = {385--394.e3},
 }
 
+@article{Muzellec2023,
+  author    = {Muzellec, Boris and Teleńczuk, Maria and Cabeli, Vincent and Andreux, Mathieu},
+  title     = {PyDESeq2: a python package for bulk RNA-seq differential expression analysis},
+  volume    = {39},
+  issn      = {1367-4811},
+  url       = {https://doi.org/10.1093/bioinformatics/btad547},
+  doi       = {10.1093/bioinformatics/btad547},
+  number    = {9},
+  journal   = {Bioinformatics},
+  publisher = {Oxford University Press (OUP)},
+  year      = {2023},
+  month     = {sep},
+  pages     = {btad547},
+}
+
 @article{Nowotschin2019,
   author    = {Nowotschin, Sonja and Setty, Manu and Kuo, Ying-Yi and Liu, Vincent and Garg, Vidur and Sharma, Roshan and Simon, Claire S. and Saiz, Nestor and Gardner, Rui and Boutet, Stéphane C. and Church, Deanna M. and Hoodless, Pamela A. and Hadjantonakis, Anna-Katerina and Pe’er, Dana},
   title     = {The emergent landscape of the mouse gut endoderm at single-cell resolution},
@@ -736,6 +795,20 @@ @article{Polanski2019
   pages     = {964--965},
 }
 
+@article{Robinson2010,
+  author    = {Robinson, Mark D. and McCarthy, Davis J. and Smyth, Gordon K.},
+  title     = {edgeR: a Bioconductor package for differential expression analysis of digital gene expression data},
+  volume    = {26},
+  issn      = {1367-4803},
+  url       = {https://doi.org/10.1093/bioinformatics/btp616},
+  doi       = {10.1093/bioinformatics/btp616},
+  number    = {1},
+  journal   = {Bioinformatics},
+  publisher = {Oxford University Press (OUP)},
+  year      = {2010},
+  pages     = {139--140},
+}
+
 @article{Satija2015,
   author    = {Satija, Rahul and Farrell, Jeffrey A and Gennert, David and Schier, Alexander F and Regev, Aviv},
   doi       = {10.1038/nbt.3192},
@@ -1076,6 +1149,21 @@ @article{Zheng2017
   journal   = {Nature Communications},
 }
 
+@article{Zimmerman2021,
+  author    = {Zimmerman, Kip D. and Espeland, Mark A. and Langefeld, Carl D.},
+  title     = {A practical solution to pseudoreplication bias in single-cell studies},
+  volume    = {12},
+  issn      = {2041-1723},
+  url       = {https://doi.org/10.1038/s41467-021-21038-1},
+  doi       = {10.1038/s41467-021-21038-1},
+  number    = {1},
+  journal   = {Nature Communications},
+  publisher = {Springer Science and Business Media LLC},
+  year      = {2021},
+  month     = {feb},
+  pages     = {738},
+}
+
 @article{Zunder2015,
   author    = {Zunder, Eli R. and Lujan, Ernesto and Goltsev, Yury and Wernig, Marius and Nolan, Garry P.},
   title     = {A Continuous Molecular Roadmap to iPSC Reprogramming through Progression Analysis of Single-Cell Mass Cytometry},

diff --git a/docs/tutorials/basics/clustering-2017.ipynb b/docs/tutorials/basics/clustering-2017.ipynb
@@ -1261,6 +1261,18 @@
     "## Finding marker genes"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    ":::{note}\n",
+    "This tutorial uses {func}`~scanpy.tl.rank_genes_groups`, which is deprecated.\n",
+    "Use {mod}`scanpy.tl.markers` instead, e.g. `markers = sc.tl.markers.wilcoxon(adata, \"leiden\")`,\n",
+    "and pass the returned table to the `sc.pl.rank_genes_groups_*` plots as `results=markers`.\n",
+    "To compare conditions across samples, see {doc}`differential-expression`.\n",
+    ":::"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

diff --git a/docs/tutorials/basics/clustering.ipynb b/docs/tutorials/basics/clustering.ipynb