fix(groupby): align groupers by label, raise on mismatch (#827)

[FBumann]

Closes #827.

@FabianHofmann We decided to NOT reindex. As all groupers should behave similarly, they now all raise if the grouper is misaligned.
But Dataframes were reindex before. We could also change this to reindex all groupers instead of raising if its a pure reorder. Users relying on the reindex will get an error now...

Warning

Potentially breaking. Groupers that were previously accepted (silently regrouping by position, or — for DataFrame groupers — silently reindexing) now raise ValueError. Code that relied on a reordered grouper "just working" must reorder the grouper to match the expression's coordinates.

Note

The following content was generated by AI.

What & why

On the default (fast) path, groupby(...).sum() matched a pd.Series/DataArray grouper to the expression by position, ignoring labels — a reordered grouper silently regrouped and produced a wrong result (#827). The three grouper paths also disagreed: DataFrame reindexed by label, the fallback raised.

This makes all grouper types follow one rule, per the issue decision ("Don't reindex, just check size and index fits — else raise"): match by label, never reindex, raise on mismatch.

• New _check_grouper_alignment(group, data) validates each shared dimension's labels against the expression's coordinates and raises a clear ValueError, distinguishing "same labels in a different order" from "a different set of labels". Runs on both the fast path and use_fallback=True (replacing the fallback's misleading "length does not match" message).
• Unified across pd.Series, pd.DataFrame and 1-D/N-D DataArray. A grouper without an index along a dim has nothing to align by and keeps the positional match.
• _encode_multikey_group no longer reindexes (alignment is now guaranteed upstream).

Breaking change

DataFrame groupers previously reindexed a reordered index silently; they now raise like the others. test_linear_expression_groupby_with_dataframe_non_aligned was updated to assert the raise.

Tests

New TestGroupbyGrouperAlignment: reordered Series/DataFrame/DataArray raise, N-D reorder raises, mismatched label-set raises, aligned + unindexed groupers still work (parametrized over use_fallback). Full test_linear_expression.py and all -k group tests pass; ruff and mypy clean.

[codspeed-hq]

Merging this PR will not alter performance

✅ 173 untouched benchmarks
⏩ 173 skipped benchmarks¹

---

_{Comparing fix-827-groupby-grouper-alignment (904ba0a) with master (c02f5db)}

Footnotes

1. 173 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[FabianHofmann]

@FBumann one thought that came to my mind. since here we don't have the ability to set the join convention - in contrast to x.mul(y, join="...") I wonder if our choice of "exact" join is the correct choice here. I will take a look at this again tomorrow morning.