Drawing and Querying the Contents of a Shapefile

Introduction
Drawing Shapefiles
Querying Shapefiles
Example
Caveat

line

Introduction
GrADS version 2.0.a8 introduces the capability to draw and query the contents of a shapefile. The shapefile format (promulgated by ESRI) stores non-topological geometry and attribute information for the spatial features in a data set. Shapefiles typically contain data related to coastlines, political boundaries, state or county boundaries, climate zones, roads, rivers, topography, etc. The geometry of each spatial feature or 'shape' is stored as a set of vector coordinates. Shapes can be points, lines, or polygons (areas). An ESRI shapefile actually consists of three files: a main file (*.shp), an index file (*.shx), and a dBASE file (*.dbf). The main file describes a set of shapes with a list of their vertices. The index file contains offsets pointing to the locations of each shape in the main file. The dBASE file contains attribute data for each shape in the main file. If you put the three shapefile components (*.shp, *.shx, and *.dbf) in the GrADS data directory (specified by the GADDIR environment variable), then it is not necessary to include the full path when referring to the shapefile.

Drawing Shapefiles
GrADS will draw the contents of a shapefile as an overlay on top of an existing plot with the command draw shp. It is necessary to draw a plot first in order to establish the dimensions and scaling of the display. Shapefiles contain 2-dimensional spatial features, so your plot must be varying in the X-Y (lon/lat) domain.

A shapefile may contain one of three kinds of graphical elements: points, lines, or polygons.

The draw shp command draws all the shapes in the shapefile by default, but it is possible to specify a single shape or a range of shapes to draw. Using these extra arguments to the draw shp command, you can control the line and color characteristics of individual shapes.

Querying Shapefiles
The GrADS shapefile interface also allows the user to discover the contents of a shapefile. The q shp command returns information about the shapes in the file (number of vertices and lon/lat bounds), and the q dbf command returns all the attribute information for each shape in the file.

The first line of the q shp output contains the shapefile type, the number of shapes in the file, and the X and Y bounds of actual extent of the shapes in the file. Subsequent lines list information about each shape element in the file: the identification number, the shape type, the number of parts, the number of vertices, and the bounds of the shape in the X, Y, Z, and M (measure) dimesions. The GrADS interface ignores the Z or M values of a shape, only it's position in X,Y (lon,lat) space is relevant.

The first line of the q dbf output contains a comma-delimited list of the names of all the attributes for each record in the database. Subsequent lines contain the comma-delimited list of all the attribute values for each record.

Please refer to the reference pages for these two commands for additional information and examples of the output.

Example
Here is an example script that shows how to use the shapefile interface to draw U.S. climate divisions colorized according to the values of the Palmer Drought Severity Index (PDSI). The script generates a plot that looks like this:

pdsi

Caveat
The ESRI Shapefile Techncial Description states that "A polygon consists of one or more rings. A ring is a connected sequence of four or more points that form a closed, non-self-intersecting loop." A polygon with two rings would look something like a flat donut -- the area between the two rings forms the interior of the polygon, and the area enclosed by the inner ring is actually in the exterior of the polygon. The GrADS interface does not draw polygons with more than one ring properly. Each ring in a polygon is handled separately; inner rings are drawn as new polygons overlapping the outer ring. If you are drawing a shapefile that contains polygons with more than one ring, and if you use the set shpopts command to draw filled polygons, then GrADS will draw both the inner and outer rings as filled polygons. In other words, your donuts will be drawn with filled holes.

The rings of a polygon are referred to as its parts, and the number of parts in each polygon is included in the ouput of the q shp command. So it is possible to discover whether this limitation is affecting your plot.