Anatomy of a tool reference page

Every tool page in the ArcGIS AllSource tool reference adheres to the same structure; understand the structure, and you'll be able to use any tool.

Summary and illustration

The Summary section includes a short description of what the tool does. It may contain links to more in-depth information about how the tool works. In some cases, the summary will be followed by an illustration that also explains what the tool does.

Usage

The Usage section contains notes and clarifications about using the tool. When the notes refer to a particular parameter, the parameter label, which appears on the tool dialog box, is used rather than the parameter name, which appears in the syntax and is used in Python. The relationship between the parameter's label and name is usually obvious, but in some cases, the name is noted to avoid confusion.

Parameters

The Parameters section is divided into two tabs: Dialog and Python.

The Dialog tab includes parameter information for using the tool in the Geoprocessing pane.

The Python tab includes information for using the tool in Python. The tab includes tool syntax; a parameter table with three columns: Name, Explanation, and Data Type; and a Code Sample section with samples that demonstrate the use of the tool in Python.

Syntax

On the Python tab, the first line below the syntax header contains the tool signature. In Python, the tool name is used instead of the tool label.

  • The tool label appears at the top of a tool dialog box.
  • In Python, arcpy is followed by the toolbox alias and the tool name, each separated by a period. For example, in Python, the Symmetrical Difference tool is identified as arcpy.analysis.SymDiff.
  • As tools in the Spatial Analyst and Image Analyst toolboxes are commonly imported from the sa and ia modules for Map Algebra, the syntax for these tools shows only the tool name.
Note:

In ArcPy, geoprocessing tools are organized in two ways. All tools are available as functions from the arcpy namespace and are also available in modules matching the toolbox alias name. Although the syntax shows the tools in the latter form, both approaches are equally valid. The approach you use will depend on personal preference and coding habits.

Tools can be accessed from modules matching the toolbox name.

arcpy.management.GetCount(in_features)

Tools can be accessed as functions on the arcpy module.

arcpy.GetCount_management(in_features)

The module name and tool name can also be identified by dragging a tool from the Geoprocessing pane to the Python window.

Parameter table

The parameter table has three columns: Label/Name, Explanation, and Data Type.

The parameter table differs depending on whether you are using the Dialog or Python tab; the Dialog tab shows the parameter label, and the descriptions are oriented toward the Geoprocessing pane, whereas the Python tab shows the parameter name, and the descriptions are oriented toward using the tool in Python.

The differences in the two parameter tables are most notable for Boolean parameters and string parameters with keywords. In the parameter dialog box, Boolean parameters are presented as check boxes and string parameters are presented as labels, whereas in Python, Boolean and string parameters both show choices as string keywords.

Note:

Parameter help that relates to usage of the tool from the tool dialog box can also be viewed by hovering over the information button Information next to each parameter.

A tool dialog box can show parameters in a different order than the actual parameter order, so in rare cases, the order of the parameters in the Geoprocessing pane may be different than the order in the parameter table. For Python, always use the order shown in the parameter table.

Parameter names versus labels

The parameter label is used on the tool's dialog box. The parameter name is for the tool in Python. The relationship between the parameter label and name is usually obvious, but in some cases, the parameter name is noted to avoid confusion.

Tool parameters can be either required or optional. Optional parameters are followed by (Optional) on the tool's dialog box.

Parameter typeDescription

Required

You must provide a value for required parameters. These parameters are always the first parameters in the command.

Optional

These parameters always follow the required parameters. If you don't provide a value for an optional parameter, the default value is calculated and used. The default value is described in the Explanation column.

Required and optional parameters

On the Python tab, additional information is shown for parameters that accept a list of values. The syntax of the list follows the parameter name as follows:

AppearanceDescription

Simple list

Simple list—Simple lists are known as multivalue parameters.

Value table

List of lists—The data type is Value Table.

Explanation

This column provides further information about what a parameter is used for and how it can be set, including keyword options.

Data Type

Every tool parameter has an associated data type. Some simple data types are string (any set of alphanumeric characters), Boolean (a true or false value), and long (an integer value between -2,147,483,648 and 2,147,483,647). In addition to these simple data types, there are over one hundred other data types built specifically for data in ArcGIS, such as coordinate system and extent.

Note:

The Data Type column includes the supported ArcGIS data types for each parameter. This is different from the Python types that the parameter supports. Although parameters will show a variety of ArcGIS data types, most parameters are supported as strings from Python.

Derived Output

Derived parameters are output parameters that are not entered as values on a tool's dialog box or as arguments in Python. Tools will have derived outputs in the following cases:

  • The tool calculates a value that is returned by the tool, such as the Get Count tool, which provides a count of records in a table.
  • The tool modifies input datasets, such as the Calculate Field tool, which modifies field values.
  • Output datasets whose name or location is determined from input parameters or other known locations, such as the Feature Class to Feature Class tool, which determines the output path from workspace and feature class name parameters.

Return Value

Many of the tools in the Spatial Analyst and Image Analyst extensions support Map Algebra, and are accessed in Python through an algebraic format. That is, an object whose name is identified to the left of an equal sign is created based on a tool or operator stated to the right of the equal sign. These tools include a Return Value section that is similar to the Derived Output section. Although parameters in the Return Value sections are not expressed in Python as an argument and are returned as values, they are unlike derived output parameters, and are entered as values on a tool's dialog box.

Learn more about Map Algebra

Code Sample

The Code Sample section includes one or more examples illustrating how the tool can be run and used in Python.

Environments

The Environments section is a list of the environment settings that the tool honors. Click any link in the list to go to its reference page. If a particular environment setting is of importance to the tool, there may be further information about that setting.