# Callback Functions

This document gives a basic walkthrough of [callback API](python_api.html.md#callback-api) used in
XGBoost Python package.  In XGBoost 1.3, a new callback interface is designed for Python
package, which provides the flexibility of designing various extension for training.
Also, XGBoost has a number of pre-defined callbacks for supporting early stopping,
checkpoints etc.

## Using builtin callbacks

By default, training methods in XGBoost have parameters like `early_stopping_rounds` and
`verbose`/`verbose_eval`, when specified the training procedure will define the
corresponding callbacks internally.  For example, when `early_stopping_rounds` is
specified, [`EarlyStopping`](python_api.html.md#xgboost.callback.EarlyStopping) callback is invoked
inside iteration loop.  You can also pass this callback function directly into XGBoost:

```python
D_train = xgb.DMatrix(X_train, y_train)
D_valid = xgb.DMatrix(X_valid, y_valid)

# Define a custom evaluation metric used for early stopping.
def eval_error_metric(predt, dtrain: xgb.DMatrix):
    label = dtrain.get_label()
    r = np.zeros(predt.shape)
    gt = predt > 0.5
    r[gt] = 1 - label[gt]
    le = predt <= 0.5
    r[le] = label[le]
    return 'CustomErr', np.sum(r)

# Specify which dataset and which metric should be used for early stopping.
early_stop = xgb.callback.EarlyStopping(rounds=early_stopping_rounds,
                                        metric_name='CustomErr',
                                        data_name='Valid')

booster = xgb.train(
    {'objective': 'binary:logistic',
     'eval_metric': ['error', 'rmse'],
     'tree_method': 'hist'}, D_train,
    evals=[(D_train, 'Train'), (D_valid, 'Valid')],
    feval=eval_error_metric,
    num_boost_round=1000,
    callbacks=[early_stop],
    verbose_eval=False)

dump = booster.get_dump(dump_format='json')
assert len(early_stop.stopping_history['Valid']['CustomErr']) == len(dump)
```

## Defining your own callback

XGBoost provides an callback interface class: [`TrainingCallback`](python_api.html.md#xgboost.callback.TrainingCallback), user defined callbacks should inherit this class and
override corresponding methods.  There’s a working example in
[Demo for using and defining callback functions](examples/callbacks.html.md#sphx-glr-python-examples-callbacks-py).