GMAP Procedure

PRISM Statement

Creates three-dimensional prism maps in which levels of magnitude of the specified response variables are represented by polyhedrons (raised polygons) of varying height, pattern, and color.
Requirement: At least one response variable is required. You must use the ID statement in conjunction with the PRISM statement.
Global statements: FOOTNOTE , NOTE, LEGEND, PATTERN, TITLE

Syntax

PRISM response-variable(s) </ option(s)>;

Summary of Optional Arguments

Appearance options
specifies a data set to annotate onto the maps that are produced by the PRISM statement.
fills empty map areas in the specified color.
outlines empty map areas in the specified color.
outlines nonempty map areas in the specified color.
stretches map extents to cover all available space in the device.
causes the same legend and coloring to be used for all maps produced by the procedure instead of being calculated within each BY group for each map.
specifies the width, in pixels, of all map area outlines.
specify the coordinates of the imaginary light source in the map coordinate system.
specify the dimensions of the map that you are drawing.
specify the viewing position coordinates for the map.
Description options
specifies a description of the output.
specifies the name of the GRSEG catalog entry and the name of the graphics output file, if one is created.
Legend options
specifies the LEGEND definition to associate with the map.
suppresses the legend.
Mapping options
specifies that a different map pattern be used for the surface of each map area or group of map areas on the map.
generates a separate response level (color and surface pattern) for each different value of the formatted response variable.
specifies the number of response levels to be graphed for the response variable.
specifies the response levels for the range of response values that are represented by each level (prism height, pattern, and color combination).
accepts a missing value as a valid level for the response variable.
causes GMAP to collect all response values (or their statistic) and chart each region as a percentage of the whole.
creates area heights that are relative to a zero value.
overrides the GMAP default format for percent of PERCENT8.2.
specifies the statistic for GMAP to chart.
ODS options
identifies the variable in the input data set whose values create links.
identifies the variable in the input data set whose values create links or data tips or both.
specifies a character variable whose values are URLs.

Required Argument

response-variable(s)
specifies one or more variables in the response data set. Each response variable produces a separate map. All variables must be in the input data set. Multiple response variables are separated with blanks.
Missing values for the response variable are not considered valid unless you use the MISSING option.
Response variables can be either numeric or character. By default, and as determined by the LEVELS= or MIDPOINTS= values, numeric response variables are grouped into ranges, or response levels. Each response level is assigned a different prism height and a different pattern and color combination. With the LEVELS=ALL option, numeric or character response variables are assigned unique response levels, as are numeric variables when the DISCRETE option is specified. The LEVELS=number-of-response-levels option is ignored when either the DISCRETE or the MIDPOINTS= option is used.

Optional Arguments

Options in a PRISM statement affect all of the graphs that are produced by that statement. You can specify as many options as you want and list them in any order.

ANNOTATE=Annotate-data-set
specifies a data set to annotate onto the maps that are produced by the PRISM statement. Annotate coordinate systems 1, 2, 7, and 8 are not valid with Prism maps.
Alias:ANNO=
AREA=n| column-name
specifies that a different map pattern be used for the surface of each map area or group of map areas on the map.
You can specify pattern fills or colors or both with PATTERN statements that specify map and plot patterns. A separate PATTERN definition is needed for each specified area.
AREA=n
The value of n indicates which variable in the ID statement determines the groups that are distinguished by a surface pattern. By default, all map unit areas are drawn using the same surface fill pattern. If your ID statement has only one map area identification variable, then use AREA=1 to indicate that each map area surface uses a different pattern. If you have more than one variable in your ID statement, then use n to indicate the position of the variable that defines groups that share a pattern. When you use the AREA= option, the map data set should be sorted in order of the variables in the ID statement.
AREA=column-name
A column name defined in either the MAP= or DATA= data sets can be indicated with the column-name value. If the column name exists in both the MAP= and DATA= data sets, the column in the map= data set is used. When column-name is used, the areas are colored based on the AREA= value. Duplicate AREA= values might have different patterns assigned
Note:The AREA statement provides a greater amount of control than the AREA= option.
CDEFAULT=empty-area-fill-color
fills empty map areas in the specified color. This option affects only map areas that are empty. Empty map areas are generated in prism maps only when there is no response value for a map area and the MISSING option is not used. They are also generated when a map area is omitted from the response data set and the ALL option is included in the PROC GMAP statement.
The default is NONE, which draws the polygon empty, showing the background in the fill area of the polygon.
Alias:CDEF=, DEFCLR=
Restriction:Not supported by Java
See:The CEMPTY option, the ALL, and Displaying Map Areas and Response Data
CEMPTY=empty-area-outline-color
outlines empty map areas in the specified color. Empty map areas are generated in prism maps either
  • when there is no response value for a map area and the MISSING option is not used, or
  • when a map area is omitted from the response data set and the ALL option is included in the PROC GMAP statement.
The default outline color is the same as the default COUTLINE= color.
Alias:CE=
Restriction:Not supported by Java
COUTLINE=area-outline-color | SAME
outlines nonempty map areas in the specified color. SAME specifies that the outline color of a map area is the same as the interior pattern color.
The default outline color is determined by the current style. If you specified the NOGSTYLE system option, then the default color is the first color in the color list.
Alias:CO=
Note:If you specify empty map patterns (VALUE=EMPTY in a PATTERN statement), you should not change the outline color from the default value SAME to a single color. Otherwise, all the outlines are one color and you cannot distinguish between the empty areas. Empty block patterns (VALUE=EMPTY in a PATTERN statement) are not supported by DEVICE=JAVA.
CTEXT=text-color
specifies a color for the text in the legend. If you omit the CTEXT= option, a color specification is searched for in this order:
  • the CTEXT= option in a GOPTIONS statement.
  • the default, the text color that is specified in the current style.
  • If you specified the NOGSTYLE system option, then the default color is black for Java and ActiveX and the first color in the color list for all other devices.
The CTEXT= color specification is overridden if you also use the COLOR= suboption of a LABEL= or VALUE= option in a LEGEND definition assigned to the map legend. The COLOR= suboption determines the color of the legend label or the color of the legend value descriptions, respectively.
Alias:CT=
DESCRIPTION='description'
specifies a description of the output. The maximum length for description is 256 characters. The description does not appear in the output. The descriptive text is shown in each of the following:
  • the chart description for Web output (depending on the device driver). See Chart Descriptions for Web Presentations for more information.
  • the Table of Contents that is generated when you use the CONTENTS= option on an ODS HTML statement, assuming that the output is generated while the contents page is open.
  • the description and the properties for the output in the Results window.
  • the description and properties for the catalog entry in the Explorer.
  • the Description field of the PROC GREPLAY window.
The description can include the #BYLINE, #BYVAL, and #BYVAR substitution options, which work as they do when used on TITLE, FOOTNOTE, and NOTE statements. Refer to Substituting BY Line Values in a Text String. The 256-character limit applies before the substitution takes place for these options. Thus, if in the SAS program the entry-description text exceeds 256 characters, it is truncated to 256 characters, and then the substitution is performed.
Alias:DES=
Default:PRISM MAP OF variable-name
DISCRETE
generates a separate response level (color and surface pattern) for each different value of the formatted response variable. The LEVELS=number-of-response-levels option is ignored when you use the DISCRETE option.
If you specify the DISCRETE option, then distinct, non-continuous colors are used for the response values. If you specify the LEVELS= option, then a color ramp is used to assign each response value a continuous color scheme.
Note:If the data does not contain a value in a particular range of the format, that formatted range is not displayed in the legend.
HTML=variable
identifies the variable in the input data set whose values create links or data tips or both. The variable values are either links or data tips or both that are created in the HTML file generated by the ODS statement. The links are URLs pointing to Web pages to display when the user clicks (drills down) on elements in the graph. Data tips are detailed information or data values that are displayed as pop-up text when a mouse pointer is positioned over elements in the graph.
HTML_LEGEND=variable
identifies the variable in the input data set whose values create links. Input data set variable values create links that are associated with a legend value and point to the URL to display when the user clicks (drills down) on the value. .
Restriction:Not supported by Java and ActiveX
LEGEND=LEGEND<1...99>
specifies the LEGEND definition to associate with the map. LEGEND= is ignored if the specified LEGEND definition is not currently in effect. In the GMAP procedure, the PRISM statement produces a legend unless you use the NOLEGEND option. If you use the SHAPE= option in a LEGEND statement, only the value BAR is valid. Most of the LEGEND options described in LEGEND Statement are supported by both Java and ActiveX. If a LEGEND option is not supported by Java or ActiveX, it is noted in the LEGEND option definition.
Restriction:Partially supported by Java and ActiveX
LEVELS=number-of-response-levels | ALL
specifies the number of response levels to be graphed for the response variable. If you specify LEVELS=ALL then all unique numeric or character response variable values are graphed.
Each response level is assigned a different surface pattern and color combination. The prism height is based on the data value of the corresponding response variable.
If you specify the LEVELS= option, then a color ramp is used to assign each response value a continuous color scheme. The response values are assigned lighter and darker values of a color scheme to express lower and higher response values. If you specify the DISCRETE option, then distinct, non-continuous colors are used for the response values.
If neither the LEVELS= option nor the DISCRETE option is used, then the GMAP procedure determines the number of response levels by using the formula FLOOR(1+3.3 log(n)), where n is the number of response variable values.
By default, an equal-distribution (quantizing) algorithm is used to determine each level.
When MIDPOINTS=OLD is used with the LEVELS= option, default midpoints are generated using the Nelder algorithm (Applied Statistics 25:94–7, 1976).
Restriction:The LEVELS=number-of-response-levels option is ignored when you use the DISCRETE or MIDPOINTS=value-list option. It is also ignored when the response variables are character.
MIDPOINTS=value-list | OLD
specifies the response levels for the range of response values that are represented by each level (prism height, pattern, and color combination).
For numeric response variables, value-list is either an explicit list of values, or a starting and an ending value with an interval increment, or a combination of both forms:
  • n <...n>
  • n TO n <BY increment>
  • n <...n> TO n <BY increment > n <...n>
By default the increment value is 1. You can specify discrete numeric values in any order. In all forms, n can be separated by blanks or commas. For example, midpoints=(2 4 6) midpoints=(2,4,6) midpoints=(2 to 10 by 2)
If a numeric variable has an associated format, the specified values must be the unformatted values. With numeric response values, DEVICE=JAVA uses only midpoints that fall in the range of the data being used. Thus, if your data ranged from 30–80, but midpoints were specified at 25, 50, 75,and 100, only 50 and 75 are used.
For character response variables, value-list has this form:
  • 'value-1' <...'value-n'>
The values are character strings enclosed in single quotation marks and separated by blanks, as shown here: midpoints="Midwest" "Northeast" "Northwest"
Specify the values in any order. If a character variable has an associated format, the specified values must be the formatted values. Character response values specified with the MIDPOINTS= option are not supported by DEVICE=JAVA.
You can selectively exclude some response variable values from the map, as shown here: midpoints="Midwest"
Only those observations for which the response variable exactly matches one of the values listed in the MIDPOINTS= option are shown on the map. As a result, observations might be inadvertently excluded if values in the list are misspelled or if the case does not match exactly.
Specifying MIDPOINTS=OLD generates default midpoints using the Nelder algorithm (Applied Statistics 25:94–7, 1976).
Restriction:Partially supported by Java
See:The RANGE option
MISSING
accepts a missing value as a valid level for the response variable.
NAME='name'
specifies the name of the GRSEG catalog entry and the name of the graphics output file, if one is created. The name can be up to 256 characters long, but the GRSEG name is truncated to eight characters. Uppercase characters are converted to lowercase, and periods are converted to underscores. The default GRSEG name is GMAP. If the name duplicates an existing name, then SAS/GRAPH adds a number to the name to create a unique name (for example, GMAP1).
If the name specified is exactly eight characters long, then the last character of the image output filename is replaced with a number. For example, myimages is changed to myimage1.
NOLEGEND
suppresses the legend.
PERCENT
causes GMAP to collect all response values (or their statistic) and chart each region as a percentage of the whole. You can use the STATISTIC= option to change how the percentage is calculated—whether as a percentage of the SUM, FREQUENCY, or MEAN. If you do not use the STATISTIC= option, then STATISTIC=FIRST is assumed and the response variable of only the first observation of each region is counted. If the response variable is a text field, then STATISTIC=FREQUENCY is used, even if you specify a different value for the STATISTIC= option.
RANGE
causes GMAP to display, in the legend, the starting value and ending value of the range around each midpoint specified with the MIDPOINTS= option (instead of displaying just the midpoints). For example, if MIDPOINTS=15 25 35, then the legend could show 10-20, 20-30, 30-40.
Restriction:MIDPOINTS= must be specified for the RANGE option to have any effect. Not supported by ActiveX.
RELZERO
creates area heights that are relative to a zero value. By default, GMAP creates heights that are relative to the minimum value, which might or might not be zero. With the RELZERO option, zero value areas have no height.
Alias:REL0, RELATIVETOZERO
Restrictions:This option works only for variables that have no negative values.

Not supported by Java

STATFMT=format-specification
overrides the GMAP default format for percent of PERCENT8.2. Use this format when using calculated values. The STATFMT option is typically used when the STATISTIC=FREQUENCY option or the PERCENT option is used.
Alias:SFMT=, SFORMAT=, STATFORMAT=
STATISTIC=FIRST | SUM | FREQUENCY | MEAN
specifies the statistic for GMAP to chart. For character variables, FREQUENCY is the only allowed value—any other value is changed to FREQUENCY and a warning is issued. The frequency of a variable does not include missing values unless the MISSING option is specified.
FIRST
GMAP matches the first observation from the DATA= data set and charts the response value from this observation only. This is the default. If more rows exist that are not processed, a warning is issued to the log.
SUM
All observations matching a given ID value are added together and the summed value is charted.
FREQUENCY
A count of all rows with nonmissing values is charted unless you specify the MISSING option.
MEAN
All observations matching a given ID value are added together and then divided by the number of nonmissing observations matched. This value is then charted unless you specify the MISSING option.
Alias:STAT=
STRETCH
stretches map extents to cover all available space in the device. This might cause the map to be distorted. When this option is applied to the PROC GMAP statement, it applies to all statements. If applied to a single statement, it applies only to that statement.
Alias:STRETCHTOFIT, STR2FIT
Restriction:Not supported by Java and ActiveX
UNIFORM
causes the same legend and coloring to be used for all maps produced by the procedure instead of being calculated within each BY group for each map. The UNIFORM option prescans the data to generate a categorization across all the data, regardless of BY grouping, and applies that categorization to all maps in the BY group. This results in a static legend and color distribution across all maps such that a single value always has the same color in multiple maps.
When specified on a PROC GMAP statement, the UNIFORM option applies to all AREA, BLOCK, CHORO, and PRISM statements included within the GMAP run-group.
When omitted from the PROC GMAP statement, and specified on an individual AREA, BLOCK, CHORO, or PRISM statement, the UNIFORM option applies only to the maps produced by that statement.
Restriction:Not supported by Java
URL=character-variable
specifies a character variable whose values are URLs. The variable values are URLs for Web pages to display when the user clicks (drills down) on elements in the graph.
Restriction: This option affects graphics output that is created through the ODS HTML destination only.
Interaction:If you specify both the HTML= and the URL= options, then the URL= option is ignored.

Example: GIF Output with Drill-Down Links

WOUTLINE=area-outline-width
specifies the width, in pixels, of all map area outlines.
Default:1
XLIGHT=x
YLIGHT=y
specify the coordinates of the imaginary light source in the map coordinate system. The position of the light source affects how the sides of the map polygons are shaded. Although you can specify any point for the light source using the XLIGHT= and YLIGHT= options, the light source is actually placed in one of only four positions.
Light Source Coordinates shows how the point that you specify is positioned.
Light Source Coordinates
Specified light source
Light source position
In quadrants I or II, or on the X or +Y axis
Behind the map (point A), and all side polygons are shadowed
On or within approximately 10 degrees of the Y axis
The viewing position (point D), and none of the side polygons are shadowed
In quadrant III (except within 10 degrees of the Y axis)
To the left of the map (point B), and the right-facing sides of polygons are shadowed
In quadrant IV (except within 10 degrees of the Y axis)
To the right of the map (point C), and the left-facing side polygons are shadowed
Coordinates of Imagined Light Source in a Map Coordinate System illustrates the light source positions. Assume that your viewing position, selected by the XVIEW=, YVIEW=, and ZVIEW= options, is point D.
Coordinates of Imagined Light Source in a Map Coordinate System
Coordinates of Imagined Light Source in a Map Coordinate System
By default, the light source position is the same as the viewing position specified by the XVIEW=, YVIEW=, and ZVIEW= options. The light source position cannot coincide with the viewing reference point (0.5,0.5), which corresponds with the position directly above the center of the map.
Restriction:Not supported by Java and ActiveX
XSIZE=map-width <units>
YSIZE=map-height <units>
specify the dimensions of the map that you are drawing. By default, the map uses the entire procedure output area.
Valid units are CELLS (character cells), CM (centimeters), IN (inches), or PCT (percentage of the graphics output area). The default unit is CELLS.
If you specify values for map-width and map height that are greater than the dimensions of the procedure output area, the map is drawn using the default size. If you specify one value and not the other, the dimension is adjusted to maintain the correct aspect ratio.
Restriction:Not supported by Java and ActiveX
XVIEW=x
YVIEW=y
ZVIEW=z
specify the viewing position coordinates for the map. In this system, the four corners of the map lie on the X–Y plane at coordinates (0, 0, 0), (0, 1, 0), (1, 1, 0), and (1, 0, 0).
The viewing position cannot coincide with the viewing reference point at coordinates (0.5, 0.5, 0).
The value for z cannot be negative.
If you omit the XVIEW=, YVIEW=, and ZVIEW= options, the default coordinates are (0.5, −2,3). This viewing position is well above and to the south of the center of the map. One, two, or all three view coordinates can be specified; any that are not specified are assigned the default values.
Viewing Position and Viewing Reference Point shows the position of the viewing reference point, as well as the default viewing position.
To ensure that the polygon edges are distinguishable, the angle from vertical must be less than or equal to 45 degrees. If you specify such a small ZVIEW= value that this condition cannot be satisfied, then PROC GMAP increases the ZVIEW= value automatically so that the angle is 45 degrees or less. Although you can use the XVIEW= and YVIEW= options with DEVICE=JAVA, ZVIEW= cannot be used with DEVICE=JAVA.
Alias:XV=, YV=, ZV=
Restriction:Partially supported by Java

Details

Description

The PRISM statement specifies the variable or variables that contain the data that are represented on the map by raised map areas. This statement automatically performs the following operations:
  • determines the midpoints ranges or midpoints
  • assigns patterns to the map areas
You can use statement options to control the ranges of the response values, specify the angle of view, and enhance the appearance of the map.
In addition, you can use global statements to modify the map area patterns and the legend, as well as add titles and footnotes to the map. You can also use an Annotate data set to enhance the map.
Note: PRISM maps do not work well with polygons within polygons (holes). It is recommended that a CHORO or BLOCK map be created for these maps instead.