Building complex statements

Available with Spatial Analyst license.

Available with Image Analyst license.

One of the most powerful aspects of Map Algebra is the ability to create a statement comprising multiple operators and tools in a single statement. Being able to enter multiple operators and tools in a single statement allows you to more easily model complex interactions, and overall processing time may be reduced. Complex expressions are not limited to the functionality provided by the tools of the ArcGIS Spatial Analyst extension; they may include tools from other toolboxes. When building complex statements, there are specific interaction rules that may be required to execute correctly.

Complex statement rules

• In complex statements, only the output to the left of the equals sign becomes a Raster object.
• The order of execution for an expression is determined by parentheses and the precedence level of the operators used. For more information on operator precedence, see Operator Precedence Table.

  outRaster = Raster("inras1") + Raster("inras2") / Raster("inras3")

• In the statement above, inras2 is divided by inras3 and the result is added to inras1.

  Note:

  It is important to know the precedence level of the operators. For example, Boolean (~, &, ^, |) operators have a higher precedence level than Relational (<, <=, >, >=, ==, !=) operators, which has an impact on how you construct your expressions. For more information on operator precedence, see Operator Precedence Table.

• You can use parentheses to control the order of execution. Parentheses can be nested, in which case the expression within the innermost parentheses will be processed first, regardless of the precedence value of the operators.

  outRas = Raster("inras1") / (Raster("inras2") + Raster("inras3"))

  In the statement above, inras1 is divided by the sum of inras2 and inras3.

• When using multiple Boolean (~, &, ^, |) or Relational (<, <=, >, >=, ==, !=) operators consecutively in a single expression, parentheses should be used. For example, parentheses are required in the following expression (a>2) & (a<5).

  outRas = (Raster("a") > 2 ) & ( Raster("a") < 5)

  Dive-in:

  Some expressions may not require parentheses, but may instead have to be rewritten. For example, an expression in the form of a < b < c will not execute, and adding parentheses will change the meaning of the expression. Therefore, to execute successfully, this expression needs to be rewritten in the form of (a < b) & (b < c).

• Operators, variables, numbers, and tools can all be used in complex statements.

  outRas = Sin("inras1") + Raster("inras2") + 8

  const = 10
  outRas = Raster("inras1") + 2 * const

• All rules that apply to parentheses for statements created with operators also apply for those statements created with tools and operators. The tool or operator that is within the deepest nested parentheses will be processed first.

  num = 10
  outRas = (ZonalStatistics((Raster("inras2") + Raster("inras3")),
                           "Value", "valueras", "MAXIMUM") - num ) / 8

  In the statement above, the sum of inras2 and inras3 is used as input to the Zonal Statistics tool. The value of num is then subtracted before being divided.

• In a series of statements, the output from a preceding statement can be used as input in a subsequent statement.

  outAdd = Raster("inras1") + Raster("inras2")
  outRas = FocalStatistics(outAdd, NbrCircle(5, "Map"), "MEAN")

  In the example above, outAdd is a raster object created from the addition of inras1 and inras2. Since outAdd is a variable, no quotation marks are required when it is used as input to the subsequent Focal Statistics tool.

• Any tool can be embedded into another tool, whether the result is a raster or feature class. The required output from the embedded tool is used as the input to the outer tool.

  outdistance = EucDistance(ContourList("elevation", "#", [1500]))

  In this example, the output from the Contour List tool is used as input to the Euclidean Distance tool.

  dist = EucDistance(arcpy.Select_analysis("schools", "#", "Pop>2000"))

  In the example above, the output from the Analysis toolbox Select tool is used as input to the Euclidean Distance tool.

  Note:

  Since the embedded tool creates an output that is just an intermediate stage in a larger workflow, the output argument can be substituted with the hash symbol "#", allowing the tool to create a unique path and name for this temporary output. The use of the hash symbol is discussed in more detail in the Tool output section of the Using tools in Python help topic.

• To use an optional output from a tool in an expression, the dataset name or variable representing the dataset must be used.

  costDist = CostDistance("source", "in_cost", 15000, "out_bklink") 
  costOut = CostPath("dest", costDist, "out_bklink")

  In the example above, the optionally output backlink raster is output in the workspace with the name "out_bklink".

  bklink = "C:/results/out_bklink"
  costDist = CostDistance("source", "in_cost", 15000, bklink) 
  costOut = CostPath("dest", costDist, bklink)

  In the example above, the backlink raster is defined by a variable before the tool is executed. The variable points to the location and name that the output backlink raster will have.