---
title: "Verified calibration methods in WFC 2.0"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Verified calibration methods in WFC 2.0}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

All public calibration methods in WFC 2.0 require the `wf_design_data` and
`wf_verified_target` objects created in the verified workflow. The examples
below assume `design`, `target`, and `dims` have already passed import and
review as shown in `vignette("safe-weighting-workflow")`.

## Fixed-tolerance soft calibration

Soft calibration is for a tolerance declared before outcomes are inspected. It
does not search for a target, widen tolerance automatically, or optimize a
study result. The declared tolerance and any relaxed external margin appear in
the result and statistical report.

```{r soft, eval=FALSE}
soft <- wf_calibrate(
  design,
  target,
  method = "soft",
  tolerance = 0.02
)

wf_report(soft, audience = "statistician")$sections$soft_relaxation
```

If the declared tolerance cannot resolve infeasibility, WFC stops. Select a
different external target only through a new, independently reviewed workflow.

## Categorical entropy balancing

Entropy balancing may use only the categorical margins contained in the
verified target.

```{r ebal, eval=FALSE}
ebal <- wf_calibrate(
  design,
  target,
  method = "ebal",
  tol = 1e-10
)

wf_report(ebal, audience = "statistician")
```

WFC 2.0 has no inline desired-mean interface. Continuous outcome goals,
pass-rate goals, and desired intervals are not weighting inputs.

## Bounded logit calibration

Bounds are reviewable settings, not values that WFC expands automatically:

```{r logit, eval=FALSE}
bounded <- wf_calibrate(
  design,
  target,
  method = "logit",
  bounds = c(0.3, 3)
)
```

For a consequential analysis, record why the method and settings are suitable
and include them in the human plan review.