Chapter Contents

Previous

Next

Using the Map Class

What It Does

A map object uses the individual map areas or markers placed on these areas to convey up to four different pieces of information to the user. These pieces of information are represented by

• the location of a marker on a map area

• the color of a map area or of a marker

• the size of a marker

• the label on a map area or marker.

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

map area

an area within a map such as a country, state, or province. Each area has its own identification (ID) value. The border of a map area is defined by X and Y variables for all observations in the map data set that have the same ID value.

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 Attributes window Map tab or the _setColor method to change the map color.

In marker maps, all map areas are the same color; only the marker color changes.

marker (marker maps only)

a graphical symbol whose size and color represent response values. The size of the marker, for example the height of a bar, is determined by the value of the response variable assigned to marker size. The color of the marker is determined by the value of the response variable assigned to marker color. The marker label is also generated from response data set values. You can use either the Attributes window Response tab or the Map class methods to assign response variables to the appropriate marker characteristic.

label

the text associated with the map area or marker and displayed in conjunction with it. The text of the label is contained in the response variable assigned to the label.

legend

one or two symbols that relate map area or marker characteristics to the data:

• 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 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 size symbol appears on the legend for marker maps only.

About Map Types

The Map class produces two types of maps: marker maps and area 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 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. (See also About the Color RANGE Entry.)

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 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:

• a map data set

• a response data set

• a marker data set

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.

This section describes these sources.

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:

• a numeric variable named X containing the horizontal coordinates of the boundary points.

• a numeric variable named Y containing the vertical coordinates of the boundary points.

• an identification variable, usually named ID, that identifies the map area to which the coordinates belong. The map identification variable links the map data set and the response data set either directly, or indirectly via the marker data set. Map area identification variables can be either character or numeric.

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 be the default map color is and 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:

• at least one identification variable that identifies the map area, such as a state, a country, or a business office, to which a response value belongs. For example, in the response data set of European sales data, the response identification variable is ID, which contains the country code for each country.

  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. See also About Marker Data Sets for details.

  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.

• one or more variables with information about the map areas. These variables control the characteristics of the map:
  • marker or map area color

  • marker size

  • marker or map area label

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 color 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 color attribute.

The response variable assigned to the size attribute affects the height or width of the markers. This variable must be numeric. For example, you could assign the STORES variable to the size attribute.

The response variable assigned to the label 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 size or color 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:

• X and Y are numeric variables that contain the coordinates of the location of each marker. These variables get their values from the map data set X and Y variables.

• an identification variable named ID that matches the identification variable in the map data set in both type and content. The corresponding variable in the map data set may have a different name, such as STATE. This variable can be either numeric or character. Character variables have a maximum length of 40.

• another identification variable named IDMATCH that matches a variable in the response data set in type and content. The corresponding variable in the response data set may have a different name, such as OFFICE. This variable can be either numeric or character. Character variables have a maximum length of 40.

A marker data can be temporary or permanent and can have a maximum of 100 observations.

Each observation in the marker data set specifies the location (X and Y) of a marker and it's 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 in the Attributes window or with the _setMarkerDsname method.

To create a marker data set in a SAS session, use a DATA step or FSEDIT to enter the X and Y location and the map identification value of each marker. 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:

1. Be sure the IDMATCH Info dialog is enabled by choosing Query ID from the Attributes window Response Tab or using the _setIdQuery method.

2. Add a marker to the map. The map object copies the X, Y, and ID values from the map data set to the current observation in the marker data set.

3. When the IDMATCH Info dialog opens, enter the value of the response ID variable that corresponds to the currently selected map area. The map object assigns that value to the IDMATCH variable.

By default it saves the marker data set as WORK.DATAn. To create a permanent data set enter a libref and data set name in the Attributes window Marker Tab.

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.  

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), or open the Attributes window, 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:

• Assign a libref and use the DATA step, for example

  libname mylib 'pathname';
  
  data mylib.marker1;
  set work.data1;
  run;

• Use the SAVE_AS method from your SCL program, for example

  call notify('map', '_save_as_','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 value

specifies the value of the response ID variable that corresponds to the currently selected map area. This value is assigned to the IDMATCH variable in the current marker data set.

You 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:

1. IDMATCH in the current marker data set

2. response ID variable

3. map ID variable

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 in the Color Range field in the Attribute window or with the _setColorRange method.

To create a new range entry, enter a libref and RANGE entry name in the Color Range field and select Edit. A RANGE entry can contain up to 24 uniquely defined ranges. For more information on the RANGE Entry, see SAS\/AF Software: FRAME Application Development Concepts.

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. For example, 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.

1. In a frame, create and fill a region with a map object.

2. In the Attributes window, enter the information for the Maps tab:
   • in Map Data Set enter MAPS.AUSTRAL

   • in ID Variable enter ID

   • for Map Type select Marker (default)

3. Enter the information for the Response tab:
   • in Response Data Set enter MYLIB.AUSREV

   • in ID Variable enter ID

   • for Size Variable select VOLUME

   • for Color Variable select REVENUE

   • for Label Variable select NAME

   • Do not select Query ID.

4. Return to the Frame and use the pop-up menu to select Map Object--> Add.

5. Click an area to add a marker. If the response data set has data for the area, the marker will be sized, colored, and labeled accordingly. Otherwise it will be gray (the default marker color), indicating no data.

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.

1. See steps 1 and 2 in Version 1.

2. Enter the information in the response tab:
   • in Response Data Set enter MYLIB.AUSCITY

   • for ID Variable select OFFICE

   • for Size Variable select VOLUME

   • for Color Variable select REVENUE

   • for Label Variable select OFFICE

   • Select Query ID.

3. Return to the Frame and use the pop-up menu to select Map Object--> Add.

4. Click an area to add a marker. The IDMATCH Info dialog opens. In the window type the value of OFFICE that corresponds to the map area. For example, if the map area is Victoria, type MELBOURNE. At this point the map object assigns MELBOURNE as the value for IDMATCH; when you clicked on Victoria, it assigned the map ID value, 6, to the marker data set ID. Now the link between the map area, 6, and the response value, MELBOURNE is complete. Click OK.

   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.  
   

Chapter Contents

Previous

Next

Top of Page

Copyright 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.