Select chain responses by mean normalized importance

Select chain-feature responses whose mean supplied importance reaches a package-defined floor. Use this table-only gate when normalized importance scores have already been assembled and a fixed percentage threshold is the desired policy.

Usage

activeByImportance(importanceDT, suffix = ".o", thresh = 0)

Arguments

importanceDT

A data.table with one row per importance observation and required columns feature and normImportance. feature must contain non-missing character names ending in suffix; normImportance must be numeric and is interpreted in normalized-importance percentage points. Extra columns are ignored. Values are not normalized or range-checked.

suffix

A single non-missing, non-empty character suffix to remove from every feature, default ".o". Removal is positional: the function does not verify that names end in this suffix.

thresh

A single numeric threshold in normalized-importance percentage points, default 0. The comparison is inclusive. The function does not validate its length, whether it is finite, or its range; NA selects no response.

Value

A character vector of unique stripped response names in first-appearance order. It is empty when no group reaches thresh.

Gate definition

For each response name obtained by removing the final nchar(suffix) characters from feature, the function computes the arithmetic mean of all non-missing normImportance values. Every input row contributes separately, including duplicate rows. A response is returned when its mean is greater than or equal to thresh; an exact threshold tie therefore passes. A group with only missing scores has a NaN mean and is excluded.

The threshold and averaging rule are ssel policy. Averaging is mechanical: the function neither establishes nor checks that scores from different learners or other sources are comparable. Output order follows the first appearance of each stripped response name, and grouping removes duplicate names from the result.

Validation and side effects

NULL and a zero-row table return character(0). A non-empty input must be a data.table; missing required columns or incompatible types produce underlying base R or data.table errors or warnings rather than a deliberate validation message. The input is copied before the temporary response column is added, so it is not modified by reference. The function reads and writes no files, uses no random numbers, and emits no message or warning for valid inputs.

See also

activeByShadow() for the strict-majority shadow alternative. extractChainImportance() is the package table producer, and computeActiveByImportance() composes extraction with this gate; their model-file and stability contracts are separate from this table operation.

Examples

importance <- data.table::data.table(
  feature = c("beta.o", "alpha.o", "beta.o", "alpha.o", "gamma.o"),
  normImportance = c(1, 2, 3, NA, NA)
)

# beta ties the 2% floor; alpha ignores one NA; gamma has no usable score.
activeByImportance(importance, suffix = ".o", thresh = 2)
#> [1] "beta"  "alpha"