% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ShrinkageTrees.R
\name{ShrinkageTrees}
\alias{ShrinkageTrees}
\title{General Shrinkage Regression Trees (ShrinkageTrees)}
\usage{
ShrinkageTrees(
  y = NULL,
  status = NULL,
  X_train,
  X_test = NULL,
  left_time = NULL,
  right_time = NULL,
  outcome_type = "continuous",
  timescale = "time",
  number_of_trees = 200,
  prior_type = "horseshoe",
  local_hp = NULL,
  global_hp = NULL,
  a_dirichlet = 0.5,
  b_dirichlet = 1,
  rho_dirichlet = NULL,
  power = 2,
  base = 0.95,
  p_grow = 0.4,
  p_prune = 0.4,
  nu = 3,
  q = 0.9,
  sigma = NULL,
  N_post = 1000,
  N_burn = 1000,
  delayed_proposal = 5,
  store_posterior_sample = TRUE,
  n_chains = 1,
  verbose = TRUE
)
}
\arguments{
\item{y}{Outcome vector. Numeric. Can represent continuous outcomes, binary
outcomes (0/1), or follow-up times for survival data. 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 censoring indicator vector (1 = event occurred,
0 = censored). Required if \code{outcome_type = "right-censored"}.
For interval-censored outcomes, this is derived automatically from
\code{left_time} and \code{right_time}.}

\item{X_train}{Covariate matrix for training. Each row corresponds to an
observation, and each column to a covariate.}

\item{X_test}{Optional covariate matrix for test data. If NULL, defaults to
the mean of the training covariates.}

\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{"binary"}, \code{"right-censored"}, or \code{"interval-censored"}.}

\item{timescale}{Indicates the scale of follow-up times. Options are
\code{"time"} (nonnegative follow-up times, will be log-transformed
internally) or \code{"log"} (already log-transformed). Used when
\code{outcome_type} is \code{"right-censored"} or
\code{"interval-censored"}.}

\item{number_of_trees}{Number of trees in the ensemble. Default is 200.}

\item{prior_type}{Type of prior on the step heights. Options include
\code{"horseshoe"}, \code{"horseshoe_fw"}, \code{"half-cauchy"},
\code{"standard"} and \code{"dirichlet"}.}

\item{local_hp}{Local hyperparameter controlling shrinkage on individual
step heights. Should typically be set smaller than 1 / sqrt(number_of_trees).
Required for \code{prior_type = "standard"}.}

\item{global_hp}{Global hyperparameter controlling overall shrinkage.
Must be specified for Horseshoe-type priors; ignored for
\code{prior_type = "half-cauchy"} or \code{"standard"}.}

\item{a_dirichlet}{First shape parameter of the Beta prior used in the
Dirichlet-Sparse splitting rule. Together with \code{b_dirichlet}, it
controls the expected sparsity level. Only when \code{prior_type = "dirichlet"}.}

\item{b_dirichlet}{Second shape parameter of the Beta prior for the
sparsity level. Larger values shrink splitting probabilities more strongly
toward uniform sparsity. Only when \code{prior_type = "dirichlet"}.}

\item{rho_dirichlet}{Sparsity hyperparameter. If left NULL, it defaults to
the number of covariates. Only when \code{prior_type = "dirichlet"}.}

\item{power}{Power parameter for the tree structure prior. Default is 2.0.}

\item{base}{Base parameter for the tree structure prior. Default is 0.95.}

\item{p_grow}{Probability of proposing a grow move. Default is 0.4.}

\item{p_prune}{Probability of proposing a prune move. Default is 0.4.}

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

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

\item{sigma}{Optional known value for error standard deviation. If NULL,
estimated from data.}

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

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

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

\item{store_posterior_sample}{Logical; whether to store posterior samples for
each iteration. Default is TRUE.}

\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{ShrinkageTrees} object,
so all existing \code{print}, \code{summary}, and \code{predict} methods
work without modification. On Windows, \code{mclapply} falls back to
sequential execution.}

\item{verbose}{Logical; whether to print verbose output. Default is TRUE.}
}
\value{
An S3 object of class "ShrinkageTrees" containing the following elements:
\describe{
\item{train_predictions}{Vector of posterior mean predictions on the
training data.}
\item{test_predictions}{Vector of posterior mean predictions on the test
data (or on mean covariate vector if \code{X_test} not provided).}
\item{sigma}{Vector of posterior samples of the error variance.}
\item{acceptance_ratio}{Average acceptance ratio across trees during
sampling.}
\item{train_predictions_sample}{Matrix of posterior samples of training
predictions (iterations in rows, observations in columns). Present only if
\code{store_posterior_sample = TRUE}.}
\item{test_predictions_sample}{Matrix of posterior samples of test
predictions. Present only if \code{store_posterior_sample = TRUE}.}
\item{train_probabilities}{Vector of posterior mean probabilities on the
training data (only for \code{outcome_type = "binary"}).}
\item{test_probabilities}{Vector of posterior mean probabilities on the
test data (only for \code{outcome_type = "binary"}).}
\item{train_probabilities_sample}{Matrix of posterior samples of training
probabilities (only for \code{outcome_type = "binary"} and if
\code{store_posterior_sample = TRUE}).}
\item{test_probabilities_sample}{Matrix of posterior samples of test
probabilities (only for \code{outcome_type = "binary"} and if
\code{store_posterior_sample = TRUE}).}
}
}
\description{
Fits a Bayesian Shrinkage Tree model with flexible global-local priors on the
step heights. This function generalizes \code{\link{HorseTrees}} by allowing
different global-local shrinkage priors on the step heights.
Supports continuous, binary, right-censored, and interval-censored outcomes.
}
\details{
This function is a flexible generalization of \code{HorseTrees}.
Instead of using a single Horseshoe prior, it allows specifying different
global–local shrinkage configurations for the tree step heights. 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{standard} prior (Chipman, George & McCulloch, 2010) corresponds to
the classical BART specification, where step heights are given a normal
prior with variance scaled by the number of trees. This prior does not
introduce a global shrinkage parameter and does not use global–local
structure.

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 with ShrinkageTrees, two priors
n <- 50
p <- 3
X <- matrix(runif(n * p), ncol = p)
X_test <- matrix(runif(n * p), ncol = p)
y <- X[, 1] + rnorm(n)

# Fit ShrinkageTrees with standard horseshoe prior
fit_horseshoe <- ShrinkageTrees(y = y,
                                X_train = X,
                                X_test = X_test,
                                outcome_type = "continuous",
                                number_of_trees = 5,
                                prior_type = "horseshoe",
                                local_hp = 0.1 / sqrt(5),
                                global_hp = 0.1 / sqrt(5),
                                N_post = 10,
                                N_burn = 5,
                                store_posterior_sample = TRUE,
                                verbose = FALSE)

# Fit ShrinkageTrees with half-Cauchy prior
fit_halfcauchy <- ShrinkageTrees(y = y,
                                 X_train = X,
                                 X_test = X_test,
                                 outcome_type = "continuous",
                                 number_of_trees = 5,
                                 prior_type = "half-cauchy",
                                 local_hp = 1 / sqrt(5),
                                 N_post = 10,
                                 N_burn = 5,
                                 store_posterior_sample = TRUE,
                                 verbose = FALSE)

# Posterior mean predictions
pred_horseshoe <- colMeans(fit_horseshoe$train_predictions_sample)
pred_halfcauchy <- colMeans(fit_halfcauchy$train_predictions_sample)

# Posteriors of the mean (global average prediction)
post_mean_horseshoe <- rowMeans(fit_horseshoe$train_predictions_sample)
post_mean_halfcauchy <- rowMeans(fit_halfcauchy$train_predictions_sample)

# Posterior mean prediction averages
mean_pred_horseshoe <- mean(post_mean_horseshoe)
mean_pred_halfcauchy <- mean(post_mean_halfcauchy)

# Example: Interval-censored survival outcome
n <- 50; p <- 3
X_ic <- matrix(rnorm(n * p), ncol = p)
true_t <- rexp(n, rate = exp(-X_ic[, 1]))
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 <- ShrinkageTrees(left_time = left_t, right_time = right_t,
                         X_train = X_ic,
                         outcome_type = "interval-censored",
                         prior_type = "horseshoe",
                         local_hp = 0.1 / sqrt(5),
                         global_hp = 0.1 / sqrt(5),
                         number_of_trees = 5,
                         N_post = 10, N_burn = 5,
                         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{HorseTrees}} (horseshoe prior),
\code{\link{CausalHorseForest}} (causal inference),
\code{\link{CausalShrinkageForest}} (causal, flexible prior).

Survival wrappers: \code{\link{SurvivalBART}}, \code{\link{SurvivalDART}}.

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