 |
|
| The GANTT Procedure |
| Automatic Text Annotation |
The automatic text annotation feature is designed specifically for labeling Gantt charts independently of the SAS/GRAPH Annotate facility. This facility enables you to display label strings with a minimum of effort and data entry while providing the capability for more complex chart labeling situations. Some of the properties that characterize this feature are
the ability to tag labels. This enables you to define 1-1, 1-many, many-1, and many-many relationships.
the ability to link label coordinates and label strings to variables in the Schedule data set. This enables the Label data set to remain unchanged even if the Schedule data set changes, such as when monitoring a project.
the ability to automatically format or convert numeric variable values that have been specified for label text strings
the ability to automatically split strings embedded with blanks to make the pieces as equal in length as possible, with the provision to override this behavior by specifying a split character
the ability to mix data and percentage coordinates
the ability to clip labels running off the frame of the Gantt chart
All relevant information is contained in a SAS data set specified using the LABDATA= data set option in the PROC GANTT statement. This data set is also referred to as the Label data set in the context of this documentation. The Label data set is required to contain certain variables in order to determine the label string and the positional information related to the string. At the very least, it requires three variables, one to determine the string to be displayed, one to determine the horizontal position, and one to determine the vertical position. The procedure terminates if it cannot find the required variables.
Determining the ... |
requires the following variables |
Label text string |
_LVAR and/or _LABEL |
Horizontal placement position |
_XVAR and/or _X |
Vertical placement position |
LABVAR= and/or _Y |
The LABVAR variable refers to the variable specified with the LABVAR= option in the CHART statement. It is the LABVAR variable that links the Schedule and Label data sets together. As far as possible, the procedure attempts to use the _X, _Y, and _LABEL variables in the Label data set. However, a link established using the LABVAR variable makes the Schedule data set a secondary source of information for determining positional and text string information for linked observations. The exact meaning of the preceding variables is explained later in this chapter.
Note that, other than the preceding requirements, there are no further restrictions on the Label data set. In fact, the Schedule data set can also be specified as the Label data set as long as the required variables are present. There are several optional variables in the Label data set. These variables enable you to specify offsets in both horizontal and vertical directions from the given coordinate position; adjust graphical attributes such as baseline angles, character rotations, colors, fonts, and heights; control justification of strings; control placement behavior at pagebreaks; and specify coordinate reference systems for the horizontal and vertical values.
Label Data Set
You specify the Label data set using the LABDATA= option in the PROC GANTT statement. This initiates the labeling of the Gantt chart. The Label data set contains the information that provides the means of determining the label strings and their placement positions. As far as possible, the procedure attempts to use the _X, _Y, and _LABEL variables in the Label data set to extract the horizontal position, the vertical position, and the text string, respectively. The Schedule data set acts as a secondary source of information for all Label data set observations that are linked to it. The priority mechanism is described in the section Determining the Vertical Position.
Determining the Vertical Position
You can specify the vertical position for a label string in one of two ways, either directly by using the _Y variable in the Label data set or indirectly by associating the label with an activity or activities. In the latter case, the vertical position is determined by the relative position of the activity on the activity axis of the Gantt chart.
Directly using _Y
The procedure determines the vertical position using the _Y variable. You specify the coordinate system for the value of _Y with the optional _YSYS variable. A value of DATA or DATAVAL for the _YSYS variable indicates that the unit of measurement is data values. This is also the default coordinate system for _Y. A value of PCT or PCTVAL indicates that the unit of measurement is percentage of the procedure output area. When the coordinate system for _Y is based on data values, the values that _Y can take are restricted to positive real numbers with the exception of -1, which is a special value indicating that the label be displayed for every activity. In effect, this is a more concise way of linking a label to every activity.
Indirectly using LABVAR=
If the _Y variable does not exist or its value is missing, the procedure uses the value of the LABVAR variable to determine the vertical position of the label. If the LABVAR= option is specified and the value of the LABVAR variable is nonmissing, the observation is displayed for every activity that provides a matching value for the LABVAR variable. It is quite possible that there are no activities that provide a match, in which case the Label data set observation is ignored. Likewise, the Label data set observation is ignored if the value of the LABVAR variable is missing,
When the vertical position is based on an integer value for _Y or linkage using the LABVAR variable, the default position for the baseline of the string is the top of the first schedule bar corresponding to the activity (unless offsets _XOFFSET or _YOFFSET are used).
Determining the Horizontal Position
The procedure attempts to determine the horizontal position using the _X variable. You specify the coordinate system for the value of _X with the optional _XSYS variable. A value of DATA or DATAVAL for the _XSYS variable indicates that the unit of measurement is data values. This is also the default coordinate system for _X. A value of PCT or PCTVAL indicates that the unit of measurement is percentage of the procedure output area.
If the _X variable does not exist or its value is missing, the procedure ignores the Label data set observation if the observation is not linked to an activity in the Schedule data set. However, if the label is linked to an activity (either by the LABVAR variable or a value of -1 for _Y, as described previously), the procedure extracts the horizontal position using the _XVAR variable in the Label data set. The _XVAR variable values are names of numeric variables in the Schedule data set. If the _XVAR value is not missing, the horizontal position is the value of the specified variable in the Schedule data set corresponding to the activity. If no such variable exists in the Schedule data set or its value is missing, no label is displayed for this particular (activity, label) link. As with the _X variable, the _XSYS variable names the unit of measurement for the associated Schedule data set variable.
Coordinate Systems
Coordinates can be specified in data values and percentages. It is important to note a significant difference between these two systems when using multiple pages. A data coordinate value is a point along either the time or activity axis, and it can be related to a page number and to a position on that page in the relevant direction. A percentage value, on the other hand, cannot be related to a particular page and, as such, is treated as applicable to every single page. It is possible to mix data and percentage coordinates. That is, the horizontal position can be in data values and the vertical position can be in percentage values, and vice versa. By mixing coordinate systems, you can get as flexible as you want in labeling Gantt charts.
If both coordinates are in data values, the label is displayed at a specific coordinate on a specific page.
If the horizontal coordinate is a percentage, the label is displayed at this horizontal position for every page that corresponds to the vertical position. Likewise, if the vertical position is a percentage, the label is displayed at this vertical position for every page that corresponds to the horizontal position. For example, you can display certain headings at the top of the Gantt chart or at the bottom of the Gantt chart by using a data value for the vertical position and a percentage value for the horizontal position.
If the horizontal and vertical coordinates are both percentages, the label is displayed on every page at the specified coordinate. This feature can be used to display text that appears on every page, much like titles and footnotes, for example.
Determining the Label String
The technique for determining the label string is similar to that of determining the horizontal position.
As far as possible, the procedure attempts to use the _LABEL variable. If the _LABEL variable does not exist or its value is missing, the procedure ignores the label data observation if the observation is not linked to an activity in the Schedule data set. However, if the label is linked to an activity (either by the LABVAR variable or a value of -1 for _Y, as described previously), the procedure extracts the text string from the Schedule data set using the _LVAR variable. The _LVAR variable values are names of variables in the Schedule data set. If the _LVAR value is not missing, the text string is the value of the specified variable in the Schedule data set corresponding to the activity. If no such variable exists in the Schedule data set or if the value is missing, no label is displayed for this particular (activity, label) link.
Note that the _LABEL variable and the Schedule data set variables named by _LVAR are not restricted to be of character type. These variables can be character or numeric, formatted or unformatted. The strings are displayed using the following rules:
If the variable is of character type, the label is the character string corresponding to the given activity.
If the variable is of numeric type and formatted, the label is the formatted string.
If the variable is of numeric type and unformatted, the label is the number displayed as a string with an integer part of up to LABMAXINT= digits and a maximum of MAXDEC= decimal positions. The LABMAXINT= and MAXDEC= options are specified in the PROC GANTT statement and their default values are 16 and 2, respectively.
Optional Information
In addition to specifying the horizontal and vertical coordinates as described previously, you can also specify a relative offset from these values using the _XOFFSET and _YOFFSET variables. These are optional variables and their default values are both 0. The unit of measurement for the _XOFFSET variable is in MININTERVAL units, and the direction of increase is from left to right. The unit of measurement for the _YOFFSET variable is in barheights, and the direction of increase is from top to bottom. When labels are split, the offset variables pertain only to the first piece of the label. The positions of the remaining split pieces are determined from the positioning of the first piece. The adjusted coordinate after taking the offsets into account is what is used for the placement of the string and is known as the referenced coordinate.
You can control the color and font of the label strings using the _CLABEL and _FLABEL variables, respectively. The values for the _CLABEL variable are any valid SAS/GRAPH color names. If the _CLABEL variable does not exist or its value is missing, the value of the CTEXT= option in the CHART statement is used. The values for the _FLABEL variable are any valid SAS/GRAPH font names. If the _FLABEL variable does not exist or its value is missing, the value of the FONT= option in the CHART statement is used.
You can control the height of the label strings with the _HLABEL variable. The units of measurement are in barheights. If the _HLABEL variable does not exist or its value is missing, the default value of 1 is used.
You can specify the angle of the character baseline with respect to the horizontal in degrees using the _ALABEL variable. If the _ALABEL variable does not exist or its value is missing, the default value of 0 is used. You can specify the rotation angle of each character in the string in degrees with the _RLABEL variable. If the _RLABEL variable does not exist or its value is missing, the default value of 0 is used.
You can control the alignment of the string with the _JLABEL variable. Strings can be displayed left-justified, right-justified, or centered at the specified coordinate. By default, all strings are displayed left-justified. The valid values are L or LEFT for left justification, R or RIGHT for right justification, and C or CENTER for centered justification.
The _PAGEBRK variable gives you displaying control when the referenced coordinate of a label coincides with a pagebreak tickmark and the horizontal coordinate is measured in data values. You can specify on which of the two pages you would like the label to be displayed. The default always displays the label on the first page associated with the common tickmark except when the tickmark is the very first tickmark on the Gantt chart. Valid values are 0 (default), 1 (use first page), or 2 (use second page).
Variables in the LABELDATA= data set
The following table lists all the variables associated with the Label data set and their interpretations by the GANTT procedure. The table also lists for each variable its type, the possible values it can assume, and its default value.
Name Type Description Allowed Values Defaults _Y N y position _X N x position _LABEL C/N Label string _XVAR C Name of numeric SAS var in DATA= ds for x position _LVAR C Name of SAS var in DATA= ds for label string _XSYS C Coordinate system for _X, _XVAR DATA, DATAVAL, PCT, PCTVAL DATA _YSYS C Coordinate system for _Y DATA, DATAVAL, PCT, PCTVAL DATA _PAGEBRK N Resolve pagebreak referenced display 0, 1, 2 0 _XOFFSET N Horizontal offset in minintervals 0 _YOFFSET N Vertical offset in bar heights 0 _ALABEL N Baseline angle in degrees 0 _CLABEL C SAS/GRAPH color name CTEXT= _FLABEL C SAS/GRAPH font name FONT= _HLABEL N Height in barheights 1 _JLABEL C Justify text L, LEFT, R, RIGHT, C, CENTER L _RLABEL N Character rotation in degrees 0 LABVAR= C/N Variable linking activities to labels
|
|
Copyright © SAS Institute, Inc. All Rights Reserved.