|SAS/GRAPH Software: Reference|
The BY statement processes data and orders output according to the BY group.
The BY statement divides the observations from an input data set into groups for processing. Each set of contiguous observations with the same value for a specified variable is called a BY group. A variable that defines BY groups is called a BY variable and is the variable that is specified in the BY statement. When you use a BY statement, the graphics procedure
By default, the procedure expects the observations in the input data set to be sorted in ascending order of the BY variable values.
Note: The BY statement in SAS/GRAPH is
essentially the same as the BY statement in base SAS, but the effect on the
output is different when it is used with SAS/GRAPH procedures.
by descending var1 var2;
This BY statement indicates that the input data set is sorted in descending order of both VAR1 and VAR2 values:
by descending var1 descending var2;
NOTSORTED can appear anywhere in the BY statement and affects all variables specified in the statement. NOTSORTED overrides DESCENDING if both appear in the same BY statement.
The requirement for ordering or indexing observations according to the values of BY variables is suspended when you use the NOTSORTED option. In fact, the procedure does not use an index if you specify NOTSORTED. For NOTSORTED, the procedure defines a BY group as a set of contiguous observations that have the same values for all BY variables. If observations with the same value for the BY variables are not contiguous, the procedure treats each new value it encounters as the first observation in a new BY group and will create a graph for that value, even if it is only one observation.
|Preparing Data for BY-Group Processing|
Unless you specify the NOTSORTED option, observations in the input data set must be in ascending numeric or alphabetic order. To prepare the data set, either sort it with the SORT procedure using the same BY statement that you plan to use in the target SAS/GRAPH procedure or create an appropriate index on the BY variables.
If the procedure encounters an observation is out of the proper order, it issues an error message.
If you need to group data in some other order, such as chronological order, you can still use BY-group processing. To do so, process the data so that observations are arranged in contiguous groups that have the same BY-variable values and specify the NOTSORTED option in the BY statement.
For an example of sorting the input data set, see Example 7. Using BY-group Processing to Generate a Series of Charts.
|Controlling BY Lines|
the BY statement prints a BY line above each graph that contains the variable
name followed by an equal sign and the variable value. For example, if you
specify BY SITE in the procedure, the default heading when the value of SITE
London would be SITE=London.
To suppress the entire BY line, use the
NOBYLINE option in an OPTION statement or specify HBY=0 in the GOPTIONS statement.
See Example 7. Using BY-group Processing to Generate a Series of Charts.
To suppress the variable name and the equal sign in the heading and leave only the BY value, use the LABEL statement to assign a null label ('00'X) to the BY variable. For example, this statement assigns a null label to the SITE variable:
See also Grouping and Arranging Pie Charts.
To control the color, font, and height of the BY lines, use the following graphics options in a GOPTIONS statement:
See Graphics Options and Device Parameters Dictionary for a complete description of each option.
|Naming the Catalog Entries|
The catalog entries generated with BY-group processing always use incremental naming. This means that the first entry created by the procedure uses the base name and subsequent entries increment that name. The base name is either the default entry name for the procedure (for example, GPLOT) or the name specified with the NAME= option in the action statement. Incrementing the base name automatically appends a number to each subsequent entry (for example, GPLOT1, GPLOT2, and so forth). See also Names and Descriptions of Catalog Entries and Using the default output name. For an example of incremented catalog names, see Example 9. Combining Graphs and Reports in a Web Page.
|Using the BY Statement|
This section describes the following:
For additional information on any of these topics, refer
to the appropriate chapter.
When you use BY-group processing with the GCHART procedure, you can do the following:
With the PIE and STAR statements, the effect of a BY
statement is similar to that of the GROUP= option, except that the GROUP=
option allows you to put more than one graph on a single page while the BY
statement does not. Do not use a BY variable as the group variable in STAR
or PIE statements.
By default, BY-group processing affects both the map data set and the response data set. This means that you get separate, individual output for each map area common to both data sets. For example, if the map data set REGION contains six states and the response data set contains the same six states, and you specify BY STATE in the GMAP procedure, you get six graphs with one state on each graph.
If you use the ALL option in the PROC GMAP statement
and you also use the BY statement, you get one output for each map area in
the response data set, but that output displays all the map areas in the map
data set. Only one map area per output contains response data information;
the others are empty. For example, if you create a block map using the data
sets REGION and SALES, specify BY STATE, and include the ALL option in the
PROC GMAP statement, you get six graphs with six states on each graph. One
state per graph has a block; the remaining five are empty.
You can use the UNIFORM option in
the PROC GPLOT statement to produce the same axis scaling for all graphs in
a BY group. By default, the range of the axes may vary from graph to graph,
but UNIFORM forces the scaling to be the same for all graphs generated by
If you use the BY statement with a procedure that processes data and supports RUN-group processing (the GCHART, GMAP, and GPLOT procedures), then each time you submit an action statement or a RUN statement you get a separate graph for each value of the BY variable. For example, each of these two RUN-groups produces a separate plot for every value of the BY variable SITE:
/* first run group*/ proc gplot data=sales; title1 'Sales Summary'; by site; plot sales*model_a; run; /* second run group */ plot sales*model_b; run; quit;
The BY statement stays in effect for every subsequent RUN group until you submit another BY statement or exit the procedure. Variables in subsequent BY statements replace any previous BY variables.
You can also turn off BY-group processing by submitting a null BY statement (BY;) in a RUN group, but when you do this, the null BY statement turns off BY-group processing and the RUN group generates a graph.
For more information, see RUN-Group Processing.
If a procedure that is using BY-group processing also specifies annotation with the ANNOTATE= option in the PROC statement, the same annotation is applied to every graph generated by the procedure.
If you specify annotation with the ANNOTATE= option
in the action statements for a procedure, the BY-group processing is applied
to the Annotate data set. In this way, you can customize the annotation for
the output from each BY group by including the BY variable in the Annotate
data set and by using each BY-variable value as a condition for the annotation
to be applied to the output for that value.
TITLE, FOOTNOTE, and NOTE statements
can automatically include the BY variable name, BY variable values, or BY
lines in the text they produce. To insert BY variable information into the
text strings used by these statements, use the #BYVAR, #BYVAL, and #BYLINE
substitution options. For details, see the description of the text-string argument. For
an example, see Example 7. Using BY-group Processing to Generate a Series of Charts.
Procedures that use SYMBOL or PATTERN
definitions, assign the symbols or patterns in order to each BY group. For
example, if the BY variable REGION has four values --
West -- the patterns are
assigned to the BY-groups in this order:
|PATTERN1 is assigned to
|PATTERN2 is assigned to
|PATTERN3 is assigned to
|PATTERN4 is assigned to
If you create sets of graphs from several data sets
containing the variable REGION, and if you want the same pattern assigned
to the same region each time, you must be sure that REGION always has the
same four values. Otherwise, the patterns may not be the same across graphs.
For example, if the value
North is missing from the data, the
patterns are assigned as follows:
|PATTERN1 is assigned to
|PATTERN2 is assigned to
|PATTERN3 is assigned to
In this case,
South is assigned pattern
2 instead of pattern 3 and
West is assigned pattern 3 instead
of pattern 4. To avoid this, include the value
North for the variable
REGION, but assign it a missing value for all other variables.
Top of Page
Copyright 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.