Skip to content

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

Open
CuiweiG wants to merge 3 commits intoscverse:mainfrom
CuiweiG:docs/neighbors-method-transformer
Open

docs: clarify method vs transformer in sc.pp.neighbors#4079
CuiweiG wants to merge 3 commits intoscverse:mainfrom
CuiweiG:docs/neighbors-method-transformer

Conversation

@CuiweiG
Copy link
Copy Markdown

@CuiweiG CuiweiG commented Apr 21, 2026

Problem

The sc.pp.neighbors docstring bundles the kNN search and the
connectivity kernel into a single lead sentence attributing both to
UMAP. The parameters controlling the two stages are independent:
transformer selects the kNN search backend, method selects the
connectivity kernel. The lead paragraph and the method /
transformer parameter descriptions obscure this.

Change

  • Rewrite the lead paragraph to describe the two stages separately.
  • Add a sentence to the method parameter description stating that
    the choice is independent of the kNN search backend.
  • Replace "Approximate kNN search implementation" with "kNN search
    backend" in the transformer description. The original wording
    contradicted the same block, which already stated that exact kNN
    is used for small data.

No signature, default, or behavior change.

Verification

  • sphinx-build -W --keep-going produces 0 new warnings; all four
    citations (McInnes2018, Coifman2005, Haghverdi2016, Levine2015)
    resolve; both :class: cross-references resolve.
  • pre-commit run --all-files: 15/15 hooks pass.
  • pytest tests/test_neighbors.py tests/test_neighbors_common.py tests/test_neighbors_key_added.py: 36 passed.

Closes #277.

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).
@codecov
Copy link
Copy Markdown

codecov Bot commented Apr 21, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.60%. Comparing base (9909599) to head (5c394fc).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #4079   +/-   ##
=======================================
  Coverage   78.60%   78.60%           
=======================================
  Files         118      118           
  Lines       12755    12755           
=======================================
  Hits        10026    10026           
  Misses       2729     2729           
Flag Coverage Δ
hatch-test.low-vers 77.90% <ø> (ø)
hatch-test.pre 78.48% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
src/scanpy/neighbors/__init__.py 82.04% <ø> (ø)

@flying-sheep
Copy link
Copy Markdown
Member

Thanks, looks good! You marked this as draft, do you plan to make more changes?

@flying-sheep flying-sheep added this to the 1.12.2 milestone Apr 21, 2026
@CuiweiG
Copy link
Copy Markdown
Author

CuiweiG commented Apr 21, 2026

Thanks! Nothing more to change — I had it in draft pending feedback. Switching to ready now.

@CuiweiG CuiweiG marked this pull request as ready for review April 21, 2026 11:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

improve sc.pp.neighbors parameter docs

2 participants