ps calculates propensity scores using gradient boosted logistic
regression and diagnoses the resulting propensity scores using a variety of
methods
ps(
formula = formula(data),
data,
n.trees = 10000,
interaction.depth = 3,
shrinkage = 0.01,
bag.fraction = 1,
n.minobsinnode = 10,
perm.test.iters = 0,
print.level = 2,
verbose = TRUE,
estimand = "ATE",
stop.method = c("ks.mean", "es.mean"),
sampw = NULL,
version = "gbm",
ks.exact = NULL,
n.keep = 1,
n.grid = 25,
keep.data = TRUE,
...
)Returns an object of class ps, a list containing
gbm.objThe returned gbm or xgboost object.
treatThe vector of treatment indicators.
treat.varThe treatment variable.
descA list containing balance tables for each method selected in
stop.methods. Includes a component for the unweighted
analysis names “unw”. Each desc component includes
a list with the following components
essThe effective sample size of the control group.
n.treatThe number of subjects in the treatment group.
n.ctrlThe number of subjects in the control group.
max.esThe largest effect size across the covariates.
mean.esThe mean absolute effect size.
max.ksThe largest KS statistic across the covariates.
mean.ksThe average KS statistic across the covariates.
bal.taba (potentially large) table summarizing the quality of the
weights for equalizing the distribution of features across
the two groups. This table is best extracted using the
bal.table method. See the help for bal.table for details
on the table's contents.
n.treesThe estimated optimal number of gradient boosted
iterations to optimize the loss function for the associated
stop.methods.
psa data frame containing the estimated propensity scores. Each
column is associated with one of the methods selected in stop.methods.
wa data frame containing the propensity score weights. Each
column is associated with one of the methods selected in stop.methods.
If sampling weights are given then these are incorporated into these weights.
estimandThe estimand of interest (ATT or ATE).
datestampRecords the date of the analysis.
parametersSaves the ps call.
alertsText containing any warnings accumulated during the estimation.
itersA sequence of iterations used in the GBM fits used by plot function.
balanceThe balance measures for the pretreatment covariates used in plotting, with a column for each
stop.method.
balance.ksThe KS balance measures for the pretreatment covariates used in plotting, with a column for each covariate.
balance.esThe standard differences for the pretreatment covariates used in plotting, with a column for each covariate.
ksThe KS balance measures for the pretreatment covariates on a finer grid, with a column for each covariate.
esThe standard differences for the pretreatment covariates on a finer grid, with a column for each covariate.
n.treesMaximum number of trees considered in GBM fit.
dataData as specified in the data argument.
An object of class formula: a symbolic
description of the propensity score model to be fit with the treatment
indicator on the left side of the formula and the potential confounding
variables on the right side.
A dataset that includes the treatment indicator as well as the potential confounding variables.
Number of gbm iterations passed on to gbm::gbm(). Default: 10000.
A positive integer denoting the tree depth used in gradient boosting. Default: 3.
A numeric value between 0 and 1 denoting the learning rate.
See gbm for more details. Default: 0.01.
A numeric value between 0 and 1 denoting the fraction of
the observations randomly selected in each iteration of the gradient
boosting algorithm to propose the next tree. See gbm for
more details. Default: 1.0.
An integer specifying the minimum number of observations
in the terminal nodes of the trees used in the gradient boosting. See
gbm for
more details. Default: 10.
A non-negative integer giving the number of iterations
of the permutation test for the KS statistic. If perm.test.iters=0
then the function returns an analytic approximation to the p-value. Setting
perm.test.iters=200 will yield precision to within 3% if the true
p-value is 0.05. Use perm.test.iters=500 to be within 2%. Default: 0.
The amount of detail to print to the screen. Default: 2.
If TRUE, lots of information will be printed to monitor the
the progress of the fitting. Default: TRUE.
"ATE" (average treatment effect) or "ATT" (average treatment
effect on the treated) : the causal effect of interest. ATE estimates the
change in the outcome if the treatment were applied to the entire
population versus if the control were applied to the entire population. ATT
estimates the analogous effect, averaging only over the treated population.
Default: "ATE".
A method or methods of measuring and summarizing balance across pretreatment
variables. Current options are ks.mean, ks.max, es.mean, and es.max. ks refers to the
Kolmogorov-Smirnov statistic and es refers to standardized effect size. These are summarized
across the pretreatment variables by either the maximum (.max) or the mean (.mean).
Default: c("ks.mean", "es.mean").
Optional sampling weights.
"gbm", "xgboost", or "legacy", indicating which version of the twang package to use.
"gbm"uses gradient boosting from the gbm package,
"xgboost"uses gradient boosting from the xgboost package, and
"legacy"uses the prior implementation of the ps function.
Default: "gbm".
NULL or a logical indicating whether the
Kolmogorov-Smirnov p-value should be based on an approximation of exact
distribution from an unweighted two-sample Kolmogorov-Smirnov test. If
NULL, the approximation based on the exact distribution is computed
if the product of the effective sample sizes is less than 10,000.
Otherwise, an approximation based on the asymptotic distribution is used.
**Warning:** setting ks.exact = TRUE will add substantial
computation time for larger sample sizes. Default: NULL.
A numeric variable indicating the algorithm should only
consider every n.keep-th iteration of the propensity score model and
optimize balance over this set instead of all iterations. Default: 1.
A numeric variable that sets the grid size for an initial
search of the region most likely to minimize the stop.method. A
value of n.grid=50 uses a 50 point grid from 1:n.trees. It
finds the minimum, say at grid point 35. It then looks for the actual
minimum between grid points 34 and 36. If specified with n.keep>1, n.grid
corresponds to a grid of points on the kept iterations as defined by n.keep. Default: 25.
A logical variable indicating whether or not the data is saved in
the resulting ps object. Default: TRUE.
Additional arguments that are passed to ps function.
For user more comfortable with the options of xgboost::xgboost(),
the options for ps controlling the behavior of the gradient boosting
algorithm can be specified using the xgboost naming
scheme. This includes nrounds, max_depth, eta, and
subsample. In addition, the list of parameters passed to
xgboost can be specified with params.
Note that unlike earlier versions of `twang`, the plotting functions are
no longer included in the ps function. See plot for
details of the plots.
Dan McCaffrey, G. Ridgeway, Andrew Morral (2004). "Propensity Score Estimation with Boosted Regression for Evaluating Adolescent Substance Abuse Treatment", *Psychological Methods* 9(4):403-425.
gbm, xgboost, plot, bal.table