Type:	Package
Title:	Visualization Tools for Sensitivity Analysis of Unmeasured Confounding
Version:	0.1.0
Description:	Provides visualization tools for sensitivity analysis to unmeasured confounding in observational studies. Includes contour-based sensitivity plots, robustness curves, and benchmark-oriented graphics that help researchers assess how strong omitted confounding would need to be to attenuate, invalidate, or reverse estimated effects. Supports regression-based sensitivity analysis frameworks, including impact threshold approaches (Frank, 2000, <doi:10.1177/0049124100029002001>), partial R-squared methods (Cinelli and Hazlett, 2020, <doi:10.1111/rssb.12348>), and E-value style metrics (VanderWeele and Ding, 2017, <doi:10.7326/M16-2607>). Emphasizes clear, interpretable, and publication-ready graphical summaries for transparent reporting of causal sensitivity analyses across the social, behavioral, health, and educational sciences.
License:	GPL-3
Encoding:	UTF-8
Language:	en-US
RoxygenNote:	7.3.3
Depends:	R (≥ 4.1.0)
Imports:	ggplot2 (≥ 3.4.0), rlang, graphics, stats
Suggests:	testthat (≥ 3.0.0), knitr, rmarkdown, gridExtra
Config/testthat/edition:	3
VignetteBuilder:	knitr
URL:	https://github.com/causalfragility-lab/confoundvis
BugReports:	https://github.com/causalfragility-lab/confoundvis/issues
NeedsCompilation:	no
Packaged:	2026-03-25 13:24:31 UTC; Subir
Author:	Subir Hait [aut, cre]
Maintainer:	Subir Hait <haitsubi@msu.edu>
Repository:	CRAN
Date/Publication:	2026-03-30 09:30:26 UTC

confoundvis: Geometric Visualization Tools for Causal Sensitivity Analysis

Description

Provides visualization tools for sensitivity analysis under unmeasured confounding, including sensitivity contour plots, robustness curves, sensitivity Love plots, and local Taylor diagnostic plots.

Author(s)

Maintainer: Subir Hait haitsubi@msu.edu (ORCID)

See Also

Useful links:

• https://github.com/causalfragility-lab/confoundvis

• Report bugs at https://github.com/causalfragility-lab/confoundvis/issues

Coerce a confoundsens object to a data frame

Description

Coerce a confoundsens object to a data frame

Usage

## S3 method for class 'confoundsens'
as.data.frame(x, ...)

Arguments

Value

A data.frame with columns lambda and theta, plus optional columns level, se, and t when present in x.

Examples

x <- new_confoundsens(
  lambda = seq(0, 0.2, length.out = 5),
  theta  = seq(1, 0.8, length.out = 5),
  se     = rep(0.05, 5)
)
as.data.frame(x)

Convert a data frame to a confoundsens object

Description

Converts a data frame containing sensitivity analysis results into a confoundsens object suitable for use with confoundvis plotting functions.

Usage

as_confoundsens(
  data,
  lambda = "lambda",
  theta = "theta",
  level = NULL,
  se = NULL,
  t = NULL
)

Arguments

Value

A confoundsens object.

Examples

df <- data.frame(
  lambda = seq(0, 0.2, length.out = 10),
  theta  = seq(1, 0.5, length.out = 10),
  se     = rep(0.1, 10),
  level  = rep(c("within", "between"), length.out = 10)
)
x <- as_confoundsens(df)
x

Fit a local quadratic approximation

Description

Fits a second-order Taylor (quadratic) approximation of an effect path \theta(\delta) near \delta = 0 using ordinary least squares:

\theta(\delta) \approx a + b\delta + c\delta^2.

Usage

fit_local_quadratic(
  data = NULL,
  delta = NULL,
  theta = NULL,
  local_max_delta = 0.2,
  include_intercept = TRUE,
  tol = 1e-12
)

Arguments

Details

You may supply either a data.frame containing columns delta and theta, or supply numeric vectors delta and theta directly.

Value

A named list with elements:

• coef — named coefficient vector from stats::lm().

• intercept, slope, quad — individual coefficients (NA when absent).

• model — the fitted lm object.

• local_data — the data.frame used for fitting.

• local_max_delta — the window half-width used.

Examples

df <- data.frame(
  delta = seq(0, 0.3, length.out = 60),
  theta = 0.4 - 0.7 * seq(0, 0.3, length.out = 60) +
          0.4 * seq(0, 0.3, length.out = 60)^2
)
fit_local_quadratic(df, local_max_delta = 0.2)

Create a confoundsens object

Description

Constructs a confoundsens object — a lightweight container for storing sensitivity paths (e.g., \theta(\lambda)) and optional uncertainty or stratification information used by confoundvis plotting functions.

Usage

new_confoundsens(lambda, theta, level = NULL, se = NULL, t = NULL)

Arguments

Value

A confoundsens object (a list with class "confoundsens").

Examples

x <- new_confoundsens(
  lambda = seq(0, 0.2, length.out = 10),
  theta  = seq(1, 0.6, length.out = 10),
  se     = rep(0.1, 10)
)
x

Compare reversal cones across multilevel components

Description

Produces a two-panel plot comparing the reversal cone cross-sections for the within-cluster and between-cluster confounding components in multilevel settings. Each panel calls plot_reversal_cone() and they are displayed side by side using faceting.

Usage

plot_cone_comparison(
  theta0_within = 0.35,
  theta0_between = 0.5,
  delta_within = 0.2,
  delta_between = 0.3,
  ...
)

Arguments

Value

Invisibly, a list with ggplot objects within and between. The plots are drawn side-by-side to the current device.

Examples

plot_cone_comparison(
  theta0_within  = 0.35, theta0_between = 0.50,
  delta_within   = 0.20, delta_between  = 0.30
)

Three-panel Taylor approximation figure

Description

Produces a three-panel figure (linear / concave-down / convex-up) showing a simulated confounding path together with its first-order (tangent) and second-order (local quadratic) approximations. The panels correspond to the three curvature regimes in the mITCV framework.

Usage

plot_figure2_taylor_panels(
  delta_max = 1.5,
  step = 0.02,
  theta0 = 0.4,
  slope = -0.7,
  kappa = 0.4,
  local_max_delta = 0.2
)

Arguments

Value

A named list with ggplot objects A (linear), B (concave), and C (convex), returned invisibly. The three panels are also printed to the active graphics device via gridExtra::grid.arrange() if gridExtra is installed, or via graphics::layout() otherwise.

Examples

plots <- plot_figure2_taylor_panels()
# Access individual panels
plots$A

Local Taylor diagnostic plot

Description

Plots local Taylor series components (or any multi-series decomposition) as a function of delta from a long-form data.frame. Lines are distinguished by colour and linetype, keyed by series.

Usage

plot_local_taylor(df, facet = FALSE)

Arguments

Value

A ggplot2::ggplot() object.

Examples

df <- data.frame(
  delta  = rep(seq(0, 0.2, length.out = 25), 3),
  series = rep(c("path", "tangent", "quadratic"), each = 25),
  value  = c(
    0.4 - 0.7 * seq(0, 0.2, length.out = 25) - 0.4 * seq(0, 0.2, length.out = 25)^2,
    0.4 - 0.7 * seq(0, 0.2, length.out = 25),
    0.4 - 0.7 * seq(0, 0.2, length.out = 25) + 0.2 * seq(0, 0.2, length.out = 25)^2
  )
)
plot_local_taylor(df)
plot_local_taylor(df, facet = TRUE)

Reversal cone geometry plot

Description

Visualizes the two-dimensional cross-section of the reversal cone C_l at a fixed confounding effect magnitude |\delta|. The cone partitions the (q, p) confounding parameter space into an attenuation zone (where the effect shrinks but does not reverse sign) and a reversal zone (where the sign changes). The boundary between zones is the reversal curve derived from the multilevel mITCV framework.

Usage

plot_reversal_cone(
  theta0 = 0.4,
  delta = 0.2,
  q_range = c(0, 1),
  p_range = c(-1, 1),
  grid_n = 200L,
  show_boundary = TRUE,
  show_volume = TRUE
)

Arguments

Value

A ggplot object.

Examples

plot_reversal_cone(theta0 = 0.40, delta = 0.20)
plot_reversal_cone(theta0 = 0.40, delta = 0.50)

Plot a robustness curve

Description

Plots the sensitivity path stored in a confoundsens object as a function of lambda. By default, plots the effect path theta(lambda); optionally plots the test-statistic path t(lambda). Pointwise 95% confidence bands are drawn when standard errors are available.

Usage

plot_robustness_curve(
  x,
  what = c("theta", "t"),
  bands = TRUE,
  points = TRUE,
  facet_level = TRUE
)

Arguments

Value

A ggplot2::ggplot() object.

Examples

x <- new_confoundsens(
  lambda = seq(0, 0.2, length.out = 25),
  theta  = 1 - 2 * seq(0, 0.2, length.out = 25),
  se     = rep(0.05, 25),
  level  = rep(c("within", "between"), length.out = 25)
)
plot_robustness_curve(x)
plot_robustness_curve(x, bands = FALSE, facet_level = FALSE)

Sensitivity contour plot

Description

Draws an ITCV-style hyperbolic boundary in (r_{YU}, r_{DU}) space and optionally overlays observed covariate benchmarks as labelled points. The robust region is the interior of the hyperbola where |r_{YU} \cdot r_{DU}| < threshold.

Usage

plot_sensitivity_contour(threshold, grid_n = 200, benchmarks = NULL)

Arguments

Value

A ggplot2::ggplot() object.

Examples

b <- data.frame(
  r_yu  = c(0.10, 0.15),
  r_du  = c(0.20, 0.12),
  label = c("SES", "BMI")
)
plot_sensitivity_contour(threshold = 0.02, benchmarks = b)

Sensitivity Love plot

Description

Benchmarks a sensitivity threshold against the empirical distribution of observed covariate impacts in a "Love plot"-style display. Each covariate appears as a point on a horizontal impact axis; the sensitivity threshold is shown as a vertical reference line. Covariates to the left of the line are weaker than the threshold; those to the right pose a credible threat.

Usage

plot_sensitivity_love(df, threshold, sort = TRUE, top = NULL)

Arguments

Value

A ggplot2::ggplot() object.

Examples

df <- data.frame(
  covariate = c("SES", "BMI", "Gender", "Race", "Age"),
  impact    = c(0.12, 0.05, 0.02, 0.08, 0.03)
)
plot_sensitivity_love(df, threshold = 0.10)
plot_sensitivity_love(df, threshold = 0.10, top = 3)

Print method for confoundsens objects

Description

Prints a concise summary of the key fields in a confoundsens object.

Usage

## S3 method for class 'confoundsens'
print(x, ...)

Arguments

Value

x, invisibly.

Examples

x <- new_confoundsens(
  lambda = seq(0, 0.2, length.out = 5),
  theta  = seq(1, 0.8, length.out = 5)
)
print(x)

Simulate demo confounding paths for Taylor panel figures

Description

Generates three synthetic sensitivity paths — linear, concave-down, and convex-up — sharing the same baseline effect \theta(0) and first-order slope, but differing in second-order curvature. These toy paths illustrate the difference between tangent-based (first-order) and local quadratic (second-order) sensitivity approximations.

Usage

simulate_taylor_demo(
  delta_max = 1.5,
  step = 0.02,
  theta0 = 0.4,
  slope = -0.7,
  kappa = 0.4
)

Arguments

Details

The three regimes are:

• Linear: \theta(\delta) = \theta_0 + s\delta

• Concave-down: \theta(\delta) = \theta_0 + s\delta - \kappa\delta^2

• Convex-up: \theta(\delta) = \theta_0 + s\delta + \kappa\delta^2

Value

A named list with elements linear, concave, and convex, each a new_confoundsens() object.

Examples

sims <- simulate_taylor_demo(
  delta_max = 1, step = 0.05, theta0 = 0.4, slope = -0.7, kappa = 0.4
)
sims$linear
plot_robustness_curve(sims$concave)

Summary method for confoundsens objects

Description

Produces a concise numerical summary of the sensitivity path, optionally broken down by level.

Usage

## S3 method for class 'confoundsens'
summary(object, ...)

Arguments

Value

An object of class summary.confoundsens containing a table data.frame with per-level summary statistics.

Examples

x <- new_confoundsens(
  lambda = seq(0, 0.2, length.out = 10),
  theta  = seq(1, 0.6, length.out = 10),
  se     = rep(0.08, 10),
  level  = rep(c("within", "between"), length.out = 10)
)
summary(x)

Validate a confoundsens object

Description

Internal validator used by constructors and methods. Checks that required fields are present and consistently sized, coerces optional fields, and issues a warning when lambda is not nondecreasing.

Usage

validate_confoundsens(x)

Arguments

Value

The validated (and possibly coerced) object, invisibly. Errors if the object is structurally invalid.