Getting started with causalfrag

Overview

causalfrag provides an AI-assisted interpretation and reporting layer over established sensitivity analysis tools for unmeasured confounding in observational studies.

Important: Statistical results are always computed by transparent R functions. The LLM assists only in translating those outputs into plain language. The package works fully offline without an API key.

Basic workflow

library(causalfrag)

# 1. Fit your model
fit <- lm(mpg ~ am + wt + hp, data = mtcars)

# 2. Run the full sensitivity pipeline
result <- sens_report(
  model     = fit,
  treatment = "am",
  data      = mtcars
)

# 3. Print the structured results + fragility flag
print(result)

# 4. Access the plain-language narrative
cat(result$narrative)

Step by step

You can also run each step individually:

library(causalfrag)

fit <- lm(mpg ~ am + wt + hp, data = mtcars)

# Step 1: detect the design
design <- detect_design(fit)

# Step 2: run sensitivity analysis
res <- run_sensitivity(fit, treatment = "am", data = mtcars, design = design)

# Step 3: flag fragility
res <- flag_fragility(res)

# Step 4: interpret (uses LLM if configured, template otherwise)
res <- interpret_sensitivity(res)

# Step 5: visualize (uses confoundvis if installed)
plot(res)

# Step 6: generate a report paragraph
cat(generate_report(res))

Configuring an LLM provider

By default the package uses template-based narratives. To enable AI-assisted interpretation, configure a provider once per session:

# Anthropic (key from ANTHROPIC_API_KEY environment variable)
use_llm_provider("anthropic")

# OpenAI
use_llm_provider("openai")

# Disable explicitly
use_llm_provider("none")

Relationship to confoundvis

confoundvis (Hait, 2026) provides visualization tools for sensitivity analysis. causalfrag provides an AI-assisted interpretation and reporting layer that can optionally use confoundvis graphics as part of a broader causal sensitivity workflow.

# Visualize with confoundvis (if installed)
visualize_sensitivity(res, engine = "confoundvis")

References

Frank, K. A. (2000). Impact of a confounding variable on the inference of a regression coefficient. Sociological Methods & Research, 29(2), 147–194.

Cinelli, C., & Hazlett, C. (2020). Making sense of sensitivity: Extending omitted variable bias. Journal of the Royal Statistical Society: Series B, 82(1), 39–67.

VanderWeele, T. J., & Ding, P. (2017). Sensitivity analysis in observational research: Introducing the E-value. Annals of Internal Medicine, 167(4), 268–274.

Hait, S. (2026). confoundvis: Visualization tools for sensitivity analysis of unmeasured confounding. R package version 0.1.0.