example7: demonstrate a dispersion sub-model, and re-run the precision sweep under disp("loglinear")

[beckyfisher]

What

Two things #193 scoped for example7 that did not land in PR #243, split out so
that PR can close its issue.

1. A dispersion sub-model as a vignette section. Rewrite example7 as a growth-data case study using the alga dataset #193 called this "the
   payoff": example7 fits growth-rate data where the variance is not constant
   in the mean, and disp() is the package feature that addresses it, but the
   vignette does not demonstrate it.

2. Re-run the precision sweep under disp("loglinear"). The sweep in the
   vignette was run with a pooled sigma.

Why it matters

The bounded check recorded in notes/disp_sensitivity_example7.md shows that
arm B2's headline numbers are largely a pooled-sigma artefact. That is one
scenario at n = 50, so it is not enough to re-score the study, but it is enough
to say that the vignette's claims about B2 are conditioned on a variance
assumption the vignette does not state and does not test. Either the sweep is
re-run under a dispersion sub-model, or the claim is qualified.

Evidence

notes/disp_sensitivity_example7.md, on the branch of PR #243. One scenario,
n = 50, bounded response.

Implementation detail

Ordering: this is downstream of PR #243 merging, and downstream of the ECx
redefinition in #281, which changes every ECx example7 reports and therefore
requires a re-render regardless. Do not start it before both have landed.

The re-run is the expensive half: example7 alone takes about 137 minutes
locally and about 2 h 56 m in CI, for 24 alga fits, and the sweep multiplies
that. Read PR #243's handoff note before starting a precompile -- it records two
traps that cost a previous session time, the stale installed library and the
figure paths.

The third item PR #243 flagged, that example7 is about 14,700 words and the
longest vignette in the package, is a judgement for RF and is not part of this
issue. Adding a dispersion section makes it longer.

[beckyfisher]

Outcome of the re-run

The precision sweep has been re-run with a dispersion sub-model, on the same
cells and realisations as the study: five arms on the four precision cells, 100
realisations each, 2,000 units, all estimable. floored, gamma and beta
under disp("loglinear"), and the two bounded families under disp("power") as
well, since a power law in the fitted mean is the shape the Gamma's failure
calls for and choosing between the two forms in advance would have assumed the
answer.

A sub-model does not repair the conventions that impose the zero boundary
through the response distribution, and it damages the conventions whose variance
model is already correct. On that basis example7 does not report it. The code
and the tables stay in
open-AIMS/negative-response-conventions,
whose CLAUDE.md records why they are uncited, so nothing has to be re-run to
revisit this.

Evidence

The simulation generates a residual standard deviation that is constant along
the curve, so a correctly specified variance model predicts the generated value
at every concentration and a ratio of one between the control and the highest
concentration. measured is correctly specified by construction and returns a
control ratio of 0.98 to 1.00 with 95% of realisations in [0.81, 1.18], and a
gradient of 1.0. That is the reference; a departure inside it is the estimator
rather than a misspecification.

convention	control ratio	control-to-floor gradient
measured (reference)	0.98 to 1.00	1.0
floored	0.91 to 1.12	1.0 to 1.1
floored + loglinear	1.08 to 1.50	1.7 to 2.2
gamma	2.45 to 2.69	90 to 181
gamma + loglinear	1.01 to 1.59	18 to 32
gamma + power	1.11 to 1.82	1.8 to 5.1
beta	1.08 to 1.10	1.7 to 2.7
beta + loglinear	1.20 to 1.71	5.5 to 7.7
beta + power	1.47 to 2.89	44 to 64

Three readings follow. Neither form corrects the Gamma on both counts:
loglinear returns the control level and leaves a gradient of 18 to 32,
power returns the gradient and leaves a worse control level. The Beta needs no
correction — its control ratio is already inside the reference — and both forms
make it worse. And a sub-model added to a Gaussian, whose variance model is
already correct, gives it a gradient of 1.7 to 2.2 where the data have none;
floored under disp("loglinear") reports the same ErC50 bias as without it,
-2.1% against -2.3%, while its ErC10 changes from -0.2% to -6.9%.

One result is not negative and is not explained. beta under
disp("loglinear") reports an ErC50 bias of -1.9% to +0.7% across the sweep
with coverage 0.97 to 1.00, against -4.4% to -5.8% with coverage falling to 0.52
without it. That is the largest estimate repair anywhere in the sweep, and it
happens while that arm's variance model deteriorates, so it is not a variance
effect and the mechanism is unidentified.

Proposed scope

Narrow this issue to the first ask, a dispersion sub-model as an example7
section, and treat the sweep as answered. The section is still worth having —
disp() is the package feature for a response whose variance is not constant in
the mean, and no vignette demonstrates it — but it should be built on data with
a residual gradient to find, not on this sweep, where there is none and the
sub-model therefore has nothing to recover.

Where the work is, and what it does not cover

In open-AIMS/negative-response-conventions: R/disp_arms.R defines the arms,
analysis/run_disp_sweep.R runs one unit, analysis/build_priors_disp.R builds
the twenty fixed priors in priors_disp/, and hpc/run.dispsweep is the array.
Results are results/metrics_disp.csv and results/diagnostics_disp.csv. The
spread figures above come from results/ppc_spread.csv, which is a separate
measurement over 100 realisations of nine arms and is cited in the vignette,
in Section 5.3, for the Gamma diagnostic alone.

archive/disp-probe/ holds five earlier fits that took bnec()'s own default
priors rather than the fixed ones and cover one cell. They are not comparable
with the sweep and are kept only as the record of what prompted it. An earlier
reading taken from them had the two dispersion forms the wrong way round on the
gradient, which is why the table above is from the 100-realisation run.

Limits of what this establishes. Four precision cells only — the cells that vary
the depth of the decline or stop the series at the zero crossing were not
re-run, on the grounds that the precision axis is where the bounded families
fail. One generating equation, nec4param, which is in every Gaussian
convention's candidate set. And the data are generated homoscedastic, so this
measures what a sub-model does when there is no gradient to find; it does not
establish what it does when there is one, which is the case the first ask is
about.

Run against bayesnec at the commit in the compendium's hpc/bayesnec.lock.
The nsec() change in #326 post-dates it, so the NSEC columns of
metrics_disp.csv will change when the study is re-run; the control ratios and
gradients above are properties of the fits and will not.

[beckyfisher]

Decision

Closed without a dispersion section in example7. The premise this issue rests
on belongs to the superseded study design, and the demonstration it asks for is
better placed in another vignette.

The premise

The evidence here is notes/disp_sensitivity_example7.md, which found arm B2's
headline numbers to be largely a pooled-sigma artefact. Arm B2 does not exist
after the #296 redesign. Every convention now calls bnec() with its own
default priors and averages over its family's declining candidate set, so there
is no fixed-equation arm whose numbers a pooled sigma could be an artefact of.

The question that replaced it separates two failures this issue treats as one.
Flooring distorts the mean structure and leaves the variance alone; an
identity-link Gamma ties the dispersion to the mean and distorts the variance.
The dispersion sweep reported above measured that on 2,000 units: a sub-model
does not repair a convention that imposes the zero boundary through the response
distribution, and applied to a convention whose variance model is already
correct it inflates the predicted spread at the control and introduces a
gradient where the generated data have none. example7 reports the separation
as a posterior predictive check in Section 5.3 rather than as a correction.

The placement of the demonstration

A demonstration of disp() as a package feature is still worth having, and
example7 is the wrong vignette for it. These data are generated with a
residual standard deviation that is constant along the curve, so the only thing
a dispersion sub-model can be shown doing here is fitting a variance term the
data do not need. #228 has found a better example, and the demonstration is
better placed as a check in example9, whose PR #238 is merged.

The code and the tables for the dispersion sweep stay in
open-AIMS/negative-response-conventions,
whose CLAUDE.md records why they are uncited, so nothing has to be re-run to
revisit this.