3.3. Runing the Test Cases for Using Scripts
Scripts are provided for Unix users to exercise most of the major functions of the software. If you cd into the scripts directory, all of the scripts should run without any editing. However, if you wish to run any of the scripts without first cd-ing into the scripts directory, edit the SA_HOME setting for all of the scripts in the directory (e.g., generate_surrogates.csh, compare_surrogates.csh) to
specify the full path to your installation folder.
A set of example scripts is provided with the software to assist users with getting started using the system. These example scripts are provided only to serve as examples - the user is responsible for providing actual input data for his/her application and customizing the scripts accordingly. The example scripts generate a set of surrogates for an 8-km grid over Nashville, Tennessee. The input files for the examples are available from the Spatial Allocator Download Site. These files were derived from files available from the EPA ftp://ftp.epa.gov/EmisInventory/emiss_shp2003/. Some of the files are used as is, while others are extracted for Tennessee from the larger national data sets due to their size. The only file that was not from this web site is the cnty_tn shapefile that contains the polygons for the counties of Tennessee. This file was obtained from an independent source of county data.
The following surrogates are generated in the examples:
- Airports
- Land Area
- Ports
- Navigable Water
- Major Highways
- Housing
- Population
NOTE that these are examples only and should not be considered a complete set of surrogates with which to do emissions modeling!
However, a complete set of input files to reproduce EPA's 66 surrogates using the Surrogate Tool is available
with the Surrogate Tool distribution.
The following are a few test scripts included in the release:
Generate Emission Spatial Surrogates from Shapefiles and Compare to Reference Surrogates
- To test the basic operation of the surrogate creation program (i.e., generating surrogates for point, line, and polygon datasets), run the generate_surrogates.csh script. This will generate a set of test surrogates in the output directory, in addition to some gridded shapefiles that can be viewed in a GIS tool. Note that some warnings will be generated for counties on the edge of the grid since some of their surrogates will not sum to 1.
- Run the compare_surrogates.csh script to compare your surrogates with the reference surrogates. Note that compare_surrogates uses the diffsurr.exe utility to compare two sets of surrogates with respect to a specified tolerance. You may find the diffsurr.exe utility useful, for example, when you are creating new surrogates and would like to compare them to the previous versions. Diffsurr takes its arguments from the command line. An example of its usage follows; note that 3 is the numeric ID for the surrogates in the two files (i.e., both surrogates are numbered 3 in this case), although that may not always be true.
diffsurr.exe ../data/srg_nash_ref.txt 3 ../output/my_srgs.txt 3 0.00001
- Examine the outputs of the program in the output directory.
- The surrogate file (srg_M08_NASH.txt) includes comments preceded by a ! on each line that contains a surrogate fraction. Each comment shows the surrogate numerator and denominator that were used to compute the fraction, and a running sum of the surrogate fractions for that county. For counties entirely within the grid, the sum should be 1; for other counties, the sum should not exceed 1.
- Since the OUTPUT_FILE_NAME variable was specified for each surrogate created with the generate_surrogates script, shapefiles were created that contain the sum of the surrogate fraction numerators for each grid cell. The names of these files start with grid (e.g., grid_airpt_M08_NASH.shp), and they are in the map projection of the output grid.
A corresponding .csv file is also created that just contains the row, column, and sum for the grid cell. There will be quite a few zeros in these files because only data for Tennessee was processed. For the airports surrogate, many additional grid cells will be zero because many cells do not contain airports.
Generate a Filtered Surrogate
- To see how to generate a filtered surrogate, run the filtered_surrogate.csh script. Examine the outputs that start with filtered_pop and filtered_srg in the output directory to see the files that it created. Also, to understand what filter was applied, examine the file filter_tn_pop.txt in the data directory. For additional examples of filters, look in the testsuite/filters directory.
Generate a Surrogate Using a Weight Function
- To see how to generate a surrogate using a weight function, run the weighted_surrogate.csh script. Examine the outputs that start with weighted_ in the output directory to see the files that it created. Also, to understand what weight was applied, look for the WEIGHT_FUNCTION line in the weighted_surrogates script. Also note that the ATTR_WEIGHT is set to USE_FUNCTION.
Change Map Projection of a Shapefile
- To see how to change the map projection of a Shapefile using the CONVERT_SHAPE mode of the allocator program run the convert_input_shape.csh script as follows:
convert_input_shape.csh ../data/tn_ports ../output/tn_ports_ll
The new tn_ports_ll file will have coordinates in a latitude-longitude map projection. The tn_ports_ll file should be easily visualizable by GIS tools. Note that the ports gridded shapefile will not have a nonzero value in each grid cell that has a port because BERTHS was used as the weight and many ports in the weight file have a value of 0 for the BERTHS attribute. To make all grid cells with ports nonzero, use NONE as the value for the WEIGHT_ATTR_LIST when creating the ports surrogate.
- (Optional) If you require a mapping tool for shapefiles (e.g., for quality assurance of surrogates), you may want to consider ArcExplorer by ESRI, which is downloadable for free from the ESRI web site (http://www.esri.com).
Filter a Shapefile
- To see how to filter a shapefile using the FILTER_SHAPE mode of the allocator program, run the filter_shapefile.csh script. Examine the outputs that start with filtered_ in the output directory to see the files that it created. Also, to understand what filter was applied, examine the file county_filter.txt in the data directory.
Convert Files
- To convert any DBF file to a .csv file, go to the $SA_HOME/bin directory and type:
dbf2asc.exe ../data/input_DBF_file ../output/output_csv_file
Generate BELD3 Data for Biogenic Emissions Processing and Compare Two I/O API Files
- To see how to create inputs to SMOKE biogenic emissions processing run the script convert_beld3.csh. This script runs the program beld3smk.exe. The BELD3 data for the Tennessee area is provided in the /data/beld directory. After running convert_beld3.csh, run the script compare_beld3.csh. This script runs the diffioapi utility to compare the outputs to a reference data set and confirm that the results are the same.
Allocation data attributes from a grid, polygon, or point file to an output grid or polygon file
To Section 3.3: Environment Variables Used by the Software
