multivariate.values: Extracting Multivariate Values

In randomForestSRC: Fast Unified Random Forests for Survival, Regression, and Classification (RF-SRC)

Extracting Multivariate Values

Description

Extract predictions, performance errors, variable importance (VIMP), and case-specific values from fitted random forests. The helpers collect response-specific results from multivariate regression, multivariate classification, and mixed-outcome forests. They also provide a common interface for univariate results. A helper for constructing a multivariate formula is included.

Usage

get.mv.predicted(obj, oob = TRUE)

get.mv.error(obj, standardize = FALSE, pretty = TRUE, block = FALSE)

get.mv.error.block(obj, standardize = FALSE)

get.mv.vimp(obj, standardize = FALSE, pretty = TRUE)

get.mv.cserror(obj, standardize = FALSE)

get.mv.csvimp(obj, standardize = FALSE)

get.mv.formula(ynames)

Arguments

obj	An object returned by rfsrc() or predict.rfsrc() containing the values to extract. For multivariate and mixed outcomes, retain the response columns in obj$yvar, including factor levels: these identify each response's type. VIMP and case-specific quantities must already be present in the object. See Details for survival and unavailable components.
oob	If TRUE, extract predicted.oob for each response when that component is present; otherwise use predicted. If FALSE, use predicted. Selection is made for the entire response component, not separately for each observation.
standardize	If TRUE, divide regression errors and VIMP by the variance of the corresponding response in obj$yvar, calculated with na.rm = TRUE. Classification and survival values are unchanged. The treatment of a zero or unavailable variance is described under Standardization.
pretty	If TRUE, return a compact error vector or VIMP matrix, retaining only the overall all entry for each classification response. If FALSE, return a response-named list and retain the class-specific entries. Competing-risk event-specific entries are retained in either form. This argument does not round the values.
block	If TRUE, extract the stored sequence of block errors from err.block.rate, rather than the final entry of err.rate. This forces pretty = FALSE. get.mv.error.block() is a shorthand for this choice.
ynames	Character vector of response names for get.mv.formula(). These should name columns in the data supplied to the subsequent forest fit.

Details

Predictions

get.mv.predicted() combines the stored predictions into a matrix with observations in rows. Each regression response supplies one column. Each classification response supplies one probability column per class, named response.class. The responses follow obj$yvar.names; class columns retain their stored order.

The default uses OOB predictions when available. An existing OOB component is retained even if some or all of its entries are missing. The fallback to predicted occurs only when that entire component is NULL. Use oob = FALSE to explicitly select full-ensemble or new-data predictions.

For right-censored survival, the helper extracts the stored mortality prediction. For competing risks, it extracts the event-specific predicted values, with names of the form response.event. It does not extract the time-indexed survival, cumulative hazard, or cumulative incidence arrays.

Performance errors and variable importance

get.mv.error() extracts the final stored performance error for each response. The error measure is the one used when the object was fitted or predicted; the helper does not recalculate it or change perf.type. With pretty = FALSE, classification output includes all and the class-specific errors. Survival output retains its stored error columns, including event-specific columns for competing risks.

get.mv.error.block() returns the full stored block-error sequence for each response. It is equivalent to get.mv.error(obj, standardize = standardize, block = TRUE). It does not choose a block size or form new blocks.

get.mv.vimp() collects the stored importance components. With pretty = TRUE, predictors index rows and results are combined across responses in columns. With pretty = FALSE, each response has its own matrix, preserving classification all and class-specific columns and competing-risk event columns. Request importance during fitting or use vimp before extracting it.

To select a response or predictor, subset the returned vector, matrix, or response-named list. These extraction calls do not fit trees, run prediction, or average errors or VIMP across responses.

Case-specific values

get.mv.cserror() obtains the case-specific error as cse.num / cse.den from the stored response component. get.mv.csvimp() similarly obtains case-specific VIMP as csv.num / csv.den. These quantities must have been retained during fitting or prediction; the helpers do not generate them from the ensemble predictions. In particular, case-specific error is not obtained by applying a loss to predicted.oob and the observed response.

With one response, the case-specific values are returned directly; with multiple responses, they are returned in a response-named list. Case-specific VIMP has observations in rows and the stored VIMP variables in columns. Variable names are attached when available from the importance component. Both helpers return NULL for right-censored survival and competing risks.

Standardization

For a regression response Y, standardize = TRUE divides each extracted error or importance value by var(Y, na.rm = TRUE). This uses the response values on the supplied object: training responses for a grow result and evaluation responses for a test-prediction result. It leaves predictions and all classification and survival values unchanged.

get.mv.error() and get.mv.vimp() divide by this variance directly; a zero or unavailable variance can therefore produce nonfinite values. The two case-specific helpers instead use divisor one when that variance is zero or NA. No standardization is applied by default.

Availability of stored results

Supply an object containing the requested output for its responses. Missing predictions and numerical NA values remain as stored. get.mv.error() returns NULL when all response errors are absent. Otherwise its compact output uses NA for an absent response error, while list output retains a NULL entry.

get.mv.vimp(), get.mv.cserror(), and get.mv.csvimp() return NULL when the first response has no corresponding component, even if a later response has one. When a response-named list is returned, absent later components remain NULL.

Constructing a multivariate formula

get.mv.formula(ynames) returns a formula of the form Multivar(y1, y2, ...) ~ .. The named responses may be continuous, factors, or a mixture; the forest fit determines their types from the supplied data. The dot denotes the remaining data columns. This helper constructs the formula only.

Value

get.mv.predicted

A numeric matrix with one row per observation and columns for the response predictions, class probabilities, or event-specific predictions. A single prediction column remains a matrix.

get.mv.error

A named numeric vector by default, or a response-named list when pretty = FALSE. Without blocking, each entry is the final stored error or final error row. With block = TRUE, list entries contain the stored block-error sequences. Returns NULL if all error components are absent.

get.mv.error.block

A response-named list of block-error vectors or matrices, or NULL when all are absent.

get.mv.vimp

A numeric matrix by default, or a response-named list of matrices when pretty = FALSE. Returns NULL under the availability rule described above.

get.mv.cserror

Case-specific error values for a single response, retaining their stored vector or array dimensions, or a response-named list for multiple responses. Returns NULL for survival families or under the availability rule above.

get.mv.csvimp

A case-by-variable matrix for a single response, or a response-named list of these matrices for multiple responses. Returns NULL for survival families or under the availability rule above.

get.mv.formula

An R formula with the supplied response names on the left of ~ and a dot on the right.

See Also

rfsrc, predict.rfsrc, vimp, subsample, classification.performance

Examples

## ------------------------------------------------------------
## A basic multivariate analysis
## ------------------------------------------------------------
o <- rfsrc(cbind(Ozone, Temp) ~ ., data = na.omit(airquality))
print(head(get.mv.predicted(o)))
print(get.mv.error(o))


## ------------------------------------------------------------
## Select a response from the stored results
## ------------------------------------------------------------
pred.oob <- get.mv.predicted(o)
print(head(pred.oob[, "Temp", drop = FALSE]))
print(get.mv.error(o)["Temp"])
print(get.mv.error(o, standardize = TRUE))
print(head(get.mv.predicted(o, oob = FALSE)))

## ------------------------------------------------------------
## Formula construction, VIMP, and block errors
## ------------------------------------------------------------
f <- get.mv.formula(c("Ozone", "Temp"))
print(f)

o.vimp <- rfsrc(f, data = na.omit(airquality), ntree = 100,
                importance = "permute", block.size = 10)
print(get.mv.vimp(o.vimp))
print(get.mv.vimp(o.vimp, standardize = TRUE))
print(get.mv.vimp(o.vimp, pretty = FALSE)[["Temp"]])
print(head(get.mv.error.block(o.vimp)[["Temp"]]))

## Optional case-specific values are NULL when not saved in the object.
print(get.mv.cserror(o.vimp))
print(get.mv.csvimp(o.vimp))

## ------------------------------------------------------------
## Mixed outcomes: retain class-specific entries
## ------------------------------------------------------------
f.mix <- get.mv.formula(c("Sepal.Length", "Species"))
mix <- rfsrc(f.mix, data = iris, ntree = 100,
             importance = "permute", block.size = 10)
print(colnames(get.mv.predicted(mix)))
print(get.mv.error(mix))
print(get.mv.error(mix, pretty = FALSE)[["Species"]])
print(get.mv.vimp(mix, pretty = FALSE)[["Species"]])

## ------------------------------------------------------------
## Extract predictions and errors for held-out observations
## ------------------------------------------------------------
dta <- na.omit(airquality)
set.seed(17)
train <- sample(seq_len(nrow(dta)), floor(.7 * nrow(dta)))
fit <- rfsrc(f, data = dta[train, ], ntree = 100)
p.test <- predict(fit, newdata = dta[-train, ])
print(head(get.mv.predicted(p.test, oob = FALSE)))
print(get.mv.error(p.test))

randomForestSRC documentation built on Sept. 16, 2026, 5:06 p.m.