Debugging Strategies

Why bugs are hard to see

A car with one misfiring cylinder still drives, and the dashboard may show nothing. A learning system behaves the same way. When a model performs poorly, the cause could be the method or a bug in the code, and the output alone rarely tells you which. This page gives tests that separate the two.

The book gives two reasons. First, nobody knows the intended behavior in advance, because the point of learning is to find behavior you did not specify. Second, most models have several adaptive parts. If one part is broken, the others can adapt and still reach acceptable performance.

The book's example shows the second reason. Suppose the update for a bias was written like this, where is the learning rate:

The rule never reads the gradient. Each step lowers the bias by the same amount, so the bias drifts negative. The weights can compensate for it, so the output may still look reasonable. The demo trains two copies of one model. Only the bias update differs.

The bias trace shows the bug at once. The weight also moves away from its correct value of 2, which is the other adaptive part at work. In this toy the prediction error reveals the bug as well. The weight drifts away from 2 to compensate for the falling bias, but it cannot keep up, so the fit gets worse as training goes on. The book's warning is that this need not happen, since the weights may compensate depending on the input distribution.

What the bug hides

The book says the bug may not be apparent from the output, because the other parts may compensate. Whether they do depends on the input distribution, so a single number can miss a real defect. The next section looks at the cases where the model is most wrong.

Look at the worst mistakes

Many models report how confident they are. A classifier with a softmax output, which turns its class scores into probabilities that add up to one, assigns a probability to every class, and the largest one reads as its confidence. The book warns that these values usually run high, but they still carry information. Examples that are hard to label correctly tend to receive smaller probabilities. Sorting by confidence therefore shows where the model is confidently wrong.

The book's example comes from the Street View transcription system. The address detector sometimes cropped the image too tightly, so the first digit was cut off. The network gave the correct answer very low probability on those images. Sorting the confident mistakes exposed the cropping problem. The book notes that spending weeks on the detector could have fixed it. Instead, the team widened the crop region, which added ten percentage points to coverage.

The demo below is a small toy with the same shape. It has sixteen address images. Some are cropped too tightly, and the model is confidently wrong on them.

The mistakes at the top of the list share one cause in this toy, and that is the signal the book describes. In a real system the fix sits in how the crop is chosen. The book's team widened the crop region rather than spend weeks improving the detector.

Two checks to run

When a model is confidently wrong on a group of inputs, look at how those inputs were prepared before you look at the model. Then ask whether the confidence numbers are useful. The book's answer is that they are useful for ranking mistakes, even though they are not exact probabilities.

Compare training and test error

The book suggests reading two errors together. If training error is low but test error is high, the training procedure probably works, and the model overfits for basic algorithmic reasons. A second possibility is that the test error itself is measured wrongly. A model saved and reloaded incorrectly, or test data prepared differently from the training data, can produce the same pattern.

If both errors are high, a software defect and genuine underfitting look alike. The book then calls for further tests, which are the tiny-dataset test in the next section and the gradient check after it.

The book gives no numbers for low and high. The threshold in the demo is your choice, and it sets what counts as low.

Notice that the case of low training error and high test error is the one the book attributes to overfitting. The second possibility, a faulty measurement, is only reached by checking the procedure, and no slider can show it. A single pair of numbers is a clue, not a verdict.

This reading is added here and is not printed in the book. When training error is above the threshold while test error is below it, the demo asks you to check how the two errors were measured, because the book does not describe this pattern.

Fit a tiny dataset

If the training error is high, the question is whether the model underfits or the code has a defect. The book's test uses a dataset so small that a correct implementation can fit it. A classifier with a single example can be fit by setting the output biases correctly. An autoencoder should reproduce one example with high fidelity, and a generative model should emit samples that resemble it.

The demo trains a three-class softmax classifier on one example. The probabilities come from and the loss is the negative logarithm of the probability of the correct class. The starting loss is the logarithm of 3, which is about 1.10. Move the steps, then switch on the defect to see what a sign error does.

This setup is added here and is not printed in the book. The book describes the test in words, and the two equations are the standard softmax and cross-entropy definitions.

A correct implementation should drive the loss down on one example, and it does so steadily. A loss that rises, or that stalls far above zero on one example, points to the code rather than the model. This is the test that separates the two.

Check gradients by finite differences

When you write a gradient by hand, a common error is a wrong sign or a missing term. The check compares your gradient with a numerical one. The book starts from the definition of the derivative, which is a limit.

Since the limit cannot be computed directly, the book uses a small finite step and gets the approximation in equation 11.6.

The centered difference in equation 11.7 is more accurate, because the first error term cancels. The step must be large enough that the change is not rounded away by the computer, and small enough that the approximation holds.

The demo uses the function at , a function chosen for this page and not taken from the book. Its exact derivative is known, so every error can be measured. The forward error, the gap between the forward estimate and the true derivative, falls as the step shrinks, then rises again, because rounding takes over. This derivation is added here and is not printed in the book. For small steps the forward error is about one half of times the step, plus a rounding part that grows as the step shrinks.

Testing a vector-valued function needs one derivative at a time. The book suggests projecting the output and the input onto random vectors, and repeating the test with more than one random choice, so that an error orthogonal to one projection is not missed.

When the software supports complex numbers, a more accurate estimate is available. Equations 11.8 and 11.9 show that the imaginary part of , divided by , estimates the derivative. The method subtracts nothing, so the step can be tiny without cancellation.

Saturation, update sizes and guarantees

Some checks need no reference answer. The book suggests watching the statistics of activations and gradients over an epoch, one full pass through the training set. For a tanh unit, which squashes its input into the range from minus one to one, the average absolute pre-activation shows how saturated the unit is. A saturated unit gives almost the same output for any input, so its gradient is close to zero. This derivation is added here and is not printed in the book: the derivative of tanh is , which is small when the output is near 1 or minus 1.

The demo draws two thousand pre-activations from a normal distribution with spread , and counts the units whose output has magnitude above 0.9. The book's measure is the average absolute pre-activation. This share is a simpler count, and it is easy to read. The normal-distribution formula gives the same share without sampling, and the two should agree.

The book also compares the size of each update with the size of the parameter. It suggests that the update over one minibatch, the small set of examples used for one gradient estimate, should be about 1 percent of the parameter's magnitude, not 50 percent and not 0.001 percent. The update ratio below is the learning rate times the gradient, divided by the parameter. The formula is added here and is not printed in the book.

The last check is for guarantees. Some algorithms promise an exact property after each step, such as a zero gradient at convergence. The book notes that rounding means these hold only approximately, so the test must allow a tolerance. The demo solves two equations exactly by a formula, then measures how far the answer is from satisfying them.

Takeaways

• Ask whether the poor result is the method or a bug. Build a case you can predict, or test one part in isolation.
• Read the worst mistakes and watch the model at work. A single error number can hide a defect that other parts absorb.
• Read training and test error together. If both are high, run the tiny-dataset test before you tune anything else.
• A correct implementation fits a single example. Check hand-written gradients with finite differences, and use complex steps where the software allows.
• Compare update sizes with parameter sizes, aiming near 1 percent, and use a tolerance for any guarantee that rounding can break.

Check yourself

Questions that mix the whole module. Each one is scored, and the score feeds your mastery of this module.

Source: Ian Goodfellow, Yoshua Bengio and Aaron Courville, Deep Learning, MIT Press, 2016, Section 11.5 (pages 436–439), free to read at deeplearningbook.org. Where the book prints equation numbers, the numbers here follow the book. The order of ideas follows the book. The explanations and all demos were written for this page.