Skip to contents

Posterior draws of the survival probability \(S(t \mid x)\) from a survival fit: an accelerated failure time (AFT) log-normal fit produced by bart with family = "aft", or a discrete-time hazard fit produced by bart with family = "hazard" (or "hazard.logistic").

bart's four own-class fits ("bartMultinomial", "bartOrdinal", "bartNegbin", "bartHurdle") refuse by name instead: none of the four is a survival model, so none carries a hazard channel.

Usage

survivalProbabilities(object, ...)

# S3 method for class 'bart'
survivalProbabilities(
  object,
  times,
  newdata = NULL,
  offset = NULL,
  combineChains = TRUE,
  na.action = dbarts::na.keepPredictors,
  sample = c("train", "test"),
  bases = NULL,
  ...
)

# S3 method for class 'bartMultinomial'
survivalProbabilities(object, ...)

# S3 method for class 'bartOrdinal'
survivalProbabilities(object, ...)

# S3 method for class 'bartNegbin'
survivalProbabilities(object, ...)

# S3 method for class 'bartHurdle'
survivalProbabilities(object, ...)

Arguments

object

A fitted bart object from a survival model: an AFT model (its family element equals "aft") or a discrete-time hazard model (it carries a $periods grid; its family records the binary link). A hazard fit must have kept its trees, as bart does for it by default (not with an explicit keepTrees = FALSE), except to read the test subjects a test set that rode the fit call gave it (the matrix interface's own hazard test acceptance, person-period-expanded on the training grid): sample = "test" reads their stored draws and no trees are needed.

times

A numeric vector of times (on the original, non-logarithmic scale) at which to evaluate the survival function. For a discrete-time hazard fit the times are horizons on the period grid, and the default (when times is missing) is the training grid, object$periods.

newdata

Optional predictors at which to evaluate. When NULL the training observations are used, always: a test set that rode the fit call never changes what the call with no newdata returns, and sample = "test" is how to get its subjects. An AFT fit reads the training subjects from its stored draws; a hazard object must have been fit with keepTrees = TRUE to give them.

offset

The offset at the subjects of newdata, as predict takes it: a single value or one per row of newdata, added to the fit's offset() terms and offset argument evaluated on newdata (see offset in bart). For a hazard fit a subject's offset applies at every period. Without newdata an offset replaces the fit's own at the subjects asked for, the training subjects' under sample = "train" and the test subjects' (the offset.test the fit stored) under "test", one value or one per subject of that set. An AFT fit's is read off the stored draws with no trees replayed; so is a hazard fit's at its test subjects, on the latent scale before the link, while a hazard fit replays its trees at the training subjects, as it does for any of them, and needs keepTrees = TRUE.

combineChains

A logical determining whether the chain dimension is collapsed into the draw dimension, as elsewhere in the package.

na.action

What to do with the subjects in newdata that have missing values, resolved per subject before a hazard fit's person-period expansion. With no newdata it answers the subjects whose offset has a missing value, as it does for the rows of newdata: the default and na.fail refuse, na.pass returns the subject with NA curves, na.omit drops it and na.exclude pads it back; a single missing value is always an error. See ‘At Prediction’ in na.keepPredictors.

sample

Either "train" (the default) or "test", as extract's and fitted's sample are. With no newdata, "train" gives the training subjects and "test" the subjects of the test set that rode the fit call, read from the draws the fit stored, with no trees: a hazard fit's stored test grid, an AFT fit's stored test fit and, on a heteroscedastic fit, its stored test scale. Refused, by name, together with newdata, which gives other subjects: either value named beside newdata, "train" as well as "test", is an error, since sample chooses among the fit's own subjects; leave it out to read newdata's. Also refused on a fit that carries no test set or whose test draws keepFits = FALSE dropped, the message naming both causes and, on a fit kept without trees, a test set at the fit or the trees as what would answer it.

bases

For a fit of several forests with a basis, the basis at the subjects, as predict takes bases but one value per subject (a hazard subject's value applies at every period, as its offset does), where predict takes one per row of the person-period newdata: a list with an entry per forest, a bare value when one forest carries a basis, or the name of a column of newdata. Left out, the basis is read from newdata by the fit's forest() terms, and with no newdata the training subjects keep their own. Refused on a fit that has one forest.

...

Not a formal on the method: a name belonging to a sibling generic (type, ci.level, weights, n.threads, forest, contribution) is refused by name rather than silently ignored, since this method returns the draws of \(S(t \mid x)\) at times alone.

Details

Under the log-normal AFT model \(\log T = f(x) + \sigma \epsilon\) with \(\epsilon \sim N(0, 1)\), the survival function is $$S(t \mid x) = 1 - \Phi\left(\frac{\log t - f(x)}{\sigma}\right),$$ where \(f(x)\) is the linear predictor \(E[\log T \mid x]\) - the log-time-scale quantity that predict and extract return for an "aft" fit, the offset included - and \(\sigma\) the residual standard deviation. The probability is evaluated at every posterior draw of \(f(x)\) and \(\sigma\), following the package's convention that draw-level functions return draws: take means or quantiles over the draw margin for point estimates and credible bands.

For a discrete-time hazard fit, the survival function is the cumulative product $$S(t \mid x) = \prod_{k \,:\, \mathrm{periods}[k] \le t} (1 - h(k \mid x)),$$ where \(h(k \mid x) = g(f(x, k) + o)\) is the per-period hazard through the fit's binary link \(g\) and \(o\) the subject's offset: the fit's own on the training subjects, and on newdata the one formed from offset as above. Because the training design is ragged (each subject carries only its at-risk rows), the method ALWAYS re-expands its subjects onto the full grid and replays the trees - so it requires keepTrees = TRUE even for the training data (newdata = NULL). With newdata, each new subject is expanded to one row per period and its curve evaluated the same way. The one exception: a test set that rode the fit call (the matrix interface's own hazard test acceptance) was already person-period-expanded on the SAME training grid at fit time, so its hazards are stored on the fit already - sample = "test" on such a fit reads them directly with no re-expansion and no trees needed. The call with no newdata is the training subjects whether or not the fit carries a test set.

Value

An array of survival probabilities. With combineChains = TRUE the dimensions are draws \(\times\) times \(\times\) observations; with combineChains = FALSE a chain dimension precedes them (chains \(\times\) draws \(\times\) times \(\times\) observations), length 1 on a one-chain fit rather than dropped, as extract and predict keep theirs. Observations are those of newdata, or the training data when newdata is NULL, or with sample = "test" the test set.

See also

Author

Vincent Dorie: vdorie@gmail.com.

Examples

set.seed(42)
n <- 100L
x <- matrix(runif(n * 2L), n, 2L)
eventTime <- exp(x[, 1L] + 0.5 * rnorm(n))
censorTime <- exp(x[, 1L] + 0.25 + 0.5 * rnorm(n))
status <- as.numeric(eventTime <= censorTime)
observedTime <- pmin(eventTime, censorTime)

fit <- bart(
  x,
  cbind(observedTime, status),
  family = "aft",
  n.trees = 25L,
  n.burn = 50L,
  n.samples = 100L,
  n.chains = 1L,
  verbose = FALSE
)

surv <- survivalProbabilities(fit, times = c(0.5, 1, 2))
dim(surv) # draws x times x observations
#> [1] 100   3 100

## posterior-mean survival curve and 90% band for the first observation
apply(surv[, , 1L], 2L, mean)
#> [1] 0.9967963 0.9301631 0.5618901
apply(surv[, , 1L], 2L, quantile, probs = c(0.05, 0.95))
#>          [,1]      [,2]      [,3]
#> 5%  0.9876239 0.8237465 0.3227842
#> 95% 0.9998395 0.9829159 0.7550134