Diagnostics for a fitted causal model

Description

Computes diagnostics appropriate to the causal estimator:

• All estimators: positivity checks (flags covariate strata where the probability of treatment is near 0 or 1).

• “ipw” with binary treatment: covariate balance via cobalt on the propensity formula, plus an observed-treatment weight distribution summary (1/p on treated rows, 1/(1-p) on controls) with mean, SD, min, max, and effective sample size.

• “matching”: covariate balance before and after matching (via cobalt), match quality summary (% matched, caliper info).

• “gcomp”: unadjusted covariate imbalance between treatment groups.

Point-treatment fits only. diagnose() aborts on a longitudinal (ICE) fit. For longitudinal data, inspect per-period propensity / balance tables manually.

Binary treatment only for IPW weight summaries. Continuous and categorical IPW fits abort with causatr_diag_unsupported_family: the density-ratio weight under those families depends on the intervention, and diagnose() is an intervention-free diagnostic.

Usage

diagnose(
  fit,
  stats = c("m", "v"),
  thresholds = c(m = 0.1),
  ps_bounds = c(0.025, 0.975)
)

Arguments

fit	A causatr_fit object returned by causat().
stats	Character vector. Balance statistics to compute. Passed to cobalt::bal.tab(). For binary treatments, valid options include “m” (standardised mean differences), “v” (variance ratios), and “ks” (Kolmogorov-Smirnov). Default c(“m”, “v”).
thresholds	Named numeric vector. Balance thresholds for flagging imbalance, e.g. c(m = 0.1, v = 2). Default c(m = 0.1).
ps_bounds	Numeric vector of length 2. Lower and upper bounds for flagging positivity violations. Default c(0.025, 0.975).

Details

Positivity

For binary treatment, fits a logistic regression of the treatment on the confounders and flags individuals whose estimated propensity score falls outside ps_bounds. The returned positivity table summarises the propensity score distribution and the number/fraction of near-violations.

Balance (IPW and matching)

If the cobalt package is installed, balance is computed via cobalt::bal.tab() on the internal weightit or matchit object. This provides standardised mean differences (SMD), variance ratios, and KS statistics before and after adjustment. If cobalt is not installed, a simpler data.table-based SMD comparison is returned.

Weight distribution (IPW only)

Summarises the IPW weights: mean, SD, min, max, and the effective sample size (ESS) for the treated and control groups.

Match quality (matching only)

Reports the number matched, number discarded, and the fraction of the original sample retained.

Value

A causatr_diag object with slots:

balance

cobalt::bal.tab object (if cobalt installed) or a data.table of SMDs. Covariate balance summary.

positivity

data.table: propensity score summary and count of near-violations.

weights

data.table or NULL: weight distribution summary (IPW only).

match_quality

data.table or NULL: match quality summary (matching only).

estimator

Character: the causal estimator.

fit

The original causatr_fit (stored for plot()).

References

Greifer N (2024). cobalt: Covariate Balance Tables and Plots. https://ngreifer.github.io/cobalt/

See Also

causat(), plot.causatr_diag()

Examples

library("causatr")

data("nhefs", package = "causatr")
fit <- causat(nhefs, outcome = "wt82_71", treatment = "qsmk",
              confounders = ~ sex + age + wt71,
              estimator = "ipw")
diag <- diagnose(fit)
print(diag)
plot(diag)