feat: new holoviz plotting

Author: flying-sheep

docs/_templates/autosummary/function-dual.rst

@@ -0,0 +1,22 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. note::
+   Both backends are accessible as ``{{ fullname }}``.
+   The active backend is chosen by :attr:`scanpy.settings.preset`:
+   the default is the legacy matplotlib backend;
+   set it to :attr:`scanpy.Preset.ScanpyV2Preview` to use the HoloViews backend.
+
+.. tab-set::
+
+   .. tab-item:: New (HoloViews)
+      :sync: scanpy-preset-v2
+
+      .. autofunction:: scanpy.plotting._v2.{{ objname }}
+         :no-index:
+
+   .. tab-item:: Legacy (matplotlib)
+      :sync: scanpy-preset-legacy
+
+      .. autofunction:: {{ objname }}

docs/api/plotting.md

@@ -21,10 +21,13 @@ See the {ref}`settings` section for all important plotting configurations.
 
 ## Generic
 
+Functions with both backends:
+
 ```{eval-rst}
 .. autosummary::
    :nosignatures:
    :toctree: ../generated/
+   :template: function-dual
 
    pl.scatter
    pl.heatmap
@@ -33,8 +36,18 @@ See the {ref}`settings` section for all important plotting configurations.
    pl.violin
    pl.stacked_violin
    pl.matrixplot
-   pl.clustermap
    pl.ranking
+
+```
+
+Legacy (matplotlib) only:
+
+```{eval-rst}
+.. autosummary::
+   :nosignatures:
+   :toctree: ../generated/
+
+   pl.clustermap
    pl.dendrogram
 
 ```
@@ -62,6 +75,7 @@ Methods for visualizing quality control and results of preprocessing functions.
 .. autosummary::
    :nosignatures:
    :toctree: generated/
+   :template: function-dual
 
    pl.highest_expr_genes
    pl.highly_variable_genes
@@ -92,17 +106,18 @@ a method with the same name in `pl`.
 
 ### Embeddings
 
+Functions with both backends:
+
 ```{eval-rst}
 .. autosummary::
    :nosignatures:
    :toctree: generated/
+   :template: function-dual
 
-   pl.tsne
    pl.umap
+   pl.tsne
    pl.diffmap
    pl.draw_graph
-   pl.spatial
-   pl.embedding
 ```
 
 Compute densities on embeddings.
@@ -111,10 +126,22 @@ Compute densities on embeddings.
 .. autosummary::
    :nosignatures:
    :toctree: generated/
+   :template: function-dual
 
    pl.embedding_density
 ```
 
+Legacy (matplotlib) only:
+
+```{eval-rst}
+.. autosummary::
+   :nosignatures:
+   :toctree: generated/
+
+   pl.spatial
+   pl.embedding
+```
+
 ### Branching trajectories and pseudotime, clustering
 
 Visualize clusters using one of the embedding methods passing e.g. `color='leiden'`.

docs/conf.py

@@ -152,6 +152,8 @@
     decoupler=("https://decoupler.readthedocs.io/en/stable/", None),
     fast_array_utils=("https://fast-array-utils.scverse.org/en/stable/", None),
     h5py=("https://docs.h5py.org/en/stable/", None),
+    holoviews=("https://holoviews.org/", None),
+    hv_anndata=("https://hv-anndata.readthedocs.io/en/latest/", None),
     zarr=("https://zarr.readthedocs.io/en/stable/", None),
     ipython=("https://ipython.readthedocs.io/en/stable/", None),
     igraph=("https://python.igraph.org/en/stable/api/", None),
@@ -265,9 +267,6 @@ def setup(app: Sphinx) -> None:
 qualname_overrides = {
     "pathlib._local.Path": "pathlib.Path",
     "sklearn.neighbors._dist_metrics.DistanceMetric": "sklearn.metrics.DistanceMetric",
-    "scanpy.plotting._matrixplot.MatrixPlot": "scanpy.pl.MatrixPlot",
-    "scanpy.plotting._dotplot.DotPlot": "scanpy.pl.DotPlot",
-    "scanpy.plotting._stacked_violin.StackedViolin": "scanpy.pl.StackedViolin",
     "pandas.core.series.Series": "pandas.Series",
     # https://github.com/pandas-dev/pandas/issues/63810
     "pandas.api.typing.aliases.AnyArrayLike": ("doc", "pandas:reference/aliases"),
@@ -283,15 +282,14 @@ def setup(app: Sphinx) -> None:
     ("py:class", "numpy._typing._dtype_like._SupportsDType"),
     ("py:class", "numpy._typing._dtype_like._DTypeDict"),
     # Will probably be documented
-    ("py:class", "scanpy._settings.Verbosity"),
     ("py:class", "scanpy.neighbors.OnFlySymMatrix"),
-    ("py:class", "scanpy.plotting._baseplot_class.BasePlot"),
+    ("py:class", "scanpy.pl.BasePlot"),
     # Currently undocumented
     # https://github.com/mwaskom/seaborn/issues/1810
     ("py:class", "seaborn.matrix.ClusterGrid"),
     ("py:class", "samalg.SAM"),
     # Won’t be documented
-    ("py:class", "scanpy.plotting._utils._AxesSubplot"),
+    ("py:class", "scanpy.pl._AxesSubplot"),
     ("py:class", "scanpy._utils.Empty"),
     ("py:class", "numpy.random.mtrand.RandomState"),
     ("py:class", "scanpy.neighbors._types.KnnTransformerLike"),

docs/release-notes/4188.feat.md

@@ -0,0 +1 @@
+Add a new [Holoviews](https://holoviews.org)-based plotting backend for {mod}`scanpy.pl`, used when {attr}`scanpy.settings.preset` is set to {attr}`~scanpy.Preset.ScanpyV2Preview` {smaller}`P Angerer`

hatch.toml

@@ -4,7 +4,8 @@ dependency-groups = [ "dev" ]
 
 [envs.docs]
 dependency-groups = [ "docs" ]
-extra-dependencies = [ "pandas>=3" ]
+# TODO: remove git again after anndata 0.13.0rc4
+extra-dependencies = [ "pandas>=3", "anndata @ git+https://github.com/scverse/anndata.git" ]
 scripts.build = "sphinx-build -M html docs docs/_build -W {args}"
 scripts.open = "python3 -m webbrowser -t docs/_build/html/index.html"
 scripts.clean = "git clean -fdX -- {args:docs}"

pyproject.toml

@@ -98,7 +98,7 @@ scanorama = [ "scanorama" ]
 scrublet = [ "scikit-image>=0.25" ]
 # highly_variable_genes method 'seurat_v3'
 skmisc = [ "scikit-misc>=0.5.1" ]
-scanpy2 = [ "anndata>=0.13rc3", "igraph>=0.10.8", "scikit-misc>=0.5.1" ]
+scanpy2 = [ "anndata>=0.13rc3", "hv-anndata>=0.0.3a4", "igraph>=0.10.8", "scikit-misc>=0.5.1" ]
 
 [dependency-groups]
 dev = [
@@ -131,7 +131,7 @@ docs = [
     "sphinx-book-theme>=1.1",
     "sphinx-copybutton",
     "sphinx-design",
-    "sphinx-exec-jupyter>=0.2.1",
+    "sphinx-exec-jupyter[holoviews]>=0.2.1",
     "sphinx-issues>=5.0.1",
     "sphinxcontrib-bibtex",
     "sphinxcontrib-katex",
@@ -291,7 +291,7 @@ markers = [
     "gpu: tests that use a GPU (unused, required by anndata.tests.helpers)",
     "array_api: tests that use array_api (unused, required by anndata.tests.helpers)",
 ]
-norecursedirs = [ "tests/_images" ]
+norecursedirs = [ "tests/_images", "src/scanpy/plotting/_v2" ]
 strict = true
 testpaths = [ "./tests", "./ci", "scanpy" ]
 

src/scanpy/__init__.py

@@ -81,7 +81,7 @@
 ]
 
 
-set_figure_params = settings._set_figure_params
+from .plotting.legacy.mpl_settings import set_figure_params
 
 annotate_doc_types(sys.modules[__name__], "scanpy")
 

src/scanpy/_settings/__init__.py

@@ -33,20 +33,12 @@ def write(self, data: T, /) -> int: ...
 
 
 if TYPE_CHECKING:
-    from collections.abc import Iterable
     from typing import Self, TextIO
 
     from pydantic import ValidationInfo
 
     from .verbosity import _VerbosityName
 
-    # Collected from the print_* functions in matplotlib.backends
-    type _Format = (
-        Literal["png", "jpg", "tif", "tiff"]  # noqa: PYI030
-        | Literal["pdf", "ps", "eps", "svg", "svgz", "pgf"]
-        | Literal["raw", "rgba"]
-    )
-
 
 __all__ = ["AnnDataFileFormat", "Default", "Preset", "Verbosity"]
 
@@ -156,12 +148,6 @@ def model_post_init(self, context: object) -> None:
     })
     """Categories that are omitted in plotting etc."""
 
-    _frameon: Annotated[bool, PrivateAttr(default=True)]
-    """See set_figure_params."""
-    _vector_friendly: Annotated[bool, PrivateAttr(default=False)]
-    """Set to true if you want to include pngs in svgs and pdfs."""
-    _low_resolution_warning: Annotated[bool, PrivateAttr(default=True)]
-    """Print warning when saving a figure with low resolution."""
     _start: Annotated[float, PrivateAttr(default_factory=time)]
     """Time when the settings module is first imported."""
     _previous_time: Annotated[float, PrivateAttr(default_factory=time)]
@@ -218,89 +204,9 @@ def _logging_side_effects(self, info: ValidationInfo) -> Self:
 
     @deprecated(Deprecation("1.11.3", "Use :func:`scanpy.set_figure_params` instead"))
     def set_figure_params(self, *args, **kwargs) -> None:
-        self._set_figure_params(*args, **kwargs)
-
-    def _set_figure_params(  # noqa: PLR0913
-        self,
-        *,
-        scanpy: bool = True,
-        dpi: int = 80,
-        dpi_save: int = 150,
-        frameon: bool = True,
-        vector_friendly: bool = True,
-        fontsize: int = 14,
-        figsize: int | None = None,
-        color_map: str | None = None,
-        format: _Format = "pdf",
-        facecolor: str | None = None,
-        transparent: bool = False,
-        ipython_format: str | Iterable[str] = "retina",
-    ) -> None:
-        """Set resolution/size, styling and format of figures.
-
-        Parameters
-        ----------
-        scanpy
-            Init default values for :obj:`matplotlib.rcParams` suited for Scanpy.
-        dpi
-            Resolution of rendered figures – this influences the size of figures in notebooks.
-        dpi_save
-            Resolution of saved figures.
-            This should typically be higher to achieve publication quality.
-        frameon
-            Add frames and axes labels to scatter plots.
-        vector_friendly
-            Plot scatter plots using `png` backend even when exporting as `pdf` or `svg`.
-        fontsize
-            Set the fontsize for several `rcParams` entries. Ignored if `scanpy=False`.
-        figsize
-            Set `rcParams['figure.figsize']`.
-        color_map
-            Convenience method for setting the default color map. Ignored if `scanpy=False`.
-        format
-            This sets the default format for saving figures: `file_format_figs`.
-        facecolor
-            Sets backgrounds via `rcParams['figure.facecolor'] = facecolor` and
-            `rcParams['axes.facecolor'] = facecolor`.
-        transparent
-            Save figures with transparent background.
-            Sets `rcParams['savefig.transparent']`.
-        ipython_format
-            Only concerns the notebook/IPython environment; see
-            `matplotlib_inline.backend_inline.set_matplotlib_formats
-            <https://github.com/ipython/matplotlib-inline/blob/b93777db35267acefe6e37d14214360362d2e8b2/matplotlib_inline/backend_inline.py#L280-L281>`_
-            for details.
-
-        """
-        if _is_run_from_ipython():
-            # No docs yet: https://github.com/ipython/matplotlib-inline/issues/12
-            from matplotlib_inline.backend_inline import set_matplotlib_formats
-
-            if isinstance(ipython_format, str):
-                ipython_format = [ipython_format]
-
-            set_matplotlib_formats(*ipython_format)
-
-        from matplotlib import rcParams
-
-        self._vector_friendly = vector_friendly
-        self.file_format_figs = format
-        if dpi is not None:
-            rcParams["figure.dpi"] = dpi
-        if dpi_save is not None:
-            rcParams["savefig.dpi"] = dpi_save
-        if transparent is not None:
-            rcParams["savefig.transparent"] = transparent
-        if facecolor is not None:
-            rcParams["figure.facecolor"] = facecolor
-            rcParams["axes.facecolor"] = facecolor
-        if scanpy:
-            from ..plotting._rcmod import set_rcParams_scanpy
-
-            set_rcParams_scanpy(fontsize=fontsize, color_map=color_map)
-        if figsize is not None:
-            rcParams["figure.figsize"] = figsize
-        self._frameon = frameon
+        from ..plotting.legacy.mpl_settings import set_figure_params
+
+        set_figure_params(*args, **kwargs)
 
     def __str__(self) -> str:
         return "\n".join(

src/scanpy/datasets/_datasets.py

@@ -377,7 +377,14 @@ def pbmc68k_reduced() -> AnnData:
         layers: None
 
     """
-    return read_h5ad(HERE / "10x_pbmc68k_reduced.h5ad")
+    from scanpy._settings import Preset, settings
+
+    adata = read_h5ad(HERE / "10x_pbmc68k_reduced.h5ad")
+    if settings.preset is Preset.ScanpyV2Preview:
+        adata.layers["counts"] = adata.raw.X
+        del adata.raw
+        adata.obsm = {k.removeprefix("X_"): v for k, v in adata.obsm.items()}
+    return adata
 
 
 @_doctest_skipif_old_anndata

src/scanpy/external/pl.py

@@ -11,14 +11,14 @@
 
 from .._utils import _doc_params
 from .._utils._doctests import doctest_needs
-from ..plotting import _utils, embedding
-from ..plotting._docs import (
+from ..plotting.legacy import _utils, embedding
+from ..plotting.legacy._docs import (
     doc_adata_color_etc,
     doc_edges_arrows,
     doc_scatter_embedding,
     doc_show_save_ax,
 )
-from ..plotting._tools.scatterplots import _wraps_plot_scatter
+from ..plotting.legacy._tools.scatterplots import _wraps_plot_scatter
 from .tl._wishbone import _anndata_to_wishbone
 
 if TYPE_CHECKING:
@@ -347,6 +347,6 @@ def wishbone_marker_trajectory(  # noqa: PLR0913
 
 @deprecated(Deprecation("1.10.0", "Import from sc.pl instead."))
 def scrublet_score_distribution(*args, **kwargs):  # pragma: no cover
-    from ..plotting._scrublet import scrublet_score_distribution
+    from ..plotting.legacy._scrublet import scrublet_score_distribution
 
     return scrublet_score_distribution(*args, **kwargs)