NCL Home > Documentation > HLUs > Classes

XyPlot class

The XyPlot object draws curves made up of X/Y coordinate pairs with tick marks, titles, and a legend.

Synopsis

Header file:		ncarg/hlu/XyPlot.h
Class name:		xyPlotClass
Class pointer:		NhlxyPlotClass
Fortran class function:	NHLFXYPLOTCLASS
Superclass:		DataComm
Composite classes:	PlotManager,LogLinTransformation,IrregularTransformation

Data specific class
Class name:		xyDataSpecClass
Class pointer:		<Not referenceable>
Fortran class function:	<Not referenceable>
Superclass:		DataSpec

Class-defined types

Type name:		NhlTAlternatePlace
Definition:
typedef enum _NhlAlternatePlace{
	NhlNONE		= 0,	/* "None"	*/
	NhlLEFTAXIS	= 1,	/* "LeftAxis"	*/
	NhlRIGHTAXIS	= 2,	/* "RightAxis"	*/
	NhlTOPAXIS	= 3,	/* "TopAxis"	*/
	NhlBOTTOMAXIS	= 4	/* "BottomAxis"	*/
} NhlAlternatePlace;

Type name:		NhlTLineLabelMode
Definition:
typedef enum _NhlLineLabelMode{
	NhlNOLABELS	= 0,	/* "NoLabels"	*/
	NhlLETTERED	= 1,	/* "Lettered"	*/
	NhlCUSTOM	= 2	/* "Custom"	*/
} NhlLineLabelMode;

Resources

Local resources

+---------------------------------------------------------------+
|			XyPlot resource set			|
|---------------------------------------------------------------|
| NAME				TYPE			ACCESS	|
|	CLASS				DEFAULT			|
|===============================================================|
| xyCoordData			NhlTObjIdGenArray	CSG	|
|	XyCoordData			NULL			|
|---------------------------------------------------------------|
| xyCoordDataSpec		NhlTObjIdGenArray	G	|
|	XyCoordDataSpec			NULL			|
|---------------------------------------------------------------|
| xyCurveDrawOrder              NhlTDrawOrder           RCSG    |
|       XyCurveDrawOrder                "Draw"                  |
|---------------------------------------------------------------|
| xyXStyle			NhlTTickMarkStyle	RCSG	|
|	XyXStyle			NhlLINEAR		|
|---------------------------------------------------------------|
| xyYStyle			NhlTTickMarkStyle	RCSG	|
|	XyYStyle			NhlLINEAR		|
|---------------------------------------------------------------|
| xyXIrregularPoints		NhlTFloatGenArray	RCSG	|
|	XyXIrregularPoints		NULL			|
|---------------------------------------------------------------|
| xyYIrregularPoints		NhlTFloatGenArray	RCSG	|
|	XyYIrregularPoints		NULL			|
|---------------------------------------------------------------|
| xyXIrrTensionF		NhlTFloat		RCSG	|
|	XyXIrrTensionF			2.0			|
|---------------------------------------------------------------|
| xyYIrrTensionF		NhlTFloat		RCSG	|
|	XyYIrrTensionF			2.0			|
|---------------------------------------------------------------|
| xyComputeXMin			NhlTBoolean		RCSG	|
|	XyComputeExtent			<dynamic>		|
|---------------------------------------------------------------|
| xyComputeXMax			NhlTBoolean		RCSG	|
|	XyComputeExtent			<dynamic>		|
|---------------------------------------------------------------|
| xyComputeYMin			NhlTBoolean		RCSG	|
|	XyComputeExtent			<dynamic>		|
|---------------------------------------------------------------|
| xyComputeYMax			NhlTBoolean		RCSG	|
|	XyComputeExtent			<dynamic>		|
+---------------------------------------------------------------+

Data-specific resources

The following resources are not set directly to the XyPlot object. These resources are used to set the graphical attributes that correspond directly with an individual piece of data that is added to the plot. So the attributes of each individual curve or marker are set this way.

When a DataItem object is added to the xyCoordData resource, either using NhlAddData or using NhlSetValues, an XyDataSpec object is automatically created as a child of the XyPlot to hold the resources that describe these graphical attributes. The XyDataSpec object is given the same name as the DataItem object that was added.

To set these resources in a resource file, you would use resource lines similar to this:

    *xyplotname.dataspecname.xyDashPattern:	solidline
    xyplotname
    the name you give the XyPlot when you create it.
    dataspecname
    the name of the XyDataSpec object, which will be the same as the name of the DataItem object that was added to the xyCoordData resource.

To set these resources programmatically, you need to retrieve the XyDataSpec object id, and call NhlSetValues on that object.

    There are two ways to retrieve the ids for the XyDataSpec objects that hold the resources that describe the graphical attributes for a particular DataItem:

  1. If you used NhlAddData to add the DataItem to the xyCoordData resource, then the return value from that function is the id of the XyDataSpec object that describes the graphical attributes for the added DataItem.
  2. You can retrieve the value of the xyCoordDataSpec resource of the XyPlot after all the data have been added to the XyPlot. It is an array containing the ids of all the XyDataSpec objects that are currently describing how all the DataItem objects in the xyCoordData resource are to be visualized.

The XyDataSpec class also inherits all the DataSpec resources. 

+---------------------------------------------------------------+
|			XyDataSpec resource set			|
|---------------------------------------------------------------|
| NAME				TYPE			ACCESS	|
|	CLASS				DEFAULT			|
|===============================================================|
| xyDashPattern			NhlTDashIndex		RSG	|
|	LineDashPattern			NhlSOLIDLINE		|
|---------------------------------------------------------------|
| xyDashPatterns		NhlTDashIndexGenArray	RSG	|
|	XyDashPatterns			NULL			|
|---------------------------------------------------------------|
| xyMonoDashPattern		NhlTBoolean		RSG	|
|	XyMonoDashPattern		False			|
|---------------------------------------------------------------|
| xyMarkLineMode		NhlTMarkLineMode	RSG	|
|	XyMarkLineMode			NhlLINES		|
|---------------------------------------------------------------|
| xyMarkLineModes		NhlTMarkLineModeGenArrayRSG	|
|	XyMarkLineModes			NULL			|
|---------------------------------------------------------------|
| xyMonoMarkLineMode		NhlTBoolean		RSG	|
|	XyMonoMarkLineMode		False			|
|---------------------------------------------------------------|
| xyExplicitLegendLabels	NhlTStringGenArray	RSG	|
|	XyExplicitLegendLabels		NULL			|
|---------------------------------------------------------------|
| xyLineColor			NhlTColorIndex		RSG	|
|	LineColor			NhlFOREGROUND		|
|---------------------------------------------------------------|
| xyLineColors			NhlTColorIndexGenArray	RSG	|
|	XyLineColors			NULL			|
|---------------------------------------------------------------|
| xyMonoLineColor		NhlTBoolean		RSG	|
|	XyMonoLineColor			False			|
|---------------------------------------------------------------|
| xyLineDashSegLenF		NhlTFloat		RCSG	|
|	LineDashSegLenF			<Dynamic>		|
|---------------------------------------------------------------|
| xyLineLabelFontHeightF	NhlTFloat		RCSG	|
|	FontHeightF			<Dynamic>		|
|---------------------------------------------------------------|
| xyLineLabelFontColor		NhlTColorIndex		RSG	|
|	FontColor			NhlFOREGROUND		|
|---------------------------------------------------------------|
| xyLineLabelFontColors		NhlTColorIndexGenArray	RSG	|
|	XyLineLabelFontColors		NULL			|
|---------------------------------------------------------------|
| xyMonoLineLabelFontColor	NhlTBoolean		RSG	|
|	XyMonoLineLabelFontColor	False			|
|---------------------------------------------------------------|
| xyLabelMode			NhlTLineLabelMode	RSG	|
|	XyLabelMode			NhlNOLABELS		|
|---------------------------------------------------------------|
| xyExplicitLabels		NhlTStringGenArray	RSG	|
|	XyExplicitLabels		NULL			|
|---------------------------------------------------------------|
| xyLineThicknessF		NhlTFloat		RSG	|
|	LineThicknessF			1.0			|
|---------------------------------------------------------------|
| xyLineThicknesses		NhlTFloatGenArray	RSG	|
|	XyLineThicknesses		NULL			|
|---------------------------------------------------------------|
| xyMonoLineThickness		NhlTBoolean		RSG	|
|	XyMonoLineThickness		False			|
|---------------------------------------------------------------|
| xyMarker			NhlTMarkerIndex		RSG	|
|	MarkerIndex			"default"		|
|---------------------------------------------------------------|
| xyMarkers			NhlTMarkerIndexGenArray	RSG	|
|	XyMarkers			NULL			|
|---------------------------------------------------------------|
| xyMonoMarker			NhlTBoolean		RSG	|
|	XyMonoMarker			False			|
|---------------------------------------------------------------|
| xyMarkerColor			NhlTColorIndex		RSG	|
|	MarkerColor			NhlFOREGROUND		|
|---------------------------------------------------------------|
| xyMarkerColors		NhlTColorIndexGenArray	RSG	|
|	XyMarkerColors			NULL			|
|---------------------------------------------------------------|
| xyMonoMarkerColor		NhlTBoolean		RSG	|
|	XyMonoMarkerColor		False			|
|---------------------------------------------------------------|
| xyMarkerSizeF			NhlTFloat		RSG	|
|	MarkerSizeF			0.01			|
|---------------------------------------------------------------|
| xyMarkerSizes			NhlTFloatGenArray	RSG	|
|	XyMarkerSizes			NULL			|
|---------------------------------------------------------------|
| xyMonoMarkerSize		NhlTBoolean		RSG	|
|	XyMonoMarkerSize		False			|
|---------------------------------------------------------------|
| xyMarkerThicknessF		NhlTFloat		RSG	|
|	MarkerThicknessF		1.0			|
|---------------------------------------------------------------|
| xyMarkerThicknesses		NhlTFloatGenArray	RSG	|
|	XyMarkerThicknesses		NULL			|
|---------------------------------------------------------------|
| xyMonoMarkerThickness		NhlTBoolean		RSG	|
|	XyMonoMarkerThickness		False			|
|---------------------------------------------------------------|
| xyLineLabelFont               NhlTFont                RCSG    |
|       Font                            "pwritx"                |
|---------------------------------------------------------------|
| xyLineLabelFontAspectF        NhlTFloat               RCSG    |
|       FontAspectF                     1.3125                  |
|---------------------------------------------------------------|
| xyLineLabelFontThicknessF     NhlTFloat               RCSG    |
|       FontThicknessF                  1.0                     |
|---------------------------------------------------------------|
| xyLineLabelFontQuality	NhlTFontQuality		RCSG	|
|       FontQuality                     "High"                  |
|---------------------------------------------------------------|
| xyLineLabelConstantSpacingF   NhlTFloat               RCSG    |
|       TextConstantSpacingF            0.0                     |
|---------------------------------------------------------------|
| xyLineLabelFuncCode           NhlTCharacter           RCSG    |
|       TextFuncCode                    ':'                     |
+---------------------------------------------------------------+

Composite resources

Transformation resources

Transformation class resources specify the extent and direction of the data coordinate system. XyPlot allows read-only access to the following resource:

XyPlot modifies access to other Transformation class resources, as follows:

    trXMinF
    If this resource is not explicitly set, it is determined based on the value of the xyComputeXMin resource and the data extents within the xyCoordData resource.
    trXMaxF
    If this resource is not explicitly set, it is determined based on the value of the xyComputeXMax resource and the data extents within the xyCoordData resource.
    trYMinF
    If this resource is not explicitly set, it is determined based on the value of the xyComputeYMin resource and the data extents within the xyCoordData resource.
    trYMaxF
    If this resource is not explicitly set, it is determined based on the value of the xyComputeYMax resource and the data extents within the xyCoordData resource.

LogLinTransformation resources

If the XyPlot xyXStyle and xyYStyle resources indicate the use of a logarithmic or linear coordinate system, it uses a LogLinTransformation object to manage the transformation to and from data space.

XyPlot disables access to all resources specific to the LogLinTransformation.

IrregularTransformation resources

If the XyPlot xyXStyle and xyYStyle resources indicate the use of an irregular coordinate system, it uses an IrregularTransformation object to manage the transformation to and from data space.

XyPlot disables access to all resources specific to the IrregularTransformation except for:

PlotManager resources

If tfPlotManagerOn is True when an XyPlot object is created, all PlotManager resources are available. However, XyPlot does modify some of the PlotManager resources as follows: The resources for the PlotManager's Composite parts are available as follows:
Title resources
All the Title resources are available as they are modified by PlotManager.
TickMark resources
All the TickMark resources are available as modified by PlotManager.
LabelBar resources
All LabelBar resources are disabled by XyPlot.
Legend resources
The Legend resources are available as modified by PlotManager with the exception of some resources that have been disabled since they are set automatically based on the current values of relevant XyPlot and XyDataSpec resources. These resources include:

Superclass resources

All of the DataComm resources can be set for the XyPlot object.

Description

XyPlot is a composite object. It combines the functionality of the PlotManager object, LogLinTransformation, and IrregularTransformation to create a fully functional XyPlot object.

Since the XyPlot is a composite object, the resources for the Composite classes are also available to the XyPlot object through the standard resource-setting mechanisms.

XyPlot is derived from the DataComm class, which is derived from the Transform class. This means that the functions NhlDataToNDC and NhlNDCToData can be used to obtain transformations of points to and from data coordinates and NDC coordinates. See the Transform class for more information on these functions.

In general, XyPlot accepts one or more vectors of X and Y coordinates and displays them by drawing a line through the {X,Y} coordinate pairs, or drawing markers at each point within the coordinate pairs, or both.

XyPlot provides the user with the capability of configuring the line thickness, dash pattern indexes, colors of the lines, line labels, and line label colors for curves. XyPlot allows the user to configure Marker indexes, colors, sizes, and thicknesses for displaying markers. XyPlot also provides all the same transformation styles that are provided by the TickMark object: LOG, LINEAR, and IRREGULAR.

XyPlot accepts DataItem objects rather than arrays of values. The xyCoordData resource is used to associate DataItem objects with the XyPlot object. The xyCoordData resource is used to specify a list of DataItem objects, and the NhlAddData function appends DataItem to the list.

There are basically two steps to visualizing a set of data in the XyPlot object. First, the programmer has to fully describe the data to the HLU environment. This is done by creating a DataItem object that describes the data's shape. Second, the programmer has to associate the DataItem with the xyCoordData resource of the XyPlot.

You can associate data with XyPlot by creating a DataItem to describe the data. Then use the NhlAddData function to add that DataItem to the list of data referenced by the xyCoordData resource. If the XyPlot object understands data in the format provided (i.e. the DataItem class used), the NhlAddData function will return with a value of NhlNOERROR.

Additionally, the programmer can just set the xyCoordData resource directly using the NhlSetValues function. The xyCoordData resource is set with an array of object ids. The difference between setting the resource directly and calling the NhlAddData function is that the NhlAddData function appends the given data to the current list of data, while setting the xyCoordData resource using NhlSetValues replaces the current value of that resource.

If programmers want to control the XyDataSpec resources programmatically, they will need to add the DataItems to the XyPlot's xyCoordData resource first. Then they can retrieve the value of the xyCoordDataSpec resource. The xyCoordDataSpec resource is an array of XyDataSpec ids. The elements of this array correspond to the DataItem ids in the xyCoordData array resource. To configure exactly how each coordinate pair array of one of the DataItems is going to be displayed, the programmer can set the XyDataSpec resources to the corresponding XyDataSpec id.

The XyDataSpec object is created on behalf of the programmer for each DataItem object that is added to the xyCoordData resource. The XyDataSpec object is created with the same name as the DataItem and as a child of the XyPlot. Therefore, the data-specific resources (i.e. the resources of the XyDataSpec object) can be set in the resource file by simply specifying the name of the DataItem as a child of the XyPlot with the XyDataSpec resources in the resource file.

The XyDataSpec resources allow the user to set dash patterns, line colors, line thicknesses, line labels, and line label font colors and heights for each element of the xyCoordData resource. The user can also set the other standard text attributes for line labels. However, these attributes are only available as scalar resources, and therefore the XyDataSpec object referenced by the first element of the xyCoordDataSpec array supplies the values of these resources for all data elements.

The xyLabelMode and xyExplicitLabels resources control how each curve is labeled. The curve line labels can be any string. However, line labels longer than six or seven characters can cause problems, and spaces are not drawn.

XyPlot also allows markers to be plotted. The xyMarkLineMode, xyMarkLineModes, and xyMonoMarkLineMode resources are used to indicate if markers should be plotted in place of curves, or in addition to them. There are also a number of other resources in the XyDataSpec object to configure exactly how the markers should be displayed.

The next step in configuring an XyPlot is to select and specify the data transformation of the XyPlot object. As is the case with the TickMark object, there are currently three styles of data transformations, Log, Linear, and Irregular. There are two style resources for setting the X-Axis and Y-Axis data transformations. This differs from the TickMark object, where each side of each axis has its own resource for specifying style. XyPlot forces both sides of an axis to have the same style, so there is no need for two separate style resources that set the style for each side of an axis. This has been done to eliminate the possibility that the tick marks don't accurately represent the data transformation. If different styles were allowed for both sides of the X Axis, then the possibility arises that one of the transformations is wrong. The two resources for selecting the transformation style are xyXStyle and xyYStyle. By default, these are both set to Linear.

Once the style is selected, the resources trXMinF, trXMaxF, trYMinF, and trYMaxF are used to set the data extents. If these resources are not set, then the XyPlot object examines the data and determines for itself what the data extents are. The actual data extents could change if additional data are added to the xyCoordData resource or if one of the current DataItems is modified. The tr data-extent resources will be automatically recomputed if the xyComputeXMin, xyComputeXMax, xyComputeYMin, and xyComputeYMax resources allow it.

Irregular style transformations require some additional information. The resources xyXIrregularPoints and xyYIrregularPoints must be used when Irregular style has been selected. These resources apply to both sides of their respective axes. For a more complete discussion of Irregular style transformations, see the description of the TickMark object.

Support functions

The XyPlot object doesn't define any support functions, but it does inherit all the support functions from its superclass.

Status

See also