DynTxRegime (version 3.01)

earl:

Description

Estimation of optimal treatment regime using efficient augmentation and relaxation learning (EARL). The method is limited to single-decision-point scenarios with binary treatment options.

Usage

earl(..., moPropen, moMain, moCont, data, response, txName, regime,
     iter = 0L, lambdas = 0.5, cvFolds = 0L, surrogate = "hinge",
     guess = NULL, verbose = TRUE)

Arguments

…

ignored. Included to require named input.

moPropen

An object of class "modelObj." This object specifies the model of the propensity score regression and the R methods to be used to obtain parameter estimates and predictions. The method specified to obtain predictions must return the prediction on the scale of the probability, i.e., returned values must be in the interval (0,1). See moPropen for further information.

moMain

An object of class "modelObj" or NULL. If a "modelObj," this input specifies the model of the main effects component of the outcome regression and the R methods to be used to obtain parameter estimates and predictions. The method specified to obtain predictions must return the prediction on the scale of the response variable.

moCont

An object of class "modelObj" or NULL. If a "modelObj," this input specifies the model of the contrasts component of the outcome regression and the R methods to be used to obtain parameter estimates and predictions. The method specified to obtain predictions must return the prediction on the scale of the response variable.

data

An object of class "data.frame." The covariates and treatment history.

response

An object of class "vector." The outcome of interest.

txName

An object of class "character." The column header of the stage treatment variable as given in input data. Not that treatment must be binary and will be recoded as -1/+1 if not provided as such.

regime

An object of class "formula." A formula defining the decision rule.

iter

An object of class "integer." If >0, the iterative method will be used to obtain parameter estimates in the outcome regression step. See iter for further information.

lambdas

An object of class "numeric." The tuning parameter to avoid overfitting. If a vector of values is given and cvFolds > 0, cross-validation will be used to select an optimal value from among those provided.

cvFolds

An object of class "integer." If cross-validation is to be used to find an optimal lambda parameter, the number of folds to use in the cross-validation procedure.

surrogate

An object of class "character." Specification of the surrogate for the 0-1 loss function. Must be one of {'hinge', 'logit', 'exp', 'sqhinge'} indicating the hinge, logistic, exponential, and squared-hinge functions, respectively

guess

An object of class "numeric" or NULL. Starting parameter values for optimization method.

verbose

An object of class "logical." If FALSE, screen prints will be suppressed.

Value

Returns an object of class "EARL" that inherits directly from class "DynTxRegime."

Methods

coef

signature(object = "EARL"): Retrieve parameter estimates for all regression steps.

cvInfo

signature(object = "EARL"): Retrieve cross-validation results.

DTRstep

signature(object = "EARL"): Retrieve description of method used to create object.

estimator

signature(x = "EARL"): Retrieve the estimated value of the estimated optimal regime for the training data set.

fitObject

signature(object = "EARL"): Retrieve value object returned by regression methods.

optimObj

signature(object = "EARL"): Retrieve value object returned by optimization routine.

optTx

signature(x = "EARL", newdata = "missing"): Retrieve the estimated optimal treatment regime for training data set.

optTx

signature(x = "EARL", newdata = "data.frame"): Estimate the optimal treatment regime for newdata.

outcome

signature(x = "EARL"): Retrieve value object returned by outcome regression methods.

plot

signature(x = "EARL"): Generate plots for regression analyses.

print

signature(object = "EARL"): Print main results of analysis.

propen

signature(x = "EARL"): Retrieve value object returned by propensity score regression methods.

regimeCoef

signature(object = "EARL"): Retrieve the estimated decision function parameter estimates.

show

signature(object = "EARL"): Show main results of analysis.

summary

signature(object = "EARL"): Retrieve summary information from regression analyses.

Details

The inverse propensity weighted estimator is calculated if both moMain and moCont are NULL; otherwise the augmented inverse propensity weighted estimator is calculated.

References

Zhao, Y-Q., Laber, E. B., Saha, S., and Sands, B. E. (2017+). Efficient Augmentation and Relaxation Learning for Treatment Regimes Using Observational Data. in press.

Examples

# Load and process data set
  data(bmiData)

  # define response y to be the negative 12 month
  # change in BMI from baseline
  bmiData$y <- -100*(bmiData[,6] - bmiData[,4])/bmiData[,4]

  bmiData$y <- bmiData$y - min(bmiData$y) + 0.001

# Constant propensity model
  moPropen <- buildModelObj(model = ~1,
                            solver.method = 'glm',
                            solver.args = list('family'='binomial'),
                            predict.method = 'predict.glm',
                            predict.args = list(type='response'))

# IPWE
  earlRes <- earl(moPropen = moPropen, moMain = NULL, moCont = NULL,
                  data = bmiData, response = bmiData$y, txName = "A2", 
                  regime = ~ parentBMI + month4BMI)

#Available methods

# Coefficients of the propensity score regression
coef(earlRes)

# Description of method used to obtain object
DTRstep(earlRes)

# Estimated value of the optimal treatment regime for training set
estimator(earlRes)

# Value object returned by propensity score regression method
fitObject(earlRes)

# Summary of optimization routine
optimObj(earlRes)

# Estimated optimal treatment for training data
optTx(earlRes)

# Estimated optimal treatment for new data
optTx(earlRes, bmiData)

# Plots if defined by propensity regression method
dev.new()
par(mfrow = c(2,4))

plot(earlRes, suppress = FALSE)
plot(earlRes, suppress = TRUE)

# Value object returned by propensity score regression method
propen(earlRes)

# Parameter estimates for decision function
regimeCoef(earlRes)

# Show main results of method
show(earlRes)

# Show summary results of method
summary(earlRes)
 


# Augmented IPWE
  # Create modeling object for main effect component
  moMain <- buildModelObj(model = ~ gender + parentBMI + month4BMI,
                          solver.method='lm')

  # Create modeling object for contrast component
  moCont <- buildModelObj(model = ~ parentBMI + month4BMI,
                          solver.method='lm')

  earlResA <- earl(moPropen = moPropen, moMain = moMain, moCont = moCont,
                   data = bmiData, response = bmiData$y, txName = "A2", 
                   regime = ~ parentBMI + month4BMI)

#Available methods

# Coefficients of the propensity score and outcome regressions
coef(earlResA)

# Description of method used to obtain object
DTRstep(earlResA)

# Estimated value of the optimal treatment regime for training set
estimator(earlResA)

# Value object returned by propensity score and outcome regression methods
fitObject(earlResA)

# Summary of optimization routine
optimObj(earlResA)

# Estimated optimal treatment for training data
optTx(earlResA)

# Estimated optimal treatment for new data
optTx(earlResA, bmiData)

# Value object returned by outcome regression method
outcome(earlResA)

# Plots if defined by propensity score and outcome regressionmethod
dev.new()
par(mfrow = c(2,4))
plot(earlResA, suppress = FALSE)

dev.new()
par(mfrow = c(2,4))
plot(earlResA, suppress = TRUE)

# Value object returned by propensity score regression method
propen(earlResA)

# Parameter estimates for decision function
regimeCoef(earlResA)

# Show main results of method
show(earlResA)

# Show summary results of method
summary(earlResA)