[smcolby]

Description

deimos.alignment.tolerance pairs features within a fixed distance of each other. Some lookups need the reverse geometry: which features fall inside a set of ranges, each with its own extent. An example is labeling MS2 spectra by whether their precursor m/z and retention time fall inside a feature's m/z and time span, padded by a margin. Batch deimos.slice handles one range per slice, but with return_index it builds a ranges-by-rows boolean mask, and it returns the rows of each range rather than the ranges of each row. Code with that need writes a dense comparison in chunks.

This PR adds deimos.alignment.within(features, boxes, dims, low, high):

• Each row of boxes has a lower and an upper bound per dimension, in the columns that low and high give in the order of dims. They default to each dimension with _min and _max appended.
• A box contains a feature when every coordinate lies within its bounds, inclusive.
• The return matches tolerance: the matched rows of features and boxes, row for row, ordered by position in features and then in boxes, or None, None when no box contains a feature.
• NaN coordinates and NaN bounds match nothing.

The search follows the sparse approach of tolerance since #67. A box can contain a value only when its lower bound lies between the value minus the widest box and the value. Each feature is windowed over the boxes sorted by lower bound in the dimension that yields the fewest candidates, and the candidates are then checked in every dimension, about a million at a time. A dimension with an unbounded box is not used for windowing, since that box can contain any value.

Verification

• 7 new tests in tests/test_alignment.py:

  • Many-to-many pairs, with a feature in two boxes and a feature in none.
  • Inclusive bounds.
  • Named bound columns.
  • No containing box.
  • NaN values and bounds.
  • A box with an infinite bound.
  • 2,000 random features against 500 random boxes, which return the same pairs in the same order as a dense comparison.

• python -m pytest: 390 tests, 5 failing, the same 5 that fail on master in this environment (pandas 3.0.3, NumPy 2.5.2). They are in tests/test_deconvolution.py, where this environment's SciPy raises _dfitpack.error for a spline with too few points. ruff check and ruff format --check pass, and In this environment, pyright reports the same 19 errors in the two changed files as on master. CI installs pandas 2.3.3, under which pyright also checks the label arguments to DataFrame; its pyright check and its test runs on Ubuntu, macOS, and Windows pass.

• On two LC-MS studies, the MS2 precursors (m/z and retention time) were assigned to background features (m/z range padded by a ppm window, time range padded by a margin), taking the first containing feature in m/z order. The assignments were identical to a dense chunked comparison:

  Spectra	Features	On a feature	Dense comparison	within
  48,656	1,372	14,293	153 ms	11 ms
  11,785	612	6,146	13 ms	2 ms

Notes for reviewers

• Candidate windows reach back by the widest box, so one very wide box in a dimension makes that dimension a poor window. The search then uses another dimension, or checks every pair if every dimension has a wide box.
• I named the function within after the condition it tests. contained_in or in_boxes would also fit.

No related issue.

Quality assurance and AI policy

To maintain project quality and respect maintainer bandwidth, please confirm the following about this pull request (PR):

• Manual verification: I have manually reviewed and tested the code in this PR, and python -m pytest passes locally.
• AI-assisted content: If artificial intelligence (AI) tools (for example, GitHub Copilot or ChatGPT) were used, I have personally verified the logic, edge cases, and compliance with the existing codebase. I confirm the code is not a "blind" AI generation.
• Minimal review: I believe this PR is in a state that requires minimal intervention or correction from maintainers.
• Scoped change: This PR addresses a single, well-scoped issue rather than multiple unrelated changes.

Status

• Ready to go (checking this signals to maintainers that the PR is ready for final review)

Developer Certificate of Origin

• I certify that this contribution is covered by the BSD 3-Clause License and the Developer Certificate of Origin.

---

Note to contributors: We reserve the right to close PRs without review if they appear to lack human validation or do not meet the quality standards described in our contributing guide.