shadow_vimp {shadowVIMP}R Documentation

Select influential covariates in random forests using multiple testing control

Description

shadow_vimp() performs variable selection and determines whether each covariate is influential based on unadjusted, FDR-adjusted, and FWER-adjusted p-values.

Usage

shadow_vimp(
  alphas = c(0.3, 0.1, 0.05),
  niters = c(30, 120, 1500),
  data,
  outcome_var,
  num.trees = max(2 * (ncol(data) - 1), 10000),
  num.threads = NULL,
  importance = "permutation",
  save_vimp_history = c("all", "last", "none"),
  to_show = c("FWER", "FDR", "unadjusted"),
  method = c("pooled", "per_variable"),
  ...
)

Arguments

alphas

Numeric vector, significance level values for each step of the procedure, default c(0.3, 0.10, 0.05).

niters

Numeric vector, number of permutations to be performed in each step of the procedure, default c(30, 120, 1500).

data

Input data frame.

outcome_var

Character, name of the column containing the outcome variable.

num.trees

Numeric, number of trees. Passed to ranger::ranger(), default is max(2 * (ncol(data) - 1), 10000).

num.threads

Numeric. The number of threads used by ranger::ranger() for parallel tree building. If NULL (the default), half of the available CPU threads are used (this is the default behaviour in shadow_vimp(), which is different from the default in ranger::ranger()). See the ranger::ranger() documentation for more details.

importance

Character, the type of variable importance to be calculated for each variable. Argument passed to ranger::ranger(), default is permutation.

save_vimp_history

Character, specifies which variable importance measures to save. Possible values are:

  • "all" (the default) - save variable importance measures from all steps of the procedure (both the pre-selection phase and the final selection step).

  • "last" - save only the variable importance measures from the final step.

  • "none" - do not save any variable importance measures.

to_show

Character, one of "FWER", "FDR" or "unadjusted".

  • "FWER" (the default) - the output includes unadjusted, Benjamini-Hochberg (FDR) and Holm (FWER) adjusted p-values together with the decision whether the variable is significant or not (1 - significant, 0 means not significant) according to the chosen criterium.

  • "FDR" - the output includes both unadjusted and FDR adjusted p-values along with the decision.

  • ⁠"unadjusted:⁠ - the output contains only raw, unadjusted p-values together with the decision.

method

Character, one of "pooled" or "per_variable".

  • "pooled" (the default) - the results of the final step of the procedure show the p-values obtained using the "pooled" approach and the corresponding decisions.

  • "per_variable" - the results of the final step of the procedure show the p-values obtained using the "per variable" approach and the corresponding decisions.

...

Additional parameters passed to ranger::ranger().

Details

The shadow_vimp() function by default performs variable selection in multiple steps. Initially, it prunes the set of predictors using a relaxed (higher) alpha threshold in a pre-selection stage. Variables that pass this stage then undergo a final evaluation using the target (lower) alpha threshold and more iterations. This stepwise approach distinguishes informative from uninformative covariates based on their VIMPs and enhances computational efficiency. The user can also perform variable selection in a single step, without a pre-selection phase.

Value

Object of the class "shadow_vimp" with the following entries:

Examples

data(mtcars)

# When working with real data, use higher values for the niters and num.trees
# parameters --> here these parameters are set to small values to reduce the
# runtime.

# Function to make sure proper number of cores is specified
safe_num_threads <- function(n) {
  available <- parallel::detectCores()
  if (n > available) available else n
}

# Standard use
out1 <- shadow_vimp(
  data = mtcars, outcome_var = "vs",
  niters = c(10, 20, 30), num.trees = 30, num.threads = safe_num_threads(1)
)


# `num.threads` sets the number of threads for multithreading in
# `ranger::ranger`. By default, the `shadow_vimp` function uses half the
# available CPU threads.
out2 <- shadow_vimp(
  data = mtcars, outcome_var = "vs",
  niters = c(10, 20, 30), num.threads = safe_num_threads(2),
  num.trees = 30
)

# Save variable importance measures only from the final step of the
# procedure
out4 <- shadow_vimp(
  data = mtcars, outcome_var = "vs",
  niters = c(10, 20, 30), save_vimp_history = "last", num.trees = 30,
  num.threads = safe_num_threads(1)
)

# Print unadjusted and FDR-adjusted p-values together with the corresponding
# decisions
out5 <- shadow_vimp(
  data = mtcars, outcome_var = "vs",
  niters = c(10, 20, 30), to_show = "FDR", num.trees = 30,
  num.threads = safe_num_threads(1)
)

# Use per-variable p-values to decide in the final step whether a covariate
# is informative or not. Note that pooled p-values are always used in the
# pre-selection (first two steps).
out6 <- shadow_vimp(
  data = mtcars, outcome_var = "vs",
  niters = c(10, 20, 30), method = "per_variable", num.trees = 30,
  num.threads = safe_num_threads(1)
)

# Perform variable selection in a single step, without a pre-selection phase
out7 <- shadow_vimp(
  data = mtcars, outcome_var = "vs", alphas = c(0.05),
  niters = c(30), num.trees = 30,
  num.threads = safe_num_threads(1)
)


[Package shadowVIMP version 1.0.2 Index]