Backport PR #4079 on branch 1.12.x (docs: clarify method vs transformer in sc.pp.neighbors) (#4086)

Co-authored-by: Cuiwei Gao <48gaocuiwei@gmail.com>

Author: meeseeksmachine

docs/release-notes/4079.docs.md

@@ -0,0 +1 @@
+Clarify that `method` selects the connectivity kernel and `transformer` selects the kNN search backend in {func}`~scanpy.pp.neighbors` {smaller}`C Gao`

src/scanpy/neighbors/__init__.py

@@ -96,12 +96,12 @@ def neighbors(  # noqa: PLR0913
 ) -> AnnData | None:
     """Compute the nearest neighbors distance matrix and a neighborhood graph of observations :cite:p:`McInnes2018`.
 
-    The neighbor search efficiency of this heavily relies on UMAP :cite:p:`McInnes2018`,
-    which also provides a method for estimating connectivities of data points -
-    the connectivity of the manifold (`method=='umap'`).
-    If `method=='gauss'`, connectivities are computed according to :cite:t:`Coifman2005`,
-    in the adaption of :cite:t:`Haghverdi2016`.
-    If `method=='jaccard'`, connectivities are computed as in PhenoGraph :cite:p:`Levine2015`.
+    The computation proceeds in two independent stages.
+    First, a k-nearest neighbor (kNN) search produces the distance matrix via the estimator passed as ``transformer``.
+    Second, connectivities are derived from the kNN search output by the kernel selected via ``method``.
+    The two stages are controlled by independent parameters:
+    ``transformer`` selects the kNN search backend,
+    ``method`` selects the connectivity kernel.
 
     .. array-support:: pp.neighbors
 
@@ -127,12 +127,14 @@ def neighbors(  # noqa: PLR0913
         Kernel to assign low weights to neighbors more distant than the
         `n_neighbors` nearest neighbor.
     method
+        Kernel that derives connectivities from the kNN search output.
+        The choice is independent of the kNN search backend,
+        which is controlled by ``transformer``.
         Use 'umap' :cite:p:`McInnes2018`,
         'gauss' (Gauss kernel following :cite:t:`Coifman2005` with adaptive width :cite:t:`Haghverdi2016`),
-        or 'jaccard' (Jaccard kernel as in PhenoGraph, :cite:t:`Levine2015`)
-        for computing connectivities.
+        or 'jaccard' (Jaccard kernel as in PhenoGraph, :cite:t:`Levine2015`).
     transformer
-        Approximate kNN search implementation following the API of
+        kNN search backend following the API of
         :class:`~sklearn.neighbors.KNeighborsTransformer`.
         See :doc:`/how-to/knn-transformers` for more details.
         Also accepts the following known options: