Package 'bartCause'

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

Help Index


Causal Inference using Bayesian Additive Regression Trees

Description

Fits a collection of treatment and response models using the Bayesian Additive Regression Trees (BART) algorithm, producing estimates of treatment effects.

Usage

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_,
      ...)

Arguments

response

A vector of the outcome variable, or a reference to such in the data argument. Can be continuous or binary.

treatment

A vector of the binary treatment variable, or a reference to data. It is 0 and 1, or logical, or a factor of two levels, the second level being the treated group, as glm reads a factor response. A character vector is refused, since which of its values is treated is not stated, and sorting would choose by locale; the error writes the factor call from the values, e.g. factor(arm, levels = c("placebo", "drug")) with the untreated value first. A treatment that is not binary, or is missing for a row subset keeps, is refused on every method.trt, including given propensity scores.

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. x1 + x2 + ...). The data argument will be searched if supplied.

parametric

The right-hand-side of a formula (e.g. x1 + x2 + (1 | g) ...) giving the equation of a parametric form to be used for estimating the mean structure. See the details section below.

data

An optional data frame or named list containing the response, treatment, and confounders. It is passed by name, as in data = d: the fourth argument of bartc is parametric.

subset

An optional vector using to subset the data. Can refer to data if provided.

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 data if provided, and is cut to subset; values must be finite and non-negative, with at least one positive, and the estimand must have weight: bartc refuses, before it fits anything, an effect on the treated whose treated rows all have weight 0, and likewise for the controls, and a common support rule that leaves none refuses at the end of the fit. A group of a grouped fit with no weight gets NA. They weight every average of the individual effects: the ATE, ATT and ATC, as "pate", "sate" and "cate" in fitted, extract and summary, within groups and in their total, and in the "p.weight" and "tmle" estimators. Their scale does not matter. The response model is fit without them (see weights.rsp and ‘Weights’ below). A "glm" treatment model is fit with them, rescaled to mean 1; a BART treatment model is fit without them, a probit having no weighted form. They are not propensity-score weights: bartc adjusts for confounding itself, and weights from a propensity model would change the population the estimate describes.

weights.rsp

An optional vector of the response model's own weights, its whole weight vector, read by dbarts as weights.type says: "precision", the default for a continuous response, a row of weight ww having noise variance σ2/w\sigma^2 / w, as a row that is the mean of ww units has; or "frequency", a row standing for ww identical observations. Missing or NULL, the response model is unweighted. No average reads them. weights.type is given through ... or args.rsp and is refused without weights.rsp; "frequency" is refused for models fit by stan4bart, which reads weights as precisions only. A 0/1 response (numeric, logical, or a factor of two levels) takes weights of 0 or 1 only; counts of identical rows are written out as repeated rows, or fit with family = "logistic" and weights.type = "frequency". A row of weight 0 is out of the response fit, which gives a continuous response no noise scale for it, so it must have a population weight of 0; bartc refuses it before fitting when no family is given and the response is not 0/1, or when family plainly says gaussian (the string, a family object, or a call of gaussian), and after the fits for any other family. Can refer to data if provided.

method.rsp

A character string specifying which method to use when fitting the response surface and estimating the treatment effect. Options are: "bart" - fit the response surface with BART and take the average of the individual treatment effect estimates, "bcf" - fit the response surface with a Bayesian causal forest, a separate prognostic and treatment ensemble, and average as for "bart", "p.weight" - fit the response surface with BART but compute the treatment effect estimate by using a propensity score weighted sum of individual effects, and "tmle" - as above, but further adjust the individual estimates using the Targeted Minimum Loss based Estimation (TMLE) adjustment.

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: "bart" - fit BART directly to the treatment variable, "glm" - fit a generalized linear model with a binomial response and all confounders added linearly, and "none" - do no propensity score estimation. Cannot be "none" if the response model requires propensity scores. When supplied as a matrix, it should be of dimensions equal to the number of observations times the number of samples used in any response model.

estimand

A character string specifying which causal effect to target. Options are "ate" - average treatment effect, "att" - average treatment effect on the treated, and "atc" - average treatment effect on the controls.

group.by

An optional factor that, when present, causes the treatment effect estimate to be calculated within each group. It is a column of data given by its bare name, as in group.by = country, or an expression of the columns and of variables in the calling frame, such as as.factor(country) or dat[[name]], that has one value for each row; a string naming a column is refused.

commonSup.rule

Rule for exclusion of observations lacking in common support. Options are "none" - no suppression, "sd" - exclude units whose predicted counterfactual standard deviation is extreme compared to the maximum standard deviation under those units' observed treatment condition, where extreme refers to the distribution of all standard deviations of observed treatment conditions, "chisq" - exclude observations according to ratio of the variance of posterior predicted counterfactual to the posterior variance of the observed condition, having a Chi Squared distribution with one degree of freedom under the null hypothesis of have equal distributions.

commonSup.cut

Cutoffs for commonSup.rule. Ignored for "none", when commonSup.rule is "sd", refers to how many standard deviations of the distribution of posterior variance for counterfactuals an observation can be above the maximum of posterior variances for that treatment condition. When commonSup.rule is "chisq", is the pp value used for rejection of the hypothesis of equal variances.

p.scoreAsCovariate

A logical such that when TRUE, the propensity score is added to the response model as a covariate. When used, this is equivalent to the 'ps-BART' method described by described by Hahn, Murray, and Carvalho.

use.ranef

Logical specifying if group.by variable - when present - should be included as a "random" or "fixed" effect. If true, the grouping factor enters the model as a varying intercept, which for BART models requires the stan4bart package and for treatment assignment mechanisms of type "glm" requires the lme4 package. If false, it enters as another predictor and no additional package is needed.

group.effects

Logical specifying if effects should be calculated within groups if the group.by variable is provided. Response methods of "tmle" and "p.weight" are such that if group effects are calculated, then the population effect is not provided.

keepCall

A logical such that when FALSE, the call to bartc is not kept. This can reduce the amount of information printed by summary when passing in data as literals.

crossvalidate

One of TRUE, FALSE, "trt", or "rsp". Enables code to attempt to estimate the optimal leaf sensitivity parameter. This uses a rudimentary Bayesian optimization routine and can be extremely slow. Refused for semiparametric models - a parametric equation, or group.by with use.ranef equal to TRUE - and for method.rsp = "bcf".

verbose

A logical that when TRUE prints information as the model is fit.

seed

Optional integer specifying the desired pRNG seed. It should not be needed when running single-threaded - set.seed will suffice, and can be used to obtain reproducible results when multi-threaded. See the Reproducibility section of bartBT.

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. args.rsp and args.trt can be used to set parameters in a single fit, and will override other values. Each is a named list, written out in the call or held in a variable or an expression that evaluates to one. See glm and bart for reference. Semiparametric models are fit by stan4bart, which names its sampling arguments differently; the bart spellings are translated for them, as described under ‘Special Arguments’. A forest constraint for method.rsp = "bcf" - mu.interactions, tau.interactions, or tau.blocks - reaching dbarts through ..., args.rsp or args.trt is evaluated before dbarts sees it, so it must be built beforehand with dbarts::dbartsForests$interactions(...) (or $blocks), not written as a bare call; see bcf.

Details

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, p(Y(1),Y(0)∣X)p(Y(1), Y(0) | X) and optionally for treatment assignment mechanism (probability of receiving treatment, i.e. propensity score, Pr(Z=1∣X)Pr(Z = 1 | X)). 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 Y^(1)i\hat{Y}(1)_i and Y^(0)i\hat{Y}(0)_i. 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 p(zi∣xi)p(z_i | x_i), normalized to sum to one within each posterior draw. For ATC, they are proportional to 1−p(zi∣xi)1 - p(z_i | x_i). 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 (P(Z=1∣X=x)>0P(Z = 1 | X = x) > 0 for all xx 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: sif(1−z)>mz+a×sd(sjf(z)s_i^{f(1-z)} > m_z + a \times sd(s_j^{f(z)}, where sif(1−z)s_i^{f(1-z)} is the posteriors standard deviation of the predicted counterfactual for observation ii, sjf(z)s_j^f(z) is the posterior standard deviation of the prediction for the observed treatment condition of observation jj, sd(sjf(z)sd(s_j^{f(z)} is the empirical standard deviation of those quantities, and mz=maxj{sjf(z)}m_z = max_j \{s_j^{f(z)}\} for all jj in the same treatment group, i.e. Zj=zZ_j = z. aa is a constant to be passed in using commonSup.cut and its default is 1.

  • "chisq" - observations are cut from the inferential sample if: (sif(1−z)/sif(z))2>qα(s_i^{f(1-z)} / s_i^{f(z)})^2 > q_\alpha, where sis_i are as above and qαq_\alpha, is the upper α\alpha percentile of a χ2\chi^2 distribution with one degree of freedom, corresponding to a null hypothesis of equal variance. The default for α\alpha 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, σ/wi\sigma / \sqrt{w_i} for precision weights.rsp and σ\sigma otherwise, and the noise of an average is σ2∑iai2/wi\sigma^2 \sum_i a_i^2 / w_i, with aia_i a row's share of the population weights and wiw_i 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 viv_i a row's population weight, (∑ivi)2/∑ivi2(\sum_i v_i)^2 / \sum_i v_i^2, 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.

Value

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

dbartsData object used when fitting the response model

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 fit.rsp

name.p.score

character string giving the name of the propensity score variable in the data of fit.rsp, or NULL when the response model has no propensity score column

trt

vector of treatment assignments

call

how bartc was called

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 NULL

weights.rsp

the response model's weights over the same rows, or NULL

combineChains

named logical, rsp and trt, for whether the chains of each model's draws were combined into one margin, which is how the computed items below are laid out

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.

Author(s)

Vincent Dorie: [email protected].

References

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.

See Also

bart

Examples

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

Generic Methods for bartcFit Objects

Description

Visual exploratory data analysis and model fitting diagnostics for causal inference models fit using the bartc function.

Usage

## 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),
      ...)

Arguments

object

Object of class bartcFit.

type

Which quantity to return. See details for a description of possible values.

sample

Return information for either the "inferential" (e.g. treated observations when the estimand is att) or "all" observations.

combineChains

Results retain the chain structure unless combineChains is TRUE. The chain dimension comes first and is kept when there is only one chain, as it is by dbarts and stan4bart: a scalar quantity (e.g. "pate", "sigma") is then a chains by samples matrix, and a per-observation quantity (e.g. "icate", "mu.obs") a chains by samples by observations array. Fields stored in the fit object are not affected.

newresp

Not presently used, but provided for compatibility with other definitions of the refit generic.

newdata

Data corresponding to the confounders in a bartc fit.

group.by

Optional grouping variable. See definition of group.by in bartc.

commonSup.rule, commonSup.cut

As in bartc.

...

Additional parameters passed up the generic method chain.

Details

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^i(1)∗zi+mu^i(0)∗(1−zi)\hat{mu}_i(1) * z_i + \hat{mu}_i(0) * (1 - z_i)

  • "mu.cf" - the expected value under the counterfactual treatment condition, i.e. mu^i(1)∗(1−zi)+mu^i(0)∗zi)\hat{mu}_i(1) * (1 - z_i) + \hat{mu}_i(0) * z_i)

  • "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. y^i(1−zi))\hat{y}_i(1 - z_i)); values are obtained by adding noise to mu.cf using the posterior predictive distribution, at the noise each observation has in the response fit (σ/wi\sigma / \sqrt{w_i} 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^i(1)∗zi+y(0)∗(1−zi)\hat{y}_i(1) * z_i + y(0) * (1 - z_i)

  • "y.1" - observed responses under the treatment together with predicted under the control, i.e. yi(1)∗zi+y^(0)∗(1−zi)y_i(1) * z_i + \hat{y}(0) * (1 - z_i)

  • "ite" - (sample) individual treatment effect estimates, i.e. (yi(zi)−yi(1−zi))∗(2zi−1)(y_i(z_i) - y_i(1 - z_i)) * (2z_i - 1); 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. mu^i(1)−mu^i(0)\hat{mu}_i(1) - \hat{mu}_i(0)

  • "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.

Value

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.

Author(s)

Vincent Dorie: [email protected].

See Also

bartc

Examples

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

Plot methods for bartc

Description

Visual exploratory data analysis and model fitting diagnostics for causal inference models fit using the bartc function.

Usage

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

Arguments

x

Object of class bartcFit.

main

Character title of plot.

xlab

Character label of xx axis. For plot_support, if NULL a default will be used.

ylab

Character label of yy axis. For plot_support, if NULL a default will be used.

lty

For line plots (plot_sigma, plot_est), models use the values of lty to visually distinguish each chain.

col

For line plots, use col vector to distinguish between groups (if any).

breaks

Argument to hist.

type

The individual quantity to be plotted. See fitted.

xvar

Variable for use on xx axis. Can be one of "tree.XX", "pca.XX", "css", any individual level quantity accepted by fitted, the number or name of a column used to fit the response model, or a given vector. See below for details.

sample

Return information for either the "inferential" (e.g. treated observations when the estimand is att) or "all" observations.

yvar

Variable for use on the yy axis, of the same form as xvar.

pch.trt

pch point value used when plotting treatment observations.

bg.trt

bg background value used when plotting treatment observations.

pch.ctl

pch point value used when plotting control observations.

bg.ctl

bg background value used when plotting treatment observations.

pch.sup

pch point value used when plotting suppressed observations.

bg.sup

bg background value used when plotting suppressed observations.

col.sup

col color value used when plotting suppressed observations.

cex.sup

cex size value used when plotting suppressed observations.

legend.x

x value passed to legend. If NULL, legend plotting is skipped.

legend.y

Optional y value passed to legend

...

Optional graphical parameters.

Details

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 xx and yy 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 y^(1)−y^(0)\hat{y}(1) - \hat{y}(0).

  • "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.

Value

None, although plotting occurs as a side-effect.

Author(s)

Vincent Dorie: [email protected].

See Also

bartc

Examples

# 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

Bayesian Causal Forests

Description

Fits a Bayesian causal forest: a prognostic surface μ(x)\mu(x) and a treatment surface τ(x)\tau(x), each its own ensemble of trees, combined as aμ(xi)+bziτ(xi)a\mu(x_i) + b_{z_i}\tau(x_i) 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.

Usage

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

Arguments

formula

A formula for the response and the confounders, as in dbartsData, or a matrix of confounders. The treatment is added to the design by bcf itself and must not appear in the formula.

data

A data frame or list in which to look up the formula's variables, or, when formula is a matrix, the response vector.

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 data. Both arms must be present after subsetting.

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; NULL is bcf's own convention, stated whether the amplitude is drawn or held: twice the standard deviation of the response over the observations with a positive weight under a continuous response, and one unit of the link under probit (1) and logistic (π/3\pi/\sqrt{3}). The size is the scale of the forest's trees; a drawn amplitude multiplies them under a Cauchy prior whose median size is 1 (amplitude = student(1) on the forest), so the forest is that size at an amplitude of 1.

sd.moderate

Size of the treatment forest, in the response's units; NULL takes dbarts's default. It too is the scale of the forest's trees; drawn amplitudes b0,b1b_0, b_1 are multipliers whose difference has prior median size 1.

update.a, update.b

Whether the prognostic and treatment amplitudes are drawn; when FALSE the coefficient is held, at 1 for the prognostic forest and at 0 and 1 for control and treated, and sd.control or sd.moderate is then that forest's prior standard deviation, exactly.

mu.interactions, tau.interactions

Optional interactions constraints, one per forest. interactions is not exported by dbarts: written as a call here, such as interactions(max.order = 1), it resolves to the dbarts constructor whether or not dbarts is attached. A constraint assembled beforehand, or passed on through a wrapper's ..., has to be built with dbarts::dbartsForests$interactions(...) instead; see dbartsForests.

tau.blocks

An optional blocks partition for the treatment forest. There is no prognostic-forest equivalent; see Details. Like tau.interactions, blocks resolves by bare name when written as a call here, and is otherwise spelled dbarts::dbartsForests$blocks(...).

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 TRUE they fold the chain margin into the sample margin. The fit always stores per-chain arrays.

keepSampler

Whether to keep the dbartsSampler-class object on the result, which allows the current-state per-forest variable counts to be read.

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 bartBCF.

object

An object of class bartBCF.

digits

Number of significant digits to print.

type

Which quantity to return; see Details.

forest

For type = "varcount", which forest's counts to return - "mu", "tau", or an index. The default returns both, as a named list.

newdata

Not presently used; see Details.

...

Additional arguments passed to dbarts or dbartsControl, such as family or n.thin. Unlike mu.interactions/tau.interactions/ tau.blocks above, anything passed through ... is evaluated before dbarts sees it, so a forest constraint reaching dbarts this way must be spelled dbarts::dbartsForests$interactions(...) (or $blocks), not written as a bare call.

Details

A Bayesian causal forest fits two ensembles at once. The prognostic forest μ\mu is an ordinary sum of trees; the treatment forest τ\tau 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 (b0,b1)(b_0, b_1) - one per arm - and the fitted value is aμ(xi)+bziτ(xi)a\mu(x_i) + b_{z_i}\tau(x_i). Swapping bzib_{z_i} for b1−zib_{1 - z_i} 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, s(b1−b0)τ(xi)s (b_1 - b_0) \tau(x_i) for the response scale ss. 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 (a,b0,b1)(a, b_0, b_1) each draw combines the forests through, named "a", "b.0" and "b.1": multipliers on the forests, with prior median size 1 for aa and for b1−b0b_1 - b_0 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 μ(x)\mu(x) and τ(x)\tau(x) 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.

Value

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, mu and tau, each forest's per-draw fitted values on the internal scale

glue

the per-draw amplitudes, n.chains x n.samples x 3, with "a", "b.0" and "b.1" named on the last margin; a drawn amplitude is a multiplier with prior median size 1, b1−b0b_1 - b_0's for the pair

mu.hat.obs, mu.hat.cf

the surfaces under the observed and counterfactual treatment conditions

varcount

named list of length two, keyed as forests is, each n.chains x n.samples x n.predictors with the predictor names on the last margin

sigma, first.sigma

the residual standard deviation for the kept and the burn-in draws, each an n.chains x n.samples matrix at every chain count (so extract(type = "sigma", combineChains = FALSE) of a one-chain fit is a 1 x n.samples matrix). first.sigma has zero columns when n.burn is 0, and both are absent on a binary fit

y, trt

the training response and treatment

name.trt, name.p.score

the resolved design column names; name.p.score is NULL when no score was given

family

the resolved response family

response.scale, response.shift

the linear map from the internal scale to the response scale

data

the dbartsData object fit

n.trees

tree counts, one per forest, named as forests is

n.chains, n.samples, n.burn

chains run, posterior draws kept per chain, and burn-in iterations discarded

n.obs

observations fit, after any subset

combineChains

the value passed to bcf, which the accessors take as their default

call

the matched call, or the response fitter's when the fit came from bartc

fit

the sampler, only under keepSampler = TRUE

Author(s)

Vincent Dorie: [email protected].

See Also

bartc, dbarts

Examples

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

Summary for bartcFit Objects

Description

Summarizes bartc fits by calculating target quantities and uncertainty estimates.

Usage

## 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"),
                           ...)

Arguments

object

Object of class bartcFit.

target

Treatment effect to calculate. One of "pate" - population average treatment effect, "sate" - sample average treatment effect, and "cate" - conditional average treatment effect.

ci.style

Means of calculating confidence intervals (posterior credible regions). Options include "norm" - use a normal approximation, "quant" - the empirical quantites of the posterior samples, and "hpd" - region of highest posterior density.

ci.level

Level of confidence for intervals.

pate.style

For target "pate", calculate uncertainty by using "ppd" - the posterior predictive distribution or "var.exp" a variance expansion formula.

...

Not used at moment, but present to match summary generic signature.

Details

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, σ2∑iai2/wi\sigma^2 \sum_i a_i^2 / w_i, with aia_i an observation's share and wiw_i 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 viv_i, (∑ivi)2/∑ivi2(\sum_i v_i)^2 / \sum_i v_i^2 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.

Value

An object of class bartcFit.summary equivalent to a list with named items:

call

how bartc was called

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 target, ci.style, ci.level, and pate.style as passed to summary

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 data.frame with columns "estimate" - the target, "sd" - standard deviation of posterior of estimate (for "p.weight" and "tmle" response methods, the square root of its variance plus the mean squared standard error of the draws, in the units of the response), "ci.lower" - lower bound of credible region, "ci.upper" - upper bound of credible region, and, in a grouped summary, "n" - the number of observations averaged and, with population weights, "n.eff" - their Kish effective sample size

n.cut

under a common support rule, a data.frame of the treated and control observations it cut, for each group of a grouped summary; with population weights, a grouped summary adds the column weight.cut, each group's share of the population weight of the observations its estimand averages over that the rule removed, NA for a group of no weight

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

Author(s)

Vincent Dorie: [email protected].