LightGBM Is Unbalance

When is_unbalance is set to true, LightGBM automatically adjusts the weights of the positive class (the minority class) to be inversely proportional to its frequency. It sets the weight of the positive class to count(negative) / count(positive), effectively simulating a manual scale_pos_weight setting. This ensures the algorithm penalizes misclassifying the rare class more heavily during the gradient boosting process.

This parameter is strictly designed for binary classification tasks. It cannot be applied to multi-class classification or regression problems. The algorithm assumes a standard binary label format where the minority class is labeled 1 (positive) and the majority class is labeled 0 (negative). Using it for other objective types will result in an error or undefined behavior.

is_unbalance and scale_pos_weight are mutually exclusive and should not be used simultaneously. If both are specified, scale_pos_weight takes precedence, overriding the automatic calculation. The is_unbalance flag is a convenience wrapper; if you need finer control over the exact weight ratio, you should manually set scale_pos_weight instead.

Setting is_unbalance=true only affects the training objective by weighting the gradients. It does not change the evaluation metrics or the raw output scores. The model will output uncalibrated raw scores, and you must still apply threshold moving or probability calibration post-training to achieve optimal decision boundaries for your specific business metric, such as maximizing F1-score.

Unlike data-level resampling techniques such as SMOTE or random under-sampling, is_unbalance does not alter the training dataset. It operates purely at the algorithmic level by modifying the loss function. This preserves the original data distribution and avoids the risk of overfitting on synthetic duplicates or discarding valuable majority class information.

By default, is_unbalance is set to false, meaning the algorithm treats both classes equally. It is best used as a quick baseline when you suspect class imbalance but haven't performed exploratory data analysis. For production fraud detection systems, manually tuning scale_pos_weight via cross-validation often yields better results, as it allows for precise optimization of the cost ratio.