% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/superlearner.R
\name{Superlearner}
\alias{Superlearner}
\title{Fit a Poisson Super Learner ensemble}
\usage{
Superlearner(
  data,
  id = "id",
  status = "status",
  event_time = NULL,
  learners,
  number_of_nodes = NULL,
  nodes = NULL,
  variable_transformation = NULL,
  nfold = 3,
  ...
)
}
\arguments{
\item{data}{\code{data.frame}. Subject-level input data, one row per subject.}

\item{id}{\code{character(1)}. Name of the subject identifier column. If missing,
an \code{id} column is created automatically.}

\item{status}{\code{character(1)}. Name of the event-status column. It must be coded
with \code{0} for censoring and \verb{1, 2, ..., K} for event types. If there is no
\code{0} in \code{status}, the data are treated as uncensored.}

\item{event_time}{\code{character(1)}. Name of the event or censoring time column.}

\item{learners}{\code{list}. List of initialized learner reference-class objects,
for example \code{\link[=Learner_glmnet]{Learner_glmnet()}}, \code{\link[=Learner_hal]{Learner_hal()}}, or \code{\link[=Learner_gam]{Learner_gam()}}. If
unnamed, learners are named \code{"learner_1"}, \code{"learner_2"}, and so on. Each
learner must implement \verb{$private_fit(dt_long)} and
\verb{$private_predictor(model, newdata)}.}

\item{number_of_nodes}{\code{numeric(1)} or \code{NULL}. If not \code{NULL}, constructs a
quantile-based node grid with \code{number_of_nodes + 1} cut points. Ignored when
\code{nodes} is supplied.}

\item{nodes}{\code{numeric} or \code{NULL}. Explicit time-node grid. If supplied,
\code{number_of_nodes} is ignored. \code{0} is added if missing, and nodes larger than
\code{max(event_time)} are dropped.}

\item{variable_transformation}{Optional transformation specification passed to
\code{apply_transformations()} on the internally created long-format data.}

\item{nfold}{\code{numeric(1)}. Number of folds for cross-validation stacking.}

\item{...}{Additional arguments currently ignored.}
}
\value{
An object of class \code{poisson_superlearner}, stored as a named \code{list}
with the following components:

\code{learners}:
the retained base learner objects.

\code{metalearner}:
the meta-learner object used for stacking. If no stacking is performed because
only one learner remains, \code{metalearner} is \code{NULL}.

\code{superlearner}:
a \code{list} of length \code{data_info$n_crisks}, one entry per cause. For cause \code{k},
\code{superlearner[[k]]} is a \code{list} with two elements:
\itemize{
\item \code{learners_fit}: the fitted base learner object or objects for cause \code{k}.
If more than one learner is retained, this is a \code{list} with one fitted
object per retained learner. If only one learner remains, this is the
single fitted learner object itself.
\item \code{meta_learner_fit}: the fitted cause-specific meta-learner for cause
\code{k}. If no stacking is performed, this is \code{NULL}.
}

\code{cross_validation_deviance}:
a \code{data.table} with columns \code{learner} and \code{deviance}, giving the mean
cross-validated Poisson deviance for each retained base learner. This
component is present when cross-validated model comparison is available.

\code{data_info}:
a \code{list} of bookkeeping information used for prediction and interpretation,
containing:
\itemize{
\item \code{id}: identifier column name used.
\item \code{status}: status column name used.
\item \code{event_time}: event-time column name used.
\item \code{nodes}: numeric vector of node cut points used for the piecewise grid.
\item \code{nfold}: number of folds used for stacking.
\item \code{maximum_followup}: maximum observed follow-up time.
\item \code{n_crisks}: number of event types detected.
\item \code{learners_labels}: character vector of retained learner labels.
\item \code{variable_transformation}: the transformation specification passed in
\code{variable_transformation}, or \code{NULL}.
}
}
\description{
Fits an ensemble of cause-specific piecewise-constant hazard models using a
long-format Poisson representation and combines them through a meta-learner
(stacking).
}
\details{
Internally, the function:
\enumerate{
\item builds a time grid (\code{nodes}) and converts the subject-level data to a
long Poisson format;
\item fits each base learner once on the full long data for each cause;
\item removes learners that already fail on the full data;
\item uses \code{nfold} cross-validation to obtain out-of-sample base-learner
predictions (\code{Z1}, \code{Z2}, ...) for stacking;
\item removes learners whose cross-validated prediction column is entirely
missing for at least one cause;
\item fits a cause-specific meta-learner on the retained stacked predictions.
}

If all learners fail on the full data, the function stops with an error.
If only one learner remains after the full-data screening step or after the
cross-validation screening step, no meta-learner is fit. In that case,
\code{metalearner} is \code{NULL}, each \code{superlearner[[k]]$meta_learner_fit} is \code{NULL},
and prediction is based directly on the stored fitted base learner.Numeric
learner positions always refer to the learners actually retained in the
fitted object.
}
\examples{
data <- simulateStenoT1(50, competing_risks = TRUE)

learners <- list(
  glm = Learner_glmnet(
    covariates = c("sex", "value_LDL"),
    lambda = 0,
    cross_validation = FALSE
  ),
  ridge = Learner_glmnet(
    covariates = c("sex", "value_LDL"),
    alpha = 0,
    lambda = 0.01,
    cross_validation = FALSE
  )
)

fit <- Superlearner(
  data = data,
  id = "id",
  status = "status_cvd",
  event_time = "time_cvd",
  learners = learners,
  number_of_nodes = 3,
  nfold = 2
)

}
