Chapter Contents
Previous
Next
|
Chapter Contents |
Previous |
Next |
| SAS/AF Software: Class Dictionary |
A map object uses individual map areas (or markers placed on these areas) to convey up to four different pieces of information:
Methods that return the exact value of each area allow you to write complete applications using the Map object as an interface tool. When a specific map area is selected, SCL code can be invoked to display graphs or generate reports based on the selection.
| Parts of a Map |
In area maps, the color of each map area represents a response value for that area. If the area has no response value, it uses the default map color. By default the map color is blue. You can use the mapColor attribute or the _setColor method to change the map color.
In marker maps, all map areas are the same color; only the marker color changes.
| About Map Types |
The Map control produces two types of maps: area maps and marker maps.
| About Area Maps |
Area maps are two-dimensional maps that display data by coloring the individual map areas according to the associated data values. For example, you can display data like this sales data for selected European countries:
ID NAME VOLUME REVENUE -- ---- ------ ------- 350 France 10 25000 394 Germany 100 250000 830 Spain 25 100000 925 UK 25 50000 480 Italy 75 150000
On an area map of Europe where revenue is mapped to color, countries with the highest revenue values would be green and those with the lowest revenue values would be red, if the default RANGE entry is used.
Area maps are similar to the maps produced by the CHORO statement of the GMAP procedure in SAS/GRAPH software.
| About Marker Maps |
Marker maps display the values of one to three variables as graphical symbols whose size, color, and label represent the data values. In the example of sales in Europe, the color of the marker could represent the volume of sales, and the size of the marker could represent sales revenue. In this case, tall green bars would indicate high sales volume and revenue; tall red bars would indicate a country that has low sales, but has high revenue from those sales. In most cases, the color and size variables should be related or the map may be confusing.
| Sources of Information |
The map object uses information from three SAS data sets:
In addition, it uses the IDMATCH Info dialog to obtain data from the user and a color RANGE entry to define the colors that are associated with the ranges of response values.
| About Map Data Sets |
A map data set contains coordinates that define the boundaries of map areas, such as states or counties. Institute supplied map data sets are stored in a library that is usually assigned the libref MAPS.
A map data set must contain these variables:
The following is an observation from the MAPS.US map data set. Notice that the ID variable is named STATE.
Single Observation from MAPS.US Map Data Set
STATE X Y ----- ------- ------- 23 0.31618 0.14411
You must specify a map data set. If the map data set is the only input to the map object, then the result is a simple marker map. In this case, all markers placed on such a map will use the default marker color and all be the same size because they have no response values.
| About Response Data Sets |
The response data set provides the data that you want the map to display, such as sales figures, population statistics, or income ranges.
The response data set must contain these variables:
The response identification variable links the response values with the corresponding map areas and must match the IDMATCH variable in the marker data set. It may also match the ID variable in the map data set.
Although referred to as the ID variable, this variable can have any name and can be either numeric or character. Character variables have a maximum length of 40.
The following is an example of an observation from a response data set.
Single Observation from a Response Data Set
FIPS STORES AVGSALES ---- ------ -------- 23 15 250000
The response variable assigned to the colorVariable attribute affects the color of the markers on a marker map or of the map areas on an area map. This variable must be numeric. Each value is compared to the ranges specified in the color RANGE entry. The markers will be the color specified for the particular range that the value fits into. For example, you could assign the AVGSALES variable to the colorVariable attribute.
The response variable assigned to the sizeVariable attribute affects the height or width of the markers. This variable must be numeric. For example, you could assign the STORES variable to the sizeVariable attribute.
The response variable assigned to the labelVariable attribute contains the text displayed at the base of the markers or on the map area in area maps. This variable can be either numeric or character.
A variable must be assigned to either the sizeVariable or colorVariable attribute for the response data to be used.
| About Marker Data Sets |
The marker data set is a standard SAS data set that determines or records the position of the markers on the map. It also serves to link the map and response data sets when they do not share an identification variable.
The marker data set contains these four variables:
A marker data set can be temporary or permanent.
Each observation in the marker data set specifies the location (X and Y) of a marker and its ID and IDMATCH values. The marker ID value must match the map ID value of the area where the marker is placed. The IDMATCH value must match the response ID value, which may also be the same as the map ID.
The following is an example of an observation from a Marker data set.
Single Observation from a Marker Data Set
X Y ID IDMATCH ------- ------- -- ------- 0.31618 0.14411 23 23
Notice that in this example the value of the IDMATCH variable, which comes from the response data set, is the same as the ID value, which comes from the map data set.
| Creating a Marker Data Set |
You can create a marker data set from a SAS session or interactively from within the map object. Once you have created a marker data set you can assign it to the map object with the markerDataSetName or markerDataSetID attributes.
To create a marker data set in a SAS session, use a DATA step or FSEDIT to enter the X and Y location, the map identification value of each marker, and the IDMATCH variable. You can use map data sets like MAPS.USCENTER to obtain the X and Y locations for the center of each state as well as the state's ID value. You must supply the values for the IDMATCH variable. These values must correspond to the identification values in the response data set.
You can also create a marker data set interactively when your map data set and response data set have different identification values and you do not already have a marker data set. In this case the map object automatically enters values in a marker data set as you add markers to the map.
These are the steps:
By default it saves the marker data set as WORK.DATAn. To create a permanent data set enter a libref and data set name for the markerDataSetName attribute, and then save the frame.
Another way to create a marker data set of locations and IDMATCH values is to simply specify a map data set and a marker data set but no response data set. Place the markers on the map at the locations you plan to use and enter the IDMATCH value in the IDMATCH Info dialog.
Note: The map object automatically assigns the type of the IDMATCH variable
so that it is the same type as the map identification variable. Therefore,
your IDMATCH values must be the same type as the map ID values. ![[cautionend]](../common/images/cautend.gif)
| Saving the Marker Data Set |
While you are in BUILD mode, the map object saves the current marker
information to the marker data set whenever you save the frame (
File -->
Save), open the Property sheet, or exit the frame. When the application
is running, you can save the marker data set at any time with the _saveAs
method.
You can save the default marker data set WORK.DATAn as a permanent data set in one of these ways:
libname mylib 'pathname'; data mylib.marker1; set work.data1; run;
map._saveAs('mylib.marker1');
| About the IDMATCH Info Dialog |
The IDMATCH Info dialog allows you to enter the value of the response ID variable that corresponds to the currently selected map area.
Numeric ID response value
Character ID response valueYou are prompted to enter either a numeric or character value depending on the data sets already assigned to the map object. The map object assigns a type to the IDMATCH variable. It looks for the following variables and assigns the type of the first one it finds:
Use this window to interactively build a marker data set by dragging a marker on a map area and entering the IDMATCH value for that area in the window.
| About the Color RANGE Entry |
The color RANGE entry determines which color is assigned to the response value that is represented by color. These colors appear either on the map areas (in area maps) or as the marker color (in marker maps).
By default the response values are divided into three ranges and each range is assigned a color: values in the lowest third are red, values in the middle third are yellow, and values in the highest third are green.
You can define your own color ranges by creating a color RANGE entry and assigning it to the map object's colorRange attribute.
| How the Data Sets Work Together |
If the identification variables in the map data set and response data set contain the same values, then the link between the two is direct. The example below shows a response data set containing sales data for three states and uses FIPS codes to identify the states Maine (23), New Hampshire (33), and Vermont (50).
The example below also shows representative observations from the corresponding map data set, MAPS.US. MAPS.US also uses FIPS codes in a variable named STATE to identify each state.
Response Data Set and Map Data Set with Matching ID Values
Response Data Set Map Data Set (MAPS.US) ========================== ============================= FIPS STORES AVGSALES STATE X Y ---- ------ -------- ----- ------- ------- 23 15 250000 23 0.31618 0.14411 33 8 450000 23 0.31572 0.14427 50 10 350000 [...] 33 0.31618 0.14411 33 0.31596 0.13988 [...] 50 0.29623 0.13249 50 0.29067 0.13122
When the identification variables match, as they do here, you can link the two data sets directly by specifying STATE as the ID variable for the map data set and FIPS as the ID variable for the response data set. In this case, when the map object builds the marker data set it automatically uses STATE as the ID variable and FIPS as the IDMATCH variable, as shown below. So long as the two variables contain the same values, it doesn't matter if they are named the same or not.
Marker Data Set with Matching ID Values
X Y ID IDMATCH ------- ------- -- ------- 0.32609 0.18508 23 23 0.33324 0.14181 33 33 0.28606 0.16714 50 50
However, the identification values in the response data set may be different from those in the map data set. For example, if the response ID value contains the names of cities instead of FIPS codes, the map and response ID values do not match. In this case, you must specify the city names as IDMATCH values, so the map object can use the ID and IDMATCH variables in the marker data set to build the link between the map and response data sets, as shown below.
Marker Data Set with Different ID Values
Map Data Set Marker Data Set Response Data Set ============ =============== ================ STATE ID IDMATCH OFFICE AVGSALES ----- -- ------- ------ -------- 23 23 'Portland' 'Portland' 250000 33 33 'Dover' 'Dover' 450000 50 50 'Burlington' 'Burlington' 350000
If you place a marker on Maine (FIPS code 23) the marker data set associates 23 with 'Portland' and displays the response data for Portland on the map.
| Creating a Map Object |
This section describes the steps for creating a simple map object and displaying response data. Because the steps depends on whether the response data set contains an ID variable that matches the ID variable in MAPS.AUSTRAL, there are two versions of the process. Both versions use the map data set of Australia, MAPS.AUSTRAL, which contains information for these map areas:
| Area Name | Identification Value (ID) |
|---|---|
| NORTHERN TERRITORY | 1 |
| NEW SOUTH WALES | 2 |
| QUEENSLAND | 3 |
| SOUTH AUSTRALIA | 4 |
| TASMANIA | 5 |
| VICTORIA | 6 |
| WESTERN AUSTRALIA | 7 |
Each version uses a different response data set. If you want to create these maps, you must first create the response data sets on your own system.
| Version 1: Map ID and Response ID Match |
The response data set MYLIB.AUSREV shown below contains an ID variable that matches in type and content the ID variable in the map data set.
Response Data Set MYLIB.AUSREV
ID NAME VOLUME REVENUE -- ---- ------ ------- 1 NORTHERN TERRITORY 10 25000 2 NEW SOUTH WALES 100 250000 4 SOUTH AUSTRALIA 25 100000 5 TASMANIA 25 50000 6 VICTORIA 75 150000
Note that not all map areas have data.
| Attribute | Value |
| mapDataSetName | Maps.Austral |
| mapIDVariable | ID |
| mapType | Marker (the default) |
| Attribute | Value |
| responseDataSetName | Mylib.Ausrev |
| responseIDVariable | ID |
| sizeVariable | Volume |
| colorVariable | Revenue |
| labelVariable | Name |
| Version 2: Map ID and Response ID Do Not Match |
The response data set MYLIB.AUSCITY shown below has an ID variable that does not match the ID variable in the map data set.
Response Data Set MYLIB.AUSCITY
OFFICE VOLUME REVENUE ------ ------ ------- DARWIN 10 25000 SYDNEY 100 250000 ADELAIDE 25 100000 MELBOURNE 75 150000
OFFICE, which contains the city names, is the ID variable.
| Attribute | Value |
| mapDataSetName | Maps.Austral |
| mapIDVariable | ID |
| mapType | Marker (the default) |
| Attribute | Value |
| responseDataSetName | Mylib.Auscity |
| responseIDVariable | Office |
| sizeVariable | Volume |
| colorVariable | Revenue |
| labelVariable | Office |
| IDQuery | On |
The marker for Melbourne appears, sized, colored, and labeled accordingly.
Note: Because you are making the connection for the marker data set,
you can assign any response value you like to the IDMATCH variable. Descriptionce
the marker is created you can drag it to any area of the map and either change
its IDMATCH value when the IDMATCH Info dialog opens or select OK to keep
it.
| Using Legends |
A map object can display two types of legends, a color legend that is displayed as a color bar, and a size legend that is displayed as a wedge.
The color bar represents the values of the color variable or the values of the color RANGE entry. By default the legend displays the minimum and maximum values of the color variable. If you assign a RANGE entry, the legend displays the minimum and maximum values defined by the RANGE entry. The legend title is the color variable's label, if it has one, or the variable name. The color bar appears on the legend for both area maps and marker maps.
The wedge-shaped size symbol shows the minimum and maximum values from the size variable. The legend title is the size variable's label, if it has one, or the variable name. The size symbol appears on the legend for marker maps only.
You can control and manage the two legends separately. On maps that support both legend types, you can display either legend or both legends.
| Attribute | Description |
| colorLegendState | determines whether the color legend is displayed. Valid values are On and Off. |
| sizeLegendState | determines whether the size legend is displayed. Valid values are On and Off. |
For a map object named map1, the following code displays both legends:
map1.colorLegendState='on'; map1.sizeLegendState='on';
Both legends are interactive in the object; you can move them or change their size. As you change the legend's size, legend information is hidden if it cannot fit within the legend. For example, if you make the legend too narrow to display the title, the title is hidden.
To move the legend, click on the middle of the legend, and then drag the legend to the desired location within the object's border. To change the legend's size, click just inside the legend border that you want to size, and then enlarge or reduce the size. For example, to make the legend taller, click on the legend's top border and drag the border up.
You can also move and size the object through its size and location attributes:
| Attribute | Description |
| colorLegendXSize | width of the color legend, measured as a percent of the object region |
| colorLegendYSize | height of the color legend, measured as a percent of the the object region |
| colorLegendXLoc | X location of the top left corner of the color legend, measured as a percent of the object region |
| colorLegendYLoc | Y location of the top left corner of the color legend, mesaured as a percent of the object region |
| sizeLegendXSize | width of the size legend, measured as a percent of the object region |
| sizeLegendYSize | height of the size legend, measured as a percent of the object region |
| sizeLegendXLoc | X location of the top left corner of the size legend, measured as a percent of the object region |
| sizeLegendYLoc | Y location of the top left corner of the size legend, measured as a percent of the object region |
In SCL code, you can use the _getValue method to determine whether a legend has been clicked on and what variable the legend represents. The method arguments are:
| Argument | What it returns |
| ON_LEGEND | 0 if no legend was clicked 1 if the color legend was clicked 2 if the size legend was clicked |
| LEGEND_VARIABLE | label of the variable represented by the clicked legend |
For an object named map1, the following SCL code shows how _getValue works. If you compile and test the code, you can click on either of the legends or on the map, and then look in the Log window to see the information returned by the put statements.
init:
/* assume map1 is an existing marker map */
map1.colorLegendState='on';
map1.sizeLegendState='on';
return;
main:
length legvar $32;
x= 0;
leg = 0;
infolist = makelist();
map1._getValue(infolist);
x= getnitemn(infolist,'MAP_X',1,1);
leg = getnitemn(infolist,'ON_LEGEND',1,1);
legvar = getnitemc(infolist,'LEGEND_VARIABLE',1,1);
put 'you clicked on ' x ;
put ' A legend? ' leg;
put ' which is for ' legvar;
rc = dellist(infolist);
return;
term:
return;
|
Chapter Contents |
Previous |
Next |
 Top of Page |
Copyright 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.