standard-calibration.qmd

---
title: "Standard Calibration"
---

# When standard calibration is the right tool

Use standard calibration when you want a single calibration map from one prediction per observation and:

- you already have a dedicated calibration split,
- you are calibrating predictions on a held-out sample,
- or you do not have fold-specific prediction matrices available.

# Minimal workflow

```python
from causal_calibration import fit_calibrator

calibrator = fit_calibrator(
    predictions=tau_hat,
    treatment=a,
    outcome=y,
    mu0=mu0_hat,
    mu1=mu1_hat,
    propensity=e_hat,
    loss="dr",
    method="isotonic",
)

tau_calibrated = calibrator.predict(tau_hat_new)
```

```r
calibrator <- fit_calibrator(
  predictions = tau_hat,
  treatment = a,
  outcome = y,
  mu0 = mu0_hat,
  mu1 = mu1_hat,
  propensity = e_hat,
  loss = "dr",
  method = "isotonic"
)

tau_calibrated <- predict(calibrator, tau_hat_new)
```

# What it does

The calibrator learns a mapping from raw treatment-effect scores to calibrated scores.

# What standard calibration does not do

Standard calibration does not reconstruct fold-specific prediction behavior. If your upstream HTE learner was trained with cross-fitting and you want to preserve that structure in-sample, cross-calibration is the better fit.

# Recommended interpretation workflow

1. Inspect the raw prediction range.
2. Fit a calibrator.
3. Compare raw and calibrated predictions on the same observations.
4. Run `diagnose_calibration()` to quantify how much miscalibration remains and inspect the BLP slope CI.
5. Run `assess_overlap()` or inspect the attached overlap summary if overlap might be weak.
6. Revisit the loss choice if the package's default overlap screen suggests that `loss="dr"` may be unstable.

# See also

- [Cross-Calibration](cross-calibration.html)
- [Losses and Methods](choosing-losses-and-methods.html)
- [API Reference](reference.html)