Available with Spatial Analyst license.
Summary
Calculates for each input cell location a statistic of the values within a specified neighborhood around it.
Illustration
Usage
If the input raster is integer, all the statistics types are available. If the input raster is floating point, only the Mean, Maximum, Median, Minimum, Percentile, Range, Standard deviation, and Sum statistics are available; the Majority, Minority, and Variety statistics are not permitted.
When a circular, an annulus-shaped, or a wedge-shaped neighborhood is specified, some of the outer diagonal cells may not be considered in the calculations because the center of the cell must be encompassed within the neighborhood.
The Irregular and Weight Neighborhood types require that a Kernel file be specified. Kernel files should have a .txt file extension.
See the Irregular and Weight sections of How Focal Statistics works for information on creating and using kernel files.
The Neighborhood type can be set to Weight for the Mean, Standard Deviation, and Sum statistics types only.
Input NoData cells may receive a value in the output if the Ignore NoData in calculations parameter is checked, provided at least one cell within the neighborhood has a valid value.
See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.
Syntax
FocalStatistics(in_raster, {neighborhood}, {statistics_type}, {ignore_nodata}, {percentile_value})
Parameter | Explanation | Data Type |
in_raster | The raster on which the focal statistics will be calculated. | Raster Layer |
neighborhood (Optional) | The Neighborhood class dictates the shape of the area around each cell used to calculate the statistic. The available neighborhood types are NbrAnnulus, NbrCircle, NbrRectangle, NbrWedge, NbrIrregular, and NbrWeight. The following are the forms of the neighborhoods:
The default neighborhood is a square NbrRectangle with a width and height of three cells. | Neighborhood |
statistics_type (Optional) | Specifies the statistic type to be calculated.
The default statistic type is MEAN. If the input raster is integer, all the statistics types are available. If the input raster is floating point, only the MEAN, MAXIMUM, MEDIAN, MINIMUM, PERCENTILE, RANGE, STD, and SUM statistic types are available. | String |
ignore_nodata (Optional) | Specifies whether NoData values will be ignored by the statistic calculation.
| Boolean |
percentile_value (Optional) | The percentile to calculate. The default is 90, for 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 option is only available if the statistics_type parameter is set to percentile. | Double |
Return Value
Name | Explanation | Data Type |
out_raster | The output focal statistics raster. | Raster |
Code sample
FocalStatistics example 1 (Python window)
This example calculates the least-frequently occurring value in a ring-shaped neighborhood around each cell in the input raster.
import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
outFocalStat = FocalStatistics("elevation", NbrAnnulus(5, 10, "CELL"),
"MINORITY", "NODATA")
outFocalStat.save("C:/sapyexamples/output/focalstat01")
FocalStatistics example 2 (stand-alone script)
This example determines the least frequently occurring value in a 10-by-10 neighborhood around each cell in the input raster.
# Name: FocalStatistics_Ex_02.py
# Description: Calculates a statistic on a raster over a specified
# neighborhood.
# 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"
# Set local variables
inRaster = "elevation"
neighborhood = NbrRectangle(10, 10, "CELL")
# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")
# Execute FocalStatistics
outFocalStatistics = FocalStatistics(inRaster, neighborhood, "MINORITY",
"")
# Save the output
outFocalStatistics.save("C:/sapyexamples/output/focalstatout")
Environments
Licensing information
- Basic: Requires Spatial Analyst
- Standard: Requires Spatial Analyst
- Advanced: Requires Spatial Analyst