SA Vector Tools Introduction

The SA Vector Tools consist of six programs to generate spatial surrogates, convert shapefiles from one map projection to another, filter (or select) shapefiles, merge surrogates, perform gap-filling of surrogates, and map data from one spatial resolution to another (e.g., from grids to counties).. The first three programs listed below are primary programs, while the other three are utility programs used for data file comparison and format conversions.

• The allocator program (allocator.exe) performs spatial computations such as filtering, overlays, map projection conversion, and conversion of data from one spatial form to another. For example, the allocator.exe can be used to map point source data to modeling grid cells or polygons, aggregate data for county polygons into state polygons, convert data from one grid to another, or create a new shapefile by specifying a filter based on any attributes of an existing shapefile.
• The surrogate creator program (srgcreate.exe) generates surrogates for point-, line-, or polygon-based weight shapefiles such as ports, airports, housing, population, agriculture, water area, and railroads. The surrogate creator tool can generate surrogates for regularly spaced air quality model grids, the WRF/NMM-CMAQ E-grids(rotated diamond shaped grids), or any modeling polygon shapes (such as census tracts) on a variety of map projections, such as Universal Transverse Mercator (UTM), Lambert Conformal, and latitude-longitude. It supports a variety of standard and user-specified ellipsoids to approximate the shape of the Earth.
• The BELD3 converter program (beld3smk.exe) converts 1-km gridded landuse data to a user-specified modeling grid, egrid, or polygons. The output of this program can be used as input to the Normbeis3 program in the SMOKE emissions model.
• The diffsurr.exe utility compares the values of two surrogates.
• The diffioapi.exe utility compares two I/O API files, checking that the files' headers and data values are consistent.
• The dbf2asc.exe utility produces an ASCII (csv) file from the DBF portion of a shapefile.

In addition, five Java-based tools for generating and processing spatial surrogates are available in the SurrogateTools.jar file. The tools provide a more user-friendly way of computing surrogates using the SA Vector Tools. The Surrogate Tools clarify how the surrogates are generated, and do not require the user to perform extensive scripting. They use comma-separated values (CVS) configuration files to compute surrogates from shapefiles, to merge together existing surrogate data, and/or to gapfil surrogates using data from other surrogates to ensure that entries are available for every single county. In addition, tools are included that provide quality assurance summary capabilities for all computed surrogates, along with a surrogate normalization program that can ensure that surrogates for every county sum to 1.0. The Surrogate Tools require Java 1.5 version or later.

More information on obtaining the programs, running example scripts for each of these programs and utilities can be found in the section entitled Using the software on the main contents page.

1.2 Project Objectives

1. Develop software that (a) reads geospatial data (polygons, lines, and points with attributes that serve as weights in latitude-longitude or projected coordinates) and a description of target polygons (possibly on a different map projection and Earth ellipsoid); (b) allocates the input data to the target polygons based on weighted spatial overlap of the input data and target polygons; and (c) outputs the results (e.g., to generate surrogates to be used as inputs to the Sparse Matrix Operator Kernel Emissions [SMOKE] modeling system)
    
2. Develop a machine-independent Java surrogate tools which calls the Spatial Allocator Vector Tool utilities internally without script files for users to compute one or more surrogates in a single run based on simple csv and text input files and summarize the computed surrogates for quality assurance.
    
3. Demonstrate the use of the spatial allocation software to prepare surface water cover, railroads, airports, and housing type information for use by SMOKE (i.e., surrogates).
    
4. Support incremental development by providing an interface that allows additional data readers and writers to be added in a reasonably simple way. The programmer's guide provides some documentation on how to develop a custom reader/writer.

1.3 Credits

The Vector Tools component of the MIMS Spatial Allocator was developed by members of the Institute for the Environment at the University of North Carolina at Chapel Hill (http://www.ie.unc.edu/), some of whom were formerly associated with MCNC. The development and continued maintenance of this software has been sponsored by the EPA Office of Research and Development. The first version of the Spatial Allocator software was developed in 2002-2003 to provide a tool for performing emission surrogate generation and other types of spatial allocation without requiring users to have a GIS. Initial releases of the software took place in March 2003 and December 2003. A project to update the tool with new features was sponsored in 2004-2005, with a first release of the updated tool in January 2005 and another release in April 2006. A training class was developed in Dec. 2008, with funding from the U.S. EPA. A complete history of revisions is available here.

This document includes instructions for the current release of the software and serves as a user's guide for the Vector Tools component of the Spatial Allocator. An older user's guide [ PDF][MS Word] is available that offers a different view of the software and was developed independently of this user's guide; it has not been updated to include any of the enhancements made during late 2005 or 2006.

To Section 2: Background on Shapefiles and Surrogates.