Title:	Piece-Wise Exponential Additive Mixed Modeling Tools for Survival Analysis
Version:	0.7.3
Date:	2025-03-23
Description:	The Piece-wise exponential (Additive Mixed) Model (PAMM; Bender and others (2018) <doi:10.1177/1471082X17748083>) is a powerful model class for the analysis of survival (or time-to-event) data, based on Generalized Additive (Mixed) Models (GA(M)Ms). It offers intuitive specification and robust estimation of complex survival models with stratified baseline hazards, random effects, time-varying effects, time-dependent covariates and cumulative effects (Bender and others (2019)), as well as support for left-truncated data as well as competing risks, recurrent events and multi-state settings. pammtools provides tidy workflow for survival analysis with PAMMs, including data simulation, transformation and other functions for data preprocessing and model post-processing as well as visualization.
Depends:	R (≥ 4.1.0)
Imports:	mgcv, survival (≥ 2.39-5), checkmate, magrittr, rlang, tidyr (≥ 1.0.0), ggplot2 (≥ 3.2.2), dplyr (≥ 1.0.0), purrr (≥ 0.2.3), tibble, lazyeval, Formula, mvtnorm, pec, vctrs (≥ 0.3.0), scam
Suggests:	testthat, mstate
Config/Needs/website:	coxme, eha, etm, scam, msm, mvna, TBFmultinomial
License:	MIT + file LICENSE
LazyData:	true
URL:	https://adibender.github.io/pammtools/
BugReports:	https://github.com/adibender/pammtools/issues
RoxygenNote:	7.3.2
Encoding:	UTF-8
NeedsCompilation:	no
Packaged:	2025-03-24 14:04:35 UTC; ab
Author:	Andreas Bender [aut, cre], Fabian Scheipl [aut], Johannes Piller [aut], Philipp Kopper [aut], Lukas Burk [ctb]
Maintainer:	Andreas Bender <andreas.bender@stat.uni-muenchen.de>
Repository:	CRAN
Date/Publication:	2025-03-24 15:20:02 UTC

pammtools: Piece-wise exponential Additive Mixed Modeling tools.

Description

pammtools provides functions and utilities that facilitate fitting Piece-wise Exponential Additive Mixed Models (PAMMs), including data transformation and other convenience functions for pre- and post-processing as well as plotting.

Details

The best way to get an overview of the functionality provided and how to fit PAMMs is to view the vignettes available at https://adibender.github.io/pammtools/articles/. A summary of the vignettes' content is given below:

• basics: Introduction to PAMMs and basic modeling.

• baseline: Shows how to estimate and visualize baseline model (without covariates) and comparison to respective Cox-PH model.

• convenience: Convenience functions for post-processing and plotting PAMMs.

• data-transformation: Transforming data into a format suitable to fit PAMMs.

• frailty: Specifying "frailty" terms, i.e., random effects for PAMMs.

• splines: Specifying spline smooth terms for PAMMs.

• strata: Specifying stratified models in which each level of a grouping variable has a different baseline hazard.

• tdcovar: Dealing with time-dependent covariates.

• tveffects: Specifying time-varying effects.

• left-truncation: Estimation for left-truncated data.

• competing-risks: Competing risks analysis.

Author(s)

Maintainer: Andreas Bender andreas.bender@stat.uni-muenchen.de (ORCID)

Authors:

• Fabian Scheipl fabian.scheipl@stat.uni-muenchen.de (ORCID)

• Johannes Piller johannes.piller@lmu.de (ORCID)

• Philipp Kopper philipp.kopper@stat.uni-muenchen.de (ORCID)

Other contributors:

• Lukas Burk burk@leibniz-bips.de (ORCID) [contributor]

References

Bender, Andreas, Andreas Groll, and Fabian Scheipl. 2018. “A Generalized Additive Model Approach to Time-to-Event Analysis” Statistical Modelling, February. https://doi.org/10.1177/1471082X17748083.

Bender, Andreas, Fabian Scheipl, Wolfgang Hartl, Andrew G. Day, and Helmut Küchenhoff. 2019. “Penalized Estimation of Complex, Non-Linear Exposure-Lag-Response Associations.” Biostatistics 20 (2): 315–31. https://doi.org/10.1093/biostatistics/kxy003.

Bender, Andreas, and Fabian Scheipl. 2018. “pammtools: Piece-Wise Exponential Additive Mixed Modeling Tools.” ArXiv:1806.01042 Stat, June. https://arxiv.org/abs/1806.01042. Ramjith J, Bender A, Roes KCB, Jonker MA. Recurrent events analysis with piece-wise exponential additive mixed models. 2022. Statistical Modelling., 2022

See Also

Useful links:

• https://adibender.github.io/pammtools/

• Report bugs at https://github.com/adibender/pammtools/issues

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Add cumulative incidence function to data

Description

Add cumulative incidence function to data

Usage

add_cif(newdata, object, ...)

## Default S3 method:
add_cif(
  newdata,
  object,
  ci = TRUE,
  overwrite = FALSE,
  alpha = 0.05,
  nsim = 500L,
  cause_var = "cause",
  time_var = NULL,
  ...
)

Arguments

Add counterfactual observations for possible transitions

Description

If data only contains one row per transition that took place, this function adds additional rows for each transition that was possible at that time (for each subject in the data).

Usage

add_counterfactual_transitions(
  data,
  from_to_pairs = list(),
  from_col = "from",
  to_col = "to",
  transition_col = "transition"
)

Arguments

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.

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,
  ...
)

add_cumu_hazard(
  newdata,
  object,
  ci = TRUE,
  se_mult = 2,
  overwrite = FALSE,
  time_var = NULL,
  interval_length = "intlen",
  ...
)

Arguments

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)

Add survival probability estimates

Description

Given suitable data (i.e. data with all columns used for estimation of the model), this functions adds a column surv_prob containing survival probabilities for the specified covariate and follow-up information (and CIs surv_lower, surv_upper if ci=TRUE).

Usage

add_surv_prob(
  newdata,
  object,
  ci = TRUE,
  se_mult = 2,
  overwrite = FALSE,
  time_var = NULL,
  interval_length = "intlen",
  ...
)

Arguments

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_surv_prob(pam, ci=TRUE)

Add time-dependent covariate to a data set

Description

Given a data set in standard format (with one row per subject/observation), this function adds a column with the specified exposure time points and a column with respective exposures, created from rng_fun. This function should usually only be used to create data sets passed to sim_pexp.

Usage

add_tdc(data, tz, rng_fun, ...)

Arguments

Embeds the data set with the specified (relative) term contribution

Description

Adds the contribution of a specific term to the linear predictor to the data specified by newdata. Essentially a wrapper to predict.gam, with type="terms". Thus most arguments and their documentation below is from predict.gam.

Usage

add_term(newdata, object, term, reference = NULL, ci = TRUE, se_mult = 2, ...)

Arguments

Examples

library(ggplot2)
ped <- as_ped(tumor, Surv(days, status)~ age, cut = seq(0, 2000, by = 100))
pam <- mgcv::gam(ped_status ~ s(tend) + s(age), family = poisson(),
  offset = offset, data = ped)
#term contribution for sequence of ages
s_age <- ped %>% make_newdata(age = seq_range(age, 50)) %>%
  add_term(pam, term = "age")
ggplot(s_age, aes(x = age, y = fit)) + geom_line() +
  geom_ribbon(aes(ymin = ci_lower, ymax = ci_upper), alpha = .3)
# term contribution relative to mean age
s_age2 <- ped %>% make_newdata(age = seq_range(age, 50)) %>%
  add_term(pam, term = "age", reference = list(age = mean(.$age)))
ggplot(s_age2, aes(x = age, y = fit)) + geom_line() +
  geom_ribbon(aes(ymin = ci_lower, ymax = ci_upper), alpha = .3)

Add transition probabilities confidence intervals

Description

Add transition probabilities confidence intervals

Usage

add_trans_ci(newdata, object, nsim = 100L, alpha = 0.05, ...)

Add transition probabilities

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.

Usage

add_trans_prob(
  newdata,
  object,
  overwrite = FALSE,
  ci = FALSE,
  alpha = 0.05,
  nsim = 100L,
  time_var = NULL,
  interval_length = "intlen",
  ...
)

Arguments

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)

Transform crps object to data.frame

Description

Aas.data.frame S3 method for objects of class crps.

Usage

## S3 method for class 'crps'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Transform data to Piece-wise Exponential Data (PED)

Description

This is the general data transformation function provided by the pammtools package. Two main applications must be distinguished:

1. Transformation of standard time-to-event data.

2. Transformation of left-truncated time-to-event data.

3. Transformation of time-to-event data with time-dependent covariates (TDC).

For the latter, the type of effect one wants to estimate is also important for the data transformation step. In any case, the data transformation is specified by a two sided formula. In case of TDCs, the right-hand-side of the formula can contain formula specials concurrent and cumulative. See the data-transformation vignette for details.

Usage

as_ped(data, ...)

## S3 method for class 'data.frame'
as_ped(
  data,
  formula,
  cut = NULL,
  max_time = NULL,
  tdc_specials = c("concurrent", "cumulative"),
  censor_code = 0L,
  transition = character(),
  timescale = c("gap", "calendar"),
  min_events = 1L,
  ...
)

## S3 method for class 'nested_fdf'
as_ped(data, formula, ...)

## S3 method for class 'list'
as_ped(
  data,
  formula,
  tdc_specials = c("concurrent", "cumulative"),
  censor_code = 0L,
  ...
)

is.ped(x)

## S3 method for class 'ped'
as_ped(data, newdata, ...)

## S3 method for class 'pamm'
as_ped(data, newdata, ...)

as_ped_multistate(
  data,
  formula,
  cut = NULL,
  max_time = NULL,
  tdc_specials = c("concurrent", "cumulative"),
  censor_code = 0L,
  transition = character(),
  timescale = c("gap", "calendar"),
  min_events = 1L,
  ...
)

Arguments

Value

A data frame class ped in piece-wise exponential data format.

Examples

tumor[1:3, ]
tumor[1:3, ] %>% as_ped(Surv(days, status)~ age + sex, cut = c(0, 500, 1000))
tumor[1:3, ] %>% as_ped(Surv(days, status)~ age + sex)
## Not run: 
data("cgd", package = "frailtyHL")
cgd2 <- cgd %>%
 select(id, tstart, tstop, enum, status, age) %>%
 filter(enum %in% c(1:2))
ped_re <- as_ped_multistate(
  formula = Surv(tstart, tstop, status) ~ age + enum,
  data = cgd2,
 transition = "enum",
 timescale = "calendar")

## End(Not run)

Competing risks trafo

Description

This is the general data transformation function provided by the pammtools package. Two main applications must be distinguished:

1. Transformation of standard time-to-event data.

2. Transformation of left-truncated time-to-event data.

3. Transformation of time-to-event data with time-dependent covariates (TDC).

For the latter, the type of effect one wants to estimate is also important for the data transformation step. In any case, the data transformation is specified by a two sided formula. In case of TDCs, the right-hand-side of the formula can contain formula specials concurrent and cumulative. See the data-transformation vignette for details.

Usage

as_ped_cr(
  data,
  formula,
  cut = NULL,
  max_time = NULL,
  tdc_specials = c("concurrent", "cumulative"),
  censor_code = 0L,
  combine = TRUE,
  ...
)

Arguments

Value

A data frame class ped in piece-wise exponential data format.

Examples

tumor[1:3, ]
tumor[1:3, ] %>% as_ped(Surv(days, status)~ age + sex, cut = c(0, 500, 1000))
tumor[1:3, ] %>% as_ped(Surv(days, status)~ age + sex)
## Not run: 
data("cgd", package = "frailtyHL")
cgd2 <- cgd %>%
 select(id, tstart, tstop, enum, status, age) %>%
 filter(enum %in% c(1:2))
ped_re <- as_ped_multistate(
  formula = Surv(tstart, tstop, status) ~ age + enum,
  data = cgd2,
 transition = "enum",
 timescale = "calendar")

## End(Not run)

Calculate confidence intervals

Description

Given 2 column matrix or data frame, returns 3 column data.frame with coefficient estimate plus lower and upper borders of the 95% confidence intervals.

Usage

calc_ci(ftab)

Arguments

Create a data frame from all combinations of data frames

Description

Works like expand.grid but for data frames.

Usage

combine_df(...)

Arguments

Examples

combine_df(
  data.frame(x=1:3, y=3:1),
  data.frame(x1=c("a", "b"), x2=c("c", "d")),
  data.frame(z=c(0, 1)))

Calculate difference in cumulative hazards and respective standard errors

Description

CIs are calculated by sampling coefficients from their posterior and calculating the cumulative hazard difference nsim times. The CI are obtained by the 2.5\

Usage

compute_cumu_diff(d1, d2, model, alpha = 0.05, nsim = 100L)

Arguments

Formula specials for defining time-dependent covariates

Description

So far, two specials are implemented. concurrent is used when the goal is to estimate a concurrent effect of the TDC. cumulative is used when the goal is to estimate a cumulative effect of the TDC. These should usually not be called directly but rather as part of the formula argument to as_ped. See the vignette on data transformation for details.

Usage

cumulative(..., tz_var, ll_fun = function(t, tz) t >= tz, suffix = NULL)

concurrent(..., tz_var, lag = 0, suffix = NULL)

has_special(formula, special = "cumulative")

Arguments

Time-dependent covariates of the patient data set.

Description

This data set contains the time-dependent covariates (TDCs) for the patient data set. Note that nutrition was protocoled for at most 12 days after ICU admission. The data set includes:

CombinedID

Unique patient identifier. Can be used to merge with patient data

Study_Day

The calendar (!) day at which calories (or proteins) were administered

caloriesPercentage

The percentage of target calories supplied to the patient by the ICU staff

proteinGproKG

The amount of protein supplied to the patient by the ICU staff

Usage

daily

Format

An object of class tbl_df (inherits from tbl, data.frame) with 18797 rows and 4 columns.

dplyr Verbs for ped-Objects

Description

See dplyr documentation of the respective functions for description and examples.

Usage

## S3 method for class 'ped'
arrange(.data, ...)

## S3 method for class 'ped'
group_by(.data, ..., .add = FALSE)

## S3 method for class 'ped'
ungroup(x, ...)

## S3 method for class 'ped'
distinct(.data, ..., .keep_all = FALSE)

## S3 method for class 'ped'
filter(.data, ...)

## S3 method for class 'ped'
sample_n(tbl, size, replace = FALSE, weight = NULL, .env = NULL, ...)

## S3 method for class 'ped'
sample_frac(tbl, size = 1, replace = FALSE, weight = NULL, .env = NULL, ...)

## S3 method for class 'ped'
slice(.data, ...)

## S3 method for class 'ped'
select(.data, ...)

## S3 method for class 'ped'
mutate(.data, ...)

## S3 method for class 'ped'
rename(.data, ...)

## S3 method for class 'ped'
summarise(.data, ...)

## S3 method for class 'ped'
summarize(.data, ...)

## S3 method for class 'ped'
transmute(.data, ...)

## S3 method for class 'ped'
inner_join(x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ...)

## S3 method for class 'ped'
full_join(x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ...)

## S3 method for class 'ped'
left_join(x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ...)

## S3 method for class 'ped'
right_join(x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ...)

Arguments

Value

a modified ped object (except for do)

A formula special used to handle cumulative effect specifications

Description

Can be used in the second part of the formula specification provided to sim_pexp and should only be used in this context.

Usage

fcumu(..., by = NULL, f_xyz, ll_fun)

Extract transition information from different objects

Description

Extract transition information from different objects

Usage

from_to_pairs(t_mat, ...)

from_to_pairs2(t_mat, ...)

## S3 method for class 'data.frame'
from_to_pairs(t_mat, from_col = "from", to_col = "to", ...)

Arguments

Examples

## Not run: 
df = data.frame(id = c(1,1, 2,2), from = c(1, 1, 2, 2), to = c(2, 3, 2, 2))
from_to_pairs(df)

## End(Not run)

(Cumulative) (Step-) Hazard Plots.

Description

geom_hazard is an extension of the geom_line, and is optimized for (cumulative) hazard plots. Essentially, it adds a (0,0) row to the data, if not already the case. Stolen from the RmcdrPlugin.KMggplot2 (slightly modified).

Usage

geom_hazard(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

geom_stephazard(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  direction = "vh",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

geom_surv(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

Arguments

See Also

geom_line, geom_step.

Examples

library(ggplot2)
library(pammtools)
ped <- tumor[10:50,] %>% as_ped(Surv(days, status)~1)
pam <- mgcv::gam(ped_status ~ s(tend), data=ped, family = poisson(), offset = offset)
ndf <- make_newdata(ped, tend = unique(tend)) %>% add_hazard(pam)
# piece-wise constant hazards
ggplot(ndf, aes(x = tend, y = hazard)) +
 geom_vline(xintercept = c(0, ndf$tend[c(1, (nrow(ndf)-2):nrow(ndf))]), lty = 3) +
 geom_hline(yintercept = c(ndf$hazard[1:3], ndf$hazard[nrow(ndf)]), lty = 3) +
 geom_stephazard() +
 geom_step(col=2) +
 geom_step(col=2, lty = 2, direction="vh")

# comulative hazard
ndf <- ndf %>% add_cumu_hazard(pam)
ggplot(ndf, aes(x = tend, y = cumu_hazard)) +
 geom_hazard() +
 geom_line(col=2) # doesn't start at (0, 0)

# survival probability
ndf <- ndf %>% add_surv_prob(pam)
ggplot(ndf, aes(x = tend, y = surv_prob)) +
 geom_surv() +
 geom_line(col=2) # doesn't start at c(0,1)

Step ribbon plots.

Description

geom_stepribbon is an extension of the geom_ribbon, and is optimized for Kaplan-Meier plots with pointwise confidence intervals or a confidence band. The default direction-argument "hv" is appropriate for right-continuous step functions like the hazard rates etc returned by pammtools.

Usage

geom_stepribbon(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  direction = "hv",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

Arguments

See Also

geom_ribbon geom_stepribbon

Examples

library(ggplot2)
huron <- data.frame(year = 1875:1972, level = as.vector(LakeHuron))
h <- ggplot(huron, aes(year))
h + geom_stepribbon(aes(ymin = level - 1, ymax = level + 1), fill = "grey70") +
    geom_step(aes(y = level))
h + geom_ribbon(aes(ymin = level - 1, ymax = level + 1), fill = "grey70") +
    geom_line(aes(y = level))

Calculate CIF for one cause

Description

Calculate CIF for one cause

Usage

get_cif(newdata, object, ...)

## Default S3 method:
get_cif(
  newdata,
  object,
  ci,
  time_var,
  alpha,
  nsim,
  cause_var,
  coefs,
  V,
  sim_coef_mat,
  ...
)

Extract cumulative coefficients (cumulative hazard differences)

Description

These functions are designed to extract (or mimic) the cumulative coefficients usually used in additive hazards models (Aalen model) to depict (time-varying) covariate effects. For PAMMs, these are the differences between the cumulative hazard rates where all covariates except one have the identical values. For a numeric covariate of interest, this calculates \Lambda(t|x+1) - \Lambda(t|x). For non-numeric covariates the cumulative hazard of the reference level is subtracted from the cumulative hazards evaluated at all non reference levels. Standard errors are calculated using the delta method.

Usage

get_cumu_coef(model, data = NULL, terms, ...)

## S3 method for class 'gam'
get_cumu_coef(model, data, terms, ...)

## S3 method for class 'aalen'
get_cumu_coef(model, data = NULL, terms, ci = TRUE, ...)

## S3 method for class 'cox.aalen'
get_cumu_coef(model, data = NULL, terms, ci = TRUE, ...)

Arguments

Calculate (or plot) cumulative effect for all time-points of the follow-up

Description

Calculate (or plot) cumulative effect for all time-points of the follow-up

Usage

get_cumu_eff(data, model, term, z1, z2 = NULL, se_mult = 2)

gg_cumu_eff(data, model, term, z1, z2 = NULL, se_mult = 2, ci = TRUE)

Arguments

Calculate cumulative hazard

Description

Calculate cumulative hazard

Usage

get_cumu_hazard(
  newdata,
  object,
  ci = TRUE,
  ci_type = c("default", "delta", "sim"),
  time_var = NULL,
  se_mult = 2,
  interval_length = "intlen",
  nsim = 100L,
  ...
)

Arguments

Expand time-dependent covariates to functionals

Description

Given formula specification on how time-dependent covariates affect the outcome, creates respective functional covariate as well as auxiliary matrices for time/latency etc.

Usage

get_cumulative(data, formula)

expand_cumulative(data, func, n_func)

Arguments

Obtain interval break points

Description

Default method words for data frames. The list method applies the default method to each data set within the list.

Usage

get_cut(data, formula, cut = NULL, ...)

## Default S3 method:
get_cut(data, formula, cut = NULL, max_time = NULL, event = 1L, ...)

## S3 method for class 'list'
get_cut(
  data,
  formula,
  cut = NULL,
  max_time = NULL,
  event = 1L,
  timescale = "gap",
  ...
)

Exctract event types

Description

Given a formula that specifies the status variable of the outcome, this function extracts the different event types (except for censoring, specified by censor_code).

Usage

get_event_types(data, formula, censor_code)

Arguments

Calculate predicted hazard

Description

Calculate predicted hazard

Usage

get_hazard(object, newdata, ...)

## Default S3 method:
get_hazard(
  object,
  newdata,
  reference = NULL,
  ci = TRUE,
  type = c("response", "link"),
  ci_type = c("default", "delta", "sim"),
  time_var = NULL,
  se_mult = 2,
  ...
)

Arguments

Information on intervals in which times fall

Description

Information on intervals in which times fall

Usage

get_intervals(x, times, ...)

## Default S3 method:
get_intervals(x, times, left.open = TRUE, rightmost.closed = TRUE, ...)

Arguments

Value

A data.frame containing information on intervals in which values of times fall.

See Also

findInterval int_info

Examples

set.seed(111018)
brks <- c(0, 4.5, 5, 10, 30)
int_info(brks)
x <- runif (3, 0, 30)
x
get_intervals(brks, x)

Construct or extract data that represents a lag-lead window

Description

Constructs lag-lead window data set from raw inputs or from data objects with suitable information stored in attributes, e.g., objects created by as_ped.

Usage

get_laglead(x, ...)

## Default S3 method:
get_laglead(x, tz, ll_fun, ...)

## S3 method for class 'data.frame'
get_laglead(x, ...)

Arguments

Examples

get_laglead(0:10, tz=-5:5, ll_fun=function(t, tz) { t >= tz + 2 & t <= tz + 2 + 3})
gg_laglead(0:10, tz=-5:5, ll_fun=function(t, tz) { t >= tz + 2 & t <= tz + 2 + 3})

Extract variables from the left-hand-side of a formula

Description

Extract variables from the left-hand-side of a formula

Extract variables from the right-hand side of a formula

Usage

get_lhs_vars(formula)

get_rhs_vars(formula)

Arguments

Extract variables from the left-hand-side of a formula

Description

Extract variables from the left-hand-side of a formula

Extract variables from the right-hand side of a formula

Usage

get_ped_form(
  formula,
  data = NULL,
  tdc_specials = c("concurrent", "cumulative")
)

Arguments

Extract plot information for all special model terms

Description

Given a mgcv gamObject, returns the information used for the default plots produced by plot.gam.

Usage

get_plotinfo(x, ...)

Arguments

Calculate simulation based confidence intervals

Description

Calculate simulation based confidence intervals

Usage

get_sim_ci(newdata, object, alpha = 0.05, nsim = 100L, ...)

helper function for add_trans_ci

Description

helper function for add_trans_ci

Usage

get_sim_cumu(newdata, ...)

Calculate survival probabilities

Description

Calculate survival probabilities

Usage

get_surv_prob(
  newdata,
  object,
  ci = TRUE,
  ci_type = c("default", "delta", "sim"),
  se_mult = 2L,
  time_var = NULL,
  interval_length = "intlen",
  nsim = 100L,
  ...
)

Arguments

Extract variables from the left-hand-side of a formula

Description

Extract variables from the left-hand-side of a formula

Extract variables from the right-hand side of a formula

Usage

get_tdc_form(
  formula,
  data = NULL,
  tdc_specials = c("concurrent", "cumulative"),
  invert = FALSE
)

Arguments

Extract variables from the left-hand-side of a formula

Description

Extract variables from the left-hand-side of a formula

Extract variables from the right-hand side of a formula

Usage

get_tdc_vars(formula, specials = "cumulative", data = NULL)

Arguments

Extract partial effects for specified model terms

Description

Extract partial effects for specified model terms

Usage

get_term(data, fit, term, n = 100, ...)

Arguments

Extract the partial effects of non-linear model terms

Description

This function basically creates a new df from data for each term in terms, creating a range from minimum and maximum of the predict(fit, newdata=df, type="terms"). Terms are then stacked to a tidy data frame.

Usage

get_terms(data, fit, terms, ...)

Arguments

Value

A tibble with 5 columns.

Examples

library(survival)
fit <- coxph(Surv(time, status) ~ pspline(karno) + pspline(age), data=veteran)
terms_df <- veteran %>% get_terms(fit, terms = c("karno", "age"))
head(terms_df)
tail(terms_df)

Forrest plot of fixed coefficients

Description

Given a model object, returns a data frame with columns variable, coef (coefficient), ci_lower (lower 95\ ci_upper (upper 95\

Usage

gg_fixed(x, intercept = FALSE, ...)

Arguments

See Also

tidy_fixed

Examples

g <- mgcv::gam(Sepal.Length ~ Sepal.Width + Petal.Length + Petal.Width + Species,
 data=iris)
gg_fixed(g, intercept=TRUE)
gg_fixed(g)

Plot Lag-Lead windows

Description

Given data defining a Lag-lead window, returns respective plot as a ggplot2 object.

Usage

gg_laglead(x, ...)

## Default S3 method:
gg_laglead(x, tz, ll_fun, ...)

## S3 method for class 'LL_df'
gg_laglead(
  x,
  high_col = "grey20",
  low_col = "whitesmoke",
  grid_col = "lightgrey",
  ...
)

## S3 method for class 'nested_fdf'
gg_laglead(x, ...)

Arguments

See Also

get_laglead

Examples

## Example 1: supply t, tz, ll_fun directly
 gg_laglead(1:10, tz=-5:5,
  ll_fun=function(t, tz) { t >= tz + 2 & t <= tz + 2 + 3})

## Example 2: extract information on t, tz, ll_from data with respective attributes
data("simdf_elra", package = "pammtools")
gg_laglead(simdf_elra)

Visualize effect estimates for specific covariate combinations

Description

Depending on the plot function and input, creates either a 1-dimensional slices, bivariate surface or (1D) cumulative effect.

Usage

gg_partial(data, model, term, ..., reference = NULL, ci = TRUE)

gg_partial_ll(
  data,
  model,
  term,
  ...,
  reference = NULL,
  ci = FALSE,
  time_var = "tend"
)

get_partial_ll(
  data,
  model,
  term,
  ...,
  reference = NULL,
  ci = FALSE,
  time_var = "tend"
)

Arguments

Plot Normal QQ plots for random effects

Description

Plot Normal QQ plots for random effects

Usage

gg_re(x, ...)

Arguments

See Also

tidy_re

Examples

library(pammtools)
data("patient")
ped <- patient %>%
 dplyr::slice(1:100) %>%
 as_ped(Surv(Survdays, PatientDied)~ ApacheIIScore + CombinedicuID, id="CombinedID")
pam <- mgcv::gam(ped_status ~ s(tend) + ApacheIIScore + s(CombinedicuID, bs="re"),
 data=ped, family=poisson(), offset=offset)
gg_re(pam)
plot(pam, select = 2)

Plot 1D (smooth) effects

Description

Flexible, high-level plotting function for (non-linear) effects conditional on further covariate specifications and potentially relative to a comparison specification.

Usage

gg_slice(data, model, term, ..., reference = NULL, ci = TRUE)

Arguments

Examples

ped <- tumor[1:200, ] %>% as_ped(Surv(days, status) ~ . )
model <- mgcv::gam(ped_status~s(tend) + s(age, by = complications), data=ped,
  family = poisson(), offset=offset)
make_newdata(ped, age = seq_range(age, 20), complications = levels(complications))
gg_slice(ped, model, "age", age=seq_range(age, 20), complications=levels(complications))
gg_slice(ped, model, "age", age=seq_range(age, 20), complications=levels(complications),
 ci = FALSE)
gg_slice(ped, model, "age", age=seq_range(age, 20), complications=levels(complications),
  reference=list(age = 50))

Plot smooth 1d terms of gam objects

Description

Given a gam model this convenience function returns a plot of all smooth terms contained in the model. If more than one smooth is present, the different smooth are faceted.

Usage

gg_smooth(x, ...)

## Default S3 method:
gg_smooth(x, fit, ...)

Arguments

Value

A ggplot object.

See Also

get_terms

Examples

g1 <- mgcv::gam(Sepal.Length ~ s(Sepal.Width) + s(Petal.Length), data=iris)
gg_smooth(iris, g1, terms=c("Sepal.Width", "Petal.Length"))

Plot tensor product effects

Description

Given a gam model this convenience function returns a ggplot2 object depicting 2d smooth terms specified in the model as heat/contour plots. If more than one 2d smooth term is present individual terms are faceted.

Usage

gg_tensor(x, ci = FALSE, ...)

Arguments

See Also

tidy_smooth2d

Examples

g <- mgcv::gam(Sepal.Length ~ te(Sepal.Width, Petal.Length), data=iris)
gg_tensor(g)
gg_tensor(g, ci=TRUE)
gg_tensor(update(g, .~. + te(Petal.Width, Petal.Length)))

Checks if data contains timd-dependent covariates

Description

Checks if data contains timd-dependent covariates

Usage

has_tdc(data, id_var)

Arguments

Value

Logical. TRUE if data contains time-dependent covariates, else FALSE.

Create start/end times and interval information

Description

Given interval breaks points, returns data frame with information on interval start time, interval end time, interval length and a factor variable indicating the interval (left open intervals). If an object of class ped is provided, extracts unique interval information from object.

Usage

int_info(x, ...)

## Default S3 method:
int_info(x, min_time = 0L, ...)

## S3 method for class 'data.frame'
int_info(x, min_time = 0L, ...)

## S3 method for class 'ped'
int_info(x, ...)

## S3 method for class 'pamm'
int_info(x, ...)

Arguments

Value

A data frame containing the start and end times of the intervals specified by the x argument. Additionally, the interval length, interval mid-point and a factor variable indicating the intervals.

See Also

as_ped ped_info

Examples

## create interval information from cut points
int_info(c(1, 2.3, 5))

## extract interval information used to create ped object
tdf <- data.frame(time=c(1, 2.3, 5), status=c(0, 1, 0))
ped <- tdf %>% as_ped(Surv(time, status)~., id="id")
int_info(ped)

Create design matrix from a suitable object

Description

Create design matrix from a suitable object

Usage

make_X(object, ...)

## Default S3 method:
make_X(object, newdata, ...)

## S3 method for class 'gam'
make_X(object, newdata, ...)

Arguments

Create design matrix from a suitable object

Description

Create design matrix from a suitable object

Usage

## S3 method for class 'scam'
make_X(object, newdata, ...)

Arguments

Construct a data frame suitable for prediction

Description

This functions provides a flexible interface to create a data set that can be plugged in as newdata argument to a suitable predict function (or similar). The function is particularly useful in combination with one of the add_* functions, e.g., add_term, add_hazard, etc.

Usage

make_newdata(x, ...)

## Default S3 method:
make_newdata(x, ...)

## S3 method for class 'ped'
make_newdata(x, ...)

## S3 method for class 'fped'
make_newdata(x, ...)

Arguments

Details

Depending on the type of variables in x, mean or modus values will be used for variables not specified in ellipsis (see also sample_info). If x is an object that inherits from class ped, useful data set completion will be attempted depending on variables specified in ellipsis. This is especially useful, when creating a data set with different time points, e.g. to calculate survival probabilities over time (add_surv_prob) or to calculate a time-varying covariate effects (add_term). To do so, the time variable has to be specified in ..., e.g., tend = seq_range(tend, 20). The problem with this specification is that not all values produced by seq_range(tend, 20) will be actual values of tend used at the stage of estimation (and in general, it will often be tedious to specify exact tend values). make_newdata therefore finds the correct interval and sets tend to the respective interval endpoint. For example, if the intervals of the PED object are (0,1], (1,2] then tend = 1.5 will be set to 2 and the remaining time-varying information (e.g. offset) completed accordingly. See examples below.

Examples

# General functionality
tumor %>% make_newdata()
tumor %>% make_newdata(age=c(50))
tumor %>% make_newdata(days=seq_range(days, 3), age=c(50, 55))
tumor %>% make_newdata(days=seq_range(days, 3), status=unique(status), age=c(50, 55))
# mean/modus values of unspecified variables are calculated over whole data
tumor %>% make_newdata(sex=unique(sex))
tumor %>% group_by(sex) %>% make_newdata()

# Examples for PED data
ped <- tumor %>% slice(1:3) %>% as_ped(Surv(days, status)~., cut = c(0, 500, 1000))
ped %>% make_newdata(age=c(50, 55))

# if time information is specified, other time variables will be specified
# accordingly and offset calculated correctly
ped %>% make_newdata(tend = c(1000), age = c(50, 55))
ped %>% make_newdata(tend = unique(tend))
ped %>% group_by(sex) %>% make_newdata(tend = unique(tend))

# tend is set to the end point of respective interval:
ped <- tumor %>% as_ped(Surv(days, status)~.)
seq_range(ped$tend, 3)
make_newdata(ped, tend = seq_range(tend, 3))

Create matrix components for cumulative effects

Description

These functions are called internally by get_cumulative and should usually not be called directly.

Usage

make_time_mat(data, nz)

make_latency_mat(data, tz)

make_lag_lead_mat(data, tz, ll_fun = function(t, tz) t >= tz)

make_z_mat(data, z_var, nz, ...)

Arguments

Calculate the modus

Description

Calculate the modus

Usage

modus(var)

Arguments

Create nested data frame from data with time-dependent covariates

Description

Provides methods to nest data with time-dependent covariates (TDCs). A formula must be provided where the right hand side (RHS) contains the structure of the TDCs

Usage

nest_tdc(data, formula, ...)

## Default S3 method:
nest_tdc(data, formula, ...)

## S3 method for class 'list'
nest_tdc(data, formula, ...)

Arguments

Fit a piece-wise exponential additive model

Description

A thin wrapper around gam, however, some arguments are prespecified: family=poisson() and offset=data$offset. These two can not be overwritten. In many cases it will also be advisable to set method="REML".

Usage

pamm(formula, data = list(), ..., trafo_args = NULL, engine = "gam")

is.pamm(x)

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

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

## S3 method for class 'pamm'
plot(x, ...)

Arguments

See Also

gam

Examples

ped <- tumor[1:100, ] %>%
 as_ped(Surv(days, status) ~ complications, cut = seq(0, 3000, by = 50))
pam <- pamm(ped_status ~ s(tend) + complications, data = ped)
summary(pam)
## Alternatively
pamm(
 ped_status ~ s(tend) + complications,
 data = tumor[1:100, ],
trafo_args = list(formula = Surv(days, status)~complications))

Survival data of critically ill ICU patients

Description

A data set containing the survival time (or hospital release time) among other covariates. The full data is available here. The following variables are provided:

Year

The year of ICU Admission

CombinedicuID

Intensive Care Unit (ICU) ID

CombinedID

Patient identificator

Survdays

Survival time of patients. Here it is assumed that patients survive until t=30 if released from hospital.

PatientDied

Status indicator; 1=death, 0=censoring

survhosp

Survival time in hospital. Here it is assumed that patients are censored at time of hospital release (potentially informative)

Gender

Male or female

Age

The patients age at Admission

AdmCatID

Admission category: medical, surgical elective or surgical emergency

ApacheIIScore

The patient's Apache II Score at Admission

BMI

Patient's Body Mass Index

DiagID2

Diagnosis at admission in 9 categories

Usage

patient

Format

An object of class data.frame with 2000 rows and 12 columns.

Extract interval information and median/modus values for covariates

Description

Given an object of class ped, returns data frame with one row for each interval containing interval information, mean values for numerical variables and modus for non-numeric variables in the data set.

Usage

ped_info(ped)

## S3 method for class 'ped'
ped_info(ped)

Arguments

Value

A data frame with one row for each unique interval in ped.

See Also

int_info, sample_info

Examples

ped <- tumor[1:4,] %>% as_ped(Surv(days, status)~ sex + age)
ped_info(ped)

S3 method for pamm objects for compatibility with package pec

Description

S3 method for pamm objects for compatibility with package pec

Usage

## S3 method for class 'pamm'
predictSurvProb(object, newdata, times, ...)

Arguments

Extract information on concurrent effects

Description

Extract information on concurrent effects

Usage

prep_concurrent(x, formula, ...)

## S3 method for class 'list'
prep_concurrent(x, formula, ...)

Arguments

Draw random numbers from piece-wise exponential distribution.

Description

This is a copy of the same function from rpexp from package msm. Copied here to reduce dependencies.

Usage

rpexp(n = 1, rate = 1, t = 0)

Arguments

Extract information of the sample contained in a data set

Description

Given a data set and grouping variables, this function returns mean values for numeric variables and modus for characters and factors. Usually this function should not be called directly but will rather be called as part of a call to make_newdata.

Usage

sample_info(x)

## S3 method for class 'data.frame'
sample_info(x)

## S3 method for class 'ped'
sample_info(x)

## S3 method for class 'fped'
sample_info(x)

Arguments

Value

A data frame containing sample information (for each group). If applied to an object of class ped, the sample means of the original data is returned. Note: When applied to a ped object, that doesn't contain covariates (only interval information), returns data frame with 0 columns.

Generate a sequence over the range of a vector

Description

Stolen from here

Usage

seq_range(x, n, by, trim = NULL, expand = NULL, pretty = FALSE)

Arguments

Examples

x <- rcauchy(100)
seq_range(x, n = 10)
seq_range(x, n = 10, trim = 0.1)
seq_range(x, by = 1, trim = 0.1)

# Make pretty sequences
y <- runif (100)
seq_range(y, n = 10)
seq_range(y, n = 10, pretty = TRUE)
seq_range(y, n = 10, expand = 0.5, pretty = TRUE)

seq_range(y, by = 0.1)
seq_range(y, by = 0.1, pretty = TRUE)

Simulate survival times from the piece-wise exponential distribution

Description

Simulate survival times from the piece-wise exponential distribution

Usage

sim_pexp(formula, data, cut)

Arguments

Examples

library(survival)
library(dplyr)
library(pammtools)

# set number of observations/subjects
n <- 250
# create data set with variables which will affect the hazard rate.
df <- cbind.data.frame(x1 = runif (n, -3, 3), x2 = runif (n, 0, 6)) %>%
 as_tibble()
# the formula which specifies how covariates affet the hazard rate
f0 <- function(t) {
 dgamma(t, 8, 2) *6
}
form <- ~ -3.5 + f0(t) -0.5*x1 + sqrt(x2)
set.seed(24032018)
sim_df <- sim_pexp(form, df, 1:10)
head(sim_df)
plot(survfit(Surv(time, status)~1, data = sim_df ))

# for control, estimate with Cox PH
mod <- coxph(Surv(time, status) ~ x1 + pspline(x2), data=sim_df)
coef(mod)[1]
layout(matrix(1:2, nrow=1))
termplot(mod, se = TRUE)

# and using PAMs
layout(1)
ped <- sim_df %>% as_ped(Surv(time, status)~., max_time=10)
library(mgcv)
pam <- gam(ped_status ~ s(tend) + x1 + s(x2), data=ped, family=poisson, offset=offset)
coef(pam)[2]
plot(pam, page=1)

## Not run: 
# Example 2: Functional covariates/cumulative coefficients
# function to generate one exposure profile, tz is a vector of time points
# at which TDC z was observed
rng_z = function(nz) {
  as.numeric(arima.sim(n = nz, list(ar = c(.8, -.6))))
}
# two different exposure times  for two different exposures
tz1 <- 1:10
tz2 <- -5:5
# generate exposures and add to data set
df <- df %>%
  add_tdc(tz1, rng_z) %>%
  add_tdc(tz2, rng_z)
df

# define tri-variate function of time, exposure time and exposure z
ft <- function(t, tmax) {
  -1*cos(t/tmax*pi)
}
fdnorm <- function(x) (dnorm(x,1.5,2)+1.5*dnorm(x,7.5,1))
wpeak2 <- function(lag) 15*dnorm(lag,8,10)
wdnorm <- function(lag) 5*(dnorm(lag,4,6)+dnorm(lag,25,4))
f_xyz1 <- function(t, tz, z) {
  ft(t, tmax=10) * 0.8*fdnorm(z)* wpeak2(t - tz)
}
f_xyz2 <- function(t, tz, z) {
  wdnorm(t-tz) * z
}

# define lag-lead window function
ll_fun <- function(t, tz) {t >= tz}
ll_fun2 <- function(t, tz) {t - 2 >= tz}
# simulate data with cumulative effect
sim_df <- sim_pexp(
  formula = ~ -3.5 + f0(t) -0.5*x1 + sqrt(x2)|
     fcumu(t, tz1, z.tz1, f_xyz=f_xyz1, ll_fun=ll_fun) +
     fcumu(t, tz2, z.tz2, f_xyz=f_xyz2, ll_fun=ll_fun2),
  data = df,
  cut = 0:10)

## End(Not run)

Simulate data for competing risks scenario

Description

Simulate data for competing risks scenario

Usage

sim_pexp_cr(formula, data, cut)

Simulated data with cumulative effects

Description

This is data simulated using the sim_pexp function. It contains two time-constant and two time-dependent covariates (observed on different exposure time grids). The code used for simulation is contained in the examples of ?sim_pexp.

Usage

simdf_elra

Format

An object of class nested_fdf (inherits from sim_df, tbl_df, tbl, data.frame) with 250 rows and 9 columns.

New basis for penalized lag selection

Description

Originally proposed in Obermeier et al., 2015, Flexible Distributed Lags for Modelling Earthquake Data, Journal of the Royal Statistical Society: Series C (Applied Statistics), 10.1111/rssc.12077. Here extended in order to penalize lead times in addition to lag times. Ideally the lag-lead window would then be selected in a data-driven fashion. Treat as experimental.

Usage

## S3 method for class 'fdl.smooth.spec'
smooth.construct(object, data, knots)

Arguments

Function to transform data without time-dependent covariates into piece-wise exponential data format

Description

Function to transform data without time-dependent covariates into piece-wise exponential data format

Usage

split_data(
  formula,
  data,
  cut = NULL,
  max_time = NULL,
  multiple_id = FALSE,
  ...
)

Arguments

See Also

survSplit

Split data to obtain recurrent event data in PED format

Description

Currently, the input data must be in start-stop notation for each spell and contain a colum that indicates the spell (event number).

Usage

split_data_multistate(
  formula,
  data,
  transition = character(),
  cut = NULL,
  max_time = NULL,
  event = 1L,
  min_events = 1L,
  timescale = c("gap", "calendar"),
  ...
)

Arguments

See Also

survSplit

Time until staphylococcus aureaus infection in children, with possible recurrence

Description

This dataset originates from the Drakenstein child health study. The data contains the following variables:

id

Randomly generated unique child ID

t.start

The time at which the child enters the risk set for the $k$-th event

t.stop

Time of $k$-th infection or censoring

.

enum

Event number. Maximum of 6.

hiv

Usage

staph

Format

An object of class tbl_df (inherits from tbl, data.frame) with 374 rows and 6 columns.

Extract fixed coefficient table from model object

Description

Given a model object, returns a data frame with columns variable, coef (coefficient), ci_lower (lower 95\ ci_upper (upper 95\

Usage

tidy_fixed(x, ...)

## S3 method for class 'gam'
tidy_fixed(x, intercept = FALSE, ...)

## S3 method for class 'coxph'
tidy_fixed(x, ...)

Arguments

Examples

library(survival)
gc <- coxph(Surv(days, status)~age + sex, data = tumor)
tidy_fixed(gc)

Extract random effects in tidy data format.

Description

Extract random effects in tidy data format.

Usage

tidy_re(x, keep = c("fit", "main", "xlab", "ylab"), ...)

Arguments

See Also

qqline

Extract 1d smooth objects in tidy data format.

Description

Extract 1d smooth objects in tidy data format.

Usage

tidy_smooth(x, keep = c("x", "fit", "se", "xlab", "ylab"), ci = TRUE, ...)

Arguments

Extract 2d smooth objects in tidy format.

Description

Extract 2d smooth objects in tidy format.

Usage

tidy_smooth2d(
  x,
  keep = c("x", "y", "fit", "se", "xlab", "ylab", "main"),
  ci = FALSE,
  ...
)

Arguments

Stomach area tumor data

Description

Information on patients treated for a cancer disease located in the stomach area. The data set includes:

days

Time from operation until death in days.

status

Event indicator (0 = censored, 1 = death).

age

The subject's age.

sex

The subject's sex (male/female).

charlson_score

Charlson comorbidity score, 1-6.

transfusion

Has subject received transfusions (no/yes).

complications

Did major complications occur during operation (no/yes).

metastases

Did the tumor develop metastases? (no/yes).

resection

Was the operation accompanied by a major resection (no/yes).

Usage

tumor

Format

An object of class tbl_df (inherits from tbl, data.frame) with 776 rows and 9 columns.

Warn if new t_j are used

Description

Warn if new t_j are used

Usage

warn_about_new_time_points(object, newdata, ...)

## S3 method for class 'pamm'
warn_about_new_time_points(object, newdata, ...)

Warn if new t_j are used

Description

Warn if new t_j are used

Usage

## S3 method for class 'glm'
warn_about_new_time_points(object, newdata, time_var, ...)