Type:	Package
Title:	Tidy Methods for Bayesian Treatment Effect Models
Version:	0.3.1
Description:	Functions for extracting tidy data from Bayesian treatment effect models, in particular BART, but extensions are possible. Functionality includes extracting tidy posterior summaries as in 'tidybayes' https://github.com/mjskay/tidybayes, estimating (average) treatment effects, common support calculations, and plotting useful summaries of these.
Encoding:	UTF-8
LazyData:	true
License:	MIT + file LICENSE
URL:	https://github.com/bonStats/tidytreatment
BugReports:	https://github.com/bonStats/tidytreatment/issues
Language:	en-US
Depends:	R (≥ 3.1.0)
Suggests:	knitr, rmarkdown, stan4bart, bartCause, ggplot2, testthat (≥ 3.0.0), withr, lme4
VignetteBuilder:	knitr
RoxygenNote:	7.3.2
Imports:	tidybayes, purrr, tidyr, dplyr, readr, rlang, dbarts, BART, coda, magrittr
Enhances:	bartMachine
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2025-01-10 11:47:06 UTC; jbon
Author:	Joshua J Bon [aut, cre]
Maintainer:	Joshua J Bon <joshuajbon@gmail.com>
Repository:	CRAN
Date/Publication:	2025-01-10 12:30:02 UTC

tidytreatment: Tidy methods for Bayesian treatment effect models

Description

tidytreatment provides functions for extracting tidy data from Bayesian treatment effect models, estimating treatment effects, and plotting useful summaries of these.

Author(s)

Maintainer: Joshua J Bon joshuajbon@gmail.com (ORCID)

See Also

Useful links:

• https://github.com/bonStats/tidytreatment

• Report bugs at https://github.com/bonStats/tidytreatment/issues

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

Value

The result of calling 'rhs(lhs)'.

Get (conditional) average treatment effect draws from posterior

Description

(C)ATE = (Conditional) Average Treatment Effects newdata specifies the conditions, if unspecified it defaults to the original data. Assumes treated column is either a integer column of 1's (treated) and 0's (nontreated) or logical indicating treatment if TRUE.

Usage

avg_treatment_effects(
  model,
  treatment,
  newdata,
  subset = "all",
  common_support_method,
  cutoff,
  ...
)

Arguments

Value

A tidy data frame (tibble) with treatment effect values.

Example model 1

Description

Model fit with simulated data from simulated dataset suhillsim1.

Usage

bartmodel1

Format

Object of type BART::wbart

Details

Propensity score estimated and included suhillsim1 for fitting the model.

Source

https://github.com/bonStats/tidytreatment/tree/master/data-raw

Model matrix used for bartmodel1

Description

Useful for testing tidytreatment package functions.

Usage

bartmodel1_modelmatrix

Format

Object of type BART::wbart

Source

https://github.com/bonStats/tidytreatment/tree/master/data-raw

Counts of variable overall inclusion

Description

Inclusion metric for bartMachine and BART are scaled differently. bartMachine averaged over number of trees, in addition to number of MCMC draws.

Usage

covariate_importance(model, ...)

Arguments

Value

Tidy data with counts of variable inclusion, when interacting with treatment variable.

Counts of variable inclusion when interacting with treatment

Description

Counts of variable inclusion when interacting with treatment

Usage

covariate_with_treatment_importance(model, treatment, ...)

Arguments

Value

Tidy data with counts of variable inclusion, when interacting with treatment variable.

Get expected prediction draws from posterior of bartCause-package objects

Description

Typically referred to as fitted value draws on response scale, where appropriate.

Usage

## S3 method for class 'bartcFit'
epred_draws(
  object,
  ...,
  value = ".epred",
  re_formula = NULL,
  fitstage = c("response", "assignment")
)

Arguments

Get expected prediction draws from posterior of stan4bart-package models

Description

Typically referred to as fitted value draws on response scale, where appropriate.

Usage

## S3 method for class 'stan4bartFit'
epred_draws(object, newdata, ..., value = ".epred", re_formula = NULL)

Arguments

Get fitted draws from posterior of bartMachine model

Description

Get fitted draws from posterior of bartMachine model

Usage

## S3 method for class 'bartMachine'
fitted_draws(
  model,
  newdata,
  value = ".value",
  ...,
  n = NULL,
  include_newdata = TRUE,
  include_sigsqs = FALSE
)

Arguments

Value

A tidy data frame (tibble) with fitted values.

Get fitted draws from posterior of lbart model

Description

Get fitted draws from posterior of lbart model

Usage

## S3 method for class 'lbart'
fitted_draws(
  model,
  newdata,
  value = ".value",
  ...,
  n = NULL,
  include_newdata = TRUE,
  include_sigsqs = FALSE
)

Arguments

Value

A tidy data frame (tibble) with fitted values.

Get fitted draws from posterior of mbart model

Description

Get fitted draws from posterior of mbart model

Usage

## S3 method for class 'mbart'
fitted_draws(
  model,
  newdata,
  value = ".value",
  ...,
  n = NULL,
  include_newdata = TRUE,
  include_sigsqs = FALSE
)

Arguments

Value

A tidy data frame (tibble) with fitted values.

Get fitted draws from posterior of mbart2 model

Description

Get fitted draws from posterior of mbart2 model

Usage

## S3 method for class 'mbart2'
fitted_draws(
  model,
  newdata,
  value = ".value",
  ...,
  n = NULL,
  include_newdata = TRUE,
  include_sigsqs = FALSE
)

Arguments

Value

A tidy data frame (tibble) with fitted values.

Get fitted draws from posterior of pbart model

Description

Get fitted draws from posterior of pbart model

Usage

## S3 method for class 'pbart'
fitted_draws(
  model,
  newdata,
  value = ".value",
  ...,
  n = NULL,
  include_newdata = TRUE,
  include_sigsqs = FALSE
)

Arguments

Value

A tidy data frame (tibble) with fitted values.

Get fitted draws from posterior of wbart model

Description

Get fitted draws from posterior of wbart model

Usage

## S3 method for class 'wbart'
fitted_draws(
  model,
  newdata,
  value = ".value",
  ...,
  n = NULL,
  include_newdata = TRUE,
  include_sigsqs = FALSE
)

Arguments

Value

A tidy data frame (tibble) with fitted values.

Get fitted draws from posterior of BART-package models

Description

Get fitted draws from posterior of BART-package models

Usage

fitted_draws_BART(
  model,
  newdata = NULL,
  value = ".value",
  ...,
  include_newdata = TRUE,
  include_sigsqs = FALSE,
  scale = "real"
)

Arguments

Value

A tidy data frame (tibble) with fitted values.

Evaluate if observations have common support.

Description

The common support identification methods are based on Hill and Su (2013). Loosely speaker, an individuals treatment effect estimate has common support if the counter factual estimate is not too uncertain. The estimates are uncertain when the prediction is 'far away' from other observations. Removing estimates without common support can be beneficial for treat effect estimates.

Usage

has_common_support(model, treatment, method, cutoff, modeldata = NULL)

Arguments

Details

Hill, Jennifer; Su, Yu-Sung. Ann. Appl. Stat. 7 (2013), no. 3, 1386–1420. doi:10.1214/13-AOAS630. https://projecteuclid.org/euclid.aoas/1380804800

Value

Tibble with a row for each observation and a column indicating whether common support exists.

Check if a model class has required generic methods for tidytreatment functions.

Description

Check if a model class has required generic methods for tidytreatment functions.

Usage

has_tidytreatment_methods(model)

Arguments

Value

Boolean

ACIC2019 High Dimensional Test Dataset

Description

Dataset from the "Data Challenge" for the Atlantic Causal Inference Conference 2019.

Usage

highDim_testdataset3

Format

A data frame with 2000 observations, and 187 variables.

Y

Outcome variable

A

Treatment variable

V1,V2,V3,V4,V5,V6,V7,V8,V9,V10,V11,V12,V13,V14,V15,V16,V17,V18,V19,V20,V21,V22,V23,V24,V25,V26,V27,V28,V29,V30,V31,V32,V33,V34,V35,V36,V37,V38,V39,V40,V41,V42,V43,V44,V45,V46,V47,V48,V49,V50,V51,V52,V53,V54,V55,V56,V57,V58,V59,V60,V61,V62,V63,V64,V65,V66,V67,V68,V69,V70,V71,V72,V73,V74,V75,V76,V77,V78,V79,V80,V81,V82,V83,V84,V85,V86,V87,V88,V89,V90,V91,V92,V93,V94,V95,V96,V97,V98,V99,V100,V101,V102,V103,V104,V105,V106,V107,V108,V109,V110,V111,V112,V113,V114,V115,V116,V117,V118,V119,V120,V121,V122,V123,V124,V125,V126,V127,V128,V129,V130,V131,V132,V133,V134,V135,V136,V137,V138,V139,V140,V141,V142,V143,V144,V145,V146,V147,V148,V149,V150,V151,V152,V153,V154,V155,V156,V157,V158,V159,V160,V161,V162,V163,V164,V165,V166,V167,V168,V169,V170,V171,V172,V173,V174,V175,V176,V177,V178,V179,V180,V181,V182,V183,V184,V185

Other covariates

...

Source

https://www.mcgill.ca/epi-biostat-occh/seminars-events/event-archive/atlantic-causal-inference-conference-2019/data-challenge

Get expected prediction draws (on linear scale) from posterior of bartCause-package objects

Description

Typically referred to as fitted value draws on linear scale, where appropriate.

Usage

## S3 method for class 'bartcFit'
linpred_draws(
  object,
  ...,
  value = ".linpred",
  re_formula = NULL,
  fitstage = c("response", "assignment")
)

Arguments

Get expected prediction draws (on linear scale) from posterior of stan4bart-package models

Description

Typically referred to as fitted value draws on linear scale, where appropriate.

Usage

## S3 method for class 'stan4bartFit'
linpred_draws(object, newdata, ..., value = ".linpred", re_formula = NULL)

Arguments

Get posterior tree draws into tibble format from BART model

Description

Tibble grouped by iteration ('iter') and tree id ('tree_id'). All information calculated by method is included in output.

Usage

posterior_trees_BART(model, label_digits = 2)

Arguments

Value

A tibble with columns to

iter

Integer describing unique MCMC iteration.

tree_id

Integer. Unique tree id with each 'iter'.

node

Integer describing node in tree. Unique to each 'tree'-'iter'.

parent

Integer describing parent node in tree.

label

Label for the node.

tier

Position in tree hierarchy.

var

Variable for split.

cut

Numeric. Value of decision rule for 'var'.

is_leaf

Logical. 'TRUE' if leaf, 'FALSE' if stem.

leaf_value

child_left

Integer. Left child of node.

child_right

Integer. Right child of node.

Get predict draws from posterior of bartMachine model

Description

Get predict draws from posterior of bartMachine model

Usage

## S3 method for class 'bartMachine'
predicted_draws(
  object,
  newdata,
  value = ".prediction",
  ...,
  ndraws = NULL,
  include_newdata = TRUE,
  include_fitted = FALSE,
  include_sigsqs = FALSE
)

Arguments

Value

A tidy data frame (tibble) with predicted values.

Get prediction draws from posterior of bartCause-package objects

Description

Get prediction draws from posterior of bartCause-package objects

Usage

## S3 method for class 'bartcFit'
predicted_draws(
  object,
  ...,
  value = ".prediction",
  re_formula = NULL,
  fitstage = c("response", "assignment")
)

Arguments

Get prediction draws from posterior of stan4bart-package models

Description

Get prediction draws from posterior of stan4bart-package models

Usage

## S3 method for class 'stan4bartFit'
predicted_draws(object, newdata, ..., value = ".prediction", re_formula = NULL)

Arguments

Get predict draws from posterior of wbart model

Description

Get predict draws from posterior of wbart model

Usage

## S3 method for class 'wbart'
predicted_draws(
  object,
  newdata,
  value = ".prediction",
  ...,
  ndraws = NULL,
  include_newdata = TRUE,
  include_fitted = FALSE,
  include_sigsqs = FALSE
)

Arguments

Value

A tidy data frame (tibble) with predicted values.

Get predict draws from posterior of BART-package models

Description

Get predict draws from posterior of BART-package models

Usage

predicted_draws_BART(
  object,
  newdata = NULL,
  value = ".prediction",
  ...,
  rng = stats::rnorm,
  include_newdata = TRUE,
  include_fitted = FALSE,
  include_sigsqs = FALSE
)

Arguments

Value

A tidy data frame (tibble) with predicted values.

Get residual draw for bartMachine model

Description

Get residual draw for bartMachine model

Usage

## S3 method for class 'bartMachine'
residual_draws(
  object,
  newdata,
  value = ".residual",
  ...,
  ndraws = NULL,
  include_newdata = TRUE,
  include_sigsqs = FALSE
)

Arguments

Value

Tibble with residuals.

Get residual draw for pbart model

Description

The original response variable must be passed as an argument to this function. e.g. 'response = y'

Usage

## S3 method for class 'pbart'
residual_draws(
  object,
  newdata,
  value = ".residual",
  ...,
  ndraws = NULL,
  include_newdata = TRUE,
  include_sigsqs = FALSE
)

Arguments

Value

Tibble with residuals.

Get residual draw for wbart model

Description

The original response variable must be passed as an argument to this function. e.g. 'response = y'

Usage

## S3 method for class 'wbart'
residual_draws(
  object,
  newdata,
  value = ".residual",
  ...,
  ndraws = NULL,
  include_newdata = TRUE,
  include_sigsqs = FALSE
)

Arguments

Value

Tibble with residuals.

Get residual draw for BART model

Description

Classes from BART-package models

Usage

residual_draws_BART(
  object,
  response,
  newdata = NULL,
  value = ".residual",
  include_newdata = TRUE,
  include_sigsqs = FALSE
)

Arguments

Value

Tibble with residuals.

Simulate data with scenarios from Hill and Su (2013)

Description

Sample n observations with the following scheme:

1. Covariates: X_j ~ N(0,1).

2. Assignment: Z ~ Bin(n, p) with p = logit^{-1}(a + X \gamma^L + Q \gamma^N) where a = \omega - mean(X \gamma^L + Q \gamma^N).

3. Mean response: E(Y(0)|X) = X \beta_0^L + Q \beta_0^N and E(Y(1)|X) = X \beta_1^L + Q \beta_1^N.

4. Observation: Y ~ N(\mu,\sigma_y^2)).

Superscript L denotes the linear components, whilst N denotes the non-linear components.

Usage

simulate_su_hill_data(
  n,
  treatment_linear = TRUE,
  response_parallel = TRUE,
  response_aligned = TRUE,
  y_sd = 1,
  tau = 4,
  omega = 0,
  add_categorical = FALSE,
  n_subjects = 0,
  sd_subjects = 1,
  coef_categorical_treatment = NULL,
  coef_categorical_nontreatment = NULL
)

Arguments

Details

Coefficients used are returned in the list this function creates. See Table 1 in Su and Hill (2013) for the table of coefficients. The X_j are in a data.frame named data in the returned list. The formula for the model matrix [X,Q] is named su_hill_formula in the returned list. The coefficients used for the model matrix are contained in coefs. The Su and Hill (2013) simulations did not include categorical variables, but you can add them here using arguments: add_categorical, coef_categorical_treatment, coef_categorical_nontreatment.

Hill, Jennifer; Su, Yu-Sung. Ann. Appl. Stat. 7 (2013), no. 3, 1386–1420. doi:10.1214/13-AOAS630. https://projecteuclid.org/euclid.aoas/1380804800

Value

An object of class suhillsim that is a list with elements

Example simulated dataset 1

Description

Simulated with simulate_su_hill_data(...), see details. Includes propensity score estimated using BART (prop_score), see source.

Usage

suhillsim1

Format

See ?simulate_su_hill_data for output format.

Details

set.seed(101)
 suhillsim1 <- simulate_su_hill_data(n = 100, treatment_linear = FALSE,  omega = 0, add_categorical = TRUE,
   coef_categorical_treatment = c(0,0,1),
   coef_categorical_nontreatment = c(-1,0,-1))

Source

https://github.com/bonStats/tidytreatment/tree/master/data-raw

Example simulated dataset 2: with subject specific random effects

Description

Simulated with simulate_su_hill_data(...), see details.

Usage

suhillsim2_ranef

Format

See ?simulate_su_hill_data for output format.

Details

set.seed(101)
 suhillsim1 <- simulate_su_hill_data(n = 100, treatment_linear = FALSE,  omega = 0, add_categorical = TRUE,
   coef_categorical_treatment = c(0,0,1),
   coef_categorical_nontreatment = c(-1,0,-1), sd_subjects = 2, n_subjects = 10)

Source

https://github.com/bonStats/tidytreatment/tree/master/data-raw

Get average treatment effect draws from posterior

Description

ATE = Average Treatment Effects Assumes treated column is either a integer column of 1's (treated) and 0's (nontreated) or logical indicating treatment if TRUE.

Usage

tidy_ate(model, treatment, common_support_method, cutoff, ...)

Arguments

Value

A tidy data frame (tibble) with treatment effect values.

Get average treatment effect on treated draws from posterior

Description

ATT = average Treatment Effects on Treated Assumes treated column is either a integer column of 1's (treated) and 0's (nontreated) or logical indicating treatment if TRUE.

Usage

tidy_att(model, treatment, common_support_method, cutoff, ...)

Arguments

Value

A tidy data frame (tibble) with treatment effect values.

Tidy access to posterior of bartCause-package objects

Description

Tidy access to posterior of bartCause-package objects

Usage

## S3 method for class 'bartcFit'
tidy_draws(model, type = NULL, fitstage = c("response", "assignment"), ...)

Arguments

Get (individual) treatment effect draws from posterior

Description

CTE = Conditional Treatment Effects (usually used to generate (C)ATE or ATT) newdata specifies the conditions, if unspecified it defaults to the original data. Assumes treated column is either a integer column of 1's (treated) and 0's (nontreated) or logical indicating treatment if TRUE.

Usage

treatment_effects(
  model,
  treatment,
  newdata,
  subset = "all",
  common_support_method,
  cutoff,
  ...
)

Arguments

Value

A tidy data frame (tibble) with treatment effect values.

Get (individual) treatment effect draws from bartcFit posterior

Description

CTE = Conditional Treatment Effects (usually used to generate (C)ATE or ATT) newdata specifies the conditions, if unspecified it defaults to the original data. Assumes treated column is either a integer column of 1's (treated) and 0's (nontreated) or logical indicating treatment if TRUE.

Usage

## S3 method for class 'bartcFit'
treatment_effects(
  model,
  treatment = NULL,
  newdata = NULL,
  subset = "all",
  common_support_method,
  cutoff,
  ...
)

Arguments

Value

A tidy data frame (tibble) with treatment effect values.

Get treatment effect draws from posterior

Description

CTE = Conditional Treatment Effects (or CATE, the average effects) newdata specifies the conditions, if unspecified it defaults to the original data. Assumes treated column is either a integer column of 1's (treated) and 0's (nontreated) or logical indicating treatment if TRUE.

Usage

## Default S3 method:
treatment_effects(
  model,
  treatment,
  newdata,
  subset = "all",
  common_support_method,
  cutoff,
  ...
)

Arguments

Value

A tidy data frame (tibble) with treatment effect values.

Get variance draws from posterior of BART models

Description

Models from BART-package include warm-up and skipped MCMC draws.

Usage

variance_draws(model, value = ".sigma_sq", ...)

Arguments

Value

A tidy data frame (tibble) with draws of variance parameter