LightGBM categorical features: verify the encoding assumptions

Categorical support works only when training and prediction agree on what each value means. A category's integer code is an implementation detail, not a stable identity unless your workflow preserves the mapping.

Our original LightGBM 4.7.0 example uses 150 synthetic rows with a numeric load index and three fictional plans: basic, team and enterprise. It tests encoding consistency, not held-out prediction quality or commercial plan behavior.

Distinguish labels from manually supplied codes

With pandas categorical columns, the tested LightGBM interface aligns prediction categories to the training category labels. Reordering the category list while keeping the same labels therefore preserves the predictions in this example.

If you extract integer codes yourself and pass an array, the labels are gone. Independently assigning codes in a new order can silently change which training category a value represents.

The LightGBM categorical-feature guide documents pandas alignment, integer encoding and treatment of unseen categories. The following probes verify the relevant behavior on the actual local version.

Reproduce the category-order checks

At load 0.5, the original model predicts approximately 11.238926 for basic, 30.869862 for team and 21.087089 for enterprise. These are outputs from an authored target rule plus noise, not measured business outcomes.

import numpy as np
from boosting_cases import categorical_case

r = categorical_case()
assert r['version']=='4.7.0'
assert r['training_rows']==150
assert r['reordered_pandas_categories_same_predictions']
assert r['unknown_and_missing_agree']
assert r['serialized_category_model_agrees']
assert np.isclose(r['probe_predictions_by_label']['basic'],11.238925668702343)
assert np.isclose(r['largest_code_drift_difference'],9.848163731768558)
assert not np.allclose(r['integer_code_predictions_stable'],r['integer_code_predictions_drifted'])
print(r)

Run with the extension environment described in the lab. The included CSV preserves label strings; loading reconstructs the declared unordered categorical dtype.

Inspect the failure caused by code drift

In the separate integer-array probe, reversing the code mapping swaps the basic and enterprise predictions. The largest change is about 9.848164 target units, even though the intended labels and load values are unchanged.

The model cannot infer that code zero has been reassigned a different business meaning. Preserve one versioned label-to-code mapping if you use integer arrays, and verify it at the serving boundary. Treating arbitrary codes as an ordinary numeric feature is another modelling choice and should not happen accidentally.

Test unknown and missing categories separately

In this fitted pandas-category model, an unseen new_plan and a missing plan produce the same prediction, about 21.087089. That confirms the tested unknown-as-missing behavior. It does not establish that the prediction is reliable for a new plan.

The numerical equality with the enterprise probe in this particular fit does not mean the unknown label was semantically recognized as enterprise. Missing-value routing is a model behavior, not a business category assignment.

Monitor unseen-category frequency and inspect outcomes when sufficient labels become available. A pipeline that keeps running can still be making weak predictions for a changed population.

Preserve categorical behavior through handover

The lab serializes the LightGBM booster to a model string and reloads it, then verifies the original pandas-category predictions. A production wrapper should additionally check column names, dtypes, category handling and model version under its own request format.

Exercise: add a spelling variant of an existing plan to a prediction fixture. Decide whether it is a data-quality alias or a genuinely new category, document the normalization policy and verify the resulting mapping. Do not silently collapse categories merely to eliminate missing values.

NeuraPath's Data Science course connects algorithm features with reproducible data contracts. A complete categorical example tests label meaning and unknown behavior, not only whether the model accepts the input array.

Continue learning

This article is part of the Supervised learning methods sequence. Use the neighbouring tasks when you need the prerequisite or the next application.

• Review the prerequisite or neighbouring task in XGBoost validation: early stopping without test-set leakage.
• Continue with K-nearest neighbours: why scaling changes the prediction.