feat: add distances parameter to sc.pp.neighbors

[amalia-k510]

Adding a function, neighbors_from_distance, that allows users to compute connectivities and distances directly from precomputed distance matrix. Might be useful where distances are generated externally, and we want to plug them into the standard scanpy graph-based pipeline without recomputing neighbors.

This function should support the following:

• supports both dense and sparse matrices
• zeroes the diagonal to avoid self-loops
• builds connectivities using either the UMAP or Gauss method
• stores results in .obsp and .uns using the same structure as sc.pp.neighbors,
• optionally allows key namespacing via key_added

[flying-sheep]

looks good except for the metrics changes being here instead of remaining in their own PR 😉

It also looks like some code is copied. Please check if you can introduce a helper function for everything after if method == "umap":, looks like most of that is identical to what’s in def neighbors. But if it’s too complicated or different, don’t do it!

Please also (after removing the metrics tests from this PR) add tests to check that passing distances results in the same stuff being added to adata as not doing it. Something like

adata_n = ...
adata_d = adata_n.copy()

sc.pp.neighbors(adata_n)
sc.pp.neighbors(adata_d, distances=adata_n.obsp["distances"])

# for all the parts that should be there:
np.testing.assert_almost_equal(...)
…

# for all the parts that can’t be derived from distances
assert "somekey" in adata_n.…
assert "somekey" not in adata_d.…

[flying-sheep]

looks good! please add a release note by running hatch run towncrier:create 3627.feature.md and editing that (don’t forget to add your name as in the other release note fragments)

[codecov]

Codecov Report

❌ Patch coverage is 82.35294% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.16%. Comparing base (2ff2a9b) to head (656bee0).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/scanpy/neighbors/__init__.py	81.81%	12 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3627      +/-   ##
==========================================
+ Coverage   77.13%   78.16%   +1.03%     
==========================================
  Files         117      117              
  Lines       12558    12586      +28     
==========================================
+ Hits         9686     9838     +152     
+ Misses       2872     2748     -124     

Flag	Coverage Δ
hatch-test.low-vers	77.49% <82.35%> (?)
hatch-test.pre	77.12% <82.35%> (-0.01%)	⬇️

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

Files with missing lines	Coverage Δ
src/scanpy/metrics/_metrics.py	93.54% <100.00%> (ø)
src/scanpy/neighbors/_connectivity.py	88.23% <100.00%> (ø)
src/scanpy/neighbors/__init__.py	80.19% <81.81%> (-0.39%)	⬇️

... and 8 files with indirect coverage changes