View on TensorFlow.org | View source on GitHub | Download notebook |

A custom callback is a powerful tool to customize the behavior of a Keras model during training, evaluation, or inference, including reading/changing the Keras model. Examples include `tf.keras.callbacks.TensorBoard`

where the training progress and results can be exported and visualized with TensorBoard, or `tf.keras.callbacks.ModelCheckpoint`

where the model is automatically saved during training, and more. In this guide, you will learn what Keras callback is, when it will be called, what it can do, and how you can build your own. Towards the end of this guide, there will be demos of creating a couple of simple callback applications to get you started on your custom callback.

## Setup

```
import tensorflow as tf
```

## Introduction to Keras callbacks

In Keras, `Callback`

is a python class meant to be subclassed to provide specific functionality, with a set of methods called at various stages of training (including batch/epoch start and ends), testing, and predicting. Callbacks are useful to get a view on internal states and statistics of the model during training. You can pass a list of callbacks (as the keyword argument `callbacks`

) to any of `tf.keras.Model.fit()`

, `tf.keras.Model.evaluate()`

, and `tf.keras.Model.predict()`

methods. The methods of the callbacks will then be called at different stages of training/evaluating/inference.

To get started, let's import tensorflow and define a simple Sequential Keras model:

```
# Define the Keras model to add callbacks to
def get_model():
model = tf.keras.Sequential()
model.add(tf.keras.layers.Dense(1, activation = 'linear', input_dim = 784))
model.compile(optimizer=tf.keras.optimizers.RMSprop(lr=0.1), loss='mean_squared_error', metrics=['mae'])
return model
```

Then, load the MNIST data for training and testing from Keras datasets API:

```
# Load example MNIST data and pre-process it
(x_train, y_train), (x_test, y_test) = tf.keras.datasets.mnist.load_data()
x_train = x_train.reshape(60000, 784).astype('float32') / 255
x_test = x_test.reshape(10000, 784).astype('float32') / 255
```

Now, define a simple custom callback to track the start and end of every batch of data. During those calls, it prints the index of the current batch.

```
import datetime
class MyCustomCallback(tf.keras.callbacks.Callback):
def on_train_batch_begin(self, batch, logs=None):
print('Training: batch {} begins at {}'.format(batch, datetime.datetime.now().time()))
def on_train_batch_end(self, batch, logs=None):
print('Training: batch {} ends at {}'.format(batch, datetime.datetime.now().time()))
def on_test_batch_begin(self, batch, logs=None):
print('Evaluating: batch {} begins at {}'.format(batch, datetime.datetime.now().time()))
def on_test_batch_end(self, batch, logs=None):
print('Evaluating: batch {} ends at {}'.format(batch, datetime.datetime.now().time()))
```

Providing a callback to model methods such as `tf.keras.Model.fit()`

ensures the methods are called at those stages:

```
model = get_model()
_ = model.fit(x_train, y_train,
batch_size=64,
epochs=1,
steps_per_epoch=5,
verbose=0,
callbacks=[MyCustomCallback()])
```

Training: batch 0 begins at 01:37:45.356264 Training: batch 0 ends at 01:37:45.821658 Training: batch 1 begins at 01:37:45.822027 Training: batch 1 ends at 01:37:45.824782 Training: batch 2 begins at 01:37:45.825011 Training: batch 2 ends at 01:37:45.826925 Training: batch 3 begins at 01:37:45.827144 Training: batch 3 ends at 01:37:45.829214 Training: batch 4 begins at 01:37:45.829564 Training: batch 4 ends at 01:37:45.831550

## Model methods that take callbacks

Users can supply a list of callbacks to the following `tf.keras.Model`

methods:

`fit()`

, `fit_generator()`

Trains the model for a fixed number of epochs (iterations over a dataset, or data yielded batch-by-batch by a Python generator).

`evaluate()`

, `evaluate_generator()`

Evaluates the model for given data or data generator. Outputs the loss and metric values from the evaluation.

`predict()`

, `predict_generator()`

Generates output predictions for the input data or data generator.

```
_ = model.evaluate(x_test, y_test, batch_size=128, verbose=0, steps=5,
callbacks=[MyCustomCallback()])
```

Evaluating: batch 0 begins at 01:37:45.878931 Evaluating: batch 0 ends at 01:37:45.931670 Evaluating: batch 1 begins at 01:37:45.931905 Evaluating: batch 1 ends at 01:37:45.933861 Evaluating: batch 2 begins at 01:37:45.934089 Evaluating: batch 2 ends at 01:37:45.935782 Evaluating: batch 3 begins at 01:37:45.936168 Evaluating: batch 3 ends at 01:37:45.937883 Evaluating: batch 4 begins at 01:37:45.938105 Evaluating: batch 4 ends at 01:37:45.939711

## An overview of callback methods

### Common methods for training/testing/predicting

For training, testing, and predicting, following methods are provided to be overridden.

`on_(train|test|predict)_begin(self, logs=None)`

Called at the beginning of `fit`

/`evaluate`

/`predict`

.

`on_(train|test|predict)_end(self, logs=None)`

Called at the end of `fit`

/`evaluate`

/`predict`

.

`on_(train|test|predict)_batch_begin(self, batch, logs=None)`

Called right before processing a batch during training/testing/predicting. Within this method, `logs`

is a dict with `batch`

and `size`

available keys, representing the current batch number and the size of the batch.

`on_(train|test|predict)_batch_end(self, batch, logs=None)`

Called at the end of training/testing/predicting a batch. Within this method, `logs`

is a dict containing the stateful metrics result.

### Training specific methods

In addition, for training, following are provided.

#### on_epoch_begin(self, epoch, logs=None)

Called at the beginning of an epoch during training.

#### on_epoch_end(self, epoch, logs=None)

Called at the end of an epoch during training.

### Usage of `logs`

dict

The `logs`

dict contains the loss value, and all the metrics at the end of a batch or epoch. Example includes the loss and mean absolute error.

```
class LossAndErrorPrintingCallback(tf.keras.callbacks.Callback):
def on_train_batch_end(self, batch, logs=None):
print('For batch {}, loss is {:7.2f}.'.format(batch, logs['loss']))
def on_test_batch_end(self, batch, logs=None):
print('For batch {}, loss is {:7.2f}.'.format(batch, logs['loss']))
def on_epoch_end(self, epoch, logs=None):
print('The average loss for epoch {} is {:7.2f} and mean absolute error is {:7.2f}.'.format(epoch, logs['loss'], logs['mae']))
model = get_model()
_ = model.fit(x_train, y_train,
batch_size=64,
steps_per_epoch=5,
epochs=3,
verbose=0,
callbacks=[LossAndErrorPrintingCallback()])
```

For batch 0, loss is 26.65. For batch 1, loss is 895.79. For batch 2, loss is 26.44. For batch 3, loss is 7.75. For batch 4, loss is 6.98. The average loss for epoch 0 is 192.72 and mean absolute error is 8.24. For batch 0, loss is 5.57. For batch 1, loss is 6.67. For batch 2, loss is 7.70. For batch 3, loss is 5.94. For batch 4, loss is 5.89. The average loss for epoch 1 is 6.35 and mean absolute error is 2.06. For batch 0, loss is 4.40. For batch 1, loss is 6.46. For batch 2, loss is 6.54. For batch 3, loss is 6.76. For batch 4, loss is 8.36. The average loss for epoch 2 is 6.50 and mean absolute error is 2.01.

Similarly, one can provide callbacks in `evaluate()`

calls.

```
_ = model.evaluate(x_test, y_test, batch_size=128, verbose=0, steps=20,
callbacks=[LossAndErrorPrintingCallback()])
```

For batch 0, loss is 9.84. For batch 1, loss is 9.96. For batch 2, loss is 9.27. For batch 3, loss is 9.70. For batch 4, loss is 9.73. For batch 5, loss is 10.25. For batch 6, loss is 9.80. For batch 7, loss is 9.62. For batch 8, loss is 9.88. For batch 9, loss is 10.67. For batch 10, loss is 9.47. For batch 11, loss is 10.47. For batch 12, loss is 10.23. For batch 13, loss is 10.35. For batch 14, loss is 8.64. For batch 15, loss is 8.15. For batch 16, loss is 10.54. For batch 17, loss is 8.85. For batch 18, loss is 11.10. For batch 19, loss is 10.46.

## Examples of Keras callback applications

The following section will guide you through creating simple Callback applications.

### Early stopping at minimum loss

First example showcases the creation of a `Callback`

that stops the Keras training when the minimum of loss has been reached by mutating the attribute `model.stop_training`

(boolean). Optionally, the user can provide an argument `patience`

to specify how many epochs the training should wait before it eventually stops.

`tf.keras.callbacks.EarlyStopping`

provides a more complete and general implementation.

```
import numpy as np
class EarlyStoppingAtMinLoss(tf.keras.callbacks.Callback):
"""Stop training when the loss is at its min, i.e. the loss stops decreasing.
Arguments:
patience: Number of epochs to wait after min has been hit. After this
number of no improvement, training stops.
"""
def __init__(self, patience=0):
super(EarlyStoppingAtMinLoss, self).__init__()
self.patience = patience
# best_weights to store the weights at which the minimum loss occurs.
self.best_weights = None
def on_train_begin(self, logs=None):
# The number of epoch it has waited when loss is no longer minimum.
self.wait = 0
# The epoch the training stops at.
self.stopped_epoch = 0
# Initialize the best as infinity.
self.best = np.Inf
def on_epoch_end(self, epoch, logs=None):
current = logs.get('loss')
if np.less(current, self.best):
self.best = current
self.wait = 0
# Record the best weights if current results is better (less).
self.best_weights = self.model.get_weights()
else:
self.wait += 1
if self.wait >= self.patience:
self.stopped_epoch = epoch
self.model.stop_training = True
print('Restoring model weights from the end of the best epoch.')
self.model.set_weights(self.best_weights)
def on_train_end(self, logs=None):
if self.stopped_epoch > 0:
print('Epoch %05d: early stopping' % (self.stopped_epoch + 1))
```

```
model = get_model()
_ = model.fit(x_train, y_train,
batch_size=64,
steps_per_epoch=5,
epochs=30,
verbose=0,
callbacks=[LossAndErrorPrintingCallback(), EarlyStoppingAtMinLoss()])
```

For batch 0, loss is 25.88. For batch 1, loss is 834.15. For batch 2, loss is 23.48. For batch 3, loss is 7.37. For batch 4, loss is 10.24. The average loss for epoch 0 is 180.23 and mean absolute error is 7.90. For batch 0, loss is 10.02. For batch 1, loss is 7.08. For batch 2, loss is 5.11. For batch 3, loss is 5.45. For batch 4, loss is 6.41. The average loss for epoch 1 is 6.81 and mean absolute error is 2.08. For batch 0, loss is 5.06. For batch 1, loss is 3.65. For batch 2, loss is 5.04. For batch 3, loss is 5.12. For batch 4, loss is 4.20. The average loss for epoch 2 is 4.61 and mean absolute error is 1.72. For batch 0, loss is 3.97. For batch 1, loss is 6.82. For batch 2, loss is 11.10. For batch 3, loss is 12.56. For batch 4, loss is 26.40. The average loss for epoch 3 is 12.17 and mean absolute error is 2.80. Restoring model weights from the end of the best epoch. Epoch 00004: early stopping

### Learning rate scheduling

One thing that is commonly done in model training is changing the learning rate as more epochs have passed. Keras backend exposes `get_value`

API which can be used to set the variables. In this example, we're showing how a custom Callback can be used to dynamically change the learning rate.

```
class LearningRateScheduler(tf.keras.callbacks.Callback):
"""Learning rate scheduler which sets the learning rate according to schedule.
Arguments:
schedule: a function that takes an epoch index
(integer, indexed from 0) and current learning rate
as inputs and returns a new learning rate as output (float).
"""
def __init__(self, schedule):
super(LearningRateScheduler, self).__init__()
self.schedule = schedule
def on_epoch_begin(self, epoch, logs=None):
if not hasattr(self.model.optimizer, 'lr'):
raise ValueError('Optimizer must have a "lr" attribute.')
# Get the current learning rate from model's optimizer.
lr = float(tf.keras.backend.get_value(self.model.optimizer.lr))
# Call schedule function to get the scheduled learning rate.
scheduled_lr = self.schedule(epoch, lr)
# Set the value back to the optimizer before this epoch starts
tf.keras.backend.set_value(self.model.optimizer.lr, scheduled_lr)
print('\nEpoch %05d: Learning rate is %6.4f.' % (epoch, scheduled_lr))
```

```
LR_SCHEDULE = [
# (epoch to start, learning rate) tuples
(3, 0.05), (6, 0.01), (9, 0.005), (12, 0.001)
]
def lr_schedule(epoch, lr):
"""Helper function to retrieve the scheduled learning rate based on epoch."""
if epoch < LR_SCHEDULE[0][0] or epoch > LR_SCHEDULE[-1][0]:
return lr
for i in range(len(LR_SCHEDULE)):
if epoch == LR_SCHEDULE[i][0]:
return LR_SCHEDULE[i][1]
return lr
model = get_model()
_ = model.fit(x_train, y_train,
batch_size=64,
steps_per_epoch=5,
epochs=15,
verbose=0,
callbacks=[LossAndErrorPrintingCallback(), LearningRateScheduler(lr_schedule)])
```

Epoch 00000: Learning rate is 0.1000. For batch 0, loss is 29.40. For batch 1, loss is 1032.78. For batch 2, loss is 25.73. For batch 3, loss is 7.73. For batch 4, loss is 10.87. The average loss for epoch 0 is 221.30 and mean absolute error is 8.69. Epoch 00001: Learning rate is 0.1000. For batch 0, loss is 6.33. For batch 1, loss is 4.81. For batch 2, loss is 4.71. For batch 3, loss is 4.50. For batch 4, loss is 5.86. The average loss for epoch 1 is 5.24 and mean absolute error is 1.87. Epoch 00002: Learning rate is 0.1000. For batch 0, loss is 6.05. For batch 1, loss is 5.39. For batch 2, loss is 5.43. For batch 3, loss is 5.99. For batch 4, loss is 4.60. The average loss for epoch 2 is 5.49 and mean absolute error is 1.89. Epoch 00003: Learning rate is 0.0500. For batch 0, loss is 4.76. For batch 1, loss is 3.17. For batch 2, loss is 3.63. For batch 3, loss is 4.32. For batch 4, loss is 4.55. The average loss for epoch 3 is 4.09 and mean absolute error is 1.60. Epoch 00004: Learning rate is 0.0500. For batch 0, loss is 3.63. For batch 1, loss is 4.11. For batch 2, loss is 5.39. For batch 3, loss is 4.91. For batch 4, loss is 4.88. The average loss for epoch 4 is 4.58 and mean absolute error is 1.68. Epoch 00005: Learning rate is 0.0500. For batch 0, loss is 4.56. For batch 1, loss is 4.09. For batch 2, loss is 5.52. For batch 3, loss is 4.63. For batch 4, loss is 6.21. The average loss for epoch 5 is 5.00 and mean absolute error is 1.79. Epoch 00006: Learning rate is 0.0100. For batch 0, loss is 8.37. For batch 1, loss is 5.97. For batch 2, loss is 5.33. For batch 3, loss is 2.67. For batch 4, loss is 4.93. The average loss for epoch 6 is 5.45 and mean absolute error is 1.80. Epoch 00007: Learning rate is 0.0100. For batch 0, loss is 5.11. For batch 1, loss is 5.44. For batch 2, loss is 4.12. For batch 3, loss is 3.95. For batch 4, loss is 2.87. The average loss for epoch 7 is 4.30 and mean absolute error is 1.64. Epoch 00008: Learning rate is 0.0100. For batch 0, loss is 3.63. For batch 1, loss is 6.23. For batch 2, loss is 3.70. For batch 3, loss is 4.06. For batch 4, loss is 5.30. The average loss for epoch 8 is 4.58 and mean absolute error is 1.72. Epoch 00009: Learning rate is 0.0050. For batch 0, loss is 4.92. For batch 1, loss is 3.18. For batch 2, loss is 4.61. For batch 3, loss is 3.57. For batch 4, loss is 4.93. The average loss for epoch 9 is 4.24 and mean absolute error is 1.63. Epoch 00010: Learning rate is 0.0050. For batch 0, loss is 3.02. For batch 1, loss is 4.17. For batch 2, loss is 4.66. For batch 3, loss is 4.32. For batch 4, loss is 4.10. The average loss for epoch 10 is 4.05 and mean absolute error is 1.59. Epoch 00011: Learning rate is 0.0050. For batch 0, loss is 4.02. For batch 1, loss is 5.40. For batch 2, loss is 3.54. For batch 3, loss is 2.65. For batch 4, loss is 3.77. The average loss for epoch 11 is 3.88 and mean absolute error is 1.55. Epoch 00012: Learning rate is 0.0010. For batch 0, loss is 3.37. For batch 1, loss is 2.69. For batch 2, loss is 4.97. For batch 3, loss is 5.25. For batch 4, loss is 2.60. The average loss for epoch 12 is 3.78 and mean absolute error is 1.51. Epoch 00013: Learning rate is 0.0010. For batch 0, loss is 4.20. For batch 1, loss is 3.82. For batch 2, loss is 3.56. For batch 3, loss is 3.71. For batch 4, loss is 2.60. The average loss for epoch 13 is 3.58 and mean absolute error is 1.50. Epoch 00014: Learning rate is 0.0010. For batch 0, loss is 4.97. For batch 1, loss is 3.14. For batch 2, loss is 4.06. For batch 3, loss is 4.93. For batch 4, loss is 3.10. The average loss for epoch 14 is 4.04 and mean absolute error is 1.61.

### Standard Keras callbacks

Be sure to check out the existing Keras callbacks by visiting the API doc. Applications include logging to CSV, saving the model, visualizing on TensorBoard and a lot more.