ps_calibrate: Calibrate propensity scores
In propensity: A Toolkit for Calculating and Working with Propensity Scores

ps_calibrate

R Documentation

Calibrate propensity scores

Description

ps_calibrate() adjusts estimated propensity scores so they better reflect true treatment probabilities. This can improve the accuracy of inverse probability weights derived from a misspecified propensity score model.

Usage

ps_calibrate(
  ps,
  .exposure,
  method = c("logistic", "isoreg"),
  smooth = TRUE,
  .focal_level = NULL,
  .reference_level = NULL,
  .treated = NULL,
  .untreated = NULL
)

Arguments

`ps`	A numeric vector of propensity scores between 0 and 1. Must not already be calibrated.
`.exposure`	A binary vector of observed treatment assignments, the same length as `ps`.
`method`	Calibration method. One of: `"logistic"` (Default) Logistic calibration, also called Platt scaling. Fits a logistic regression of `.exposure` on `ps`, yielding a smooth, parametric correction. Works well with small samples and when the bias in `ps` is approximately monotone. `"isoreg"` Isotonic regression. Fits a non-parametric, monotone step function. More flexible than logistic calibration because it makes no distributional assumption, but needs larger samples for stable estimates.
`smooth`	Logical. When `method = "logistic"`, controls the form of the calibration model. If `TRUE` (default), fits a GAM with a spline on `ps` via `mgcv::gam()`; if `FALSE`, fits a simple logistic regression via `stats::glm()`. Ignored when `method = "isoreg"`.
`.focal_level`	The value of `.exposure` representing the focal group (typically the treated group). If `NULL` (default), coding is determined automatically.
`.reference_level`	The value of `.exposure` representing the reference group (typically the control group). If `NULL` (default), coding is determined automatically.
`.treated`	Use `.focal_level` instead.
`.untreated`	Use `.reference_level` instead.

Details

Calibration is useful when the propensity score model is correctly specified in terms of variable selection but produces probabilities that are systematically too high or too low. Unlike ps_trim() and ps_trunc(), which handle extreme scores by removing or bounding them, calibration reshapes the entire distribution of scores.

Choosing a method:

Use "logistic" (the default) as a first choice. It is stable and fast, and the smooth = TRUE option adds flexibility via a spline.
Use "isoreg" when you suspect a non-smooth or irregular relationship between estimated and true probabilities and have a sufficiently large sample.

The calibrated scores are returned as a ps_calib object, which can be passed directly to weight functions such as wt_ate().

Value

A ps_calib vector the same length as ps. The attribute ps_calib_meta stores calibration metadata (method and whether smoothing was applied). Use is_ps_calibrated() to test whether an object has been calibrated.

References

Platt, J. (1999). Probabilistic outputs for support vector machines and comparisons to regularized likelihood methods. Advances in Large Margin Classifiers, 61–74.

Zadrozny, B., & Elkan, C. (2002). Transforming classifier scores into accurate multiclass probability estimates. Proceedings of the Eighth ACM SIGKDD International Conference on Knowledge Discovery and Data Mining, 694–699. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1145/775047.775151")}

Examples

# Simulate data
set.seed(42)
ps <- runif(200)
exposure <- rbinom(200, 1, ps)

# Logistic calibration without smoothing (simple Platt scaling)
cal <- ps_calibrate(ps, exposure, smooth = FALSE)
cal

# Use calibrated scores to calculate weights
wt_ate(cal, exposure)

# Isotonic regression calibration
cal_iso <- ps_calibrate(ps, exposure, method = "isoreg")

if (rlang::is_installed("mgcv")) {
  # Logistic calibration with spline smoothing (default)
  cal_smooth <- ps_calibrate(ps, exposure)
}

propensity documentation built on March 3, 2026, 1:06 a.m.