add_hazard: Add predicted (cumulative) hazard to data set

In pammtools: Piece-Wise Exponential Additive Mixed Modeling Tools for Survival Analysis

Add predicted (cumulative) hazard to data set

Description

Add (cumulative) hazard based on the provided data set and model. If ci=TRUE confidence intervals (CI) are also added. Their width can be controlled via the se_mult argument. The method by which the CI are calculated can be specified by ci_type. This is a wrapper around predict.gam. When reference is specified, the (log-)hazard ratio is calculated. In addition to models fit with gam/bam or glm, shape-constrained additive models fit with scam are supported (e.g., for monotone baseline hazards). For scam models all calculations (including delta-method and simulation based confidence intervals) are based on the re-parametrized coefficients and their covariance matrix, i.e., on the same normal approximation that underlies the standard errors reported by scam itself.

Usage

add_hazard(newdata, object, ...)

## Default S3 method:
add_hazard(
  newdata,
  object,
  reference = NULL,
  type = c("response", "link"),
  ci = TRUE,
  se_mult = 2,
  ci_type = c("default", "delta", "sim"),
  overwrite = FALSE,
  time_var = NULL,
  nsim = 100L,
  alpha = 0.05,
  ...
)

add_cumu_hazard(newdata, object, ...)

## Default S3 method:
add_cumu_hazard(
  newdata,
  object,
  ci = TRUE,
  se_mult = 2,
  overwrite = FALSE,
  time_var = NULL,
  interval_length = "intlen",
  boundary = TRUE,
  check_grouping = TRUE,
  ...
)

## S3 method for class 'pamm_ic'
add_hazard(
  newdata,
  object,
  ci = TRUE,
  alpha = 0.05,
  nsim = 500L,
  time_var = NULL,
  ...
)

## S3 method for class 'pamm_ic'
add_cumu_hazard(
  newdata,
  object,
  ci = TRUE,
  alpha = 0.05,
  nsim = 500L,
  time_var = NULL,
  interval_length = "intlen",
  check_grouping = TRUE,
  ...
)

Arguments

newdata	A data frame or list containing the values of the model covariates at which predictions are required. If this is not provided then predictions corresponding to the original data are returned. If newdata is provided then it should contain all the variables needed for prediction: a warning is generated if not. See details for use with link{linear.functional.terms}.
object	a fitted gam object as produced by gam().
...	Further arguments passed to predict.gam and get_hazard
reference	A data frame with number of rows equal to nrow(newdata) or one, or a named list with (partial) covariate specifications. See examples.
type	Either "response" or "link". The former calculates hazard, the latter the log-hazard.
ci	logical. Indicates if confidence intervals should be calculated. Defaults to TRUE.
se_mult	Factor by which standard errors are multiplied for calculating the confidence intervals.
ci_type	The method by which standard errors/confidence intervals will be calculated. Default transforms the linear predictor at respective intervals. "delta" calculates CIs based on the standard error calculated by the Delta method. "sim" draws the property of interest from its posterior based on the normal distribution of the estimated coefficients. See here for details and empirical evaluation. For ci_type = "sim", interval bounds are empirical quantiles (type 6, see quantile) of nsim posterior draws (default nsim = 100L, passed via ...). Type-6 quantiles avoid the systematic inward bias that the quantile default (type 7) exhibits for small nsim, but at the default nsim = 100 the bounds are estimated from few tail draws and thus noisy; increase nsim (e.g., to 500 or more) for more stable interval bounds. Very small nsim (nsim < 2 / alpha - 1, i.e., below 39 for alpha = 0.05) cannot achieve the nominal level at all.
overwrite	Should hazard columns be overwritten if already present in the data set? Defaults to FALSE. If TRUE, columns with names c("hazard", "se", "lower", "upper") will be overwritten.
time_var	Name of the variable used for the baseline hazard. Defaults to "tend".
nsim	Total number of pooled posterior draws used for the interval.
alpha	Significance level for pooled confidence intervals (a (1-\alpha) interval).
interval_length	The variable in newdata containing the interval lengths. Can be either bare unquoted variable name or character. Defaults to "intlen".
boundary	Logical. If TRUE (default), a boundary row at time = 0 with cumulative hazard 0 is prepended (per group), so that cumulative hazards start at the natural origin (consistent with add_surv_prob, add_cif and add_trans_prob).
check_grouping	Logical. If TRUE (default), the function checks that newdata is grouped so that the time variable is unique within each group and stops otherwise, guarding against silently accumulating cumulative quantities across distinct covariate profiles (a forgotten group_by()). Set to FALSE to skip the check (e.g.\ for internal calls on already-validated data).

Details

When computing cumulative hazards or survival probabilities across groups, the input data must be grouped via group_by() prior to calling add_cumu_hazard() or add_surv_prob(), so that the cumulative quantity is accumulated within each covariate profile rather than across the whole dataset. If newdata still contains several profiles per group (i.e.\ repeated time_var values within a group, typically a forgotten group_by()), the functions now stop with an error rather than returning silently incorrect results. Set check_grouping = FALSE to skip this safeguard. Note the check detects the common mis-grouping cases – in particular any grid built with make_newdata, where profiles share time values – but cannot catch hand-built grids that stack profiles with disjoint time grids, as these are indistinguishable from a single profile with time-varying covariates. See the workflow vignette for a worked example.

See Also

predict.gam, add_surv_prob

Examples

ped <- tumor[1:50,] %>% as_ped(Surv(days, status)~ age)
pam <- mgcv::gam(ped_status ~ s(tend)+age, data = ped, family=poisson(), offset=offset)
ped_info(ped) %>% add_hazard(pam, type="link")
ped_info(ped) %>% add_hazard(pam, type = "response")
ped_info(ped) %>% add_cumu_hazard(pam)

pammtools documentation built on Aug. 27, 2026, 1:08 a.m.