quantlab.model.predefined.xgb.record_feature_importance

quantlab.model.predefined.xgb.record_feature_importance(booster, factor_names, run, owner, booster_type='gbtree', suffix='')

Write a Booster’s per-factor importance to a tracking run.

Booster.get_score keys features as f{i} by column index when the Booster was trained on an array, and as the column name, which is x_cont_{i} for a pytabkit head, when it was trained on a frame; the columns follow factor_names, so either maps to the i-th factor. Factors that were never split on get 0.0. For every type in _IMPORTANCE_TYPES the scalars go to the summary as importance_{type}{suffix}/{factor}, and a table feature_importance{suffix}/{type} lists every factor sorted by importance, with a bar chart of the top _IMPORTANCE_CHART_TOP_N where the tracker draws one.

This is reporting only, so a failure here must never lose a checkpoint. booster_type="gblinear" has no split importance and is skipped with an info message. A type that raises XGBoostError or returns non-scalar scores is skipped with a warning, and a failure while logging a table is also only a warning.

Parameters:

boosterxgb.Booster

The fitted Booster.

factor_nameslist[str]

The feature columns the Booster was trained on, in order.

runTrackingRun

The run whose summary and tables receive the importance.

ownerstr

Class name quoted in messages.

booster_typestr, default “gbtree”

The booster parameter the Booster was trained with.

suffixstr, default “”

Appended to the summary keys and table names, e.g. "/ret_5".

Raises:

ValueError

If a score key is not f<index> for one of the factors, which means the Booster was not trained on these columns.

Examples

With booster trained on two factor columns, the run’s summary gets importance_gain/mom_5 and importance_gain/mom_20 (and the same for weight and total_gain), and three tables feature_importance/{weight,gain,total_gain}:

>>> tracker = WandbTracker(project="importance", mode="offline")
>>> with tracker.start_run(project="P", group=None, name="n", config={}) as run:
...     record_feature_importance(booster, ["mom_5", "mom_20"], run, "Head")