Volume Percentile Contours (Spatial Analyst Tools)

Summary

Creates contours that delineate the smallest area enclosing the top p% of total magnitude (value * cell area) by accumulating ranked cells to the volume threshold.

Learn more about how Volume Percentile Contours works

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.

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 90^th 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. Planar—The calculation will be performed on a projected flat plane using a 2D Cartesian coordinate system. This is the default. Geodesic—The calculation will be performed in a 3D Cartesian coordinate system by considering the shape of the earth as an ellipsoid.	String
Ignore Negative Values (Optional)	Specifies whether negative values will be ignored in the volume percentile calculation. Checked—Negative values will be ignored in the volume percentile calculation. Unchecked—Negative values will not be ignored in the volume percentile calculation; they will be included. This is the default.	Boolean
Smooth Outputs (Optional)	Determines if the output polygons will be smoothed into simpler shapes or conform to the input raster's cell edges. Checked—The polygons will be smoothed into simpler shapes. The smoothing is done in such a way that the polygons contain a minimum number of segments while remaining as close as possible to the original raster cell edges. This is the default. Unchecked—The edge of the polygons will conform exactly to the input raster's cell edges. With this option, converting the resulting polygon feature class back to a raster would produce a raster the same as the original.	Boolean

VolumePercentileContours(in_surface_raster, out_contour_polygons, {percentile_values}, {method}, {ignore_negative_values}, {smooth_outputs})

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 90^th 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. `PLANAR`—The calculation will be performed on a projected flat plane using a 2D Cartesian coordinate system. This is the default. `GEODESIC`—The calculation will be performed in a 3D Cartesian coordinate system by considering the shape of the earth as an ellipsoid.	String
ignore_negative_values (Optional)	Specifies whether negative values will be ignored in the volume percentile calculation. `IGNORE_NEGATIVE_VALUES`—Negative values will be ignored in the volume percentile calculation. `USE_ALL_VALUES`—Negative values will not be ignored in the volume percentile calculation; they will be included. This is the default.	Boolean
smooth_outputs (Optional)	Determines if the output polygons will be smoothed into simpler shapes or conform to the input raster's cell edges. `SMOOTH`—The polygons will be smoothed into simpler shapes. The smoothing is done in such a way that the polygons contain a minimum number of segments while remaining as close as possible to the original raster cell edges. This is the default. `NO_SMOOTH`—The edge of the polygons will conform exactly to the input raster's cell edges. With this option, converting the resulting polygon feature class back to a raster would produce a raster the same as the original.	Boolean

Code sample

VolumePercentileContours example 1 (Python window)

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",
                         smooth_outputs="SMOOTH")

VolumePercentileContours example 2 (stand-alone script)

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 *

## 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"
smooth_outputs="SMOOTH"
out_volP_contour = "VolumeP_CrimeDensity_Out.shp"

## Run: Create Volume Percentile Contours
VolumP_out_contours = VolumePercentileContours(in_surface_raster,
                                               out_volP_contour,
                                               percentile_values, method,
                                               ignore_negative_values, smooth_outputs)

Environments

Auto Commit, Current Workspace, Default Output Z Value, Extent, Geographic Transformations, M Resolution, M Tolerance, Parallel Processing Factor, Output CONFIG Keyword, Output Coordinate System, Output has M values, Output has Z values, Output M Domain, Output XY Domain, Output Z Domain, Scratch Workspace, XY Resolution, XY Tolerance, Z Resolution, Z Tolerance

Licensing information

Basic: Requires Spatial Analyst
Standard: Requires Spatial Analyst
Advanced: Requires Spatial Analyst