Array-API fallback for Combiner.sigma_clipping when the namespace is not numpy

[mwcraig]

Part of #929 (the Combiner.sigma_clipping half). Companion PR: #1000 (the sigma_func half), built off the same main; the two touch different files and merge cleanly in either order (the only overlap is adjacent bullets in CHANGES.rst / docs/array_api.rst).

Combiner.sigma_clipping wrapped astropy.stats.sigma_clip unconditionally, which converts the data to numpy and fails outright on array-api-strict (3 of the 13 remaining strict failures).

Policy (numpy is untouched): when the namespace is numpy, the data still go to astropy.stats.sigma_clip exactly as before — masked=True, all extra keyword arguments forwarded, compiled fast path intact. Every other namespace uses a new private _sigma_clip_mask, an iterative clip written purely in terms of the array API that reproduces astropy's mask: the last iteration's bounds applied to the original data, non-finite values always masked, None/0 thresholds meaning 3 as in astropy. The 'median'/'mean'/'std'/'mad_std' string options map to the same tiered (bottleneck → native → fallback) NaN-aware reductions the combination methods use (new private _nanmadstd for 'mad_std'); astropy-only keyword arguments (grow, masked, return_bounds, …) raise TypeError off numpy. An integer maxiters runs with no host synchronisation, so on dask the clip stays one graph.

Latent bug fixed: axis, copy and maxiters were read with kwd.get and then forwarded again through **kwd, so passing any of them raised TypeError: got multiple values for keyword argument. They are popped now.

Docstring fixes: func defaults to 'mean', not 'median'; None thresholds are treated as 3 (as astropy does) rather than "no rejection" — the docstring still described the pre-2.4 behaviour. The None/0/negative threshold semantics are a behaviour question, not part of this PR — see #1002.

Tests: the three test_combiner_sigmaclip_* tests are parametrized over a backend-generic MAD callable and "mad_std" and no longer use numpy-only .all(). A differential test runs _sigma_clip_mask on every backend against astropy.stats.sigma_clip(..., masked=True, copy=False).mask over 5 data sets (outliers, NaN/inf incl. an all-NaN column, zero spread, a column that collapses mid-loop, ints) × 3 cenfuncs × 3 stdfuncs × 4 threshold pairs × maxiters ∈ {1, 3, None}; plus tests for silence on all-NaN slices, None/0 → 3, final-bounds-not-union semantics, numpy scalar thresholds, bad axes/strings, _nanmadstd vs mad_std, a spy proving astropy is called iff numpy, the axis/maxiters regression, astropy-only kwargs, the use_astropy deprecation, existing-mask preservation, and combine(sigma_clip=True) (previously not exercised at all). Design was prototype-verified against astropy over 864 structured cases (numpy + strict device1), 2400 random numpy trials and 243 cases each on jax and dask, 0 mismatches.

Docs: changelog entry; one bullet in docs/array_api.rst; docs/image_combination.rst now recommends func="median" over np.ma.median. The combiner.py sigma_clipping line leaves the escape baseline (confirmed by a full-suite dask regeneration; the diff is that one line).

Verified locally

• numpy: 1123 passed
• array-api-strict: 10 failed (down from 13: the 8 sigma_func tests for the companion PR, Array API: units/Quantity handling with non-numpy arrays #936, Consider marray as a uniform masked-array representation across array backends #983), 0 xpassed
• jax (X64): 1122 passed
• dask: 1116 passed; escape-baseline enforce run clean
• Merged locally with the companion PR: strict 2 failed (Array API: units/Quantity handling with non-numpy arrays #936, Consider marray as a uniform masked-array representation across array backends #983), 0 xpassed; enforce run clean

🤖 Generated with Claude Code

https://claude.ai/code/session_01XGArZMnLPC1G7YP62vN18V

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.92%. Comparing base (57fd985) to head (8fb4719).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1001      +/-   ##
==========================================
+ Coverage   97.78%   97.92%   +0.13%     
==========================================
  Files           9        9              
  Lines        1808     1878      +70     
==========================================
+ Hits         1768     1839      +71     
+ Misses         40       39       -1     

Flag	Coverage Δ
dask	97.11% <100.00%> (+0.16%)	⬆️
jax	97.27% <100.00%> (+0.15%)	⬆️
numpy	97.81% <100.00%> (+0.13%)	⬆️

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

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.