| Title: | Conduct Sensitivity Analysis with Continuous Exposures and Binary Outcomes |
| Version: | 0.1.0 |
| Description: | Performs sensitivity analysis for the sharp null and attributable effects in matched studies with continuous exposures and binary outcomes as described in Zhang, Small, Heng (2024) <doi:10.48550/arXiv.2401.06909>. Two of the functions require installation of the 'Gurobi' optimizer. Please see https://www.gurobi.com/documentation/9.0/refman/ins_the_r_package.html for guidance. |
| License: | MIT + file LICENSE |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.2.1 |
| LazyData: | true |
| Imports: | dplyr, gtools, stats, utils |
| Suggests: | gurobi |
| NeedsCompilation: | no |
| Packaged: | 2024-01-17 18:30:42 UTC; jeffreyzhang |
| Author: | Jeffrey Zhang [aut, cre] |
| Maintainer: | Jeffrey Zhang <jzhang17@wharton.upenn.edu> |
| Depends: | R (≥ 3.5.0) |
| Repository: | CRAN |
| Date/Publication: | 2024-01-17 19:42:10 UTC |
Separable algorithm for threshold attributable effect in a sensitivity analysis with at most one over-exposed unit in each matched set. For a greater than alternative, finds the 'a' matched sets that most decrease the mean and/or variance.
Description
Separable algorithm for threshold attributable effect in a sensitivity analysis with at most one over-exposed unit in each matched set. For a greater than alternative, finds the 'a' matched sets that most decrease the mean and/or variance.
Usage
binary_thresh_attribute(
Z,
Q,
index,
gamma,
thresh = 0,
a = 1,
trans = identity,
mc = 50000
)
Arguments
Z |
A length N vector of (nonnegative) observed doses. |
Q |
A length N vector of observed binary outcomes. |
index |
A length N vector of indices indicating matched set membership. |
gamma |
The nonnegative sensitivity parameter; gamma = 0 means no unmeasured confounding. |
thresh |
The dose threshold for the TAE. |
a |
The number of attributable effects to test for. |
trans |
The transformation of the doses to use for the test statistic. Default is the identity function. |
mc |
Number of monte-carlo samples if testing the sharp null, i.e. a = 0. |
Value
Either "reject" if the value a is deemed not plausible/compatible, "feasible" if the value a is deemed so, else a list containing a p-value and dataframe of matched sets that have contribution to the test statistic sorted in order of smallest mean reduction followed by smallest variance reduction.
Examples
# Load the data
data <- treat_out_match
# Solve by the separable algorithm
solution <- binary_thresh_attribute(data$treat, data$complain, data$match_ind,
gamma = 0, thresh = log(3.5), a = 5, trans = identity)
A helper that takes a gurobi model object outputted from dose_attributable_general or dose_thresh_attributable_one_sided and changes the Delta parameter. Saves computation time by directly editing the constraint involving Delta without having to reinitialize the other constraints that are kept the same. Outputs a list analogous to output from dose_attributable_general or dose_thresh_attributable_one_sided.
Description
A helper that takes a gurobi model object outputted from dose_attributable_general or dose_thresh_attributable_one_sided and changes the Delta parameter. Saves computation time by directly editing the constraint involving Delta without having to reinitialize the other constraints that are kept the same. Outputs a list analogous to output from dose_attributable_general or dose_thresh_attributable_one_sided.
Usage
change_Delta(model, Delta, direction = "equal", TT)
Arguments
model |
A gurobi model object outputted from dose_attributable_general. |
Delta |
The new Delta to test for. |
direction |
The new direction to test |
TT |
The observed test statistic. |
Value
A gurobi model and solution.
Computes deviation from uniform distribution in total variation distance for a given amount of unmeasured confounding and a greater than alternative with a binary outcome.
Description
Computes deviation from uniform distribution in total variation distance for a given amount of unmeasured confounding and a greater than alternative with a binary outcome.
Usage
dev_TV(Z, Q, index, gamma, direct = "upper")
Arguments
Z |
A length N vector of (nonnegative) observed doses. |
Q |
A length N vector of observed binary outcomes. |
index |
A length N vector of indices indicating matched set membership. |
gamma |
The nonnegative sensitivity parameter; gamma = 0 means no unmeasured confounding. |
direct |
The direction of the test - "upper" or "lower"; default is upper. |
Value
A vector of length equaling the number of matched sets consisting of the TV distance from the uniform for each matched set at gamma level of unmeasured confounding for the worst-case.
Examples
# Load the data
data <- treat_out_match
# compute total variation distances.
total_variation <- dev_TV(data$treat, data$complain,
data$match_ind, gamma = log(1.5))
Inference for general attributable effects in sensitivity analysis with continuous exposures and binary outcomes. Gurobi must be installed to use this function.
Description
Inference for general attributable effects in sensitivity analysis with continuous exposures and binary outcomes. Gurobi must be installed to use this function.
Usage
dose_attributable_general(
Z,
Q,
index,
gamma,
alpha = 0.05,
monotone = TRUE,
Delta,
sign = "positive",
trans = identity,
direction = "equal",
M = 10000,
eps = 0.01,
alternative = "both",
mv_threshold = NA,
baseline = 0,
relax = FALSE,
feasible = TRUE,
MIPgap = 0.01,
WorkLimit = 1000,
OutputFlag = 0
)
Arguments
Z |
A length N vector of (nonnegative) observed doses. |
Q |
A length N vector of observed binary outcomes. |
index |
A length N vector of indices indicating matched set membership. |
gamma |
The nonnegative sensitivity parameter; gamma = 0 means no unmeasured confounding. |
alpha |
Level of the test. |
monotone |
Whether to impose a monotonicity constraint on the potential outcomes |
Delta |
A numeric for the attributable effect to be tested for. |
sign |
The sign of monotonicity - "positive" or "negative". |
trans |
The transformation of the doses to use for the test statistic. Default is the identity function. |
direction |
A string indicating the direction of testing the attributable effect with respect to Delta; "greater", "equal", or "less" |
M |
The numeric penalty parameter to ensure correct sign relationship. |
eps |
precision parameter for the objective function if solving feasible = "Yes" |
alternative |
For constraining the rejection region using the test statistic with baseline potential outcomes, should it be constructed with "lower" alternative, "upper" alternative, or "both." |
mv_threshold |
The number of allowed monotonicity violations. |
baseline |
The baseline dose level for defining the threshold attributable effect. |
relax |
Whether to solve the continuous relaxation. |
feasible |
Whether to look for a feasible solution or to find the optimal solution. |
MIPgap |
Gurobi parameter specifying the precision of the mixed integer program solution; default is 0.01. |
WorkLimit |
Gurobi parameter specifying the maximum work units before stopping; default is 1000. |
OutputFlag |
0 if Gurobi print output is desired, 1 otherwise; default 0. |
Value
A list containing the following:
sol |
A gurobi object containing the solution to the optimization. If feasible is TRUE, then failing to find a solution indiciates rejection. If feasible is FALSE, then optimal value greater than zero indiciates rejection. |
attribut |
The attributable effect attained by the least rejectable allocation of potential outcomes and unmeasured confounders. |
search |
A list of length the number of matched sets containing the matrix of compatible baseline potential outcomes in each matched set. |
null_exp |
The null expectation of the pivot attained by the least rejectable allocation of potential outcomes and unmeasured confounders. |
obsT |
The value of the pivot attained by the least rejectable allocation of potential outcomes and unmeasured confounders. |
nps |
A vector with length the number of matched sets containing the size of each matched set. |
start.ind |
A vector with length the number of matched sets containing the starting index of the decision variables pertaining to each matched set in the optimization program. |
exp_upper |
The expectation of the pivot attained by the unmeasured confounders equalling the baseline potential outcome. |
exp_lower |
The expectation of the pivot attained by the unmeasured confounders equalling 1 minus the baseline potential outcome. |
var_upper |
The variance of the pivot attained by the unmeasured confounders equalling the baseline potential outcome. |
var_lower |
The variance of the pivot attained by the unmeasured confounders equalling 1 minus the baseline potential outcome. |
dose |
A list of length the number of matched sets containing the vector of doses observed in each matched set. |
model |
The initialized gurobi model. |
Examples
# To run the following example, Gurobi must be installed.
# Load the data
data <- treat_out_match
# Make a threshold at log(3.5) transformation function.
above = function(Z) { return(Z > log(3.5)) }
# Solve the mixed-integer program.
solution = dose_attributable_general(data$treat,
data$complain, data$match_ind, gamma=log(1),
alpha = 0.1, monotone = TRUE, trans = above,
Delta = 5, direction = "less", M = 10000, eps = 0.0001,
alternative = "upper", relax = FALSE, feasible = FALSE)
Sharp null monte-carlo sensitivity analysis for continuous exposures and binary outcomes.
Description
Sharp null monte-carlo sensitivity analysis for continuous exposures and binary outcomes.
Usage
dose_sensitivity_mc_gen(
Z,
Q,
index,
mc,
gamma,
weights = NA,
obsT = NULL,
trans = identity,
direct = "upper",
seed = 1,
verbose = FALSE
)
Arguments
Z |
A length N vector of (nonnegative) observed doses. |
Q |
A length N vector of observed binary outcomes. |
index |
A length N vector of indices indicating matched set membership. |
mc |
An integer for the total number of Monte-Carlo samples desired. |
gamma |
The nonnegative sensitivity parameter; gamma = 0 means no unmeasured confounding. |
weights |
Weights for each stratum to apply for the test statistic |
obsT |
The observed value of the test statistic; default is NULL |
trans |
The transformation of the doses to use for the test statistic. Default is the identity function. |
direct |
The direction of the test - "upper" or "lower"; default is upper. |
seed |
seed for random number generation. |
verbose |
Whether to print status updates or not; default is FALSE. |
Value
A list containing two objects:
mc |
A length mc vector containing the monte-carlo samples of the test statistic. |
p |
The monte-carlo p-value. |
Examples
# Load the data
data <- treat_out_match
# Make a threshold at log(3.5) transformation function.
above = function(Z) { return(Z > log(3.5)) }
# Conduct randomization test.
solution <- dose_sensitivity_mc_gen(data$treat, data$complain, data$match_ind,
mc = 250, gamma = 0, trans = above)
Inference for threshold attributable effects in sensitivity analysis with continuous exposures and binary outcomes. Gurobi must be installed to use this function.
Description
Inference for threshold attributable effects in sensitivity analysis with continuous exposures and binary outcomes. Gurobi must be installed to use this function.
Usage
dose_thresh_attributable_one_sided(
Z,
Q,
index,
gamma,
alpha = 0.05,
monotone = TRUE,
Delta,
sign = "positive",
direction = "equal",
threshold = 0,
M = 10000,
eps = 0.01,
mv_threshold = NA,
baseline = 0,
relax = FALSE,
feasible = TRUE,
MIPgap = 0.01,
WorkLimit = 1000,
OutputFlag = 0
)
Arguments
Z |
A length N vector of (nonnegative) observed doses. |
Q |
A length N vector of observed binary outcomes. |
index |
A length N vector of indices indicating matched set membership. |
gamma |
The nonnegative sensitivity parameter; gamma = 0 means no unmeasured confounding. |
alpha |
Level of the test. |
monotone |
Whether to impose a monotonicity constraint on the potential outcomes |
Delta |
A numeric for the attributable effect to be tested for. |
sign |
The sign of monotonicity - "positive" or "negative". |
direction |
A string indicating the direction of testing the attributable effect with respect to Delta; "greater", "equal", or "less" |
threshold |
The threshold for the TAE. |
M |
The numeric penalty parameter to ensure correct sign relationship. |
eps |
precision parameter for the objective function if solving feasible = "Yes" |
mv_threshold |
The number of allowed monotonicity violations. |
baseline |
The baseline dose level for defining the threshold attributable effect. |
relax |
Whether to solve the continuous relaxation. |
feasible |
Whether to look for a feasible solution or to find the optima. |
MIPgap |
Gurobi parameter specifying the precision of the mixed integer program solution; default is 0.01. |
WorkLimit |
Gurobi parameter specifying the maximum work units before stopping; default is 1000. |
OutputFlag |
0 if Gurobi print output is desired, 1 otherwise; default 0. |
Value
A list containing the following:
sol |
A gurobi object containing the solution to the optimization. If feasible is TRUE, then failing to find a solution indiciates rejection. If feasible is FALSE, then optimal value greater than zero indiciates rejection. |
attribut |
The attributable effect attained by the least rejectable allocation of potential outcomes and unmeasured confounders. |
search |
A list of length the number of matched sets containing the matrix of compatible baseline potential outcomes in each matched set. |
null_exp |
The null expectation of the pivot attained by the least rejectable allocation of potential outcomes and unmeasured confounders. |
obsT |
The value of the pivot attained by the least rejectable allocation of potential outcomes and unmeasured confounders. |
nps |
A vector with length the number of matched sets containing the size of each matched set. |
start.ind |
A vector with length the number of matched sets containing the starting index of the decision variables pertaining to each matched set in the optimization program. |
exp_upper |
The expectation of the pivot attained by the unmeasured confounders equalling the baseline potential outcome. |
var_upper |
The variance of the pivot attained by the unmeasured confounders equalling the baseline potential outcome. |
dose |
A list of length the number of matched sets containing the vector of doses observed in each matched set. |
model |
The initialized gurobi model. |
Examples
# To run the following example, Gurobi must be installed.
# Load the data
data <- treat_out_match
# Solve the mixed-integer program.
solution = dose_thresh_attributable_one_sided(data$treat,
data$complain, data$match_ind,
gamma=log(1), alpha = 0.1, monotone = TRUE, Delta = 5,
direction = "less", threshold = log(3.5),M = 10000,
eps = 0.0001,relax = FALSE, feasible = FALSE)
Sharp null sensitivity analysis for continuous exposures and binary outcomes using normal approximation.
Description
Sharp null sensitivity analysis for continuous exposures and binary outcomes using normal approximation.
Usage
normal_test_gen(
Z,
Q,
index,
gamma,
trans = identity,
weights = NA,
obsT = NULL,
direct = "upper"
)
Arguments
Z |
A length N vector of (nonnegative) observed doses. |
Q |
A length N vector of observed binary outcomes. |
index |
A length N vector of indices indicating matched set membership. |
gamma |
The nonnegative sensitivity parameter; gamma = 0 means no unmeasured confounding. |
trans |
The transformation of the doses to use for the test statistic. Default is the identity function. |
weights |
Weights to apply for the test statistic |
obsT |
The observed value of the test statistic; default is NULL. |
direct |
The direction of the test - "upper" or "lower"; default is upper. |
Value
A list containing the following:
obsT |
The observed value of the test statistic |
exp |
The worst-case expectation |
var |
The worst-case variance. |
deviate |
The normal approximation deviate. |
Examples
# Load the data
data <- treat_out_match
# Make a threshold at log(3.5) transformation function.
above = function(Z) { return(Z > log(3.5)) }
# Conduct randomization test using normal approximation.
solution <- normal_test_gen(data$treat, data$complain, data$match_ind,
gamma = 0, trans = above)
Matched lead dataset
Description
A matched, trimmed dataset of early life lead exposure and juvenile delinquency. There are 2007 matched sets.
Usage
treat_out_match
Format
treat_out_match
A data frame with 4,134 rows and 4 columns:
- treat
The log of lead exposure level measured in micrograms per deciliter.
- serious
Whether the juvenile comitted a serious offense.
- complain
Whether the juvenile comitted an offense worthy of complaint.
- match_ind
Matched set membership.
...