# Sampling Diagnostics and Conservative Decisions

## Evidence layers

`gp3bayes` separates four questions that are often incorrectly collapsed:

1. Did the backend complete sampling?
2. Did prespecified numerical sampling diagnostics pass?
3. Did selected posterior predictive summaries reproduce relevant features?
4. 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.