| Label | Explanation | Data Type |
Input Raster or Feature Zones | The dataset that defines the zones. The zones can be defined by an integer raster or a feature layer. | Raster Layer; Feature Layer |
Input Value Rasters | The collection of rasters whose values will each be summarized by a statistic. This parameter has the following properties.
A statistic will be calculated for all cells in each input value raster that belong to the same zone as the output cell. The following are the available statistics types:
The field names in the output statistics table will be derived from the value raster name and statistics type by default. | Value Table |
Output Statistics Table | The output table that will contain the summary of the values in each zone for all value rasters. The format of the table is determined by the output location and path. By default, the output will be a geodatabase table if in a geodatabase workspace, and a dBASE table if in a file workspace. | Table |
Output Statistics Feature Class (Optional) | The output feature class that will be created by joining the output table to the input zone data. | Feature Class |
Zone Field (Optional) | The field that contains the values that define each zone. It can be an integer or a string field of the zone dataset. | Field |
Ignore NoData in Calculations (Optional) | Specifies whether NoData values in the value input will be ignored in the results of the zone that they fall within.
| Boolean |
Percentile Values (Optional) | The percentile that will be calculated. The default is 90, indicating the 90th percentile. The values can range from 0 to 100. The 0th percentile is essentially equivalent to the minimum statistic, and the 100th percentile is equivalent to maximum. A value of 50 will produce essentially the same result as the median statistic. This parameter is only available if the Statistics type parameter is set to Percentile or All. | Double |
Percentile Interpolation Type (Optional) | Specifies the method of interpolation that will be used when the percentile value falls between two cell values from the input value raster.
| String |
Calculate Circular Statistics (Optional) | Specifies how the input raster will be processed for circular data.
| Boolean |
Circular Wrap Value (Optional) |
The value that will be used to round a linear value to the range of a given circular statistic. Its value must be a positive integer or a floating-point value. The default value is 360 degrees. This parameter is only supported if the Calculate Circular Statistics parameter is checked. | Double |
Process as Multidimensional (Optional) | Specifies how the input rasters will be calculated if they are multidimensional.
| Boolean |
Append Zone Attributes to Output Features (Optional) | Specifies whether any of the additional zone attributes from the input zones will be appended to the output feature class.
| Boolean |
Summary
Summarizes the values of multiple rasters within the zones of another dataset and reports the results as a table.
Usage
The following are example applications of the tool:
- Calculate the mean precipitation, maximum temperature, and sum of population within different ecosystem zones to estimate sustainable agricultural practices.
- Estimate the mean elevation, mean slope, and sum of NDVI values for each plot to locate areas suitable for planting shade trees.
A zone is defined as all areas in the input that have the same value. The areas do not have to be contiguous. Both rasters and features can be used for the zone input.
If the Input Raster or Feature Zones (in_zone_raster_or_features in Python) parameter value is a raster, it must be an integer raster.
If the Input Raster or Feature Zones parameter value is a feature, it will be converted to a raster internally using the cell size, cell alignment, and spatial reference from the Input Value Rasters (in_value_rasters_statistics in Python) parameter value with the smallest cell size, unless otherwise specified in the analysis environment. This will trigger an internal resampling before the zonal operation is performed.
If the Input Raster or Feature Zones parameter value is a feature, for any of the zone features that do not overlap any cell centers of a value raster, those zones will not be converted to the internal zone raster. As a result, those zones will not be represented in the output. You can manage this by determining an appropriate value for the cell size environment that will preserve the desired level of detail of the feature zones, and specify it in the analysis environment.
If the Input Raster or Feature Zones value is a point feature, more than one point may be contained in any particular cell of the input value rasters. For such cells, the zone value is determined by the point with the lowest ObjectID field (for example, OID or FID).
If the Input Raster or Feature Zones value has overlapping features, the zonal analysis will be performed for each individual feature.
When the cell size of the Input Raster or Feature Zones and the Input Value Rasters parameter values are different, the cell size, cell alignment and spatial reference from the Input Value Rasters parameter value with the smallest cell size will be used, unless otherwise specified in the analysis environment. This will trigger an internal resampling before the zonal operation is performed.
When the zone and value inputs are all rasters of the same cell size and the cells are aligned, they will be used directly in the tool and will not be resampled internally during tool processing.
When specifying the Input Raster or Feature Zones value, the default Zone Field (zone_field in Python) parameter value will be the first available integer field (for example, OID or FID) for features, and the VALUE field for raster. The zone field can be an integer or a string field type.
The supported statistics type depends on the data type of the Input Value Rasters parameter value, and the statistics calculation type specified by the Calculate Circular Statistics parameter value.
If the data type is integer, the arithmetic statistics calculation supports the Mean, Majority, Majority count, Majority percentage, Maximum, Median, Minimum, Minority, Minority count, Minority percentage, Percentile, Range, Standard deviation, Sum, and Variety options. The circular statistics calculation supports the Mean, Majority, Minority, Standard deviation, and Variety options.
If the data type is float, the arithmetic statistics calculation supports the Mean, Maximum, Median, Minimum, Percentile, Range, Standard deviation, and Sum options. The circular statistics calculation supports the Mean and Standard deviation options.
For majority and minority calculations, when there is a tie, the output will be the lowest of the tied values.
To calculate more than one statistics type per value raster, the same value raster needs to be specified multiple times. If the same value raster and statistics type combination is duplicated, the tool will generate an error.
To calculate circular statistics, check the Calculate Circular Statistics parameter (circular_calculation = "CIRCULAR" in Python), and specify a value for the Circular Wrap Value (circular_wrap_value in Python) parameter.
If the Calculate Circular Statistics parameter is checked, circular statistics will be calculated for all value rasters with the specified circular wrap value applied.
Supported multidimensional raster dataset types include multidimensional raster layer, mosaic, image service, and Esri CRF.
The Output Statistics Table (out_statistics_table in Python) parameter value will have the following characteristics:
- The number of rows in the output table is the number of zones within the analysis extent.
- A series of fields will be created in the output table to represent the zones, with the count and statistics values for each Input Value Rasters value.
- The names of the fields are derived from the value raster name and statistics type by default, unless specified in the Field Name parameter. For circular statistics, the name of the field will include C_ before the specified statistic. For example, the field name will be ValueRasterName_MEAN for the arithmetic mean statistic and ValueRasterName_C_MEAN for the circular mean statistic.
- The maximum length of the field names in the output table will depend on the workspace.
- The data type for each value of the items in the output table will depend on the zonal calculation being performed. See How zonal statistics tools work for the specific behavior of a statistic.
For the Output Statistics Feature Class (out_statistics_features in Python) parameter value, if the zone input is a raster, the output feature class will be converted to features without generalizing and by honoring the analysis environment.
This tool will use the following environment settings:
- The value raster with the smallest cell size will be used as the analysis cell size, output coordinate system, and snap raster by default.
- The default extent will be the intersection of the zone with the union of all the value rasters.
By default, this tool will use multicore processors if available. The maximum number of cores that can be used is four.
To use fewer cores, use the Parallel Processing Factor environment setting.
See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.
Parameters
ZonalCharacterization(in_zone_raster_or_features, in_value_rasters_statistics, out_statistics_table, {out_statistics_features}, {zone_field}, {ignore_nodata}, {percentile_values}, {percentile_interpolation_type}, {circular_calculation}, {circular_wrap_value}, {process_as_multidimensional}, {add_zone_attributes})| Name | Explanation | Data Type |
in_zone_raster_or_features | The dataset that defines the zones. The zones can be defined by an integer raster or a feature layer. | Raster Layer; Feature Layer |
in_value_rasters_statistics [in_value_rasters_statistics,...] | The collection of rasters whose values will each be summarized by a statistic. This parameter has the following properties.
A statistic will be calculated for all cells in each input value raster that belong to the same zone as the output cell. The following are the available statistics types:
The field names in the output statistics table will be derived from the value raster name and statistics type by default. | Value Table |
out_statistics_table | The output table that will contain the summary of the values in each zone for all value rasters. The format of the table is determined by the output location and path. By default, the output will be a geodatabase table if in a geodatabase workspace, and a dBASE table if in a file workspace. | Table |
out_statistics_features (Optional) | The output feature class that will be created by joining the output table to the input zone data. | Feature Class |
zone_field (Optional) | The field that contains the values that define each zone. It can be an integer or a string field of the zone dataset. | Field |
ignore_nodata (Optional) | Specifies whether NoData values in the value input will be ignored in the results of the zone that they fall within.
| Boolean |
percentile_values [percentile_values,...] (Optional) | The percentile that will be calculated. The default is 90, indicating the 90th percentile. The values can range from 0 to 100. The 0th percentile is essentially equivalent to the minimum statistic, and the 100th percentile is equivalent to maximum. A value of 50 will produce essentially the same result as the median statistic. This parameter is only supported if the statistics_type parameter is set to PERCENTILE or ALL. | Double |
percentile_interpolation_type (Optional) | Specifies the method of interpolation that will be used when the percentile value falls between two cell values from the input value raster.
| String |
circular_calculation (Optional) | Specifies how the input raster will be processed for circular data.
| Boolean |
circular_wrap_value (Optional) |
The value that will be used to round a linear value to the range of a given circular statistic. Its value must be a positive integer or a floating-point value. The default value is 360 degrees. This parameter is only supported if the circular_calculation parameter is set to CIRCULAR. | Double |
process_as_multidimensional (Optional) | Specifies how the input rasters will be calculated if they are multidimensional.
| Boolean |
add_zone_attributes (Optional) | Specifies whether any of the additional zone attributes from the input zones will be appended to the output feature class.
| Boolean |
Code sample
This example summarizes the values of multiple rasters within the zones defined by a polygon shapefile and records the results in a table and a feature class.
import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
outTable = ZonalCharacterization("zones.shp",
"ValueRas1.tif MEAN ValueRas1_MEAN;ValueRas2.tif MAXIMUM ValueRas2_MAX;ValueRas3.tif STD ValueRas3_STD",
"zonalcharacterout.dbf","featurestatout.shp","Id","DATA","",
"AUTO_DETECT","ARITHMETIC","","CURRENT_SLICE","ZONE_FIELD_ONLY")This example summarizes the values of multiple rasters within the zones defined by a zone raster and records the results in a table and a feature class.
# Name: ZonalCharacterization_Ex_standalone.py
# Description: Summarizes the values of multiple rasters within the zones
# of another dataset and reports the results as a table.
# Requirements: Spatial Analyst Extension
# Import system modules
import arcpy
from arcpy.sa import *
# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")
# Set the analysis environments
arcpy.env.workspace = "C:/sapyexamples/data"
# Set the local variables
inZoneData = "zones.tif"
zoneField = "Value"
inValueRas1 = "ValueRas1.tif"
inValueRas2 = "ValueRas2.tif"
inValueRas3 = "ValueRas3.tif"
outTable = "zonalcharactereizationout.dbf"
outFeatureClass = "featurestatout.shp"
# Execute ZonalCharacterization
outzonalchar = ZonalCharacterization(inZoneData, [[inValueRas1, "MEAN",
"ValueRas1_MEAN"], [inValueRas2, "STD", "ValueRas2_STD"],
[inValueRas3, "SUM", "ValueRas3_SUM"]], outTable, outFeatureClass,
zoneField, "NODATA", "", "", "ARITHMETIC", "", "CURRENT_SLICE", "ALL")