API Reference

Core fitting functions

fit_calibrator()

Use when you have one prediction per unit.

Required by loss

  • loss="dr": mu0, mu1, propensity
  • loss="r": outcome_mean, propensity

Common mistakes

  • supplying raw learner objects instead of prediction vectors,
  • forgetting outcome_mean for loss="r",
  • using non-binary treatment indicators.

fit_cross_calibrator()

Use for cross-fitted treatment-effect predictions.

Contract

  • predictions: pooled out-of-fold predictions used to fit the calibration map
  • fold_predictions: n x K matrix used for calibrated aggregation at prediction time
  • fold_ids: optional out-of-fold column index per observation; when supplied, the package validates that pooled OOF predictions really match the designated fold-specific column.

Common mistakes

  • swapping predictions and fold_predictions,
  • passing a single-column matrix when the intended workflow is cross-calibration,
  • forgetting that prediction later also expects a fold-specific matrix.

Validation helpers

  • validate_crossfit_bundle(...): validate pooled OOF predictions, fold matrices, and optional fold IDs before fitting.
  • crossfit_bundle(...) / crossfit_bundle_from_data_frame(...): package the cross-fit workflow objects in one place.

diagnose_calibration()

Use for a calibration curve, a scalar error estimate, a linear BLP-style score diagnostic, and uncertainty quantification.

Inputs

  • prediction vector,
  • treatment and outcome,
  • nuisance estimates,
  • optional comparison vector,
  • optional target_population = "dr" | "overlap" | "both".

Interpretation

The meaning of the result depends on the target population implied by your loss and nuisance structure. See Losses and Methods.

assess_overlap()

Use for the package’s default overlap screen before choosing loss="dr" versus loss="r".

Outputs

  • propensity min/max,
  • tail fractions below 0.05, 0.10, above 0.90, 0.95 used by the default screen,
  • clipped fraction,
  • IPW effective sample size,
  • overlap-weight effective sample size,
  • severity label and recommended loss under the package defaults.

Treat those cutoffs as workflow heuristics built into the package, not as universal overlap thresholds.

Bundle helpers

  • calibration_bundle(...) / calibration_bundle_from_data_frame(...)
  • crossfit_bundle(...) / crossfit_bundle_from_data_frame(...)
  • fit_bundle_calibrator(...)
  • fit_bundle_cross_calibrator(...)

Object behavior

Calibrator

  • predict(...): apply the fitted calibration map
  • summary(): lightweight metadata summary
  • plotting: visualize the fitted calibration map

CrossCalibrator

  • predict(...): apply the map to a fold-specific matrix and aggregate with the order-statistic median
  • summary(): metadata summary including fold count

CalibrationDiagnostics

  • summary(): scalar results, BLP slope/intercept summaries, and intervals
  • plotting helpers: calibration-curve outputs for visualization

Reference examples