% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/learners.R
\docType{class}
\name{Learner_gam-class}
\alias{Learner_gam-class}
\alias{Learner_gam}
\title{GAM learner via \code{mgcv::bam}}
\arguments{
\item{covariates}{\code{character}. Right-hand-side terms, including \code{mgcv} smooths
(e.g. \code{"s(age)"}) and/or linear terms (e.g. \code{"value_LDL"}).}

\item{cross_validation}{\code{logical}. Included for compatibility with the learner
interface; smoothing selection is controlled by \code{mgcv} and arguments in \code{...}.}
}
\description{
\code{Learner_gam} is a Reference Class implementing the learner interface
used by \code{\link[=Superlearner]{Superlearner()}} and \code{\link[=fit_learner]{fit_learner()}}.
}
\details{
\strong{User-facing API:} users should \strong{only initialize} the learner and pass it
to \code{\link[=Superlearner]{Superlearner()}} / \code{\link[=fit_learner]{fit_learner()}}. The methods \code{private_fit()} and
\code{private_predictor()} are part of the internal learner interface and are
\strong{not meant to be called directly by users}.

\strong{Wrapper role:} this class wraps \code{mgcv::bam} in a piecewise-constant hazard
workflow. The package-specific contribution is to provide a convenient
interface for the long-format Poisson likelihood with offsets for time at risk,
and optional node terms encoding the baseline hazard, while forwarding standard
\code{mgcv::bam} arguments supplied via \code{...}.
}

\section{Model}{

Let \eqn{0=t_0 < t_1 < \cdots < t_m}{0=t0 < t1 < ... < tm} denote time knots and
define interval indicators \eqn{I_k(t)=1\{t\in(t_k,t_{k+1}]\}}{Ik(t)=I(t in (tk, t{k+1}])}.
The piecewise-constant hazard model with an additive predictor is
\deqn{
  \lambda(t \mid x) = \sum_{k=0}^{m} I_k(t)\,\exp\{\eta(x) + \gamma_k\}.
}{
  lambda(t|x) = sum_{k=0}^m Ik(t) * exp(eta(x) + gamma_k).
}
The additive predictor \eqn{\eta(x)}{eta(x)} is constructed from \code{covariates}
(smooth terms such as \code{s(age)} and/or linear terms) and estimated by \code{mgcv}.
}

\section{Fields}{

\describe{
\item{\code{covariates} (\code{character})}{Terms used to build the additive predictor (may include \code{s()} terms).}
\item{\code{cross_validation} (\code{logical})}{Workflow flag; see Details.}
\item{\code{intercept} (\code{logical})}{Whether to include an intercept.}
\item{\code{add_nodes} (\code{logical})}{If \code{TRUE}, include interval ("node") effects encoding the baseline hazard.}
\item{\code{formula} (\code{character})}{Formula string passed to \code{mgcv::bam}.}
\item{\code{learner} (\code{function})}{Backend fitter (\code{mgcv::bam}).}
\item{\code{fit_arguments} (\code{list})}{Additional arguments forwarded to \code{mgcv::bam}.}
}
}

\section{Methods (internal learner interface)}{

\describe{
\item{\code{initialize(...)}}{Construct and configure the learner. This is the only method users should call.}
\item{\code{private_fit(data, ...)}}{Internal. Fits a Poisson GAM with offset \code{log(tij)} on long-format data.}
\item{\code{private_predictor(model, newdata, ...)}}{Internal. Predicts hazards on the response scale.}
}
}

\examples{
lrn <- Learner_gam(covariates = c("s(age)", "value_LDL"))

}
