Computing an Indicator

We have now run the simulation, so let's explore the results. UrbanSim supports the concept of ``indicators'' that are useful representations of dataset attributes. Conceptually, an indicator is a dataset attribute that is presented in a useful manner, such as a map, comma-separated-value file, or a tab-delimited file for use by another program.

First, let's produce a simple map (don't get too excited, it is only an image map - we're working on fancier maps with ArcGIS and other systems too, but this is a quick visualizer that doesn't have all the overhead of a GIS).

1. In your command window, make sure you are in the eugene\tools directory. Then type the following command to open a tool that will allow us to specify and then view an indicator:

   python create_indicator.py
   

2. In the ``Cache directory'' field, enter the location of the cache directory created by the simulation, e.g. C:\urbansim_cache\ run_2006_11_15_15_12. This will be a directory in the output directory you specified when starting the simulation.

3. Leave the ``Compare to another cache directory'' unchecked. This option lets you compare results from two different simulations.

4. Select ``Matplotlib map'' from Type drop down menu. You can see there are currently 4 other indicator types available: Comma-separated table, Tab-separated table, Chart, and Dbf export. We'll try tab-delimited table in a moment.

5. In the ``Attribute'' field, enter:

   urbansim.gridcell.population
   

   This entry contains the ``Opus path'' for a variable that shows the population within each gridcell. More specifically, this Opus path specifies the location of a Python file defining this gridcell : it is in the urbansim Opus package, is defined for the gridcell dataset, and is located in the Python file named population.py. You can find the directory that holds the code for the urbansim package in your workspace directory.

6. Leave the optional ``Name'' entry empty. If entered, it is used as the name for the created indicator (and also determines the filename of the resulting indicator). We'll let the program use the default name (``population'' in this case).

7. Type in ``gridcell'' in the ``Dataset'' entry. This is consistent with the attribute we're going to create indicator for.

8. Type in 1982 in the ``Year(s)'' entry. Leave the optional Scale entry as it is.

9. Press ``Run Request'' to generate this indicator.

10. The tool will then compute the indicators. When the ``View results'' button becomes active, it means the computation has finished. Press this button. A web browser will be launched and page loaded with a link to the requested indicator.

11. Click on the ``1982'' link to see the map. This simple map was produced by matplotlib, a Python graphing and mapping package. More sophisticated maps can be generated by importing the data into other tools, such as ArcMap.

12. Now let's produce a tab-delimited file for a different attribute. Switch back to the indictors interface, change the ``Type'' to ``Tab-delimited table'', and change the ``Attribute'' field to be:

    urbansim.zone.residential_units
    

    (Note that zone refers to a traffic analysis zone.)

13. Type in ``zone'' for the ``Dataset'' field and a single year for which you want to generate the data (e.g. 1981 or 1982) in the ``Year(s)'' entry, and press ``Run request'' to generate the data.

14. When the ``View results'' button is active again, press it to take you to the resulting web page which will now also contain a link to the tab file. In Windows, the default viewer for a tab file is often Excel, which will open your file automatically when you click on the link in this web page. Alternatively, you can of course load it into any software package that can read an ASCII, tab-delimited file -- even a text editor.

15. Just for fun, change the selection in the tool from ``Tab-delimited table (*.tab)'' to ``Matplotlib map (*.png)'', and run the indicator again. Note that the map is a gridcell map but shows the data by traffic analysis zone. The map shows ``jaggies'' because of the resolution of the gridcells (150 x 150 meters) at this scale.

    See http://www.urbansim.org/wiki/external/index.php/Indicators for a partial list of indicators that are known to work on the Eugene-Springfield data. Also, note that maps only work for indicators associated with a geography. In the case of Eugene, this includes indicators for gridcell and zone. You cannot, for instance, create a map for urbansim.household.is_minority, since household is not a geography. You can, however, define and use a variable that links this information with a geography, such as done by urbansim.gridcell.number_of_minority_households.

16. Press ``Close'' to exit this tool.

Note that you can examine any of the data in the urbansim_cache by using these indicator tools. You can also export the data for any year to a MySQL database, or to tab-delimited or comma separated ASCII files to be able to explore them in other software systems. If you want to export the cache data, either from the base year database or from the simulation output, change directory to the eugene\tools directory and run one of the three tools we have provided for this purpose to export the output in the format you prefer:

python export_cache_to_mysql.py

python export_cache_to_tab.py

python export_cache_to_csv.py

These tools open a simple tool, which at this point you should be able to figure out from the preceding parts of the tutorial. If you are uncertain about the function of an edit window, click on its label for a bit of help. Enjoy!