Writing Indicator Documentation

Documentation on an individual indicator is contained in an XML file, to make it convenient to browse to the indicator documentation on the web.

These XML files go in the opus_docs project, in the directory opus_docs/docs/indicators. The new indicator should also be added to the predefined_indicators.xml file in an appropriate category. (At the moment we don't support having multiple indicator directories, e.g. for specific applications of UrbanSim, but we will probably add this in the future.)

The indicator documentation is linked from http://www.urbansim.org/. There is also a link to a web page, ``Reading Indicator Documentation,'' which briefly describes each section of the indicator documentation. It is intended for people who are reading the documentation (as opposed to writing it). Each section of the documentation for an individual indicator also includes a link to the corresponding section of the ``Reading Indicator Documentation'' web page.

The technical documentation for each indicator should be relatively neutral. There is also an experimental Indicator Perspectives framework, which allows different organizations to present their perspectives on which indicators are important and how to interpret them. Support for this may be added to UrbanSim 4 in the future. The mechanism is outlined in the following paper: Alan Borning, Batya Friedman, Janet Davis, and Peyina Lin, ``Informing Public Deliberation: Value Sensitive Design of Indicators for a Large-Scale Urban Simulation,'' Proceedings of the 9th European Conference on Computer Supported Cooperative Work, Paris, September 2005. (Available from http://www.urbansim.org/papers/.)

The technical documentation for each indicator includes a definition, related indicators, limitations, and other information. The web display also includes links to the Opus variable or primary attribute for that indicator.

Required elements in the XML are marked as required; if these are missing a note in red (such as ``specification missing'') will appear in the rendered web page. Other elements are optional; if omitted the heading will still appear in the rendered web page, with an appropriate note. The DTD file that formally specifies the syntax of an XML indicator definition is indicator-declaration.dtd; the file indicators.xsl specifies how the indicator is rendered on a web page when browsing.

Definition

(required) A short, accurate definition of this indicator. In the rendered web page, this appears directly under the indicator name (there isn't a separate heading ``definition'').

Principal Uses

What are the principal uses of this indicator? (This element should say whether the indicator is useful for policy evaluation, or mostly diagnostic. An indicator is useful for policy evaluation if it is useful in evaluating whether particular policy goals are supported or not by different scenarios. An indicator is useful for diagnosis if it has a clear directionality given different test input scenarios.)

Interpreting Results

Describes how to interpret the results from this indicator, either from a diagnostic perspective, a policy perspective, or both.

Display Format

(Appears as ``Units of Measurement and Precision'') This section provides a machine-readable specification of the default display for the indicator data. Since it is machine-readable, it must use a set of XML elements, rather than being free-form English text. The first element should specify the units used, e.g. <units>square feet</units> or <units>persons/acre</units>. If the data is unitless then this element should be <unitless/> (this would be the case for ratios, e.g. a vacancy rate). The next element should specify how numbers should be displayed, and how many decimal places of precision should be used. The options here are <numberdigits="N"/>, <percentage digits="N"/>, or <scientific digits="N"/>, where N in each case is the number of digits. For percentages, this is the number of digits after the decimal place, so that if N=2 the value 0.08352222 would displayed as 8.35%.

Specification

(required) A human-readable specification of how the indicator can be computed. This is not necessarily the same as how it is actually computed.

Limitations

Known limitations or problems.

Related Indicators

A short discussion of related indicators. If this indicator could be computed as the composite of other indicators, list them here, and describe the relation (see ``Jobs per capita'' for an example). Another example of using this category is in the ``Employment density'', ``Household density'', and ``Population density'' indicators, which all show different aspects of density. However, if this indicator is just related to others in its category, by virtue of being in that category, then that information can probably be safely omitted.

How Modeled

This element should describe whether the value of this indicator is determined by the interactions of UrbanSim's component models, or whether it is exogenous (that is, is determined outside the operation of UrbanSim). In some cases, the value of the indicator will be exogenous for the regional geography, but not for sub-regional geographies. If this element is omitted, the default output is ``Not specified. (In this case, normally one can assume that the value of this indicator is modeled by UrbanSim itself, as opposed to being exogenous, that is, coming from an external source such as a control total.)''

Indicator Source, Evolution, and Examples of Use

Where did the definition and code for this indicator come from? How has its specification evolved? If known, provide examples of using this indicator (including citations).

Source

This element gives a link to the source code for the indicator if it is defined as an Opus variable. If it is a primary attribute, the attribute should be listed (with no link), followed by ``Opus primary attribute'' in parentheses. (See for example the documentation for ``Residential units''.)