Type:	Package
Title:	Tipping Point Analyses
Version:	1.0.2
Description:	The strength of evidence provided by epidemiological and observational studies is inherently limited by the potential for unmeasured confounding. We focus on three key quantities: the observed bound of the confidence interval closest to the null, the relationship between an unmeasured confounder and the outcome, for example a plausible residual effect size for an unmeasured continuous or binary confounder, and the relationship between an unmeasured confounder and the exposure, for example a realistic mean difference or prevalence difference for this hypothetical confounder between exposure groups. Building on the methods put forth by Cornfield et al. (1959), Bross (1966), Schlesselman (1978), Rosenbaum & Rubin (1983), Lin et al. (1998), Lash et al. (2009), Rosenbaum (1986), Cinelli & Hazlett (2020), VanderWeele & Ding (2017), and Ding & VanderWeele (2016), we can use these quantities to assess how an unmeasured confounder may tip our result to insignificance.
License:	MIT + file LICENSE
URL:	https://r-causal.github.io/tipr/, https://github.com/r-causal/tipr
BugReports:	https://github.com/r-causal/tipr/issues
Depends:	R (≥ 2.10)
Imports:	cli (≥ 3.4.1), glue, purrr, rlang (≥ 1.0.6), sensemakr, tibble
Suggests:	broom, dplyr, MASS, testthat
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.3.1
NeedsCompilation:	no
Packaged:	2024-02-06 19:19:07 UTC; lucymcgowan
Author:	Lucy D'Agostino McGowan [aut, cre], Malcolm Barrett [aut]
Maintainer:	Lucy D'Agostino McGowan <lucydagostino@gmail.com>
Repository:	CRAN
Date/Publication:	2024-02-06 19:30:02 UTC

tipr

Description

The tipr package.

Author(s)

Maintainer: Lucy D'Agostino McGowan lucydagostino@gmail.com (ORCID)

Other contributors:

• Malcolm Barrett malcolmbarrett@gmail.com (ORCID) [contributor]

References

D'Agostino McGowan, L, (2022). tipr: An R package for sensitivity analyses for unmeasured confounders. Journal of Open Source Software, 7(77), 4495.

D’Agostino McGowan, L. (2022). Sensitivity Analyses for Unmeasured Confounders. Current Epidemiology Reports, 9(4), 361-375.

VanderWeele, TJ, and Peng D (2017). Sensitivity Analysis in Observational Research: Introducing the E-Value. Ann Intern Med, 167(4), 268–74.

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

Lin, DY, Psaty, BM, & Kronmal, RA. (1998). Assessing the sensitivity of regression results to unmeasured confounders in observational studies. Biometrics, 54(3), 948–963.

See Also

Useful links:

• https://r-causal.github.io/tipr/

• https://github.com/r-causal/tipr

• Report bugs at https://github.com/r-causal/tipr/issues

Pipe operator

Description

Pipe operator

Usage

lhs %>% rhs

Adjust an observed regression coefficient for a normally distributed confounder

Description

Adjust an observed regression coefficient for a normally distributed confounder

Usage

adjust_coef(
  effect_observed,
  exposure_confounder_effect,
  confounder_outcome_effect,
  verbose = getOption("tipr.verbose", TRUE)
)

adjust_coef_with_continuous(
  effect_observed,
  exposure_confounder_effect,
  confounder_outcome_effect,
  verbose = getOption("tipr.verbose", TRUE)
)

Arguments

Value

Data frame.

Examples

## Update an observed coefficient of 0.5 with an unmeasured confounder
## with a difference in scaled means between exposure groups of 0.2
## and coefficient of 0.3
adjust_coef(0.5, 0.2, 0.3)

Adjust an observed coefficient from a regression model with a binary confounder

Description

Adjust an observed coefficient from a regression model with a binary confounder

Usage

adjust_coef_with_binary(
  effect_observed,
  exposed_confounder_prev,
  unexposed_confounder_prev,
  confounder_outcome_effect,
  loglinear = FALSE,
  verbose = getOption("tipr.verbose", TRUE)
)

Arguments

Value

Data frame.

Examples

adjust_coef_with_binary(1.1, 0.5, 0.3, 1.3)

Adjust a regression coefficient using the partial R2 for an unmeasured confounder-exposure relationship and unmeasured confounder- outcome relationship

Description

This function wraps the sensemakr::adjusted_estimate() and sensemakr::adjusted_se() functions.

Usage

adjust_coef_with_r2(
  effect_observed,
  se,
  df,
  confounder_exposure_r2,
  confounder_outcome_r2,
  verbose = getOption("tipr.verbose", TRUE),
  alpha = 0.05,
  ...
)

Arguments

Value

A data frame.

References

Carlos Cinelli, Jeremy Ferwerda and Chad Hazlett (2021). sensemakr: Sensitivity Analysis Tools for Regression Models. R package version 0.1.4. https://CRAN.R-project.org/package=sensemakr

Examples

adjust_coef_with_r2(0.5, 0.1, 102, 0.05, 0.1)

Adjust an observed hazard ratio for a normally distributed confounder

Description

Adjust an observed hazard ratio for a normally distributed confounder

Usage

adjust_hr(
  effect_observed,
  exposure_confounder_effect,
  confounder_outcome_effect,
  verbose = getOption("tipr.verbose", TRUE),
  hr_correction = FALSE
)

adjust_hr_with_continuous(
  effect_observed,
  exposure_confounder_effect,
  confounder_outcome_effect,
  verbose = getOption("tipr.verbose", TRUE),
  hr_correction = FALSE
)

Arguments

Value

Data frame.

Examples

adjust_hr(0.9, -0.9, 1.3)

Adjust an observed hazard ratio with a binary confounder

Description

Adjust an observed hazard ratio with a binary confounder

Usage

adjust_hr_with_binary(
  effect_observed,
  exposed_confounder_prev,
  unexposed_confounder_prev,
  confounder_outcome_effect,
  verbose = getOption("tipr.verbose", TRUE),
  hr_correction = FALSE
)

Arguments

Value

Data frame.

Examples

adjust_hr_with_binary(0.8, 0.1, 0.5, 1.8)

Adjust an observed odds ratio for a normally distributed confounder

Description

Adjust an observed odds ratio for a normally distributed confounder

Usage

adjust_or(
  effect_observed,
  exposure_confounder_effect,
  confounder_outcome_effect,
  verbose = getOption("tipr.verbose", TRUE),
  or_correction = FALSE
)

adjust_or_with_continuous(
  effect_observed,
  exposure_confounder_effect,
  confounder_outcome_effect,
  verbose = getOption("tipr.verbose", TRUE),
  or_correction = FALSE
)

Arguments

Value

Data frame.

Examples

adjust_or(1.2, 0.9, 1.3)

Adjust an observed odds ratio with a binary confounder

Description

Adjust an observed odds ratio with a binary confounder

Usage

adjust_or_with_binary(
  effect_observed,
  exposed_confounder_prev,
  unexposed_confounder_prev,
  confounder_outcome_effect,
  verbose = getOption("tipr.verbose", TRUE),
  or_correction = FALSE
)

Arguments

Value

Data frame.

Examples

adjust_or_with_binary(3, 1, 0, 3)
adjust_or_with_binary(3, 1, 0, 3, or_correction = TRUE)

Adjust an observed risk ratio for a normally distributed confounder

Description

Adjust an observed risk ratio for a normally distributed confounder

Usage

adjust_rr(
  effect_observed,
  exposure_confounder_effect,
  confounder_outcome_effect,
  verbose = TRUE
)

adjust_rr_with_continuous(
  effect_observed,
  exposure_confounder_effect,
  confounder_outcome_effect,
  verbose = TRUE
)

Arguments

Value

Data frame.

Examples

adjust_rr(1.2, 0.5, 1.1)

Adjust an observed risk ratio with a binary confounder

Description

Adjust an observed risk ratio with a binary confounder

Usage

adjust_rr_with_binary(
  effect_observed,
  exposed_confounder_prev,
  unexposed_confounder_prev,
  confounder_outcome_effect,
  verbose = getOption("tipr.verbose", TRUE)
)

Arguments

Value

Data frame.

Examples

adjust_rr_with_binary(1.1, 0.5, 0.3, 1.3)

Calculate an E-value

Description

Calculate an E-value

Usage

e_value(effect_observed)

Arguments

Value

Numeric value

Examples

e_value(0.9)
e_value(1.3)

Example Data (Continuous Outcome)

Description

A data set simulated with two Normally distributed confounders, one "measured" and one "unmeasured", an exposure, and outcome. The "true" causal effect of the exposure on the outcome, accounting for both the measured and unmeasured confounders, should be 0.

Usage

exdata_continuous

Format

A data frame with 2,000 rows and 4 columns:

• .unmeasured_confounder: A simulated unmeasured confounder

• measured_confounder: A simulated measured confounder

• exposure

• outcome

Example Data (Risk Ratio)

Description

A data set simulated with two Normally distributed confounders, one "measured" and one "unmeasured", an exposure, and outcome. The "true" causal effect of the exposure on the outcome, accounting for both the measured and unmeasured confounders, should be 0.

Usage

exdata_rr

Format

A data frame with 2,000 rows and 4 columns:

• .unmeasured_confounder: A simulated unmeasured confounder

• measured_confounder: A simulated measured confounder

• exposure

• outcome

Order observed bias data frame for plotting

Description

Order observed bias data frame for plotting

Usage

observed_bias_order(d, by)

Arguments

Value

Data frame in the correct order

Create a data frame to assist with creating an observed bias plot

Description

Create a data frame to assist with creating an observed bias plot

Usage

observed_bias_tbl(ps_mod, outcome_mod, drop_list = NULL)

Arguments

Value

Data frame with the following columns:

• dropped: The covariate or group of covariates that were dropped

• type: Explanation of dropped, whether it refers to a single covariate (covariate) or a group of covariates (group)

• ps_formula: The new formula for the updated propensity score model

• outcome_formula: The new formula for the updated outcome model

• ps_model: The new model object for the updated propensity score model

• p: The updated propensity score

Examples

ps_mod <- glm(am ~ mpg + cyl + I(hp^2), data = mtcars)
outcome_mod <- lm(qsec ~ am + hp + disp + wt, data = mtcars)
observed_bias_tbl(
 ps_mod,
 outcome_mod,
 drop_list = list(
   group_one = c("mpg", "hp"),
   group_two = c("cyl", "wt")
   )
 )

Create a data frame to combine with an observed bias data frame demonstrating a hypothetical unmeasured confounder

Description

Create a data frame to combine with an observed bias data frame demonstrating a hypothetical unmeasured confounder

Usage

observed_bias_tip(
  tip,
  point_estimate,
  lb,
  ub,
  tip_desc = "Hypothetical unmeasured confounder"
)

Arguments

Value

A data frame with five columns:

• dropped: the input from tip_desc

• type: Explanation of dropped, here tip to clarify that this was calculated as a tipping point.

• point_estimate: the shifted point estimate

• lb: the shifted lower bound

• ub: the shifted upper bound

Calculate the Observed Covariate E-value

Description

Calculate the Observed Covariate E-value

Usage

observed_covariate_e_value(lb, ub, lb_adj, ub_adj, transform = NULL)

Arguments

Value

The Observed Covariate E-value

Robustness value

Description

This function wraps the sensemakr::robustness_value() function

Usage

r_value(effect_observed, se, df, ...)

Arguments

Value

Numeric. Robustness value

References

Carlos Cinelli, Jeremy Ferwerda and Chad Hazlett (2021). sensemakr: Sensitivity Analysis Tools for Regression Models. R package version 0.1.4. https://CRAN.R-project.org/package=sensemakr

Examples

r_value(0.5, 0.1, 102)

Tip a result with a normally distributed confounder.

Description

choose one of the following, and the other will be estimated:

• exposure_confounder_effect

• confounder_outcome_effect

Usage

tip(
  effect_observed,
  exposure_confounder_effect = NULL,
  confounder_outcome_effect = NULL,
  verbose = getOption("tipr.verbose", TRUE),
  correction_factor = "none"
)

tip_with_continuous(
  effect_observed,
  exposure_confounder_effect = NULL,
  confounder_outcome_effect = NULL,
  verbose = getOption("tipr.verbose", TRUE),
  correction_factor = "none"
)

tip_c(
  effect_observed,
  exposure_confounder_effect = NULL,
  confounder_outcome_effect = NULL,
  verbose = getOption("tipr.verbose", TRUE),
  correction_factor = "none"
)

Arguments

Value

Data frame.

Examples

## to estimate the relationship between an unmeasured confounder and outcome
## needed to tip analysis
tip(1.2, exposure_confounder_effect = -2)

## to estimate the number of unmeasured confounders specified needed to tip
## the analysis
tip(1.2, exposure_confounder_effect = -2, confounder_outcome_effect = .99)

## Example with broom
if (requireNamespace("broom", quietly = TRUE) &&
    requireNamespace("dplyr", quietly = TRUE)) {
  glm(am ~ mpg, data = mtcars, family = "binomial") %>%
   broom::tidy(conf.int = TRUE, exponentiate = TRUE) %>%
   dplyr::filter(term == "mpg") %>%
   dplyr::pull(conf.low) %>%
   tip(confounder_outcome_effect = 2.5)
}

Tip a linear model coefficient with a continuous confounder.

Description

choose one of the following, and the other will be estimated:

• exposure_confounder_effect

• confounder_outcome_effect

Usage

tip_coef(
  effect_observed,
  exposure_confounder_effect = NULL,
  confounder_outcome_effect = NULL,
  verbose = getOption("tipr.verbose", TRUE)
)

tip_coef_with_continuous(
  effect_observed,
  exposure_confounder_effect = NULL,
  confounder_outcome_effect = NULL,
  verbose = getOption("tipr.verbose", TRUE)
)

Arguments

Value

Data frame.

Examples

## to estimate the relationship between an unmeasured confounder and outcome
## needed to tip analysis
tip_coef(1.2, exposure_confounder_effect = -2)

## to estimate the number of unmeasured confounders specified needed to tip
## the analysis
tip_coef(1.2, exposure_confounder_effect = -2, confounder_outcome_effect = -0.05)

## Example with broom
if (requireNamespace("broom", quietly = TRUE) &&
    requireNamespace("dplyr", quietly = TRUE)) {
  lm(wt ~ mpg, data = mtcars) %>%
   broom::tidy(conf.int = TRUE) %>%
   dplyr::filter(term == "mpg") %>%
   dplyr::pull(conf.low) %>%
   tip_coef(confounder_outcome_effect = 2.5)
}

Tip a regression coefficient using the partial R2 for an unmeasured confounder-exposure relationship and unmeasured confounder- outcome relationship

Description

Choose one of the following, and the other will be estimated:

• confounder_exposure_r2

• confounder_outcome_r2

Usage

tip_coef_with_r2(
  effect_observed,
  se,
  df,
  confounder_exposure_r2 = NULL,
  confounder_outcome_r2 = NULL,
  verbose = getOption("tipr.verbose", TRUE),
  alpha = 0.05,
  tip_bound = FALSE,
  ...
)

Arguments

Value

A data frame.

Examples

tip_coef_with_r2(0.5, 0.1, 102, 0.5)

Tip an observed hazard ratio with a normally distributed confounder.

Description

choose one of the following, and the other will be estimated:

• exposure_confounder_effect

• confounder_outcome_effect

Usage

tip_hr(
  effect_observed,
  exposure_confounder_effect = NULL,
  confounder_outcome_effect = NULL,
  verbose = getOption("tipr.verbose", TRUE),
  hr_correction = FALSE
)

tip_hr_with_continuous(
  effect_observed,
  exposure_confounder_effect = NULL,
  confounder_outcome_effect = NULL,
  verbose = getOption("tipr.verbose", TRUE),
  hr_correction = FALSE
)

Arguments

Value

Data frame.

Examples

## to estimate the relationship between an unmeasured confounder and outcome
## needed to tip analysis
tip_hr(1.2, exposure_confounder_effect = -2)

## to estimate the number of unmeasured confounders specified needed to tip
## the analysis
tip_hr(1.2, exposure_confounder_effect = -2, confounder_outcome_effect = .99)

Tip an observed hazard ratio with a binary confounder.

Description

Choose two of the following three to specify, and the third will be estimated:

• exposed_confounder_prev

• unexposed_confounder_prev

• confounder_outcome_effect

Alternatively, specify all three and the function will return the number of unmeasured confounders specified needed to tip the analysis.

Usage

tip_hr_with_binary(
  effect_observed,
  exposed_confounder_prev = NULL,
  unexposed_confounder_prev = NULL,
  confounder_outcome_effect = NULL,
  verbose = getOption("tipr.verbose", TRUE),
  hr_correction = FALSE
)

Arguments

Value

Data frame.

Examples

tip_hr_with_binary(0.9, 0.9, 0.1)

Tip an observed odds ratio with a normally distributed confounder.

Description

choose one of the following, and the other will be estimated:

• exposure_confounder_effect

• confounder_outcome_effect

Usage

tip_or(
  effect_observed,
  exposure_confounder_effect = NULL,
  confounder_outcome_effect = NULL,
  verbose = getOption("tipr.verbose", TRUE),
  or_correction = FALSE
)

tip_or_with_continuous(
  effect_observed,
  exposure_confounder_effect = NULL,
  confounder_outcome_effect = NULL,
  verbose = getOption("tipr.verbose", TRUE),
  or_correction = FALSE
)

Arguments

Value

Data frame.

Examples

## to estimate the relationship between an unmeasured confounder and outcome
## needed to tip analysis
tip_or(1.2, exposure_confounder_effect = -2)

## to estimate the number of unmeasured confounders specified needed to tip
## the analysis
tip_or(1.2, exposure_confounder_effect = -2, confounder_outcome_effect = .99)

## Example with broom
if (requireNamespace("broom", quietly = TRUE) &&
    requireNamespace("dplyr", quietly = TRUE)) {
  glm(am ~ mpg, data = mtcars, family = "binomial") %>%
   broom::tidy(conf.int = TRUE, exponentiate = TRUE) %>%
   dplyr::filter(term == "mpg") %>%
   dplyr::pull(conf.low) %>%
   tip_or(confounder_outcome_effect = 2.5, or_correction = TRUE)
}

Tip an observed odds ratio with a binary confounder.

Description

Choose two of the following three to specify, and the third will be estimated:

• exposed_confounder_prev

• unexposed_confounder_prev

• confounder_outcome_effect

Alternatively, specify all three and the function will return the number of unmeasured confounders specified needed to tip the analysis.

Usage

tip_or_with_binary(
  effect_observed,
  exposed_confounder_prev = NULL,
  unexposed_confounder_prev = NULL,
  confounder_outcome_effect = NULL,
  verbose = getOption("tipr.verbose", TRUE),
  or_correction = FALSE
)

Arguments

Value

Data frame.

Examples

tip_or_with_binary(0.9, 0.9, 0.1)

Tip an observed risk ratio with a normally distributed confounder.

Description

choose one of the following, and the other will be estimated:

• exposure_confounder_effect

• confounder_outcome_effect

Usage

tip_rr(
  effect_observed,
  exposure_confounder_effect = NULL,
  confounder_outcome_effect = NULL,
  verbose = getOption("tipr.verbose", TRUE)
)

tip_rr_with_continuous(
  effect_observed,
  exposure_confounder_effect = NULL,
  confounder_outcome_effect = NULL,
  verbose = getOption("tipr.verbose", TRUE)
)

Arguments

Value

Data frame.

Examples

## to estimate the relationship between an unmeasured confounder and outcome
## needed to tip analysis
tip_rr(1.2, exposure_confounder_effect = -2)

## to estimate the number of unmeasured confounders specified needed to tip
## the analysis
tip_rr(1.2, exposure_confounder_effect = -2, confounder_outcome_effect = .99)

Tip an observed risk ratio with a binary confounder.

Description

Choose two of the following three to specify, and the third will be estimated:

• exposed_confounder_prev

• unexposed_confounder_prev

• confounder_outcome_effect

Alternatively, specify all three and the function will return the number of unmeasured confounders specified needed to tip the analysis.

Usage

tip_rr_with_binary(
  effect_observed,
  exposed_confounder_prev = NULL,
  unexposed_confounder_prev = NULL,
  confounder_outcome_effect = NULL,
  verbose = getOption("tipr.verbose", TRUE)
)

Arguments

Tip a result with a binary confounder.

Description

Choose two of the following three to specify, and the third will be estimated:

• exposed_confounder_prev

• unexposed_confounder_prev

• confounder_outcome_effect

Alternatively, specify all three and the function will return the number of unmeasured confounders specified needed to tip the analysis.

Usage

tip_with_binary(
  effect_observed,
  exposed_confounder_prev = NULL,
  unexposed_confounder_prev = NULL,
  confounder_outcome_effect = NULL,
  verbose = getOption("tipr.verbose", TRUE),
  correction_factor = "none"
)

tip_b(
  effect_observed,
  exposed_confounder_prev = NULL,
  unexposed_confounder_prev = NULL,
  confounder_outcome_effect = NULL,
  verbose = getOption("tipr.verbose", TRUE),
  correction_factor = "none"
)

Arguments

Details

tip_b() is an alias for tip_with_binary().

Examples

## to estimate the relationship between an unmeasured confounder and outcome
## needed to tip analysis
tip_with_binary(1.2, exposed_confounder_prev = 0.5, unexposed_confounder_prev = 0)

## to estimate the number of unmeasured confounders specified needed to tip
## the analysis
tip_with_binary(1.2,
  exposed_confounder_prev = 0.5,
  unexposed_confounder_prev = 0,
  confounder_outcome_effect = 1.1)

## Example with broom
if (requireNamespace("broom", quietly = TRUE) &&
    requireNamespace("dplyr", quietly = TRUE)) {
  glm(am ~ mpg, data = mtcars, family = "binomial") %>%
   broom::tidy(conf.int = TRUE, exponentiate = TRUE) %>%
   dplyr::filter(term == "mpg") %>%
   dplyr::pull(conf.low) %>%
   tip_with_binary(exposed_confounder_prev = 1, confounder_outcome_effect = 1.15)
}