Sampling Diagnostics and Conservative Decisions

Evidence layers

gp3bayes separates four questions that are often incorrectly collapsed:

Did the backend complete sampling?
Did prespecified numerical sampling diagnostics pass?
Did selected posterior predictive summaries reproduce relevant features?
Is the model scientifically and substantively defensible?

A positive answer to an earlier question does not guarantee a positive answer to a later one.

Numerical diagnostic contract

For approved binary and duration fits, diagnose_binary_fit() and diagnose_duration_fit() report:

rank-normalized split R-hat;
bulk effective sample size per chain;
tail effective sample size per chain;
divergent transitions after warmup;
saturation at the configured maximum treedepth;
chain-level energy Bayesian fraction of missing information (E-BFMI).

The default thresholds are deliberately inspectable:

Component	Pass	Review	Fail
R-hat	at most 1.01	above 1.01 through 1.05	above 1.05
Bulk ESS per chain	at least 100	50 through below 100	below 50
Tail ESS per chain	at least 100	50 through below 100	below 50
Divergences	zero	not used	one or more
Treedepth saturation	zero	above zero through 1%	above 1%
E-BFMI	at least 0.30	0.20 through below 0.30	below 0.20

These are package reporting thresholds, not mathematical proofs. The overall status is fail when any component fails, review when any component requires review or cannot be assessed, and pass only when all components pass.

No automatic convergence statement

A diagnostic object always records:

Diagnostics assessed: TRUE
Automatic convergence claim: FALSE
Posterior adequacy established: FALSE

This design prevents a single threshold or a successful sampler return code from being converted into an unsupported claim.

Diagnostic plots

The optional bayesplot dependency supports trace, energy, treedepth, and divergence views.

plot_sampling_diagnostics(
  binary_fit,
  type = "trace"
)

plot_sampling_diagnostics(
  binary_fit,
  type = "energy"
)

plot_sampling_diagnostics(
  binary_fit,
  type = "treedepth"
)

plot_sampling_diagnostics(
  binary_fit,
  type = "divergence"
)

Plots complement numerical summaries. They do not replace them.

Responding to failures

A failure should lead to model-specific investigation rather than automatic suppression. Possible actions include:

checking data coding and the readiness audit;
examining weak identification or separation;
reconsidering grouping structures;
inspecting prior implications;
increasing iterations only when Monte Carlo error is the actual problem;
considering a defensible reparameterization;
documenting unresolved failures.

Increasing adapt_delta, iterations, or treedepth without understanding the problem is not treated as model validation.

Reporting language

Appropriate:

Sampling completed. All declared numerical diagnostic thresholds passed. Posterior adequacy and substantive validity were assessed separately.

Inappropriate:

The model converged and is valid because R-hat was below 1.05.

The structured reports generated by create_binary_model_report() and create_duration_model_report() use the conservative form.