---
title: "Understanding validation status"
author: "Raban Heller"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Understanding validation status}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
resource_files:
  - figures/logo.svg
  - figures/logo-dark.svg
---

<!-- cttir-vignette-logo: start -->
<style>
.cttir-vignette-logo { float: right; width: 120px; max-width: 30%; margin: 0 0 1rem 1.5rem; }
.cttir-vignette-logo img { width: 100%; height: auto; border: 0; background: transparent; box-shadow: none; }
.cttir-vignette-logo .cttir-vignette-logo-light { display: block; }
.cttir-vignette-logo .cttir-vignette-logo-dark { display: none; }
@media (prefers-color-scheme: dark) {
  .cttir-vignette-logo .cttir-vignette-logo-light { display: none; }
  .cttir-vignette-logo .cttir-vignette-logo-dark { display: block; }
}
[data-bs-theme="light"] .cttir-vignette-logo .cttir-vignette-logo-light { display: block; }
[data-bs-theme="light"] .cttir-vignette-logo .cttir-vignette-logo-dark { display: none; }
[data-bs-theme="dark"] .cttir-vignette-logo .cttir-vignette-logo-light { display: none; }
[data-bs-theme="dark"] .cttir-vignette-logo .cttir-vignette-logo-dark { display: block; }
</style>
<div class="cttir-vignette-logo">
  <img class="cttir-vignette-logo-light" src="figures/logo.svg" alt="inferguidR logo" width="120" height="139" />
  <img class="cttir-vignette-logo-dark" src="figures/logo-dark.svg" alt="inferguidR logo" width="120" height="139" />
</div>
<!-- cttir-vignette-logo: end -->

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

An implemented engine can have unresolved branches. A successful calculation
does not establish agreement with every external reference or suitability for
a particular study. Always retain the specification, result and package revision.

## Inspect the method before using a result

```{r method-status}
validation_status("t_means_two_independent")
```

`independently_checked` records the existence of independent numerical checks.
It does not mean every option combination is certified. `reference_pending`
means complete G*Power comparison is not certified; captured cases may already
exist. The Boschloo extension is outside the G*Power inventory and therefore
has G*Power reference status `not_applicable`.

```{r extension}
validation_status("boschloo_proportions_two_independent")
```

Standalone Boschloo power and sample-size functions have independent checks.
The explicit `advisor_power_spec()` bridge preserves the selected central,
minlike or prespecified directional variant for completed, mapped advisor
recommendations. Supply event probabilities, direction and allocation
explicitly. Unmapped or incomplete recommendations remain unavailable for
automatic planning; the mapping does not certify every numerical branch.

## Inspect the actual outcome

```{r outcome}
spec <- analysis_spec(
  "t_means_two_independent", "a_priori",
  inputs = list(alpha = 0.05, power = 0.8, d = 0.5),
  options = list(tails = "two")
)
result <- solve_design(spec)
result$status
result$warnings
result$validation
```

Use a design estimate only after checking its typed status, warnings and
assumptions. In particular, exact unconditional compromise and tetrachoric
approximation confidence intervals still have pending branches. Classifier
bootstrap validation remains at development status.

## Reproduce the public checks

The source repository includes an installed-package checker with synthetic
inputs and separate reference calculations. It emits per-case comparisons and
a run summary, and exits unsuccessfully on a mismatch. Its scope and tolerances
are documented in the [public validation instructions](https://github.com/CTTIR/inferguidR/blob/main/tools/validation/README.md).

Separate bounded numerical campaigns exercise exact table enumeration, inverse
targets, rank and regression models, multivariate approximations and utility
calculations. Their method/mode/option inventory distinguishes an independently
checked sample from an uncovered branch or an intentional refusal. A finite
sample for every registered method is not certification of all its inputs.
The [numerical contracts](https://github.com/CTTIR/inferguidR/blob/main/tools/validation/NUMERICAL-CONTRACTS.md)
state the oracle, tolerance, supported scope and remaining boundary for each
work package. The installed release preflight separately checks API/help
availability, startup effects and report round-trips under full and minimal
dependency profiles.

The package regression suite and this independent checker answer different
questions. Neither replaces full reference-corpus comparison. Some provenance
checks skip because development inventories, captured fixtures and ledgers are
not shipped. The [validation guide](https://github.com/CTTIR/inferguidR/blob/main/VALIDATION.md)
lists those skips and the [roadmap](https://github.com/CTTIR/inferguidR/blob/main/ROADMAP.md)
defines the remaining qualification gates.