Draw Variable Importance — draw_varimp • rtemis.draw

Draw signed importance summaries with BarConfig, or fold distributions with BoxplotConfig using type = "boxplot". Numeric input uses its names as variable labels, or row numbers when unnamed. Tables preserve named measures and optionally identify resamples with fold.

Usage

draw_varimp(
  x,
  measure = NULL,
  top_n = 20L,
  rank_by = "magnitude",
  summary = "mean",
  absent = "missing",
  folds = NULL,
  horizontal = TRUE,
  xlab = NULL,
  ylab = NULL,
  title = NULL,
  theme = NULL,
  width = NULL,
  height = NULL,
  element_id = NULL,
  filename = NULL,
  type = "bar",
  decreasing = TRUE,
  ...,
  legend_position = "top",
  legend_placement = "outside"
)

Arguments

x: Numeric vector, single-column matrix, or data frame: Importance scores. Tables require variable and named numeric measures, optionally fold. Variable names must be unique within each fold.
measure: Optional Character: Measure column. NULL selects the first column other than variable or fold; vectors use "importance".
top_n: Optional Integer [1, Inf): Maximum number of variables. NULL includes all variables with a summary; fractions are not accepted.
rank_by: Character {"magnitude", "signed"}: Rank by absolute or signed summary, respectively.
summary: Character {"mean", "median"}: Summary across folds.
absent: Character {"missing", "zero"}: Meaning of omitted variable rows within a fold reporting the selected measure.
folds: Optional Character: Full set of fold IDs, including folds with no rows. NULL uses the IDs observed in the fold column.
horizontal: Logical: Draw horizontal bars or boxes.
xlab, ylab: Optional Character: Physical axis labels. NULL derives the score label from the measure and summary and labels the variable axis.
title: Optional Character: Chart title.
theme: Optional Theme: Theme override. Set palette in ... to override its series colors.
width: Optional Character or Numeric: Widget width.
height: Optional Character or Numeric: Widget height. NULL allocates space per selected variable for horizontal bars.
element_id: Optional Character: Explicit DOM element ID for the widget container. NULL lets htmlwidgets generate one.
filename: Optional Character: If provided, save the widget to this file via save_drawing().
type: Character {"bar", "boxplot"}: Summary or fold-distribution view.
decreasing: Logical: Select and display ranks from largest to smallest. FALSE selects and displays the smallest ranks first.
...: Additional settings for setup_BarConfig() or setup_BoxplotConfig(), according to type. Boxplots accept boxpoints, quartiles, whisker, and point styling; unset boxpoints shows all scores. Data bindings, labels, and orientation are set here.
legend_position: Character {"top", "bottom", "left", "right", "top-left", "top-right", "bottom-left", "bottom-right"}: Legend anchor. Top/bottom anchors use horizontal rows; left/right anchors use a vertical column. Corner anchors align within the top or bottom row.
legend_placement: Character {"outside", "inside"}: Relation to the plotting area. Outside placement reserves space for the complete legend; inside placement overlays the data. Neither setting adds a missing legend.

Value

htmlwidget: ECharts importance bars or fold distributions.

Details

Resampled scores are summarized before selection. Magnitude ranking uses the absolute summary, not the mean absolute fold score. Signed ranking uses the summary itself. decreasing = FALSE selects the smallest ranks first. Ties retain first appearance in the input. The first selected variable appears at the top of horizontal bars or the left of vertical bars or boxes. Zero scores are retained. For distributions, the summary controls selection and ordering only; boxes use the fold values. Ranking direction is never inferred from a measure name. For smaller-is-better scores, use rank_by = "signed", decreasing = FALSE. Averaging fold p-values does not produce a combined p-value; choose a suitable summary outside this function when the score's interpretation requires it.

Set bar_width to a pixel thickness for separate zero-to-score segments. This uses native bars and covers the legacy importance type = "line" geometry without connecting different variables or adding a new chart type.

Explicit NA scores and wholly unavailable folds are excluded from each variable's summary. Variables with no available score are omitted. absent = "zero" declares that omitted variable rows mean known zero scores within folds reporting that measure. It never replaces an explicit NA or a wholly unavailable fold/measure with zero. Use it only for sparse importance tables whose producer omits zero entries. Infinite scores are rejected.

Means and medians give each contributing fold equal weight. An incomplete summary describes the available folds, not an estimate guaranteed to be unbiased for all folds. Incomplete fold coverage is reported in the console; chart labels retain only the variable and measure names. The input is never modified.

Boxplots require fold-level records. Every available score (including known structural zeros) is overlaid by default, with its fold ID in the tooltip. Missing values remain missing in the materialized table and are reported in the console. Boxes describe resample variability, not a confidence interval. See draw_boxplot() for quartiles, whiskers, and point placement. Use whisker = 0 for full-range whiskers, as in the current live importance view.

For portable rendering, materialize the selected, summarized label and importance columns in display order and bind them using setup_BarConfig(x = "label", y = "importance"). Preserve variable IDs and contributing/total fold counts alongside these columns. Set horizontal, axis labels, and title explicitly. That table and config reproduce the view without a fitted model or R callbacks. The raw-data summary and selection options are not yet part of a shared visualization schema. For distributions, use one numeric column per selected variable and an observation column for the complete fold universe. Bind those columns and the variable labels through setup_BoxplotConfig(). Only selected variables are widened; selection does not discard folds needed to identify structural zeros.

Examples

draw_varimp(c(age = 0.8, weight = -0.4, height = 0.2))

scores <- data.frame(
  variable = c("age", "weight", "age"),
  fold = c("A", "A", "B"),
  gain = c(0.8, 0.4, 0.6)
)
draw_varimp(scores, measure = "gain", absent = "zero")

draw_varimp(scores, measure = "gain", type = "boxplot", absent = "zero")