Start overhaul for embedding sort order

[ivirshup]

• Closes Order of plotting datapoints with categorical colouring should be amended #1263
• Tests included or not required because:

• Release notes not necessary because:

Implements something close to what is described here:

• Order of plotting datapoints with categorical colouring should be amended #1263 (comment)

Doesn't:

• Use "current", instead that's just None
• Include random, instead lets the user pass an array to order by, so random can be rng.permutation(adata.n_obs)
• Do broadcasting. Can either be added later or we can tell people to do this themselves.

TODO:

• Check when input order array has repeated values
• Test sort_order argument deprecation
• Add support for pd.Series array values.
  • Maybe lists?
• "How to" or modify existing advanced plotting tutorial
• Tests for
  • Categorical ordering
    • None is same as np.arange(N)
    • direct overlap + ordering is equivalent to masking
  • Continuous ordering
    • "ascending" is like np.argsort(values) and vice versa
    • "ascending" is like "descending" for inverted values
  • Check masking for both
  • Errors
    • For incorrectly sized input array
    • incorrect non-array input
• "ascending" is when the highest value goes on top, right?

[codecov]

Codecov Report

Attention: Patch coverage is 48.71795% with 20 lines in your changes are missing coverage. Please review.

Project coverage is 75.43%. Comparing base (10f4ebc) to head (06c93dc).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2998      +/-   ##
==========================================
- Coverage   75.52%   75.43%   -0.09%     
==========================================
  Files         117      117              
  Lines       12951    12986      +35     
==========================================
+ Hits         9781     9796      +15     
- Misses       3170     3190      +20     

Files	Coverage Δ
scanpy/plotting/_tools/scatterplots.py	83.29% <48.71%> (-3.19%)	⬇️