Complete Workflow: From Data to Decision

Deniz Akdemir

2026-11-09

Overview

This vignette demonstrates the complete causaldef workflow, from data specification through to policy decision-making. We show how deficiency theory translates abstract statistical concepts into actionable clinical insights.

The workflow consists of four stages:

  1. Specify → Define the causal problem
  2. Estimate → Compute deficiency for different adjustment strategies
  3. Diagnose → Validate assumptions using negative controls and sensitivity analysis
  4. Decide → Compute policy regret bounds and make informed decisions

Part 1: Gene Perturbation Study (Continuous Outcome)

We begin with the gene_perturbation dataset, which simulates a CRISPR knockout experiment. This illustrates the core workflow for continuous outcomes.

1.1 Data Description

Variables:

Causal Structure:

      [Batch, Library Size]
             |
             v
   [Knockout] -----> [Target Expression]
             \
              \---X--> [Housekeeping Gene]  (no causal effect)

The housekeeping gene is affected by the same technical variations but NOT by the knockout, making it an ideal negative control.

1.2 Step 1: Specification

1.3 Step 2: Deficiency Estimation

We compare three adjustment strategies:

  1. Unadjusted: Ignores technical confounders
  2. IPTW: Reweights samples to balance batch and library size
  3. AIPW: Augmented IPTW (doubly robust)

Interpretation:

In this run, the unadjusted PS-TV proxy is about 0.142, while IPTW and AIPW reduce it to about 0.037. That is a substantial reduction in the observational-to-interventional gap, but it should still be interpreted through the downstream regret bounds rather than as literal proof of randomized equivalence.

1.4 Step 3: Diagnose with Negative Control

The negative control diagnostic tests whether our adjustment removes ALL confounding, not just the measured confounders.

Decision Logic:

Result Interpretation Action
falsified = FALSE The screen does not find strong evidence against the current adjustment, but this is not proof that all confounding is gone Proceed with explicit uncertainty qualification
falsified = TRUE Residual confounding is detected by the screen Add covariates, reconsider the design, or report the limitation

1.5 Step 4: Policy Decision

Suppose we’re deciding whether to pursue this gene target for drug development. The utility is measured on a scale where: - 0 = no promise (no effect on expression) - 10 = maximum promise (strong effect)

Regret Bounds:

policy_regret_bound() reports:

Decision Rule: - If transfer_penalty is small relative to the practical stakes of the decision → the observational evidence may be usable with caveats - If transfer_penalty is large relative to those stakes → seek more evidence or narrow the decision scope

1.6 Effect Estimation

Finally, we estimate the causal effect using the best-performing method:

Complete Report:

Gene Perturbation Analysis Report

Treatment Effect (IPTW-adjusted): -1.71 log2 expression units Deficiency (δ): 0.037 Negative Control Screen: Not falsified (p = 0.149; delta_NC = 0.082) Transfer Penalty: 1.470 on [0, 10] scale Minimax Safety Floor: 0.092 on [0, 10] scale

Conclusion: Adjustment improved balance, but the remaining proxy gap is still material on the chosen utility scale.

Part 2: Hematopoietic Cell Transplantation (Survival Outcome)

Next, we analyze the hct_outcomes dataset, which mimics a retrospective registry study comparing conditioning regimens in HCT.

2.1 Data Description

Clinical Context:

The key challenge is confounding by indication: doctors assign treatment based on patient status, making naive comparisons biased.

2.2 Step 1: Survival Specification

The deficiency, sensitivity, and regret-bound calculations in this section run on all supported runtimes. The final RMST effect-estimation chunk requires a compatible survival runtime, which in the current support matrix means R >= 4.0.

For a full competing-risks analysis of relapse versus death, prefer causal_spec_competing() together with estimate_deficiency_competing(). Here we keep the workflow aligned with the current reproducible death-endpoint survival interface.

2.3 Step 2: Deficiency Estimation

Clinical Interpretation:

The deficiency tells us how much our observational evidence differs from what an RCT would provide. In this run, the unadjusted proxy is about 0.303, while IPTW reduces it to about 0.064. That is a meaningful improvement, but the remaining gap is still large enough to matter on a 24-month clinical utility scale.

2.4 Step 3: Confounding Frontier

Beyond point estimates, we can map a sensitivity analysis showing how deficiency varies with hypothetical unmeasured confounding:

Reading the Frontier Map:

If an unmeasured confounder would need extreme strength (beyond observed benchmarks) to substantially increase δ, conclusions are robust.

2.5 Step 4: Policy Regret and RMST Effect

Clinical Regret Bounds:

In the current example, the IPTW proxy implies a transfer penalty of about 6.18 months and a minimax safety floor of about 0.39 months on the 0–24 month utility scale. That means the residual observational-to-interventional gap is materially improved relative to the unadjusted analysis, but still not negligible for treatment decisions.

Effect-estimation chunks are skipped on runtimes without the required survival support. The deficiency, frontier, and regret-bound calculations above still provide the main observational-versus-interventional diagnostics for this example.

2.6 Complete Decision Framework

delta_iptw <- deficiency_hct$estimates["iptw"]
transfer_penalty <- bounds_hct$transfer_penalty
minimax_floor <- bounds_hct$minimax_floor
rmst_diff <- effect_hct$estimate

# Decision logic
if (transfer_penalty < 1) {
    evidence_quality <- "LOW residual decision risk"
} else if (transfer_penalty < 2) {
    evidence_quality <- "MODERATE residual decision risk"
} else {
    evidence_quality <- "HIGH residual decision risk"
}

# Benefit-to-risk ratio
if (!is.na(rmst_diff) && !is.na(transfer_penalty) && transfer_penalty > 0) {
    benefit_to_risk <- abs(rmst_diff) / transfer_penalty
    recommendation <- ifelse(benefit_to_risk > 2,
        "The estimated effect exceeds the transfer penalty, but the recommendation should still be qualified by residual confounding risk.",
        "The estimated effect is not clearly separated from the transfer penalty; avoid strong recommendations from observational evidence alone."
    )
} else {
    benefit_to_risk <- NA
    recommendation <- "Unable to calculate benefit-to-risk ratio"
}

cat(sprintf(
    "
## HCT Treatment Decision Report

**RMST Difference (IPTW):** %.2f months (%s favored)
**Deficiency:** %.3f
**Residual Decision Risk:** %s
**Transfer Penalty:** %.2f months
**Minimax Safety Floor:** %.2f months

**Benefit-to-Risk Ratio:** %.1f:1
**Recommendation:** %s

### Clinical Translation

The observational evidence suggests %s conditioning provides approximately
%.1f months difference in restricted mean survival within the first 24 months.

However, the transfer penalty is %.1f months and the minimax safety floor is %.1f months
on the 0--24 month utility scale. This is a decision-relevant amount of residual uncertainty, so clinicians should weigh it against individual patient factors and avoid over-interpreting the observational comparison.
",
    abs(rmst_diff),
    ifelse(rmst_diff > 0, "Myeloablative", "Reduced"),
    delta_iptw,
    evidence_quality,
    transfer_penalty,
    minimax_floor,
    benefit_to_risk,
    recommendation,
    ifelse(rmst_diff > 0, "myeloablative", "reduced-intensity"),
    abs(rmst_diff),
    transfer_penalty,
    minimax_floor
))

Part 3: Comparative Analysis Across Studies

3.1 When Is Observational Evidence Sufficient?

Study IPTW proxy Additional diagnostic Transfer penalty Interpretation
Gene Perturbation 0.037 NC not falsified; 0.082 observable residual-association proxy 1.47 on [0, 10] Residual uncertainty appears modest but nonzero
HCT Death-Endpoint RMST 0.064 Confounding frontier recommended; no negative control in this example 6.18 months Residual uncertainty remains material on the 24-month scale

3.2 General Workflow Summary

┌─────────────────────────────────────────────────────────────────┐
│  SPECIFY: causal_spec() / causal_spec_survival()                │
│           ↓ Define treatment, outcome, covariates, NC           │
├─────────────────────────────────────────────────────────────────┤
│  ESTIMATE: estimate_deficiency()                                │
│            ↓ Compare unadjusted, IPTW, AIPW, TMLE, etc.        │
│            ↓ Select method with lowest δ                        │
├─────────────────────────────────────────────────────────────────┤
│  DIAGNOSE: nc_diagnostic() + confounding_frontier()             │
│            ↓ Test whether assumptions are falsified             │
│            ↓ Map sensitivity to unmeasured confounding          │
├─────────────────────────────────────────────────────────────────┤
│  DECIDE: policy_regret_bound() + estimate_effect()              │
│          ↓ Compute transfer penalty / minimax floor             │
│          ↓ Report effect with uncertainty qualification         │
└─────────────────────────────────────────────────────────────────┘

References

  1. Akdemir, D. (2026). Constraints on Causal Inference as Experiment Comparison: A Framework for Identification, Transportability, and Policy Learning. DOI: 10.5281/zenodo.18367346

  2. Le Cam, L., & Yang, G. L. (2000). Asymptotics in Statistics: Some Basic Concepts. Springer.

  3. VanderWeele, T. J., & Ding, P. (2017). Sensitivity Analysis in Observational Research: Introducing the E-value. Annals of Internal Medicine.