% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/CausalShrinkageForest.R
\name{CausalShrinkageForest}
\alias{CausalShrinkageForest}
\title{General Causal Shrinkage Forests}
\usage{
CausalShrinkageForest(
  y = NULL,
  status = NULL,
  X_train_control,
  X_train_treat,
  treatment_indicator_train,
  X_test_control = NULL,
  X_test_treat = NULL,
  treatment_indicator_test = NULL,
  left_time = NULL,
  right_time = NULL,
  outcome_type = "continuous",
  timescale = "time",
  number_of_trees_control = 200,
  number_of_trees_treat = 200,
  prior_type_control = "horseshoe",
  prior_type_treat = "horseshoe",
  local_hp_control = NULL,
  local_hp_treat = NULL,
  global_hp_control = NULL,
  global_hp_treat = NULL,
  a_dirichlet_control = 0.5,
  a_dirichlet_treat = 0.5,
  b_dirichlet_control = 1,
  b_dirichlet_treat = 1,
  rho_dirichlet_control = NULL,
  rho_dirichlet_treat = NULL,
  power_control = 2,
  power_treat = 2,
  base_control = 0.95,
  base_treat = 0.95,
  p_grow = 0.5,
  p_prune = 0.5,
  nu = 3,
  q = 0.9,
  sigma = NULL,
  N_post = 5000,
  N_burn = 5000,
  delayed_proposal = 5,
  store_posterior_sample = FALSE,
  treatment_coding = "centered",
  propensity = NULL,
  propensity_test = NULL,
  n_chains = 1,
  verbose = TRUE
)
}
\arguments{
\item{y}{Outcome vector. Numeric. Represents continuous outcomes or follow-up times.
Set to \code{NULL} when using \code{outcome_type = "interval-censored"}, as
values are derived from \code{left_time} and \code{right_time}.}

\item{status}{Optional event indicator vector (1 = event occurred, 0 = censored).
Required when \code{outcome_type = "right-censored"}. For interval-censored
outcomes, this is derived automatically from \code{left_time} and
\code{right_time}.}

\item{X_train_control}{Covariate matrix for the control forest. Rows correspond to samples,
columns to covariates.}

\item{X_train_treat}{Covariate matrix for the treatment forest.}

\item{treatment_indicator_train}{Vector indicating treatment assignment for training samples
(1 = treated, 0 = control).}

\item{X_test_control}{Optional covariate matrix for control forest test data. Defaults to
column means of \code{X_train_control} if NULL.}

\item{X_test_treat}{Optional covariate matrix for treatment forest test data. Defaults to
column means of \code{X_train_treat} if NULL.}

\item{treatment_indicator_test}{Optional vector indicating treatment assignment for test data.}

\item{left_time}{Optional numeric vector of left (lower) time boundaries.
Required when \code{outcome_type = "interval-censored"}. Exact events
have \code{left_time == right_time}; right-censored observations have
\code{right_time = Inf}; interval-censored observations have finite
\code{left_time < right_time}.}

\item{right_time}{Optional numeric vector of right (upper) time boundaries.
Required when \code{outcome_type = "interval-censored"}. Use \code{Inf}
for right-censored observations.}

\item{outcome_type}{Type of outcome: one of \code{"continuous"},
\code{"right-censored"}, or \code{"interval-censored"}.
Default is \code{"continuous"}.}

\item{timescale}{For survival outcomes: either \code{"time"} (original scale, log-transformed
internally) or \code{"log"} (already log-transformed). Default is \code{"time"}.
Used when \code{outcome_type} is \code{"right-censored"} or
\code{"interval-censored"}.}

\item{number_of_trees_control}{Number of trees in the control forest. Default is 200.}

\item{number_of_trees_treat}{Number of trees in the treatment forest. Default is 200.}

\item{prior_type_control}{Type of prior on control forest step heights. One of
\code{"horseshoe"}, \code{"horseshoe_fw"}, or \code{"half-cauchy"}.
Default is \code{"horseshoe"}.}

\item{prior_type_treat}{Type of prior on treatment forest step heights. Same options as
\code{prior_type_control}.}

\item{local_hp_control}{Local hyperparameter controlling shrinkage on individual steps
(control forest). Required for all prior types.}

\item{local_hp_treat}{Local hyperparameter for treatment forest.}

\item{global_hp_control}{Global hyperparameter for control forest. Required for horseshoe-type
priors; ignored for \code{"half-cauchy"}.}

\item{global_hp_treat}{Global hyperparameter for treatment forest.}

\item{a_dirichlet_control}{First shape parameter of the Beta prior used in the
Dirichlet–Sparse splitting rule for the control forest. Together with
\code{b_dirichlet_control}, it controls the expected sparsity level.}

\item{a_dirichlet_treat}{First shape parameter of the Beta prior used in the
Dirichlet–Sparse splitting rule for the treatment forest.}

\item{b_dirichlet_control}{Second shape parameter of the Beta prior for the
sparsity level in the control forest. Larger values shrink splitting
probabilities more strongly toward uniform sparsity.}

\item{b_dirichlet_treat}{Second shape parameter of the Beta prior governing
sparsity in the treatment forest.}

\item{rho_dirichlet_control}{Sparsity hyperparameter for the control forest.
Represents the \emph{expected number of active predictors}. If left NULL, it
defaults to the number of covariates in the control forest.}

\item{rho_dirichlet_treat}{Sparsity hyperparameter for the treatment forest,
interpreted as the expected number of active predictors. Defaults to the
number of covariates in the treatment forest if not specified.}

\item{power_control}{Power parameter for the control forest tree structure prior splitting probability.}

\item{power_treat}{Power parameter for the treatment forest tree structure prior splitting probability.}

\item{base_control}{Base parameter for the control forest tree structure prior splitting probability.}

\item{base_treat}{Base parameter for the treatment forest tree structure prior splitting probability.}

\item{p_grow}{Probability of proposing a grow move. Default is 0.5. These are fixed at 0.5 for prior_type
\code{"standard"} and \code{"dirichlet"}.}

\item{p_prune}{Probability of proposing a prune move. Default is 0.5. These are fixed at 0.5 for prior_type
\code{"standard"} and \code{"dirichlet"}.}

\item{nu}{Degrees of freedom for the error variance prior. Default is 3.}

\item{q}{Quantile parameter for error variance prior. Default is 0.90.}

\item{sigma}{Optional known standard deviation of the outcome. If NULL, estimated from data.}

\item{N_post}{Number of posterior samples to store. Default is 5000.}

\item{N_burn}{Number of burn-in iterations. Default is 5000.}

\item{delayed_proposal}{Number of delayed iterations before proposal updates. Default is 5.}

\item{store_posterior_sample}{Logical; whether to store posterior samples of predictions.
Default is \code{FALSE}.}

\item{treatment_coding}{Treatment coding scheme for the two-forest model.
One of \code{"centered"} (default), \code{"binary"}, \code{"adaptive"},
or \code{"invariant"}.
\code{"centered"} uses \eqn{b_i \in \{-1/2, 1/2\}};
\code{"binary"} uses \eqn{b_i \in \{0, 1\}};
\code{"adaptive"} uses \eqn{b_i = A_i - \hat{e}(x_i)} where
\eqn{\hat{e}(x_i)} is the estimated propensity score;
\code{"invariant"} treats \eqn{b_0, b_1} as parameters estimated within
the Gibbs sampler with \eqn{b_j \sim N(0, 1/2)} priors, yielding a
parameterisation-invariant model (Hahn et al., 2020, Section 5.2).}

\item{propensity}{Optional numeric vector of propensity scores
\eqn{\hat{e}(x_i)} for training observations. Required when
\code{treatment_coding = "adaptive"}.}

\item{propensity_test}{Optional numeric vector of propensity scores for
test observations. Only used when \code{treatment_coding = "adaptive"}.
Defaults to \code{0.5} for all test observations if not provided.}

\item{n_chains}{Number of independent MCMC chains to run. Default is
\code{1} (standard single-chain behaviour). When \code{n_chains > 1} the
chains are run in parallel via \code{parallel::mclapply} and their
posterior samples are pooled into a single \code{CausalShrinkageForest}
object, so all existing \code{print} and \code{summary} methods work
without modification. On Windows, \code{mclapply} falls back to
sequential execution.}

\item{verbose}{Logical; whether to print verbose output. Default is \code{TRUE}.}
}
\value{
An S3 object of class \code{"CausalShrinkageForest"} containing:
\describe{
\item{train_predictions}{Posterior mean predictions on training data (combined forest).}
\item{test_predictions}{Posterior mean predictions on test data (combined forest).}
\item{train_predictions_control}{Estimated control outcomes on training data.}
\item{test_predictions_control}{Estimated control outcomes on test data.}
\item{train_predictions_treat}{Estimated treatment effects on training data.}
\item{test_predictions_treat}{Estimated treatment effects on test data.}
\item{sigma}{Vector of posterior samples for the error standard deviation.}
\item{acceptance_ratio_control}{Average acceptance ratio in control forest.}
\item{acceptance_ratio_treat}{Average acceptance ratio in treatment forest.}
\item{train_predictions_sample_control}{Matrix of posterior samples for control predictions
(if \code{store_posterior_sample = TRUE}).}
\item{test_predictions_sample_control}{Matrix of posterior samples for control predictions
(if \code{store_posterior_sample = TRUE}).}
\item{train_predictions_sample_treat}{Matrix of posterior samples for treatment effects
(if \code{store_posterior_sample = TRUE}).}
\item{test_predictions_sample_treat}{Matrix of posterior samples for treatment effects
(if \code{store_posterior_sample = TRUE}).}
}
}
\description{
Fits a (Bayesian) Causal Shrinkage Forest model for estimating heterogeneous treatment effects.
This function generalizes \code{\link{CausalHorseForest}} by allowing flexible
global-local shrinkage priors on the step heights in both the control and treatment forests.
It supports continuous, right-censored, and interval-censored survival outcomes.
}
\details{
This function is a flexible generalization of \code{CausalHorseForest}.
The Causal Shrinkage Forest model decomposes the outcome into a prognostic
(control) and a treatment effect part. Each part is modeled by its own
shrinkage tree ensemble, with separate flexible global-local shrinkage
priors. It is particularly useful for estimating heterogeneous treatment
effects in high-dimensional settings. Further
methodological details on the Horseshoe Forest framework can be found in
Jacobs, van Wieringen & van der Pas (2025).

The \code{horseshoe} prior is the fully Bayesian global-local shrinkage
prior, where both the global and local shrinkage parameters are assigned
half-Cauchy distributions with scale hyperparameters \code{global_hp} and
\code{local_hp}, respectively. The global shrinkage parameter is defined
separately for each tree, allowing adaptive regularization per tree.

The \code{horseshoe_fw} prior (forest-wide horseshoe) is similar to
\code{horseshoe}, except that the global shrinkage parameter is shared
across all trees in the forest simultaneously.

The \code{half-cauchy} prior considers only local shrinkage and does not
include a global shrinkage component. It places a half-Cauchy prior on each
local shrinkage parameter with scale hyperparameter \code{local_hp}.

The \code{dirichlet} prior implements the Dirichlet–Sparse splitting rule of
Linero (2018), in which splitting probabilities follow a Dirichlet prior
whose concentration is controlled by a Beta sparsity parameter
(\code{a_dirichlet}, \code{b_dirichlet}) and an expected sparsity level
\code{rho_dirichlet}.
}
\examples{
# Example: Continuous outcome, homogeneous treatment effect, two priors
n <- 50
p <- 3
X <- matrix(runif(n * p), ncol = p)
X_treat <- X_control <- X
treat <- rbinom(n, 1, X[,1])
tau <- 2
y <- X[, 1] + (0.5 - treat) * tau + rnorm(n)

# Fit a standard Causal Horseshoe Forest
fit_horseshoe <- CausalShrinkageForest(y = y,
                                       X_train_control = X_control,
                                       X_train_treat = X_treat,
                                       treatment_indicator_train = treat,
                                       outcome_type = "continuous",
                                       number_of_trees_treat = 5,
                                       number_of_trees_control = 5,
                                       prior_type_control = "horseshoe",
                                       prior_type_treat = "horseshoe",
                                       local_hp_control = 0.1/sqrt(5),
                                       local_hp_treat = 0.1/sqrt(5),
                                       global_hp_control = 0.1/sqrt(5),
                                       global_hp_treat = 0.1/sqrt(5),
                                       N_post = 10,
                                       N_burn = 5,
                                       store_posterior_sample = TRUE,
                                       verbose = FALSE
)

# Fit a Causal Shrinkage Forest with half-cauchy prior
fit_halfcauchy <- CausalShrinkageForest(y = y,
                                        X_train_control = X_control,
                                        X_train_treat = X_treat,
                                        treatment_indicator_train = treat,
                                        outcome_type = "continuous",
                                        number_of_trees_treat = 5,
                                        number_of_trees_control = 5,
                                        prior_type_control = "half-cauchy",
                                        prior_type_treat = "half-cauchy",
                                        local_hp_control = 1/sqrt(5),
                                        local_hp_treat = 1/sqrt(5),
                                        N_post = 10,
                                        N_burn = 5,
                                        store_posterior_sample = TRUE,
                                        verbose = FALSE
)

# Posterior mean CATEs
CATE_horseshoe <- colMeans(fit_horseshoe$train_predictions_sample_treat)
CATE_halfcauchy <- colMeans(fit_halfcauchy$train_predictions_sample_treat)

# Posteriors of the ATE
post_ATE_horseshoe <- rowMeans(fit_horseshoe$train_predictions_sample_treat)
post_ATE_halfcauchy <- rowMeans(fit_halfcauchy$train_predictions_sample_treat)

# Posterior mean ATE
ATE_horseshoe <- mean(post_ATE_horseshoe)
ATE_halfcauchy <- mean(post_ATE_halfcauchy)

# Example: Interval-censored causal survival outcome
n <- 50; p <- 3
X_ic <- matrix(rnorm(n * p), ncol = p)
treat_ic <- rbinom(n, 1, 0.5)
true_t <- rexp(n, rate = exp(-X_ic[, 1] - 0.5 * treat_ic))
left_t  <- true_t * runif(n, 0.5, 1)
right_t <- true_t * runif(n, 1, 1.5)
exact <- sample(n, 15)
left_t[exact] <- true_t[exact]; right_t[exact] <- true_t[exact]
rc <- sample(setdiff(seq_len(n), exact), 10); right_t[rc] <- Inf

fit_ic <- CausalShrinkageForest(
  left_time = left_t, right_time = right_t,
  X_train_control = X_ic, X_train_treat = X_ic,
  treatment_indicator_train = treat_ic,
  outcome_type = "interval-censored",
  number_of_trees_control = 5, number_of_trees_treat = 5,
  prior_type_control = "horseshoe", prior_type_treat = "horseshoe",
  local_hp_control = 0.1/sqrt(5), local_hp_treat = 0.1/sqrt(5),
  global_hp_control = 0.1/sqrt(5), global_hp_treat = 0.1/sqrt(5),
  N_post = 10, N_burn = 5,
  store_posterior_sample = TRUE, verbose = FALSE)

}
\references{
Jacobs, T., van Wieringen, W. N., & van der Pas, S. L. (2025).
\emph{Horseshoe Forests for High-Dimensional Causal Survival Analysis.}
arXiv:2507.22004. https://doi.org/10.48550/arXiv.2507.22004

Chipman, H. A., George, E. I., & McCulloch, R. E. (2010).
\emph{BART: Bayesian additive regression trees.} Annals of Applied Statistics.

Linero, A. R. (2018). \emph{Bayesian regression trees for high-dimensional
prediction and variable selection.} Journal of the American Statistical
Association.
}
\seealso{
Model family: \code{\link{CausalHorseForest}} (causal, horseshoe prior),
\code{\link{ShrinkageTrees}} (non-causal, flexible prior),
\code{\link{HorseTrees}} (non-causal, horseshoe prior).

Survival wrappers: \code{\link{SurvivalBCF}}, \code{\link{SurvivalShrinkageBCF}}.

S3 methods: \code{\link{print.CausalShrinkageForest}},
\code{\link{summary.CausalShrinkageForest}},
\code{\link{predict.CausalShrinkageForest}},
\code{\link{plot.CausalShrinkageForest}}.
}
