NCL Home > Documentation > Functions > Graphics routines

simple_legend_ndc

Creates a legend in NDC space based on user supplied resources.

Available in version 6.5.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"

	procedure simple_legend_ndc (
		wks      : graphic,  
		genres   : logical,  
		lineres  : logical,  
		textres  : logical   
	)

Arguments

wks

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

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.

Description

Creates a legend in NDC space using calls to gsn_polyline_ndc and gsn_text_ndc. 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 workstation. frame must be called after invoking this procedure as the frame is not advanced.

There are three resource lists that get passed to the procedure. Each list has a small number of resources that are recognized by simple_legend_ndc. 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 width of the workstation. For example setting genres@XPosPosition = 20 will set the left border of the legend to be 20% of the distance from the left side of the workstation towards the right side, equal to a NDC value of 0.2. Valid range is 0 to 100. (Default=5.)
-- YPosPosition sets the position of the legend object in units of percentage of the height of the workstation. 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 bottom of the workstation towards the top, equal to a NDC value of 0.8. 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 workstation Y-axis. Valid range is 0 to 100. (Default=2.5)
-- LineLabelWhiteSpacePercent sets the spacing between the legend lines and the legend text items in units of percentage of the range of the workstation 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 workstation 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 anywhere on the workstation. To create a legend that is attached to a plot (and is therefore resizable) simple_legend should be used.

Limitations: simple_legend_ndc 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_polygon_ndc. See Polygons Examples #10, #13 or #18 for examples of drawing a filled polygon.

See Also

simple_legend, gsn_legend_ndc

Examples

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

Example 1

Draw a 3-item legend positioned in the upper left corner of a workstation 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@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)

  simple_legend_ndc(wks,gres,lineres,textres)
  frame(wks)

Example 2

Create and attach a legend to a workstation by using all possible resources accepted by simple_legend_ndc. 

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

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

  gres = True
  gres@YPosPercent = 5.               ; expressed as %, 0->100, sets position of bottom border of legend
                                      ;  when gres@Position="Bottom" (Default = 95.)
  gres@XPosPercent = 30.               ; expressed as %, 0->100, sets position of left border of legend
                                      ;  (Default = 5.)
  gres@Position = "Bottom"            ; YPosPercent setting reflects the "Top" or "Bottom" of legend
                                      ;  (Default="Top")
  gres@ItemSpacePercent = 2.          ; expressed as %, 0->100, space between legend items (Default = 2.5)
  gres@LineLabelWhiteSpacePercent = 2 ; expressed as %, 0->100, space between line and label (Default = 3.)

  lineres = True
  lineres@lgLineColors = (/"red","blue","dodgerblue"/) ; line colors
  lineres@lgLineOpacity = (/0.3,0.5,0.5/)              ; line opacities
  lineres@lgLineThicknesses = (/1.0,4.0,12.0/)         ; line thicknesses
  lineres@lgDashIndexes = (/0,1,14/)                   ; line types
  lineres@LineLengthPercent = 5                        ; expressed as %, 0->100, length of line

  textres = True
  textres@lgLabels = (/"CCSM4 Control","b.e11.B1850C5CN.f09_g16.005","Ensemble Member #15"/) ; labels (req)
  textres@lgLabelFontHeights = (/0.015,0.018,0.025/)                           ; label font heights
  textres@lgLabelColors = (/"green","black","orange"/)                        ; label font colors
  textres@lgLabelOpacity = (/0.8,0.5,1.0/)                                     ; 0->1, label opacities

  simple_legend_ndc(wks,gres,lineres,textres)
  frame(wks)