% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/SurvivalWrappers.R
\name{SurvivalShrinkageBCF}
\alias{SurvivalShrinkageBCF}
\title{SurvivalShrinkageBCF (Shrinkage Bayesian Causal Forest for survival data)}
\usage{
SurvivalShrinkageBCF(
  time = NULL,
  status = NULL,
  X_train,
  treatment,
  timescale = "time",
  propensity = NULL,
  treatment_coding = "centered",
  a_dir = 0.5,
  b_dir = 1,
  number_of_trees_control = 200,
  number_of_trees_treat = 50,
  power_control = 2,
  base_control = 0.95,
  power_treat = 3,
  base_treat = 0.25,
  N_post = 1000,
  N_burn = 1000,
  store_posterior_sample = TRUE,
  verbose = TRUE,
  left_time = NULL,
  right_time = NULL,
  ...
)
}
\arguments{
\item{time}{Outcome vector of (non-negative) survival times. Required for
right-censored outcomes; set to \code{NULL} when using interval censoring.}

\item{status}{Event indicator (1 = event, 0 = censored). Required for
right-censored outcomes; derived automatically for interval censoring.}

\item{X_train}{Design matrix for training data.}

\item{treatment}{Treatment indicator (0/1) for training data.}

\item{timescale}{Either \code{"time"} (log-transform internally) or
\code{"log"} (already log-transformed).}

\item{propensity}{Optional vector of propensity scores. If provided,
it is appended to the control forest design matrix. Required when
\code{treatment_coding = "adaptive"}.}

\item{treatment_coding}{Character string specifying how the treatment
indicator enters the model. One of \code{"centered"} (default, maps to
\eqn{-1/2} and \eqn{1/2}), \code{"binary"} (maps to \eqn{0} and \eqn{1}),
\code{"adaptive"} (maps to \eqn{z_i - \hat{e}(x_i)}, where
\eqn{\hat{e}(x_i)} is the propensity score), or \code{"invariant"}
(parameter-expanded coding with \eqn{b_0, b_1 \sim N(0, 1/2)} estimated
within the Gibbs sampler; Hahn et al., 2020, Section 5.2).}

\item{a_dir}{First shape parameter of the Beta prior controlling the
sparsity level in the Dirichlet splitting rule.}

\item{b_dir}{Second shape parameter of the Beta prior controlling the
sparsity level in the Dirichlet splitting rule.}

\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 50.}

\item{power_control, base_control}{Tree-structure prior parameters for the
control forest.}

\item{power_treat, base_treat}{Tree-structure prior parameters for the
treatment forest.}

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

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

\item{store_posterior_sample}{Logical; if \code{TRUE} (default), store
the full \eqn{N_\text{post} \times n} matrix of posterior predictions.
Required for \code{predict()}, \code{plot(type = "survival")} with full
posterior credible bands, and custom posterior analyses. Set to
\code{FALSE} to save memory when only posterior means are needed.}

\item{verbose}{Logical; print sampling progress.}

\item{left_time}{Optional numeric vector of left (lower) time boundaries
for interval-censored data. 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}. When provided together with
\code{right_time}, the model is fitted with
\code{outcome_type = "interval-censored"} and \code{time}/\code{status}
are ignored.}

\item{right_time}{Optional numeric vector of right (upper) time boundaries.
Use \code{Inf} for right-censored observations.}

\item{...}{Additional arguments passed to \code{\link{CausalShrinkageForest}}
to override default hyperparameters.}
}
\value{
An object of class \code{"CausalShrinkageForest"} fitted with
Dirichlet splitting priors and additional shrinkage.
}
\description{
Fits a survival version of a Bayesian Causal Forest (BCF) under an
accelerated failure time (AFT) model, combining Dirichlet splitting
priors with global-local shrinkage. Supports both right-censored and
interval-censored survival outcomes.
}
\details{
This wrapper extends \code{\link{SurvivalBCF}} by incorporating
Dirichlet sparsity in both the prognostic (control) and treatment
forests, while applying additional shrinkage to the control forest
via a half-Cauchy prior.

The SurvivalShrinkageBCF model decomposes the outcome as
\deqn{
  \log T = \mu(x) + a \cdot \tau(x) + \varepsilon,
}
where \eqn{\mu(x)} represents the prognostic (control) component and
\eqn{\tau(x)} the heterogeneous treatment effect.

In contrast to \code{SurvivalBCF}, this function:
\itemize{
\item Applies a Dirichlet splitting prior to both forests, inducing
structural sparsity in variable selection.
\item Combines Dirichlet sparsity with additional half-Cauchy shrinkage
in the control forest.
}

The Dirichlet prior follows the sparse splitting framework of Linero (2018),
where splitting probabilities are governed by a Beta-Dirichlet hierarchy.
The sparsity level is controlled by \code{a_dir} and \code{b_dir}.

Survival outcomes are modeled using an AFT formulation with censoring
handled via data augmentation. Both right-censored and interval-censored
data are supported. For interval-censored data, supply \code{left_time}
and \code{right_time} instead of \code{time} and \code{status}.
}
\examples{
set.seed(4)
n <- 30; p <- 5
X <- matrix(rnorm(n * p), ncol = p)
treatment <- rbinom(n, 1, 0.5)
log_T <- X[, 1] + treatment * (-0.5) + rnorm(n)
time <- exp(log_T)
status <- rbinom(n, 1, 0.7)

fit <- SurvivalShrinkageBCF(time = time, status = status, X_train = X,
                             treatment = treatment,
                             number_of_trees_control = 5,
                             number_of_trees_treat = 5,
                             N_post = 50, N_burn = 25,
                             verbose = FALSE)

# S3 methods
print(fit)
smry <- summary(fit)

# Posterior ATE with 95\% credible interval
cat("ATE:", round(smry$treatment_effect$ate, 3), "\n")

# Diagnostic and treatment-effect plots (requires ggplot2)
if (requireNamespace("ggplot2", quietly = TRUE)) {
  plot(fit, type = "trace")
  plot(fit, type = "cate")
}

# Interval-censored causal example
set.seed(14)
n <- 30; p <- 5
X <- matrix(rnorm(n * p), ncol = p)
treatment <- rbinom(n, 1, 0.5)
true_t <- exp(X[, 1] + treatment * (-0.5) + rnorm(n))
left_t  <- true_t * runif(n, 0.5, 1)
right_t <- true_t * runif(n, 1, 1.5)
exact <- sample(n, 10); left_t[exact] <- true_t[exact]; right_t[exact] <- true_t[exact]
rc <- sample(setdiff(seq_len(n), exact), 5); right_t[rc] <- Inf

fit_ic <- SurvivalShrinkageBCF(left_time = left_t, right_time = right_t,
                                X_train = X, treatment = treatment,
                                number_of_trees_control = 5,
                                number_of_trees_treat = 5,
                                N_post = 50, N_burn = 25, verbose = FALSE)

}
\references{
Caron, A., Baio, G., & Manolopoulou, I. (2022).
Shrinkage Bayesian Causal Forests for Heterogeneous Treatment Effects Estimation.
Journal of Computational and Graphical Statistics, 31(4), 1202--1214.
https://doi.org/10.1080/10618600.2022.2067549
}
\seealso{
Related models: \code{\link{SurvivalBCF}} (standard BART priors),
\code{\link{CausalShrinkageForest}} (general shrinkage priors),
\code{\link{CausalHorseForest}} (horseshoe prior).

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