NCL Home > Documentation > Functions > Graphics routines

simple_legend

Creates a legend based on user supplied resources.

Available in version 6.4.0 and later.

Prototype

load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_code.ncl"      ; These four libraries are automatically
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_csm.ncl"       ; loaded from NCL V6.4.0 onward.
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/contributed.ncl"   ; No need for user to explicitly load.
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/shea_util.ncl"

	function simple_legend (
		wks      : graphic,  
		plot     : graphic,  
		genres   : logical,  
		lineres  : logical,  
		textres  : logical   
	)

	return_val [1] :  graphic

Arguments

wks

A Workstation identifier. The identifier is one returned either from calling gsn_open_wks or calling create to create a Workstation object.

plot

The plot upon which the legend will be drawn.

genres

Variable to which general legend resources are associated.

lineres

Variable to which legend line resources are associated.

textres

Variable to which legend text resources are associated.

Return value

A scalar id of the XY plot created is returned. The id of the data object is also returned as an attribute called data. This is useful if you want to use setvalues to change some data options after this function has been called.

Description

Creates a legend using calls to gsn_add_polyline and gsn_add_text. Resources are used to set the position of the legend, the legend labels, the spacing of the legend items, and the appearance of the lines and labels. The legend will be attached to the plot and can therefore be resized with the plot. draw and frame must be called after invoking this function as the plot is not drawn nor is the frame advanced.

There are three resource lists that get passed to the function. Each list has a small number of resources that are recognized by simple_legend. While not every resource and resource list needs to be set, the textres resource list and the lgLabels resource must be set.

genres: General resource list used to set the legend position and spacing between legend items.
-- XPosPosition sets the left position of the legend object in units of percentage of the range of the X-axis. For example setting genres@XPosPosition = 20 will set the left border of the legend to be 20% of the distance from the minimum X-axis value towards the maximum X-axis value. Valid range is 0 to 100. (Default=5.)
-- YPosPosition sets the position of the legend object in units of percentage of the range of the Y-axis. When genres@Position = "Top" YPosPosition sets the top position of the legend object. When genres@Position = "Bottom" YPosPosition sets the bottom position of the legend object. For example setting genres@Position="Top" and genres@YPosPosition = 80. will set the top position of the legend to be 80% of the distance from the minimum Y-axis value towards the maximum Y-axis value. Valid range is 0 to 100. (Default=95.)
-- Position can be set to either "Top" or "Bottom", and sets whether YPosPosition refers to the top or bottom of the legend object. (Default="Top")
-- ItemSpacePercent sets the spacing between legend items in the vertical in units of percentage of the range of the Y-axis. Valid range is 0 to 100. (Default=5.)
-- LineLabelWhiteSpacePercent sets the spacing between the legend lines and the legend text items in units of percentage of the range of the X-axis. Valid range is 0 to 100. (Default=3.)

lineres: Resource list used to set the appearance of the legend lines.
-- lgLineColors sets the colors of the individual legend lines. Can set one color or a list of colors. (Default=foreground color)
-- lgLineOpacity sets the opacity level (range is from 0->1) for individual legend lines. (Default=1.0)
-- lgLineThicknesses sets the line thickness for individual legend lines. (Default=1.0)
-- lgDashIndexes sets the type of dash patterns to be used for the legend lines.(Default=0)
-- LineLengthPercent sets the length of the all legend lines in units of percentage of the range of the X-axis. Valid range is 0 to 100. (Default=7.)

textres: Resource list used to set the appearance of the legend labels.
-- lgLabels sets the labels for each individual legend line. This resource is required, and the size must equal the number of desired legend lines. If no labels are required set lgLabels equal to a empty string array that is of the same size of the number of legend lines.
-- lgLabelFontHeights sets the font heights of the legend labels.(Default=.05)
-- lgLabelColors sets the font colors of the legend labels. (Default=foreground color)
-- lgLabelOpacity sets the opacity of each individual legend label. Valid range is 0 to 1. (Default=1)

For all resources that accept a list, if the dimension size of the list passed to a specific resource does not match the dimension size of the list passed to the textres@lgLabels resource then the first setting in the given resource list will be applied to all other legend entities.

This function can be used to create a legend within the plot area. If the entirety of the legend lines and/or legend labels falls outside the plot area the legend lines and/or the legend labels will not be drawn. To create a legend outside the plot area it is recommended that you create a legend using standard legend resources or use gsn_legend_ndc. (Refer to the Legend Applications Page for examples.)

Limitations: simple_legend can not draw marked lines, draw a border around the legend, nor can it change the background color of the legend box. The latter two issues can be solved manually by calling gsn_add_polygon. See Legend Examples #10 or #12 for examples of drawing a filled polygon.

Examples

The following examples, complete with graphical output, are shown in examples 16 and 17 on the Legend Applications Page.

Example 1

Attach a 3-item legend positioned in the upper left corner to a XY-plot with additional settings for line thickness, line colors, and line lengths. Note that the XPosPercent, YPosPercent and LineLengthPercent resources are set using percentages ranging from 0 to 100.

  wks = gsn_open_wks("png","example1")

  res = True
  res@gsnDraw = False
  res@gsnFrame = False
  plot = gsn_csm_xy(wks,ispan(1,10,1),fspan(1,5,10),res)

  gres = True
  gres@YPosPercent = 95.    ; expressed as %, 0->100, sets position of top border of legend
                            ;  when gres@Position is set to its default setting of "Top" (Default = 95.)
  gres@XPosPercent = 5      ; expressed as %, 0->100, sets position of left border of legend(Default = 5.)

  lineres = True
  lineres@lgLineColors = (/"red","orange","dodgerblue"/) ; line colors
  lineres@lgLineThicknesses = 2.5                        ; line thicknesses
  lineres@LineLengthPercent = 9.                         ; expressed as %, 0->100, length of line

  textres = True
  textres@lgLabels = (/"CESM1 50","CESM1 52","CESM1 55"/)  ; legend labels (required)

  plot = simple_legend(wks,plot,gres,lineres,textres)
  draw(plot)
  frame(wks)

Example 2

Create and attach a legend by using all possible resources accepted by simple_legend.