feat: add Harmony to scanpy

benchmarks/benchmarks/tools.py

@@ -44,3 +44,9 @@ def time_rank_genes_groups(self) -> None:
 
     def peakmem_rank_genes_groups(self) -> None:
         sc.tl.rank_genes_groups(self.adata, "bulk_labels", method="wilcoxon")
+
+    def time_combat(self) -> None:
+        sc.pp.combat(self.adata, key="bulk_labels")
+
+    def peakmem_combat(self) -> None:
+        sc.pp.combat(self.adata, key="bulk_labels")

docs/api/preprocessing.md

@@ -47,18 +47,24 @@ For visual quality control, see {func}`~scanpy.pl.highest_expr_genes` and
    pp.recipe_seurat
 ```
 
-## Batch effect correction
+(pp-data-integration)=
 
-Also see {ref}`data-integration`. Note that a simple batch correction method is available via {func}`pp.regress_out`. Checkout {mod}`scanpy.external` for more.
+## Data integration
+
+Batch effect correction and other data integration.
+Note that a simple batch correction method is available via {func}`pp.regress_out`.
 
 ```{eval-rst}
 .. autosummary::
    :nosignatures:
    :toctree: generated/
 
    pp.combat
+   pp.harmony_integrate
 ```
 
+Also see {ref}`data integration tools <data-integration>` and external {ref}`external data integration <external-data-integration>`.
+
 ## Doublet detection
 
 ```{eval-rst}

docs/conf.py

@@ -176,6 +176,7 @@
     "pp.downsample_counts": (["np", "sp[csr]"], []),
     "pp.filter_cells": (["np", "sp", "da"], []),
     "pp.filter_genes": (["np", "sp", "da"], []),
+    "pp.harmony_integrate": (["np"], []),
     "pp.highly_variable_genes": (["np", "sp", "da"], ["da[sp[csc]]"]),
     "pp.log1p": (["np", "sp", "da"], []),
     "pp.neighbors": (["np", "sp"], []),

docs/extensions/array_support.py

@@ -7,6 +7,7 @@
 
 from docutils import nodes
 from sphinx.util.docutils import SphinxDirective
+from sphinx.util.typing import ExtensionMetadata
 
 from scanpy._utils import _docs
 
@@ -179,7 +180,8 @@ def one[T](arg: Collection[T]) -> T | None:
     return item
 
 
-def setup(app: Sphinx) -> None:
+def setup(app: Sphinx) -> ExtensionMetadata:
     """App setup hook."""
     app.add_directive("array-support", ArraySupport)
     app.add_config_value("array_support", {}, "env")
+    return ExtensionMetadata(parallel_read_safe=True)

docs/extensions/autosummary_skip_deprecated.py

@@ -4,6 +4,8 @@
 
 from typing import TYPE_CHECKING
 
+from sphinx.util.typing import ExtensionMetadata
+
 if TYPE_CHECKING:
     from typing import Literal
 
@@ -27,6 +29,7 @@ def skip_deprecated(  # noqa: PLR0917
     return None
 
 
-def setup(app: Sphinx) -> None:
+def setup(app: Sphinx) -> ExtensionMetadata:
     """App setup hook."""
     app.connect("autodoc-skip-member", skip_deprecated)
+    return ExtensionMetadata(parallel_read_safe=True)

docs/extensions/autosummary_skip_inherited.py

@@ -5,6 +5,8 @@
 from traceback import walk_stack
 from typing import TYPE_CHECKING
 
+from sphinx.util.typing import ExtensionMetadata
+
 if TYPE_CHECKING:
     from typing import Literal
 
@@ -54,6 +56,7 @@ def skip_inherited(  # noqa: PLR0917
     return True
 
 
-def setup(app: Sphinx) -> None:
+def setup(app: Sphinx) -> ExtensionMetadata:
     """App setup hook."""
     app.connect("autodoc-skip-member", skip_inherited)
+    return ExtensionMetadata(parallel_read_safe=True)

docs/extensions/canonical_tutorial.py

@@ -5,6 +5,7 @@
 from typing import TYPE_CHECKING
 
 from sphinx.util.docutils import SphinxDirective
+from sphinx.util.typing import ExtensionMetadata
 
 if TYPE_CHECKING:
     from typing import ClassVar
@@ -22,6 +23,7 @@ def run(self) -> list[nodes.Node]:  # noqa: D102
         return []
 
 
-def setup(app: Sphinx) -> None:
+def setup(app: Sphinx) -> ExtensionMetadata:
     """App setup hook."""
     app.add_directive("canonical-tutorial", CanonicalTutorial)
+    return ExtensionMetadata(parallel_read_safe=True)

docs/extensions/debug_docstrings.py

@@ -8,10 +8,12 @@
 from typing import TYPE_CHECKING
 
 import sphinx.ext.napoleon
+from sphinx.util.typing import ExtensionMetadata
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
 
+
 _pd_orig = sphinx.ext.napoleon._process_docstring
 
 
@@ -21,7 +23,8 @@ def pd_new(app, what, name, obj, options, lines) -> None:  # noqa: PLR0917
     print(*lines, sep="\n")
 
 
-def setup(app: Sphinx) -> None:
+def setup(app: Sphinx) -> ExtensionMetadata:
     """App setup hook."""
     if os.environ.get("DEBUG") is not None:
         sphinx.ext.napoleon._process_docstring = pd_new
+    return ExtensionMetadata(parallel_read_safe=True)

docs/extensions/function_images.py

@@ -5,6 +5,8 @@
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from sphinx.util.typing import ExtensionMetadata
+
 if TYPE_CHECKING:
     from typing import Any
 
@@ -27,7 +29,8 @@ def insert_function_images(  # noqa: PLR0917
     ]
 
 
-def setup(app: Sphinx) -> None:
+def setup(app: Sphinx) -> ExtensionMetadata:
     """App setup hook."""
     app.add_config_value("api_dir", Path(), "env")
     app.connect("autodoc-process-docstring", insert_function_images)
+    return ExtensionMetadata(parallel_read_safe=True)

docs/extensions/git_ref.py

@@ -7,6 +7,8 @@
 from functools import lru_cache
 from typing import TYPE_CHECKING
 
+from sphinx.util.typing import ExtensionMetadata
+
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
     from sphinx.config import Config
@@ -45,6 +47,7 @@ def set_ref(app: Sphinx, config: Config):
     app.config["html_theme_options"]["repository_branch"] = get() or "main"
 
 
-def setup(app: Sphinx) -> None:
+def setup(app: Sphinx) -> ExtensionMetadata:
     """App setup hook."""
     app.connect("config-inited", set_ref)
+    return ExtensionMetadata(parallel_read_safe=True)

docs/extensions/myst_ignore_mime_types.py

@@ -0,0 +1,83 @@
+"""Extension to patch ignored mime types."""
+
+from __future__ import annotations
+
+import sys
+from importlib.abc import MetaPathFinder
+from importlib.metadata import Distribution, EntryPoint, EntryPoints
+from types import MappingProxyType
+from typing import TYPE_CHECKING, override
+
+from myst_nb.core.render import MimeRenderPlugin
+from sphinx.util.typing import ExtensionMetadata
+
+if TYPE_CHECKING:
+    import os
+    from collections.abc import Iterable, Sequence
+    from importlib.machinery import ModuleSpec
+    from importlib.metadata import DistributionFinder, SimplePath
+    from types import ModuleType
+
+    from docutils import nodes
+    from myst_nb.core.render import MimeData, NbElementRenderer
+    from sphinx.application import Sphinx
+
+
+ignore: set[str] = set()
+
+
+class _Ignore(MimeRenderPlugin):
+    @override
+    @staticmethod
+    def handle_mime(
+        renderer: NbElementRenderer, data: MimeData, inline: bool
+    ) -> None | list[nodes.Element]:
+        if data.mime_type in ignore:
+            return []  # returning a list instead of `None` means “we handled it”
+        return None
+
+
+class _IgnoreMimeDist(Distribution):
+    metadata = MappingProxyType(dict(Name=__name__, Version="0.0.0"))
+
+    @override
+    def read_text(self, filename: str) -> str | None:
+        return None
+
+    @override
+    def locate_file(self, path: str | os.PathLike[str]) -> SimplePath:
+        raise RuntimeError
+
+    @property
+    @override
+    def entry_points(self) -> EntryPoints:
+        ep = EntryPoint("ignore", f"{__name__}:_Ignore", "myst_nb.mime_renderers")
+        return EntryPoints([ep])
+
+
+class _IgnoreMimeFinder(MetaPathFinder):
+    def find_spec(
+        self,
+        fullname: str,
+        path: Sequence[str] | None,
+        target: ModuleType | None = None,
+    ) -> ModuleSpec | None:
+        return None
+
+    def find_distributions(
+        self, context: DistributionFinder.Context | None
+    ) -> Iterable[Distribution]:
+        """Find fake distribution."""
+        yield _IgnoreMimeDist()
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    """App setup hook."""
+    global ignore  # noqa: PLW0603
+
+    app.add_config_value("myst_ignore_mime_types", [], "env")
+    ignore |= set(app.config.myst_ignore_mime_types)
+
+    sys.meta_path.append(_IgnoreMimeFinder())
+
+    return ExtensionMetadata(parallel_read_safe=True)

docs/extensions/param_police.py

@@ -6,10 +6,12 @@
 from typing import TYPE_CHECKING
 
 from sphinx.ext.napoleon import NumpyDocstring
+from sphinx.util.typing import ExtensionMetadata
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
 
+
 _format_docutils_params_orig = NumpyDocstring._format_docutils_params
 param_warnings = {}
 
@@ -46,7 +48,8 @@ def show_param_warnings(app, exception):
         raise RuntimeError(msg)
 
 
-def setup(app: Sphinx):
+def setup(app: Sphinx) -> ExtensionMetadata:
     """App setup hook."""
     NumpyDocstring._format_docutils_params = scanpy_log_param_types
     app.connect("build-finished", show_param_warnings)
+    return ExtensionMetadata(parallel_read_safe=True)

docs/external/preprocessing.md

@@ -5,6 +5,11 @@
 .. currentmodule:: scanpy.external
 ```
 
+Previously found here, but now part of scanpy’s main API:
+- {func}`scanpy.pp.harmony_integrate`
+- {func}`scanpy.pp.scrublet`
+- {func}`scanpy.pp.scrublet_simulate_doublets`
+
 (external-data-integration)=
 
 ## Data integration
@@ -14,10 +19,8 @@
    :toctree: ../generated/
 
    pp.bbknn
-   pp.harmony_integrate
    pp.mnn_correct
    pp.scanorama_integrate
-
 ```
 
 ## Sample demultiplexing
@@ -38,5 +41,4 @@ Note that the fundamental limitations of imputation are still under [debate](htt
    :toctree: ../generated/
 
    pp.magic
-
 ```

docs/references.bib

@@ -657,6 +657,16 @@ @article{Ntranos2019
   pages     = {163--166},
 }
 
+@article{Patikas2026,
+  author    = {Patikas, Nikolaos and Yao, Hongcheng and Madhu, Roopa and Raychaudhuri, Soumya and Hemberg, Martin and Korsunsky, Ilya},
+  title     = {Integration of large, complex single-cell datasets with Harmony2},
+  url       = {https://doi.org/10.1101/2026.03.16.711825},
+  doi       = {10.1101/2026.03.16.711825},
+  journal   = {bioRxiv},
+  publisher = {Cold Spring Harbor Laboratory},
+  year      = {2026},
+}
+
 @article{Paul2015,
   author    = {Paul, Franziska and Arkin, Ya’ara and Giladi, Amir and Jaitin, Diego Adhemar and Kenigsberg, Ephraim and Keren-Shaul, Hadas and Winter, Deborah and Lara-Astiaso, David and Gury, Meital and Weiner, Assaf and David, Eyal and Cohen, Nadav and Lauridsen, Felicia Kathrine Bratt and Haas, Simon and Schlitzer, Andreas and Mildner, Alexander and Ginhoux, Florent and Jung, Steffen and Trumpp, Andreas and Porse, Bo Torben and Tanay, Amos and Amit, Ido},
   title     = {Transcriptional Heterogeneity and Lineage Commitment in Myeloid Progenitors},

docs/release-notes/1.10.0.md

@@ -25,7 +25,7 @@ Some highlights:
 * {func}`scanpy.datasets.blobs` now accepts a `random_state` argument {pr}`2683` {smaller}`E Roellin`
 * {func}`scanpy.pp.pca` and {func}`scanpy.pp.regress_out` now accept a layer argument {pr}`2588` {smaller}`S Dicks`
 * {func}`scanpy.pp.subsample` with `copy=True` can now be called in backed mode {pr}`2624` {smaller}`E Roellin`
-* {func}`scanpy.external.pp.harmony_integrate` now runs with 64 bit floats improving reproducibility {pr}`2655` {smaller}`S Dicks`
+* {func}`scanpy.pp.harmony_integrate` now runs with 64 bit floats improving reproducibility {pr}`2655` {smaller}`S Dicks`
 * {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`
 * `scanpy.pp.calculate_qc_metrics` now allows `qc_vars` to be passed as a string {pr}`2859` {smaller}`N Teyssier`
 * {func}`scanpy.tl.leiden` and {func}`scanpy.tl.louvain` now store clustering parameters in the key provided by the `key_added` parameter instead of always writing to (or overwriting) a default key {pr}`2864` {smaller}`J Fan`