Skip to content

ENH: Add Array API support to center_distance_matrix#2436

Open
LarytheLord wants to merge 2 commits intoscikit-bio:mainfrom
LarytheLord:enh/center-distance-matrix-array-api
Open

ENH: Add Array API support to center_distance_matrix#2436
LarytheLord wants to merge 2 commits intoscikit-bio:mainfrom
LarytheLord:enh/center-distance-matrix-array-api

Conversation

@LarytheLord
Copy link
Copy Markdown

center_distance_matrix() currently only dispatches to the Cython implementation, which requires NumPy arrays via the CPython buffer protocol. This means GPU-backed arrays (CuPy, JAX, PyTorch) cannot pass through center_distance_matrix() or the PCoA pipeline that depends on it.

What changed

  • NumPy arrays continue using the optimized Cython path (zero regression)
  • Non-NumPy arrays now go through a pure-xp fallback implementing the same Gower centering (Eqs. 9.20 and 9.21, Legendre & Legendre 1998) using ingest_array and xp.mean
  • Array type and device are preserved for GPU backends
  • inplace=True is documented as NumPy-only

Tests

  • Added TestCenterDistanceMatrixArrayAPI with NumPy, PyTorch, and JAX backends
  • Validates type preservation, device preservation, and numerical correctness against f_matrix(e_matrix()) reference
  • All existing ordination tests pass (144 passed, 0 failures)

Numerical agreement

Cython vs xp path max absolute difference at n=100: 8.88e-16

Context

This follows the same ingest_array + xp namespace pattern established in the composition module (centralize, vlr, closure, clr, etc.) and extends Array API support into the ordination module for the first time.

Related: #2429

@codecov
Copy link
Copy Markdown

codecov Bot commented Apr 2, 2026

Codecov Report

❌ Patch coverage is 47.05882% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.77%. Comparing base (3b445f3) to head (839b162).

Files with missing lines Patch % Lines
skbio/stats/ordination/_utils.py 47.05% 7 Missing and 2 partials ⚠️

❌ Your patch check has failed because the patch coverage (47.05%) is below the target coverage (80.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files
@@            Coverage Diff             @@
##             main    #2436      +/-   ##
==========================================
- Coverage   97.81%   97.77%   -0.05%     
==========================================
  Files         127      127              
  Lines       15640    15649       +9     
  Branches     2882     2883       +1     
==========================================
+ Hits        15299    15301       +2     
- Misses        165      171       +6     
- Partials      176      177       +1     

☔ View full report in Codecov by Sentry.
📢 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.

center_distance_matrix() currently only dispatches to the Cython
implementation, which requires NumPy arrays via the buffer protocol.
GPU-backed arrays (CuPy, JAX, PyTorch) cannot flow through it.

Add an xp-compatible fallback path using ingest_array and xp.mean,
implementing the same Gower centering (Eqs. 9.20/9.21, Legendre &
Legendre 1998). NumPy arrays continue using the optimized Cython path.

Array type and device are preserved for non-NumPy backends. Tests added
for NumPy, PyTorch, and JAX.
…trix

Add array-api-strict to CI test requirements so the Array API fallback
path is exercised on every run without requiring optional GPU backends.

Two new tests in TestCenterDistanceMatrixArrayAPI:
- test_numpy_noncontiguous: covers the C-contiguous conversion branch
  by passing a Fortran-order array
- test_xp_array_api_strict: covers the full xp fallback path

Also adds a changelog entry for the Array API support introduced in this PR.
@LarytheLord LarytheLord force-pushed the enh/center-distance-matrix-array-api branch from 839b162 to 875c92c Compare April 17, 2026 16:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant