Make the DTW band pluggable: Sakoe-Chiba and Itakura constraints (#197)

[kgdunn]

Summary

Closes the two band items of #197: "allow a user-specified band" and "add Sakoe-Chiba constraints". Implemented as option 3 of the three we discussed: one pluggable mechanism, with Sakoe-Chiba and Itakura as its first two constraints, so a future geometry is a function rather than a branch.

No existing behaviour changes. The default is band=None, which builds the same unconstrained band the code hard-coded before. The cost matrix is verified bit-identical to the pre-#197 kernel, and no slower.

What a constraint is

None (unconstrained), a literal (n_test, 2) array of half-open reference-row bounds, or a callable of the two batch lengths. The lengths are not known until a pair is aligned, so the callable is the useful form:

from process_improve.batch.alignment_helpers import sakoe_chiba, itakura

batch_dtw(..., settings={"band": sakoe_chiba(window=0.1)})   # 10% of batch duration
batch_dtw(..., settings={"band": itakura(max_slope=2.0)})

The callable is resolved outside the numba kernel, since nopython code cannot call back into Python; only the finished array crosses the boundary. That is why distance_matrix is now a thin wrapper over the jitted _banded_distance_matrix.

full_band, resolve_band and validate_band are public too, for a third geometry.

What a band actually buys, and costs

The band has to constrain the cost evaluation, not just the accumulation. My first version constrained only the accumulation, which left the whole function quadratic in the batch lengths however narrow the band: a 10% band was then 1.3x faster at 1000 samples and slower at 2000. Measured on random series, with the cost restricted too:

samples	no band	10% band	speedup
100	1.95 ms	0.38 ms	5.7x
300	24.5 ms	3.3 ms	7.6x
700	6.55 s	25.0 ms	323x

It also changes results. On the bundled dryer fixture (71 batches, 89 to 201 samples), a 50% window reproduces the unconstrained weights to nine figures; narrowing degrades the alignment monotonically:

window	worst normalized distance
none	0.0714
50%	0.0714 (identical weights)
20%	0.0804
10%	0.178
5%	0.235

So the guidance in the docstring is to widen the window until the alignment stops changing.

Three defects the band exposed

None could fire while the band was always full, so they are latent rather than regressions, but any band work walks straight into them:

1. backtrack_optimal_path would have crashed with a bare AssertionError. It selected a predecessor with <= chains ending in else: raise AssertionError. NaN fails every comparison, and every out-of-band cell is NaN, so the first step to a constrained cell fell through to that bare raise. It now picks the cheapest finite predecessor and raises a ValueError naming the cause. On unconstrained input the choice, ties included, is unchanged: diagonal wins a tie, then horizontal (pinned by a test).
2. The first row and column were filled ignoring the band, which would have let a path run along an edge outside the corridor and re-enter it later. They are now filled only as far as the band admits.
3. one_iteration_dtw discarded the reason a batch failed. It re-raised every per-batch ValueError as Failed on batch {id} with from None. That was already unhelpful, and with a band the dropped part is the actionable one: a corridor too narrow for one batch says which window or slope to use. The cause is now interpolated and chained.

Geometry details worth reviewing

Sakoe-Chiba centres on the line joining the two corners rather than on m == n, so it is correct for unequal durations, and floors the radius at ceil((n_ref - 1) / (n_test - 1)). Below that the corridor has gaps no monotone path can cross, so the alignment would be infeasible rather than merely constrained. window is an int (rows) or a float (fraction of the reference length); bool is rejected, since True as a one-row radius is almost certainly a mistake.

Itakura rounds its edges outwards. Rounding inwards empties any column whose corridor is thinner than one row, which happens as soon as the two lengths differ much. Batches of very different duration admit no Itakura parallelogram at any slope (its corner columns are one cell wide, so a path needing many reference rows per test sample has nowhere to start); that case is refused by name and points at Sakoe-Chiba.

The refusal quotes a minimum slope found by bisection on the real construction, rounded up to four significant figures and confirmed accepted. My first attempt derived it in closed form and formatted it with :.4g, which rounded below the threshold: the error told the reader to pass a value the code then rejected. A sweep over 36 length pairs caught it, and a parametrised test now pins it.

Two things I found and deliberately did not change

• np.diag(A @ W @ A.T) forms an h-by-h product to keep its h diagonal entries, so the cost matrix is cubic in batch length. That is why 700 samples takes seconds at all. The row-wise equivalent np.sum((A @ W) * A, axis=1) measured 150x to 1500x faster, but it accumulates in a different order and differs in the last bits (~1e-15), so it would move pinned values across the repo. Worth its own PR; say the word.
• A slice of the full extent is not free under numba. Replacing ref with ref[0:nr] cost the unconstrained path 4x at 700 samples (1.63 s to 6.65 s on the cost loop) because the slice cannot be proven contiguous. The two cases are separate loops for that reason, not for clarity.

Test plan

• uv run pytest full suite: 3297 passed, 41 skipped (3261 before, plus 36 new; the skips are proxy-blocked openmv.net downloads, pre-existing).
• ruff check ., ruff format --check ., mypy src/process_improve all clean.
• Default cost matrix bit-identical to the pre-Batch alignment improvements #197 kernel at 100, 300 and 700 samples, and no slower.
• Dryer alignment weights unchanged to twelve figures with band=None.
• Sweep over 36 length pairs (2 to 97 samples, both orders) times 5 windows and 4 slopes: every band validates, every path runs corner to corner, and no banded distance is ever cheaper than the unconstrained one.

New coverage: 36 tests over six classes. TestFullBand (the default cannot drift), TestSakoeChibaBand (diagonal centring, corners, the radius floor, int vs float windows, bool rejected, wide window recovers the unconstrained distance, narrow one costs more), TestItakuraBand (corner columns one cell wide, widest in the middle, no empty column at unequal lengths, the lopsided refusal, and that the advised slope is itself accepted), TestBandValidation (one test per rejection message), TestBacktrackingUnreachableCells (both NaN paths raise a named error; ties still take the diagonal) and TestBatchDtwBandSetting (end to end, including that an impossible band explains itself).

Checklist

• Version bumped in pyproject.toml (MINOR: 1.88.0 to 1.89.0, new public API and a new setting; CITATION.cff in step in the same commit)
• Tests added
• ruff check . passes
• CHANGELOG.md updated

Still open in #197

Three items remain, and this PR does not touch them: the percentage-scale x-axis with configurable resolution, the batch-key str coercion bug, and tightening the alignment test now that DTW termination is settled.

🤖 Generated with Claude Code

https://claude.ai/code/session_0123j56Hk6jRz9zy91Doc1og

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!