7.2. Overlaying Spatial Data

7.2.1 Modes of the Allocator Program

The allocator program supports ALLOCATE and OVERLAY modes for operating on shapefiles, point files, polygon files, I/O API files and regular grid shapefiles.

The OVERLAY mode allows the user to specify a grid, bounding box, polygon, or set of polygons and then print the attributes of the shapes (i.e., points, lines, or polygons) from an input data file that fall within the boundaries of the specified region. One example of how this mode might be used is to start with a data set from a group of observation stations in a particular region and then overlay those data with a grid to determine which grid cells the observation stations reside in. The results may be printed to standard output or saved to a delimited file. Eventually, we may also be able to save the data to a shapefile or an I/O API file.

7.2.2 Overlay Printing Mode

When MIMS_PROCESSING is set to OVERLAY (a new processing mode in version 3.0), the Spatial Allocator responds to the following environment variables (bold text indicates required fields):

• OVERLAY_TYPE – The type of the overlay shape (valid values are BoundingBox, PolygonFile, ShapeFile, and RegularGrid)
• OVERLAY_SHAPE – The shape name or information used to define a region of interest in overlays. If OVERLAY_TYPE is:
  • BoundingBox, specify as: x1,y1,x2,y2
  • RegularGrid, specify the name of a grid (when used, this requires GRIDDESC to be set)
  • ShapeFile, specify the name of a shapefile (note that the OVERLAY region is the union of all of the polygons in the shapefile)
  • PolygonFile, specify the name of an ASCII polygon file; each line of the file should contain two values with the following format: xcoord ycoord. Note that the polygon will automatically be closed, and the points should be specified in a clockwise manner so that they are not interpreted as a hole
• OVERLAY_MAP_PRJN – The map projection of the overlay shape
• OVERLAY_ELLIPSOID – The ellipsoid for the overlay shape
• OVERLAY_ATTRS – Set to ALL or a comma-separated list of attribute names for which values will be printed
• INPUT_FILE_NAME – Name of the file containing input data for spatial allocation
• INPUT_FILE_TYPE – Shapefile, PointFile, IoapiFile, or RegularGrid
• INPUT_FILE_MAP_PRJN – The map projection of the INPUT_FILE_NAME file
• INPUT_FILE_ELLIPSOID – The ellipsoid of the INPUT_FILE_NAME file
• GRIDDESC – grid description file name (only when using OVERLAY_GRID)
• INPUT_GRID_NAME – Name of input grid (when INPUT_FILE_TYPE is RegularGrid)
• INPUT_FILE_DELIM – The delimiter that is used for the PointFile (when INPUT_FILE_TYPE is PointFile)
• INPUT_FILE_XCOL – The name of the column containing x coordinates in the PointFile (when INPUT_FILE_TYPE is PointFile)
• INPUT_FILE_YCOL – The name of the column containing y coordinates in the PointFile (when INPUT_FILE_TYPE is PointFile)
• OVERLAY_OUT_TYPE – The type of output; specify either Stdout or DelimitedFile (eventually also Shapefile)
• OVERLAY_OUT_NAME – The name of the output file; specify either Stdout or a file name
• OVERLAY_OUT_DELIM – A constant that specifies the type of delimiter to use for the DelimitedFile output type (note that a PointFile is a special case of DelimitedFile – but DelimitedFile is used here because the output file does not need to be a PointFile since the shapes may not be points)
• WRITE_HEADER – Y or N (specifies whether to write a header line to give the names of the output attributes)
• DEBUG_OUTPUT –Y or N (specifies whether to write the debug output to standard output; this can be used to make the program output only critical information)

7.2.3 Overlay Mode Examples

Example overlay scripts are provided for Unix/Linux in C-shell format (.csh extension appended) These scripts can be executed directly from the scripts directory. If desired, you may edit the overlay script and set the SA_HOME environment variable to your new installation directory. The scripts place their output shapefiles in the output directory. The output files can be viewed with a GIS.

Several different overlay example scripts have been provided in order to give the reader an overview of how this new processing mode operates. The sample scripts for the overlay mode are:

• overlay_county_on_grid
• overlay_grid_on_counties
• overlay_grid_on_ports
• overlay_polygon_on_census_tracts

The overlay_grid_on_ports.csh script is presented below as an example. The OVERLAY_TYPE is a bounding box, which means that OVERLAY_SHAPE will be set to a pair of x,y coordinates instead of to a file name. In all other cases, the OVERLAY_SHAPE is a file name. The file that is being overlaid by the bounding box is a shapefile with the same map projection as the bounding box (but this need not be the case, as the allocator program will convert between map projections as needed). The overlay output is being placed in a delimited file, as specified by OVERLAY_OUT_TYPE. The delimiter will be a COMMA, as specified by OVERLAY_OUT_DELIM. Because WRITE_HEADER is set to Y (yes), the names of the OVERLAY_ATTRS — in this case, NAME, BERTHS, LAT, and LONG — will be provided on the first row of ports_over_grid.csv. The MAX_INPUT_FILE_SHAPES variable can be set to any nonzero integer value to enable data "chunking" of the input file so that it is processed piecemeal instead of all at once. This reduces memory overhead in the program. Input file chunking is handy when very large shapefiles are being processed.

# Set debug output
setenv DEBUG_OUTPUT Y

# Set executable
setenv SA_HOME ..
setenv EXE "$SA_HOME/bin/allocator.exe"

# Set Input Directory
setenv DATADIR $SA_HOME/data
setenv OUTPUT $SA_HOME/output

# Select method of spatial analysis

setenv MIMS_PROCESSING OVERLAY

setenv TIME time

setenv OVERLAY_SHAPE 1000000.0,-536000.0,1368000.0,-200000.0
setenv OVERLAY_TYPE BoundingBox
setenv OVERLAY_MAP_PRJN "+proj=lcc,+lon_0=-100.0,+lat_1=30.0,+lat_2=60.0,+lat_0=40.0"
setenv OVERLAY_ELLIPSOID "+a=6370997.00,+b=6370997.00"
setenv OVERLAY_ATTRS NAME,BERTHS,LAT,LONG
setenv INPUT_FILE_NAME $DATADIR/tn_ports
setenv INPUT_FILE_TYPE ShapeFile
setenv INPUT_FILE_ELLIPSOID "+a=6370997.00,+b=6370997.00"
setenv INPUT_FILE_MAP_PRJN "+proj=lcc,+lon_0=-100.0,+lat_1=30.0,+lat_2=60.0,+lat_0=40.0"
setenv OVERLAY_OUT_TYPE DelimitedFile
setenv OVERLAY_OUT_NAME $OUTPUT/ports_over_grid.csv
setenv OVERLAY_OUT_DELIM COMMA
setenv WRITE_HEADER Y

echo "Overlaying ports with a grid (bounding box of grid)"
$TIME $EXE

To Section 7.3: Filtering a Shapefile