SAS/AF Software: Class Dictionary

Adding Reference Lines to a Histogram Control

A Histogram control lets you emphasizes a particular value on an axis. To do so, you can draw a reference line from that value across the axis area. You can add as many reference lines as you like to an axis that displays values for a numeric variable. You cannot add reference lines on an axis that displays values for a categorical or character variable. Reference lines are available for both 2D and 3D graphs.

[IMAGE]

Reference lines are interactive within the control. They have a handle (the square) at one end of the line, which you can drag toward either end of the axis when the actionMode attribute is set to Refline. You cannot drag the line past the axis variable's minimum or maximum data value. The reference lines also have a label, which you can set. The default label is the number of the reference line, in the order that you created it for the axis (the first line is labeled 1, the second line 2, and so on).

You can create reference lines as restricted or unrestricted. Restricted reference lines cannot cross each other, whereas unrestricted lines can cross. For example, assume you have two reference lines on an axis, and that the lines are positioned at data values 75 and 55. If the reference lines are restricted, you cannot drag the line currently at value 75 to a position below 55 in the data, because it would require the line to cross the line at 55. If the lines are unrestricted, you can drag the line at 75 to a position below 55.

To create a reference line, use the _addReferenceLine method, which takes the following arguments:

Argument Description

axis Axis that will contain the reference line. This can be the X, Y, or Z axis. The axis variable must be numeric.

refID Reference line ID. A unique ID, which is returned by the method. Use this ID to identify the reference line when you want to query or delete the line. If there is an error while creating the reference line, this ID is set to -1.

vType Value type. When this type is set for a reference line, it cannot be changed.
Specify Value to position the reference line according to data values. The value can be numeric or character.
Specify Location (available only for a numeric axis) to position the reference line according to a percentage of the length of the data range.

value The reference line's initial position on the assigned axis.
If the vType parameter is Value, the position must be a data value; for example, specify 5 to position the line at data value 5. The value must be within the axis variable's data range for the reference line to be displayed.
If the vType parameter is Location, the position must be a percentage; for example, specify 0.5 to position the line in the middle of the assigned axis. The location value should be between 0 and 1.

label An optional label to display above or next to the reference line to identify it for the user. For example, you might label it with the data value at the line's current position. The label can contain up to 16 characters.

Argument	Description
axis	Axis that will contain the reference line. This can be the X, Y, or Z axis. The axis variable must be numeric.
refID	Reference line ID. A unique ID, which is returned by the method. Use this ID to identify the reference line when you want to query or delete the line. If there is an error while creating the reference line, this ID is set to -1.
vType	Value type. When this type is set for a reference line, it cannot be changed. Specify Value to position the reference line according to data values. The value can be numeric or character. Specify Location (available only for a numeric axis) to position the reference line according to a percentage of the length of the data range.
value	The reference line's initial position on the assigned axis. If the vType parameter is Value, the position must be a data value; for example, specify 5 to position the line at data value 5. The value must be within the axis variable's data range for the reference line to be displayed. If the vType parameter is Location, the position must be a percentage; for example, specify 0.5 to position the line in the middle of the assigned axis. The location value should be between 0 and 1.
label	An optional label to display above or next to the reference line to identify it for the user. For example, you might label it with the data value at the line's current position. The label can contain up to 16 characters.

To determine whether the reference lines are restricted or unrestricted, set the referenceLineRestriction attribute to Yes to impose a restriction, or No not to impose the restriction.

To set the color for all reference lines on an axis, use the referenceLineColor attribute.

For a control named histogram1, the following code adds a reference line to the middle of the Y axis:

histogram1.referenceLineRestriction = 'yes';
histogram1._addReferenceLine('y', xRefId, 'location', 0.5, 'myLabel');

The following table shows the methods you can use to create and communicate with a reference line.

Method Action

_addReferenceLine adds a reference line to an axis

_deleteReferenceLine deletes a reference line

_getReferenceLineLocation gets the location of the reference line's current position

_getReferenceLineValue gets the data value for the reference line's current position

_setReferenceLineLabel sets a label for the reference line

_setReferenceLineLocation sets the location for the reference line's position

_setReferenceLineValue specifies the data value to use for setting the reference line's position. The value must be within the axis variable's data range.

Method	Action
_addReferenceLine	adds a reference line to an axis
_deleteReferenceLine	deletes a reference line
_getReferenceLineLocation	gets the location of the reference line's current position
_getReferenceLineValue	gets the data value for the reference line's current position
_setReferenceLineLabel	sets a label for the reference line
_setReferenceLineLocation	sets the location for the reference line's position
_setReferenceLineValue	specifies the data value to use for setting the reference line's position. The value must be within the axis variable's data range.

Chapter Contents
Previous
Next
Top of Page