Skip to content

docs: clarify method vs transformer in sc.pp.neighbors #4079

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
CuiweiG wants to merge 3 commits into
base: main
Choose a base branch
from
+12 −9
Open

docs: clarify method vs transformer in sc.pp.neighbors #4079

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ab1fd9e
docs(neighbors): distinguish kernel from kNN search backend
CuiweiG Apr 21, 2026
43f1b6f
docs(neighbors): add release note fragment
CuiweiG Apr 21, 2026
5c394fc
style: reformat for diff-friendlyness
flying-sheep Apr 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/release-notes/4079.docs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`
20 changes: 11 additions & 9 deletions src/scanpy/neighbors/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -133,12 +133,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:
Expand Down
Loading