feat: switch to use and out

[flying-sheep]

Current design:

• deprecate copy everywhere
• functions operating on a main matrix get use and out – default for out is to operate in place, out=None means returning the matrix instead of writing it into AnnData.
  • Variant: out=True could mean return and out=False inplace, that way users could specify it intentionally
• multi-in/out functions use key_added/inplace for the same functionality, like Neighbors(dists=A.obsp["foo"], conns=A.obsp["bar"], meta=A.uns["foo"]) (where A.uns doesn’t even exist yet)
  • Variant: create NamedTuples or so for the spots used. Probably what @ilan-gold would prefer, but we should meet to spec this out.

Examples for use/out (key_added is unchanged):

# in-place on X
sc.pp.log1p(adata)
# read counts, write X
sc.pp.log1p(adata, use=A.layers["counts"], out=A.X)
# return numpy array, equivalent to `sc.pp.log1p(adata.X)`
logged = sc.pp.log1p(adata, out=None)

out makes the singledispatch use some functions have (sc.pp.log1p(adata.X)) unnecessaary, so we might deprecate that, what do you think?

Example for how this improves code:

-logged = sc.pp.log1p(adata_obs, copy=True)
-sc.pp.highly_variable_genes(logged)
-adata_obs = adata_obs[:, logged.var["highly_variable"]]
+sc.pp.log1p(adata_obs, out="layers.log1p")
+sc.pp.highly_variable_genes(adata_obs, use="layers.log1p")
+adata_obs = adata_obs[:, adata_obs.var["highly_variable"]]

TODO:

• use needs to be consistently documented
• use_raw needs deprecating
• scale still writes var["mean"]/["std"] under out=None, should maybe gain a return_stats parameter or so
• regress_out copies a backed array before rejecting it

---

• Closes anndata.acc replacement for functions taking obsm, layer, … #4334, closes Remove inplace/copy #2583
• Tests included or not required because:

• Release notes not necessary because:

[codecov]

Codecov Report

❌ Patch coverage is 89.35361% with 28 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.92%. Comparing base (5f2accb) to head (15957fe).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/scanpy/get/get.py	80.89%	17 Missing ⚠️
src/scanpy/preprocessing/_simple.py	83.87%	5 Missing ⚠️
src/scanpy/preprocessing/_scale.py	85.00%	3 Missing ⚠️
src/scanpy/tools/_rank_genes_groups.py	77.77%	2 Missing ⚠️
src/scanpy/tools/_score_genes.py	83.33%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff            @@
##           main    #4359       +/-   ##
=========================================
+ Coverage      0   81.92%   +81.92%     
=========================================
  Files         0      134      +134     
  Lines         0    12794    +12794     
=========================================
+ Hits          0    10482    +10482     
- Misses        0     2312     +2312     

Flag	Coverage Δ
hatch-test.low-vers	78.48% <72.24%> (?)
hatch-test.pre	81.79% <89.35%> (?)

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

Files with missing lines	Coverage Δ
src/scanpy/_docs.py	100.00% <100.00%> (ø)
src/scanpy/_utils/__init__.py	76.68% <100.00%> (ø)
src/scanpy/experimental/_docs.py	100.00% <100.00%> (ø)
...c/scanpy/experimental/pp/_highly_variable_genes.py	100.00% <100.00%> (ø)
src/scanpy/experimental/pp/_normalization.py	100.00% <100.00%> (ø)
src/scanpy/get/__init__.py	100.00% <ø> (ø)
src/scanpy/get/_aggregated.py	96.37% <100.00%> (ø)
src/scanpy/metrics/_gearys_c.py	100.00% <100.00%> (ø)
src/scanpy/metrics/_morans_i.py	100.00% <100.00%> (ø)
src/scanpy/neighbors/__init__.py	81.93% <100.00%> (ø)
... and 18 more

... and 106 files with indirect coverage changes