Tune tree size for Random Hazard Forests

Tune the treesize for a Random Hazard Forest using either out-of-bag (OOB) empirical risk or an OOB integrated AUC computed by auct.rhf.

tune.treesize.rhf(
  formula,
  data,
  ntree = 500,
  nsplit = 10,
  nodesize = NULL,
  ntime = 50,
  min.events.per.gap = 10,
  adaptive = TRUE,
  perf = c("risk", "iAUC"),
  auct.args = NULL,
  lower = 5L,
  upper = NULL,
  C = 3,
  method = c("golden", "bisect"),
  max.evals = 20L,
  bracket.tol = 2L,
  seed = NULL,
  verbose = TRUE,
  forest = TRUE,
  ...
)


tune.iAUC.rhf(
  formula,
  data,
  auct.args = NULL,
  adaptive = TRUE,
  ...
)

# S3 method for class 'tune.treesize.rhf'
plot(x, ylab = NULL, main = NULL,
    se.band = TRUE, se.mult = 1, ylim = NULL, ...)

Arguments

formula: Survival formula for rhf. The response may be ordinary right-censored data, Surv(time, event), or counting-process data, Surv(id, start, stop, event).
data: Data frame containing the variables in formula. Ordinary right-censored input has one row per subject; counting-process input may have multiple rows per subject.
ntree: Number of trees grown at each candidate treesize.
nsplit: Number of random split points tried per variable.
nodesize: Minimum number of events in a terminal node; passed to rhf.
ntime: Controls the working time grid used by every candidate rhf fit and by the final refit. It has the same meaning and default as in rhf. When upper = NULL, it is also used when processing the event information for the automatic tuning range.
min.events.per.gap: Minimum number of observed events required in each working-time interval when ntime is specified as an integer. The value is passed to every candidate rhf fit and to the final refit. When upper = NULL, it also determines the package-default tree size and event-support limit used to construct the automatic upper bound.
adaptive: Logical flag passed to rhf. When TRUE, each candidate forest uses the default adaptive trimming protocol. When FALSE, each candidate forest uses the fixed trimming fraction 0.05, so the tuning criterion varies with treesize while holding this hazard aggregation setting fixed.
perf: Tuning criterion. "risk" minimizes mean OOB risk; "iAUC" maximizes integrated AUC obtained using auct.rhf.
auct.args: Optional list of arguments passed to auct.rhf when perf = "iAUC".
lower: Smallest treesize considered.
upper: Largest treesize considered. If NULL, the upper bound is computed from the event information used by rhf. Specifically, it is the smaller of C times the package-default tree size and the event-supported limit floor(ndead / min.events.per.gap), where ndead is the number of events remaining after RHF data processing.
C: Multiplier applied to the package-default tree size when computing the automatic upper bound. The resulting value is capped by the event-supported limit.
method: Discrete search strategy: "golden" (golden-section search) or "bisect" (bisection-style search).
max.evals: Maximum number of distinct treesize values evaluated by the search.
bracket.tol: Tolerance for the bracketing interval width used by the search algorithms.
seed: Optional random seed for reproducible comparisons across tree sizes.
verbose: Logical; if TRUE, print progress messages when evaluating new treesize values.
forest: Logical; if TRUE, return the RHF object at the best treesize.
...: Additional arguments passed to rhf.
x, ylab, main, se.band, se.mult, ylim: Arguments to customize plot.

Details

The alias tune.rhf is provided for convenience.

Repeatedly fits a hazard forest with different values of treesize and selects the value that optimizes the chosen criterion perf. Ordinary Surv(time, event) input is converted internally to the same one-interval counting-process representation used by rhf. The tuning preflight, automatic upper bound, all candidate forests, and the final refit therefore use the same effective subjects and event information. The returned forest retains the original right-censored response names and can be used directly with ordinary survival test data through predict.rhf().

When perf = "risk", the criterion is the mean OOB risk. When perf = "iAUC", auct.rhf is applied to each fit and the criterion is 1 - iAUC.uno. tune.iAUC is a wrapper around tune.rhf with perf = "iAUC", using default auct.rhf settings when auct.args = NULL.

Because the default RHF fit adaptively selects the trimming fraction by OOB risk, tuning by OOB risk can otherwise combine the choice of treesize with adaptive trimming. Use adaptive = FALSE for a controlled tree-size search that fixes the trimming fraction at coe.trim = 0.05.

Value

An object of class "tune.treesize.rhf" with components

best.size: optimal treesize;
best.err: minimal criterion value (mean OOB risk if perf = "risk", or 1 - iAUC.uno if perf = "iAUC");
path: data frame with evaluated treesize values and corresponding criterion values (and an iAUC column when perf = "iAUC");
n.subjects: number of subjects remaining after RHF input processing;
adaptive: logical value indicating whether adaptive trimming was used during tuning;
forest: RHF fit at best.size when forest = TRUE.

Examples

# \donttest{
## ------------------------------------------------------------
## Example: tuning treesize by OOB empirical risk
## ------------------------------------------------------------

data(pbc, package = "randomForestSRC")
pbc.raw <- na.omit(pbc)
set.seed(7)
trn <- sample(
  seq_len(nrow(pbc.raw)),
  size = floor(0.75 * nrow(pbc.raw)),
  replace = FALSE
)

d <- pbc.raw[trn, , drop = FALSE]
tst <- pbc.raw[-trn, , drop = FALSE]
f <- Surv(days, status) ~ .

## tune.rhf is an alias for tune.treesize.rhf; no manual conversion is needed
tuneRisk <- tune.rhf(f, d)  ## same as tune.treesize.rhf(f, d)

## For a controlled tree-size search, keep the trimming fraction fixed.
tuneRisk.fixed <- tune.rhf(f, d, adaptive = FALSE)

oldpar <- par(mfrow = c(1, 1))
plot(tuneRisk)
par(oldpar)

tuneRisk$best.size    # treesize minimizing mean OOB risk
tuneRisk$best.err

## Access the tuned forest and refit AUC diagnostics if desired
best.forest <- tuneRisk$forest
a.risk <- auct.rhf(best.forest)
print(a.risk$iAUC.uno)

## the tuned forest accepts the ordinary PBC test data directly
print(predict(best.forest, tst))


## ------------------------------------------------------------
## Example: tuning treesize by iAUC
## ------------------------------------------------------------

set.seed(7)
f <- "Surv(id, start, stop, event) ~ ."
d <- hazard.simulation(1, n=100)$dta
tuneiAUC <- tune.iAUC(f, d)

oldpar <- par(mfrow = c(1, 1))
plot(tuneiAUC)
par(oldpar)

print(tuneiAUC$best.size)
print(1 - tuneiAUC$best.err)

best.forest.iauc <- tuneiAUC$forest
a.iauc <- auct.rhf(best.forest.iauc)
print(1 - a.iauc$iAUC.uno)


## ------------------------------------------------------------
## Example: tuning treesize by iAUC with bootstrap s.e.
## ------------------------------------------------------------

set.seed(7)
f <- "Surv(id, start, stop, event) ~ ."
d <- hazard.simulation(1, n=100)$dta
tuneiAUC.boot <- tune.iAUC(f, d, auct.args=list(bootstrap.rep=25))
oldpar <- par(mfrow = c(1, 1))
plot(tuneiAUC.boot)        
par(oldpar)

## ------------------------------------------------------------
## Example: tuning by hazard-based incident AUC
## increase min.cases for stability
## ------------------------------------------------------------

set.seed(7)
f <- "Surv(id, start, stop, event) ~ ."
d <- hazard.simulation(1, n=100)$dta
tuneHazInc <- tune.iAUC(
  f, d,
  auct.args = list(
    min.cases    = 5,
    marker       = "hazard",
    method       = "incident"
  )
)

oldpar <- par(mfrow = c(1, 1))
plot(tuneHazInc)
par(oldpar)

print(tuneHazInc$best.size)
print(tuneHazInc$best.err)

## Confirm the tuned incident AUC on the selected forest
best.forest.haz <- tuneHazInc$forest
aHazInc <- auct.rhf(
  best.forest.haz,
  min.cases = 5,
  marker  = "hazard",
  method  = "incident"
)
print(aHazInc)
print(1 - aHazInc$iAUC.uno)

# }

Arguments

Details

Value

See also

Examples