Deprecate visium (#3407)

Author: flying-sheep

docs/conf.py

@@ -143,6 +143,7 @@
     scipy=("https://docs.scipy.org/doc/scipy/", None),
     seaborn=("https://seaborn.pydata.org/", None),
     session_info2=("https://session-info2.readthedocs.io/en/stable/", None),
+    squidpy=("https://squidpy.readthedocs.io/en/stable/", None),
     sklearn=("https://scikit-learn.org/stable/", None),
 )
 

docs/release-notes/1.5.0.md

@@ -5,7 +5,7 @@ The `1.5.0` release adds a lot of new functionality, much of which takes advanta
 
 #### Spatial data support
 
-- Basic analysis {doc}`/tutorials/spatial/basic-analysis` and integration with single cell data {doc}`/tutorials/spatial/integration-scanorama` {smaller}`G Palla`
+- Tutorials for basic analysis and integration with single cell data {smaller}`G Palla`
 - {func}`~scanpy.read_visium` read 10x Visium data {pr}`1034` {smaller}`G Palla, P Angerer, I Virshup`
 - {func}`~scanpy.datasets.visium_sge` load Visium data directly from 10x Genomics {pr}`1013` {smaller}`M Mirkazemi, G Palla, P Angerer`
 - {func}`~scanpy.pl.spatial` plot spatial data {pr}`1012` {smaller}`G Palla, P Angerer`

docs/release-notes/3407.misc.md

@@ -0,0 +1,7 @@
+| Deprecate … | in favor of … |
+| --- | --- |
+| {func}`scanpy.read_visium` | {func}`squidpy.read.visium` |
+| {func}`scanpy.datasets.visium_sge` | {func}`squidpy.datasets.visium` |
+| {func}`scanpy.pl.spatial` | {func}`squidpy.pl.spatial_scatter` |
+
+{smaller}`P Angerer`

docs/tutorials/index.md

@@ -37,19 +37,6 @@ trajectories/index
 
 ## Spatial data
 
-```{seealso}
-For more up-to-date tutorials on working with spatial data, see:
-
-* [SquidPy tutorials](https://squidpy.readthedocs.io/en/stable/notebooks/tutorials/index.html)
-* [SpatialData tutorials](https://spatialdata.scverse.org/en/latest/tutorials/notebooks/notebooks.html)
-* [Scverse ecosystem spatial tutorials](https://scverse.org/learn/)
-```
-
-```{toctree}
-:maxdepth: 2
-
-spatial/index
-```
 
 ## Experimental
 
@@ -64,3 +51,12 @@ experimental/index
 A number of older tutorials can be found at:
 
 * The [`scanpy_usage`](https://github.com/scverse/scanpy_usage) repository
+
+```{seealso}
+Scanpy used to have tutorials for its (now deprecated) spatial data functionality.x
+For up-to-date tutorials on working with spatial data, see:
+
+* SquidPy {doc}`squidpy:notebooks/tutorials/index`
+* [SpatialData tutorials](https://spatialdata.scverse.org/en/latest/tutorials/notebooks/notebooks.html)
+* [Scverse ecosystem spatial tutorials](https://scverse.org/learn/)
+```

docs/tutorials/spatial/basic-analysis.ipynb

@@ -9,7 +9,7 @@
 from anndata import AnnData
 
 from .. import _utils
-from .._compat import old_positionals
+from .._compat import deprecated, old_positionals
 from .._settings import settings
 from .._utils._doctests import doctest_internet, doctest_needs
 from ..readwrite import read, read_visium
@@ -509,6 +509,7 @@ def _download_visium_dataset(
     return sample_dir
 
 
+@deprecated("Use `squidpy.datasets.visium` instead.")
 @doctest_internet
 @check_datasetdir_exists
 def visium_sge(
@@ -519,6 +520,9 @@ def visium_sge(
     """\
     Processed Visium Spatial Gene Expression data from 10x Genomics’ database.
 
+    .. deprecated:: 1.11.0
+       Use :func:`squidpy.datasets.visium` instead.
+
     The database_ can be browsed online to find the ``sample_id`` you want.
 
     .. _database: https://support.10xgenomics.com/spatial-gene-expression/datasets

docs/tutorials/spatial/index.md

@@ -28,6 +28,7 @@
 from packaging.version import Version
 
 from ... import logging as logg
+from ..._compat import deprecated
 from ..._settings import settings
 from ..._utils import (
     Empty,  # noqa: TCH001
@@ -919,6 +920,7 @@ def pca(
     return axs
 
 
+@deprecated("Use `squidpy.pl.spatial_scatter` instead.")
 @_wraps_plot_scatter
 @_doc_params(
     adata_color_etc=doc_adata_color_etc,
@@ -948,6 +950,9 @@ def spatial(
     """\
     Scatter plot in spatial coordinates.
 
+    .. deprecated:: 1.11.0
+       Use :func:`squidpy.pl.spatial_scatter` instead.
+
     This function allows overlaying data on top of images.
     Use the parameter `img_key` to see the image in the background
     And the parameter `library_id` to select the image.
@@ -994,8 +999,6 @@ def spatial(
     --------
     :func:`scanpy.datasets.visium_sge`
         Example visium data.
-    :doc:`/tutorials/spatial/basic-analysis`
-        Tutorial on spatial analysis.
     """
     # get default image params if available
     library_id, spatial_data = _check_spatial_data(adata.uns, library_id)

docs/tutorials/spatial/integration-scanorama.ipynb

@@ -36,7 +36,7 @@
 from matplotlib.image import imread
 
 from . import logging as logg
-from ._compat import add_note, old_positionals
+from ._compat import add_note, deprecated, old_positionals
 from ._settings import settings
 from ._utils import _empty
 
@@ -366,6 +366,7 @@ def _read_v3_10x_h5(filename, *, start=None):
             raise Exception("File is missing one or more required datasets.")
 
 
+@deprecated("Use `squidpy.read.visium` instead.")
 def read_visium(
     path: Path | str,
     genome: str | None = None,
@@ -378,6 +379,9 @@ def read_visium(
     """\
     Read 10x-Genomics-formatted visum dataset.
 
+    .. deprecated:: 1.11.0
+       Use :func:`squidpy.read.visium` instead.
+
     In addition to reading regular 10x output,
     this looks for the `spatial` folder and loads images,
     coordinates and scale factors.