---
title: "Sampling Diagnostics and Conservative Decisions"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Sampling Diagnostics and Conservative Decisions}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## 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:

```text
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.

```{r diagnostic-plots, eval=FALSE}
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.