% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bootstrap.R
\name{bootstrap_orthoMTL}
\alias{bootstrap_orthoMTL}
\title{Bootstrap Inference for orthoMTL Coefficients}
\usage{
bootstrap_orthoMTL(
  X,
  Y,
  lambda = 1,
  alpha = 0,
  step_size = 0.1,
  K = NULL,
  disjoint = FALSE,
  schedule = c("sqrt", "log", "const", "linear"),
  survival = FALSE,
  censored.mat = NULL,
  n_repeats = 100,
  n_cores = 2,
  seed = NULL,
  verbose = TRUE
)
}
\arguments{
\item{X}{A numeric matrix of predictor variables with dimensions
\code{n x p}.}

\item{Y}{A numeric matrix of response labels with dimensions
\code{n x numTasks}. May contain \code{NA} for censored
observations.}

\item{lambda}{Regularisation parameter for the orthogonal penalty.}

\item{alpha}{Elastic-net mixing parameter in \eqn{[0, 1]}, passed
through to \code{\link{orthoMTL}}. Default: \code{0}.}

\item{step_size}{Step size for gradient descent. Default: \code{0.1}.}

\item{K}{Constraint matrix of dimensions
\code{numTasks x numTasks}. Default: \code{NULL} (identity).}

\item{disjoint}{Logical. Enforce disjoint supports? Default:
\code{FALSE}.}

\item{schedule}{Character; the gradient-step decay schedule passed to
\code{\link{orthoMTL}} for every resample/permutation fit. One of
\code{"sqrt"} (default), \code{"log"}, \code{"const"}, \code{"linear"}.
Because bootstrap refits the model many times, switching to \code{"log"} or
\code{"const"} -- which reach the same optimum in far fewer iterations --
can substantially cut total runtime; see the \code{schedule} argument of
\code{\link{orthoMTL}} for details.}

\item{survival}{Logical. Use censored survival loss? Default:
\code{FALSE}.}

\item{censored.mat}{A numeric indicator matrix of dimensions
\code{n x numTasks}. Required when \code{survival = TRUE}.}

\item{n_repeats}{Number of bootstrap/permutation repeats. Default:
\code{100}.}

\item{n_cores}{Number of cores for parallel execution. Default:
\code{2}.}

\item{seed}{Optional base random seed. Default: \code{NULL} (no seed
is set; repeats vary via the ambient RNG state and the run is not
reproducible). If supplied, repeat \code{i} uses
\code{set.seed(seed + i)} for \code{i} in \code{1:n_repeats}, so the
whole run becomes reproducible while still varying across repeats.}

\item{verbose}{Logical. Print progress information? Default:
\code{TRUE}.}
}
\value{
An object of class \code{"bootstrap_orthoMTL"} containing:
  \describe{
    \item{results}{A tidy \code{data.frame} with columns \code{id}
      (feature name), \code{time} (task/threshold), \code{coeff}
      (coefficient value), \code{group} (\code{"real"} or
      \code{"null"}), and \code{repeat_id} (integer).}
    \item{coefficients_real}{A list of \code{n_repeats} coefficient
      matrices (each \code{p x numTasks}).}
    \item{coefficients_null}{A list of \code{n_repeats} coefficient
      matrices from permuted outcomes.}
    \item{obj_real}{Numeric vector of final objective values for
      real bootstrap models.}
    \item{obj_null}{Numeric vector of final objective values for
      null permutation models.}
    \item{n_repeats}{Number of repeats.}
    \item{n_features}{Number of features.}
    \item{n_tasks}{Number of tasks.}
    \item{feature_names}{Character vector of feature names.}
    \item{task_names}{Character vector of task names.}
    \item{call}{The matched function call.}
  }
}
\description{
Estimates coefficient variability and statistical relevance by
comparing bootstrapped models (real signal) against null models
(permuted outcomes). This two-pronged approach answers: (1) how
stable is each coefficient across resamples, and (2) is each
coefficient distinguishable from what would be obtained by chance.
}
\details{
\strong{Real bootstrap}: For each repeat, rows of \code{X}, \code{Y},
and \code{censored.mat} are resampled \emph{with replacement}. The
model is refit with identical hyperparameters. This produces a
distribution of coefficient values reflecting estimation variability.

\strong{Null permutation}: For each repeat, rows of \code{Y} and
\code{censored.mat} are permuted \emph{without replacement} while
\code{X} remains fixed. This breaks the association between features
and outcomes, producing a null distribution of coefficients.

Comparing real vs null distributions for each feature and task
indicates whether observed coefficients are distinguishable from
noise. Visualise with \code{\link{plot_bootstrap}}.
}
\examples{
\donttest{
set.seed(42)
n <- 30; p <- 5; n_tasks <- 3
X <- matrix(rnorm(n * p), n, p)
colnames(X) <- paste0("V", seq_len(p))
SurvTime <- rexp(n, rate = 0.1)
Event <- rbinom(n, 1, 0.7)
thresholds <- c(4, 6, 10)

Y <- create_longitudinal_labels(SurvTime, Event, thresholds)
W <- create_indicator_matrix(Y)
K <- create_constraint_matrix(n_tasks)

boot_res <- bootstrap_orthoMTL(
  X = X, Y = Y, lambda = 1e-3, step_size = 0.1,
  K = K, survival = TRUE, censored.mat = W,
  n_repeats = 5, n_cores = 1, verbose = FALSE
)

print(boot_res)
head(boot_res$results)
}
}
\seealso{
\code{\link{orthoMTL}}, \code{\link{plot_bootstrap}}
}
