| Label | Explanation | Data Type |
Input Surface Raster | The input raster that contour polygons will be calculated for. It must be a continuous raster. The input raster data type can be integer or floating point. | Raster Layer |
Output Contour Polygons | The output contour polygon features. The output includes contour polygons for all the specified percentile values. | Feature Class |
Percentile Values (Optional) | The percentile values that contours will be calculated for. The default is 90, indicating the 90th percentile. The values can range from 0 to 100. | Double |
Method (Optional) | Specifies whether the calculation will be based on a planar (flat earth) or a geodesic (ellipsoid) method. The planar method is appropriate to use on local areas in a projection that maintains correct distance and area. It is suitable for analyses that cover areas such cities, counties, or smaller states in area. The geodesic method produces a more accurate result at the potential cost of an increase in processing time.
| String |
Ignore Negative Values (Optional) | Specifies whether negative values will be ignored in the volume percentile calculation.
| Boolean |
Summary
Creates contours that delineate the smallest area enclosing p percent of total magnitude (value × cell area) by accumulating ranked cells to the volume threshold.
Illustration
Usage
Percentile values can be any values between 0 and 100. A value of 0 may result in an empty or trivial result. A value of 100 returns the entire valid footprint.
The tool ranks the cells by their values in descending order and accumulates per-cell volume (volume × cell area) until the cumulative total reaches p percent of the raster’s total volume. The area is calculated by the Method parameter value of Planar or Geodesic. The percentile volume threshold is the value at the cutoff. The output selects cells that meet or exceed this threshold.
The area enclosed within the output contour polygon indicates the area enclosed by the percentage of the total sum of the volume calculated using the percentile values. The area of the output polygons reports the physical footprint; it does not equal volume, but it’s the area where p percent of the volume resides
In the case of repeated values at the volume threshold, the tool includes all the values at that threshold. As a result, the output volume will not be below the specified percentile. A consequence of this is that adjacent percentiles can be similar.
When multiple percentile values are specified, the output polygons will be nested. The innermost polygon corresponds to the highest values, and the outermost polygon covers the smaller values.
The polygon's shape area reports how much ground is in that extreme band.
The Planar option for the Method parameter is appropriate if the analysis is performed at a local scale with a projection that accurately maintains the correct distance and area.
Use the Geodesic option to perform analysis at a regional or large scale (for example, using Web Mercator or any geographic coordinate system). This option accounts for the curvature of the spheroid and correctly handles data near the poles and the international dateline.
If the Ignore Negative Values parameter is unchecked, the tool will include negative input cell values in the analysis. This may influence the cumulative sum of the volume calculation.
The input surface raster must be a single-band raster.
If the goal is to create polygons based on ranked cell values only, use the Value Percentile Contours tool instead.
See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.
Parameters
VolumePercentileContours(in_surface_raster, out_contour_polygons, {percentile_values}, {method}, {ignore_negative_values})| Name | Explanation | Data Type |
in_surface_raster | The input raster that contour polygons will be calculated for. It must be a continuous raster. The input raster data type can be integer or floating point. | Raster Layer |
out_contour_polygons | The output contour polygon features. The output includes contour polygons for all the specified percentile values. | Feature Class |
percentile_values [percentile_values,...] (Optional) | The percentile values that contours will be calculated for. The default is 90, indicating the 90th percentile. The values can range from 0 to 100. | Double |
method (Optional) | Specifies whether the calculation will be based on a planar (flat earth) or a geodesic (ellipsoid) method. The planar method is appropriate to use on local areas in a projection that maintains correct distance and area. It is suitable for analyses that cover areas such cities, counties, or smaller states in area. The geodesic method produces a more accurate result at the potential cost of an increase in processing time.
| String |
ignore_negative_values (Optional) | Specifies whether negative values will be ignored in the volume percentile calculation.
| Boolean |
Code sample
The following sample demonstrates using this tool in the Python window.
import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
VolumePercentileContours("CrimeEventsDensity.tif", "VolP_CrimeDensity_Out.shp",
[50, 75, 90, 95, 99], method = "Planar",
ignore_negative_values = "USE_ALL_VALUES")The following sample demonstrates the using this tool in a stand-alone Python script.
## Name: VolumePercentileContours_Ex_standalone.py
## Description: Delineate areas of different magnitudes from density surface
## Requirements: Spatial Analyst Extension
## Import system modules
import arcpy
from arcpy import env
from arcpy.sa import *
## Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")
## Set environment settings
env.workspace = "C:/sapyexamples/data"
# To allow overwriting outputs change overwriteOutput option to True.
env.overwriteOutput = False
## Set local variables
in_surface_raster = "CrimeEventsDensity.tif"
percentile_values = [25, 50, 75, 90, 95, 99]
method = "Planar"
ignore_negative_values = "USE_ALL_VALUES"
out_volP_contour = "VolumeP_CrimeDensity_Out.shp"
## Execute: Create Volume Percentile Contours
VolumP_out_contours = VolumePercentileContours(in_surface_raster,
out_volP_contour,
percentile_values, method,
ignore_negative_values)