From ab1fd9e10963a2da86e3480b2a11975823d57f08 Mon Sep 17 00:00:00 2001 From: CuiweiG <48gaocuiwei@gmail.com> Date: Tue, 21 Apr 2026 13:22:35 +0800 Subject: [PATCH 1/3] docs(neighbors): distinguish kernel from kNN search backend The previous lead stated that kNN search relies on UMAP and bundled that with the choice of connectivity kernel, conflating two stages controlled by independent parameters: ``transformer`` (kNN search backend) and ``method`` (connectivity kernel). --- src/scanpy/neighbors/__init__.py | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/src/scanpy/neighbors/__init__.py b/src/scanpy/neighbors/__init__.py index 239822e3f2..9ba9403211 100644 --- a/src/scanpy/neighbors/__init__.py +++ b/src/scanpy/neighbors/__init__.py @@ -102,12 +102,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 @@ -133,12 +133,13 @@ def neighbors( # noqa: PLR0913 Kernel to assign low weights to neighbors more distant than the `n_neighbors` nearest neighbor. method - Use 'umap' :cite:p:`McInnes2018`, + 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: From 43f1b6f5fafba3b5b2e95793cf796f6048005fc4 Mon Sep 17 00:00:00 2001 From: CuiweiG <48gaocuiwei@gmail.com> Date: Tue, 21 Apr 2026 15:24:45 +0800 Subject: [PATCH 2/3] docs(neighbors): add release note fragment --- docs/release-notes/4079.docs.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/release-notes/4079.docs.md diff --git a/docs/release-notes/4079.docs.md b/docs/release-notes/4079.docs.md new file mode 100644 index 0000000000..b3eef060ae --- /dev/null +++ b/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` From 5c394fc99d7e1ce76b6528eee89b7113db048dd5 Mon Sep 17 00:00:00 2001 From: "Philipp A." Date: Tue, 21 Apr 2026 13:13:56 +0200 Subject: [PATCH 3/3] style: reformat for diff-friendlyness --- src/scanpy/neighbors/__init__.py | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/src/scanpy/neighbors/__init__.py b/src/scanpy/neighbors/__init__.py index 9ba9403211..3622c02576 100644 --- a/src/scanpy/neighbors/__init__.py +++ b/src/scanpy/neighbors/__init__.py @@ -102,12 +102,12 @@ def neighbors( # noqa: PLR0913 ) -> AnnData | None: """Compute the nearest neighbors distance matrix and a neighborhood graph of observations :cite:p:`McInnes2018`. - 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. + 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 @@ -134,8 +134,9 @@ def neighbors( # noqa: PLR0913 `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`, + 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`). transformer