Fix silently-ignored grouping, lost metadata on grouped variables, and four smaller defects

[rafa-guedes]

Motivation

Writing a client-facing description of a delivered gridstats product meant reading every stat against its source. Seven defects surfaced, all of the same shape: the library produces a plausible-looking answer instead of an error. Each is fixed here, with a regression test that fails without the fix.

Three commits, grouped by concern. Each passes the suite on its own.

---

1. group silently ignored — caf862a

CallConfig.group is forwarded to every stat, and pcount, rpv, hmo and distribution3_timestep absorbed it into **kwargs and ignored it. Meanwhile _apply still appended _{group} to the output name. A config asking for group: month on pcount got a variable called hs_pcount_month holding the ungrouped whole-record value, with no month dimension. Wrong data, convincing name, no error — the same defect fixed for range_probability in #1, in four more places.

Group support is now detected by inspecting the function signature rather than a hand-maintained flag: a stat supports grouping if it declares an explicit group parameter rather than absorbing it variadically. That cannot drift out of sync with the code. Pipeline._apply raises before any data is read if grouping is requested from a stat that cannot honour it, naming the stat and listing those that can.

pcount gains real grouping, since it is the one of the four where the meaning is unambiguous — the denominator is the group's own timestep count, not the whole record. rpv, hmo and distribution3_timestep are left unsupported deliberately (a per-calendar-month extreme-value fit on a twelfth of the samples is not something to offer by accident); all three also documented a group argument they ignored, in docstrings and in docs/, now corrected.

harmonics and statdir were also swept in as unsupported by the signature rule. statdir gains support in commit 3; harmonics is genuinely not groupable.

Also fixes rpv's nanosecond assumption — float(np.diff(...)) / 3.6e12 raises TypeError under NumPy 2 for any other datetime64 resolution and would silently mis-scale if it did not. Same fix already applied to exceedance.

2. Metadata and naming — 66836a5

Grouped variables lost every attribute. set_variable_attributes treats the last _ token as the statistic, so hs_mean_month resolved as stat month, the lookup failed, and the variable shipped with {} — no units, no names. The existing code meant to handle this was unreachable, tested a substring rather than the trailing token, and would have emitted "seasonly". Now a recognised trailing group token is stripped before resolution, with an explicit adjective mapping (monthly / seasonal / annual), composing correctly with _direc and with the stat_units override.

count shipped as metres. hs_count inherited its parent's units; count and dist are now declared dimensionless in stat_units.

range_probability default labels could contain a dot — hs_1.5_to_max. The p-substitution applied to exceedance now lives in a shared ops/_naming.py used by both, so the two cannot drift.

3. statdir and output.chunks — 761af67

statdir raised MergeError with more than one func, because each delegated stat returned its result under the base variable name. Outputs are now suffixed with the producing function, giving hs_mean_direc / hs_max_direc — byte-identical to what equivalent nsector calls produce, so the same product has one name by either route and still resolves in attributes.yml.

A second, worse interaction turned up while pinning that: nsector is a CallConfig field, so on a statdir call it was consumed by the pipeline's directional wrapper and never reached the stat, which then re-binned each outer sector with its own default of 4 — the documented eight-sector example died with conflicting dimension sizes. Sector settings are now forwarded to self-sectorising stats rather than wrapped around them. statdir also gains group, validated across all delegated funcs.

statdir is now functionally redundant with nsector, its only remaining justification being one pass over the data for several statistics. Kept, with the redundancy documented rather than left implicit.

output.chunks was silently dropped. pipeline.py read it via __dict__.get, but OutputConfig never declared the field, so pydantic discarded it — finalise() has a working chunks parameter that never received anything. The field is now declared, and OutputConfig rejects unknown keys, since silently swallowing output options is what let this hide.

---

Breaking changes

• Requesting group on a stat that cannot honour it now raises instead of being ignored.
• range_probability default labels render a fractional bound as 1p5 rather than 1.5. Configs setting label: explicitly are unaffected.
• OutputConfig rejects unknown keys.

I checked the blast radius of the last one: 98 embedded gridstats configs across config/hindcast/prax/stats/ validate cleanly, including all seven in the current Cawthron delivery. The only failures are legacy onstats configs that fail at the YAML-tag level on !!python/object/apply:onstats.stats.Stats — a different package.

Grouped variables written before this branch carry no metadata and need rewriting, or at least re-consolidating, to pick it up. Grouped pcount output produced earlier is wrong and should be regenerated.

Testing

308 passing, up from 231; zero failures. Every fix has a test that fails without it — including a pcount denominator test constructed so the whole-record denominator gives a different, wrong answer, and a statdir pipeline test asserting equality with the equivalent nsector calls.

Docs updated alongside: docs/ops/rpv.md, docs/ops/distribution.md, docs/ops/aggregations.md, docs/ops/directional.md, docs/ops/probability.md, docs/configuration/output.md.