Learner_hal is a Reference Class implementing the learner interface
used by Superlearner() and fit_learner().
Details
User-facing API: users should only initialize the learner and pass it
to Superlearner() / fit_learner(). The remaining methods documented below
are part of the internal learner interface and are not meant to be called
directly by users.
Wrapper role: this class provides a piecewise-constant hazard wrapper around
a HAL-style indicator-basis construction, estimated by L1-penalized Poisson
regression using a glmnet backend. The package-specific contribution is to
(i) construct the long-format Poisson representation with offsets for time at
risk, (ii) generate indicator bases compatible with piecewise hazards, and
(iii) forward backend fitting arguments supplied via ....
Model
Let \(0=t_0 < t_1 < \cdots < t_m\) denote time knots and define interval indicators \(I_k(t)=1\{t\in(t_k,t_{k+1}]\}\). The HAL piecewise-constant hazard model is $$ \lambda(t \mid x) = \sum_{k=0}^{m} I_k(t)\,\exp\{f(t,x)\}, $$ where \(f(t,x)\) is approximated by a finite linear combination of indicator basis functions.
Two-covariate illustration
Let \(x=(x_1,x_2)\) be two covariates and let \(t_0 < t_1 < \cdots < t_R\) be time grid points used to create step functions in time. Choose covariate cutpoints \(c_{1,1},\ldots,c_{1,K_1}\) for \(x_1\) and \(c_{2,1},\ldots,c_{2,K_2}\) for \(x_2\).
Define indicator bases: $$B_r(t) = 1\{t_r \le t\}$$ $$B_{1,p}(x) = 1\{c_{1,p} \le x_1\}$$ $$B_{2,q}(x) = 1\{c_{2,q} \le x_2\}$$
A main-effects HAL approximation on the log-hazard scale can be written as:
$$
f_\beta(t,x) = \beta_0
+ \sum_{r=1}^R \beta_r B_r(t)
+ \sum_{r=1}^R\sum_{p=1}^{K_1} \beta_{r,1,p} B_r(t) B_{1,p}(x)
+ \sum_{r=1}^R\sum_{q=1}^{K_2} \beta_{r,2,q} B_r(t) B_{2,q}(x).
$$
If max_degree >= 2, the learner additionally includes interaction bases such as
$$
\sum_{r=1}^R\sum_{p=1}^{K_1}\sum_{q=1}^{K_2}
\beta_{r,12,pq} B_r(t) B_{1,p}(x) B_{2,q}(x).
$$
How reference class parameters map to the model
covariatesCovariate columns used to build covariate indicator bases.
num_knotsControls the number of cutpoints per covariate used for indicator bases.
max_degreeMaximum interaction order included in the basis expansion.
interceptWhether the backend penalized regression includes an intercept term.
cross_validationIf
TRUE, selects the penalty level usingglmnet::cv.glmnet.maxit_prefitOptional
maxitvalue used for the initial HAL backend fit. Leave asNAto use the backend default.fit_argumentsAdditional arguments forwarded to the
glmnetbackend (e.g.nfolds).
Fields
covariates(character)Names of covariate columns used in the basis.
cross_validation(logical)Whether to use
cv.glmnetto select the penalty.intercept(logical)Backend intercept flag.
max_degree(integer)Maximum interaction order.
num_knots(numeric)Knots used for basis construction.
lambda_opt(numeric)Selected penalty level when using cross-validation.
maxit_prefit(numeric)Optional
maxitvalue used for the initial HAL backend fit.fit_arguments(list)Extra backend arguments forwarded to
glmnet.
Methods (internal learner interface)
initialize(...)Construct and configure the learner. This is the only method users should call.
hal_basis(...)Internal helper. Constructs HAL basis matrices and metadata for fitting.
hal_prepare_new(...)Internal helper. Builds prediction-time HAL basis matrices from fitted basis metadata.
private_fit(data, ...)Internal. Builds bases and fits the penalized Poisson model with offset
log(tij).private_fit_all_causes(data, ...)Internal. Fits penalized Poisson HAL models for all requested causes using a shared basis setup.
private_predictor(model, newdata, ...)Internal. Evaluates the fitted approximation and returns hazards on the response scale.