Package 'pammtools'

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,
  interval_length = "intlen",
  check_grouping = TRUE,
  ...
)

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

Arguments

Details

When computing cumulative incidence for multiple groups, the input data must be grouped via group_by() (by cause and any covariates) before calling this function. If newdata still contains several profiles per group (repeated time_var values within a group, typically a forgotten group_by()), the function now stops with an error rather than returning silently incorrect results, as the cumulative incidence would otherwise be accumulated across profiles rather than within each group.

The returned data contains one boundary row per group at time_var = 0 for plotting cumulative incidence from the time origin. On this row, cif = 0; if confidence intervals are requested, cif_lower = cif_upper = 0. If an interval-length column is present, it is set to 0 on the boundary row. add_cumu_hazard() adds an analogous boundary row (with cumu_hazard = 0) for continuous-time models (GAM/SCAM/PAMM), controllable via its boundary argument; interval-factor models (e.g. PEM via glm) keep the original prediction grid without a boundary row.

Examples

if (require("etm")) {
  data("fourD", package = "etm")
  ped_stacked <- fourD |>
    dplyr::select(-medication, -treated) |>
    as_ped(Surv(time, status) ~., id = "id") |>
    dplyr::mutate(cause = as.factor(cause))
  pam <- pamm(
    ped_status ~ s(tend, by = cause) + sex + sex:cause + age + age:cause,
    data = ped_stacked)
  ped_stacked |>
    make_newdata(tend = unique(tend), cause = unique(cause)) |>
    group_by(cause) |>
    add_cif(pam)
}

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

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

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)

Description

Convenience helper to manufacture interval-censored (panel) data from exact simulated survival times (e.g.\ the output of sim_pexp), for coverage studies and examples. Each subject is "inspected" at a sequence of times; the true event time is then only known to lie between the last clean and the first positive inspection. The exact time is retained (by default in column true_time) so that coverage can be scored against the truth.

Usage

add_inspections(
  data,
  time_var = "time",
  status_var = "status",
  mechanism = c("random", "fixed", "mixed"),
  rate = 1,
  schedule = NULL,
  max_time = NULL,
  terminal_exam = TRUE,
  keep_truth = TRUE,
  L = "L",
  R = "R"
)

Arguments

Value

data augmented with interval bounds in columns L and R (and true_time). Use Surv(L, R, type = "interval2") on the result.

See Also

pamm_ic, sim_pexp

Examples

set.seed(1)
df <- data.frame(x = runif(100, -1, 1))
sdf <- sim_pexp(~ -2 + 0.4 * x, df, cut = seq(0, 10, by = 0.5))
icd <- add_inspections(sdf, rate = 1)
fit <- pamm_ic(Surv(L, R, type = "interval2") ~ x, icd, m = 5)

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

## Default S3 method:
add_surv_prob(
  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_surv_prob(
  newdata,
  object,
  ci = TRUE,
  alpha = 0.05,
  nsim = 500L,
  time_var = NULL,
  interval_length = "intlen",
  check_grouping = TRUE,
  ...
)

Arguments

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.

The returned data contains one boundary row per group at time_var = 0 for plotting cumulative quantities from the time origin. On this row, surv_prob = 1; if confidence intervals are requested, surv_lower = surv_upper = 1. If an interval-length column is present, it is set to 0 on the boundary row.

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)

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

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. Shape-constrained additive models fit with scam are supported as well.

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)

Description

add_trans_prob adds transition probabilities on the provided data set and model. Optionally, confidence intervals (CI) are added if ci=TRUE. The function builds on cumulative hazards cumu_hazard and mgcv::gam models.

Usage

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

Arguments

Details

When computing transition probabilities for multiple groups, the input data must be grouped via group_by() before calling this function. If newdata still contains several covariate profiles per (group, transition) – i.e.\ repeated time_var values within a group once transition is added to the grouping, typically a forgotten group_by() – the function now stops with an error rather than returning silently incorrect results, as the transition probability would otherwise be accumulated across profiles rather than within each group.

The returned data contains one boundary row per group and transition at time_var = 0 for plotting transition probabilities from the time origin. On this row, trans_prob = 0; if confidence intervals are requested, trans_lower = trans_upper = 0. If an interval-length column is present, it is set to 0 on the boundary row.

Examples

data("prothr", package = "mstate")
  prothr <- prothr |>
    mutate(transition = as.factor(paste0(from, "->", to))
    , treat = as.factor(treat)) |>
    filter(Tstart != Tstop, id <= 100) |> select(-trans)
  ped <- as_ped(data= prothr, formula= Surv(Tstart, Tstop, status)~ .,
    transition = "transition", id= "id", timescale  = "calendar")
  pam <- mgcv::bam(ped_status ~ s(tend, by=transition) + transition * treat,
    data = ped, family = poisson(), offset = offset,
    method = "fREML", discrete = TRUE)
  ndf <- make_newdata(ped, tend  = unique(tend),
    treat  = unique(treat),
    transition = unique(transition)) |>
    group_by(treat, transition) |>  # important!
    add_trans_prob(pam)

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

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.

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)

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

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,
  time_var = "tend",
  interval_length = "intlen",
  ...
)

## S3 method for class 'scam'
get_cumu_coef(
  model,
  data,
  terms,
  time_var = "tend",
  interval_length = "intlen",
  ...
)

## 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

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

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)

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})

Description

Given a mgcv gamObject (or a scam object), returns the information used for the default plots produced by plot.gam (plot.scam, respectively).

Usage

get_plotinfo(x, ...)

Arguments

Description

Creates, for each requested univariate smooth, a sequence over the range of the smooth's numeric covariate, evaluates the term-wise contribution via predict(fit, newdata = ., type = "terms") and stacks the results into a tidy data frame.

Usage

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

Arguments

Details

For gam fits the requested terms are matched against the model's smooths (see get_smooth_terms): a bare variable name (e.g. "tend") selects every univariate smooth over that variable – the main effect s(tend) as well as any s(tend, by = ...) or factor-smooth interaction – while an exact smooth label (e.g. "s(tend)") selects a single smooth. Names that do not match any smooth (for example parametric factor main effects) are skipped with a warning; use gg_fixed for those. For factor-indexed smooths one curve per factor level is returned, identified by the level column.

For models without mgcv smooth metadata (e.g. coxph) terms must be supplied and is matched against the columns of predict(type = "terms").

Value

A tibble with columns term, x, level, eff, se, ci_lower and ci_upper.

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)

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)

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)

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

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)

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

Description

Given a gam model this convenience function returns a plot of its univariate smooth terms. If terms is not specified, all univariate smooths are plotted; otherwise only the requested ones (see get_terms for how terms are matched). Different smooths are faceted. Smooths that are indexed by a factor – a factor by-variable or a factor-smooth interaction (bs = "fs"/"sz") – are drawn in a single facet with one coloured/filled curve per factor level.

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"))
# all univariate smooths (terms omitted)
gg_smooth(iris, g1)
# factor-by smooth: one coloured curve per Species
g2 <- mgcv::gam(Sepal.Length ~ s(Sepal.Width, by = Species), data = iris)
gg_smooth(iris, g2, terms = "Sepal.Width")

Description

Creates a stacked area plot of state occupation probabilities over time, computed from transition probability matrices stored as an attribute of the input data. Optionally facets by a grouping variable.

Usage

gg_state_occupation(
  newdata,
  init_state,
  group_var = NULL,
  time_var = "tend",
  ncol = NULL
)

Arguments

Value

A ggplot object showing stacked-area state occupation probabilities over time, optionally faceted by group_var.

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

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.

The returned data frame contains tend, id, the user-supplied covariates (and cause/transition for competing risks / multi-state models). Internal PED columns tstart, intlen, interval, offset, and ped_status are dropped. Downstream add_* functions reconstruct intlen on demand via reconstruct_intlen() when needed. 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))

Description

This dataset originates from IAEA and contains 730 power. The data contains the following variables:

months

Construction time

status

Event indicator (0 = censored, 1 = construction finished).

region

Continent, Africa/Asia, America, Europe, Soviet Union and Warsaw Pact

Usage

nuclear

Format

An object of class data.frame with 724 rows and 3 columns.

Description

Competing-risks extension of pamm_ic. The event time is drawn from the all-cause conditional hazard within $(L, R]$ and a cause is assigned: observed causes are retained (with the time drawn so that it follows the cause-specific conditional density, via rejection), unknown causes are sampled with probability proportional to the cause-specific hazards at the imputed time (see impute_ic_cr). Each completed data set is transformed with as_ped_cr (cause-specific hazards) and re-fit. Cf. Delord & Genin (2016) for MI of interval-censored competing-risks data.

Usage

pamm_ic_cr(
  formula,
  data,
  cause,
  model_formula = NULL,
  cut = NULL,
  max_time = NULL,
  m = 10L,
  iter = 1L,
  censor_code = 0L,
  id = "id",
  engine = "gam",
  ...
)

Arguments

Value

An object of class pamm_ic with type = "cr"; fits are cause-specific (stacked ped_cr) pamm objects and cause_levels records the competing causes.

See Also

pamm_ic, add_cif

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.

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)

Description

S3 method for pamm objects for compatibility with package pec

Usage

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

Arguments

Description

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

Usage

## 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

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.

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.

See Also

impute_ic_times, add_surv_prob, strip_pamm_fit

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)

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)

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.

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.

Description

Extract random effects in tidy data format.

Usage

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

Arguments

See Also

qqline

Description

Extract 1d smooth objects in tidy data format.

Usage

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

Arguments

Description

Extract 2d smooth objects in tidy format.

Usage

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

Arguments

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.