NCL Home > Documentation > Graphics > Graphical Interfaces

gsn_csm_xy

Creates and draws an XY plot.

Prototype

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

	function gsn_csm_xy (
		wks [1] : graphic,  
		x       : numeric,  
		y       : numeric,  
		res [1] : 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.

x
y

The X and Y coordinates of the curve(s). If x and/or y are two-dimensional, then the leftmost dimension determines the number of curves.

res

A variable containing an optional list of plot resources, attached as attributes. Set to True if you want the attached attributes to be applied, and False if you either don't have any resources to set, or you don't want the resources applied.

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

This function creates and draws an XY plot on the given workstation. By default, the tickmarks will point outward.

If either x or y has a _FillValue attribute, this value will be used as a missing value. If either of the data arrays have a "long_name" and/or "units" attribute, these will be used to label the X and Y axes, unless the tickmarks on the X or Y axes are explicitly labeled using the tmXBMode or tmYLMode resources.

To maximize the area that the plot is drawn in, set the special resource gsnMaximize to True.

In NCL 6.4.0, this function was majorly overhauled to allow horizontal bar charts, and to allow the special 'gsn' color resources to be set with RGB/A colors, allowing for transparency.

Here are some of the special "gsn" resources recognized by this function:

  • gsnYRefLine / gsnXRefLine if either of these are are set to some value, then a vertical or horizontal reference line will be drawn at that value.

  • gsnAboveYRefLineColor /gsnBelowYRefLineColor - if either of these resources are set, then the areas between the reference line specified by gsnYRefLine and the Y-curve are filled in the given colors.

  • gsnRightXRefLineColor /gsnLeftXRefLineColor - if either of these resources are set , then areas between the reference line specified by gsnXRefLine and the X-curve are filled in the given colors. (Added in NCL V6.4.0.)

  • gsnXYBarChart - if set to True, then instead of a curve, a vertical bar will be drawn for each Y value. Each bar will be centered around its X location. In NCL 6.4.0, if gsnXRefLine is set, then horizontal bars will be drawn instead.

  • gsnXYBarChartOutlineOnly - if set to True, then instead of a curve, you will get a box outline of your curve. This resource is different than the behavior of gsnXYBarChart, because the vertical lines represent the exact location of the X (or Y) values, and not centered about the X (or Y) values.

There are many other special GSN resources that apply to XY plots. See the gsn resource page for a full list.

See Also

gsn_csm_y, gsn_csm_xy2, gsn_csm_x2y, gsn_csm_x2y2, gsn_xy, gsn_y
Special gsn resources

Examples

For some application examples, see: