Multiscale Surface Percentile (Spatial Analyst)

Summary

Calculates the most extreme percentile across a range of spatial scales.

Learn more about how Multiscale Surface Percentile works

Usage

• The Input Surface Raster (in_raster in Python) parameter value can be any type of surface raster. When using a surface raster other than an elevation surface, this tool calculates the percentile of the raster's cell values.

• When using an elevation surface as input, Elevation Percentile (EP) is the percentile calculated. EP is a measure of Local Topographic Position (LTP). It expresses the vertical position for a cell as the percentile of the elevation distribution within a filter window, or neighborhood. Multiscale EP is highly variable at smaller scales and changes more gradually at larger scales. It is also relatively unaffected by irregular elevation distributions and outliers, making it a robust measure of LTP.

• Whether using an elevation surface or another type of surface as input, percentile is calculated across multiple scales. These scales are the neighborhood distance value used for calculation. They are the distances from the target cell center, creating a square of cells around the target cell. For example, a scale of 4 cells is a 9 by 9 cell neighborhood.

• The Output Percentile Raster (out_percentile_raster in Python) parameter is the primary output. This is a raster containing the most extreme percentiles for each cell across a range of spatial scales. Values can range from 0 to 100. The most extreme value is the percentile furthest from 50 (such as, percentiles closer to 0 or 100).

• The Output Scale Raster (out_scale_raster in Python) parameter provides more information about the primary output. It contains the scale at which the most extreme percentile was found for each cell. The scale is the neighborhood distance value, which is the distance from the target cell center, creating a square of cells around the target cell.

• The Minimum Neighborhood Distance (min_scale in Python) and Maximum Neighborhood Distance (max_scale in Python) parameters define the minimum and maximum neighborhood sizes, or scales, that percentile will be calculated for. These values represent the smallest and largest distance from the target cell. For example, a value of 1 creates a 3 by 3 cell neighborhood, and a value of 2 creates a 5 by 5 cell neighborhood.

  These values cannot be less than the input raster cell size or 1 cell.

  The Minimum Neighborhood Distance parameter value must be less than or equal to the Maximum Neighborhood Distance parameter value.

• The Base Distance Increment (base_increment in Python) parameter is the initial increase in neighborhood distance between scales. This increase is altered when using a value greater than 1 for the Nonlinearity Factor (nonlinearity in Python) parameter.

  This parameter value cannot be less than the input raster cell size or 1 cell. The default value is the input raster cell size.

• The Nonlinearity Factor parameter controls the increase in neighborhood distance, or scale. A value of 1.0 creates a linear increase in scale in which the increment between scales will be the same (the value of the Base Distance Increment parameter). Increasing this value will increase scale faster and decrease the number of scales for a given minimum and maximum scale.

  Use a value larger than 1.0 for this parameter if you want high scale sampling density for smaller scales and lower scale sampling density for larger scales.

  This parameter accepts values greater than or equal to 1.0. Generally, values between 1.0 and 2.0 are most often used for this parameter when seeking a nonlinear increase in neighborhood distance.

  Learn more about how Multiscale Surface Percentile works

• NoData cells in the Input Surface Raster value will be ignored and those cells will be assigned NoData in the Output Percentile Raster and Output Scale Raster parameter values.

• This tool can be GPU accelerated, which means that if a compatible graphics processing unit (GPU) is available on your system, it will be used to enhance the performance of the tool. Use the Target device for analysis (analysis_target_device in Python) parameter to control whether the GPU or CPU will be used to run the tool.

  See GPU processing with Spatial Analyst for details on compatible GPUs, configuring and working with GPU devices, as well as troubleshooting tips.

• Running with GPU results in higher precision output compared to CPU.

• This tool supports parallel processing. If your computer has multiple processors or processors with multiple cores, better performance may be achieved, particularly on larger datasets. The Parallel processing with Spatial Analyst help topic includes details about this capability and how to configure it.

  By default, this tool will use 50 percent of the available cores. You can control the number of cores the tool uses with the Parallel processing factor environment.

• When the output raster format is .crf, this tool supports the Pyramid raster storage environment. Pyramids will be created in the output by default. For any other output format, this environment is not supported, and pyramids will not be created.

• See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.

Parameters

Dialog

Label	Explanation	Data Type
Input Surface Raster	The input surface raster.	Raster Layer
Output Scale Raster (Optional)	The output raster containing the scale at which the most extreme percentile was found for each cell. Scales are represented as their neighborhood distance values. It will be floating-point type.	Raster Dataset
Distance Units (Optional)	Specifies the distance unit that will be used for the Minimum Neighborhood Distance, Maximum Neighborhood Distance, and Base Distance Increment parameters. Distance will be measured in the number of cells or specified unit. The default is the map unit of the spatial reference for the Input Surface Raster value. Cells—The distance unit will be cells. Meters—The distance unit will be meters. Centimeters—The distance unit will be centimeters. Kilometers—The distance unit will be kilometers. Inches—The distance unit will be inches. Feet—The distance unit will be feet. Yard—The distance unit will be yards. Miles—The distance unit will be miles.	String
Minimum Neighborhood Distance (Optional)	The distance that defines the minimum neighborhood scale that elevation percentile will be calculated for. This is the distance from the target cell center, creating a square of cells around the target cell. This value must be less than or equal to the Maximum Neighborhood Distance parameter value and greater than or equal to the input raster cell size or one cell. The default value is 4 times the cell size of the Input Surface Raster parameter value, resulting in a 9 by 9 cell neighborhood.	Double
Maximum Neighborhood Distance (Optional)	The distance that defines the maximum neighborhood scale that elevation percentile will be calculated for. This is the distance from the target cell center, creating a square of cells around the target cell. This value must be greater than or equal to the Minimum Neighborhood Distance parameter value and the input raster cell size or one cell. The default value is 13 times the cell size of the Input Surface Raster parameter value, resulting in a 27 by 27 cell neighborhood.	Double
Base Distance Increment (Optional)	The initial increase in neighborhood distance between scales. This parameter value cannot be less than the Input Surface Raster cell size or 1 cell. The default value is the cell size of the Input Surface Raster parameter value.	Double
Nonlinearity Factor (Optional)	The factor that can introduce nonlinearity into the scale increase at each increment. This causes the increment between scales to increase instead of remaining constant. Generally, values between 1.0 and 2.0 are used. This parameter must be greater than or equal to 1. The default value is 1, which creates a linear increase in neighborhood distances (where the increment between scales remains constant).	Double
Target Device for Analysis (Optional)	Specifies the device that will be used to perform the calculation. GPU then CPU—If a compatible GPU is found, it will be used to perform the calculation. Otherwise, the CPU will be used. This is the default. CPU only—The calculation will only be performed on the CPU. GPU only—The calculation will only be performed on the GPU.	String

Return Value

Label	Explanation	Data Type
Output Percentile Raster	The output raster containing the most extreme percentile value for each cell. The most extreme value is the percentile furthest from 50 (such as percentiles closer to 0 or 100). It will be floating-point type.	Raster

Python

MultiscaleSurfacePercentile(in_raster, {out_scale_raster}, {distance_units}, {min_scale}, {max_scale}, {base_increment}, {nonlinearity}, {analysis_target_device})

Name	Explanation	Data Type
in_raster	The input surface raster.	Raster Layer
out_scale_raster (Optional)	The output raster containing the scale at which the most extreme percentile was found for each cell. Scales are represented as their neighborhood distance values. It will be floating-point type.	Raster Dataset
distance_units (Optional)	Specifies the distance unit that will be used for the min_scale, max_scale, and base_increment parameters. Distance will be measured in the number of cells or specified unit. The default is the map unit of the spatial reference for the in_raster value. CELLS—The distance unit will be cells. METERS—The distance unit will be meters. CENTIMETERS—The distance unit will be centimeters. KILOMETERS—The distance unit will be kilometers. INCHES—The distance unit will be inches. FEET—The distance unit will be feet. YARDS—The distance unit will be yards. MILES—The distance unit will be miles.	String
min_scale (Optional)	The distance that defines the minimum neighborhood scale that elevation percentile will be calculated for. This is the distance from the target cell center, creating a square of cells around the target cell. This value must be less than or equal to the max_scale parameter value and greater than or equal to the input raster cell size or one cell. The default value is 4 times the cell size of the in_raster parameter value, resulting in a 9 by 9 cell neighborhood.	Double
max_scale (Optional)	The distance that defines the maximum neighborhood scale that elevation percentile will be calculated for. This is the distance from the target cell center, creating a square of cells around the target cell. This value must be greater than or equal to the min_scale parameter value and the input raster cell size or one cell. The default value is 13 times the cell size of the in_raster parameter value, resulting in a 27 by 27 cell neighborhood.	Double
base_increment (Optional)	The initial increase in neighborhood distance between scales. This parameter cannot be less than the in_raster cell size or 1 cell. The default value is the cell size of the in_raster parameter value.	Double
nonlinearity (Optional)	The factor that can introduce nonlinearity into the scale increase at each increment. This causes the increment between scales to increase instead of remaining constant. Generally, values between 1.0 and 2.0 are used. This parameter must be greater than or equal to 1. The default value is 1, which creates a linear increase in neighborhood distances (where the increment between scales remains constant).	Double
analysis_target_device (Optional)	Specifies the device that will be used to perform the calculation. GPU_THEN_CPU—If a compatible GPU is found, it will be used to perform the calculation. Otherwise, the CPU will be used. This is the default. CPU_ONLY—The calculation will only be performed on the CPU. GPU_ONLY—The calculation will only be performed on the GPU.	String

Return Value

Name	Explanation	Data Type
out_percentile_raster	The output raster containing the most extreme percentile value for each cell. The most extreme value is the percentile furthest from 50 (such as percentiles closer to 0 or 100). It will be floating-point type.	Raster

Code sample

MultiscaleSurfacePercentile example 1 (Python window)

The following sample demonstrates the use of this tool in the Python window.

This example generates the percentiles output raster from an input surface raster using the default values for all optional parameters.

from arcpy.sa import *
outPercentiles = MultiscaleSurfacePercentile("elevation.tif", "", "", "", "", "", "", "")
outPercentiles.save("C:/sapyexamples/output/outpercentiles01.tif")

MultiscaleSurfacePercentile example 2 (stand-alone script)

The following sample demonstrates the use of this tool in a stand-alone Python script.

This example generates a percentiles raster for scales starting at 10 meters up to 100 meters with 10 meter increments between each scale.

# Name: MultiscaleSurfacePercentile_standalone.py
# Description: Calculates the most extreme percentiles over a range of spatial scales.
# Requirements: Spatial Analyst Extension

# Import system modules
import arcpy
from arcpy.sa import *

# Set environment settings
arcpy.env.workspace = "C:/sapyexamples/data"

# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")

# Set local variables
inRaster = "elevation.tif"
inDistanceUnits = "METERS"
inMinScale = 10
inMaxScale = 100
inIncrement = 10
inNonlinearity = 1

# Execute the tool
outPercentiles = MultiscaleSurfacePercentile(inRaster, "", inDistanceUnits, inMinScale,
                                             inMaxScale, inIncrement, inNonlinearity, "")

# Save the output 
outPercentiles.save("C:/sapyexamples/output/outpercentiles02.tif")

Environments

Auto Commit, Cell Size, Cell Size Projection Method, Current Workspace, Extent, Geographic Transformations, Mask, Output CONFIG Keyword, Output Coordinate System, Pyramid, Parallel Processing Factor, Scratch Workspace, Snap Raster, Tile Size