% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/SuperSurv.R
\name{SuperSurv}
\alias{SuperSurv}
\title{Super Learner for conditional survival functions}
\usage{
SuperSurv(
  time,
  event,
  X,
  newdata = NULL,
  new.times,
  event.library,
  cens.library,
  id = NULL,
  verbose = FALSE,
  control = list(),
  cvControl = list(),
  obsWeights = NULL,
  metalearner = "brier",
  selection = "ensemble",
  nFolds = 10,
  parallel = FALSE
)
}
\arguments{
\item{time}{Observed follow-up time.}

\item{event}{Observed event indicator.}

\item{X}{Training covariate data.frame.}

\item{newdata}{Test covariate data.frame for prediction (defaults to X).}

\item{new.times}{Times at which to obtain predicted survivals.}

\item{event.library}{Character vector of prediction algorithms for the event.}

\item{cens.library}{Character vector of prediction algorithms for censoring.}

\item{id}{Cluster identification variable.}

\item{verbose}{Logical. If TRUE, prints progress messages.}

\item{control}{List of control parameters for the Super Learner.}

\item{cvControl}{List of control parameters for cross-validation.}

\item{obsWeights}{Observation weights.}

\item{metalearner}{Character string specifying the optimizer (e.g., "brier" or "logloss").}

\item{selection}{Character. Specifies how the meta-learner combines the base models.
Use \code{"ensemble"} (default) to calculate a weighted average (convex combination)
of the base learners. Use \code{"best"} to act as a Discrete Super Learner, which
assigns a weight of 1.0 to the single model with the lowest cross-validated risk.}

\item{nFolds}{Number of cross-validation folds (default: 10).}

\item{parallel}{Logical. If TRUE, uses future.apply for parallel execution.}
}
\value{
A list of class \code{SuperSurv} containing:
\itemize{
\item \code{call}: The matched function call.
\item \code{event.predict}: Matrix of in-sample cross-validated survival predictions.
\item \code{cens.predict}: Matrix of in-sample cross-validated censoring predictions.
\item \code{eval.times}: Numeric vector of prediction evaluation times.
\item \code{event.coef}: Numeric vector of optimized ensemble weights for the event.
\item \code{cens.coef}: Numeric vector of optimized ensemble weights for censoring.
\item \code{event.library.predict}: 3D array of cross-validated predictions from individual event learners.
\item \code{event.libraryNames}: Data frame detailing the algorithms and screeners used.
\item \code{event.fitLibrary}: List of the fitted base learner models (if \code{saveFitLibrary = TRUE}).
\item \code{times}: The time grid used for evaluation.
}
}
\description{
Orchestrates the cross-validation, metalearner optimization, and prediction
for an ensemble of survival base learners.
}
\details{
\strong{Extending the learner library.} Custom base learners can be added by
defining a wrapper function and passing its name in \code{event.library} or
\code{cens.library}. A learner wrapper should accept \code{time},
\code{event}, \code{X}, \code{newdata}, \code{new.times},
\code{obsWeights}, \code{id}, and \code{...}, and should return a list with
\code{pred}, a numeric survival-probability matrix with
\code{nrow(newdata)} rows and \code{length(new.times)} columns, and
\code{fit}, the fitted object used for future prediction. If saved fits are
needed, give \code{fit} a class and provide a corresponding
\code{predict.<class>()} method that returns the same matrix shape.

Screening methods can also be supplied by name. A screener should accept the
training inputs and return a logical vector aligned with the columns of
\code{X}. See \code{vignette("extending-supersurv", package = "SuperSurv")}
for a practical custom learner and screener example.
}
\examples{
if (requireNamespace("glmnet", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:80, ]
  x_cols <- grep("^x", names(dat))[1:5]
  X <- dat[, x_cols, drop = FALSE]
  new.times <- seq(20, 120, by = 20)

  fit <- SuperSurv(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = X,
    new.times = new.times,
    event.library = c("surv.coxph", "surv.ridge"),
    cens.library = c("surv.coxph"),
    control = list(saveFitLibrary = TRUE)
  )

  fit
  event_weights(fit)
}
}
