Add plot gallery to docs

.gitignore

@@ -22,6 +22,10 @@ __pycache__/
 # docs
 /docs/generated/
 /docs/_build/
+/docs/auto_gallery/
+/docs/sg_execution_times.rst
+/docs/gallery/**/data/
+/docs/gallery/**/__pycache__/
 
 # IDEs
 /.idea/

docs/_static/css/custom.css

@@ -2,3 +2,8 @@
 div.cell_output table.dataframe {
     font-size: 0.8em;
 }
+
+/* Gallery landing: subsection links are shown in the sidebar; hide the duplicate inline list. */
+section#gallery > .toctree-wrapper {
+    display: none;
+}

docs/conf.py

@@ -56,6 +56,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
+    "sphinx_gallery.gen_gallery",
     "sphinxcontrib.bibtex",
     "sphinxcontrib.katex",
     "sphinx_autodoc_typehints",
@@ -118,6 +119,9 @@
     "tutorials/notebooks/README.md",
     "tutorials/notebooks/references.md",
     "tutorials/notebooks/notebooks/paper_reproducibility/*",
+    "gallery/*",
+    "auto_gallery/**/*.ipynb",
+    "auto_gallery/**/*.py",
 ]
 
 
@@ -157,3 +161,19 @@
     # you can add an exception to this list.
     ("py:class", "igraph.Graph"),
 ]
+
+# -- Sphinx-Gallery configuration -------------------------------------------
+
+sys.path.insert(0, str(HERE / "gallery"))
+
+sphinx_gallery_conf = {
+    "examples_dirs": ["gallery"],
+    "gallery_dirs": ["auto_gallery"],
+    "filename_pattern": r"/plot_",
+    "ignore_pattern": r"(__init__|_helpers)\.py",
+    "image_scrapers": ("matplotlib",),
+    "matplotlib_animations": True,
+    "within_subsection_order": "FileNameSortKey",
+    "nested_sections": True,
+    "download_all_examples": True,
+}

docs/gallery.rst

@@ -0,0 +1,15 @@
+Gallery
+-------
+
+Examples demonstrating the plotting capabilities of ``spatialdata-plot``.
+
+.. toctree::
+   :maxdepth: 1
+
+   auto_gallery/basic/index
+   auto_gallery/customization/index
+   auto_gallery/overlays/index
+
+.. include:: auto_gallery/index.rst
+   :start-after: Examples demonstrating the plotting capabilities of ``spatialdata-plot``.
+   :end-before: .. toctree::

docs/gallery/README.rst

@@ -0,0 +1,4 @@
+Gallery
+-------
+
+Examples demonstrating the plotting capabilities of ``spatialdata-plot``.

docs/gallery/_helpers.py

@@ -0,0 +1,60 @@
+"""Shared data loaders for gallery examples."""
+
+from __future__ import annotations
+
+import warnings
+
+import numpy as np
+import scanpy as sc
+import spatialdata as sd
+from spatialdata.models import Image2DModel, ShapesModel, TableModel
+
+
+def load_visium_breast_cancer() -> sd.SpatialData:
+    """Load Visium breast cancer tissue as a SpatialData object.
+
+    Uses ``scanpy.datasets.visium_sge`` which caches the download
+    via :mod:`pooch`, so the data is only fetched once.
+    """
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        adata = sc.datasets.visium_sge(
+            sample_id="V1_Breast_Cancer_Block_A_Section_1",
+        )
+
+    sample = list(adata.uns["spatial"].keys())[0]
+    meta = adata.uns["spatial"][sample]
+    sf = meta["scalefactors"]["tissue_hires_scalef"]
+
+    image = Image2DModel.parse(
+        np.moveaxis(meta["images"]["hires"], -1, 0),
+        dims=("c", "y", "x"),
+    )
+
+    radius = meta["scalefactors"]["spot_diameter_fullres"] * sf / 2
+    circles = ShapesModel.parse(
+        adata.obsm["spatial"] * sf,
+        geometry=0,
+        radius=radius,
+        index=adata.obs_names,
+    )
+
+    adata.obs["region"] = "spots"
+    adata.obs["region"] = adata.obs["region"].astype("category")
+    adata.obs["instance_key"] = adata.obs_names
+    table = TableModel.parse(
+        adata,
+        region="spots",
+        region_key="region",
+        instance_key="instance_key",
+    )
+
+    table.var_names_make_unique()
+    sc.pp.normalize_total(table)
+    sc.pp.log1p(table)
+
+    return sd.SpatialData(
+        images={"tissue": image},
+        shapes={"spots": circles},
+        tables={"table": table},
+    )

docs/gallery/basic/README.rst

@@ -0,0 +1,4 @@
+Basic
+-----
+
+Rendering individual spatial element types.

docs/gallery/basic/plot_render_images.py

@@ -0,0 +1,14 @@
+"""
+Render tissue image
+===================
+
+Render an H&E tissue image from a Visium experiment.
+"""
+
+from _helpers import load_visium_breast_cancer
+
+import spatialdata_plot  # noqa: F401
+
+sdata = load_visium_breast_cancer()
+
+sdata.pl.render_images("tissue").pl.show()

docs/gallery/basic/plot_render_labels.py

@@ -0,0 +1,14 @@
+"""
+Render labels
+=============
+
+Render a cell segmentation mask.
+"""
+
+import spatialdata as sd
+
+import spatialdata_plot  # noqa: F401
+
+sdata = sd.datasets.blobs()
+
+sdata.pl.render_labels("blobs_labels").pl.show()

docs/gallery/basic/plot_render_labels_contour.py

@@ -0,0 +1,14 @@
+"""
+Render label contours
+=====================
+
+Render segmentation boundaries using ``contour_px``.
+"""
+
+import spatialdata as sd
+
+import spatialdata_plot  # noqa: F401
+
+sdata = sd.datasets.blobs()
+
+sdata.pl.render_labels("blobs_labels", contour_px=3).pl.show()

docs/gallery/basic/plot_render_points.py

@@ -0,0 +1,14 @@
+"""
+Render points
+=============
+
+Render transcript detections as points.
+"""
+
+import spatialdata as sd
+
+import spatialdata_plot  # noqa: F401
+
+sdata = sd.datasets.blobs()
+
+sdata.pl.render_points("blobs_points", size=3).pl.show()

docs/gallery/basic/plot_render_shapes.py

@@ -0,0 +1,14 @@
+"""
+Render spots
+============
+
+Render Visium spot shapes on their own.
+"""
+
+from _helpers import load_visium_breast_cancer
+
+import spatialdata_plot  # noqa: F401
+
+sdata = load_visium_breast_cancer()
+
+sdata.pl.render_shapes("spots").pl.show()

docs/gallery/customization/README.rst

@@ -0,0 +1,4 @@
+Customization
+-------------
+
+Styling options: colormaps, outlines, contours, and alpha.

docs/gallery/customization/plot_gene_cmap.py

@@ -0,0 +1,14 @@
+"""
+Gene expression with custom colormap
+=====================================
+
+Color spots by gene expression using a custom colormap.
+"""
+
+from _helpers import load_visium_breast_cancer
+
+import spatialdata_plot  # noqa: F401
+
+sdata = load_visium_breast_cancer()
+
+(sdata.pl.render_images("tissue").pl.render_shapes("spots", color="ERBB2", cmap="magma", fill_alpha=0.8).pl.show())

docs/gallery/customization/plot_multi_panel.py

@@ -0,0 +1,31 @@
+"""
+Multi-panel layout
+==================
+
+Display multiple coordinate systems side by side.
+"""
+
+import numpy as np
+import spatialdata as sd
+from spatialdata.models import Image2DModel
+from spatialdata.transformations import Identity
+
+import spatialdata_plot  # noqa: F401
+
+rng = np.random.default_rng(0)
+img_a = Image2DModel.parse(
+    rng.random((3, 64, 64)),
+    dims=("c", "y", "x"),
+    transformations={"sample_a": Identity()},
+)
+img_b = Image2DModel.parse(
+    rng.random((3, 64, 64)),
+    dims=("c", "y", "x"),
+    transformations={"sample_b": Identity()},
+)
+sdata = sd.SpatialData(images={"img_a": img_a, "img_b": img_b})
+
+sdata.pl.render_images().pl.show(
+    coordinate_systems=["sample_a", "sample_b"],
+    figsize=(8, 4),
+)

docs/gallery/customization/plot_shapes_outline.py

@@ -0,0 +1,24 @@
+"""
+Spots with outlines
+===================
+
+Style spots with visible outlines and translucent fill.
+"""
+
+from _helpers import load_visium_breast_cancer
+
+import spatialdata_plot  # noqa: F401
+
+sdata = load_visium_breast_cancer()
+
+(
+    sdata.pl.render_images("tissue")
+    .pl.render_shapes(
+        "spots",
+        fill_alpha=0.3,
+        outline_width=1.5,
+        outline_color="black",
+        outline_alpha=1.0,
+    )
+    .pl.show()
+)

docs/gallery/customization/plot_single_channel.py

@@ -0,0 +1,14 @@
+"""
+Single channel with colormap
+=============================
+
+Render one image channel with a colormap.
+"""
+
+from _helpers import load_visium_breast_cancer
+
+import spatialdata_plot  # noqa: F401
+
+sdata = load_visium_breast_cancer()
+
+sdata.pl.render_images("tissue", channel=0, cmap="viridis").pl.show()

docs/gallery/overlays/README.rst

@@ -0,0 +1,4 @@
+Overlays
+--------
+
+Combining multiple spatial element layers in a single plot.

docs/gallery/overlays/plot_color_by_category.py

@@ -0,0 +1,14 @@
+"""
+Color spots by category
+=======================
+
+Overlay spots colored by a categorical annotation.
+"""
+
+from _helpers import load_visium_breast_cancer
+
+import spatialdata_plot  # noqa: F401
+
+sdata = load_visium_breast_cancer()
+
+(sdata.pl.render_images("tissue").pl.render_shapes("spots", color="in_tissue", fill_alpha=0.7).pl.show())

docs/gallery/overlays/plot_color_by_gene.py

@@ -0,0 +1,14 @@
+"""
+Color spots by gene expression
+===============================
+
+Overlay spots colored by a gene on an H&E tissue image.
+"""
+
+from _helpers import load_visium_breast_cancer
+
+import spatialdata_plot  # noqa: F401
+
+sdata = load_visium_breast_cancer()
+
+(sdata.pl.render_images("tissue").pl.render_shapes("spots", color="ERBB2", fill_alpha=0.8).pl.show())

docs/gallery/overlays/plot_filter_groups.py

@@ -0,0 +1,14 @@
+"""
+Filter by category groups
+=========================
+
+Show only selected categories using the ``groups`` parameter.
+"""
+
+from _helpers import load_visium_breast_cancer
+
+import spatialdata_plot  # noqa: F401
+
+sdata = load_visium_breast_cancer()
+
+(sdata.pl.render_images("tissue").pl.render_shapes("spots", color="in_tissue", groups=["1"], fill_alpha=0.7).pl.show())

docs/gallery/overlays/plot_images_shapes.py

@@ -0,0 +1,14 @@
+"""
+Tissue with spots
+=================
+
+Overlay Visium spots on an H&E tissue image.
+"""
+
+from _helpers import load_visium_breast_cancer
+
+import spatialdata_plot  # noqa: F401
+
+sdata = load_visium_breast_cancer()
+
+(sdata.pl.render_images("tissue").pl.render_shapes("spots", fill_alpha=0.5).pl.show())

docs/index.md

@@ -4,8 +4,9 @@
 
 ```{toctree}
 :hidden: true
-:maxdepth: 1
+:maxdepth: 2
 
+gallery
 api.md
 changelog.md
 contributing.md