| Title: | Causal Inference using Bayesian Additive Regression Trees |
|---|---|
| Description: | Contains a variety of methods to generate typical causal inference estimates using Bayesian Additive Regression Trees (BART) as the underlying regression model (Hill (2012) <doi:10.1198/jcgs.2010.08162>). |
| Authors: | Vincent Dorie [aut, cre] (ORCID: <https://orcid.org/0000-0002-9576-3064>), Jennifer Hill [aut] (ORCID: <https://orcid.org/0000-0003-4983-2206>) |
| Maintainer: | Vincent Dorie <[email protected]> |
| License: | GPL (>= 2) |
| Version: | 1.1-0 |
| Built: | 2026-11-12 01:38:27 UTC |
| Source: | https://github.com/vdorie/bartcause |
Fits a collection of treatment and response models using the Bayesian Additive Regression Trees (BART) algorithm, producing estimates of treatment effects.
bartc(response, treatment, confounders, parametric, data, subset, weights, weights.rsp, method.rsp = c("bart", "bcf", "tmle", "p.weight"), method.trt = c("bart", "glm", "none"), estimand = c("ate", "att", "atc"), group.by = NULL, commonSup.rule = c("none", "sd", "chisq"), commonSup.cut = c(NA_real_, 1, 0.05), args.rsp = list(), args.trt = list(), p.scoreAsCovariate = TRUE, use.ranef = TRUE, group.effects = FALSE, crossvalidate = FALSE, keepCall = TRUE, verbose = TRUE, seed = NA_integer_, ...)bartc(response, treatment, confounders, parametric, data, subset, weights, weights.rsp, method.rsp = c("bart", "bcf", "tmle", "p.weight"), method.trt = c("bart", "glm", "none"), estimand = c("ate", "att", "atc"), group.by = NULL, commonSup.rule = c("none", "sd", "chisq"), commonSup.cut = c(NA_real_, 1, 0.05), args.rsp = list(), args.trt = list(), p.scoreAsCovariate = TRUE, use.ranef = TRUE, group.effects = FALSE, crossvalidate = FALSE, keepCall = TRUE, verbose = TRUE, seed = NA_integer_, ...)
response |
A vector of the outcome variable, or a reference to such in the |
treatment |
A vector of the binary treatment variable, or a reference to |
confounders |
A matrix or data frame of covariates to be used in estimating the treatment
and response model. Can also be the right-hand-side of a formula (e.g.
|
parametric |
The right-hand-side of a formula (e.g. |
data |
An optional data frame or named list containing the |
subset |
An optional vector using to subset the data. Can refer to |
weights |
An optional vector of population weights - sampling, nonresponse or
target-population weights - giving each row's share of the population the
effects are averaged over. Can refer to |
weights.rsp |
An optional vector of the response model's own weights, its whole weight
vector, read by dbarts as |
method.rsp |
A character string specifying which method to use when fitting the response
surface and estimating the treatment effect. Options are: |
method.trt |
A character string specifying which method to use when fitting the treatment
assignment mechanism, or a vector/matrix of propensity scores. Character
string options are: |
estimand |
A character string specifying which causal effect to target. Options are
|
group.by |
An optional factor that, when present, causes the treatment effect estimate
to be calculated within each group. It is a column of |
commonSup.rule |
Rule for exclusion of observations lacking in common support. Options are
|
commonSup.cut |
Cutoffs for |
p.scoreAsCovariate |
A logical such that when |
use.ranef |
Logical specifying if |
group.effects |
Logical specifying if effects should be calculated within groups if the
|
keepCall |
A logical such that when |
crossvalidate |
One of |
verbose |
A logical that when |
seed |
Optional integer specifying the desired pRNG seed. It should not be needed
when running single-threaded - |
args.rsp, args.trt, ...
|
Further arguments to the treatment and response model fitting algorithms.
Arguments passed to the main function as ... will be used in both models.
|
bartc represents a collection of methods that primarily use the
Bayesian Additive Regression Trees (BART) algorithm to estimate causal
treatment effects with binary treatment variables and continuous or binary
outcomes. This requires models to be fit to the response surface (distribution
of the response as a function of treatment and confounders,
and optionally for treatment assignment mechanism
(probability of receiving treatment, i.e. propensity score,
). The response surface model is used to impute
counterfactuals, which may then be adjusted together with the propensity score
to produce estimates of effects.
Similar to lm, models can be specified symbolically. When the
data term is present, it will be added to the search path for the
response, treatment, and confounders variables. The
confounders must be specified devoid of any "left hand side", as they appear
in both of the models.
Response Surface
The response surface methods included are:
"bart" - use BART to fit the response surface and produce
individual estimates and
. Treatment effect estimates are
obtained by averaging the difference of these across the population of
interest.
"bcf" - use a Bayesian causal forest to fit the response
surface: a prognostic ensemble and a treatment ensemble with their own
priors, combined through per-draw amplitudes, so that the
counterfactual is obtained by swapping the amplitude rather than by
predicting on a flipped treatment. The treatment is masked out of both
forests and the propensity score, when used as a covariate, out of the
treatment forest. Treatment effect estimates are averaged as in
"bart". Missing responses, crossvalidation, parametric,
group.by with use.ranef equal to TRUE, and
predict are all refused for this method; see bcf
for the standalone interface and the reasons.
"p.weight" - individual effects are estimated as in
"bart", but treatment effect estimates are obtained by using a
propensity score weighted average. For the average treatment effect on
the treated, the weights are proportional to the propensity score
, normalized to sum to one within each posterior
draw. For ATC, they are proportional to . When
weights are supplied, each is multiplied by its observation's
population weight before normalizing. The standard error of each draw is in the
units of the response, and summary combines it with the
posterior variance of the estimates. For ATE, "p.weight" is equal to
"bart".
"tmle" - individual effects are estimated as in "bart"
and a weighted average is taken as in "p.weight", however the
response surface estimates and propensity scores are corrected by
using the Targeted Minimum Loss based Estimation method. This uses
the tmle package; without weights, a built-in
implementation stands in, with a warning, when the package is not
installed. With weights, tmle version 2.0.0 or later
is required, and the population weights are passed to it as
obsWeights,
with the library for its own refit of the treatment mechanism
limited to a glm and a gam, since dbarts refuses to weight
the probit BART learner in its default library; weights that are all
equal are not passed, so they give the unweighted fit to rounding.
Treatment Assignment
The treatment assignment models are:
"bart" - fit a binary BART directly to the treatment using all
the confounders.
"none" - no modeling is done. Only applies when using response
method "bart" and p.scoreAsCovariate is FALSE.
"glm" - fit a binomial generalized linear model with logistic
link and confounders included as linear terms.
Finally, a vector or matrix of propensity scores can be supplied. Propensity score matrices should have a number of rows equal to the number of observations in the data and a number of columns equal to the number of posterior samples.
Parametrics
bartc uses the stan4bart package, when available, to fit semi-
parametric surfaces. Equations can be given as to lm. Grouping
structures are also permitted, and use the syntax of lmer.
group.by with use.ranef equal to TRUE is fit the same
way: the grouping factor becomes a (1 | group.by) term added to
whatever parametric equation is supplied, so the two can be given
together. Crossvalidation and missing responses are not available for these
models, and the sampling arguments are translated onto stan4bart's -
see ‘Special Arguments’.
Generics
For a fitted model, the easiest way to analyze the resulting fit is to use the
generics fitted, extract, and
predict to analyze specific quantities and
summary to aggregate those values into
targets (e.g. ATE, ATT, or ATC).
Common Support Rules
Common support, or that the probability of receiving all treatment conditions
is non-zero within every area of the covariate space
( for all in the inferential sample), can be
enforced by excluding observations with high posterior uncertainty.
bartc supports two common support rules through commonSup.rule
argument:
"sd" - observations are cut from the inferential sample if:
,
where is the posteriors standard
deviation of the predicted counterfactual for observation ,
is the posterior standard deviation of the prediction
for the observed treatment condition of observation ,
is the empirical standard deviation
of those quantities, and
for all
in the same treatment group, i.e. . is a constant
to be passed in using commonSup.cut and its default is 1.
"chisq" - observations are cut from the inferential sample if:
,
where are as above and , is the upper
percentile of a distribution with one degree
of freedom, corresponding to a null hypothesis of equal variance. The
default for is 0.05, and it is specified using the
commonSup.cut parameter.
Special Arguments
Some default arguments are unconventional or are passed in a unique fashion.
If n.chains is missing, unlike in bart a default
of 10 is used.
Semiparametric models - a parametric equation, or
group.by with use.ranef equal to TRUE - are fit
by stan4bart, whose sampling arguments carry
different names. The bart spellings are
translated onto them: n.samples and n.burn become
iter - which counts the warmup draws that n.samples
excludes - and warmup, n.chains becomes chains,
n.thin becomes skip, and n.trees, k,
power and base are collected into bart_args.
Arguments given in stan4bart's own names override the
translation.
stan4bart runs its chains in a cluster rather than inside the
sampler, and building one costs about a second, so n.threads
becomes cores only for more than one chain and a fit long
enough to repay it. A clustered fit that was given no seed
receives one drawn from R's generator, so that set.seed
still reproduces it.
power, base and split.probs are passed through
to dbarts, as are the same names given to the cross-validation.
sigdf, sigquant and rngSeed, the spellings of
1.0-10, are still taken and are written for dbarts as the
family and seed that replace them.
Giving one with its replacement, in the call or in the same one of
args.rsp and args.trt, is an error. tree.prior
is not an argument of bartc and is refused. Where
args.rsp or args.trt gives one and the call the
other, the list's entry governs, and seed governs
rngSeed; the argument that does not govern is named in a
warning, as is any other that does not reach a sampler.
For method.rsp == "tmle", a special arg.trt of
posteriorOfTMLE determines if the TMLE correction should be
applied to each posterior sample (TRUE), or just the posterior
mean (FALSE).
Weights
weights are population weights, and the response model is fit
without them: the individual effects are the model's predictions given the
confounders, and the weights say how much of the population each row stands
for. This is sound when the variables the weights were built from are among
the confounders (Gelman, 2007), so put them there: the strata, and the
variables a nonresponse or target-population model used. Where only the
weights are at hand, log(v) can be added to the confounders when the
weights were built from information collected before treatment, never when
they were built from outcomes or from later waves, as attrition weights are:
the model would then predict the outcome from the weights. Clusters of a
sampling design go in group.by, with use.ranef = TRUE. A
response model fit with the weights as precisions remains a call away,
weights = v, weights.rsp = v. Solon, Haider and Wooldridge (2013)
discuss when weighting a regression for causal effects is called for.
Intervals treat the rows as sampled independently; they do not reflect a
design's strata or clusters. Each counterfactual is drawn with its noise as
the response model has it, for precision
weights.rsp and otherwise, and the noise of an average
is , with
a row's share of the population weights and its
response-model weight (1 when unweighted; a count under
"frequency"). No interval depends on the population weights' scale.
summary prints their effective sample size, with a row's
population weight,
, over the
rows averaged; a grouped summary gives each group its own, and its own
share of the weight a common support rule cut.
Rows that are counts of identical units are best written out,
d[rep(seq_len(nrow(d)), d$count), ], which is exact; or give
weights = count, weights.rsp = count with
weights.type = "frequency". Survey weights are not counts: rows of
count c with survey weight v take
weights = c * v, weights.rsp = c, weights.type = "frequency", or are
written out with weights = v.
To average over another sample - a target population with its own weights
tw - fit with keepTrees = TRUE, then
icate <- predict(fit, newdata = target, type = "icate") and
tate <- icate %*% (tw / sum(tw)) give a draw of the target's
conditional average effect for each posterior draw, whose mean and quantiles
are its estimate and interval.
A row with a missing response stays in the average with its weight, its
outcomes predicted by the model; where the weights already adjust for the
missing outcomes, give those rows a weight of 0 or leave them out with
subset; to use rows only in the treatment model, give them an
NA response and a population weight of 0. A common support rule that
cuts rows changes the population the estimate describes; summary reports the share
of the weight cut.
Missing Data
Missingness is allowed only in the response; a row with a missing treatment
is left out with subset. If some response values are
NA, the BART models will be trained just for where data are available
and those values will be used to make predictions for the missing
observations. Missing observations are not used when calculating statistics
for assessing common support, although they may still be excluded on those
grounds. Further, missing observations may not be compatible with response
method "tmle".
Semiparametric response surfaces - a parametric equation, or
group.by with use.ranef equal to TRUE - recover the
counterfactual by flipping the treatment in the fitted model frame, which
holds only the complete cases, so a missing response has no counterfactual to
recover and is refused. Drop the incomplete rows, or pass
use.ranef = FALSE.
bartc returns an object of class bartcFit. Information about the
object can be derived by using methods summary,
plot_sigma, plot_est, plot_indiv,
and plot_support. Numerical quantities are recovered with the
fitted and
extract generics. Predictions for new
observations are obtained with predict.
Objects of class bartcFit are lists containing items:
method.rsp |
character string specifying the method used to fit the response surface |
method.trt |
character string specifying the method used to fit the treatment assignment mechanism |
estimand |
character string specifying the targeted causal effect |
fit.rsp |
object containing the fitted response model |
data.rsp |
|
fit.trt |
object containing the fitted treatment model |
group.by |
optional factor vector containing the groups in which treatment effects are estimated |
est |
matrix or array of posterior samples of the treatment effect estimate |
p.score |
the vector of propensity scores used as a covariate in the response model, when applicable |
samples.p.score |
matrix or array of posterior samples of the propensity score, when applicable; computed when read, see below |
mu.hat.obs |
samples from the posterior of the expected value for individual responses under the observed treatment regime; computed when read, see below |
mu.hat.cf |
samples from the posterior of the expected value for individual responses under the counterfactual treatment; computed when read, see below |
name.trt |
character string giving the name of the treatment
variable in the data of |
name.p.score |
character string giving the name of the propensity
score variable in the data of |
trt |
vector of treatment assignments |
call |
how |
n.chains |
number of independent posterior sampler chains in response model |
commonSup.rule |
common support rule used for suppressing observations |
commonSup.cut |
common support parameter used to set cutoff when suppressing observations |
sd.obs |
vector of standard deviations of individual posterior predictors for observed treatment conditions |
sd.cf |
vector of standard deviations of individual posterior predictors for counterfactuals |
commonSup.sub |
logical vector expressing which observations are used when estimating treatment effects |
use.ranef |
logical for whether ranef models were used; only added when true |
group.effects |
logical for whether group-level estimates are made; only added when true |
seed |
a random seed for use when drawing from the posterior predictive distribution |
weights |
the population weights over the rows modeled, those with
a missing response included, or |
weights.rsp |
the response model's weights over the same rows, or
|
combineChains |
named logical, |
A fit keeps its posterior draws once, in fit.rsp and fit.trt.
mu.hat.obs, mu.hat.cf and samples.p.score are not
stored in the fit: reading one of them, with fit$mu.hat.obs or
fit[["mu.hat.obs"]], computes it from the draws of fit.rsp (or,
for samples.p.score, fit.trt) as bartc always has, at a
cost of a fraction of a second for a fit of ordinary size, and gives the same
array. They do not appear in names(fit), str(fit) or
with(fit, ...), and fit[c("mu.hat.obs", "trt")] does not
return them; every other name and form of indexing reads as it does on a
list. The one exception is a matrix of propensity draws given as
method.trt, which no fit holds: samples.p.score is then stored.
A bartcFit saved by an earlier version holds all three, and reads them
as stored. With method.rsp = "bcf", mu.hat.obs and
mu.hat.cf are those of fit.rsp. A fit saves at about half the
size it had when it also held the three.
Vincent Dorie: [email protected].
Chipman, H., George, E. and McCulloch R. (2010) BART: Bayesian additive regression trees. The Annals of Applied Statistics 4(1), 266–298. The Institute of Mathematical Statistics. doi:10.1214/09-AOAS285.
Hill, J. L. (2011) Bayesian Nonparametric Modeling for Causal Inference. Journal of Computational and Graphical Statistics 20(1), 217–240. Taylor & Francis. doi:10.1198/jcgs.2010.08162.
Hill, J. L. and Su Y. S. (2013) Assessing Lack of Common Support in Causal Inference Using Bayesian Nonparametrics: Implications for Evaluating the Effect of Breastfeeding on Children's Cognitive Outcomes The Annals of Applied Statistics 7(3), 1386–1420. The Institute of Mathematical Statistics. doi:10.1214/13-AOAS630.
Carnegie, N. B. (2019) Comment: Contributions of Model Features to BART Causal Inference Performance Using ACIC 2016 Competition Data Statistical Science 34(1), 90–93. The Institute of Mathematical Statistics. doi:10.1214/18-STS682
Gelman, A. (2007) Struggles with Survey Weighting and Regression Modeling. Statistical Science 22(2), 153–164. The Institute of Mathematical Statistics. doi:10.1214/088342306000000691.
Solon, G., Haider, S. J. and Wooldridge, J. (2013) What Are We Weighting For? NBER Working Paper 18859. National Bureau of Economic Research.
Hahn, P. R., Murray, J. S., and Carvalho, C. M. (2020) Bayesian Regression Tree Models for Causal Inference: Regularization, Confounding, and Heterogeneous Effects (with Discussion). Bayesian Analysis 15(3), 965–1056. International Society for Bayesian Analysis. doi:10.1214/19-BA1195.
## fit a simple linear model n <- 100L beta.z <- c(.75, -0.5, 0.25) beta.y <- c(.5, 1.0, -1.5) sigma <- 2 set.seed(725) x <- matrix(rnorm(3 * n), n, 3) tau <- rgamma(1L, 0.25 * 16 * rgamma(1L, 1 * 32, 32), 16) p.score <- pnorm(x %*% beta.z) z <- rbinom(n, 1, p.score) mu.0 <- x %*% beta.y mu.1 <- x %*% beta.y + tau y <- mu.0 * (1 - z) + mu.1 * z + rnorm(n, 0, sigma) # low parameters only for example fit <- bartc(y, z, x, n.samples = 100L, n.burn = 15L, n.chains = 2L) summary(fit) ## example to show refitting under the common support rule fit2 <- refit(fit, commonSup.rule = "sd") fit3 <- bartc(y, z, x, subset = fit2$commonSup.sub, n.samples = 100L, n.burn = 15L, n.chains = 2L)## fit a simple linear model n <- 100L beta.z <- c(.75, -0.5, 0.25) beta.y <- c(.5, 1.0, -1.5) sigma <- 2 set.seed(725) x <- matrix(rnorm(3 * n), n, 3) tau <- rgamma(1L, 0.25 * 16 * rgamma(1L, 1 * 32, 32), 16) p.score <- pnorm(x %*% beta.z) z <- rbinom(n, 1, p.score) mu.0 <- x %*% beta.y mu.1 <- x %*% beta.y + tau y <- mu.0 * (1 - z) + mu.1 * z + rnorm(n, 0, sigma) # low parameters only for example fit <- bartc(y, z, x, n.samples = 100L, n.burn = 15L, n.chains = 2L) summary(fit) ## example to show refitting under the common support rule fit2 <- refit(fit, commonSup.rule = "sd") fit3 <- bartc(y, z, x, subset = fit2$commonSup.sub, n.samples = 100L, n.burn = 15L, n.chains = 2L)
bartcFit ObjectsVisual exploratory data analysis and model fitting diagnostics for causal inference models fit
using the bartc function.
## S3 method for class 'bartcFit' fitted(object, type = c("pate", "sate", "cate", "mu.obs", "mu.cf", "mu.0", "mu.1", "y.cf", "y.0", "y.1", "icate", "ite", "p.score", "p.weights"), sample = c("inferential", "all"), ...) extract(object, ...) ## S3 method for class 'bartcFit' extract(object, type = c("pate", "sate", "cate", "mu.obs", "mu.cf", "mu.0", "mu.1", "y.cf", "y.0", "y.1", "icate", "ite", "p.score", "p.weights", "sigma"), sample = c("inferential", "all"), combineChains = TRUE, ...) ## S3 method for class 'bartcFit' predict(object, newdata, group.by, type = c("mu", "y", "mu.0", "mu.1", "y.0", "y.1", "icate", "ite", "p.score"), combineChains = TRUE, ...) refit(object, newresp, ...) ## S3 method for class 'bartcFit' refit(object, newresp = NULL, commonSup.rule = c("none", "sd", "chisq"), commonSup.cut = c(NA_real_, 1, 0.05), ...)## S3 method for class 'bartcFit' fitted(object, type = c("pate", "sate", "cate", "mu.obs", "mu.cf", "mu.0", "mu.1", "y.cf", "y.0", "y.1", "icate", "ite", "p.score", "p.weights"), sample = c("inferential", "all"), ...) extract(object, ...) ## S3 method for class 'bartcFit' extract(object, type = c("pate", "sate", "cate", "mu.obs", "mu.cf", "mu.0", "mu.1", "y.cf", "y.0", "y.1", "icate", "ite", "p.score", "p.weights", "sigma"), sample = c("inferential", "all"), combineChains = TRUE, ...) ## S3 method for class 'bartcFit' predict(object, newdata, group.by, type = c("mu", "y", "mu.0", "mu.1", "y.0", "y.1", "icate", "ite", "p.score"), combineChains = TRUE, ...) refit(object, newresp, ...) ## S3 method for class 'bartcFit' refit(object, newresp = NULL, commonSup.rule = c("none", "sd", "chisq"), commonSup.cut = c(NA_real_, 1, 0.05), ...)
object |
Object of class |
type |
Which quantity to return. See details for a description of possible values. |
sample |
Return information for either the |
combineChains |
Results retain the chain structure unless |
newresp |
Not presently used, but provided for compatibility with other definitions of the |
newdata |
Data corresponding to the confounders in a |
group.by |
Optional grouping variable. See definition of |
commonSup.rule, commonSup.cut
|
As in |
... |
Additional parameters passed up the generic method chain. |
fitted returns the values that would serve as predictions for an object returned by the
bartc function, while extract instead returns the full matrix or array of posterior
samples. The possible options are:
"pate", "sate", "cate" - various target quantities, weighted by the population weights
when bartc was given them; see
summary
"mu" - predict only: expected value; requires user-supplied treatment variable in
newdata
"y" - predict only: sample of the response; requires user-supplied treatment variable in
newdata
"mu.obs" - (samples from the posterior of) the expected value under the observed
treatment condition, i.e.
"mu.cf" - the expected value under the counterfactual treatment condition, i.e.
"mu.0" - the expected value under the control condition
"mu.1" - the expected value under the treated condition
"y.cf" - samples of the response under the the counterfactual treatment condition, i.e.
; values are obtained by adding noise to mu.cf
using the posterior predictive distribution, at the noise each observation has
in the response fit ( for precision weights
weights.rsp; missing for an observation of weight 0)
"y.0" - observed responses under the control together with predicted under the treated, i.e.
"y.1" - observed responses under the treatment together with predicted under the control, i.e.
"ite" - (sample) individual treatment effect estimates, i.e.
; uses observed responses and posterior
predicted counterfactuals; for "y.0", "y.1" and "ite", a
missing response is drawn from the posterior predictive distribution
"icate" - individual conditional average treatment effect estimates, i.e.
"p.score" - probability that each observation is assigned to the treatment group
"p.weights" - weights assigned to each individual difference if the response method
is "p.weight", times the population weights when given;
they are normalized to sum to one over
all observations in each draw, and with sample = "all", no
group effects and no observations dropped by a common support rule,
the sum over observations of a weight and its individual effect is
the estimate, up to the bounding of extreme mean responses the
estimator applies, which can matter in small samples. The default
sample = "inferential" returns only the treated ("att")
or control ("atc") observations, so their sum is below one
"sigma" - residual standard deviation from continuous response models
refit exists to allow the same regressions to be used to calculate estimates under different
common support rules. To refit those models on a subset, see the examples in bartc.
predict allows the fitted model to be used to make predictions on an out-of-sample set.
Requires model to be fit with keepTrees equal to TRUE. As ‘y’ values are
all considered out of sample, the posterior predictive distribution is always used when relevant.
For fitted, extract, and predict, a matrix, array, or vector depending on the
dimensions of the result and whether chains are combined. With combineChains = FALSE the chain
dimension comes first and has length one when n.chains is one; with combineChains = TRUE
it is absent.
"pate", "sate", "cate", or "sigma" - with fitted, a scalar; with
extract, n.chains x n.samples (a vector of length n.chains * n.samples
when chains are combined)
"p.score" - depending on the fitting method, samples may or not be present; when samples
are absent, a vector is returned for both functions; when present, the same as "y".
all other types - with fitted, a vector of length equal to the number of
observations (n.obs); with extract or predict, an array of
dimensions n.chains x n.samples x n.obs, or a matrix of
(n.chains * n.samples) x n.obs when chains are combined.
For refit, an object of class bartcFit.
Vincent Dorie: [email protected].
## fit a simple linear model n <- 100L beta.z <- c(.75, -0.5, 0.25) beta.y <- c(.5, 1.0, -1.5) sigma <- 2 set.seed(725) x <- matrix(rnorm(3 * n), n, 3) tau <- rgamma(1L, 0.25 * 16 * rgamma(1L, 1 * 32, 32), 16) p.score <- pnorm(x %*% beta.z) z <- rbinom(n, 1, p.score) mu.0 <- x %*% beta.y mu.1 <- x %*% beta.y + tau y <- mu.0 * (1 - z) + mu.1 * z + rnorm(n, 0, sigma) # low parameters only for example fit <- bartc(y, z, x, n.samples = 100L, n.burn = 15L, n.chains = 2L) # compare fit to linear model lm.fit <- lm(y ~ z + x) plot(fitted(fit, type = "mu.obs"), fitted(lm.fit)) # rank order sample individual treatment effect estimates and plot ites <- extract(fit, type = "ite") ite.m <- apply(ites, 2, mean) ite.sd <- apply(ites, 2, sd) ite.lb <- ite.m - 2 * ite.sd ite.ub <- ite.m + 2 * ite.sd ite.o <- order(ite.m) plot(NULL, type = "n", xlim = c(1, length(ite.m)), ylim = range(ite.lb, ite.ub), xlab = "effect order", ylab = "individual treatment effect") lines(rbind(seq_along(ite.m), seq_along(ite.m), NA), rbind(ite.lb[ite.o], ite.ub[ite.o], NA), lwd = 0.5) points(seq_along(ite.m), ite.m[ite.o], pch = 20)## fit a simple linear model n <- 100L beta.z <- c(.75, -0.5, 0.25) beta.y <- c(.5, 1.0, -1.5) sigma <- 2 set.seed(725) x <- matrix(rnorm(3 * n), n, 3) tau <- rgamma(1L, 0.25 * 16 * rgamma(1L, 1 * 32, 32), 16) p.score <- pnorm(x %*% beta.z) z <- rbinom(n, 1, p.score) mu.0 <- x %*% beta.y mu.1 <- x %*% beta.y + tau y <- mu.0 * (1 - z) + mu.1 * z + rnorm(n, 0, sigma) # low parameters only for example fit <- bartc(y, z, x, n.samples = 100L, n.burn = 15L, n.chains = 2L) # compare fit to linear model lm.fit <- lm(y ~ z + x) plot(fitted(fit, type = "mu.obs"), fitted(lm.fit)) # rank order sample individual treatment effect estimates and plot ites <- extract(fit, type = "ite") ite.m <- apply(ites, 2, mean) ite.sd <- apply(ites, 2, sd) ite.lb <- ite.m - 2 * ite.sd ite.ub <- ite.m + 2 * ite.sd ite.o <- order(ite.m) plot(NULL, type = "n", xlim = c(1, length(ite.m)), ylim = range(ite.lb, ite.ub), xlab = "effect order", ylab = "individual treatment effect") lines(rbind(seq_along(ite.m), seq_along(ite.m), NA), rbind(ite.lb[ite.o], ite.ub[ite.o], NA), lwd = 0.5) points(seq_along(ite.m), ite.m[ite.o], pch = 20)
bartc
Visual exploratory data analysis and model fitting diagnostics for causal inference models fit
using the bartc function.
plot_sigma(x, main = "Traceplot sigma", xlab = "iteration", ylab = "sigma", lty = 1:x$n.chains, ...) plot_est(x, main = paste("Traceplot", x$estimand), xlab = "iteration", ylab = x$estimand, lty = 1:x$n.chains, col = NULL, ...) plot_indiv(x, main = "Histogram Individual Quantities", type = c("icate", "mu.obs", "mu.cf", "mu.0", "mu.1", "y.cf", "y.0", "y.1", "ite"), xlab = "treatment effect", breaks = 20, ...) plot_support(x, main = "Common Support Scatterplot", xvar = "tree.1", yvar = "tree.2", sample = c("inferential", "all"), xlab = NULL, ylab = NULL, pch.trt = 21, bg.trt = "black", pch.ctl = pch.trt, bg.ctl = NA, pch.sup = pch.trt, bg.sup = NA, col.sup = "red", cex.sup = 1.5, legend.x = "topleft", legend.y = NULL, ...)plot_sigma(x, main = "Traceplot sigma", xlab = "iteration", ylab = "sigma", lty = 1:x$n.chains, ...) plot_est(x, main = paste("Traceplot", x$estimand), xlab = "iteration", ylab = x$estimand, lty = 1:x$n.chains, col = NULL, ...) plot_indiv(x, main = "Histogram Individual Quantities", type = c("icate", "mu.obs", "mu.cf", "mu.0", "mu.1", "y.cf", "y.0", "y.1", "ite"), xlab = "treatment effect", breaks = 20, ...) plot_support(x, main = "Common Support Scatterplot", xvar = "tree.1", yvar = "tree.2", sample = c("inferential", "all"), xlab = NULL, ylab = NULL, pch.trt = 21, bg.trt = "black", pch.ctl = pch.trt, bg.ctl = NA, pch.sup = pch.trt, bg.sup = NA, col.sup = "red", cex.sup = 1.5, legend.x = "topleft", legend.y = NULL, ...)
x |
Object of class |
main |
Character title of plot. |
xlab |
Character label of |
ylab |
Character label of |
lty |
For line plots ( |
col |
For line plots, use |
breaks |
Argument to |
type |
The individual quantity to be plotted. See |
xvar |
Variable for use on |
sample |
Return information for either the |
yvar |
Variable for use on the |
pch.trt |
|
bg.trt |
|
pch.ctl |
|
bg.ctl |
|
pch.sup |
|
bg.sup |
|
col.sup |
|
cex.sup |
|
legend.x |
x value passed to |
legend.y |
Optional y value passed to |
... |
Optional graphical parameters. |
Produces various plots using objects fit by bartc. plot_sigma and plot_est
are traditional parameter trace plots that can be used to diagnose the convergence of the posterior
sampler. If the bartc model is fit with n.chains greater than one, by default each chain
will be plotted with its own line type.
plot_indiv produces a simple histogram of the distribution of the estimates of the individual
effects, taken as the average of their posterior samples.
plot_support is used to visualize the common support diagnostic in the form of a scatterplot.
Points that the diagnostic excludes are outlined in red. The contents of the and axes
are controlled by the xvar and yvar arguments respectively and can be of the form:
"tree.XX" - Variable number "XX" as selected by variable importance in predicting
individual treatment effects using a tree fit by rpart. "XX" must be a number
not exceeding the number of continuous variables used to fit the response model.
"pca.XX" - "XX"th principal component axis.
"css" - The common support statistic.
"y" - Observed response variable.
"y0" - Predicted values for the response under the control as obtained by fitted.
"y1" - Predicted values for the response under the treatment fitted.
"indiv.diff" - Individual treatment effect estimates, or .
"p.score" - Propensity score used to fit the response model (if applicable).
"p.weights" - Weights used when taking average of individual differences for response method
"p.weight"; they are normalized to sum to one over all observations in each draw,
see extract for when fewer are shown.
predictor columns - Given by name or number.
supplied vector - Any vector of length equal to the number of observations.
None, although plotting occurs as a side-effect.
Vincent Dorie: [email protected].
# generate fake data using a simple linear model n <- 100L beta.z <- c(.75, -0.5, 0.25) beta.y <- c(.5, 1.0, -1.5) sigma <- 2 set.seed(725) x <- matrix(rnorm(3 * n), n, 3) tau <- rgamma(1L, 0.25 * 16 * rgamma(1L, 1 * 32, 32), 16) p.score <- pnorm(x %*% beta.z) z <- rbinom(n, 1, p.score) mu.0 <- x %*% beta.y mu.1 <- x %*% beta.y + tau y <- mu.0 * (1 - z) + mu.1 * z + rnorm(n, 0, sigma) # run with low parameters only for example fit <- bartc(y, z, x, n.samples = 100L, n.burn = 15L, n.chains = 2L, n.threads = 1L, commonSup.rule = "sd") ## plot specific functions # sigma plot can be used to access convergence of chains plot_sigma(fit) # show points lacking common support plot_support(fit, xvar = "tree.1", yvar = "css", legend.x = NULL) # see example in ?"bartc-generics" for rank-ordered individual effects plot# generate fake data using a simple linear model n <- 100L beta.z <- c(.75, -0.5, 0.25) beta.y <- c(.5, 1.0, -1.5) sigma <- 2 set.seed(725) x <- matrix(rnorm(3 * n), n, 3) tau <- rgamma(1L, 0.25 * 16 * rgamma(1L, 1 * 32, 32), 16) p.score <- pnorm(x %*% beta.z) z <- rbinom(n, 1, p.score) mu.0 <- x %*% beta.y mu.1 <- x %*% beta.y + tau y <- mu.0 * (1 - z) + mu.1 * z + rnorm(n, 0, sigma) # run with low parameters only for example fit <- bartc(y, z, x, n.samples = 100L, n.burn = 15L, n.chains = 2L, n.threads = 1L, commonSup.rule = "sd") ## plot specific functions # sigma plot can be used to access convergence of chains plot_sigma(fit) # show points lacking common support plot_support(fit, xvar = "tree.1", yvar = "css", legend.x = NULL) # see example in ?"bartc-generics" for rank-ordered individual effects plot
Fits a Bayesian causal forest: a prognostic surface and a
treatment surface , each its own ensemble of trees,
combined as
with amplitudes drawn alongside them. Both counterfactual surfaces, both
forests' per-draw fitted values, the amplitudes and each forest's per-draw
variable counts are reported, and no test matrix is involved.
bcf(formula, data, subset, weights, offset, treatment, moderators = NULL, p.score = NULL, n.trees = 200L, base = 0.95, power = 2.0, n.trees.treatment = 50L, treatment.base = 0.25, treatment.power = 3, sd.control = NULL, sd.moderate = NULL, update.a = TRUE, update.b = TRUE, mu.interactions = NULL, tau.interactions = NULL, tau.blocks = NULL, n.samples = 500L, n.burn = 500L, n.chains = 4L, n.threads = min(dbarts::guessNumCores(), n.chains), combineChains = TRUE, keepSampler = FALSE, verbose = TRUE, seed = NA_integer_, ...) ## S3 method for class 'bartBCF' print(x, digits = max(3L, getOption("digits") - 3L), ...) ## S3 method for class 'bartBCF' fitted(object, type = c("mu.obs", "mu.cf", "mu.1", "mu.0", "icate", "mu", "tau", "glue", "sigma", "varcount"), ...) ## S3 method for class 'bartBCF' extract(object, type = c("mu.obs", "mu.cf", "mu.1", "mu.0", "icate", "mu", "tau", "glue", "sigma", "varcount"), forest = NULL, combineChains = object[["combineChains"]], ...) ## S3 method for class 'bartBCF' predict(object, newdata, type = c("mu", "tau"), ...) ## S3 method for class 'bartBCF' residuals(object, ...)bcf(formula, data, subset, weights, offset, treatment, moderators = NULL, p.score = NULL, n.trees = 200L, base = 0.95, power = 2.0, n.trees.treatment = 50L, treatment.base = 0.25, treatment.power = 3, sd.control = NULL, sd.moderate = NULL, update.a = TRUE, update.b = TRUE, mu.interactions = NULL, tau.interactions = NULL, tau.blocks = NULL, n.samples = 500L, n.burn = 500L, n.chains = 4L, n.threads = min(dbarts::guessNumCores(), n.chains), combineChains = TRUE, keepSampler = FALSE, verbose = TRUE, seed = NA_integer_, ...) ## S3 method for class 'bartBCF' print(x, digits = max(3L, getOption("digits") - 3L), ...) ## S3 method for class 'bartBCF' fitted(object, type = c("mu.obs", "mu.cf", "mu.1", "mu.0", "icate", "mu", "tau", "glue", "sigma", "varcount"), ...) ## S3 method for class 'bartBCF' extract(object, type = c("mu.obs", "mu.cf", "mu.1", "mu.0", "icate", "mu", "tau", "glue", "sigma", "varcount"), forest = NULL, combineChains = object[["combineChains"]], ...) ## S3 method for class 'bartBCF' predict(object, newdata, type = c("mu", "tau"), ...) ## S3 method for class 'bartBCF' residuals(object, ...)
formula |
A formula for the response and the confounders, as in
|
data |
A data frame or list in which to look up the formula's variables, or, when
|
subset |
An optional vector of rows to fit. Logical masks, positive and negative integer indices, and character row names are all accepted; the treatment basis is built from the full-length treatment and restricted to the same rows. |
weights |
An optional vector of observation weights. |
offset |
An optional vector added to the linear predictor. It cancels out of the counterfactual difference, so it need not be supplied to obtain one. |
treatment |
A binary treatment variable coded 0 and 1, or a reference to one in
|
moderators |
An optional character vector of design columns the treatment forest may split on. Defaults to every column except the treatment and the propensity score. Naming either of those is an error rather than a silent drop. |
p.score |
An optional propensity score, added to the design as a prognostic-forest-only column. |
n.trees, base, power
|
Number of trees and the tree structure prior for the prognostic forest. |
n.trees.treatment, treatment.base, treatment.power
|
The same, for the treatment forest, whose default prior is shallower. |
sd.control |
Size of the prognostic forest, in the response's units; |
sd.moderate |
Size of the treatment forest, in the response's units; |
update.a, update.b
|
Whether the prognostic and treatment amplitudes are drawn; when
|
mu.interactions, tau.interactions
|
Optional |
tau.blocks |
An optional |
n.samples, n.burn, n.chains, n.threads
|
Posterior samples kept per chain, burn-in iterations discarded, number of chains, and number of threads. |
combineChains |
The default the accessors use: when |
keepSampler |
Whether to keep the |
verbose |
Whether the sampler prints its progress. |
seed |
An optional integer seed for the sampler's own random number generators, making a fit reproducible independently of the number of threads. |
x |
An object of class |
object |
An object of class |
digits |
Number of significant digits to print. |
type |
Which quantity to return; see Details. |
forest |
For |
newdata |
Not presently used; see Details. |
... |
Additional arguments passed to |
A Bayesian causal forest fits two ensembles at once. The prognostic forest
is an ordinary sum of trees; the treatment forest
reaches the model through a basis, the treatment as a two-level factor with one
indicator per arm, so each draw
carries a pair of amplitudes - one per arm - and
the fitted value is
. Swapping
for gives the
counterfactual surface directly, with no test matrix, no out-of-sample
prediction and no second pass through the trees.
The moderator exclusion. The treatment enters the model through the
treatment forest's basis, so both forests are masked out of the treatment
column: a prognostic forest free to split on it would absorb the very effect
the treatment forest exists to estimate. The propensity score, when supplied,
is a prognostic-forest column only and is masked out of the treatment
forest. moderators overrides the treatment forest's split set, but
naming the treatment or the propensity score is refused rather than silently
dropped.
Variable counts are structurally zero under those masks. The treatment forest's counts are zero on the treatment column and on the propensity score column, and the prognostic forest's are zero on the treatment column, in every draw. A zero there is the mask, not a finding about the data.
Binary responses. A 0/1 response fits a probit model (or a logistic
one under family = "logistic"). The two forests are combined on the
latent scale and the link is applied last, to both surfaces, so
"mu.obs" and "mu.cf" are probabilities while "mu",
"tau", "glue" and "icate" remain on the latent scale.
A binary fit has no sigma or first.sigma element at all.
fitted returns posterior means and extract the draws. The types
are:
"mu.obs" - the expected value under the observed treatment
condition
"mu.cf" - the expected value under the counterfactual condition
"mu.0", "mu.1" - the expected values under control and
under treatment
"icate" - the individual conditional average treatment effect,
for the response
scale . On a continuous response this equals
"mu.1" minus "mu.0" exactly; on a binary one it is the
latent-scale contrast.
"mu", "tau" - each forest's own fitted values, on the
internal scale the amplitudes multiply. (Unrelated to the
tau channel of dbarts, which is a
different quantity.)
"glue" - the amplitudes each
draw combines the forests through, named "a", "b.0" and
"b.1": multipliers on the forests, with prior median size 1
for and for where drawn
"sigma" - the residual standard deviation; an error on a binary
fit. n.chains x n.samples when chains are kept apart, a vector when combined
"varcount" - per-forest, per-draw predictor split counts, a
named list unless forest names one
With combineChains = FALSE, extract keeps the chain dimension first
and of length one for a one-chain fit, as dbarts does: per-observation
quantities are n.chains x n.samples x n.obs, "glue" is
n.chains x n.samples x 3, each "varcount" element is
n.chains x n.samples x n.predictors, and "sigma" is
n.chains x n.samples. With combineChains = TRUE no result has a
chain dimension. The fields stored in the fit are not affected.
What a Bayesian causal forest cannot do here. predict is
defined and refuses: out-of-sample and
need per-forest saved-tree replay, which dbarts does not expose, and
the blended test surface they would be combined through is refused by the
sampler at creation. For the same reason a missing response cannot be
recovered, so one is refused rather than dropped. Crossvalidation is refused:
the crossvalidation engine has no multi-forest form. A varying intercept
(group.by with use.ranef = TRUE through bartc) and
semiparametric parametric equations are both fit by stan4bart,
which has no multi-forest form, so they are refused.
Finally, a prognostic-forest blocks partition is refused: a block
partition covers the full design and would have to include the treatment
column the prognostic forest is masked out of. Use tau.blocks.
bcf returns an object of class bartBCF, a list whose posterior
quantities are stored per chain as n.chains x n.samples x n.obs arrays,
losing the leading margin when n.chains is one. Items are:
forests |
named list of length two, |
glue |
the per-draw amplitudes, |
mu.hat.obs, mu.hat.cf
|
the surfaces under the observed and counterfactual treatment conditions |
varcount |
named list of length two, keyed as |
sigma, first.sigma
|
the residual standard deviation for
the kept and the burn-in draws, each an
|
y, trt
|
the training response and treatment |
name.trt, name.p.score
|
the resolved design column names;
|
family |
the resolved response family |
response.scale, response.shift
|
the linear map from the internal scale to the response scale |
data |
the |
n.trees |
tree counts, one per forest, named as |
n.chains, n.samples, n.burn
|
chains run, posterior draws kept per chain, and burn-in iterations discarded |
n.obs |
observations fit, after any |
combineChains |
the value passed to |
call |
the matched call, or the response fitter's when the fit
came from |
fit |
the sampler, only under |
Vincent Dorie: [email protected].
## fit a simple linear model n <- 100L beta.z <- c(.75, -0.5, 0.25) beta.y <- c(.5, 1.0, -1.5) set.seed(725) x <- matrix(rnorm(3 * n), n, 3) tau <- rgamma(1L, 0.25 * 16 * rgamma(1L, 1 * 32, 32), 16) p.score <- as.vector(pnorm(x %*% beta.z)) z <- rbinom(n, 1, p.score) y <- as.vector(x %*% beta.y) + tau * z + rnorm(n, 0, 2) df <- data.frame(y = y, z = z, x1 = x[,1], x2 = x[,2], x3 = x[,3]) # low parameters only for example fit <- bcf(y ~ x1 + x2 + x3, data = df, treatment = z, p.score = p.score, n.samples = 100L, n.burn = 15L, n.chains = 2L, verbose = FALSE) fit # the individual conditional average treatment effects mean(fitted(fit, "icate")) # the treatment forest never splits on the propensity score or the treatment fitted(fit, "varcount")$tau## fit a simple linear model n <- 100L beta.z <- c(.75, -0.5, 0.25) beta.y <- c(.5, 1.0, -1.5) set.seed(725) x <- matrix(rnorm(3 * n), n, 3) tau <- rgamma(1L, 0.25 * 16 * rgamma(1L, 1 * 32, 32), 16) p.score <- as.vector(pnorm(x %*% beta.z)) z <- rbinom(n, 1, p.score) y <- as.vector(x %*% beta.y) + tau * z + rnorm(n, 0, 2) df <- data.frame(y = y, z = z, x1 = x[,1], x2 = x[,2], x3 = x[,3]) # low parameters only for example fit <- bcf(y ~ x1 + x2 + x3, data = df, treatment = z, p.score = p.score, n.samples = 100L, n.burn = 15L, n.chains = 2L, verbose = FALSE) fit # the individual conditional average treatment effects mean(fitted(fit, "icate")) # the treatment forest never splits on the propensity score or the treatment fitted(fit, "varcount")$tau
bartcFit ObjectsSummarizes bartc fits by calculating target quantities and uncertainty estimates.
## S3 method for class 'bartcFit' summary(object, target = c("pate", "sate", "cate"), ci.style = c("norm", "quant", "hpd"), ci.level = 0.95, pate.style = c("ppd", "var.exp"), ...)## S3 method for class 'bartcFit' summary(object, target = c("pate", "sate", "cate"), ci.style = c("norm", "quant", "hpd"), ci.level = 0.95, pate.style = c("ppd", "var.exp"), ...)
object |
Object of class |
target |
Treatment effect to calculate. One of |
ci.style |
Means of calculating confidence intervals (posterior credible regions). Options include
|
ci.level |
Level of confidence for intervals. |
pate.style |
For target |
... |
Not used at moment, but present to match |
summary produces a numeric and qualitative summary of a bartc fit.
Target Types
The SATE and PATE involve calculating predicted response values under different treatment conditions.
When using extract or fitted, these values are simulated directly
from the posterior predictive distribution. However, since these quantities all have the same expected
value, in order to provide consistent results summary only uses those simulations to derive
credible intervals. Thus the estimates for CATE, SATE, and PATE all should be reported as the same
but with increasing degrees of uncertainty.
Weights
With population weights (weights in bartc), every average is weighted: each
observation counts by its share of the weights over the observations averaged, so results do not
depend on the weights' scale. The SATE and PATE uncertainty includes the response noise of that
weighted average, , with an observation's share and
its weight in the response fit (1 for an unweighted fit, a count under
weights.type = "frequency"); an observation with a missing response adds its term once more
to the SATE. Observations are treated as independent. The printed summary gives the Kish effective
sample size of the population weights , over the
observations averaged. In a grouped summary the table of estimates has an n.eff column beside
n, each group's own figure over its observations averaged and the total row's the whole
figure; a group of no weight is NA.
Grouped Data
If a model is fit with a supplied grouping variable and group.effects = TRUE, the estimates
will also be reported within groups. When possible, the last line corresponds to the population. Within
group estimates for resposne methods such as "tmle" cannot easily be extrapolated to the
population at large - the means will combine based on the sample sizes, or on the shares of the
population weights, but the uncertainty estimates
will lack correlations. A group's n counts the observations its estimate averages over, those
of the estimand that a common support rule kept.
An object of class bartcFit.summary equivalent to a list with named items:
call |
how |
method.rsp |
character string specifying the method used to fit the response surface |
method.trt |
character string specifying the method used to fit the treatment assignment mechanism |
ci.info |
a named list with items |
n.obs |
total number of observations |
n.samples |
number of samples within any one chain |
n.chains |
total number of chains |
commonSup.rule |
common support rule used when fitting object to produce estimates |
estimates |
a |
n.cut |
under a common support rule, a |
weight.cut |
with population weights and a common support rule, the share of the population weight of the observations the estimand averages over that the rule removed |
n.eff |
with population weights, the Kish effective sample size of the weights over the observations averaged; absent otherwise |
Vincent Dorie: [email protected].