Technical Tips

NOTE: Assumes a practical understanding of ArcGIS model builder

ArcGIS provides the user with a powerful capability to extending the base geoprocessing toolset with the ability to create new toolsets that can be combinations of geoprocessing models or scripts.

Most end-users create tools (models and/or scripts) to:
• Increase efficiency by removing the need to remember complex geoprocessing steps
• Increase efficiency and knowledge dissemination by providing a mechanism to share corporate knowledge amongst staff
• Increase reliability and transparency by providing a means to easily repeat key geoprocessing operations.

The concept of developing tools is not new in GIS, in fact, most corporate GIS packages provide some level of capability or support for tool development. While tool development is well established in the spatial industry, integrated documentation (both from a user and technical perspective) has not been a core feature of GIS packages. That is, until now.

With the release of ArcGIS 9.2 ESRI now provide a tool documentation paradigm that is fully integrated into the ToolBox environment with ArcGIS. This technical tip will explore some of the interesting features of this new offering.

For the purpose of this exercise we will be using an ArcGIS geoprocessing model developed by Spatial Vision to undertake slope classification and analysis for commercial forest applications.

A Model is a geoprocessing concept that uses inputs (datasets) and functions (geoprocessing action on the dataset(s) to produce outputs (datasets). In addition, models allow for parameters related to geoprocessing function or input datasets to be used as variables. The inputs, outputs, function and parameters are all model objects that can be manipulated by the end user. Models in the ArcGIS paradigm can be delivered in a graphical or script (python or VB) format.

It is possible to print the model (a set of geoprocessing objects and actions) and store this information as hardcopy or PDF, however, as an organisations custom toolset grows and/or tools are deployed as a shared resource, a more integrated approach to documentation is required.

Figure 1 - Assumes that a model has been developed for a particular purpose, in this case a geoprocess for undertaking slope classification and analysis. Most ESRI users will be familiar with this graphic layout that is available via ArcGIS's model builder paradigm.

We will look at two of the key reasons for documenting a geoprocess:
1. Communicating the concept to others - making the process less of a mystery and easing the pain for other in using your geoprocess
2. Capturing technical information on any key processes undertaken as part of project and/or programs ia a user Guide.

Finally, we will discuss how to report on the setting used in a particular instance of a model.

By way of background, it is important to remember at this point that a user can interact with a particular model in two modes: Visual and Parameter. At first viewing, these two modes appear a little disparate but from a documentation perspective it will become clear that they are inexorably linked.

• Visual Mode - right-click>Edit will "open" the model in the visual mode for editing or running

Figure 2 - Visual Mode for a Model

• Parameter Mode - right-click>Open will open the model in parameter mode. In this mode only assigned parameters can be altered - note the Help panel on the right hand-side of the dialogue box. Note: parameters are those parts of the model that are made available to the user to alter, that is they are the geoprocessing variables.

Figure 3 - Parameter Mode for a Model

1. Documentation as a Communication Device

One of the simple but powerful things that model builder provides are colour-coded process diagrams. The following three diagrams illustrate the 3 geoprocessing object types and their relationships.

Figure 4 - Visual Mode - Dark Blue = Inputs (samdem); Green = Outputs (sampdem_s); Yellow = Processes (Slope); Light Blue=parameter options or process settings (Extent and Cell Size).

In addition, a model that has variables or parameters assigned can be "viewed" in Parameter Mode. This mode lists the modal parameters for the user to interact with.

Figure 5 - Parameter Mode - The 3 parameters set above appear in the Parameter Mode.

Colour (figure 4) coding is a great start to communicating what the process might be trying to achieve. However, one of the drawbacks of initial visual display for a model is that the geoprocess objects and action names can be somewhat cryptic (see Figure 5) to those whom are less familiar with the ArcGIS functional capability or unfamiliar with a particular function. To overcome this issue, model builder allows all objects in the model to be renamed. This has two important effects:
A. Visual Mode - Makes the purpose of an object or action more explicit

Figure 6 - right-click on the object and select Rename to change the display without changing the underlying object type or function.

B. Parameter Mode - provides the user with a parameter heading that can communicate what the parameter's intended function might be. Changing the names of the geoprocessing objects changes the headings in Parameter mode.

Figure 7 - Changes made in the model editor translate to the Parameter Mode

In this simple way the visual communication represented by the Visual Mode display and Parameter Mode headings can better inform users as to the geoprocessing concept and what the key model parameters are intended to achieve.

Figure 8 - Geoprocessing Object renaming for both Visual and Parameter Modes

This level of model documentation is an effective communication device and, importantly, takes relatively little effort to achieve.

This is by no means the extent of the documentation capability provided in ArcGIS. The next section takes the communication idea to the next level and illustrates the level of technical documentation available.

2. Documentation as a User Guides

Fundamental to deployment of any tool to a 3rd party (internally or externally) is a user-centric guide to assist in navigating the tool. In the past, this usually involved creating a separate document for the end-user with screen grabs etc (much like this tech tip). A clear problem with this approach is that the documentation exists separately from the tool.

ArcGIS 9.2 has developed a solution for this issue by providing the ability to create a user guide that is part of the tool deployed.

Figure 9 - ArcGIS provides the ability to display a User Guide Panel - the basic concept being that clicking in any parameter in the Parameter Mode will provide the user with a guide as to what to do.

As per figure 9 above - our sample tool currently has no User Guide information. The next section provides an insight as to how to add information into the User Guide Panel. Documentation is added to a tool via the ArcToolbox Documentation Editor interface.

Figure 10 - Right-click on the tool to be documented and select Edit Documentation to begin the ArcToolbox Documentation Editor.

The ArcToolbox Documentation Editor is the one stop editor for documenting all aspects of the tool that you have created.

Within the ArcToolbox paradigm there are two types of "help".

a. User Guide or Dialogue Reference help - this appears in the User Guide Panel

b. Technical Guide or Command Reference help - this appears in the HTML-help that is accessed using the tool's help button

Figure 11 -ArcToolbox Documentation Editor Interface.

The Editor is made up of two main sections:

• General Information - this section is related to the User Guide Panel for the help that you are about to provide. This area is further sub-divided into 4 sub-sections:

• Abstract - generally a short paragraph on what the tool is intended to do.
• Keywords - adding keyword can provide the end-user of the deployed too the ability to use the search capability of the toolbox to locate tools.
• Author - provides the ability to add authoring information.
• Constraints - a summary of any constraints that the en-user should be aware of.

• Help - this section is primarily related to the "HTML - help" mode for ArcToolbox however this area also allows for addition of User Guide Panel information. This area is further sub-divided into 6 sub-sections:

• Summary - generally a short paragraph on what the tool is intended to do
• Illustration - this sub-section allows for the use of an image - generally assume that will use the Visual Mode model diagram but it may also be useful to add a Parameter Mode screen capture for completeness.
• Usage Tips - any key tips for the end user - for example Tool assumes a Spatial Analyst extension or Tool assumes an ArcInfo Licence
• Parameters - this is perhaps the most important sub-section as it is here that you can add documentation for both the HTML-help and Use Guide Panel. Each tool parameter (variable) that you have identified (P tag in the Visual Mode) will appear in this subsection.
• Command example - this allows the developer of the tool to provide an example of how the tool might be used as a command line function (if appropriate).
• Script example - this allows the developer to provide an example of the tool as a script in either python or VB.

Figure 12 -ArcToolbox Documentation Editor Interface - Help for Parameters.

As indicated in Figure 11, for each parameter you can add information for:
• The Command Reference - this information will appear in the HTML-help
• Dialog Reference - this information will appear in the User Guide Help panel
In the majority of cases the information can be the same in each of these; however there may be cases where you will want to add more detail in the HTML-help.

The following sections provide a set-by-set illustration of adding information to the editor and the result of that addition.

General Information
Abstract
Figure 13a -Information entered into the Abstract appears in the User Guide Panel when the tool is "opened".

Keywords

Keywords become available in the standard index / search tabs of ArcToolbox making it easy for end users to locate the tools that you have developed. To register the keywords save the current information (keywords) to the default settings as shown below.

Figure 13b - Information entered into the Keywords list will be available to the user to search on - note: the tool must be "registered" to the ArcToolbox default settings for this to be enabled.

Figure 14a - Keywords can now be used in the general search (Index and Search tabs) capability that comes with ArcToolbox - note: clicking on the locate tool will take you to the tools location.

Figure 14b

Author
Figure 15 -Information entered into the Author section provides the ability to brand the tool for future reference.

Constraints
Figure 16 -Information entered into the Constraints section provides the ability to describe any key constraints of the model.

Meta Data

An important feature of the model documentation is the recording of metadata about each tool created.

Figure 17a -All General Information will appear in the Metadata tab in ArcCatalogue for the tool.

Figure 17b

An additional option for documentation is the creation of supporting help files in HTML format. The creation and access to help will be the subject of our next Technical Tip

3. Reporting on Model Settings

Each geoprocessing object in any model created in Model Builder has specific settings for any particular run. Parameters allow the user to change setting but at all times each object has a specific setting. An important documentation function for many project is to record the specific instance of a model. ArcGIS allows this via the Model Report function available in the View Mode.

To access this function open the model in View Mode>click on the Model Menu and select Report.

Figure 18a - Creating a report on the settings for a model.

Figure 18b

4. Summary

The ArcGIS model builder represents a powerful tool for creating processes to leverage your investment in GIS. Our next tip will explore the documentation of help files.

back to top

Copyright © Spatial Vision, Tuesday, 18-December-2007