Planning-time statistical power from a design's REAL model matrix — no data needed.
Builds the design and takes `ncp = effect_size² / (X'X)⁻¹_jj`, so it is correct for centre
points, axial points and unbalanced designs — unlike `covadoe_power_analysis`, which assumes
orthogonality and overstates power on a CCD, Box-Behnken or DSD. Use this when planning an
experiment; use `covadoe_post_hoc_power` only once you have measured responses.
`design_type` + `n_factors` builds the design (same generator as `covadoe_create_design`, so the
answer describes the design you would actually get). Common aliases resolve ("full_factorial",
"ccd", "dsd"). Alternatively pass `design`, an explicit coded run matrix, to score a design you
already hold — D/I-optimal, mixture, split-plot or hand-built. `n_runs` / `model_terms` are
forwarded to the generator for the optimal designs.
`model`: "linear" | "interaction" | "quadratic" | "quadratic_no_interaction" (a DSD supports only
the last). `term` names the coefficient — "x1", "x1^2", "x1*x2"; omit it to get power for every
term and group, which differ sharply on the same design. `alpha` is the significance level;
the CCD axial distance is `axial_alpha`, and the two are easy to confuse.
CCD variant: `axial_alpha` defaults to ROTATABLE, (2**n_factors)**0.25 — the design JMP,
Design-Expert and Minitab hand you. Pass a number, or "orthogonal" for the α where Σx² = n_runs
(at 3 factors: main-effect power 0.9400 against the rotatable 0.8846 on the same 17 runs; the
orthogonal α is also the premise of `covadoe_power_analysis`, so on that design the two agree
for a main effect and disagree for every other term). `face` — "circumscribed" (default),
"faced" (star points on the faces, α = 1) or "inscribed"; a bool works, and an unknown value is
rejected rather than quietly treated as circumscribed.
Returns power, power_by_term, power_by_group, df_error, relative_variance ((X'X)⁻¹_jj), the
resolved design_summary (the α and factorial level actually built — read both, an inscribed CCD
always reports α = 1), and `orthogonal_shortcut_power` — what `covadoe_power_analysis` would
have claimed — with its signed error (signed: the shortcut does not always overstate). Returns
`estimable: false` plus a reason when the model cannot be fitted on the design.
