swjm: Stagewise Variable Selection for Joint Models of Semi-Competing Risks

Description

Implements stagewise regression for penalized variable selection in joint models of recurrent events and terminal events (semi-competing risks).

Two model frameworks are supported:

• Joint Frailty Model (JFM): Cox-type model where alpha = recurrence/readmission coefficients (first p elements of theta), beta = terminal/death coefficients (second p elements).

• Joint Scale-Change Model (JSCM): AFT-type model where alpha = recurrence/readmission coefficients (first p elements of theta), beta = terminal/death coefficients (second p elements).

Three penalty types are available:

• "coop": Cooperative lasso, which encourages shared support between the recurrence and terminal event coefficient vectors.

• "lasso": Standard L1 penalty applied coordinate-wise.

• "group": Group lasso, which selects variables jointly across both processes.

Data Format

All functions expect a recurrent-event data frame with the following columns:

id

Subject identifier (integer).

t.start

Interval start time.

t.stop

Interval stop time.

event

1 for recurrent event, 0 for terminal/censoring row.

status

1 for death, 0 for alive/censored.

x1, x2, ..., xp

Covariate columns.

Author(s)

Maintainer: Jared D. Huling jaredhuling@gmail.com

Authors:

• Lingfeng Huo

• Ziren Jiang

• Jue Hou

Other contributors:

• Sy Han (Steven) Chiou [contributor]

• Chiung-Yu Huang [contributor]

Cumulative Baseline Hazard Step Functions

Description

Evaluates the cumulative baseline hazards for readmission and death at arbitrary time points. For JFM, Breslow-type estimators are used. For JSCM, Nelson-Aalen estimators on the accelerated time scale are used.

Usage

baseline_hazard(
  object,
  times = NULL,
  which = c("both", "readmission", "death")
)

Arguments

Value

A data frame with column time and, depending on which, cumhaz_readmission and/or cumhaz_death.

Examples

dat <- generate_data(n = 50, p = 10, scenario = 1, model = "jfm")
cv  <- cv_stagewise(dat$data, model = "jfm", penalty = "coop",
                    max_iter = 100)
bh  <- baseline_hazard(cv)
head(bh)

Compute the Cooperative Lasso Norm

Description

For each pair (theta_j, theta_(j+p)), computes the cooperative lasso norm: L2 norm if signs agree, L1 norm if signs disagree.

Usage

coop_norm(theta, p)

Arguments

Value

Scalar cooperative lasso norm value.

Count Leading Zeros After Decimal Point

Description

Used for adaptive step size computation. Returns the position of the first non-zero digit after the decimal point.

Usage

count_digits(num)

Arguments

Value

Integer count of leading zeros after the decimal point.

Create Stratified K-Fold Splits

Description

Randomly assigns a vector of IDs into K approximately equal-sized folds.

Usage

create_folds(ids, K)

Arguments

Value

A list of length K, where each element contains the IDs assigned to that fold.

Cumulative Hazard from Estimated Baseline Hazards (JFM)

Description

Computes subject-specific cumulative hazards for recurrent events using estimated baseline hazard point masses and the pseudo data approach.

Usage

cumulative_hazard_jfm(t.start, I, Z, beta, tr, lambda0_r, tr.id)

Arguments

Value

A list with components:

Cumulative Hazard Under True Baseline Hazard (JFM)

Description

Computes the cumulative hazard at time x under piecewise-constant baseline hazard with known cut points and covariate values.

Usage

cumulative_hazard_true_jfm(x, cut_points, z_values, beta)

Arguments

Value

Scalar cumulative hazard value.

Cross-Validation for Stagewise Variable Selection

Description

Selects the optimal penalty parameter (lambda) along the stagewise path using K-fold cross-validation with cross-fitted estimating equations.

Usage

cv_stagewise(
  data,
  model = c("jfm", "jscm"),
  penalty = c("coop", "lasso", "group"),
  K = 5L,
  lambda_seq = NULL,
  eps = NULL,
  max_iter = NULL,
  pp = NULL,
  estimate_frailty = FALSE,
  ncores = 1L,
  standardize = TRUE
)

Arguments

Value

An object of class "swjm_cv", a list with components:

position_CF

Integer, position of best lambda by combined cross-fitted score norm.

position_CF_re

Integer, position of best lambda by recurrence score norm.

position_CF_cen

Integer, position of best lambda by terminal score norm.

lambda_seq

Numeric vector of lambda values evaluated.

Scorenorm_crossfit

Combined cross-fitted score norm path.

Scorenorm_crossfit_re

Recurrence score norm path.

Scorenorm_crossfit_ce

Terminal score norm path.

full_fit

The full-data stagewise fit (class "swjm_path").

model

Character.

penalty

Character.

Examples

dat <- generate_data(n = 50, p = 10, scenario = 1, model = "jfm")
fit <- stagewise_fit(dat$data, model = "jfm", penalty = "coop",
                     max_iter = 100)
cv_res <- cv_stagewise(dat$data, model = "jfm", penalty = "coop",
                       lambda_seq = fit$lambda, max_iter = 100)
cv_res

Extract Common Data Components from a Recurrent-Event Data Frame

Description

Parses a standard recurrent-event data frame into the components needed by the JFM estimating equations: covariate lists, event times, at-risk indicators, etc.

Usage

extract_data_components(Data2)

Arguments

Value

A list with components:

Extract Decreasing Lambda Path

Description

Post-processes a raw lambda sequence from the stagewise algorithm to keep only strictly decreasing values (via running minimum and deduplication).

Usage

extract_decreasing_indices(lambda, tol_digits = 6L)

Arguments

Value

An integer vector of indices into the original lambda vector corresponding to the strictly decreasing subsequence.

Generate Simulated Data for Joint Models

Description

Unified interface that dispatches to model-specific data generation functions for the joint frailty model (JFM) or joint scale-change model (JSCM).

Usage

generate_data(n, p, scenario = 1, model = c("jfm", "jscm"), ...)

Arguments

Value

A list with components:

data

A data frame in recurrent-event format with columns id, t.start, t.stop, event, status, and covariate columns x1, ..., xp.

alpha_true

Numeric vector of true alpha coefficients.

beta_true

Numeric vector of true beta coefficients.

Examples

# JFM data with 30 subjects and 10 covariates
dat_jfm <- generate_data(n = 30, p = 10, scenario = 1, model = "jfm")
head(dat_jfm$data)

# JSCM data with 30 subjects and 10 covariates
dat_jscm <- generate_data(n = 30, p = 10, scenario = 1, model = "jscm")
head(dat_jscm$data)

Generate Simulated Data for the Joint Frailty Model (JFM)

Description

Generates recurrent-event and terminal-event data under a Cox-type joint frailty model. Ported from Data_Generation_time_dependent_new().

Usage

generate_data_jfm(
  n,
  p,
  scenario = 1,
  b = 6.5,
  lambda0_d = 0.041,
  lambda0_r = 1,
  gamma_frailty = 0,
  cov_type = c("internal", "external", "fixed")
)

Arguments

Details

Internally the simulation uses the Rondeau et al. (2007) convention where alpha governs death and beta governs recurrence. The returned alpha_true and beta_true are relabelled to match the package-wide convention:

• alpha_true: recurrence (readmission) coefficients.

• beta_true: terminal (death) coefficients.

Within each subject the covariates are regenerated at each gap time, yielding time-dependent covariates. Censoring times are Uniform(1, b).

Value

A list with components:

data

Data frame with columns id, t.start, t.stop, event, status, x1, ..., xp.

alpha_true

True alpha (terminal) coefficients.

beta_true

True beta (recurrence) coefficients.

Examples

dat <- generate_data_jfm(n = 30, p = 10, scenario = 1)
head(dat$data)
dat$alpha_true
dat$beta_true

Generate Simulated Data for the Joint Scale-Change Model (JSCM)

Description

Generates recurrent-event and terminal-event data under an AFT-type joint scale-change model using simGSC. Ported from Data_gen_reReg().

Usage

generate_data_jscm(n, p, scenario = 1, b = 4)

Arguments

Details

In the JSCM convention:

• alpha governs the recurrence process.

• beta governs the terminal (death) process.

Covariates are drawn from Uniform(-1, 1). A gamma frailty with shape = 4, scale = 1/4 is used. Censoring times are Uniform(0, b).

Value

A list with components:

data

Object returned by simGSC (a data frame with recurrent-event structure).

alpha_true

True alpha (recurrence) coefficients.

beta_true

True beta (terminal) coefficients.

Examples

dat <- generate_data_jscm(n = 30, p = 10, scenario = 1)
head(dat$data)
dat$alpha_true
dat$beta_true

Compute Exit Times for Pseudo-Entries

Description

For each row in the sorted pseudo-data matrix, computes the exit time: non-last entries for a subject exit at the next entry's start time; the last entry exits at Y_i (the subject's observation time).

Usage

jfm_compute_exit_times(pseudo_entries, Y)

Arguments

Value

Numeric vector of exit times, one per pseudo-entry row.

Flag Last Pseudo-Entry per Subject

Description

Returns a logical vector indicating whether each pseudo-entry is the last entry for its subject. Used for tie-breaking in timeline construction.

Usage

jfm_compute_is_last(pseudo_entries)

Arguments

Value

Logical vector, one per pseudo-entry row.

Counting Process of Recurrent Event

Description

Computes the value of the counting process N_i(t), i.e., the number of recurrent events that occurred at or before time t.

Usage

jfm_counting_process(t, recur_time)

Arguments

Value

Integer count of recurrent events at or before time t.

Estimating Equation for Theta

Description

Evaluates the estimating equation for the frailty variance parameter theta.

Usage

jfm_est_theta(
  td_id,
  r2i_death_subject_matrix,
  td,
  Y,
  STATUS,
  list_recur,
  theta,
  num_recur
)

Arguments

Value

Scalar value of the estimating equation for theta.

Theta Estimating Equation for the Stagewise Algorithm

Description

Self-contained version of the theta estimating equation that rebuilds all intermediate quantities (wt_matrix, r2i, G-bar) internally, used as the objective in a root-finding procedure for theta.

Usage

jfm_est_theta_new(
  theta,
  t.start,
  I,
  Z,
  alpha,
  beta,
  lambda0_r,
  lambda0_d,
  td,
  tr,
  tr.id,
  td.id,
  Y,
  STATUS,
  list_recur,
  num_recur
)

Arguments

Value

Scalar value of the scaled estimating equation for theta.

Extract Event Pseudo-Entry Indices

Description

For each event time, extracts the pseudo-entry row index for the subject who experienced the event. Returns a 0-based integer vector suitable for passing to C++ score functions.

Usage

jfm_event_pseudo_idx(index_matrix, event_subject_ids)

Arguments

Value

Integer vector (length ne) of 0-based pseudo-entry row indices.

Inverse CDF of Exponential Distribution

Description

Computes the quantile function (inverse CDF) of an exponential distribution for simulation purposes.

Usage

jfm_exp_icdf(y, rate)

Arguments

Value

Numeric value(s) corresponding to the inverse CDF.

G-bar(t) Evaluated at Each Death Time

Description

Computes the ratio G-bar(t) at each death event time, used in the estimating equation for theta.

Usage

jfm_gt_bar_death(r2i_death_subject_matrix, td, Y, STATUS, list_recur)

Arguments

Value

A matrix (1 row) of G-bar values, one per death time.

Solve for Baseline Death Hazard lambda0_d

Description

Computes the closed-form solution for the baseline hazard point masses of the death sub-model.

Usage

jfm_lambda0d_solution(td, d_td, n, S0t_de)

Arguments

Value

Named numeric vector of baseline hazard point masses for death.

Solve for Baseline Recurrence Hazard lambda0_r

Description

Computes the closed-form solution for the baseline hazard point masses of the recurrence sub-model.

Usage

jfm_lambda0r_solution(tr, d_tr, n, S0t_re)

Arguments

Value

Named numeric vector of baseline hazard point masses for recurrence.

R2i(t) Evaluated at Each Death Time for Each Subject

Description

Computes R2i(t) for each subject at each death event time, by combining the recurrent event integral with the weight matrix.

Usage

jfm_r2i_death(t.start, I, Z, beta, tr, lambda0_r, td, wt_matrix, tr.id)

Arguments

Value

A list with components:

Integral in R2i(t) Evaluated at Each Recurrent Event Time

Description

Computes the integral component of R2i(t) for each subject at each recurrent event time, using the pseudo data set approach.

Usage

jfm_r2i_integral(t.start, I, Z, beta, tr, lambda0_r, tr.id)

Arguments

Value

A list with components:

S0(t) for Death Sub-Model

Description

Computes the weighted zeroth moment S0(t) at each death event time for the death sub-model.

Usage

jfm_s0t_death(Y, wt_matrix, td, index_death_matrix, pseudo_entries, alpha)

Arguments

Value

Numeric vector of S0(t) values, one per death time.

S0(t) for Death Sub-Model with Cross-Fitting

Description

Computes the weighted zeroth moment S0(t) at each death event time for the death sub-model, using fold-specific alpha coefficients for cross-fitting.

Usage

jfm_s0t_death_cf(
  Y,
  wt_matrix,
  td,
  index_death_matrix,
  pseudo_entries,
  alpha_mat,
  CV_map
)

Arguments

Value

Numeric vector of S0(t) values, one per death time.

S0(t) for Recurrent Event Sub-Model

Description

Computes the weighted zeroth moment S0(t) at each recurrent event time for the recurrence sub-model.

Usage

jfm_s0t_recurrent(
  Y,
  wt_recurrent_subject,
  tr,
  index_recurrent_matrix,
  pseudo_entries,
  beta
)

Arguments

Value

Numeric vector of S0(t) values, one per recurrent event time.

S0(t) for Recurrent Event Sub-Model with Cross-Fitting

Description

Computes the weighted zeroth moment S0(t) at each recurrent event time for the recurrence sub-model, using fold-specific beta coefficients for cross-fitting.

Usage

jfm_s0t_recurrent_cf(
  Y,
  wt_recurrent_subject,
  tr,
  index_recurrent_matrix,
  pseudo_entries,
  beta_mat,
  CV_map
)

Arguments

Value

Numeric vector of S0(t) values, one per recurrent event time.

S1(t) for Death Sub-Model

Description

Computes the weighted first moment S1(t) at each death event time for the death sub-model.

Usage

jfm_s1t_death(Y, wt_matrix, td, index_death_matrix, pseudo_entries, alpha)

Arguments

Value

Matrix of S1(t) values (rows = covariates, cols = death times).

S1(t) for Death Sub-Model with Cross-Fitting

Description

Computes the weighted first moment S1(t) at each death event time for the death sub-model, using fold-specific alpha coefficients for cross-fitting.

Usage

jfm_s1t_death_cf(
  Y,
  wt_matrix,
  td,
  index_death_matrix,
  pseudo_entries,
  alpha_mat,
  CV_map
)

Arguments

Value

Matrix of S1(t) values (rows = covariates, cols = death times).

S1(t) for Recurrent Event Sub-Model

Description

Computes the weighted first moment S1(t) at each recurrent event time for the recurrence sub-model.

Usage

jfm_s1t_recurrent(
  Y,
  wt_recurrent_subject,
  tr,
  index_recurrent_matrix,
  pseudo_entries,
  beta
)

Arguments

Value

Matrix of S1(t) values (rows = covariates, cols = recurrent times).

S1(t) for Recurrent Event Sub-Model with Cross-Fitting

Description

Computes the weighted first moment S1(t) at each recurrent event time for the recurrence sub-model, using fold-specific beta coefficients for cross-fitting.

Usage

jfm_s1t_recurrent_cf(
  Y,
  wt_recurrent_subject,
  tr,
  index_recurrent_matrix,
  pseudo_entries,
  beta_mat,
  CV_map
)

Arguments

Value

Matrix of S1(t) values (rows = covariates, cols = recurrent times).

Score Equation U2 for Alpha (Death)

Description

Evaluates the score equation for the death coefficient vector alpha.

Usage

jfm_score_alpha(pseudo_entries, index_death_matrix, td_id, S1t_de, S0t_de)

Arguments

Value

Numeric vector of score values, one per covariate.

Score Equation U1 for Beta (Recurrence)

Description

Evaluates the score equation for the recurrence coefficient vector beta.

Usage

jfm_score_beta(pseudo_entries, index_recurrent_matrix, tr_id, S1t_re, S0t_re)

Arguments

Value

Numeric vector of score values, one per covariate.

Estimating Equation U4 for Baseline Death Hazard

Description

Evaluates the estimating equation for the baseline hazard of the death sub-model at each death event time.

Usage

jfm_u4(td, d_td, n, S0t_de, lambda0_d)

Arguments

Value

Named numeric vector of U4 values, one per death time.

Estimating Equation U4 (New) for Numerically Solving Baseline Death Hazard

Description

Self-contained version of U4 that rebuilds the weight matrix and S0(t) internally, used for numerically solving for lambda0_d when a closed-form solution is not applicable.

Usage

jfm_u4_new(lambda0_d, d_td, n, Y, td, theta, alpha, t.start, I, Z, td.id)

Arguments

Value

Named numeric vector of U4 values, one per death time.

Estimating Equation U5 for Baseline Recurrence Hazard

Description

Evaluates the estimating equation for the baseline hazard of the recurrence sub-model at each recurrent event time.

Usage

jfm_u5(tr, d_tr, n, S0t_re, lambda0_r)

Arguments

Value

Named numeric vector of U5 values, one per recurrent event time.

Generate a Single Covariate Vector

Description

Generates n observations from a specified distribution for simulation purposes.

Usage

jfm_v_gene(n, v.type, v.coeffi)

Arguments

Value

Numeric vector of length n.

W_i(t) Evaluated at Each Death Time for Each Subject

Description

Constructs the weight matrix W_i(t) evaluated at each death event time for each subject, using the pseudo data set approach.

Usage

jfm_wt_death(theta, alpha, t.start, I, Z, td, lambda0_d, td.id)

Arguments

Value

A list with components:

W_i(t) Evaluated at Each Recurrent Event Time for Each Subject

Description

Constructs the weight matrix W_i(t) evaluated at each recurrent event time for each subject, by mapping recurrent event times to the nearest death time in the weight matrix.

Usage

jfm_wt_recurrent(tr, wt_matrix, td)

Arguments

Value

Matrix of W_i(t) values at recurrent event times (rows = subjects, cols = recurrent event times).

At-Risk Indicator Y(t)

Description

Returns 1 if the subject's observed time y is at least t, 0 otherwise.

Usage

jfm_yt(y, t)

Arguments

Value

Integer 0 or 1 indicator.

At-Risk Indicator Y*(t) with Status-Dependent Comparison

Description

Returns 1 if the subject is at risk at time t, using strict or non-strict inequality depending on the status indicator.

Usage

jfm_yt_star(t, y, stat)

Arguments

Value

Integer 0 or 1 indicator.

Estimating Equation for Alpha (Recurrence) in the JSCM

Description

Evaluates the estimating equation for the recurrence coefficient vector alpha in the joint scale-change model, using the C++ implementation am1.

Usage

jscm_ee_alpha(Data2, a)

Arguments

Value

Numeric vector of score values, one per covariate.

Estimating Equation for Beta (Death) in the JSCM

Description

Evaluates the estimating equation for the terminal event coefficient vector beta in the joint scale-change model, using the C++ implementations temLog and reRate.

Usage

jscm_ee_beta(Data2, a, b)

Arguments

Value

Numeric vector of score values, one per covariate.

Generate Both Baseline Hazards (JFM)

Description

Computes Breslow-type baseline hazards for both death and recurrence.

Usage

lambda0_gen(Data2, alpha, beta)

Arguments

Value

A list with components lambda0_r and lambda0_d.

Generate Baseline Hazard for Recurrence (JFM)

Description

Computes the Breslow-type baseline hazard for recurrence from a fitted alpha coefficient vector.

Usage

lambda0_r_gen(Data2, alpha)

Arguments

Value

Named numeric vector of baseline hazard point masses.

Interpolate Coefficient Vectors Along a Lambda Sequence

Description

Given a decreasing lambda sequence from a fitted path and a new set of lambda values, linearly interpolates the corresponding coefficient vectors.

Usage

lambda_interp(lambda, s)

Arguments

Value

A list with components:

Cause-Specific CIF Markers (JFM)

Description

Computes cause-specific cumulative incidence function (CIF) markers for recurrent events under the joint frailty model, using estimated baseline hazards.

Usage

markers_cause_specific(alpha, beta, tr, td, lambda0_r, lambda0_d, Z_base)

Arguments

Value

A list with components:

Cause-Specific CIF Markers Under True Parameters (JFM)

Description

Computes the CIF at a single time point under constant baseline hazards.

Usage

markers_cause_specific_true(t, alpha, beta, lambda0_r, lambda0_d, Z_base)

Arguments

Value

A list with components:

Plot Cross-Validation Results

Description

Plots the cross-validated estimating-equation score norms versus \log(\lambda), with separate lines for the readmission and death components. A vertical dashed line marks the lambda that minimizes the combined norm. The top axis shows the total number of active variables along the path.

Usage

## S3 method for class 'swjm_cv'
plot(x, log_lambda = TRUE, ...)

Arguments

Value

Invisibly returns x.

Examples

dat <- generate_data(n = 50, p = 10, scenario = 1, model = "jfm")
cv  <- cv_stagewise(dat$data, model = "jfm", penalty = "coop",
                    max_iter = 200)
plot(cv)

Plot a Stagewise Coefficient Path

Description

Produces a glmnet-style plot of coefficient trajectories versus \log(\lambda) along the stagewise regularization path. Two panels are drawn by default: one for the readmission sub-model (alpha) and one for the death sub-model (beta). The top axis of each panel shows the number of active variables at that lambda.

Usage

## S3 method for class 'swjm_path'
plot(
  x,
  log_lambda = TRUE,
  which = c("both", "readmission", "death"),
  col = NULL,
  ...
)

Arguments

Value

Invisibly returns x.

Examples

dat <- generate_data(n = 50, p = 10, scenario = 1, model = "jfm")
fit <- stagewise_fit(dat$data, model = "jfm", penalty = "coop",
                     max_iter = 200)
plot(fit)

Plot Predicted Survival Curves and Predictor Contributions

Description

Produces a figure for a "swjm_pred" object. The layout depends on the model:

Usage

## S3 method for class 'swjm_pred'
plot(
  x,
  which_subject = 1L,
  which_process = c("both", "readmission", "death"),
  threshold = 0,
  ...
)

Arguments

Details

JFM (four panels):

1. Readmission-free survival curves for all subjects, with the selected subject highlighted.

2. Bar chart of readmission predictor contributions \hat\alpha_j z_{ij} (log-hazard scale).

3. Death-free survival curves with the selected subject highlighted.

4. Bar chart of death predictor contributions \hat\beta_j z_{ij}.

JSCM (four panels):

1. Recurrent-event survival curves (AFT model) with the selected subject highlighted. The panel title shows the total acceleration factor e^{\hat\alpha^\top z_i}.

2. Bar chart of recurrence log time-acceleration contributions \hat\alpha_j z_{ij}: positive = events sooner, negative = later.

3. Death-free survival curves with the selected subject highlighted, total acceleration factor e^{\hat\beta^\top z_i} in the title.

4. Bar chart of terminal-event log time-acceleration contributions \hat\beta_j z_{ij}.

In all cases bars represent subject-specific contributions (coefficient \times covariate value), not bare coefficients, so the display correctly reflects how much each predictor shifts the log-hazard (JFM) or log time-acceleration (JSCM) for this particular subject.

Value

Invisibly returns x.

Examples

dat  <- generate_data(n = 50, p = 10, scenario = 1, model = "jfm")
cv   <- cv_stagewise(dat$data, model = "jfm", penalty = "coop",
                     max_iter = 100)
newz <- matrix(rnorm(30), nrow = 3, ncol = 10)
pred <- predict(cv, newdata = newz)
plot(pred, which_subject = 2)
plot(pred, which_subject = 2, threshold = 0.05)

Predict from a Cross-Validated Joint Model Fit

Description

Computes subject-specific predictions from a cross-validated swjm_cv fit. The output differs by model:

Usage

## S3 method for class 'swjm_cv'
predict(object, newdata, times = NULL, ...)

Arguments

Details

JFM — returns survival curves for both processes using the Breslow cumulative baseline hazards. For subject i with covariate vector z_i:

S_{\text{re}}(t \mid z_i) = \exp\!\bigl(-\hat\Lambda_0^r(t)\, e^{\hat\alpha^\top z_i}\bigr), \quad S_{\text{de}}(t \mid z_i) = \exp\!\bigl(-\hat\Lambda_0^d(t)\, e^{\hat\beta^\top z_i}\bigr).

JSCM — returns survival curves for both processes using a Nelson-Aalen baseline on the accelerated time scale. For subject i:

S_{\text{re}}(t \mid z_i) = \exp\!\bigl(-\hat\Lambda_0^r(t\, e^{\hat\alpha^\top z_i})\bigr), \quad S_{\text{de}}(t \mid z_i) = \exp\!\bigl(-\hat\Lambda_0^d(t\, e^{\hat\beta^\top z_i})\bigr).

The linear predictor \hat\alpha^\top z_i is a log time-acceleration factor: the recurrence process for subject i runs on a time axis scaled by e^{\hat\alpha^\top z_i} relative to the baseline. Each predictor contributes \hat\alpha_j z_{ij} to this log-scale factor, so e^{\hat\alpha_j z_{ij}} is the multiplicative factor on the time scale attributable to predictor j alone. Values greater than 1 accelerate events (shorter times); values less than 1 decelerate them (longer times).

Value

An object of class "swjm_pred", a list with:

S_re

Matrix of readmission-free survival probabilities (rows = subjects, columns = times).

S_de

Matrix of death-free survival probabilities.

times

Numeric vector of evaluation times.

lp_re

Linear predictors for readmission (\hat\alpha^\top z_i). For JSCM this is the log time-acceleration for the recurrence process.

lp_de

Linear predictors for death (\hat\beta^\top z_i). For JSCM this is the log time-acceleration for the terminal process.

time_accel_re

(JSCM only) e^{\hat\alpha^\top z_i}: the multiplicative factor by which the recurrence time axis is scaled relative to baseline. NULL for JFM.

time_accel_de

(JSCM only) Analogous time-acceleration factor for the terminal process. NULL for JFM.

contrib_re

Matrix of per-predictor contributions \hat\alpha_j z_{ij} (rows = subjects, columns = covariates). For JFM these are log-hazard contributions; for JSCM they are log time-acceleration contributions.

contrib_de

Analogous matrix for the terminal process.

Examples

dat <- generate_data(n = 50, p = 10, scenario = 1, model = "jfm")
cv  <- cv_stagewise(dat$data, model = "jfm", penalty = "coop",
                    max_iter = 100)
newz <- matrix(rnorm(30), nrow = 3, ncol = 10)
pred <- predict(cv, newdata = newz)
plot(pred)

dat_jscm <- generate_data(n = 50, p = 10, scenario = 1, model = "jscm")
cv_jscm  <- cv_stagewise(dat_jscm$data, model = "jscm", penalty = "coop",
                          max_iter = 500)
pred_jscm <- predict(cv_jscm, newdata = newz)
plot(pred_jscm)

Prepare Data for swjm Functions

Description

Expands factor and character covariate columns into dummy (indicator) variables. The first 5 columns (id, t.start, t.stop, event, status) are left unchanged. For each factor/character column with L levels, L-1 dummy columns are created (reference level dropped). A message is printed when expansion occurs.

Usage

prepare_data(data, caller = "swjm")

Arguments

Value

A data frame with factor/character covariates replaced by numeric dummy columns.

Fit a Stagewise Regularization Path

Description

Unified interface for stagewise variable selection in joint models of recurrent events and terminal events. Dispatches to model-specific implementations for the Joint Frailty Model (JFM) or Joint Scale-Change Model (JSCM).

Usage

stagewise_fit(
  data,
  model = c("jfm", "jscm"),
  penalty = c("coop", "lasso", "group"),
  eps = NULL,
  max_iter = NULL,
  pp = NULL,
  estimate_frailty = FALSE,
  standardize = TRUE
)

Arguments

Value

An object of class "swjm_path", a list with components:

k

Number of iterations performed.

theta

Matrix of coefficient paths (2p rows by k+1 columns).

lambda

Numeric vector of penalty parameter approximations at each iteration.

norm

Numeric vector of penalty norm values along the path.

model

Character, the model used.

penalty

Character, the penalty used.

Examples

dat <- generate_data(n = 50, p = 10, scenario = 1, model = "jfm")
fit <- stagewise_fit(dat$data, model = "jfm", penalty = "coop",
                     max_iter = 100)
fit

Validate Recurrent-Event Data Frame

Description

Checks that a data frame has the required structure for swjm functions: columns id, t.start, t.stop, event, status, and at least one covariate. Produces informative error messages for each violated requirement.

Usage

validate_data(data, caller = "swjm")

Arguments

Value

Invisibly returns TRUE if valid; throws an error otherwise.