Package 'RLT'

survival time

The censoring indicator if survival model is used

the predicted value for each subject

A fitted RLT object.

The dataset for prediction. This calculates an $n_1 \times n_1$ kernel matrix of X1.

The dataset for reference/training. If X2 is supplied, then calculate an $n_1 \times n_2$ kernel matrix. If vs.train is used, then this must be the original training data.

To calculate the kernel weights with respect to the training data. This is slightly different than supplying the training data to X2 due to re-samplings of the training process. To use this feature, you must specify resample.track = TRUE in param.control when fitting the forest

Whether fitting should be printed.

... Additional arguments.

A fitted RLT object

the tree number, starting from 1 to ntrees.

...

A RLT prediction object. Must be from a forest with var.mode != "none".

Observation number in the prediction. Default to calculate all (i = 0).

alpha level for interval (alpha/2, 1 - alpha/2).

Confidence band approach:

• naive: marsd = sqrt(diag(Cov)), MC band using full covariance.

• smoothed: GAM-smoothed rank-K covariance + eigenvalue-ratio weighted residual correction.

Number of simulations for estimating the Monte Carlo critical value.

Rank truncation K used for the smooth low-rank covariance AND GAM basis size.

Rank selection mode: "fixed" (use k_rank) or "proportion" (auto-select by eigenvalue cumulative ratio).

Proportion threshold (0,1] for cumulative eigenvalue ratio when k_mode = "proportion".

Further arguments (currently not used).

A fitted RLT object from RLT.

Additional arguments (unused).

A fitted RLT object

The testing samples, must have the same structure as the training samples

Whether to estimate the variance of each testing data. The original forest must be fitted with var.mode != "none". For survival forests, calculates the covariance matrix over all observed time points and calculates critical value for the confidence band.

Variance estimation mode for prediction. Can be "none", "matched", "IJ", or "jack". If NULL (default), uses the mode from the fitted object. Only used when var.est = TRUE. "matched" requires the forest to be fitted with var.mode = "matched". "IJ" and "jack" require the forest to have been fitted with resample tracking (automatically enabled when using IJ or jack variance).

whether to keep the prediction from all trees. Warning: this can occupy a large storage space, especially in survival model

number of cores

print additional information

An integer specifying the number of time points for confidence band calculation. Default is 0, which uses all unique failure time points. If a positive integer is provided, a subset of time points will be selected using quantiles, skipping the earliest 5% of time points to improve stability.

...

Prediction

if var.est = TRUE and the fitted object is var.mode != "none"

predicted hazard functions

predicted cumulative hazard function

predicted survival function

if keep.all = TRUE, the predicted hazard function for each observation and each tree

if keep.all = TRUE, the predicted cumulative hazard function for each observation and each tree

if var.est = TRUE and the fitted object is var.mode != "none". For each test subject, a matrix of size NFail$\times$NFail where NFail is the number of observed failure times in the training data

if var.est = TRUE and the fitted object is var.mode != "none". Marginal variance for each subject

ordered observed failure times from the training data

if var.est = TRUE and the fitted object is var.mode != "none". Marginal variance for each subject from the Cov matrix projected to the nearest positive definite matrix

if var.est = TRUE and the fitted object is var.mode != "none". Marginal variance for each subject from the Cov matrix projected to the nearest positive definite matrix and then smoothed using Gaussian kernel smoothing

if var.est = TRUE and the fitted object is var.mode != "none". Critical values to calculate confidence bands around cumulative hazard predictions at several confidence levels. Calculated using MarginalVar

if var.est = TRUE and the fitted object is var.mode != "none". Critical values to calculate confidence bands around cumulative hazard predictions at several confidence levels. Calculated using MarginalVarSmooth

An importance.RLT object.

Number of digits for formatting. Default: 4.

Additional arguments (unused).

A fitted RLT object

...

A matrix or data.frame of features. If x is a data.frame, then all factors are treated as categorical variables, which will go through an exhaustive search of splitting criteria.

Response variable. a numeric/factor vector.

Censoring indicator if survival model is used.

The model type: "regression", "classification", or "survival". Quantile forest is not yet implemented.

Number of trees, ntrees = 100 if reinforcement is used and ntrees = 500 otherwise.

Number of randomly selected variables used at each internal node. Default: max(1, floor(p/2)).

Terminal node size. Splitting will stop when the internal node size is less equal to nmin. Default: 5.

Minimum proportion of samples (of the parent node) enforced in each child node. Default: 0 (no constraint). Clamped to the range 0 to 0.5.

Number of random cutting points to compare for each variable at an internal node. Default: 0 (use all unique values, i.e., best split). When nsplit > 0, random cutting points are generated.

Whether the in-bag samples are obtained with replacement.

Proportion of in-bag samples.

A pre-specified matrix for in-bag data indicator/count matrix. It must be an $n \times$ ntrees matrix with integer entries. Positive number indicates the number of copies of that observation (row) in the corresponding tree (column); zero indicates out-of-bag; negative values indicates not being used in either. Extremely large counts should be avoided. The sum of each column should not exceed $n$.

Observation weights. The weights will be used for calculating the splitting scores, such as a weighted variance reduction or weighted gini index. But they will not be used for sampling observations. In that case, one can pre-specify resample.preset instead for balanced sampling, etc. For survival analysis, observation weights are supported in the "logrank", "suplogrank", and "coxgrad" splitting rules. Weighted logrank and suplogrank use a variance estimator that accounts for the observation weights.

Variable probabilities for split variable selection. A numeric vector of length p (number of predictors) with non-negative weights. When supplied, mtry variables are sampled without replacement with probabilities proportional to these weights at each internal node. This effectively up-weights or down-weights individual predictors during tree construction. Works for all models (regression, classification, survival). The vector does not need to sum to 1; it is internally normalized. If NULL (default), uniform sampling is used.

Whether to calculate variable importance measures. When set to "TRUE" (or "permute"), the calculation follows Breiman's original permutation strategy. If set to "distribute", then it sends the oob data to both child nodes with weights proportional to their sample sizes. Hence the final prediction is a weighted average of all possible terminal nodes that a perturbed observation could fall into. This feature is currently only available in regression and classification models.

Should reinforcement splitting rule be used. Default is "FALSE", i.e., regular random forests with marginal search of splitting variable. When it is activated, an embedded model is fitted to find the best splitting variable or a linear combination of them, if linear.comb $> 1$. They can also be specified in param.control.

Number of variables to combine in each linear combination split. Default is 1 (standard axis-aligned splits). See also linear.comb.method and param.control.

Method for constructing linear combinations: "default", "coxph" (Cox PH loading, survival only), or "naive" (covariance-based loading). See param.control.

Splitting criterion. Default "default" selects the standard rule for each model. For survival: "logrank", "suplogrank", or "coxgrad". See param.control.

Variance estimation mode. Default is "none" (no variance estimation). Set to "matched" or TRUE to use matched-sample U-statistic decomposition for prediction variance and variable importance variance. When active, several resampling parameters are automatically adjusted. Equivalent to setting param.control = list(var.mode = "matched"). See param.control for full details.

A list of additional parameters. This can be used to specify other features in a random forest or set embedded model parameters for reinforcement splitting rules. Using reinforcement = TRUE will automatically generate some default tuning for the embedded model. Reinforcement is available for regression, classification, and survival models. They are not necessarily optimized.

• embed.ntrees: number of trees in the embedded model. Default: 50.

• embed.mtry: proportion of variables for embedded splits. Default: 0.5.

• embed.nmin: terminal node size for embedded model. Default: 5.

• embed.nsplit: number of random cutting points. Default: 3.

• embed.resample.replace: whether to sample with replacement. Default: TRUE.

• embed.resample.prob: proportion of samples (of the internal node) in the embedded model. Default: 0.9.

• embed.mute: variables to mute per split. If >= 1: exact count; if < 1: proportion. Default: 0 (no muting).

• embed.protect: number of top variables to protect from muting. Default: ceiling(log(n)).

• embed.threshold: threshold, as a fraction of the best VI, for being included in the protected set at an internal node. Default: 0.25.

• linear.comb: number of variables to use in linear combination splits. Requires reinforcement = TRUE. Default: 1 (no linear combination).

• linear.comb.method: method for constructing linear combination splits. Regression: "naive" (1), "lm" (2), "pca" (3), "sir" (4, default). Classification: "lda" (1, default), "naive" (2), "random" (3), "logistic" (4).

• time.grid.size: number of unique time points for survival estimation (default 0 = all). See time.grid.size argument for details.

                   See \code{linear.comb} and \code{linear.comb.method} under
                   \code{param.control} documentation above.

                   \code{split.rule} specifies the splitting criterion for each model type.
                   \itemize{
                   \item \strong{Regression}: \code{"var"} (variance reduction, default and only option)
                   \item \strong{Classification}: \code{"gini"} (Gini index, default and only option)
                   \item \strong{Survival}: \code{"logrank"} (default), \code{"suplogrank"}, \code{"coxgrad"}
                   }
                   Internally mapped to integers: var=1, gini=1, logrank=1, suplogrank=2, coxgrad=3.

                   \code{resample.track} indicates whether to keep track
                   of which observations are used in each tree. This is
                   required for variance estimation (via \code{var.mode}).

                   \code{var.mode} specifies the variance estimation method
                   to prepare during model fitting. Currently available methods:
                   \itemize{
                   \item \code{"none"} (default): No variance estimation.
                   \item \code{"matched"}: Uses matched-sample U-statistic
                   decomposition (Xu, Zhu & Shao, 2023) for prediction
                   variance and variable importance variance. Also used for
                   confidence band in survival models (Formentini, Liang & Zhu, 2023).
                   }
                   Specifying \code{var.mode = TRUE} is equivalent to
                   \code{var.mode = "matched"}.
                   When \code{var.mode} is not \code{"none"}, the following
                   parameters are automatically adjusted if not already set:
                   \itemize{
                   \item \code{resample.preset} is constructed automatically
                   \item \code{resample.replace} is set to \code{FALSE}
                   \item \code{resample.prob} is set to 0.5
                   \item \code{resample.track} is set to \code{TRUE}
                   \item \code{importance} is set to \code{"distribute"}
                   }

                   It is recommended to use a very large \code{ntrees},
                   e.g, 10000 or larger. For \code{resample.prob} greater
                   than 0.5, one should consider the bootstrap
                   approach in Xu, Zhu & Shao (2023).

                   \\code{time.grid.size} specifies the number of unique
                   time points used for survival estimation. By default
                   (0), all observed failure times are used. Setting a
                   smaller number (e.g., 50) can speed up computation
                   for large datasets. The time points are selected at
                   evenly spaced quantiles of the observed failure times,
                   always including the minimum and maximum failure times.

Number of CPU logical cores. Default is 0 (using all available cores).

Whether info should be printed.

Random seed number to replicate a previously fitted forest. Internally, the ⁠xoshiro256++⁠ generator is used. If not specified, a seed will be generated automatically and recorded.

Additional arguments.

Fitted tree structures

Variable importance measures, if importance = TRUE

Out-of-bag prediction

Out-of-bag prediction error, adaptive to the model type

Provided if resample.track = TRUE, var.mode != "none", or if resample.preset was supplied. This is an n $\times$ ntrees matrix that has the same meaning as resample.preset.

The number of classes

Out-of-bag predicted probability

ordered observed failure times

The number of observed failure times

Out-of-bag prediction of hazard function