iv.sensemakr: Sensitivity Analysis Tools for Instrumental Variable Estimates

Description

Implements a suite of sensitivity analysis tools for instrumental variable estimates, as described in Cinelli and Hazlett (2025).

Details

The main functions of the package are iv_fit, which fits an IV regression model using the Anderson-Rubin approach, and sensemakr.iv_fit, which computes sensitivity analysis results for objects of class iv_fit.

Author(s)

Maintainer: Carlos Cinelli carloscinelli@hotmail.com [copyright holder]

Authors:

• Chad Hazlett [copyright holder]

References

Cinelli, C. and Hazlett, C. (2025), "An Omitted Variable Bias Framework for Sensitivity Analysis of Instrumental Variables." Biometrika. doi:10.1093/biomet/asaf004

See Also

Useful links:

• https://carloscinelli.com/iv.sensemakr/

• https://github.com/carloscinelli/iv.sensemakr

• Report bugs at https://github.com/carloscinelli/iv.sensemakr/issues

National Longitudinal Survey of Young Men (NLSYM)

Description

Data used in Card (1995). Consists of a sample of 3,010 individuals from the National Longitudinal Survey of Young Men (NLSYM).

The treatment is educ, the outcome is lwage and the instrument is nearc4.

Usage

data('card')

Format

A data.frame with 3010 observations and 34 variables:

• id: person identifier

• nearc2: =1 if near 2 yr college, 1966

• nearc4: =1 if near 4 yr college, 1966

• educ: years of schooling, 1976

• age: in years

• fatheduc: father's schooling

• motheduc: mother's schooling

• weight: NLS sampling weight, 1976

• momdad14: =1 if live with mom, dad at 14

• sinmom14: =1 if with single mom at 14

• step14: =1 if with step parent at 14

• reg661: =1 for region 1, 1966

• reg662: =1 for region 2, 1966

• reg663: =1 for region 3, 1966

• reg664: =1 for region 4, 1966

• reg665: =1 for region 5, 1966

• reg666: =1 for region 6, 1966

• reg667: =1 for region 7, 1966

• reg668: =1 for region 8, 1966

• reg669: =1 for region 9, 1966

• south66: =1 if in south in 1966

• black: =1 if black

• smsa: =1 in in SMSA, 1976

• south: =1 if in south, 1976

• smsa66: =1 if in SMSA, 1966

• wage: hourly wage in cents, 1976

• enroll: =1 if enrolled in school, 1976

• KWW: knowledge world of work score

• IQ: IQ score

• married: =1 if married, 1976

• libcrd14: =1 if lib. card in home at 14

• exper: age - educ - 6

• lwage: log(wage)

• expersq: exper^2

References

Card, D. "Using Geographic Variation in College Proximity to Estimate the Return to Schooling". In L.N. Christofides, E.K. Grant, and R. Swidinsky, editors, Aspects of Labor Market Behaviour: Essays in Honour of John Vanderkamp. Toronto: University of Toronto Press, 1995.

Examples

data('card')
head(card)

Extract estimates of an iv.sensemakr object

Description

This function extracts the estimate, lower limit, upper limit, t-value, and (extreme) robustness values of an iv.sensemakr object, created with the function sensemakr.

Usage

## S3 method for class 'iv.sensemakr'
coef(object, parm = "iv", ...)

Arguments

Value

A data.frame with the sensitivity statistics for the requested parameters.

Examples

data("card")
y <- card$lwage
d <- card$educ
z <- card$nearc4
x <- model.matrix( ~ exper + expersq + black + south + smsa + reg661 + reg662 +
                     reg663 + reg664 + reg665+ reg666 + reg667 + reg668 + smsa66,
                   data = card)
card.fit <- iv_fit(y, d, z, x)
card.sens <- sensemakr(card.fit, benchmark_covariates = "black")
coef(card.sens)
coef(card.sens, parm = "fs")

Extracts point estimates and confidence intervals of an iv_fit model.

Description

The function coef extracts point estimates of an iv_fit model.

The function confint extracts confidence intervals of an iv_fit model.

Usage

## S3 method for class 'iv_fit'
coef(object, parm = "iv", ...)

## S3 method for class 'iv_fit'
confint(object, parm = c("iv", "fs", "rf"), level, ...)

Arguments

Value

coef returns a numeric vector with the estimates of interest.

confint returns a numeric vector with the confidence interval of interest.

Examples

# prepare data
data("card")
y <- card$lwage
d <- card$educ
z <- card$nearc4
x <- model.matrix( ~ exper + expersq + black + south + smsa + reg661 + reg662 +
                     reg663 + reg664 + reg665+ reg666 + reg667 + reg668 + smsa66,
                   data = card)

# fit iv model
card.fit <- iv_fit(y, d, z, x)

# extract coefficients
coef(card.fit)
coef(card.fit, parm = "fs")
coef(card.fit, parm = "rf")

# extract confidence intervals
confint(card.fit)
confint(card.fit, parm = "fs")
confint(card.fit, parm = "rf")

Instrumental Variable Estimation using the Anderson-Rubin approach

Description

iv_fit computes instrumental variable estimates and confidence intervals using the Anderson-Rubin (AR) approach (Anderson and Rubin, 1949). This approach is numerically identical to Fieller's theorem (Fieller, 1954). See Cinelli and Hazlett (2025) for further discussion.

The AR point estimate is numerically identical to the point estimate of two-stage least squares (2SLS) and it is given by the ratio of the reduced-form to the first-stage regression coefficient. Confidence intervals, however, are constructed differently. 2SLS is equivalent to using the delta-method to obtain the variance of the ratio estimator, and then proceeding by assuming the ratio is asymptotically normal. This approximation can fail when instruments are "weak." The Anderson-Rubin approach instead uses a test inversion procedure to construct confidence intervals. This procedure has correct coverage regardless of instrument strength, at the (inevitable) cost of eventually obtaining unbounded confidence intervals.

Usage

iv_fit(y, d, z, x = NULL, h0 = 0, alpha = 0.05)

Arguments

Value

An object of class iv_fit, containing:

data

A data.frame with the data used for fitting the models.

models

A list with the lm models used for obtaining the IV estimates. This includes the first-stage (FS), reduced-form (RF), and Anderson-Rubin (AR) regressions.

estimates

A list with the summary information of IV estimates, as well as summary information of the auxiliary estimates of the FS, RF, and AR regression.

pars

A list with the parameters of the call, such as the null hypothesis h0 and the significance level alpha.

References

Anderson, T.W. and Rubin, H. (1949), Estimation of the parameters of a single equation in a complete system of stochastic equations, Annals of Mathematical Statistics, 20, 46-63.

Fieller, E. C. (1954). Some problems in interval estimation. Journal of the Royal Statistical Society: Series B (Methodological), 16(2), 175-185.

Cinelli, C. and Hazlett, C. (2025), "An Omitted Variable Bias Framework for Sensitivity Analysis of Instrumental Variables." Biometrika. doi:10.1093/biomet/asaf004

Examples

# prepare data
data("card")
y <- card$lwage
d <- card$educ
z <- card$nearc4
x <- model.matrix( ~ exper + expersq + black + south + smsa + reg661 + reg662 +
                     reg663 + reg664 + reg665+ reg666 + reg667 + reg668 + smsa66,
                   data = card)

# fit iv model
card.fit <- iv_fit(y, d, z, x)
card.fit
summary(card.fit)

Contour plots of omitted variable bias for IV

Description

Contour plots of omitted variable bias for sensitivity analysis of instrumental variable estimates.

The main inputs are an iv_fit model, and the covariates used for benchmarking the strength of omitted variables.

If parm = "iv" (default) contour plots of the IV estimate are shown. The horizontal axis of the plot shows hypothetical values of the partial R2 of latent variables with the instrument. The vertical axis shows hypothetical values of the partial R2 of latent variables with the (pot.) outcome. The contour levels represent the adjusted lower limit (or upper limit) of the Anderson-Rubin confidence interval of the IV estimate, or the t-value for testing a specific null hypothesis. The reference points are the bounds on the partial R2 of latent variables if they were k times "as strong" as the observed covariate used for benchmarking (see arguments kz and ky). The dotted red line show the chosen critical threshold (for instance, zero): latent variables with such strength (or stronger) are sufficient to invalidate the research conclusions.

if parm = "fs" or parm = "rf", then contour plots of the first-stage and reduced-form regression are shown. See, e.g, ovb_contour_plot.lm.

See Cinelli and Hazlett (2020, 2025) for details.

Usage

ovb_contour_plot(...)

## S3 method for class 'iv_fit'
ovb_contour_plot(
  model,
  benchmark_covariates = NULL,
  kz = 1,
  ky = kz,
  kd = kz,
  sensitivity.of = c("lwr", "upr", "t-value"),
  parm = "iv",
  r2zw.x = NULL,
  r2y0w.zx = r2zw.x,
  bound_label = "manual bound",
  xlab = NULL,
  ylab = NULL,
  ...
)

Arguments

Details

Other parameters include:

alpha

significance level.

threshold

critical threshold, default is 0.

lim

limits for the axes.

lim.x

limits for the x axis. Default is lim.

lim.y

limits for the y axis. Default is lim.

nlevels

number of levels in the contour plot.

col.contour

color of the contour lines.

col.thr.line

color of the threshold line.

label.text

should benchmark label texts be shown? Default is TRUE.

cex.label.text

character size of label text. Default is .7.

label.bump.x

bump on the x coordinate of label text.

label.bump.y

bump on the y coordinate of label text.

cex.lab

The magnification to be used for x and y labels relative to the current setting of cex.

cex.main

The magnification to be used for main titles relative to the current setting of cex.

cex.axis

The magnification to be used for axis annotation relative to the current setting of cex.

asp

the y/x aspect ratio. Default is 1.

If parm = "fs" or parm = "rf" the function is simply a wrapper to the sensemakr function ovb_contour_plot.lm on the first-stage or reduced-form lm models.

Value

The function is called for its side effect of producing a contour plot. It invisibly returns a list with the grid values used for the contour plot.

References

Cinelli, C. and Hazlett, C. (2020), "Making Sense of Sensitivity: Extending Omitted Variable Bias." Journal of the Royal Statistical Society, Series B (Statistical Methodology).

Cinelli, C. and Hazlett, C. (2025), "An Omitted Variable Bias Framework for Sensitivity Analysis of Instrumental Variables." Biometrika. doi:10.1093/biomet/asaf004

Examples

data("card")
y <- card$lwage
d <- card$educ
z <- card$nearc4
x <- model.matrix( ~ exper + expersq + black + south + smsa + reg661 + reg662 +
                     reg663 + reg664 + reg665+ reg666 + reg667 + reg668 + smsa66,
                   data = card)
card.fit <- iv_fit(y, d, z, x)

# contour plot of the lower CI limit
ovb_contour_plot(card.fit, sensitivity.of = "lwr",
                 benchmark_covariates = "black")

Minimal sensitivity reporting for IV estimates

Description

This function produces LaTeX or HTML code for a minimal sensitivity analysis table for instrumental variable estimates, as suggested in Cinelli and Hazlett (2025). For objects of class sensemakr (from the sensemakr package), it dispatches to sensemakr::ovb_minimal_reporting.

Usage

ovb_minimal_reporting(
  x,
  digits = 3,
  verbose = TRUE,
  format = c("latex", "html", "pure_html"),
  ...
)

Arguments

Value

The function returns the LaTeX or HTML code invisibly as a character string and also prints it with cat when verbose = TRUE.

References

Cinelli, C. and Hazlett, C. (2025), "An Omitted Variable Bias Framework for Sensitivity Analysis of Instrumental Variables." Biometrika. doi:10.1093/biomet/asaf004

Examples

# loads package
library(iv.sensemakr)

# loads dataset
data("card")

# prepares data
y <- card$lwage
d <- card$educ
z <- card$nearc4
x <- model.matrix( ~ exper + expersq + black + south + smsa + reg661 + reg662 +
                     reg663 + reg664 + reg665+ reg666 + reg667 + reg668 + smsa66,
                   data = card)

# fits IV model and runs sensitivity analysis
card.fit <- iv_fit(y, d, z, x)
card.sens <- sensemakr(card.fit, benchmark_covariates = c("black", "smsa"))

# latex code
ovb_minimal_reporting(card.sens)

# html code (pure html, no mathjax needed)
ovb_minimal_reporting(card.sens, format = "pure_html")

Sensitivity analysis plots for IV sensemakr

Description

This function provides the contour plots of the sensitivity analysis results obtained with the function sensemakr for IV. It is basically a dispatcher to the core plot function ovb_contour_plot.

Usage

## S3 method for class 'iv.sensemakr'
plot(x, sensitivity.of = c("ci", "lwr", "upr", "t-value"), parm = "iv", ...)

Arguments

Value

The function is called for its side effect of producing contour plots. It invisibly returns the output from ovb_contour_plot.

Examples

data("card")
y <- card$lwage
d <- card$educ
z <- card$nearc4
x <- model.matrix( ~ exper + expersq + black + south + smsa + reg661 + reg662 +
                     reg663 + reg664 + reg665+ reg666 + reg667 + reg668 + smsa66,
                   data = card)
card.fit <- iv_fit(y, d, z, x)
card.sens <- sensemakr(card.fit, benchmark_covariates = "black")
plot(card.sens, lim = 0.09)

Computes the (extreme) robustness value for IV

Description

Computes robustness values for iv_fit objects, adapting the robustness value definitions of sensemakr to instrumental variables as described in Cinelli and Hazlett (2025). For parm = "iv", returns robustness values for the IV estimate; for parm = "fs" or parm = "rf", dispatches to sensemakr methods on the corresponding lm models.

Usage

robustness_value(...)

extreme_robustness_value(...)

xrv(...)

rv(...)

## S3 method for class 'iv_fit'
extreme_robustness_value(
  model,
  parm = "iv",
  q = 1,
  alpha = 0.05,
  min = TRUE,
  ...
)

## S3 method for class 'iv_fit'
robustness_value(model, parm = "iv", q = 1, alpha = 0.05, min = TRUE, ...)

Arguments

Value

A numeric value with the (extreme) robustness value.

References

Cinelli, C. and Hazlett, C. (2025), "An Omitted Variable Bias Framework for Sensitivity Analysis of Instrumental Variables." Biometrika. doi:10.1093/biomet/asaf004

Examples

data("card")
y <- card$lwage
d <- card$educ
z <- card$nearc4
x <- model.matrix( ~ exper + expersq + black + south + smsa + reg661 + reg662 +
                     reg663 + reg664 + reg665+ reg666 + reg667 + reg668 + smsa66,
                   data = card)
card.fit <- iv_fit(y, d, z, x)

# robustness value of the IV estimate
rv(card.fit)

# extreme robustness value
xrv(card.fit)

# robustness values for first-stage and reduced-form
rv(card.fit, parm = "fs")
rv(card.fit, parm = "rf")

Sensitivity Analysis of Instrumental Variable Estimates

Description

This function performs sensitivity analysis of instrumental variable estimates, as discussed in Cinelli and Hazlett (2025). The main input is an object of class iv_fit. It returns an object of class iv.sensemakr with several pre-computed sensitivity statistics for reporting. After running sensemakr you may directly use the plot, print and summary methods in the returned object.

Usage

sensemakr(...)

## S3 method for class 'iv_fit'
sensemakr(
  model,
  benchmark_covariates = NULL,
  kz = 1,
  ky = kz,
  kd = kz,
  r2zw.x = NULL,
  r2y0w.zx = r2zw.x,
  bound_label = "Manual Bound",
  q = 1,
  alpha = 0.05,
  min = TRUE,
  ...
)

Arguments

Value

An object of class iv.sensemakr, containing:

pars

A list with the general parameters used when calling sensemakr.

unadjusted

A list with the original, unadjusted results.

sensitivity_stats

A list with the sensitivity statistics of the IV, First-Stage, and Reduced-Form regressions.

bounds

A list with bounds on the strength of latent variables if they were "k times" as strong as the benchmark covariates.

References

Cinelli, C. and Hazlett, C. (2025), "An Omitted Variable Bias Framework for Sensitivity Analysis of Instrumental Variables." Biometrika. doi:10.1093/biomet/asaf004

Examples

# loads package
library(iv.sensemakr)

# loads dataset
data("card")

# prepares data
y <- card$lwage  # outcome
d <- card$educ   # treatment
z <- card$nearc4 # instrument
x <- model.matrix( ~ exper + expersq + black + south + smsa + reg661 + reg662 +
                     reg663 + reg664 + reg665+ reg666 + reg667 + reg668 + smsa66,
                   data = card) # covariates
# fits IV model
card.fit <- iv_fit(y,d,z,x)

# see results
card.fit

# runs sensitivity analysis
card.sens <- sensemakr(card.fit, benchmark_covariates = c("black", "smsa"))

# see results
card.sens

# sensitivity contour plot
plot(card.sens, lim = 0.09)

Sensitivity statistics for instrumental variable estimates

Description

Convenience function that computes robustness values for IV estimates as well as auxiliary first stage and reduced form regressions.

Usage

sensitivity_stats(...)

## S3 method for class 'iv_fit'
sensitivity_stats(model, parm = "iv", q = 1, alpha = 0.05, min = TRUE, ...)

## S3 method for class 'iv.sensemakr'
sensitivity_stats(model, parm = "iv", q = 1, alpha = 0.05, min = TRUE, ...)

Arguments

Value

A data.frame with columns for the estimate, confidence interval bounds (lower and upper), t-value, extreme robustness value (xrv_qa), robustness value (rv_qa), and the parameters used (q, min, alpha, dof).

Examples

data("card")
y <- card$lwage
d <- card$educ
z <- card$nearc4
x <- model.matrix( ~ exper + expersq + black + south + smsa + reg661 + reg662 +
                     reg663 + reg664 + reg665+ reg666 + reg667 + reg668 + smsa66,
                   data = card)
card.fit <- iv_fit(y, d, z, x)

# sensitivity statistics for the IV estimate
sensitivity_stats(card.fit)

# sensitivity statistics for the first-stage
sensitivity_stats(card.fit, parm = "fs")

Sensitivity analysis print and summary methods for iv.sensemakr

Description

The print and summary methods provide verbal descriptions of the sensitivity analysis results obtained with the function sensemakr.

Usage

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

## S3 method for class 'summary.iv.sensemakr'
print(x, digits = 3, ...)

Arguments

Value

summary.iv.sensemakr returns an object of class summary.iv.sensemakr. The print methods return the object invisibly.

Examples

data("card")
y <- card$lwage
d <- card$educ
z <- card$nearc4
x <- model.matrix( ~ exper + expersq + black + south + smsa + reg661 + reg662 +
                     reg663 + reg664 + reg665+ reg666 + reg667 + reg668 + smsa66,
                   data = card)
card.fit <- iv_fit(y, d, z, x)
card.sens <- sensemakr(card.fit, benchmark_covariates = "black")
print(card.sens)
summary(card.sens)

print and summary methods for iv_fit

Description

The print and summary methods provide verbal descriptions of the results obtained with the function iv_fit.

Usage

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

## S3 method for class 'iv_fit'
print(x, digits = 3, ...)

Arguments

Value

print.iv_fit returns the object x invisibly. summary.iv_fit returns an object of class summary.iv_fit. print.summary.iv_fit returns its argument invisibly.

Examples

data("card")
y <- card$lwage
d <- card$educ
z <- card$nearc4
x <- model.matrix( ~ exper + expersq + black + south + smsa + reg661 + reg662 +
                     reg663 + reg664 + reg665+ reg666 + reg667 + reg668 + smsa66,
                   data = card)
card.fit <- iv_fit(y, d, z, x)
print(card.fit)
summary(card.fit)