Chapter Contents
Previous
Next
Using Spatial Data with SAS/GIS Software

SPATIAL Statement

SPATIAL <operation> <libref.catalog.>spatial-entry </ options>;

The SPATIAL statement

Description

A spatial entry is a SAS catalog entry of type GISSPA that defines the components of a SAS/GIS spatial database. The definition specifies which SAS data sets contain spatial information, how the data sets are related, and what roles the variables play.

Any composites, polygonal indexes, and lattice hierarchies that are created or updated during an invocation of the GIS procedure are stored in the current spatial entry. Any subsequent COVERAGE statements that are issued within the PROC GIS step subset the data in the current spatial entry.

No additional arguments (other than the spatial entry name) are used when the operation keyword is omitted. An error occurs if there is no existing spatial entry that has the specified name.

Note:   When creating or replacing spatial entries, you can either define entirely new spatial entries or merge two or more existing spatial entries.  [cautionend]

SPATIAL Statement Operations

In a SPATIAL statement, the operation argument can be one of the following:

Note:   If you omit the operation keyword, the SPATIAL statement makes the specified spatial entry the current spatial entry for subsequent operations. No SPATIAL statement options can be used in a spatial assignment statement.  [cautionend]

The following list contains descriptions of the SPATIAL statement operations:

CONTENTS
Prints information about the specified spatial entry to the Output window, including:

No additional arguments (other than the spatial entry name) are used with this operation. An error occurs if the specified spatial entry does not exist.

Note:   The specified spatial entry does not become the current spatial entry for subsequent operations unless no spatial entry is currently selected.  [cautionend]

CREATE
Generates a new spatial entry in which subsequent composites, polygonal index names, and lattice hierarchies that are specified in the GIS procedure are stored. The new spatial entry becomes the current spatial entry for subsequent operations.

An error occurs if a spatial entry with the specified name already exists. The SPATIAL CREATE statement does not overwrite existing spatial entries. Use SPATIAL REPLACE to replace an existing entry.

For a SPATIAL CREATE statement, you must also specify both the CHAINS= and NODES= arguments or the MERGE= argument.

DELETE
Deletes the specified spatial entry. By default, any polygonal index data sets that are referred to in the spatial entry are also deleted. The chains, nodes, or details data sets that are referred to in the spatial entry are not deleted. To retain existing polygonal index data sets when the spatial entry is deleted, use the KEEP argument in the SPATIAL DELETE statement.

KEEP is the only additional argument (other than the spatial entry name) that can be used with this operation. An error occurs if the specified spatial entry does not exist.

Note:   For the DELETE operation, you can also specify the special value _ALL_ for the spatial entry name argument to delete all spatial entries in the current catalog.  [cautionend]

CAUTION:
Use the DELETE operation with care. The GIS procedure does not prompt you to verify the request before deleting the spatial entry. Be especially careful when you use the _ALL_ keyword.  [cautionend]

REPLACE
Overwrites the specified spatial entry or creates a new entry if an entry with the specified name does not exist. The specified spatial entry becomes the current spatial entry for subsequent operations. The SPATIAL REPLACE statement has the effect of canceling all previously issued SPATIAL CREATE, COMPOSITE, POLYGONAL INDEX, and LATTICE statements for the specified spatial entry.

For the SPATIAL REPLACE statement, you must specify both the CHAINS= and NODES= arguments or the MERGE= argument.

UPDATE
Modifies the specified spatial entry by applying new values for specified arguments. The updated spatial entry becomes the current spatial entry for the subsequent operations.

An error occurs if there is no existing spatial entry with the specified name.


Spatial-Entry Name

In a SPATIAL statement, the spatial entry name argument identifies the GISSPA-type entry that you want to create, replace, update, delete, or make the current spatial entry. The general form of the argument is

<libref.catalog.>spatial-entry

CAUTION:
Do not use host commands to move or rename SAS data sets that are referenced in GISSPA entries. Moving or renaming a data set that is referred to in a spatial entry breaks the association between the spatial 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.  [cautionend]

SPATIAL Statement Optional Arguments

When you specify CREATE, REPLACE, or UPDATE for the operation keyword, you can specify one or more of the following optional arguments after the spatial entry name.

Note:   Separate the list of arguments from the spatial entry name with a slash (/).  [cautionend]

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

The following list contains descriptions of the optional SPATIAL statement arguments:

CARTESIAN | LATLON
Specifies the coordinate system that is used in the stored spatial data.

CARTESIAN
Data are in an arbitrary rectangular (plane) coordinate system

LATLON
Data are in a geographic (spherical) coordinate system.

The default is LATLON.

Note:   The CARTESIAN and LATLON arguments are ignored when the MERGE= argument is used.  [cautionend]

CHAINS=data-set
Names the SAS data set that contains chain definitions for the spatial database. A chain is one or more line segments that connect one node (or point on the map) to another. For example, a series of chains can represent a railroad or a river.

Note:   The CHAINS= argument is required when you use the CREATE or REPLACE keyword and do not specify the MERGE= argument.  [cautionend]

DEGREES | RADIANS | SECONDS
Specifies the coordinate units for the stored spatial data when the coordinate system is geographic (LATLON). The default is RADIANS.

Note:   This argument is ignored when the CARTESIAN or MERGE= arguments are used.  [cautionend]

DETAILS=data-set
Names the SAS data set that contains detail definitions for the spatial database. Details are the points at angle breaks in chains. They provide a finer granularity for the chain's line segments. A data set that contains detail definitions might describe the curvy outline of a coastal road.

EAST | WEST
Specifies the hemisphere in which the spatial data points lie. The default is EAST. EAST refers to points east of the Prime Meridian (0 degrees) at Greenwich, England, while WEST refers to points west of the Prime Meridian.

If the data are in the Western Hemisphere, longitude values (the X coordinates) are negative, that is -35° 45' 08". If your data are in the Western Hemisphere but have positive longitudes, your map is displayed flipped or with the east and west directions reversed. See Preparing Spatial Data for an example of this behavior. Applying the WEST argument to the spatial data causes the longitudes to be negated when the data are read in, and the map is displayed correctly.

Note:   This argument is ignored when the CARTESIAN or MERGE= arguments are used.  [cautionend]

KEEP
Specifies that polygonal index data sets are not deleted when the spatial entry is deleted. This option is valid only with the DELETE operation.

MERGE=(<libref.catalog.>spatial-entry-1<, ..., <libref.catalog.>spatial-entry-n>)
Lets you build a new spatial entry by referencing two or more existing spatial entries. The dependent data sets for the spatial entries are not actually combined when you use the MERGE argument; the new spatial entry includes them by reference. An error occurs if any of the specified spatial entries do not exist.

You can specify either of the following additional arguments in conjunction with the MERGE= argument:

EDGEMATCH <LINKONLY>
Matches common boundaries between the merged spatial entries. Missing values along common boundary chains are filled in where possible by using values from the adjoining spatial data sets. The affected chains data sets are rewritten unless the LINKONLY option is specified, and you cannot reverse the operation.

OVERLAP
Merges spatial entries without attempting to match boundaries. The chains data sets for the merged entries are not rewritten. This is the default behavior.

MULT=multiplier-value
Specifies a constant value by which the stored spatial data coordinates were multiplied. The default is MULT=1.

Note:   This argument is ignored when the MERGE= argument is used.  [cautionend]

NODES=data-set
Names the SAS data set that contains node definitions for the spatial database. A node is a point on the map, usually representing the intersection of latitude and longitude positions. For example, a node can represent the intersection of two streets.

Note:   The NODES= argument is required when you use the CREATE or REPLACE keyword and do not specify the MERGE= argument.  [cautionend]

NORTH | SOUTH
Indicates the hemisphere in which the spatial data points lie. The default is NORTH.

If the data are in the southern hemisphere, latitude values (the Y coordinates) are negative, for example, -45° 12' 33". If your data are in the southern hemisphere, but the latitude values are positive, your map is displayed inverted with the east and west directions reversed. Applying the SOUTH argument to the spatial data causes the latitude values to be negated when the data is read in, and the map is displayed with the correct side up.

Note:   This argument is ignored when the CARTESIAN or MERGE= arguments are used.  [cautionend]

DESCRIPTION='string'
Specifies a descriptive phrase, up to 256 characters long, that is stored in the description field of the spatial entry. The default description is blank.

SPATIAL Statement Examples

Define the current spatial entry

The following code fragment makes MAPS.NC.NC.GISSPA the current spatial entry that is used for subsequent operations: 

proc gis cat=maps.nc;
   spatial nc;

Update an existing spatial entry

The following code fragment replaces the existing details data set with MAPS.USAD for the existing MAPS.USA.USA.GISSPA spatial entry: 

spatial update maps.usa.usa / details=maps.usad;

Merge three existing spatial databases

The following code fragment creates a new spatial entry that is named TRIANGLE.GISSPA in the current catalog by merging three existing spatial entries, ORANGE, DURHAM, and WAKE. In this example, each of the spatial entries to be merged is stored in a different library. See Working with Spatial Data for more information on merging. 

spatial create triangle / merge=(gmap1.orange.orange,
                                 gmap2.durham.durham,
                                 gmap3.wake.wake);


Chapter Contents
Previous
Next
Top of Page

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