Extract normalized importance for response companions

Read fitted model files, ask caret::varImp() for each model's importance table, normalize scores within that table, and retain features ending in a configured companion suffix. This helper produces the table consumed by the fixed and shadow chain gates; it does not itself select active responses.

Usage

extractChainImportance(pathModel, suffix = ".o", useModel = TRUE)

Arguments

pathModel

Directory scanned non-recursively for case-sensitive filenames ending in .Rds.

suffix

Character suffix matched with endsWith() against every importance feature name. Length, missingness, emptiness, and collisions are not proactively validated.

useModel

Value passed unchanged to caret::varImp(model, useModel = useModel). TRUE requests caret's model-specific path and is used by the fixed gate. FALSE requests caret's model-independent regression path and is used by the shadow gate. The helper does not validate a logical scalar.

Value

A data.table with one row per retained model–companion pair and columns feature, response, dataset, method, normImportance, and shadowImportance. Importance columns are in normalized percentage points. If no row is retained, returns an empty zero-column data.table.

File parser and skips

A model basename is split on underscores after removing its extension. The first field becomes method, the last becomes dataset, and all interior fields joined by underscores become response. Method and dataset identifiers therefore cannot be reconstructed when they contain underscores; a response may contain them. A valid basename must have at least three fields: method, one or more response fields, and dataset. This precondition is not validated. With two fields, for example lm_demo.Rds, the index sequence reverses and the response becomes demo_lm; with one field, lm.Rds, it becomes NA_lm while both method and dataset are lm. Such malformed stems can therefore contribute spurious response labels rather than being rejected. Files are processed in list.files() order.

An unreadable model, a caught caret::varImp() error, an empty importance table, or a table with no suffix-matching feature contributes no row. The returned caret table is expected to become columns rn and Overall; incompatible schemas fail at column renaming rather than being skipped. Apart from the unvalidated short-stem behavior above, other type, filesystem, and data.table errors propagate.

Normalization and shadow field

For model file \(c\), let \(I_{fc}\) be caret's Overall score for feature \(f\), and let $$T_c=\sum_f I_{fc},$$ removing missing scores. When \(T_c>0\), ssel writes $$J_{fc}=100 I_{fc}/T_c$$ rounded to four decimals; otherwise it writes zero for every row. The sum is over all importance rows before companion filtering, so retained companion percentages need not sum to 100. Negative, infinite, duplicated, or otherwise unusual caret scores are not range-checked.

The exact feature name shadow, when it occurs once, supplies that model's normalized shadowImportance on the same row-local scale. Zero or multiple exact matches yield a missing shadow score. Only features whose names end in suffix are returned. Their names are not stripped here.

Model-specific importance definitions can differ across learners. This normalization is a package aggregation convention and does not establish cross-learner comparability. Likewise, the model-independent/shadow path is one package null-reference input; it is not the Boruta algorithm.

Side effects and return

The helper reads model files and calls their caret importance methods. It writes no file, sets no seed, draws no random value directly, and emits no deliberate progress condition. Caught model/importance failures are silent.

See also

activeByImportance() for the fixed table gate, activeByShadow() for the strict shadow-majority table gate, and computeActiveByImportance() for fixed-gate composition.

Examples

root <- tempfile("ssel-chain-importance-")
dir.create(root)
train <- data.frame(
  alpha.o = 1:12,
  beta.o = rep(c(0, 1), 6),
  x = rep(1:4, 3),
  y = c(2.1, 1.7, 3.5, 2.8, 5.2, 4.1,
        6.4, 5.3, 7.1, 6.8, 8.2, 7.5)
)
fit <- caret::train(
  y ~ ., data = train, method = "lm",
  trControl = caret::trainControl(method = "none")
)
saveRDS(fit, file.path(root, "lm_target_demo.Rds"))

importance <- extractChainImportance(root, suffix = ".o")
importance[, .(feature, response, dataset, normImportance)]
#>    feature response dataset normImportance
#>     <char>   <char>  <char>          <num>
#> 1: alpha.o   target    demo        78.8293
#> 2:  beta.o   target    demo        21.1707
# Percentages use all model features in their denominator.

unlink(root, recursive = TRUE)