docs: document array type support

[flying-sheep]

• Closes Document dask support for highly variable genes #3892
• Tests included or not required because:

• Release notes not necessary because:

I double-checked everything in #2578 and mostly winged it for the rest.

Would be nice if one of you could take a look if I mis-specified something.

• I didn’t check if some flavors of highly_variable_genes supports only CSR. Any idea?
• I tried to document things that implicitly convert to csr as “not supporting csc”, except when that’s conditional (i.e sc.pp.scale supports CSC if you don’t specify mask_obs, so that’s detailed in mask_obs).

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.80%. Comparing base (830d15e) to head (0bce8e5).
⚠️ Report is 42 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3895      +/-   ##
==========================================
+ Coverage   69.09%   76.80%   +7.70%     
==========================================
  Files         116      117       +1     
  Lines       12403    12441      +38     
==========================================
+ Hits         8570     9555     +985     
+ Misses       3833     2886     -947     

Flag	Coverage Δ
hatch-test.pre	76.80% <100.00%> (+7.70%)	⬆️

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

Files with missing lines	Coverage Δ
src/scanpy/_utils/_docs.py	100.00% <100.00%> (ø)
...c/scanpy/experimental/pp/_highly_variable_genes.py	18.44% <ø> (ø)
src/scanpy/get/_aggregated.py	92.95% <ø> (+41.78%)	⬆️
src/scanpy/neighbors/__init__.py	80.05% <ø> (ø)
src/scanpy/preprocessing/_combat.py	88.46% <ø> (+76.92%)	⬆️
src/scanpy/preprocessing/_highly_variable_genes.py	94.71% <ø> (+53.52%)	⬆️
src/scanpy/preprocessing/_normalization.py	94.66% <ø> (ø)
src/scanpy/preprocessing/_pca/__init__.py	90.65% <ø> (+2.19%)	⬆️
src/scanpy/preprocessing/_qc.py	95.83% <ø> (+41.66%)	⬆️
src/scanpy/preprocessing/_scale.py	91.20% <ø> (ø)
... and 15 more

... and 18 files with indirect coverage changes

[grst]

How hard would it be to make an overview page that lists all functions in a single table?

[ilan-gold]

@flying-sheep I'll try to look tomorrow more closely but I do like @grst's suggestion. That being said, I don't think it should be instead of what is here, this is really cool!

[flying-sheep]

Can you draft how that would look like? Tables for something like PCA are already quite big, and I can’t imagine how to lay out one big table in a way that it would be clear what’s going on.

[grst]

I had in mind something like this

✅ = supported
❌ = not supported
⚡= supported in dask

Function	numpy.ndarray	csr_array	csr_matrix	csc_array	csc_matrix
sc.tl.pca	✅⚡	✅⚡	✅⚡	✅	✅
sc.tl.tsne	✅	✅	✅	❌	❌
sc.tl.umap	✅⚡	✅	✅	❌	❌
...

[Intron7]

@flying-sheep I have not checked how this work or not. But do umap and tsne work with sp_matrix and arrays?

[flying-sheep]

Yes! In umap, doing sc.pp.neighbors(adata, use_rep="X") results in X being passed to simplicial_set_embedding, which will do a TruncatedSVD on it.

TSNE calls validate_data(self, X, accept_sparse=["csr", "csc", "coo"], ...) which very likely also means it supports it.

Thanks, thinking like this is exactly the reason I requested your reviews! Could have easily been that I messed this up.

[grst]

The table leads to horizontal scrolling for me

Also not sure if the top of the API page is the best place to place it? Maybe even have a dedicated page for it?

[flying-sheep]

OK, all fixed.

• I left it on the API page but added a header
• made all individual functions’ tables link back to it
• made things smaller by removing the way to distinguish scipy.sparse’s *_matrix and *_array, everything should support both or none.

compare the tables:

• sc.get.aggregate, which supports all sparse types
• sc.pp.downsample_counts which only supports CSR

only thing left to do (but I probably won’t) would be to make it read scipy.sparse.csr_{array,matrix} instead of scipy.sparse.csr_array / csr_matrix for consistency.