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.
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 "Determining the Vertical Position" section.
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 via _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 via 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 via 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).
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 via 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.
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.
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 via 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.
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 position of the remaining split pieces is 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).
The following table lists all the variables associated with the
LABELDATA= 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.
Table 4.25: Label Data Set Variables
|
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 © 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.
