Package 'ivmte'

Description

Angrist Evans Data

Usage

AE

Format

A data frame with 209,133 rows and 8 columns.

worked

indicator for whether worked in the previous year

hours

weekly hours worked in the previous year

morekids

indicator for having more than two children vs. exactly two children.

samesex

indicator for the first two children having the same sex (male-male or female-female)

yob

the year the woman was born

black

indicator that mother is Black

hisp

indicator that mother is Hispanic

other

indicator that mother is neither Black nor Hispanic

Source

Derived from Angrist and Evans (1998, The American Economic Review).

Description

This function returns a numerically integrable function corresponding to a single splines basis function. It was not implemented because it was slower than using the function from the splines2 package.

Usage

altDefSplinesBasis(splineslist, j, l, v = 1)

Arguments

Value

a vectorized function corresponding to a single splines basis function that can be numerically integrated.

Description

Auxiliary function to extract arguments from a function that is in string form.

Usage

argstring(string)

Arguments

Value

string of arguments.

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

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")

Description

This function estimates the bounds on the target treatment effect. The LP model must be passed as an environment variable, under the entry $model. See lpSetup.

Usage

bound(
  env,
  sset,
  solver,
  solver.options,
  noisy = FALSE,
  smallreturnlist = FALSE,
  rescale = FALSE,
  debug = FALSE
)

Arguments

Value

a list containing the bounds on the treatment effect; the coefficients on each term in the MTR associated with the upper and lower bounds, for both counterfactuals; the optimization status to the maximization and minimization problems; the LP problem that the optimizer solved.

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))

## 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)
## Only the entry $sset is required
sSet <- sSet$sset

## Define additional upper- and lower-bound constraints for the LP
## problem
A <- matrix(0, nrow = 22, ncol = 4)
A <- cbind(A, rbind(cbind(1, seq(0, 1, 0.1)),
                    matrix(0, nrow = 11, ncol = 2)))
A <- cbind(A, rbind(matrix(0, nrow = 11, ncol = 2),
                    cbind(1, seq(0, 1, 0.1))))
sense <- c(rep(">", 11), rep("<", 11))
rhs <- c(rep(0.2, 11), rep(0.8, 11))

## Construct LP object to be interpreted and solved by
## lpSolveAPI. Note that an environment has to be created for the LP
## object. The matrices defining the shape restrictions must be stored
## as a list under the entry \code{$mbobj} in the environment.
modelEnv <- new.env()
modelEnv$mbobj <- list(mbA = A,
                    mbs = sense,
                    mbrhs = rhs)
## Convert the matrices defining the shape constraints into a format
## that is suitable for the LP solver.
lpSetup(env = modelEnv,
        sset = sSet,
        solver = "lpsolveapi")
## Setup LP model so that it is solving for the bounds.
lpSetupBound(env = modelEnv,
             g0 = targetGamma$gstar0,
             g1 = targetGamma$gstar1,
             sset = sSet,
             criterion.tol = 0,
             criterion.min = 0,
             solver = "lpsolveapi")
## Declare any LP solver options as a list.
lpOptions <- optionsLpSolveAPI(list(epslevel = "tight"))
## Obtain the bounds.
bounds <- bound(env = modelEnv,
                sset = sSet,
                solver = "lpsolveapi",
                solver.options = lpOptions)
cat("The bounds are [",  bounds$min, ",", bounds$max, "].\n")

Description

This function constructs the forward and backward confidence intervals for the treatment effect under partial identification.

Usage

boundCI(bounds, bounds.resamples, n, m, levels, type)

Arguments

Value

if type is 'forward' or 'backward', then the corresponding type of confidence interval for each level is returned. The output is in the form of a matrix, with each row corresponding to a level. If type is 'both', then a list is returned. One element of the list is the matrix of backward confidence intervals, and the other element of the list is the matrix of forward confidence intervals.

Description

This function estimates the p-value for the treatment effect under partial identification. p-values corresponding to forward and backward confidence intervals can be returned.

Usage

boundPvalue(bounds, bounds.resamples, n, m, type)

Arguments

Value

If type is 'forward' or 'backward', a scalar p-value corresponding to the type of confidence interval is returned. If type is 'both', a vector of p-values corresponding to the forward and backward confidence intervals is returned.

Description

This function is the splines basis function of order 1. This function was coded in accordance to Carl de Boor's set of notes on splines, "B(asic)-Spline Basics".

Usage

bX(x, knots, i)

Arguments

Value

scalar.

Description

This function ensures that the unobservable term enters into the MTR in the correct manner. That is, it enters as a polynomial.

Usage

checkU(formula, uname)

Arguments

Value

If the unobservable term is entered correctly into the formula, then NULL is returned. Otherwise, the vector of incorrect terms is returned.

Description

Auxiliary function to test if an object is a formula. Warnings are suppressed.

Usage

classFormula(obj)

Arguments

Value

boolean expression.

Description

Auxiliary function to test if an object is a list. Warnings are suppressed.

Usage

classList(obj)

Arguments

Value

boolean expression.

Description

This function simply combines the objects associated with the boundedness constraints and the monotonicity constraints.

Usage

combinemonobound(bdA, monoA)

Arguments

Value

a list containing a unified constraint matrix, unified vector of inequalities, and unified RHS vector for the boundedness and monotonicity constraints of an LP/QCQP problem.

Description

This function constructs another function that returns a constant. It is used for constructing weight/knot functions.

Usage

constructConstant(x)

Arguments

Value

a function.

Description

Given a set of IV-like estimates and the set of matrices/vectors defining an LP problem, this function minimizes the violation of observational equivalence under the L1 norm. The LP model must be passed as an environment variable, under the entry $model. See lpSetup.

Usage

criterionMin(env, sset, solver, solver.options, rescale = FALSE, debug = FALSE)

Arguments

Value

A list including the minimum violation of observational equivalence, the solution to the LP problem, and the status of the solution.

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))

## 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)
## Only the entry $sset is required
sSet <- sSet$sset

## Define additional upper- and lower-bound constraints for the LP
## problem.  The code below imposes a lower bound of 0.2 and upper
## bound of 0.8 on the MTRs.
A <- matrix(0, nrow = 22, ncol = 4)
A <- cbind(A, rbind(cbind(1, seq(0, 1, 0.1)),
                    matrix(0, nrow = 11, ncol = 2)))
A <- cbind(A, rbind(matrix(0, nrow = 11, ncol = 2),
                    cbind(1, seq(0, 1, 0.1))))
sense <- c(rep(">", 11), rep("<", 11))
rhs <- c(rep(0.2, 11), rep(0.8, 11))

## Construct LP object to be interpreted and solved by
## lpSolveAPI. Note that an environment has to be created for the LP
## object. The matrices defining the shape restrictions must be stored
## as a list under the entry \code{$mbobj} in the environment.
modelEnv <- new.env()
modelEnv$mbobj <- list(mbA = A,
                    mbs = sense,
                    mbrhs = rhs)
## Convert the matrices defining the shape constraints into a format
## that is suitable for the LP solver.
lpSetup(env = modelEnv,
        sset = sSet,
        solver = "lpsolveapi")
## Setup LP model so that it will minimize the criterion
lpSetupCriterion(env = modelEnv,
                sset = sSet)
## Declare any LP solver options as a list.
lpOptions <- optionsLpSolveAPI(list(epslevel = "tight"))
## Minimize the criterion.
obseqMin <- criterionMin(env = modelEnv,
                         sset = sSet,
                         solver = "lpsolveapi",
                         solver.options = lpOptions)
obseqMin
cat("The minimum criterion is",  obseqMin$obj, "\n")

Description

This function generates the design matrix given an IV specification.

Usage

design(formula, data, subset, treat, orig.names)

Arguments

Value

Three matrices are returned: one for the outcome variable, Y; one for the second stage covariates, X; and one for the first stage covariates, Z.

Examples

dtm <- ivmte:::gendistMosquito()
design(formula = ey ~ d | z,
           data = dtm,
           subset = z %in% c(1, 2))

Description

Auxiliary function to extract columns from a matrix based on column names.

Usage

extractcols(M, components)

Arguments

Description

This function simply takes a number and formats it for being displayed. Numbers less than 1 in absolute value are rounded to 6 significant figure. Numbers larger than

Usage

fmtResult(x)

Arguments

Value

A scalar.

Description

This function evaluates a single function in a list of functions.

Usage

funEval(fun, values = NULL, argnames = NULL)

Arguments

Value

the output of the function evaluated.

Description

The user can declare that the unobservable enters into the MTRs in the form of splines. This function generates the basis matrix for the splines. The specifications for the spline must be passed as the $splineslist object generated by removeSplines. Note that this function does not account for any interactions between the splines and the covariates. Interactions can be added simply by sweeping the basis matrix by a vector for the values of the covariates.

Usage

genBasisSplines(splines, x, d = NULL)

Arguments

Value

a matrix. The number of rows is equal to the length of x, and the number of columns depends on the specifications of the spline. The name of each column takes the following form: "u[d]S[j].[b]", where "u" and "S" are fixed and stand for "unobservable" and "Splines" respectively. "[d]" will be either 0 or 1, depending on the treatment status. "[j]" will be an integer indicating which element of the list splines the column pertains to. "[b]" will be an integer reflect which component of the basis the column pertains to.

Description

This function generates the component of the constraint matrix in the LP/QCQP problem pertaining to the lower and upper bounds on the MTRs and MTEs. These bounds are declared by the user.

Usage

genboundA(
  A0,
  A1,
  sset,
  gridobj,
  uname,
  m0.lb,
  m0.ub,
  m1.lb,
  m1.ub,
  mte.lb,
  mte.ub,
  solution.m0.min = NULL,
  solution.m1.min = NULL,
  solution.m0.max = NULL,
  solution.m1.max = NULL,
  audit.tol,
  direct = FALSE
)

Arguments

Value

a constraint matrix for the LP/QCQP problem, the associated vector of inequalities, and the RHS vector in the inequality constraint. The objects pertain only to the boundedness constraints declared by the user.

Description

This function generates a data set for testing purposes. There is a single instrument that takes on values of 1 or 2, and the distribution of the values for the binary instrument is uniform. The MTRs are m0 ~ 0 + u and m1 ~ 1 + u. All unobservables u are integrated out.

Usage

gendist1(subN = 5, p1 = 0.4, p2 = 0.6)

Arguments

Value

a data.frame.

Description

This function generates a data set for testing purposes. There is a single instrument that takes on values of 1 or 2, and the distribution of the values for the binary instrument is uniform. The MTRs are m0 ~ 0 + u and m1 ~ 1 + u.

Usage

gendist1e(N = 100, subN = 0.5, p1 = 0.4, p2 = 0.6, v0.sd = 0.5, v1.sd = 0.75)

Arguments

Value

a data.frame.

Description

This function generates a data set for testing purposes. There is a single instrument that takes on values of 1, 2, or 3, and the distribution of the values for the binary instrument is uniform. The MTRs are m0 ~ 1 + u and m1 ~ 1 + u. All unobservables u are integrated out.

Usage

gendist2(subN = 5, p1 = 0.4, p2 = 0.6, p3 = 0.8)

Arguments

Value

a data.frame.

Description

This function generates a data set for testing purposes. There is a single instrument that takes on values of 1 and 2, and the distribution of the values for the binary instrument is uniform. The MTRs are m0 ~ 1 and m1 ~ 1. All unobservables u are integrated out.

Usage

gendist3(subN = 5, p1 = 0.4, p2 = 0.6)

Arguments

Value

a data.frame.

Description

This function generates a data set for testing purposes. There is a single instrument that takes on values of 1 or 2, and the distribution of the values for the binary instrument is uniform. The MTRs are m0 ~ 0 + u and m1 ~ 1 + u.

Usage

gendist3e(N = 100, subN = 0.5, p1 = 0.4, p2 = 0.6, v0.sd = 0.5, v1.sd = 0.75)

Arguments

Value

a data.frame.

Description

This function generates a data set for testing purposes. There is a single instrument that takes on values of 1, 2, and 3, and the distribution of the values for the binary instrument is uniform. The MTRs are m0 ~ 1 and m1 ~ 1. All unobservables u are integrated out.

Usage

gendist4(subN = 5, p1 = 0.4, p2 = 0.6, p3 = 0.8)

Arguments

Value

a data.frame.

Description

This function generates a data set for testing purposes. There is a single instrument that takes on values of 1 or 2, and the distribution of the values for the binary instrument is uniform. The MTRs are both of the form m ~ 1 + x + u.

Usage

gendist5e(N = 100, subN = 0.5, p1 = 0.4, p2 = 0.6, v0.sd = 1, v1.sd = 1.55)

Arguments

Value

a data.frame.

Description

This function generates a data set for testing purposes. There is a single instrument that is uniformly distributed over [0, 1]. The MTRs are both of the form m ~ 1 + x + x:u.

Usage

gendist6e(N = 100, v0.sd = 1, v1.sd = 1.55)

Arguments

Value

a data.frame.

Description

This code generates population level data to test the estimation function. This is a simpler dataset, one in which we can more easily estimate a correctly specified model. The data presented below will have already integrated over the # unobservable terms U, where U | X, Z ~ Unif[0, 1].

Usage

gendistBasic()

Value

a list of two data.frame objects. One is the distribution of the simulated data, the other is the full simulated data set.

Description

This code generates population level data to test the estimation function. This data includes covariates. The data generated will have already integrated over the unobservable terms U, where U | X, Z ~ Unif[0, 1].

Usage

gendistCovariates()

Value

a list of two data.frame objects. One is the distribution of the simulated data, the other is the full simulated data set.

Description

This code generates the population level data in Mogstad, Santos, Torgovitsky (2018), i.e. the mosquito data set used as the running example.

Usage

gendistMosquito()

Value

data.frame.

Description

This code generates population level data to test the estimation function. This data set incorporates splines in the MTRs.

Usage

gendistSplines()

Details

The distribution of the data is as follows

| Z X/Z | 0 1 _______|___________ -1 | 0.1 0.1 | X 0 | 0.2 0.2 | 1 | 0.1 0.2

The data presented below will have already integrated over the unobservable terms U, and U | X, Z ~ Unif[0, 1].

The propensity scores are generated according to the model

p(x, z) = 0.5 - 0.1 * x + 0.2 * z

| Z p(X,Z) | 0 1 _______|___________ -1 | 0.6 0.8 | X 0 | 0.5 0.7 | 1 | 0.4 0.6

The lowest common multiple of the first table is 12. The lowest common multiple of the second table is 84. It turns out that 840 * 5 = 4200 observations is enough to generate the population data set, such that each group has a whole-number of observations.

The MTRs are defined as follows:

y1 ~ beta0 + beta1 * x + uSpline(degree = 2, knots = c(0.3, 0.6), intercept = FALSE)

The coefficients (beta1, beta2), and the coefficients on the splines, will be defined below.

y0 = x : uSpline(degree = 0, knots = c(0.2, 0.5, 0.8), intercept = TRUE) + uSpline(degree = 1, knots = c(0.4), intercept = TRUE) + beta3 * I(u ^ 2)

The coefficient beta3, and the coefficients on the splines, will be defined below.

Value

a list of two data.frame objects. One is the distribution of the simulated data, the other is the full simulated data set.

Description

Auxiliary function to generate standard basis vectors.

Usage

genej(pos, length)

Arguments

Value

Vector containing 1 in a single position, and 0 elsewhere.

Description

This function generates the gamma objects defined in the paper, i.e. each additive term in E[md], where md is a MTR.

Usage

genGamma(
  monomials,
  lb,
  ub,
  multiplier = 1,
  subset = NULL,
  means = TRUE,
  late.rows = NULL
)

Arguments

Value

If means = TRUE, then the function returns a vector of the additive terms in Gamma (i.e. the expectation is over D, X, Z, and u). If means = FALSE, then the function returns a matrix, where each row corresponds to an observation, and each column corresponds to an additive term in E[md | D, X, Z] (i.e. only the integral with respect to u is performed).

Examples

dtm <- ivmte:::gendistMosquito()

## Declare MTR formula
formula0 = ~ 1 + u

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

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

## Generate gamma moments, with S-weight equal to its default value
## of 1
genGamma(monomials = polynomials0,
         lb = 0,
         ub = propensityObj$phat)

Description

The user can declare that the unobservable enters into the MTRs in the form of splines. This function generates the gamma moments for the splines. The specifications for the spline must be passed as an element generated by removeSplines. This function accounts for the interaction between covariates and splines.

Usage

genGammaSplines(
  splinesobj,
  data,
  lb,
  ub,
  multiplier = 1,
  subset,
  d = NULL,
  means = TRUE,
  late.rows = NULL
)

Arguments

Value

a matrix, corresponding to the splines being integrated over the region specified by lb and ub, accounting for the interaction terms. The number of rows is equal to the number of rows in data. The number of columns depends on the specifications of the spline. The name of each column takes the following form: "u[d]S[j].[b]", where "u" and "S" are fixed and stand for "unobservable" and "Splines" respectively. "[d]" will be either 0 or 1, depending on the treatment status. "[j]" will be an integer indicating which element of the list splines the column pertains to. "[b]" will be an integer reflect which component of the basis the column pertains to.

Description

This function generates the Gamma moments for a given set of weights. This funciton is written specifically for tests.

Usage

genGammaSplinesTT(distr, weight, zvars, u1s1, u0s1, u0s2, target = FALSE, ...)

Arguments

Value

vector, the Gamma moments associated with weight.

Description

This function generates the gamma moments from a population level data set. This is specifically constructed to carry out tests.

Usage

genGammaTT(data, s0, s1, lb, ub)

Arguments

Value

list, contains the vectors of the Gamma moments for control and treated observations.

Description

This function takes in a matrix summarizing the support of the covariates, as well as set of points summarizing the support of the unobservable variable. A Cartesian product of the subset of the support of the covariates and the points in the support of the unobservable generates the grid that is used for the audit procedure.

Usage

gengrid(index, xsupport, usupport, uname)

Arguments

Value

a list containing the grid used in the audit; a vector mapping the elements in the support of the covariates to index.

Description

This function generates the matrix and vectors associated with the monotonicity constraints declared by the user. It takes in a grid of the covariates on which the shape constraints are defined, and then calculates the values of the MTR and MTE over the grid. The matrices characterizing the monotonicity conditions can then be obtained by taking first differences over the grid of the unobservable term, within each set of values in the grid of covariate values.

Usage

genmonoA(
  A0,
  A1,
  sset,
  uname,
  gridobj,
  gstar0,
  gstar1,
  m0.dec,
  m0.inc,
  m1.dec,
  m1.inc,
  mte.dec,
  mte.inc,
  solution.m0.min = NULL,
  solution.m1.min = NULL,
  solution.m0.max = NULL,
  solution.m1.max = NULL,
  audit.tol,
  direct
)

Arguments

Value

constraint matrix for the LP/QCQP problem. The matrix pertains only to the monotonicity conditions on the MTR and MTE declared by the user.

Description

This is a wrapper function generating the matrices and vectors associated with the monotonicity and boundedness constraints declared by the user. Since this function generates all the components required for the shape constraints, it is also the function that performs the audit. That is, MTR coefficients are passed, then this function will verify whether they satisfy the shape constraints.

Usage

genmonoboundA(
  pm0,
  pm1,
  support,
  grid_index,
  uvec,
  splinesobj,
  monov,
  uname,
  m0,
  m1,
  sset,
  gstar0,
  gstar1,
  m0.lb,
  m0.ub,
  m1.lb,
  m1.ub,
  mte.lb,
  mte.ub,
  m0.dec,
  m0.inc,
  m1.dec,
  m1.inc,
  mte.dec,
  mte.inc,
  solution.m0.min = NULL,
  solution.m1.min = NULL,
  solution.m0.max = NULL,
  solution.m1.max = NULL,
  audit.tol,
  direct
)

Arguments

Value

a list containing a unified constraint matrix, unified vector of inequalities, and unified RHS vector for the boundedness and monotonicity constraints of an LP/QCQP problem.

Description

This function takes in the IV estimate and its IV-like specification, and generates a list containing the corresponding IV-like point estimate, and the corresponding moments (gammas) that will enter into the constraint matrix of the LP problem. If the option means = FALSE, then the data are not averaged to generate the gamma moments and may be used for GMM. The function requires the user to provide a list (i.e. the list the point estimates and moments corresponding to other IV-like specifications; or an empty list) to append these point estimates and moments to.

Usage

genSSet(
  data,
  sset,
  sest,
  splinesobj,
  pmodobj,
  pm0,
  pm1,
  ncomponents,
  scount,
  subset_index,
  means = TRUE,
  yvar,
  dvar,
  noisy = TRUE,
  ivn = NULL,
  redundant = NULL
)

Arguments

Value

A list containing the point estimate for the IV regression, and the expectation of each monomial term in the MTR.

Examples

dtm <- ivmte:::gendistMosquito()

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

## Declare MTR formulas
formula1 = ~ 1 + u
formula0 = ~ 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))

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

polynomials1 <- polyparse(formula = formula0,
                 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(d),
                          treat = d,
                          list = FALSE)

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

Description

This function estimates the moment of each MTR term under the target weight.

Usage

genTarget(
  treat,
  m0,
  m1,
  target,
  target.weight0,
  target.weight1,
  target.knots0,
  target.knots1,
  late.Z,
  late.from,
  late.to,
  late.X,
  eval.X,
  genlate.lb,
  genlate.ub,
  data,
  splinesobj,
  pmodobj,
  pm0,
  pm1,
  noisy = TRUE
)

Arguments

Value

A list containing either the vectors of gamma moments for D = 0 and D = 1, or a matrix of individual gamma values for D = 0 and D = 1. Additoinally, two vectors are returned. xindex0 and xindex1 list the variables that interact with the unobservable u in m0 and m1. uexporder0 and uexporder1 lists the exponents of the unobservable u in each term it appears in.

Examples

dtm <- ivmte:::gendistMosquito()

## Declare MTR functions
formula1 = ~ 1 + u
formula0 = ~ 1 + u
splinesList = list(removeSplines(formula0), removeSplines(formula1))

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

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

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

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

Description

This function takes in the user-defined target weight functions and the data set, and generates the weight functions for each observation.

Usage

genWeight(fun, fun.name, uname, data)

Arguments

Value

The weight function 'fun', where all arguments other than that of the unobserved variable are fixed according to the vector 'data'.

Description

Auxiliary function that takes in a two-sided formula, and extracts the variable names of either the covariates or instruments. The function returns an error if the formula includes a variable called 'intercept'.

Usage

getXZ(fm, inst = FALSE, terms = FALSE, components = FALSE)

Arguments

Value

vector of variable names.

Description

If the user sets the argument point = TRUE in the function ivmte, then it is assumed that the treatment effect parameter is point identified. The observational equivalence condition is then set up as a two-step GMM problem. Solving this GMM problem recovers the coefficients on the MTR functions m0 and m1. Combining these coefficients with the target gamma moments allows one to estimate the target treatment effect.

Usage

gmmEstimate(
  sset,
  gstar0,
  gstar1,
  center = NULL,
  subsetList = NULL,
  n = NULL,
  redundant = NULL,
  identity = FALSE,
  nMoments,
  splines,
  noisy = TRUE
)

Arguments

Value

a list containing the point estimate of the treatment effects, and the MTR coefficient estimates. The moment conditions evaluated at the solution are also returned, along with the J-test results. However, if the option center is passed, then the moment conditions and J-test are centered (this is to perform the J-test via bootstrap).

Examples

dtm <- ivmte:::gendistMosquito()

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

## Declare MTR formulas
formula1 = ~ 0 + u
formula0 = ~ 0 + 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))

## Construct MTR polynomials
polynomials0 <- polyparse(formula = formula0,
                 data = dtm,
                 uname = u,
                 as.function = FALSE)
polynomials1 <- polyparse(formula = formula0,
                 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 = FALSE)

## Obtain point estimates using GMM
gmmEstimate(sset = sSet$sset,
            gstar0 = targetGamma$gstar0,
            gstar1 = targetGamma$gstar1)

Description

Certain interactions between factor variables and splines should be dropped to avoid collinearity. Albeit collinearity in the MTR specification will not impact the bounds, it can substantially impact how costly it is to carry out the estimation. What this function does is map each spline to a temporary variable. A design matrix is then constructed using these temporary variables in place the splines. If an interaction involving one of the temporary variables is dropped, then one knows to also drop the corresponding interaction with the spline. Note that only interaction terms need to be omitted, so one does not need to worry about the formula contained in removeSplines$formula.

Usage

interactSplines(splinesobj, m0, m1, data, uname)

Arguments

Value

An updated version of splinesobj.

Description

Auxiliary function to check if a string is in fact a command, but in string form.

Usage

isfunctionstring(string)

Arguments

Value

boolean expression.

Description

This function estimates the IV-like estimands, as well as generates the weights associated with the IV-like specifications.

Usage

ivEstimate(
  formula,
  data,
  subset,
  components,
  treat,
  list = FALSE,
  order = NULL
)

Arguments

Value

Returns a list containing the matrices of IV-like specifications for D = 0 and D = 1; and the estimates of the IV-like estimands.

Examples

dtm <- ivmte:::gendistMosquito()
ivEstimate(formula = ey ~ d | z,
           data = dtm,
           components = l(d),
           treat = d,
           list = FALSE)

Description

This function provides a general framework for using the marginal treatment effect (MTE) to extrapolate. The model is the same binary treatment instrumental variable (IV) model considered by Imbens and Angrist (1994) (doi:10.2307/2951620) and Heckman and Vytlacil (2005) (doi:10.1111/j.1468-0262.2005.00594.x). The framework on which this function is based was developed by Mogstad, Santos and Torgovitsky (2018) (doi:10.3982/ECTA15463). See also the recent survey paper on extrapolation in IV models by Mogstad and Torgovitsky (2018) (doi:10.1146/annurev-economics-101617-041813). A detailed description of the module and its features can be found in Shea and Torgovitsky (2021).

Usage

ivmte(
  data,
  target,
  late.from,
  late.to,
  late.X,
  genlate.lb,
  genlate.ub,
  target.weight0 = NULL,
  target.weight1 = NULL,
  target.knots0 = NULL,
  target.knots1 = NULL,
  m0,
  m1,
  uname = u,
  m1.ub,
  m0.ub,
  m1.lb,
  m0.lb,
  mte.ub,
  mte.lb,
  m0.dec,
  m0.inc,
  m1.dec,
  m1.inc,
  mte.dec,
  mte.inc,
  equal.coef,
  ivlike,
  components,
  subset,
  propensity,
  link = "logit",
  treat,
  outcome,
  solver,
  solver.options,
  solver.presolve,
  solver.options.criterion,
  solver.options.bounds,
  lpsolver,
  lpsolver.options,
  lpsolver.presolve,
  lpsolver.options.criterion,
  lpsolver.options.bounds,
  criterion.tol = 1e-04,
  initgrid.nx = 20,
  initgrid.nu = 20,
  audit.nx = 2500,
  audit.nu = 25,
  audit.add = 100,
  audit.max = 25,
  audit.tol,
  rescale,
  point,
  point.eyeweight = FALSE,
  bootstraps = 0,
  bootstraps.m,
  bootstraps.replace = TRUE,
  levels = c(0.99, 0.95, 0.9),
  ci.type = "backward",
  specification.test = TRUE,
  noisy = FALSE,
  smallreturnlist = FALSE,
  debug = FALSE
)

Arguments

Details

When the function is used to estimate bounds, and statistical inference is not performed, the function returns the following objects.

audit.count

the number of audits required until there were no more violations; or the number of audits performed before the audit procedure was terminated.

audit.criterion

the minimum criterion.

audit.grid

a list containing the points used to define the audit grid, as well as a table of points where the shape constraints were violated.

bounds

a vector with the estimated lower and upper bounds of the target treatment effect.

call.options

a list containing all the model specifications and call options generating the results.

gstar

a list containing the estimate of the weighted means for each component in the MTRs. The weights are determined by the target parameter declared in target, or the weights defined by target.weight1, target.knots1, target.weight0, target.knots0.

gstar.coef

a list containing the coefficients on the treated and control group MTRs.

gstar.weights

a list containing the target weights used to estimate gstar.

result

a list containing the LP/QCQP model, and the full output from solving the problem.

solver

the solver used in estimation.

moments

the number of elements in the S-set used to generate achieve (partial) identification.

propensity

the propensity score model. If a variable is fed to the propensity argument when calling ivmte, then the returned object is a list containing the name of variable given by the user, and the values of that variable used in estimation.

s.set

a list of all the coefficient estimates and weights corresponding to each element in the S-set.

splines.dict

a list including the specifications of each spline declared in each MTR.

messages

a vector of character strings logging the output of the estimation procedure.

If bootstraps is greater than 0, then statistical inference will be performed and the output will additionally contain the following objects.

bootstraps

the number of bootstraps.

bootstraps.failed

the number of bootstraps that failed (e.g. due to collinearity) and had to be repeated.

bounds.bootstraps

the estimates of the bounds from every bootstrap draw.

bounds.ci

forward and/or backward confidence intervals for the bound estimates at the levels specified in levels.

bounds.se

bootstrap standard errors on the lower and upper bound estimates.

p.value

p-value for the estimated bounds. p-values are constructed by finding the level at which the confidence interval no longer contains 0.

propensity.ci

confidence interval for coefficient estimates of the propensity score model.

propensity.se

standard errors for the coefficient estimates of the propensity score model.

specification.p.value

p-value from a specification test. The specification test is only performed if the minimum criterion is not 0.

If point = TRUE and bootstraps = 0, then point estimation is performed using two-step GMM. The output will contain the following objects.

j.test

test statistic and results from the asymptotic J-test.

moments

a vector. Each element is the GMM criterion for each moment condition used in estimation.

mtr.coef

coefficient estimates for the MTRs.

point.estimate

point estimate of the treatment effect.

redundant

indexes for the moment conditions (i.e. elements in the S set) that were linearly independent and could be dropped.

If point = TRUE and bootstraps is not 0, then point estimation is performed using two-step GMM, and additional statistical inference is performed using the bootstrap samples. The output will contain the following additional objects.

bootstraps

the number of bootstraps.

bootstraps.failed

the number of bootstraps that failed (e.g. due to collinearity) and had to be repeated.

j.test

test statistic and result from the J-test performed using the bootstrap samples.

j.test.bootstraps

J-test statistic from each bootstrap.

mtr.bootstraps

coefficient estimates for the MTRs from each bootstrap sample. These are used to construct the confidence intervals and standard errors for the MTR coefficients.

mtr.ci

confidence intervals for each MTR coefficient.

mtr.se

standard errors for each MTR coefficient estimate.

p.value

p-value for the treatment effect point estimate estimated using the bootstrap.

point.estimate.bootstraps

treatment effect point estimate from each bootstrap sample. These are used to construct the confidence interval, standard error, and p-value for the treatment effect.

point.estimate.ci

confidence interval for the treatment effect.

point.estimate.se

standard error for the treatment effect estimate.

propensity.ci

confidence interval for the coefficients in the propensity score model, constructed using the bootstrap.

propensity.se

standard errors for the coefficient estimates of the propensity score model.

Value

Returns a list of results from throughout the estimation procedure. This includes all IV-like estimands; the propensity score model; bounds on the treatment effect; the estimated expectations of each term in the MTRs; the components and results of the LP/QCQP problem.

Examples

dtm <- ivmte:::gendistMosquito()

ivlikespecs <- c(ey ~ d | z,
                 ey ~ d | factor(z),
                 ey ~ d,
                 ey ~ d | factor(z))
jvec <- l(d, d, d, d)
svec <- l(, , , z %in% c(2, 4))

ivmte(ivlike = ivlikespecs,
      data = dtm,
      components = jvec,
      propensity = d ~ z,
      subset = svec,
      m0 = ~  u + I(u ^ 2),
      m1 = ~  u + I(u ^ 2),
      uname = u,
      target = "att",
      m0.dec = TRUE,
      m1.dec = TRUE,
      bootstraps = 0,
      solver = "lpSolveAPI")

Description

This function estimates the treatment effect parameters, following the procedure described in Mogstad, Santos and Torgovitsky (2018) (doi:10.3982/ECTA15463). A detailed description of the module and its features can be found in Shea and Torgovitsky (2021). However, this is not the main function of the module. See ivmte for the main function. For examples of how to use the package, see the vignette, which is available on the module's GitHub page.

Usage

ivmteEstimate(
  data,
  target,
  late.Z,
  late.from,
  late.to,
  late.X,
  eval.X,
  genlate.lb,
  genlate.ub,
  target.weight0,
  target.weight1,
  target.knots0 = NULL,
  target.knots1 = NULL,
  m0,
  m1,
  uname = u,
  m1.ub,
  m0.ub,
  m1.lb,
  m0.lb,
  mte.ub,
  mte.lb,
  m0.dec,
  m0.inc,
  m1.dec,
  m1.inc,
  mte.dec,
  mte.inc,
  equal.coef,
  ivlike,
  components,
  subset,
  propensity,
  link = "logit",
  treat,
  solver,
  solver.options,
  solver.presolve,
  solver.options.criterion,
  solver.options.bounds,
  criterion.tol = 0.01,
  initgrid.nx = 20,
  initgrid.nu = 20,
  audit.nx = 2500,
  audit.nu = 25,
  audit.add = 100,
  audit.max = 25,
  audit.tol,
  audit.grid = NULL,
  rescale = TRUE,
  point = FALSE,
  point.eyeweight = FALSE,
  point.center = NULL,
  point.redundant = NULL,
  bootstrap = FALSE,
  count.moments = TRUE,
  orig.sset = NULL,
  orig.criterion = NULL,
  vars_y,
  vars_mtr,
  terms_mtr0,
  terms_mtr1,
  vars_data,
  splinesobj,
  splinesobj.equal,
  noisy = TRUE,
  smallreturnlist = FALSE,
  debug = FALSE,
  environments
)

Arguments

Details

The treatment effects parameters the user can choose from are the ATE, ATT, ATU, LATE, and generalized LATE. The user is required to provide a polynomial expression for the marginal treatment responses (MTR), as well as a set of regressions.

There are two approaches to estimating the treatment effect parameters. The first approach restricts the set of MTR coefficients on each term of the MTRs to be consistent with the regression estimates from the specifications passed through ivlike. The bounds on the treatment effect parameter correspond to finding coefficients on the MTRs that maximize their average difference. If the model is point identified, then GMM is used for estimation. Otherwise, the function solves an LP problem. The second approach restricts the set of MTR coefficients to fit the conditional mean of the outcome variable. If the model is point identified, then constrained least squares is used for estimation. Otherwise, the function solves a QCQP.

The estimation procedure relies on the propensity to take up treatment. The propensity scores can either be estimated as part of the estimation procedure, or the user can specify a variable in the data set already containing the propensity scores.

Constraints on the shape of the MTRs and marginal treatment effects (MTE) can be imposed by the user. Specifically, bounds and monotonicity restrictions are permitted. These constraints are first enforced over a subset of points in the data. An iterative audit procedure is then performed to ensure the constraints hold more generally.

Value

Returns a list of results from throughout the estimation procedure. This includes all IV-like estimands; the propensity score model; bounds on the treatment effect; the estimated expectations of each term in the MTRs; the components and results of the LP/QCQP problem.

Description

ivmte Simulated Data

Usage

ivmteSimData

Format

A data frame with 5,000 rows and 14 columns.

y

binary outcome variable

d

binary treatment variable

z

instrument that takes the value 0, 1, 2, or 3

x

covariate x that takes integer values from 1 to 10

Source

Simulated — see code in data/ivmteSimData.R.

Description

This function allows the user to declare a list of variable names in non-character form and subsetting conditions. This is used to ensure clean entry of arguments into the components and subset arguments of the function. When selecting components to include in the S set, selecting the intercept term and factor variables requires special treatment. To select the intercept term, include in the vector of variable names, ‘intercept’. If the the factorized counterpart of a variable x = 1, 2, 3 is included in the IV-like specifications via factor(x), the user can select the coefficients for specific factors by declaring the components factor(x)-1, factor(x)-2, factor(x)-3.

Usage

l(...)

Arguments

Value

list.

Examples

components <- l(d, x1, intercept, factor(x)-2)
subsets <- l(, z %in% c(2, 4))

Description

If the user passes IV-like moments to the function, then the function constructs the components of the LP problem. If no IV-like moments are passed, then the function constructs the linear constraints of the QCQP problem. Note that the LP/QCQP model will be saved inside an environment variable, which is to be passed through the argument env. This is done for efficient use of memory. The environment env is supposed to already contain a list under the entry $mbobj containing the matrices defining the shape constraints. This list of shape constraints $mbobj should contain three entries corresponding to a system of linear equations of the form Ax <=> b: mbA, the matrix defining the constraints, A; mbs, a vector indicating whether a row in mbA is an equality or inequality constraint (for Gurobi and MOSEK, use '<=', '>=', '='; for CPLEX, use 'L', 'G', and 'E'); mbrhs, a vector of the right hand side values defining the constraint of the form i.e. the vector b. Depending on the linear programming solver used, this function will return different output specific to the solver.

Usage

lpSetup(
  env,
  sset,
  orig.sset = NULL,
  equal.coef0 = NULL,
  equal.coef1 = NULL,
  shape = TRUE,
  direct = FALSE,
  rescale = TRUE,
  solver
)

Arguments

Value

A list of matrices and vectors necessary to define an LP/QCQP problem.

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))

## 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)
## Only the entry $sset is required
sSet <- sSet$sset

## Define additional upper- and lower-bound constraints for the LP
## problem.  The code below imposes a lower bound of 0.2 and upper
## bound of 0.8 on the MTRs.
A <- matrix(0, nrow = 22, ncol = 4)
A <- cbind(A, rbind(cbind(1, seq(0, 1, 0.1)),
                    matrix(0, nrow = 11, ncol = 2)))
A <- cbind(A, rbind(matrix(0, nrow = 11, ncol = 2),
                    cbind(1, seq(0, 1, 0.1))))
sense <- c(rep(">", 11), rep("<", 11))
rhs <- c(rep(0.2, 11), rep(0.8, 11))

## Construct LP object to be interpreted and solved by
## lpSolveAPI. Note that an environment has to be created for the LP
## object. The matrices defining the shape restrictions must be stored
## as a list under the entry \code{$mbobj} in the environment.
modelEnv <- new.env()
modelEnv$mbobj <- list(mbA = A,
                    mbs = sense,
                    mbrhs = rhs)
## Convert the matrices defining the shape constraints into a format
## that is suitable for the LP solver.
lpSetup(env = modelEnv,
        sset = sSet,
        solver = "lpsolveapi")
## Setup LP model so that it is solving for the bounds.
lpSetupBound(env = modelEnv,
             g0 = targetGamma$gstar0,
             g1 = targetGamma$gstar1,
             sset = sSet,
             criterion.tol = 0,
             criterion.min = 0,
             solver = "lpsolveapi")
## Declare any LP solver options as a list.
lpOptions <- optionsLpSolveAPI(list(epslevel = "tight"))
## Obtain the bounds.
bounds <- bound(env = modelEnv,
                sset = sSet,
                solver = "lpsolveapi",
                solver.options = lpOptions)
cat("The bounds are [",  bounds$min, ",", bounds$max, "].\n")

Description

This function sets up the LP model so that the bounds can be obtained. The LP model must be passed as an environment variable, under the entry $model. See lpSetup.

Usage

lpSetupBound(
  env,
  g0,
  g1,
  sset,
  criterion.tol,
  criterion.min,
  solver,
  setup = TRUE
)

Arguments

Value

Nothing, as this modifies an environment variable to save memory.

Description

This function sets up the objective function for minimizing the criterion. The LP model must be passed as an environment variable, under the entry $model. See lpSetup.

Usage

lpSetupCriterion(env, sset)

Arguments

Value

Nothing, as this modifies an environment variable to save memory.

Description

This function re-centers various objects in the LP environment so that a specification test can be performed via the bootstrap. The LP model must be passed as an environment variable, under the entry $model. See lpSetup.

Usage

lpSetupCriterionBoot(
  env,
  sset,
  orig.sset,
  orig.criterion,
  criterion.tol = 0,
  setup = TRUE
)

Arguments

Value

Nothing, as this modifies an environment variable to save memory.

Description

This function generates the linear constraints to ensure that certain MTR coefficients are constant across the treatment and control group.

Usage

lpSetupEqualCoef(equal.coef0, equal.coef1, ANames)

Arguments

Value

A list, containing the matrix of linear equality constraints, a vector of equal signs, and a vector of 0s.

Description

This function separates the shape constraints from the LP environment. That way, the model can be solved without any shape constraints, which is the primary cause of infeasibility. This is done in order to check which shape constraints are causing the model to be infeasible. The LP model must be passed as an environment variable, under the entry $model. See lpSetup.

Usage

lpSetupInfeasible(env, sset)

Arguments

Value

Nothing, as this modifies an environment variable to save memory.

Description

This alters the LP environment so the model will be compatible with specific solvers. The LP model must be passed as an environment variable, under the entry $model. See lpSetup.

Usage

lpSetupSolver(env, solver)

Arguments

Value

Nothing, as this modifies an environment variable to save memory.

Description

This function returns the order of magnitude of a a number.

Usage

magnitude(x)

Arguments

Value

An integer indicating the order of magnitude.

Description

This function converts matrices into triplet form for Mosek. This is required in order to declare quadratic programming problems and second-order cone programming problems.

Usage

matrixTriplets(mat, lower = TRUE)

Arguments

Value

A list containing vectors of row and column indexes, and matrix values.

Description

Function carries out integral for a polynomial of degree 3.

Usage

mInt(ub, lb, coef)

Arguments

Value

scalar.

Description

This function can be used to modify calls in several ways.

Usage

modcall(call, newcall, newargs, keepargs, dropargs)

Arguments

Value

New call object.

Description

This function constructs the matrix to be fed into the GMM estimator to construct the moment conditions.

Usage

momentMatrix(sset, gn0, gn1, subsetList = NULL, n = NULL)

Arguments

Value

matrix whose column means can be used to carry out the GMM estimation.

Description

Analytically integrates monomials and evalates them at a given point. It is assumed that there is no constant multiplying the monomial.

Usage

monoIntegral(u, exp)

Arguments

Value

scalar or vector, depending on what u is.

Description

This function checks whether the user-declared weights for treated and control groups are in fact negations of each other. This is problematic for the GMM procedure when accounting for estimation error of the target weights.

Usage

negationCheck(
  data,
  target.knots0,
  target.knots1,
  target.weight0,
  target.weight1,
  N = 20
)

Arguments

Value

boolean. If the weights are negations of each other, TRUE is returned.

Description

Function generating the S-weights for OLS estimand, with controls.

Usage

olsj(X, X0, X1, components, treat, order = NULL)

Arguments

Value

A list of two vectors: one is the weight for D = 0, the other is the weight for D = 1.

Description

This function constructs a list of options to be parsed when solver is set to cplexapi.

Usage

optionsCplexAPI(options)

Arguments

Value

list, each element being the command to evaluate to implement an option.

Description

This function constructs a string to be parsed when solver is set to cplexapi.

Usage

optionsCplexAPISingle(name, vector)

Arguments

Value

string, the command to be evaluated to implement a single option.

Description

This function parses through the user-submitted CPLEX options to determine what the feasibility tolerance is. This tolerance can then be used for the audit. If the user does not set the CPLEX feasibility tolerance, then a default value of 1e-06 is returned.

Usage

optionsCplexAPITol(options)

Arguments

Value

scalar, the level to set the audit tolerance at.

Description

This function constructs a list of options to be parsed when solver is set to Gurobi. This function really implements some default values, and accounts for the debug option.

Usage

optionsGurobi(options, debug)

Arguments

Value

list, the set of options declared by the user, including some additional default values (if not assigned by the user) and accounting for debug.

Description

This function constructs a list of options to be parsed when solver is set to lpsolveapi. The options permitted are those that can be set via lpSolveAPI::lp.control, and should be passed as a named list (e.g. list(epslevel = "tight")).

Usage

optionsLpSolveAPI(options)

Arguments

Value

string, the command to be evaluated to implement the options.

Description

This function constructs a list of options to be parsed when solver is set to Rmosek. This function really implements the default feasibility tolerances.

Usage

optionsRmosek(options, debug)

Arguments

Value

list, the set of options declared by the user, including some additional default values.

Description

This function takes a vector of terms and places parentheses around boolean expressions.

Usage

parenthBoolean(termsList)

Arguments

Value

character vector.

Description

This function generates every permutation of the elements in a vector.

Usage

permute(vector)

Arguments

Value

a list of all the permutations of vector.

Description

This function generates every permutation of the first n natural numbers.

Usage

permuteN(n)

Arguments

Value

a list of all the permutations of the first n natural numbers.

Description

This function performs TSLS to obtain the estimates for the IV-like estimands.

Usage

piv(
  Y,
  X,
  Z,
  lmcomponents = NULL,
  weights = NULL,
  order = NULL,
  excluded = TRUE
)

Arguments

Value

vector of select coefficient estimates.

Description

This function takes in an MTR formula, and then parses the formula such that it becomes a polynomial in the unobservable u. It then breaks these polynomials into monomials, and then integrates each of them with respect to u. Each integral corresponds to E[md | D, X, Z].

Usage

polyparse(
  formula,
  data,
  uname = "u",
  env = parent.frame(),
  as.function = FALSE
)

Arguments

Value

A list (of lists) of monomials corresponding to the original MTR (for each observation); a list (of lists) of the integrated monomials; a vector for the degree of each of the original monomials in the MTR; and a vector for the names of each variable entering into the MTR (note x^2 + x has only one term, x).

Examples

dtm <- ivmte:::gendistMosquito()

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

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

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

Description

This function takes in two vectors characterizing polynomials. It then returns a vector characterizing the product of the two polynomials.

Usage

polyProduct(poly1, poly2)

Arguments

Value

vector, characterizing the product of the two polynomials characterized poly1 and poly2.

Description

Given a distribution, this function calculates the population mean for each term in a formula.

Usage

popmean(formula, distribution, density = "f")

Arguments

Value

vector, the means for each term in formula.

Description

This function uses the print method on the ivmte return list.

Usage

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

Arguments

Value

basic set of results.

Description

This function estimates the propensity of taking up treatment. The user can choose from fitting a linear probability model, a logit model, or a probit model. The function can also be used to generate a table of propensity scores for a given set of covariates and excluded variables. This was incorporated to account for the LATE being a target parameter. Specifically, if the argument formula is the name of a variable in data, but the target parameter is not the LATE, then no propensity model is returned. If the target parameter is the LATE, then then the propensity model is simply the empirical distribution of propensity scores in the data conditioned on the set of covariates declared in late.X and late.Z.

Usage

propensity(formula, data, link = "logit", late.Z, late.X, env = parent.frame())

Arguments

Value

A vector of propensity scores for each observation, as well as a 'model'. If the user inputs a formula characterizing the model for taking up treatment, then the lm/glm object is returned. If the user declares a variable in the data set to be used as the propensity score, then a data.frame containing the propensity score for each value of the covariates in the probability model is returned.

Examples

dtm <- ivmte:::gendistMosquito()

## Declaring a probability model.
propensity(formula = d ~ z,
               data = dtm,
               link = "linear")

## Declaring a variable to be used instead
propensity(formula = ~ pz,
               data = dtm,
               link = "linear")

Description

This function is only used when the direct MTR regression procedure is used. This function simply constructs the quadratic constraint, and adds it to the LP problem defined by the linear optimization problem for the bounds and the linear shape constraints.

Usage

qpSetup(env, sset, rescale = TRUE)

Arguments

Description

This function is only used when the direct MTR regression procedure is used. This function simply constructs the quadratic constraint, and adds it to the LP problem defined by the linear optimization problem for the bounds and the linear shape constraints.

Usage

qpSetupBound(
  env,
  g0,
  g1,
  criterion.tol,
  criterion.min,
  rescale = FALSE,
  setup = TRUE
)

Arguments

Value

A list of matrices and vectors necessary to define an LP problem for Gurobi or MOSEK.

Description

This function sets up the objective function for minimizing the criterion. The QCQP model must be passed as an environment variable, under the entry $model. See qpSetup.

Usage

qpSetupCriterion(env)

Arguments

Value

Nothing, as this modifies an environment variable to save memory.