feat: add pick command for reduce

[henryiii]

This implements a pick command for algorithm::reduce, closes #275. Adds a new constructor:

Axis(const Axis& src, axis::pick_tag,
     const axis::index_type* begin, const axis::index_type* end)

To be pickable, an axis must have this constructor, using axis::pick_tag to opt in. Pointers are used in the signature to avoid forcing a specific collection like std::vector (and C++17's std::span is not available); this is similar to (It begin, It end) iterator-pair constructors of axis::variable and axis::category. Concrete pointers are used instead of a template so that axis::traits::is_pickable can detect the constructor with std::is_constructible. Categorical axes gain this new constructor.

Picking uses pick({2, 0}) (a std::vector). The items here do need to be a specific collection, similar to the std::initializer_list constructors of axis::variable and axis::category, because the type-erased reduce_command must store the indices in a concrete container.

🤖 AI text below 🤖

This adds a pick command to algorithm::reduce, which selects an arbitrary subset of bins by index from an axis which is not ordered, like the category axis. Unlike slice, the bins do not have to be adjacent, and the new axis keeps them in the order given.

auto h = make_histogram(axis::category<std::string>({"red", "green", "blue"}));
// ...
auto h2 = algorithm::reduce(h, pick({2, 0})); // axis is now {"blue", "red"}

Summary:

• Counts in bins that were not picked go to the overflow bin, if present; otherwise they are dropped.
• Axes opt in with a special constructor A(const A&, axis::pick_tag, const std::vector<index_type>&), detected by the new axis::traits::is_pickable trait. The pick_tag disambiguates the constructor from the generic (iterable, metadata) axis constructors, which could otherwise match by accident and break compilation of reduce for unrelated axes. Only category opts in.
• pick cannot be combined with another reduce command on the same axis; indices must be unique and in range.

[henryiii]

Testing this downstream, report below. Works great. The #423 change is known (we are accessing internals in fill, trivial update to match upstream). The 8x slower comment is known too, it's due to np.take's vectorized gather. It is something we could fix here, but it's not reduce specific; we could address this in a followup for all reductions (would need per-axis lut + bulk copies). I'm not sure how difficult that is, can investigate afterwards. The overflow bins now work, too, so the old boost-histogram "experimental" warning can go away :).

🤖 AI text below 🤖

Verdict: yes, the feature works for us. The whole home-grown pick_set block in Histogram.__getitem__ (axis reconstruction + np.take copies, ~30 lines) collapsed into building _core.algorithm.pick(i, selection) commands that go through the same reduce() call as slices. All 1131 tests, mypy, and prek pass.

What I set up (all uncommitted, for the trial):

• extern/histogram is on a local branch pick-on-1.90: the PR's 7 commits cherry-picked cleanly onto our pinned 1.90.0 commit. The PR branch itself is based on develop, which breaks our fill.hpp via an unrelated change (80fcf10, fix: avoid dangling-reference in sample tuple conversion for C++23 compatibility #423 sample-tuple conversion) — that's next-bump compat work, not a pick problem.
• Bound pick in src/register_algorithm.cpp (both overloads, mirroring slice, plus __repr__ support) and added stubs.
• Replaced the Python implementation in histogram.py:1479, updated tests and docs/user-guide/indexing.rst.

Feedback on the feature itself:

1. The pick_tag opt-in design composes perfectly with our bindings. Our category axes are plain bh::axis::category instantiations, so they became pickable with zero changes on our side. Binding pick was mechanical.
2. Semantics are an upgrade. Unpicked bins now land in overflow, so sum(flow=True) is preserved — exactly the gap that forced our "experimental" warning ("Removed bins are not placed in overflow"). I removed the warning and updated the docs. crop mode is available too, though the indexing API doesn't expose it yet. One old behavior is inexpressible with the new API (keep original overflow but drop unpicked bins — neither shrink nor crop), but nothing needs it.
3. Minor behavior changes: duplicate indices (h[[0, 0]]) and empty lists now raise ValueError (previously silently allowed/weird). Metadata survives (__dict__ metadata test passes). I kept a Python pre-check so picking on ordered axes still raises RuntimeError rather than ValueError, preserving our API.
4. The one real concern is performance at scale. Parity on the existing small benchmarks (~62 µs both ways), but on a 1000×500×50 histogram picking half the bins on two axes, reduce takes 320 ms vs 38 ms for the old vectorized np.take path — ~8× slower, because reduce walks every input bin individually through the per-bin command dispatch. Not blocking for typical categorical axes (tens of bins), but worth noting on the PR — a pick-only fast path or bulk copy per picked bin could close the gap.

So the PR can come out of draft as far as boost-histogram verification goes; the perf note is the one thing I'd consider addressing upstream first.

[henryiii]

@HDembinski This is ready for review, by the way. There were several decisions along the way (axis::pick_tag, pointers, vector); I think I matched the initial issue and current design (see the non-AI text in the description), but happy to change things if you prefer anything different.

[HDembinski]

Using a tag type is clean, but I don't like it because it becomes part of the public API and we managed so far without adding these things. This should be an implementation detail and not part of the public API.

A pickable axis is detected via the special constructor, and it looks like the constructor is already distinct from any other constructors, so I think we can do this without a public tag type. Please give it a try.

Otherwise looks good and it's a nice feature.

[henryiii]

It wasn't originally unambiguous with std::vector, but the current form actually is, I believe, due to the two pointers. (The arbitrary metadata entry was the issue before). I'll push a version that doesn't have a pick tag if it works in a minute.

[HDembinski]

@henryiii There are some conflicts here, can you give it another iteration? I also added a comment. I think this feature is in a good shape, but I want to see whether we can avoid the tag type.