NCL Home> Application examples> Plot techniques

Legends

There are six distinct ways to create legends, and all are shown in the examples below.
leg_1.ncl: The resources in this script contain the bare minimum to get a two item legend in the upper left corner of the plot. The default values of many of these resources draw a huge legend that is outside of the plot domain.

pmLegendDisplayMode = "Always" Turns on the legend. The location of the legend within the plot is controlled primarily by three resources. One chooses the reference axis (pmLegendSide = "Top") and the other two determine in NDC coordinates how far to move the legend perpendicular (pmLegendOrthogonalPosF = -0.3 ) and parallel (pmLegendParallelPosF = .1) to this reference axis.
In this example the top axis is the reference, and the Parallel value of .1 keeps the legend close to the left axis. Increasing this value will move the legend at the same "height" across the plot to the right.

Note that the orthogonal position is negative. This is expected. In this case decreasing values (e.g. from -0.3 to -0.4) would move the legend down the plot.

The default size of the legend is much to large for the plot, so several resources are set to resize the legend:
pmLegendWidthF = 0.15
pmLegendHeightF = 0.18.

The default size of the legend labels is also too large, and so is scaled down with lgLabelFontHeightF = 0.03.

The values of the legend labels are determined by:
xyExplicitLegendLabels = (/"U","V"/). The default value is the name of the variable.

Finally, the default box around the legend is turned off with:
lgPerimOn = False

leg_2.ncl: Adds a title and bounding box to the plot. Changes the position of the legend.

lgTitleOn = True
lgTitleString = "Example"
lgTitleFontHeightF = .025, Turns on the title and sets its value and font size.

leg_3.ncl: Demonstrates what a legend looks like with colored markers. Swaps the orientation.

lgOrientation = "horizontal"
changes the orientation of the legend.

leg_4.ncl: In many cases there may be very little space on a line plot to place a label, particularly when there are many lines and the label is long. This examples demonstrates making the legend horizontal, using the height and width attributes to really shrink the lines, and then angling the labels in order to shrink it even more.

lgLabelAngleF = 280., Changes the angle of the labels.

pmLegendWidthF = 0.12
pmLegendHeightF = 0.05
lgLabelFontHeightF = .02
were the values I chose to make this legend small. You can experiment with values that work for you.

leg_5.ncl: Demonstrates the old way of creating a custom legend. See example 6 for an easier method.

A legend can have two types of labels. One is in the center of the line lgLineLabelStrings, and the other is at the end lgLabelStrings. This example uses the former, which is why several of the resources are different from the other legend examples.

leg_6.ncl: Demonstrates the addition of a legend for a contour-on-contour plot.

gsn_legend_ndc is the function that will add a legend to a contour plot.

leg_7.ncl: Demonstrates how to add a legend using calls to gsn_polymarker_ndc and gsn_text_ndc.
leg_8.ncl: Demonstrates how to create a legend by using gsn_create_legend, available in NCL version 4.2.0.a034. After the legend is created you have to attach it to the plot by using gsn_add_annotation.

Note when using gsn_add_annotation that gsnDraw and gsnFrame must be set to False. This results in the need to call draw and frame after the legend is attached to the plot

leg_9.ncl: Demonstrates how to change the order of the items in a legend using the lgItemOrder resource, added in version 5.1.0.
leg_10.ncl: This example demonstrates how to fill the legend box so that it masks the XY curves, by setting lgPerimFill to "SolidFill" and lgPerimFillColor to the desired fill color.

If you add other plot items, like grid lines (see 2nd and 3rd images), then you need to draw the plot twice in order to get the legend to mask the additional items.

Setting xyLabelMode = "Custom" allows you specify labels for the XY curves. These labels will automatically be used in the legend.

leg_11.ncl: This example demonstrates how to create a separate legend based on XY resource settings and draw it on a separate page.

The following XY resources translate into the following legend resources:

xyMarkLineModes lgItemTypes
xyDashPatterns lgDashIndexes
xyMarkers lgMarkerIndexes
xyMarkerColors lgMarkerColors

Note that you have to set lgAutoManage to False in order to be able to control the font height of the legend title (lgTitleFontHeightF).

leg_12.ncl: This example demonstrates how to customize a legend by:

moving it into the plot (pmLegendOrthogonalPosF / pmLegendParallelPosF)
changing the legend width and height (pmLegendWidthF / pmLegendHeightF)
increasing the label size (lgLabelFontHeightF)
decreasing the length of the legend lines (lgBoxMinorExtentF)

leg_13.ncl: This example demonstrates how to customize a legend based on resource settings in an XY plot. This method may be desired if you need to turn off individual legend items, which you can't do very easily using the legend that comes with the XY plot.

This script has a function called "create_legend_from_plot" for creating and attaching the legend. It uses special attributes attached to the "opt" variable to indicate how many legend items are desired.

leg_14.ncl: This example demonstrates how to create an XY plot with four curves, but only include a legend for two of the curves.

The steps are 1) create the first plot with two curves and no legend, 2) create the second plot with the other two curves and with a legend, 3) call overlay to overlay the two plots, 4) draw the overlaid plots.

leg_15.ncl: This example is similar to leg_10.ncl,except it shows how to attach one plot to another, so you can panel them later. gsn_add_annotation is used to attach the plots.

This example is slightly different in that it shows how to draw legends on top of tickmarks; there's no draw order resource for this (yet).

leg_16.ncl: Demonstrates how to use simple_legend to create a legend. simple_legend gives the user complete control over the design and placement of the legend by utilizing user-defined resources.

This example creates a simple XY plot and attaches the legend to the upper left corner of the plot by setting a few of the resources that the function accepts. Note that draw and frame must be called after the legend is created.

leg_17.ncl: Similar to leg_16.ncl, this script demonstrates how to use simple_legend to create a legend by invoking all possible resources that simple_legend accepts.