These are design notes for the Indicator tab of the opus GUI. The goal of the indicator tab is to allow UrbanSim users to easily define, manage, share, and create indicators.

Necessary functionality

• Define new indicators (i.e. named expressions)
• Persist indicator definitions
• Import indicator definitions from elsewhere (e.g. default parcel-based indicators) ** Share indicators with others
• Define logically-grouped sets of indicators
• Run indicators over run results for some years and output the results given a reporting template
• View indicator results

Use cases

We are thinking about two broad classes of uses that the indicator tab should support.

• Scripter: The scripter has a standard set(s) of indicators that they want to create many times (e.g. for every run). For this role, it is important to support the creation and maintenance of sets of indicators. Indicators might be grouped into sets based on their function (e.g. diagnosis), domain (e.g. transportation indicators), proposed use (e.g. indicators needed for the weekly meeting), etc.
• Explorer: The explorer engages in exploratory analysis of the results. This might characterize someone who is hunting down problems in the results or who is evaluating some model. For this use case, it is important to enable rapid definition and creation of indicators; persistence and organization of the indicators is less important.

Design

Here we give an outline for a possible design for the Indicator tab based on the use cases.

The Indicator tab XML is broken into four sections representing the persistent objects:

• Indicator libraries: Primitives to be used in indicator definitions. Libraries can include inherited indicators for the employed model (e.g. parcel/gridcell), indicators defined by the user (personal), and indicators imported from other project team members (shared).
• Indicator sets: Groups of primitives that have been parameterized into a computable expression. A set can be coupled with a result template to create a batch of indicators to create.
• Result templates: Named configuration information for the indicator batch including cache directory (should really be a named run), report template (how output is formatted), and years.
• Results: Exploration of all the created indicators. Every indicator includes indicator name, date, and the result template it was generated with.

There are also a number of actions that can be performed (tabs can be defined as necessary):

• Import indicator library: Indicator libraries can be obtained from multiple sources (e.g. standard template for parcel-based application). The import feature allows adding of additional libraries, and sharing of these libraries amongst people.
• Define indicator. Allows the definition and naming of an indicator expression. This will then be added to the user's personal indicator library.
• Create result template. Allows the definition of a result template (see above)
• Create indicator using.... Creates the indicator or indicators in an indicator set using the information in a given result template.
• View result as.... Visualize the indicator using a table/map/chart. It may launch external programs such as Post-GIS or pop up a table widget in the right-hand pane to view a table.

Example

Details

These are some details that need to be taken into account.

Indicator Libraries / Import library

• The libraries are an index of primitives that can be used in full indicator specifications. This came out of a discussion about how the imports are organized--they might be categorized by their source (parent, shared, personal) or target dataset.
• Should imports be copies or references?
• We need to consider at what level imports work and what their syntax is like. We've discussed so far that we probably want some kind of fine-grained control of importation of indicators in order to facilitate sharing amongst teammates over long periods. We think that a python like syntax--e.g. from psrc.larry.indicators.libraries import population--would best facilitate importation. This might be represented in the GUI with a file navigation drop down menu that also reads in available indicators. Users can select individual indicators living in a file or just import them all.
  • Alan has defined syntax for implementing this, where the location of the import determines which part of the parent's tree is grafted to the child's:

<item type="scenario" name="grandchild_scenario">

<item name="parent" type="dictionary" parser_action="parent_external">
  <item name="name" type="string">test_scenario</item>
  <item name="path" type="file">childconfig.xml</item>
</item>

<item name="description" type="string">this is the grandchild</item>

</item>

General

• General design decision about what information is stored on the left and what is brought up in tabs in the right pane
• We should start to aggregate information about indicators in the model-specific project files

Indicator Sets

• Primitives become indicators via parameterization with a dataset etc. Some primitives can only be associated with a subset of available datasets.

Result templates

• All results will be treated as being a report of some kind. The default "report" will be something very close to the IndicatorResults? page that we have now.
• Presumably, users won't be typing in cache_directories, but rather the names of runs.

Results / View results as…

• As a first step, computed indicators are all displayed at the same time, non-hierarchically. They are identified by indicator name, date of creation, and result template.

• We envision allowing users to be able to right click on an image and select "view result as...". A dialog box then allows them to choose a visualization option (e.g. map, table, chart) and their specific visualization options. ** First step to get Tables, Maps (loaded through ArcGIS), and Charts visualized

Action items

• Separate intermediate computation from visualization in indicator computation
  • Store intermediate results of indicator computations (need unique identifier as well)
  • Visualize intermediate result
  • Store indicator definition as XMLconfiguration
• Add TableWidget? view for viewing indicator results as indicator
• Convert indicator results to reporting framework
• Integrate result tab into GUI

AZ-smart-demo-instructions