pammtools (version 0.8.1)

get_terms: Extract the partial effects of univariate smooth model terms

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

Value

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

Arguments

data

A data frame containing variables used to fit the model. The first row is used as the basis for all covariates other than the one being varied (their values are irrelevant for the term-wise contribution).

fit

A fitted object of class gam.

terms

A character vector (can be length one) specifying the terms for which partial effects will be returned. If NULL (the default) all univariate smooth terms in the model are used.

...

Further arguments controlling extraction, passed on per term, e.g. n (number of evaluation points) and conf_level.

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

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)