Support for multiarm ancova, Draft v2

[luwidmer]

First draft to further iterate onaccording to to the discussion in #520 so far @gowerc @tobiasmuetze @bailliem @wwojciech @danielinteractive: this branch builds on the original multi-arm ANCOVA prototype (#520 ) with a more flexible contrast API.

Let me know what you think, this definitely will need further review and iteration.

Flexible custom contrasts

• group_contrasts now accepts, in addition to pairwise c(minuend, subtrahend) character vectors, general linear contrasts as named numeric weight vectors over the group levels (e.g. c(Placebo = -1, A = 0.5, B = 0.5) for pooled active-vs-control, or dose-response trends). Weights must sum to zero; evaluation is coding-agnostic and preserves the trt estimand (evaluated at the covariate reference).
• Default two-arm and multi-arm output is unchanged (trt, lsm_ref, lsm_alt, trt_alt2, ...).

Correctness & robustness

• Contrast coding-agnostic evaluation: ancova_linear_contrast() now maps group-level weights onto the model coefficients via the factor's own contrast matrix instead of parsing rbmiGroupL* coefficient names. Results are correct under any options("contrasts") (e.g. contr.sum), not just contr.treatment, and reduce exactly to the previous coefficient contrast for the pairwise/default case. Rank-deficient designs (missing/aliased/NA group coefficients) now error instead of silently dropping a term.
• as_data_frame_internal() errors if pooled parameters have no matching metadata rather than emitting silent NA columns.

Named contrasts & output metadata

• Explicit contrasts must be named: the list name becomes the output parameter and a new contrast_label metadata column (surfaced by pool() / as.data.frame()). The auto-derived trt_alt2_alt-style names are used only for the default (group_contrasts = NULL) set, preserving backward compatibility. Naming a contrast trt reproduces the classic name.
• Names starting with lsm_ are rejected (reserved for least-squares means) to prevent output collisions.
• pool() / as.data.frame() output gains contrast_label alongside the existing estimate_type, group, group_level_1, group_level_2, visit columns; the legacy parameter column is retained.

Documentation

• Fixed stale ancova() @return (now documents the extended default scheme and named custom contrasts); added an @details note clarifying that trt is the model-coefficient contrast and differs from lsm_alt − lsm_ref under group×covariate interactions.
• Added runnable multi-arm/custom-contrast examples to ancova() and worked pairwise + weight-vector blocks to the FAQ and quickstart vignettes.
• NEWS updated.

Tests

• Coefficient-contrast reproduction, pooled/weight-vector correctness, contr.sum invariance, named-label propagation through pool(), reserved-name and validation errors, an end-to-end ancova() → pool() → as.data.frame() metadata integration test.

Housekeeping

• Project formatted with air.

Compatibility

• Two-arm and default multi-arm results and names are unchanged. group_contrasts and the metadata columns are new (unreleased), so tightening explicit contrasts to require names introduces no break for released behaviour.
• The covariate reference point for trt is fixed at 0 to preserve the historic estimand (documented in @details).