Survival Probability Draws from a Survival Fit
survivalProbabilities.RdPosterior 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
bartobject from a survival model: an AFT model (itsfamilyelement equals"aft") or a discrete-time hazard model (it carries a$periodsgrid; itsfamilyrecords the binary link). A hazard fit must have kept its trees, asbartdoes for it by default (not with an explicitkeepTrees = FALSE), except to read the test subjects atestset that rode the fit call gave it (the matrix interface's own hazardtestacceptance, 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
timesis missing) is the training grid,object$periods.- newdata
Optional predictors at which to evaluate. When
NULLthe training observations are used, always: atestset that rode the fit call never changes what the call with nonewdatareturns, andsample = "test"is how to get its subjects. An AFT fit reads the training subjects from its stored draws; a hazardobjectmust have been fit withkeepTrees = TRUEto give them.- offset
The offset at the subjects of
newdata, aspredicttakes it: a single value or one per row ofnewdata, added to the fit'soffset()terms andoffsetargument evaluated onnewdata(seeoffsetinbart). For a hazard fit a subject's offset applies at every period. Withoutnewdataan offset replaces the fit's own at the subjects asked for, the training subjects' undersample = "train"and the test subjects' (theoffset.testthe 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 needskeepTrees = 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
newdatathat have missing values, resolved per subject before a hazard fit's person-period expansion. With nonewdatait answers the subjects whoseoffsethas a missing value, as it does for the rows ofnewdata: the default andna.failrefuse,na.passreturns the subject withNAcurves,na.omitdrops it andna.excludepads it back; a single missing value is always an error. See ‘At Prediction’ inna.keepPredictors.- sample
Either
"train"(the default) or"test", asextract's andfitted'ssampleare. With nonewdata,"train"gives the training subjects and"test"the subjects of thetestset 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 withnewdata, which gives other subjects: either value named besidenewdata,"train"as well as"test", is an error, sincesamplechooses among the fit's own subjects; leave it out to readnewdata's. Also refused on a fit that carries no test set or whose test drawskeepFits = FALSEdropped, 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
predicttakesbasesbut one value per subject (a hazard subject's value applies at every period, as its offset does), wherepredicttakes one per row of the person-periodnewdata: a list with an entry per forest, a bare value when one forest carries a basis, or the name of a column ofnewdata. Left out, the basis is read fromnewdataby the fit'sforest()terms, and with nonewdatathe 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)\) attimesalone.
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.
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