NCL Home> Application examples> Plot techniques

NCL Graphics: Text (adding to a plot)

There are many ways you can manipulate text, including:

  • formatting the string (for floating point or integers) using sprinti and/or sprintf
  • changing the font (via xxYYYYFont resources, or a function code)
  • making it larger (via xxYYYYFontHeightF resources)
  • changing the color (via xxYYYYFontColor resources)

Function codes:

There are many fonts/character sets in NCL (e.g. Greek). You change between sets by using a function code. The default code is a ":", but since this is a character that people often put into their strings, we recommend changing that to a non-used character like a "~" (in V6.1.0 of NCL and later, the default function code is a "~"). You can change this on the fly or in your .hluresfile.

To add a Greek character, use fonts/character set F33 (e.g. ~F33~s is a sigma). See example xy_10.ncl for details.

To superscript: ~S~

To subscript: ~B~

text_add_1.ncl / text_1.ncl: Adds text to a plot using plot coordinates

There are two different ways you can put text on an existing plot using plot coordinates: using the gsn_add_text function (text_add_1.ncl), or the gsn_text procedure text_1.ncl).

The gsn_add_text function is usually the better one to use. It actually attaches the text the plot, so if you resize the plot, the text will automatically resize (see example text_9.ncl below). This is especially important if you plan to panel the text later. It's a little more work, because you have to call draw on the plot in order to see the text. With the gsn_text procedure, you see the text right away.

The default added text size is too large, so we have made it smaller using txFontHeightF. You could also change the color etc of the text here as well.

text_2.ncl: Adds text to a plot using page (ndc) coordinates.

gsn_text_ndc is the plot interface that adds text to an already created plot using page coordinates. Note: page coordinates are normalized. They go from 0->1.0 in both directions.

text_3.ncl: Can be difficult to determine the NDC coordinates of a page. Adam Phillips created a nifty function that draws an NDC grid on a plot. This allows the user to determine their text placement in fewer iterations.

drawNDCGrid draws the grid.

text_4.ncl: Demonstrates adding data values to a contour plot.

sprintf is the function that formats the text output.

text_5.ncl: Demonstrates adding a carriage return to a text string.

The ~C~ will put a carriage return in a text string. By default it is left justified. If you need it centered, you will have to add spaces.

The ~ is a function code. The default function code is a colon (:), but we have changed this to a ~ in our .hluresfile

text_6.ncl: Demonstrates how to put a double quote into a text string.
text_7.ncl: Demonstrates how to put a degree symbol into a string.
text_8.ncl: A more complicated example of adding multiple text strings to a plot using gsn_add_text.
text_9.ncl: This example shows how to use gsn_create_text to create text strings and gsn_add_annotation to attach text items to a plot.

By attaching the strings, they will get resized if you resize the plot (see last frame).

The default is to put the string in the center of the plot. In order to change how the string is positioned, you can set some annotation resources: amParallelPosF, amOrthogonalPosF, and amJust. The amParallelPosF and amOrthogonalPosF resources indicate where, relative to the plot's boundaries, to position the string, and the amJust resource indicates which one of nine possible locations on the string ("CenterCenter", "TopCenter", "TopRight", "CenterRight", "BottomRight", "BottomCenter", "BottomLeft", "CenterLeft", "TopLeft") about which the string is positioned.

See example text_18.ncl below for a similar example that adds to strings to four plots and panels them.

text_10.ncl: This example shows how to use gsn_add_text to add lots of strings to a map plot, and then how to determine which ones overlay other strings so you can remove them.

You can download the small istasyontablosu_son.txt data file for this example. Thanks to Ozan Mert Gokturk for providing the data file and the inspiration for this example.

This example is similar to "text_17.ncl" below, which removes strings that fall on the plot's borders.

text_11.ncl: This example shows how to use gsn_add_text to add a string on the right Y axis, since you can't have both a right and left Y axis string using the usual ti* resources.

The gsn_create_text and gsn_add_annotation functions are used to create and attach the text strings.

text_12.ncl: This example shows how to add three subtitles at the top of any plot, mimicing the subtitles you get in the gsn_csm functions.

The gsn_create_text and gsn_add_annotation functions are used to create and attach the text strings.

The key to getting the strings to be either left-justified, right-justified, or centered is to use a combination of the amJust and amParallelPosF resources. You also need to set amOrthogonalPosF to some small value to move the strings away from the top edge (tickmarks) of the plot. This value should be the same for all three strings, in order to keep them lined up.

Left-justified string:
amJust = "BottomLeft"
amParallelPosF = -0.5
Centered string:
amJust = "BottomCenter"
amParallelPosF = 0.0
Right-justified string:
amJust = "BottomRight"
amParallelPosF = 0.5
text_13.ncl: This example shows how to use the txJust resource to align text.

To place text using a gsn_text* routine, you specify X and Y positions of the text box that encloses the string. By default, the text string box is centered about that X,Y position, unless you set txJust to one of the other eight allowed values: "BottomRight", "CenterRight", "TopRight", "BottomCenter", "TopCenter", "BottomLeft", "CenterLeft", or "TopLeft". ("CenterCenter" is the default.)

text_14.ncl: This example shows how to use text function codes to draw accented characters like the umlaut. This is done using the H and V function codes that allow you to do small vertical and horizontal moves as you are drawing text.

For example, the double dots in the umlaut are drawn by using character "H" from font table 35, and a series of horizontal and vertical moves to put the dots over the desired character.

This script was contributed by Mateus da Silva Teixeira from IPMet.

text_15.ncl: This example shows how to use gsn_add_text to add data values to an existing cell-filled contour plot.

The txJust resource is set to "CenterCenter", unless the text string is on one of the four edges of the plot.

text_16.ncl: This example shows how to use sprintf in conjunction with txJust to make sure text strings with floating point numbers line up at their decimal points.
newcolor_2.ncl: This example shows how to create a text string that is highly transparent by setting the txFontOpacityF resource to 0.10. A value of 1.0 means fully opaque.

This capability was added in NCL version 6.1.0.

text_17.ncl: This example shows how to remove text strings that were added to a map that fall outside the map's borders. Since there's no way to clip these strings, you need to use NhlRemoveAnnotation to remove the offending text strings.

This example shows three versions of the map: the original plot with the "bad" strings, the plot with the "bad" strings drawn in a different color, and the plot with the "bad" strings removed.

This example is similar to "text_10.ncl", which shows how to remove overlapping strings.

text_18.ncl: This example shows how to add text strings to the top left and right of four plots and then panel them. This is similar to example text_9.ncl above.

You can't do this kind of thing using gsnPanelFigureStrings, because this only allows for one label per plot be added.

The text strings are created with gsn_create_text, and then attached to each plot using gsn_add_annotation. You need to set the special resources amParallelPosF and amOrthogonalPosF to correctly align the text strings as desired.

text_19.ncl: This example shows how to draw text strings on a map that follow the curve of a lat/lon line.

The key is to use gsn_polyline or gsn_add_polyline to define the lat/lon line, and set the special resources gsLineLabelString resource to the desired string.

Note: we discovered a bug in NCL that causes this script not to work with NCL versions 6.2.0, 6.2.1, or 6.3.0. We have a ticket on this (NCL-2262), and hope to fix it for version 6.4.0.

text_20.ncl: This example shows how to use the drawNDCGrid procedure to help you select locations for placing text outside the plot.

The first image is the plot with the NDC grid. The second image is the plot with text strings added.

Once the XY plot is created, you can use setvalues to retrieve the viewport area of the plot, and NhlGetBB to retrieve the bounding box that encloses all the plot elements. This allows you to calculate the location of various text strings relative to the plot's size and location.