chore: remove external tests and deprecate sc.external

docs/conf.py

@@ -161,6 +161,7 @@
     matplotlib=("https://matplotlib.org/stable/", None),
     networkx=("https://networkx.org/documentation/stable/", None),
     numpy=("https://numpy.org/doc/stable/", None),
+    palantir=("https://palantir.readthedocs.io/en/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),

docs/external/index.md

@@ -5,8 +5,8 @@
 .. module:: scanpy.external
 ```
 
-```{warning}
-We are no longer accepting new tools into `scanpy.external`.
+```{deprecated} 1.13.0
+`scanpy.external` is deprecated and will be removed in a future release.
 For tools that integrate well with scanpy and anndata, or to submit your own, see the [scverse ecosystem](https://scverse.org/packages/#ecosystem).
 ```
 

docs/release-notes/3645.chore.md

@@ -0,0 +1 @@
+Deprecate {mod}`scanpy.external` and each of its functions. Each function’s deprecation message names its replacement: an upstream package, a successor project, or the scanpy function it will move to. See also the [scverse ecosystem](https://scverse.org/packages/#ecosystem) {smaller}`P Angerer`

pyproject.toml

@@ -255,6 +255,8 @@ addopts = [
 ]
 filterwarnings = [
     "error",
+    # we still collect doctests from the deprecated module
+    "ignore:The `scanpy.external` module is deprecated:DeprecationWarning",
     # Umap warns when tensorflow isn’t installed.
     "ignore::ImportWarning:umap",
     # matplotlib<3.10.7 uses old pyparsing APIs

src/scanpy/__init__.py

@@ -10,12 +10,13 @@
 
 from anndata import AnnData, concat
 
-from . import datasets, experimental, external, get, io, logging, metrics, queries
+from . import datasets, experimental, get, io, logging, metrics, queries
 from . import plotting as pl
 from . import preprocessing as pp
 from . import tools as tl
 from ._utils import annotate_doc_types
 from .neighbors import Neighbors
+from .plotting.legacy.mpl_settings import set_figure_params
 
 if TYPE_CHECKING:
     from typing import Any
@@ -28,7 +29,6 @@
     "concat",
     "datasets",
     "experimental",
-    "external",
     "get",
     "io",
     "logging",
@@ -42,11 +42,8 @@
 ]
 
 
-from .plotting.legacy.mpl_settings import set_figure_params
-
 annotate_doc_types(sys.modules[__name__], "scanpy")
 
-# has to be done at the end, after everything has been imported
 sys.modules.update({f"{__name__}.{m}": globals()[m] for m in ["tl", "pp", "pl"]})
 
 
@@ -62,6 +59,11 @@ def __getattr__(name: str) -> Any:
         warn(msg, FutureWarning)
         return version("scanpy")
 
+    if name == "external":
+        import scanpy.external
+
+        return scanpy.external
+
     if name in {"read", "read_10x_h5", "read_10x_mtx", "write"} or (
         name in io.__all__ and name in anndata.io.__all__
     ):

src/scanpy/external/pl.py

@@ -38,6 +38,11 @@
 ]
 
 
+@deprecated(
+    Deprecation(
+        "1.13.0", "Use :func:`scanpy.pl.embedding` with ``basis='phate'`` instead."
+    )
+)
 @doctest_needs("phate")
 @_wraps_plot_scatter
 @_doc_params(
@@ -77,18 +82,27 @@ def phate(adata: AnnData, **kwargs) -> list[Axes] | None:
     >>> adata = AnnData(data)
     >>> adata.obs["branches"] = branches
     >>> sce.tl.phate(adata, k=5, a=20, t=150)
+    FutureWarning: The function phate is deprecated and will be removed in the future. Use the `phate <https://github.com/KrishnaswamyLab/PHATE>`_ package directly.
+        sce.tl.phate(adata, k=5, a=20, t=150)
     >>> adata.obsm["X_phate"].shape
     (2000, 2)
     >>> sce.pl.phate(
     ...     adata,
     ...     color="branches",
     ...     color_map="tab20",
     ... )
+    FutureWarning: The function phate is deprecated and will be removed in the future. Use :func:`scanpy.pl.embedding` with ``basis='phate'`` instead.
+        sce.pl.phate(
 
     """
     return embedding(adata, "phate", **kwargs)
 
 
+@deprecated(
+    Deprecation(
+        "1.13.0", "Use :func:`scanpy.pl.embedding` with ``basis='trimap'`` instead."
+    )
+)
 @_wraps_plot_scatter
 @_doc_params(
     adata_color_etc=doc_adata_color_etc,
@@ -114,6 +128,11 @@ def trimap(adata: AnnData, **kwargs) -> Axes | list[Axes] | None:
     return embedding(adata, "trimap", **kwargs)
 
 
+@deprecated(
+    Deprecation(
+        "1.13.0", "Use :func:`scanpy.pl.embedding` with ``basis='harmony'`` instead."
+    )
+)
 @_wraps_plot_scatter
 @_doc_params(
     adata_color_etc=doc_adata_color_etc,
@@ -162,6 +181,7 @@ def harmony_timeseries(
     return axes
 
 
+@deprecated(Deprecation("1.13.0", "Use :func:`scanpy.pl.embedding` instead."))
 def sam(
     adata: AnnData,
     projection: str | np.ndarray = "X_umap",
@@ -256,6 +276,13 @@ def sam(
     return axes
 
 
+@deprecated(
+    Deprecation(
+        "1.13.0",
+        "Use :func:`palantir.plot.plot_gene_trends` from Wishbone’s successor "
+        "`palantir <https://github.com/dpeerlab/Palantir>`_ instead.",
+    )
+)
 @_doc_params(show_save_ax=doc_show_save_ax)
 def wishbone_marker_trajectory(  # noqa: PLR0913
     adata: AnnData,

src/scanpy/external/pp/_bbknn.py

@@ -2,6 +2,8 @@
 
 from typing import TYPE_CHECKING
 
+from scverse_misc import Deprecation, deprecated
+
 from ..._utils._doctests import doctest_needs
 
 if TYPE_CHECKING:
@@ -11,6 +13,7 @@
     from sklearn.metrics import DistanceMetric
 
 
+@deprecated(Deprecation("1.13.0", "Use :func:`scanpy.pp.bbknn` instead."))
 @doctest_needs("bbknn")
 def bbknn(  # noqa: PLR0913
     adata: AnnData,

src/scanpy/external/pp/_hashsolo.py

@@ -36,6 +36,7 @@
 import numpy as np
 import pandas as pd
 from scipy.stats import norm
+from scverse_misc import Deprecation, deprecated
 
 from ..._utils import check_nonnegative_integers
 from ..._utils._doctests import doctest_skipif
@@ -291,6 +292,7 @@ def _calculate_bayes_rule(
     }
 
 
+@deprecated(Deprecation("1.13.0", "Use :func:`scanpy.pp.hashsolo` instead."))
 @doctest_skipif(reason="Illustrative but not runnable doctest code")
 def hashsolo(
     adata: AnnData,

src/scanpy/external/pp/_magic.py

@@ -6,6 +6,7 @@
 from typing import TYPE_CHECKING
 
 from packaging.version import Version
+from scverse_misc import Deprecation, deprecated
 
 from ... import logging as logg
 from ..._compat import pkg_version
@@ -23,6 +24,13 @@
 MIN_VERSION = "2.0"
 
 
+@deprecated(
+    Deprecation(
+        "1.13.0",
+        "Use :func:`palantir.utils.run_magic_imputation` from MAGIC’s successor "
+        "`palantir <https://github.com/dpeerlab/Palantir>`_ instead.",
+    )
+)
 @doctest_needs("magic")
 def magic(  # noqa: PLR0913
     adata: AnnData,
@@ -127,12 +135,18 @@ def magic(  # noqa: PLR0913
     >>> sc.pp.normalize_total(adata)
     >>> sc.pp.sqrt(adata)  # or sc.pp.log1p(adata)
     >>> adata_magic = sce.pp.magic(adata, name_list=["Mpo", "Klf1", "Ifitm1"], knn=5)
+    FutureWarning: The function magic is deprecated and will be removed in the future. Use :func:`palantir.utils.run_magic_imputation` from MAGIC’s successor `palantir <https://github.com/dpeerlab/Palantir>`_ instead.
+        adata_magic = sce.pp.magic(adata, name_list=["Mpo", "Klf1", "Ifitm1"], knn=5)
     >>> adata_magic.shape
     (2730, 3)
     >>> sce.pp.magic(adata, name_list="pca_only", knn=5)
+    FutureWarning: The function magic is deprecated and will be removed in the future. Use :func:`palantir.utils.run_magic_imputation` from MAGIC’s successor `palantir <https://github.com/dpeerlab/Palantir>`_ instead.
+        sce.pp.magic(adata, name_list="pca_only", knn=5)
     >>> adata.obsm["X_magic"].shape
     (2730, 100)
     >>> sce.pp.magic(adata, name_list="all_genes", knn=5)
+    FutureWarning: The function magic is deprecated and will be removed in the future. Use :func:`palantir.utils.run_magic_imputation` from MAGIC’s successor `palantir <https://github.com/dpeerlab/Palantir>`_ instead.
+        sce.pp.magic(adata, name_list="all_genes", knn=5)
     >>> adata.X.shape
     (2730, 3451)
 

src/scanpy/external/pp/_mnn_correct.py

@@ -2,6 +2,8 @@
 
 from typing import TYPE_CHECKING
 
+from scverse_misc import Deprecation, deprecated
+
 from ..._settings import settings
 
 if TYPE_CHECKING:
@@ -13,6 +15,13 @@
     from anndata import AnnData
 
 
+@deprecated(
+    Deprecation(
+        "1.13.0",
+        # TODO: better suggestion?
+        "For batch correction, use :func:`scanpy.pp.combat` or :func:`scanpy.pp.harmony_integrate` instead.",
+    )
+)
 def mnn_correct(  # noqa: PLR0913
     *datas: AnnData | np.ndarray,
     var_index: Collection[str] | None = None,

src/scanpy/external/pp/_scanorama_integrate.py

@@ -5,13 +5,20 @@
 from typing import TYPE_CHECKING
 
 import numpy as np
+from scverse_misc import Deprecation, deprecated
 
 from ..._utils._doctests import doctest_needs
 
 if TYPE_CHECKING:
     from anndata import AnnData
 
 
+@deprecated(
+    Deprecation(
+        "1.13.0",
+        "Use `snapatac2.pp.scanorama_integrate <https://scverse.org/SnapATAC2/api/_autosummary/snapatac2.pp.scanorama_integrate.html>`_ instead.",
+    )
+)
 @doctest_needs("scanorama")
 def scanorama_integrate(
     adata: AnnData,
@@ -97,6 +104,8 @@ def scanorama_integrate(
     ``adata.obsm`` containing the Scanorama embeddings.
 
     >>> sce.pp.scanorama_integrate(adata, "batch", verbose=1)
+    FutureWarning: The function scanorama_integrate is deprecated and will be removed in the future. Use `snapatac2.pp.scanorama_integrate <https://scverse.org/SnapATAC2/api/_autosummary/snapatac2.pp.scanorama_integrate.html>`_ instead.
+        sce.pp.scanorama_integrate(adata, "batch", verbose=1)
     Processing datasets a <=> b
     >>> "X_scanorama" in adata.obsm
     True

src/scanpy/external/tl/_harmony_timeseries.py

@@ -6,6 +6,7 @@
 
 import numpy as np
 import pandas as pd
+from scverse_misc import Deprecation, deprecated
 
 from ... import logging as logg
 from ..._utils._doctests import doctest_needs
@@ -14,6 +15,12 @@
     from anndata import AnnData
 
 
+@deprecated(
+    Deprecation(
+        "1.13.0",
+        "Use the `harmonyTS <https://github.com/dpeerlab/Harmony>`_ package directly.",
+    )
+)
 @doctest_needs("harmony")
 def harmony_timeseries(
     adata: AnnData,
@@ -118,10 +125,14 @@ def harmony_timeseries(
     Run harmony_timeseries
 
     >>> sce.tl.harmony_timeseries(adata, tp="time_points", n_components=500)
+    FutureWarning: The function harmony_timeseries is deprecated and will be removed in the future. Use the `harmonyTS <https://github.com/dpeerlab/Harmony>`_ package directly.
+        sce.tl.harmony_timeseries(adata, tp="time_points", n_components=500)
 
     Plot time points:
 
     >>> sce.pl.harmony_timeseries(adata)
+    FutureWarning: The function harmony_timeseries is deprecated and will be removed in the future. Use :func:`scanpy.pl.embedding` with ``basis='harmony'`` instead.
+        sce.pl.harmony_timeseries(adata)
 
     For further demonstration of Harmony visualizations please follow the notebook
     `Harmony_sample_notebook.ipynb

src/scanpy/external/tl/_palantir.py

@@ -5,6 +5,7 @@
 from typing import TYPE_CHECKING
 
 import pandas as pd
+from scverse_misc import Deprecation, deprecated
 
 from ... import logging as logg
 from ..._utils._doctests import doctest_needs
@@ -13,6 +14,13 @@
     from anndata import AnnData
 
 
+@deprecated(
+    Deprecation(
+        "1.13.0",
+        "Use :func:`palantir.utils.run_diffusion_maps` and "
+        ":func:`palantir.utils.determine_multiscale_space` directly.",
+    )
+)
 @doctest_needs("palantir")
 def palantir(
     adata: AnnData,
@@ -135,6 +143,8 @@ def palantir(
     dimensional phenotypic manifold of the data.
 
     >>> sce.tl.palantir(adata, n_components=5, knn=30)
+    FutureWarning: The function palantir is deprecated and will be removed in the future. Use :func:`palantir.utils.run_diffusion_maps` and :func:`palantir.utils.determine_multiscale_space` directly.
+        sce.tl.palantir(adata, n_components=5, knn=30)
 
     if pre-computed distances are to be used,
 
@@ -145,6 +155,8 @@ def palantir(
     ...     use_adjacency_matrix=True,
     ...     distances_key="distances",
     ... )
+    FutureWarning: The function palantir is deprecated and will be removed in the future. Use :func:`palantir.utils.run_diffusion_maps` and :func:`palantir.utils.determine_multiscale_space` directly.
+        sce.tl.palantir(
 
     **Visualizing Palantir results**
 
@@ -183,6 +195,8 @@ def palantir(
     ...     ms_data="X_palantir_multiscale",
     ...     num_waypoints=500,
     ... )
+    FutureWarning: The function palantir_results is deprecated and will be removed in the future. Use :func:`palantir.core.run_palantir` directly.
+        pr_res = sce.tl.palantir_results(
 
     .. note::
        A `start_cell` must be defined for every data set. The start cell for
@@ -244,6 +258,12 @@ def palantir(
     return adata if copy else None
 
 
+@deprecated(
+    Deprecation(
+        "1.13.0",
+        "Use :func:`palantir.core.run_palantir` directly.",
+    )
+)
 def palantir_results(
     adata: AnnData,
     early_cell: str,