POLYGONAL INDEX Statement

The POLYGONAL INDEX statement creates, replaces, modifies, or deletes polygonal index data sets by using a libref and polygonal index references from a spatial entry. Polygonal indexes delineate enclosed areas in the spatial data by noting the chains that form polygons. This statement is also used to compute the enclosed areas, the centroid coordinates, and the perimeter lengths of the individual polygons.

The spatial database must include a polygonal index data set for each feature type that you intend to represent as an area layer in the map. For example, to represent states and counties as enclosed areas, you must have separate polygonal indexes for each.

The POLYGONAL INDEX statement uses composite values from the current spatial entry to determine area boundaries. The composites that are used for polygonal indexes must have the CLASS attribute AREA (or one of the political subdivision area classes such as COUNTRY, STATE, or COUNTY that imply AREA by default).

Polygonal index definitions are stored in the currently specified spatial entry. An error occurs if you submit a POLYGONAL INDEX statement when no spatial entry is currently selected.

Note:   You can use the SPATIAL CONTENTS statement to view the polygonal index definitions for a spatial entry.  

In a POLYGONAL INDEX statement, the operation is one of the following:

• CREATE

• DELETE

• REPLACE

• UPDATE.

The following sections contain descriptions of the POLYGONAL INDEX statement operations.

CREATE Operation

CREATE creates a polygonal index data set and stores the polygonal index definition in the current spatial entry.

A warning is issued and processing of the current RUN group is halted if either a polygonal index definition or a SAS data set with the specified names already exist. The POLYGONAL INDEX CREATE statement does not overwrite existing index definitions or data sets. Use POLYGONAL INDEX REPLACE to replace an existing index definition or data set.

For a POLYGONAL INDEX CREATE statement, you must specify both the COMPOSITE= and OUT= arguments.

DELETE Operation

DELETE removes the specified polygonal index definition from the spatial entry. By default, the POLYGONAL INDEX DELETE statement also deletes the associated index data set. You can use the KEEP option to prevent the index data set from being deleted.

KEEP is the only additional argument (other than the polygonal index name) that can be used with this operation. A warning is issued and processing of the current RUN group is halted if the specified polygonal index does not exist.

For DELETE, you can also specify the special value _ALL_ for the polygonal-index argument to delete all the polygonal index definitions in the current spatial entry.

CAUTION:

Use DELETE with care.

The GIS procedure does not prompt you to verify the request before deleting an existing polygonal index. Be especially careful when you use the _ALL_.  

REPLACE Operation

REPLACE overwrites the polygonal index definition in the current spatial entry or creates a new polygonal index definition if the specified index does not exist.

For a POLYGONAL INDEX REPLACE statement, you must specify both the COMPOSITE= and OUT= arguments.

Note:   If the data set that is specified in the OUT= argument already exists and belongs to a different spatial entry, you must specify the FORCE argument to cause it to be overwritten.  

UPDATE Operation

UPDATE modifies only the specified characteristics for an existing polygonal index.

A warning is issued and processing of the current RUN group is halted if there is no existing polygonal index with the specified name.

Note:   If the data set that is specified in the OUT= argument already exists and belongs to a different spatial entry, you must specify the FORCE argument to cause it to be overwritten.  

Polygonal-Index Name Argument

In a POLYGONAL INDEX statement, the polygonal-index argument names the polygonal index you want to create, delete, replace, or update.

The polygonal-index value must conform to the rules for SAS names:

• The name can be no more than 32 characters long.

• The first character must be a letter or underscore (_). Subsequent characters can be letters, numeric digits, or underscores. Blanks are not permitted.

• Mixed-case names are honored for presentation purposes. However, because any comparison of names is not case-sensitive, you cannot have two names that differ only in case (for example, State and STATE are read as the same name).

When you specify CREATE, REPLACE, or UPDATE for the operation in a POLYGONAL INDEX statement, you can specify the following additional arguments following the polygonal index name.

• AREA

• CENTROID < = GEOMETRIC | VISUAL >

• COMPOSITE

• ERRORS

• FORCE

• KEEP

• OUT

When you specify DELETE for the operation keyword, only the following option is allowed:

• KEEP.

Note:   Separate the list of arguments from the polygonal index name with a slash (/).  

The following sections contain descriptions of optional POLYGONAL INDEX statement arguments.

AREA Argument

AREA calculates the enclosed areas and perimeter lengths for the lowest-level area composite that is specified on the COMPOSITE= argument. The calculated area is added to the polygonal index data set in a variable named AREA. A label for the AREA variable contains the storage area units. The calculated perimeter is added to the polygonal index data set in a variable named PERIMETER. A label for the PERIMETER variable contains the units.

CENTROID Argument

CENTROID=GEOMETRIC

returns the actual calculated centroids, which might not fall within the boundaries of their corresponding polygons. The coordinates are added to the polygonal index data set in variables that are named CTRX and CTRY. Labels for the CTRX and CTRY variables contain the storage projection units and indicate that this is a GEOMETRIC centroid. Specifying the CENTROID argument by itself returns the same results as specifying CENTROID=GEOMETRIC.

CENTROID=VISUAL

returns adjusted centroids that fall within the boundaries of their corresponding polygons. The coordinates are added to the polygonal index data set in variables that are named CTRX and CTRY. Labels on the CTRX and CTRY variables contain the storage projection units and indicate that this is a VISUAL centroid.

COMPOSITE= Argument

COMPOSITE= specifies the composite or list of composites that define the boundaries of the enclosed polygonal areas that are used to create the index. If the composite-name list consists of a single composite, you can omit the parentheses. An error occurs if any of the specified composites are not defined in the current spatial entry or if any do not have the CLASS attribute of AREA.

Note:   The COMPOSITE= argument is required when you use the CREATE or REPLACE operation.  

ERRORS Argument

ERRORS specifies whether messages about any topological errors that are detected while the index is being constructed are written to the SAS log. A polygon boundary consists of a single chain with the same starting and ending point, or multiple chains that form a closed boundary. A closed polygon boundary must start and end at the same point. A topology error occurs when the polygon is not closed. You can specify the ERRORS argument with no added parameter to print all topological error messages, or you can add the =number parameter to specify the maximum number of topological error messages that will be written to the log.

FORCE Argument

FORCE indicates that an existing polygonal index data set that is specified in the OUT= argument can be overwritten, even if it belongs to a different spatial entry. If you omit this option, the data set is not replaced and a warning is issued.

KEEP Argument

KEEP specifies that polygonal index data sets are to be retained when the index definition is removed from the spatial entry. This option is valid only with the DELETE operation.

OUT= Argument

OUT= names the index data set that you want to create, replace, or update.

Note:   The OUT= argument is required when you use the CREATE or REPLACE operation.  

CAUTION:

Do not use host commands to move or rename polygonal index data sets.

Because the polygonal index data set names are stored in GISSPA entries, moving or renaming a polygonal index data set breaks the association between the GISSPA entry and the data set. To prevent breaking the association, use the PROC GIS MOVE statement with the CHECKPARENT option instead of a host command.   

The following code fragment builds a polygonal index data set that is named GMAPS.STATEX. The data set identifies the boundaries of the polygons for the area feature that is identified by the STATE composite in the current spatial entry:

polygonal index create state / composite=state
                               out=gmaps.statex;
run;

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