audit {ivmte}

Audit procedure

Description

This is the wrapper for running the entire audit procedure. This function sets up the LP/QCQP problem of minimizing criterion. for the set of IV-like estimands, while satisfying boundedness and monotonicity constraints declared by the user. Rather than enforce that boundedness and monotonicity hold across the entire support of covariates and unobservables, this procedure enforces the conditions over a grid of points. This grid corresponds to the set of values the covariates can take, and a set of values of the unobservable term. The size of this grid is specified by the user in the function arguments. The procedure first estimates the bounds while imposing the shape constraints for an initial subset of points in the grid. The procedure then goes on to check ('audit') whether the constraints are satisfied over the entire grid. Any point where either the boundedness or monotonicity constraints are violated are incorporated into the initial grid, and the process is repeated until the audit no longer finds any violations, or until some maximum number of iterations is reached.

Usage

audit(
  data,
  uname,
  m0,
  m1,
  pm0,
  pm1,
  splinesobj,
  vars_mtr,
  terms_mtr0,
  terms_mtr1,
  vars_data,
  initgrid.nu = 20,
  initgrid.nx = 20,
  audit.nx = 2500,
  audit.nu = 25,
  audit.add = 100,
  audit.max = 25,
  audit.tol,
  audit.grid = NULL,
  m1.ub,
  m0.ub,
  m1.lb,
  m0.lb,
  mte.ub,
  mte.lb,
  m1.ub.default = FALSE,
  m0.ub.default = FALSE,
  mte.ub.default = FALSE,
  m1.lb.default = FALSE,
  m0.lb.default = FALSE,
  mte.lb.default = FALSE,
  m0.dec = FALSE,
  m0.inc = FALSE,
  m1.dec = FALSE,
  m1.inc = FALSE,
  mte.dec = FALSE,
  mte.inc = FALSE,
  equal.coef0,
  equal.coef1,
  sset,
  gstar0,
  gstar1,
  orig.sset = NULL,
  orig.criterion = NULL,
  criterion.tol = 1e-04,
  solver,
  solver.options,
  solver.presolve,
  solver.options.criterion,
  solver.options.bounds,
  rescale = TRUE,
  smallreturnlist = FALSE,
  noisy = TRUE,
  debug = FALSE
)

Arguments

data

data.frame or data.table used to estimate the treatment effects.

uname

variable name for the unobservable used in declaring the MTRs. The name can be provided with or without quotation marks.

m0

one-sided formula for the marginal treatment response function for the control group. Splines may also be incorporated using the expression uSpline, e.g. uSpline(degree = 2, knots = c(0.4, 0.8), intercept = TRUE). The intercept argument may be omitted, and is set to TRUE by default.

m1

one-sided formula for the marginal treatment response function for the treated group. See m0 for details.

pm0

A list of the monomials in the MTR for the control group.

pm1

A list of the monomials in the MTR for the treated group.

splinesobj

list of spline components in the MTRs for treated and control groups. Spline terms are extracted using removeSplines. This object is supposed to be a dictionary of splines, containing the original calls of each spline in the MTRs, their specifications, and the index used for naming each basis spline.

vars_mtr

character, vector of variables entering into m0 and m1.

terms_mtr0

character, vector of terms entering into m0.

terms_mtr1

character, vector of terms entering into m1.

vars_data

character, vector of variables that can be found in the data.

initgrid.nu

integer determining the number of points in the open interval (0, 1) drawn from a Halton sequence. The end points 0 and 1 are additionally included. These points are always a subset of the points defining the audit grid (see audit.nu). These points are used to form the initial constraint grid for imposing shape restrictions on the u components of the MTRs.

initgrid.nx

integer determining the number of points of the covariates used to form the initial constraint grid for imposing shape restrictions on the MTRs.

audit.nx

integer determining the number of points on the covariates space to audit in each iteration of the audit procedure.

audit.nu

integer determining the number of points in the open interval (0, 1) drawn from a Halton sequence. The end points 0 and 1 are additionally included. These points are used to audit whether the shape restrictions on the u components of the MTRs are satisfied. The initial grid used to impose the shape constraints in the LP/QCQP problem are constructed from a subset of these points.

audit.add

maximum number of points to add to the initial constraint grid for imposing each kind of shape constraint. For example, if there are 5 different kinds of shape constraints, there can be at most audit.add * 5 additional points added to the constraint grid.

audit.max

maximum number of iterations in the audit procedure.

audit.tol

feasibility tolerance when performing the audit. By default to set to be 1e-06, which is equal to the default feasibility tolerances of Gurobi (solver = "gurobi"), CPLEX (solver = "cplexapi"), and Rmosek (solver = "rmosek"). This parameter should only be changed if the feasibility tolerance of the solver is changed, or if numerical issues result in discrepancies between the solver's feasibility check and the audit.

audit.grid

list, contains the A matrix used in the audit for the original sample, as well as the RHS vector used in the audit from the original sample.

m1.ub

numeric value for upper bound on MTR for the treated group. By default, this will be set to the largest value of the observed outcome in the estimation sample.

m0.ub

numeric value for upper bound on MTR for the control group. By default, this will be set to the largest value of the observed outcome in the estimation sample.

m1.lb

numeric value for lower bound on MTR for the treated group. By default, this will be set to the smallest value of the observed outcome in the estimation sample.

m0.lb

numeric value for lower bound on MTR for the control group. By default, this will be set to the smallest value of the observed outcome in the estimation sample.

mte.ub

numeric value for upper bound on treatment effect parameter of interest.

mte.lb

numeric value for lower bound on treatment effect parameter of interest.

m1.ub.default

boolean, default set to FALSE. Indicator for whether the value assigned was by the user, or set by default.

m0.ub.default

boolean, default set to FALSE. Indicator for whether the value assigned was by the user, or set by default.

mte.ub.default

boolean, default set to FALSE. Indicator for whether the value assigned was by the user, or set by default.

m1.lb.default

boolean, default set to FALSE. Indicator for whether the value assigned was by the user, or set by default.

m0.lb.default

boolean, default set to FALSE. Indicator for whether the value assigned was by the user, or set by default.

mte.lb.default

boolean, default set to FALSE. Indicator for whether the value assigned was by the user, or set by default.

m0.dec

logical, set to FALSE by default. Set equal to TRUE if the MTR for the control group should be weakly monotone decreasing.

m0.inc

logical, set to FALSE by default. Set equal to TRUE if the MTR for the control group should be weakly monotone increasing.

m1.dec

logical, set to FALSE by default. Set equal to TRUE if the MTR for the treated group should be weakly monotone decreasing.

m1.inc

logical, set to FALSE by default. Set equal to TRUE if the MTR for the treated group should be weakly monotone increasing.

mte.dec

logical, set to FALSE by default. Set equal to TRUE if the MTE should be weakly monotone decreasing.

mte.inc

logical, set to FALSE by default. Set equal to TRUE if the MTE should be weakly monotone increasing.

equal.coef0

character, a vector containing all the terms in m0 that should have the same coefficients in m1. The order of the variables must match those of equal.coef1, which contains all the corresponding terms in m1. The reason the terms are entered separately for m0 and m1 is because the spline terms may be named differently across treatment and control groups.

equal.coef1

character, a vector containing all the terms in m1 that should have the same coefficients in m0. See the description for equal.coef0 for more details.

sset

a list containing the point estimates and gamma moments for each IV-like specification.

gstar0

set of expectations for each terms of the MTR for the control group, corresponding to the target parameter.

gstar1

set of expectations for each terms of the MTR for the control group, corresponding to the target parameter.

orig.sset

list, only used for bootstraps. The list contains the gamma moments for each element in the S-set, as well as the IV-like coefficients.

orig.criterion

numeric, only used for bootstraps. The scalar corresponds to the minimum observational equivalence criterion from the original sample.

criterion.tol

tolerance for the criterion function, and is set to 1e-4 by default. The criterion measures how well the IV-like moments/conditional means are matched using the l1-norm. Statistical noise may prohibit the theoretical LP/QCQP problem from being feasible. That is, there may not exist a set of MTR coefficients that are able to match all the specified moments. The function thus first estimates the minimum criterion, which is reported in the output under the name 'minimum criterion', with a criterion of 0 meaning that all moments were able to be matched. The function then relaxes the constraints by tolerating a criterion up to minimum criterion * (1 + criterion.tol). Set criterion.tol to a value greater than 0 to allow for more conservative bounds.

solver

character, name of the programming package in R used to obtain the bounds on the treatment effect. The function supports 'gurobi', 'cplexapi', rmosek, 'lpsolveapi'. The name of the solver should be provided with quotation marks.

solver.options

list, each item of the list should correspond to an option specific to the solver selected.

solver.presolve

boolean, default set to TRUE. Set this parameter to FALSE if presolve should be turned off for the LP/QCQP problems.

solver.options.criterion

list, each item of the list should correspond to an option specific to the solver selected. These options are specific for finding the minimum criterion.

solver.options.bounds

list, each item of the list should correspond to an option specific to the solver selected. These options are specific for finding the bounds.

rescale

boolean, set to TRUE if the MTR components should be rescaled to improve stability in the LP/QCQP optimization.

smallreturnlist

boolean, default set to FALSE. Set to TRUE to exclude large intermediary components (i.e. propensity score model, LP/QCQP model, bootstrap iterations) from being included in the return list.

noisy

boolean, default set to TRUE. If TRUE, then messages are provided throughout the estimation procedure. Set to FALSE to suppress all messages, e.g. when performing the bootstrap.

debug

boolean, indicates whether or not the function should provide output when obtaining bounds. The option is only applied when solver = 'gurobi' or solver = 'rmosek'. The output provided is the same as what the Gurobi API would send to the console.

Value

a list. Included in the list are estimates of the treatment effect bounds; the minimum violation of observational equivalence of the set of IV-like estimands; the list of matrices and vectors defining the LP/QCQP problem; the points used to generate the audit grid, and the points where the shape constraints were violated.

Examples

dtm <- ivmte:::gendistMosquito()

## Declare empty list to be updated (in the event multiple IV like
## specifications are provided
sSet <- list()

## Declare MTR formulas
formula0 = ~ 1 + u
formula1 = ~ 1 + u

## Construct object that separates out non-spline components of MTR
## formulas from the spline components. The MTR functions are
## obtained from this object by the function 'genSSet'
splinesList = list(removeSplines(formula0), removeSplines(formula1))

## If splines are interacted with other variables, the
## 'interactSplines' should be used.
## splinesList <- interactSplines(splinesobj = splinesList,
##                               m0 = formula0,
##                               m1 = formula1,
##                               data = data,
##                               uname = 'u')

## Construct MTR polynomials
polynomials0 <- polyparse(formula = formula0,
                 data = dtm,
                 uname = u,
                 as.function = FALSE)

polynomials1 <- polyparse(formula = formula1,
                 data = dtm,
                 uname = u,
                 as.function = FALSE)

## Generate propensity score model
propensityObj <- propensity(formula = d ~ z,
                            data = dtm,
                            link = "linear")

## Generate IV estimates
ivEstimates <- ivEstimate(formula = ey ~ d | z,
                          data = dtm,
                          components = l(intercept, d),
                          treat = d,
                          list = FALSE)

## Generate target gamma moments
targetGamma <- genTarget(treat = "d",
                         m0 = ~ 1 + u,
                         m1 = ~ 1 + u,
                         target = "atu",
                         data = dtm,
                         splinesobj = splinesList,
                         pmodobj = propensityObj,
                         pm0 = polynomials0,
                         pm1 = polynomials1)

## Construct S-set, which contains the coefficients and weights
## corresponding to various IV-like estimands
sSet <- genSSet(data = dtm,
                sset = sSet,
                sest = ivEstimates,
                splinesobj = splinesList,
                pmodobj = propensityObj$phat,
                pm0 = polynomials0,
                pm1 = polynomials1,
                ncomponents = 2,
                scount = 1,
                yvar = "ey",
                dvar = "d",
                means = TRUE)

## Perform audit procedure and return bounds
audit(data = dtm,
      uname = u,
      m0 = formula0,
      m1 = formula1,
      pm0 = polynomials0,
      pm1 = polynomials1,
      splinesobj = splinesList,
      vars_data = colnames(dtm),
      vars_mtr = "u",
      terms_mtr0 = "u",
      terms_mtr1 = "u",
      sset = sSet$sset,
      gstar0 = targetGamma$gstar0,
      gstar1 = targetGamma$gstar1,
      m0.inc = TRUE,
      m1.dec = TRUE,
      m0.lb = 0.2,
      m1.ub = 0.8,
      audit.max = 5,
      solver = "lpSolveAPI")