% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fit_learner.R
\name{fit_learner}
\alias{fit_learner}
\title{Fit a single base learner}
\usage{
fit_learner(
  data,
  learner,
  id = "id",
  stratified_k_fold = FALSE,
  status = "status",
  event_time = NULL,
  number_of_nodes = NULL,
  nodes = NULL,
  variable_transformation = NULL,
  ...
)
}
\arguments{
\item{data}{\code{data.frame}. Subject-level input data (one row per subject).}

\item{learner}{Reference-class learner object (e.g. from \code{\link[=Learner_glmnet]{Learner_glmnet()}},
\code{\link[=Learner_hal]{Learner_hal()}} or \code{\link[=Learner_gam]{Learner_gam()}}). Must implement a \verb{$private_fit(dt_long)}
method that fits the learner on long Poisson data for one cause.}

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

\item{stratified_k_fold}{\code{logical(1)}. Reserved argument for future fold strategy.
Currently ignored.}

\item{status}{\code{character(1)}. Name of the event-status column.
Must be coded with \code{0} = censoring and \verb{1,2,...,K} for event types (causes).
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/censoring time column.
Must be present in \code{data}.}

\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 (including
endpoints), then adds \code{0} if missing.}

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

\item{variable_transformation}{\code{list}/\code{character}/\code{formula} or \code{NULL}.
Optional transformations applied to the internally created long Poisson data
before fitting (via \code{apply_transformations()}).}

\item{...}{Additional arguments currently ignored.}
}
\value{
An object of class \code{base_learner}, i.e. a named \code{list} with:

\describe{
\item{model}{The \strong{learner object} that was fit (the input \code{learner}), stored
for later prediction. This contains the learner specification (e.g.,
covariates, tuning parameters).}

\item{learner_fit}{A \code{list} of fitted model objects, \strong{one per cause}.
Its length equals \code{data_info$n_crisks}. The list is created by splitting the
internally pre-processed long data by cause indicator \code{k} and calling
\code{model$private_fit()} on each split.

\itemize{
\item Names typically correspond to the cause labels \code{"1"}, \code{"2"}, ..., \code{"K"}.
\item Each element is \strong{learner-dependent}: e.g. for \code{Learner_glmnet} it
may be a \code{"glmnet"} (often wrapped, e.g. \code{"fishnet"}) fit; for other
learners it will be whatever \verb{$private_fit()} returns.
\item Each fitted object is trained on long Poisson data representing the
piecewise-constant hazard for that cause across the node intervals.
}}

\item{data_info}{A \code{list} of bookkeeping information needed for prediction and
interpretation:
\describe{
\item{id}{Identifier column name used.}
\item{status}{Status column name used.}
\item{event_time}{Event/censoring time column name used.}
\item{nodes}{Numeric vector of node cut points used for the piecewise grid
(includes \code{0} and is sorted). These are the interval boundaries used in
the long Poisson representation.}
\item{maximum_followup}{\code{max(data[[event_time]])}.}
\item{n_crisks}{Number of event types (causes) detected.
If censoring is present (\code{0} in \code{status}), then \verb{n_crisks = #unique(status) - 1};
otherwise \verb{n_crisks = #unique(status)}.}
\item{variable_transformation}{The transformation specification passed in
\code{variable_transformation} (or \code{NULL}).}
}}
}
}
\description{
Pre-processes subject-level time-to-event data into a long Poisson format on a
piecewise-constant time grid, then fits \strong{one} initialized learner object.
For competing risks, a separate model is fit for each event type (cause)
using the standard cause-specific Poisson likelihood on the long data.
}
\examples{
d <- simulateStenoT1(50, competing_risks = TRUE)
lrn <- Learner_glmnet(covariates = c("age", "value_LDL"),
                      lambda = 0,
                      cross_validation = FALSE)
bl <- fit_learner(d,
                  learner = lrn,
                  id = "id",
                  status = "status_cvd",
                  event_time = "time_cvd",
                  number_of_nodes = 4)

}
