(feat): presets

docs/api/settings.md

@@ -30,6 +30,16 @@ An object that allows configuring Scanpy.
 
 Some selected settings are discussed in the following.
 
+Presets allow to set the behavior of many scanpy functions at once:
+
+```{eval-rst}
+.. autosummary::
+   :signatures: none
+   :toctree: ../generated/
+
+   Preset
+```
+
 Verbosity controls the amount of logging output:
 
 ```{eval-rst}

docs/conf.py

@@ -219,6 +219,9 @@ def setup(app: Sphinx):
     "scanpy.plotting._matrixplot.MatrixPlot": "scanpy.pl.MatrixPlot",
     "scanpy.plotting._dotplot.DotPlot": "scanpy.pl.DotPlot",
     "scanpy.plotting._stacked_violin.StackedViolin": "scanpy.pl.StackedViolin",
+    "scanpy._param_sets.HVGFlavor": "tuple",
+    "scanpy._param_sets.FilterCellsCutoffs": "tuple",
+    "scanpy._param_sets.FilterGenesCutoffs": "tuple",
     "pandas.core.series.Series": "pandas.Series",
     "numpy.bool_": "numpy.bool",  # Since numpy 2, numpy.bool is the canonical dtype
 }

docs/release-notes/3653.feature.md

@@ -0,0 +1 @@
+Add {attr}`scanpy.settings.preset` setting with two new presets: {attr}`~scanpy.settings.Preset.SeuratV5` and {attr}`~scanpy.settings.Preset.ScanpyV2Preview`. {smaller}`P Angerer`

src/scanpy/__init__.py

@@ -15,7 +15,7 @@
 # the actual API
 # (start with settings as several tools are using it)
 
-from ._settings import Verbosity, settings
+from ._settings import Preset, Verbosity, settings
 
 set_figure_params = settings._set_figure_params
 
@@ -62,6 +62,7 @@
 __all__ = [
     "AnnData",
     "Neighbors",
+    "Preset",
     "Verbosity",
     "__version__",
     "concat",

src/scanpy/_settings/__init__.py

@@ -11,6 +11,7 @@
 from .._compat import deprecated, old_positionals
 from .._singleton import SingletonMeta
 from ..logging import _RootLogger, _set_log_file, _set_log_level
+from .presets import Preset
 from .verbosity import Verbosity
 
 if TYPE_CHECKING:
@@ -27,7 +28,6 @@
         | Literal["raw", "rgba"]
     )
 
-
 S = TypeVar("S")
 T = TypeVar("T")
 P = ParamSpec("P")
@@ -67,6 +67,7 @@ def wrapped(self: S, var: T, *args: P.args, **kwargs: P.kwargs) -> R:
 
 
 class SettingsMeta(SingletonMeta):
+    _preset: Preset
     # logging
     _root_logger: _RootLogger
     _logfile: TextIO | None
@@ -99,6 +100,15 @@ class SettingsMeta(SingletonMeta):
     _previous_memory_usage: int
     """Stores the previous memory usage."""
 
+    @property
+    def preset(cls) -> Preset:
+        """Preset to use."""
+        return cls._preset
+
+    @preset.setter
+    def preset(cls, preset: Preset | str) -> None:
+        cls._preset = Preset(preset)
+
     @property
     def verbosity(cls) -> Verbosity:
         """Verbosity level (default :attr:`Verbosity.warning`)."""
@@ -336,7 +346,7 @@ def categories_to_ignore(cls, categories_to_ignore: Iterable[str]) -> None:
 
     @deprecated("Use `scanpy.set_figure_params` instead")
     def set_figure_params(cls, *args, **kwargs) -> None:
-        cls.set_figure_params(*args, **kwargs)
+        cls._set_figure_params(*args, **kwargs)
 
     @old_positionals(
         "scanpy",
@@ -455,6 +465,7 @@ class settings(metaclass=SettingsMeta):
     def __new__(cls) -> type[Self]:
         return cls
 
+    _preset = Preset.ScanpyV1
     # logging
     _root_logger: ClassVar = _RootLogger(logging.INFO)
     _logfile: ClassVar = None

src/scanpy/_settings/presets.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+import inspect
+import re
+from contextlib import contextmanager
+from enum import StrEnum, auto
+from functools import cached_property, partial, wraps
+from typing import TYPE_CHECKING, Literal, NamedTuple, TypeVar
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator, Mapping
+
+
+NT = TypeVar("NT", bound=NamedTuple)
+
+__all__ = [
+    "DETest",
+    "HVGFlavor",
+    "HVGPreset",
+    "LeidenFlavor",
+    "LeidenPreset",
+    "PcaPreset",
+    "Preset",
+    "RankGenesGroupsPreset",
+]
+
+
+DETest = Literal["logreg", "t-test", "wilcoxon", "t-test_overestim_var"]
+HVGFlavor = Literal["seurat", "cell_ranger", "seurat_v3", "seurat_v3_paper"]
+LeidenFlavor = Literal["leidenalg", "igraph"]
+
+
+class HVGPreset(NamedTuple):
+    flavor: HVGFlavor
+    return_df: bool
+
+
+class PcaPreset(NamedTuple):
+    key_added: str | None
+
+
+class RankGenesGroupsPreset(NamedTuple):
+    method: DETest
+    mask_var: str | None
+
+
+class LeidenPreset(NamedTuple):
+    flavor: LeidenFlavor
+
+
+preset_postprocessors: list[Callable[[], None]] = []
+
+
+def named_tuple_non_defaults(
+    nt: NamedTuple,
+) -> Generator[tuple[str, object], None, None]:
+    cls = type(nt)
+    for param in cls._fields:
+        value = getattr(nt, param)
+        if param not in cls._field_defaults or value != cls._field_defaults[param]:
+            yield param, value
+
+
+def postprocess_preset_prop(
+    prop: cached_property[NT], get_map: Callable[[], Mapping[Preset, NT]]
+) -> None:
+    map = get_map()
+
+    map_type = inspect.signature(get_map).return_annotation
+    m = re.fullmatch(r"Mapping\[Preset, (.*)\]", map_type)
+    assert m is not None
+    value_type = m[1]
+
+    added_doc = "\n".join(
+        ":attr:`{name}`\n    Defaults: {defaults}".format(
+            name=k.name,
+            defaults=", ".join(
+                f"`{param}={default!r}`"
+                for param, default in named_tuple_non_defaults(params)
+            )
+            or "none",
+        )
+        for k, params in map.items()
+    )
+
+    prop.__doc__ = f"{prop.__doc__}\n\n{added_doc}"
+    prop.func.__annotations__["return"] = value_type
+
+
+def preset_property(get_map: Callable[[], Mapping[Preset, NT]]) -> cached_property[NT]:
+    @wraps(get_map)
+    def get(self: Preset) -> NT:
+        return get_map()[self]
+
+    prop = cached_property(get)
+    preset_postprocessors.append(partial(postprocess_preset_prop, prop, get_map))
+    return prop
+
+
+class Preset(StrEnum):
+    """Presets for :attr:`scanpy.settings.preset`.
+
+    See properties below for details.
+    """
+
+    ScanpyV1 = auto()
+    """Scanpy 1.*’s default settings."""
+
+    ScanpyV2Preview = auto()
+    """Scanpy 2.*’s feature default settings. (Preview: subject to change!)"""
+
+    SeuratV5 = auto()
+    """Try to match Seurat 5.* as closely as possible."""
+
+    @preset_property
+    def highly_variable_genes() -> Mapping[Preset, HVGPreset]:
+        """Flavor for :func:`~scanpy.pp.highly_variable_genes`."""
+        return {
+            Preset.ScanpyV1: HVGPreset(flavor="seurat", return_df=False),
+            Preset.ScanpyV2Preview: HVGPreset(flavor="seurat_v3_paper", return_df=True),
+            Preset.SeuratV5: HVGPreset(flavor="seurat_v3_paper", return_df=True),
+        }
+
+    @preset_property
+    def pca() -> Mapping[Preset, PcaPreset]:
+        """Settings for :func:`~scanpy.pp.pca`."""  # noqa: D401
+        return {
+            Preset.ScanpyV1: PcaPreset(key_added=None),
+            Preset.ScanpyV2Preview: PcaPreset(key_added="pca"),
+            Preset.SeuratV5: PcaPreset(key_added="pca"),
+        }
+
+    @preset_property
+    def rank_genes_groups() -> Mapping[Preset, RankGenesGroupsPreset]:
+        """Correlation method for :func:`~scanpy.tl.rank_genes_groups`."""
+        return {
+            Preset.ScanpyV1: RankGenesGroupsPreset(method="t-test", mask_var=None),
+            Preset.ScanpyV2Preview: RankGenesGroupsPreset(
+                method="wilcoxon", mask_var=None
+            ),
+            Preset.SeuratV5: RankGenesGroupsPreset(
+                method="wilcoxon", mask_var="highly_variable"
+            ),
+        }
+
+    @preset_property
+    def leiden() -> Mapping[Preset, LeidenPreset]:
+        """Flavor for :func:`~scanpy.tl.leiden`."""
+        return {
+            Preset.ScanpyV1: LeidenPreset(flavor="leidenalg"),
+            Preset.ScanpyV2Preview: LeidenPreset(flavor="igraph"),
+            Preset.SeuratV5: LeidenPreset(flavor="leidenalg"),
+        }
+
+    @contextmanager
+    def override(self, preset: Preset) -> Generator[Preset, None, None]:
+        """Temporarily override :attr:`scanpy.settings.preset`.
+
+        >>> import scanpy as sc
+        >>> sc.settings.preset = sc.Preset.ScanpyV1
+        >>> with sc.settings.preset.override(sc.Preset.SeuratV5):
+        ...     sc.settings.preset
+        <Preset.SeuratV5: 'seuratv5'>
+        >>> sc.settings.preset
+        <Preset.ScanpyV1: 'scanpyv1'>
+        """
+        from scanpy import settings
+
+        settings.preset = preset
+        try:
+            yield self
+        finally:
+            settings.preset = self
+
+
+for postprocess in preset_postprocessors:
+    postprocess()