Improve documentation of gr.spatial_neighbors

[grst]

Spatial neighbors has many different modes

• grid vs. non grid
• delauney vs. nearest neighbors
• knn vs. radius-based

To me, it is not entirely clear from the docs, how the different parameters interact.

• If I specify both n_neighs, and a radius, what takes precedence? Or are both cutoffs applied
• If I specify both delauney and radius/n_neigh, what takes precedence?

I think this could be clearer in the docs.

Not sure if it is still an option, but an alternative could be to split up the function into multiple functions for different purposes, e.g.

gr.spatial_neighbors_grid
gr.spatial_neighbors_knn
gr.spatial_neighbors_delauney
gr.spatial_neighbors_radius

In that case, only arguments relevant to the respective methods would be in the function signature.

[grst]

Having separate functions for separate NN-flavors would also make it easier to use algorithms optimized towards a specific flavor. E.g. for radius based NN, much faster implementations exist than KDTree, e.g. https://github.com/nla-group/snn

[selmanozleyen]

Thank you, I agree that we should have separate functions in general for squidpy. It would be also easier for someone to add an extension like in #1023 . Keeping the legacy function as a convenience function IMO is would be the best solution. And would reduce the maintenance of the code greatly IMO