update backends

Author: Intron7

hatch.toml

@@ -37,7 +37,7 @@ download = "python ./.scripts/ci/download_data.py {args}"
 
 [[envs.hatch-test.matrix]]
 deps = ["stable"]
-python = ["3.11", "3.12", "3.13"]
+python = ["3.12", "3.13"]
 
 [[envs.hatch-test.matrix]]
 deps = ["pre"]

pyproject.toml

@@ -65,7 +65,7 @@ dependencies = [
   "scikit-image>=0.25",
   # due to https://github.com/scikit-image/scikit-image/issues/6850 breaks rescale ufunc
   "scikit-learn>=0.24",
-  "scverse-backends",
+  "scverse-backends>=0.0.2,<0.1",
   "spatialdata>=0.7.1",
   "spatialdata-plot",
   "statsmodels>=0.12",

src/squidpy/_backends/__init__.py

@@ -25,16 +25,16 @@
     },
 )
 
-dispatch = _dispatcher.dispatch
+backend_dispatch = _dispatcher.backend_dispatch
 settings = _dispatcher.settings
 get_backend = _dispatcher.get_backend
 available_backend_names = _dispatcher.available_backend_names
 discover = _dispatcher.discover
 
 __all__ = [
     "available_backend_names",
+    "backend_dispatch",
     "discover",
-    "dispatch",
     "get_backend",
     "settings",
 ]

src/squidpy/_utils.py

@@ -228,6 +228,45 @@ def wrapper(*args: Any, **kwargs: Any) -> Any:
     return wrapper
 
 
+_JOBLIB_BACKENDS = frozenset({"dask", "loky", "multiprocessing", "ray", "sequential", "threading"})
+
+
+def _is_joblib_backend(backend: Any) -> bool:
+    return isinstance(backend, str) and (backend in _JOBLIB_BACKENDS or backend in jl.parallel.BACKENDS)
+
+
+def _deprecate_backend_as_parallel_backend(func: Callable[..., Any]) -> Callable[..., Any]:
+    @functools.wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        if _is_joblib_backend(kwargs.get("backend")):
+            if "parallel_backend" in kwargs:
+                raise TypeError("Pass only one of `backend` or `parallel_backend` for joblib parallelism.")
+            warnings.warn(
+                "Using `backend` for joblib parallelism is deprecated. Use `parallel_backend` instead.",
+                FutureWarning,
+                stacklevel=2,
+            )
+            kwargs["parallel_backend"] = kwargs.pop("backend")
+        return func(*args, **kwargs)
+
+    return wrapper
+
+
+def _deprecate_legacy_joblib_backend(func: Callable[..., Any]) -> Callable[..., Any]:
+    @functools.wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        if _is_joblib_backend(kwargs.get("backend")):
+            warnings.warn(
+                "Using `backend` for joblib parallelism is deprecated and has no effect.",
+                FutureWarning,
+                stacklevel=2,
+            )
+            kwargs.pop("backend")
+        return func(*args, **kwargs)
+
+    return wrapper
+
+
 def _get_n_cores(n_cores: int | None) -> int:
     """
     Make number of cores a positive integer.

src/squidpy/gr/_build.py

@@ -38,6 +38,7 @@
     get_model,
 )
 
+from squidpy._backends import backend_dispatch
 from squidpy._constants._constants import CoordType, Transform
 from squidpy._constants._pkg_constants import Key
 from squidpy._docs import d, inject_docs
@@ -61,6 +62,7 @@ class SpatialNeighborsResult(NamedTuple):
 
 @d.dedent
 @inject_docs(t=Transform, c=CoordType)
+@backend_dispatch
 def spatial_neighbors(
     adata: AnnData | SpatialData,
     spatial_key: str = Key.obsm.spatial,

src/squidpy/gr/_ligrec.py

@@ -8,7 +8,7 @@
 from functools import partial
 from itertools import product
 from types import MappingProxyType
-from typing import TYPE_CHECKING, Any, Literal, TypeAlias
+from typing import TYPE_CHECKING, Any, Literal
 
 import numpy as np
 import pandas as pd
@@ -17,11 +17,11 @@
 from scipy.sparse import csc_matrix
 from spatialdata import SpatialData
 
-from squidpy._backends import dispatch
+from squidpy._backends import backend_dispatch
 from squidpy._constants._constants import ComplexPolicy, CorrAxis
 from squidpy._constants._pkg_constants import Key
 from squidpy._docs import d, inject_docs
-from squidpy._utils import NDArrayA, Signal, SigQueue, _get_n_cores, parallelize
+from squidpy._utils import NDArrayA, Signal, SigQueue, _deprecate_backend_as_parallel_backend, _get_n_cores, parallelize
 from squidpy._validators import assert_positive, check_tuple_needles
 from squidpy.gr._utils import (
     _assert_categorical_obs,
@@ -31,11 +31,11 @@
 
 __all__ = ["ligrec", "PermutationTest"]
 
-StrSeq: TypeAlias = Sequence[str]
-SeqTuple: TypeAlias = Sequence[tuple[str, str]]
-Interaction_t: TypeAlias = pd.DataFrame | Mapping[str, StrSeq] | StrSeq | tuple[StrSeq, StrSeq] | SeqTuple
+type StrSeq = Sequence[str]
+type SeqTuple = Sequence[tuple[str, str]]
+type Interaction_t = pd.DataFrame | Mapping[str, StrSeq] | StrSeq | tuple[StrSeq, StrSeq] | SeqTuple
 
-Cluster_t: TypeAlias = StrSeq | tuple[StrSeq, StrSeq] | SeqTuple
+type Cluster_t = StrSeq | tuple[StrSeq, StrSeq] | SeqTuple
 
 SOURCE = "source"
 TARGET = "target"
@@ -314,6 +314,7 @@ def prepare(
     @d.get_sections(base="PT_test", sections=["Parameters"])
     @d.dedent
     @inject_docs(src=SOURCE, tgt=TARGET, fa=CorrAxis)
+    @_deprecate_backend_as_parallel_backend
     def test(
         self,
         cluster_key: str,
@@ -327,6 +328,7 @@ def test(
         copy: bool = False,
         key_added: str | None = None,
         numba_parallel: bool | None = None,
+        parallel_backend: str = "loky",
         **kwargs: Any,
     ) -> Mapping[str, pd.DataFrame] | None:
         """
@@ -357,6 +359,8 @@ def test(
             If `None`, ``'{{cluster_key}}_ligrec'`` will be used.
         %(numba_parallel)s
         %(parallelize)s
+        parallel_backend
+            Which joblib backend to use for permutation parallelism.
 
         Returns
         -------
@@ -423,6 +427,7 @@ def test(
             seed=seed,
             n_jobs=n_jobs,
             numba_parallel=numba_parallel,
+            parallel_backend=parallel_backend,
             **kwargs,
         )
         index = pd.MultiIndex.from_frame(interactions, names=[SOURCE, TARGET])
@@ -630,7 +635,8 @@ def prepare(
 
 
 @d.dedent
-@dispatch
+@_deprecate_backend_as_parallel_backend
+@backend_dispatch
 def ligrec(
     adata: AnnData | SpatialData,
     cluster_key: str,
@@ -643,6 +649,7 @@ def ligrec(
     copy: bool = False,
     key_added: str | None = None,
     gene_symbols: str | None = None,
+    parallel_backend: str = "loky",
     **kwargs: Any,
 ) -> Mapping[str, pd.DataFrame] | None:
     """
@@ -655,6 +662,8 @@ def ligrec(
     %(PT_test.parameters)s
     gene_symbols
         Key in :attr:`anndata.AnnData.var` to use instead of :attr:`anndata.AnnData.var_names`.
+    parallel_backend
+        Which joblib backend to use for permutation parallelism.
 
     Returns
     -------
@@ -673,6 +682,7 @@ def ligrec(
                 corr_axis=corr_axis,
                 copy=copy,
                 key_added=key_added,
+                parallel_backend=parallel_backend,
                 **kwargs,
             )
         )
@@ -688,6 +698,7 @@ def _analysis(
     seed: int | None = None,
     n_jobs: int = 1,
     numba_parallel: bool | None = None,
+    parallel_backend: str = "loky",
     **kwargs: Any,
 ) -> TempResult:
     """
@@ -711,8 +722,10 @@ def _analysis(
         Number of parallel jobs to launch.
     numba_parallel
         Whether to use :func:`numba.prange` or not. If `None`, it's determined automatically.
+    parallel_backend
+        Which joblib backend to use for permutation parallelism.
     kwargs
-        Keyword arguments for :func:`squidpy._utils.parallelize`, such as ``n_jobs`` or ``backend``.
+        Additional keyword arguments for :func:`squidpy._utils.parallelize`.
 
     Returns
     -------
@@ -756,6 +769,7 @@ def extractor(res: Sequence[TempResult]) -> TempResult:
         _analysis_helper,
         np.arange(n_perms, dtype=np.int32).tolist(),
         n_jobs=n_jobs,
+        backend=parallel_backend,
         unit="permutation",
         extractor=extractor,
         **kwargs,

src/squidpy/gr/_nhood.py

@@ -17,10 +17,18 @@
 from scanpy import logging as logg
 from spatialdata import SpatialData
 
+from squidpy._backends import backend_dispatch
 from squidpy._constants._constants import Centrality
 from squidpy._constants._pkg_constants import Key
 from squidpy._docs import d, inject_docs
-from squidpy._utils import NDArrayA, Signal, SigQueue, _get_n_cores, parallelize
+from squidpy._utils import (
+    NDArrayA,
+    Signal,
+    SigQueue,
+    _deprecate_backend_as_parallel_backend,
+    _get_n_cores,
+    parallelize,
+)
 from squidpy._validators import assert_positive
 from squidpy.gr._utils import (
     _assert_categorical_obs,
@@ -134,6 +142,8 @@ def _create_function(n_cls: int, parallel: bool = False) -> Callable[[NDArrayA,
 
 @d.get_sections(base="nhood_ench", sections=["Parameters"])
 @d.dedent
+@_deprecate_backend_as_parallel_backend
+@backend_dispatch
 def nhood_enrichment(
     adata: AnnData | SpatialData,
     cluster_key: str,
@@ -144,7 +154,7 @@ def nhood_enrichment(
     seed: int | None = None,
     copy: bool = False,
     n_jobs: int | None = None,
-    backend: str = "loky",
+    parallel_backend: str = "loky",
     show_progress_bar: bool = True,
 ) -> NhoodEnrichmentResult | None:
     """
@@ -161,6 +171,8 @@ def nhood_enrichment(
     %(seed)s
     %(copy)s
     %(parallelize)s
+    parallel_backend
+        Which joblib backend to use for parallel neighborhood enrichment.
 
     Returns
     -------
@@ -203,7 +215,7 @@ def nhood_enrichment(
         collection=np.arange(n_perms).tolist(),
         extractor=np.vstack,
         n_jobs=n_jobs,
-        backend=backend,
+        backend=parallel_backend,
         show_progress_bar=show_progress_bar,
     )(
         callback=_test,
@@ -230,14 +242,16 @@ def nhood_enrichment(
 
 @d.dedent
 @inject_docs(c=Centrality)
+@_deprecate_backend_as_parallel_backend
+@backend_dispatch
 def centrality_scores(
     adata: AnnData | SpatialData,
     cluster_key: str,
     score: str | Iterable[str] | None = None,
     connectivity_key: str | None = None,
     copy: bool = False,
     n_jobs: int | None = None,
-    backend: str = "loky",
+    parallel_backend: str = "loky",
     show_progress_bar: bool = False,
 ) -> pd.DataFrame | None:
     """
@@ -260,6 +274,8 @@ def centrality_scores(
     %(conn_key)s
     %(copy)s
     %(parallelize)s
+    parallel_backend
+        Which joblib backend to use for parallel centrality computation.
 
     Returns
     -------
@@ -307,7 +323,7 @@ def centrality_scores(
             collection=cat,
             extractor=pd.concat,
             n_jobs=n_jobs,
-            backend=backend,
+            backend=parallel_backend,
             show_progress_bar=show_progress_bar,
         )(clusters=clusters, fun=v, method=k)
         res_list.append(df)
@@ -326,6 +342,7 @@ def centrality_scores(
 
 
 @d.dedent
+@backend_dispatch
 def interaction_matrix(
     adata: AnnData | SpatialData,
     cluster_key: str,

src/squidpy/gr/_niche.py

@@ -18,6 +18,7 @@
 from spatialdata import SpatialData
 from spatialdata._logging import logger as logg
 
+from squidpy._backends import backend_dispatch
 from squidpy._constants._constants import NicheDefinitions
 from squidpy._docs import d, inject_docs
 from squidpy._validators import assert_isinstance, assert_key_in_adata, assert_one_of
@@ -27,6 +28,7 @@
 
 @d.dedent
 @inject_docs(fla=NicheDefinitions)
+@backend_dispatch
 def calculate_niche(
     data: AnnData | SpatialData,
     flavor: Literal["neighborhood", "utag", "cellcharter", "spatialleiden"],