Fit a PAMM to interval-censored data via multiple imputation

Source: R/pamm-ic-pool.R, R/pamm-ic.R

Fits a piecewise exponential additive (mixed) model to interval-censored time-to-event data using a multiple-imputation (MI) and re-fit strategy: exact event times are repeatedly drawn from the model-based conditional distribution \(p(T \mid L < T \le R, x, \theta)\) (see impute_ic_times), with \(\theta\) drawn from the imputation model's asymptotic posterior before each imputation ("proper" MI – this is what makes the pooled intervals calibrated), each completed data set is transformed to PED format with the standard (right-censored) pipeline and re-fit, and the resulting fits are pooled for inference with the existing add_* family (see add_surv_prob and the pamm_ic methods).

# S3 method for class 'pamm_ic'
print(x, ...)

# S3 method for class 'pamm_ic'
summary(object, ...)

# S3 method for class 'summary.pamm_ic'
print(x, ...)

pamm_ic(
  formula,
  data,
  model_formula = NULL,
  cut = NULL,
  max_time = NULL,
  m = 10L,
  iter = 1L,
  init = c("midpoint", "uniform"),
  id = "id",
  engine = "gam",
  ...
)

Arguments

x, object

A pamm_ic object.

...

Further arguments passed to pamm / mgcv.

formula

A two-sided formula whose left-hand side is an interval-censored response Surv(L, R, type = "interval2") and whose right-hand side lists the covariates to retain (as in as_ped).

data

A data frame in standard (one row per subject) format.

model_formula

Optional model formula passed to pamm (e.g.\ ped_status ~ s(tend) + x). If NULL, a default ped_status ~ s(tend) + <covariates> formula is constructed.

cut

Optional fixed vector of interval cut-points shared across all imputations. If NULL, the finite interval endpoints are used.

max_time

Optional cap on the cut-points.

m

Number of imputations (default 10).

iter

Number of impute-refit iterations per imputation chain (default 1 = classic one-step MI: all m imputations are drawn from the single initialiser fit). For iter = k > 1, each chain alternates imputation and re-fitting on its own completed data set k times, so later imputations are drawn from fits whose dependence on the midpoint initialiser is progressively attenuated – a sequential ("chained") MI scheme that progressively removes initialiser bias under sparse inspection, at roughly iter-fold fitting cost. Simulation evidence (see the package's interval-censoring benchmark): with inspection gaps that are small relative to the time scale, iter = 1 is unbiased; with wide gaps (mean gap of order 1/3 of the follow-up), early-time survival estimates from iter = 1 are biased upward and iter = 3 removes most of that bias (iter = 5 essentially all of it), with bias shrinking roughly geometrically in iter. Caveat: with flexible time-varying effect terms and small samples, iterating can occasionally amplify a weakly identified imputation chain into divergent estimates with very wide intervals (without mgcv warnings) – inspect pooled smooth effects for plausibility when iterating such models.

init

Initialiser for the first fit: "midpoint" (default) or "uniform" imputation within each interval.

id

Name of the subject identifier column.

engine

Estimation engine passed to pamm ("gam" or "bam").

Value

An object of class pamm_ic: a list with

fits

the m imputation fits, each slimmed (via strip_pamm_fit) to drop per-observation slots so memory does not scale with the number of imputations; they still support coef, vcov and predict(type = "lpmatrix"), which is all the pooled add_* methods need.

pooled

a pooled summary container with Rubin-pooled parametric coefficients and covariance, pooled parametric/smooth tables with median-p values ($p.table, $s.table), parametric coefficient FMI diagnostics ($fmi.table) and smooth-term FMI five-number summaries over the training grid ($smooth.fmi).

init_fit

the (slimmed) initialiser/imputation model.

unstable_chains

indices of imputation chains flagged as numerically unstable (extreme coefficients or coefficient SEs on the log-hazard scale; also raised as a warning). Degenerate chains can arise – silently, without mgcv warnings – when iterating flexible time-varying models on small samples.

others

the parsed bounds ic, the shared cut, and metadata.

print/summary report the pooled summary; add_* compute pooled quantities of interest from fits.

Details

An imputed event time is an exact event time, so once imputation has produced it, the entire downstream pipeline (split_data -> pamm -> add_*) is reused unchanged. The interval cut-points are resolved once and shared across all imputations, but mgcv's smooth bases and centering constraints can still differ across completed data sets. Pooled predictions therefore evaluate each fitted imputation model with its own design matrix; object$pooled is a summary container, not a gam-like model for direct predict() or plot() calls.