Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 40 ยท Imbalanced Data and Custom Losses

Custom Objective Functions

Write your own loss for XGBoost and LightGBM by returning the gradient and hessian: verify squared error, build an asymmetric loss and a focal loss, and avoid the common traps.

Built-in objectives cover most needs, but sometimes the business loss is not the textbook one: underestimating demand costs more than overestimating it, rare positives need extra focus, or you want a smooth approximation of a metric. Both libraries let you pass your own loss by supplying two functions' worth of numbers per row: the gradient (first derivative) and the hessian (second derivative) of the loss with respect to the raw prediction. If the reason these two numbers are enough is new to you, read Loss Gradients and Hessians first.

The contract

In the scikit-learn interface, a custom objective is a function:

Python
def my_objective(y_true, y_pred):
    grad = ...   # d loss / d y_pred, one number per row
    hess = ...   # d2 loss / d y_pred2, one number per row
    return grad, hess

You pass it as objective=my_objective to XGBRegressor, XGBClassifier, LGBMRegressor or LGBMClassifier. Three details matter:

  • y_pred is the raw score, not a probability. For a classification loss you apply the sigmoid yourself, and predict_proba will not convert back correctly for a custom objective (you apply the sigmoid to predict(..., output_margin=True) or the raw output).
  • The hessian must be positive (or at least non-negative with a small floor). A zero or negative hessian makes the leaf value -G/(H+lambda) explode or flip sign.
  • The base score: with a custom objective the booster starts from a fixed initial value (0.5 in XGBoost unless you set base_score, 0 for LightGBM unless boost_from_average applies). Set base_score to something sensible, such as the mean of the target, for regression.

Step 1: reproduce squared error

Always start by reproducing a built-in loss and compare. Loss 0.5 * (pred - y)^2 has gradient pred - y and hessian 1:

Python A custom squared error equals the built-in one

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The XGBoost predictions match to numerical precision, which tells you the gradient, the hessian and the base_score are right. This sanity test catches sign errors immediately. (LightGBM's built-in objective starts from the mean of the target; a custom objective starts from zero unless told otherwise, so the two can differ slightly in the first trees; the correlation shows they end up almost identical.)

Step 2: an asymmetric loss

Suppose predicting too low (running out of stock) costs three times as much as predicting too high. Use a weighted squared error where the weight depends on the sign of the residual:

loss = w * 0.5 * (pred - y)^2, with w = 3 when pred < y and w = 1 otherwise. Then grad = w * (pred - y) and hess = w.

Python Asymmetric loss shifts predictions upward

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The asymmetric model under-predicts clearly less often (about 37% of rows instead of 50% in one run), because under-predicting hurts more, and its mean residual is strongly positive (about +16 against +0.6). This is the intended behavior: you trade some average accuracy for fewer costly misses. Scikit-learn's quantile or XGBoost's reg:quantileerror objective offer related tools (see Objectives for Counts, Quantiles and Ranking).

Step 3: focal loss for hard examples

Focal loss down-weights easy examples so training concentrates on the hard ones, which can help with severe imbalance. For a binary label y and probability p = sigmoid(z), with focusing parameter gamma, the loss is -(1-p_t)^gamma * log(p_t), where p_t is p for positives and 1-p for negatives. Deriving the exact hessian is tedious; a common trick is to compute the gradient analytically or numerically and approximate the hessian with a safe positive value. Here we use central finite differences, which is easy and good enough for experiments:

Python Focal loss with numerically derived gradient and hessian

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that for the focal models we evaluate the raw margin z, which is fine for ranking metrics, because they only need an order. To get a probability you would apply sigmoid(z), and keep in mind that focal loss does not produce calibrated probabilities. The results usually land close to the plain log loss model; focal loss helps most when the data is extremely imbalanced and the model is flexible. Measure on validation data before adopting it.

Checklist for custom objectives

  • Reproduce a built-in loss first, and compare predictions.
  • Return positive hessians; clip them with a floor if they can reach zero.
  • Remember that y_pred is raw margin, and that metrics and predict_proba may need the transformation applied by you.
  • Pair a custom objective with a matching evaluation metric (next lesson), otherwise early stopping will watch the wrong number.
  • Check gradients numerically with finite differences when unsure, as in the focal loss above.
  • Custom Python objectives are slower than built-in ones because they run in Python once per round.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What must a custom objective return?

    Boosting uses the first and second derivative to build each tree; the loss value itself is not needed for training.
  2. 2. In a custom binary classification objective, what is y_pred?

    Custom objectives receive the raw margin, so you apply the sigmoid inside the function if the loss needs probabilities.
  3. 3. Why should the hessian stay positive?

    A near-zero or negative hessian sum makes the leaf weight huge or reverses its sign, destabilizing training.
  4. 4. What is a good first test for a new custom objective?

    Matching a known objective proves that gradient, hessian and base score are correct.

Summary

  • A custom objective is a function returning the gradient and hessian with respect to the raw prediction.
  • Validate it by reproducing squared error; keep hessians positive; set a sensible base score.
  • Asymmetric squared error encodes unequal costs; focal loss focuses on hard examples.
  • Raw outputs need a sigmoid for probabilities, and custom losses are not calibrated.
  • Pair a custom objective with a matching evaluation metric.

Next: Custom Evaluation Metrics