How to Use Labels, Annotations, and Legends in MatPlotLib

To fully document your MatPlotLib graph, you usually have to resort to labels, annotations, and legends. Each of these elements has a different purpose, as follows:

• Label: Provides positive identification of a particular data element or grouping. The purpose is to make it easy for the viewer to know the name or kind of data illustrated.
• Annotation: Augments the information the viewer can immediately see about the data with notes, sources, or other useful information. In contrast to a label, the purpose of annotation is to help extend the viewer’s knowledge of the data rather than simply identify it.
• Legend: Presents a listing of the data groups within the graph and often provides cues (such as line type or color) to make identification of the data group easier. For example, all the red points may belong to group A, while all the blue points may belong to group B.

The following information helps you understand the purpose and usage of various documentation aids provided with MatPlotLib. These documentation aids help you create an environment in which the viewer is certain as to the source, purpose, and usage of data elements. Some graphs work just fine without any documentation aids, but in other cases, you might find that you need to use all three in order to communicate with your viewer fully.

Adding labels

Labels help people understand the significance of each axis of any graph you create. Without labels, the values portrayed don’t have any significance. In addition to a moniker, such as rainfall, you can also add units of measure, such as inches or centimeters, so that your audience knows how to interpret the data shown. The following example shows how to add labels to your graph:

values = [1, 5, 8, 9, 2, 0, 3, 10, 4, 7>

import matplotlib.pyplot as plt

plt.xlabel('Entries')

plt.ylabel('Values')

plt.plot(range(1,11), values)

plt.show()

The call to xlabel() documents the x-axis of your graph, while the call to ylabel() documents the y-axis of your graph.

Annotating the chart

You use annotation to draw special attention to points of interest on a graph. For example, you may want to point out that a specific data point is outside the usual range expected for a particular data set. The following example shows how to add annotation to a graph.

values = [1, 5, 8, 9, 2, 0, 3, 10, 4, 7>

import matplotlib.pyplot as plt

plt.annotate(xy=[1,1>, s='First Entry')

plt.plot(range(1,11), values)

plt.show()

The call to annotate() provides the labeling you need. You must provide a location for the annotation by using the xy parameter, as well as provide text to place at the location by using the s parameter. The annotate() function also provides other parameters that you can use to create special formatting or placement on-screen.

Creating a legend

A legend documents the individual elements of a plot. Each line is presented in a table that contains a label for it so that people can differentiate between each line. For example, one line may represent sales from the first store location and another line may represent sales from a second store location, so you include an entry in the legend for each line that is labeled first and second. The following example shows how to add a legend to your plot:

values = [1, 5, 8, 9, 2, 0, 3, 10, 4, 7>

values2 = [3, 8, 9, 2, 1, 2, 4, 7, 6, 6>

import matplotlib.pyplot as plt

line1 = plt.plot(range(1,11), values)

line2 = plt.plot(range(1,11), values2)

plt.legend(['First', 'Second’>, loc=4)

plt.show()

The call to legend() occurs after you create the plots, not before. You must provide a handle to each of the plots. Notice how line1 is set equal to the first plot() call and line2 is set equal to the second plot() call.

The default location for the legend is the upper-right corner of the plot, which proved inconvenient for this particular example. Adding the loc parameter lets you place the legend in a different location. See the legend() function documentation for additional legend locations.