% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/predict.R
\name{predict.poisson_superlearner}
\alias{predict.poisson_superlearner}
\title{Predict hazards, survival and absolute risk from a fitted Poisson Super Learner}
\usage{
\method{predict}{poisson_superlearner}(object, newdata, times, cause = 1, model = "sl", ...)
}
\arguments{
\item{object}{\code{poisson_superlearner}. A fitted ensemble from \code{\link[=Superlearner]{Superlearner()}}.}

\item{newdata}{\code{data.frame}/\code{data.table}. New covariate data (one row per subject).
If \code{newdata} contains the original \code{event_time}, \code{status}, or \code{id} columns used
for fitting, they are ignored for prediction.}

\item{times}{\code{numeric}. Prediction horizon(s). May include \code{0}.
Times larger than \code{object$data_info$maximum_followup} are not supported:
if \strong{all} requested times exceed the maximum follow-up, a warning is issued and
\code{NULL} is returned; if only \strong{some} exceed, output rows for those times are
returned with \code{NA} predictions.}

\item{cause}{\code{numeric(1)}. Cause index (1, 2, ...) used for the \code{absolute_risk}
calculation.}

\item{model}{Scalar model selector. Default is \code{"sl"} for the stacked super learner.
Other allowed values are:
\describe{
\item{\code{0} or \code{"sl"}}{Use the super learner prediction.}
\item{learner label}{Use one stored base learner by its label in
\code{object$data_info$learners_labels}.}
\item{\code{"learner_j"}}{Use the \code{j}-th stored learner.}
\item{integer \code{j >= 1}}{Use the \code{j}-th stored learner.}
}
Numeric positions refer to the learners actually stored in the fitted object.}

\item{...}{Additional arguments (currently ignored).}
}
\value{
A \code{data.table} with one row per \verb{(row in newdata, time in times)} and columns:
\describe{
\item{(original columns)}{All columns from \code{newdata} (excluding ignored event columns).}
\item{time column}{A column with name \code{object$data_info$event_time} holding the requested horizon.}
\item{pwch_1, pwch_2, ...}{Predicted cause-specific piecewise hazards at the horizon.}
\item{survival_function}{Predicted survival probability at the horizon.}
\item{absolute_risk}{Predicted cumulative incidence (absolute risk) for \code{cause} at the horizon.}
}
}
\description{
Computes \strong{cause-specific piecewise-constant hazards} (\code{pwch_k}), the corresponding
\strong{survival function}, and \strong{absolute risk} for a given cause, at user-supplied
prediction horizons \code{times}, for each row in \code{newdata}.
}
\details{
Internally, \code{newdata} is expanded to a Cartesian product with the requested
\code{times}, converted to long Poisson format on \code{object$data_info$nodes}, and hazards
are predicted either from the stacked super learner (\code{model = "sl"}) or from one
selected fitted base learner. Survival and absolute risk are then computed from
the predicted hazards.

\strong{Special case \code{times = 0}:} when \code{0} is included in \code{times}, the returned rows
have \code{survival_function = 1}, \code{absolute_risk = 0}, and all \code{pwch_k = 0} at time 0.

\strong{Identifiers in the output:} if \code{newdata} contains the \code{id} column, it is carried
into the output. If \code{newdata} does not contain an id column, an internal id is
created for computation, but it is not guaranteed to appear in the returned table
unless it was present in \code{newdata}.
}
\examples{
d <- simulateStenoT1(30, competing_risks = TRUE)

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

fit <- Superlearner(
  data = d,
  id = "id",
  status = "status_cvd",
  event_time = "time_cvd",
  learners = learners,
  number_of_nodes = 3,
  nfold = 2
)
p <- predict(fit, newdata = d[1:3], times = c(0, 2), cause = 1)
p[, .(id, time_cvd, absolute_risk)]


}
