Extract Predictor Variable Importance from a Fusion Model

Extracts feature importance metrics for the underlying LightGBM models stored within a microdata fusion model file (.fsn). Returns both per-model detailed metrics and pooled summary metrics averaged across all target sub-models.

Usage

importance(fsn)

Arguments

fsn: Character string. Path to a valid microdata fusion model file (.fsn) previously generated by train.

Value

A named list containing two data frames:

summary: A data.frame providing pooled, normalized importance metrics (gain, cover, frequency) averaged across sub-models for each target variable (y). Predictor names (x) are pre-formatted as ordered factors for straightforward plotting.
detailed: A data.frame providing raw, un-normalized importance metrics for every individual LightGBM sub-model (model) across all target variables (y).

Details

Microdata fusion models trained via train consist of an archive of LightGBM models corresponding to different target variables ($y$) and estimation types—such as mean ("m"), zero-indicator ("z"), or conditional quantiles ("q").

importance() uncompresses the .fsn archive into a temporary session directory, parses each LightGBM text model using lgb.load, and calculates feature importance via lgb.importance.

Three standard LightGBM importance metrics are computed:

gain: The relative contribution of a predictor variable to the model, measured by the total gain of splits using that feature. Gain is the primary and recommended metric for evaluating predictor importance.
cover: The relative number of observations (samples) impacted by splits containing the feature.
frequency: The relative number of times a feature is used across all split trees in the model.

In the $summary output, importance metrics are averaged across all underlying sub-models for a given target variable ($y$) and normalized so that feature contributions sum to 1.0 per target variable. Factor levels for predictor variables (x) in $summary are pre-ordered by overall mean gain to facilitate clear, ordered visualizations (e.g., via ggplot2).

Examples

if (FALSE) { # \dontrun{
library(fusionModel)
library(ggplot2)

# Build a fusion model using RECS sample microdata
# Note: train() writes "fusion_model.fsn" to the working directory
fusion.vars <- c("electricity", "natural_gas", "aircon")
predictor.vars <- names(recs)[2:12]
fsn.path <- train(data = recs, y = fusion.vars, x = predictor.vars)

# Extract predictor variable importance
ximp <- importance(fsn.path)

# Inspect overall summary results
head(ximp$summary)

# Plot relative gain across target variables
ggplot(ximp$summary, aes(x = x, y = gain, fill = y)) +
  geom_col(show.legend = FALSE) +
  facet_wrap(~ y, scales = "free_y") +
  coord_flip() +
  labs(
    x = "Predictor Variable",
    y = "Normalized Relative Gain",
    title = "Predictor Importance by Target Variable"
  ) +
  theme_bw()

# View raw, per-model detailed metrics
head(ximp$detailed)
} # }