Focal Statistics (Spatial Analyst Tools)

Summary

Calculates for each input cell location a statistic of the values within a specified neighborhood around it.

Learn more about how Focal Statistics works

Illustration

Input and output values from the Focal Statistics tool for a rectangle neighborhood with the Sum statistic set — `OutRas = FocalStatistics(InRas1, NbrRectangle(3,3,"CELL"), "SUM", "DATA"`)

Usage

There are several neighborhood shapes and statistics types to choose from. The available statistics depend on the type of the input raster.
The available neighborhood shapes are annulus (a donut or ring), circle, rectangle, and wedge. A custom neighborhood shape can be defined using a kernel file.
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 value be specified. A kernel file is an ASCII text file that specifies the values and shape of the neighborhood. The file can be created with any plain text editor. The file must have a .txt extension and no spaces in the file name.

See the Irregular and Weight sections of How Focal Statistics works for information about creating and using kernel files.
For integer input rasters, the valid statistics for Statistics type are majority, maximum, mean, median, minimum, minority, percentile, range, standard deviation, sum, and variety. For float input rasters, the valid statistics are maximum, mean, median, minimum, percentile, range, standard deviation, and sum. Majority, minority, and variety are not available for float input rasters.
If the input raster is integer, the output raster will be integer for the majority, maximum, minimum, minority, range, sum, and variety statistic types. The output will be float for the mean, median, percentile, and standard deviation statistic types.

If the input raster is of float type, the output will be float for all of the available statistic types.
For median calculations, if the neighborhood has an odd number of cells, the values will be ranked and the middle value will be reported as the median. If the neighborhood has an even number of cells, the values will be ranked and the middle two values will be averaged.
For majority and minority calculations, see the How Focal Statistics works topic for more information when there is a tie.
The Neighborhood parameter can be set to Weight only for the Mean, Standard deviation, and Sum statistic types.
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.

Label	Explanation	Data type
Input raster	The raster for which the focal statistics for each input cell will be calculated.	Raster Layer
Neighborhood (Optional)	The cells surrounding a processing cell that will be used in the statistic calculation. There are several predefined neighborhood types to choose from, or a custom kernel can be defined. Once the neighborhood type is selected, other parameters can be set to fully define the shape, size, and units of measure. The default neighborhood is a square rectangle with a width and height of three cells. The following are the forms of the available neighborhood types: Annulus, Inner radius, Outer radius, Units type A ring or donut-shaped neighborhood defined by an inner radius and an outer radius. The minimum value for radius is 1 cell, and the outer radius must be larger than the inner. The maximum inner radius is 2046 cells, and the maximum outer radius is 2047 cells. The default annulus is an inner radius of 1 cell and an outer radius of 3 cells. Circle, Radius, Units type A circular neighborhood with the given radius. The minimum value for radius is 1 cell, and the maximum value is 2047 cells. The default radius is 3 cells. Rectangle, Height, Width, Units type A rectangular neighborhood defined by width and height. The minimum value for width or height is 1 cell, and the maximum value is 4096 cells. The default is a square with a width and height of 3 cells. Wedge, Radius, Start angle, End angle, Units type A wedge-shaped neighborhood defined by a radius, a start angle, and an end angle. The minimum value for radius is 1 cell, and the maximum value is 2047 cells. The wedge extends counterclockwise from the starting angle to the ending angle. Angles are specified in degrees, with 0 or 360 representing east. Negative angles can be used. The default wedge is from 0 to 90 degrees, with a radius of 3 cells. Irregular, Kernel file A custom neighborhood with specifications set by the identified kernel text file. The minimum value for width or height of the kernel is 1 cell, and the maximum value is 4096 cells. Weight, Kernel file A custom neighborhood with specifications set by the identified kernel text file, which can apply weights to the members of the neighborhood. The minimum value for width or height of the kernel is 1 cell, and the maximum value is 4096 cells. For the annulus, circle, rectangle and wedge neighborhood types, the distance units for the parameters can be specified in Cell units or Map units. Cell units is the default. For kernel neighborhoods, the first line in the kernel file defines the width and height of the neighborhood in numbers of cells. The subsequent lines indicate how the input value that corresponds to that location in the kernel will be processed. A value of 0 in the kernel file for either the irregular or the weight neighborhood type indicates the corresponding location will not be included in the calculation. For the irregular neighborhood, a value of 1 in the kernel file indicates that the corresponding input cell will be included in the operation. For the weight neighborhood, the value at each position indicates what the corresponding input cell value is to be multiplied by. Positive, negative, and decimal values can be used.	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 will be available. If the input raster is floating point, only the Mean, Maximum, Median, Minimum, Percentile, Range, Standard deviation, and Sum statistic types will be available. Mean—The mean (average value) of the cells in the neighborhood will be calculated. Majority—The majority (value that occurs most often) of the cells in the neighborhood will be identified. Maximum—The maximum (largest value) of the cells in the neighborhood will be identified. Median—The median of the cells in the neighborhood will be calculated. Median is equivalent to the 50th percentile. Minimum—The minimum (smallest value) of the cells in the neighborhood will be identified. Minority—The minority (value that occurs least often) of the cells in the neighborhood will be identified. Percentile—A percentile of the cells in the neighborhood will be calculated. The 90th percentile is calculated by default. You can specify other values (from 0 to 100) using the Percentile value parameter. Range—The range (difference between largest and smallest value) of the cells in the neighborhood will be calculated. Standard deviation—The standard deviation of the cells in the neighborhood will be calculated. Sum—The sum of the cells in the neighborhood will be calculated. Variety—The variety (the number of unique values) of the cells in the neighborhood will be calculated.	String
Ignore NoData in calculations (Optional)	Specifies whether NoData values will be ignored by the statistic calculation. Checked—If a NoData value exists within a neighborhood, the NoData value will be ignored. Only cells within the neighborhood that have data values will be used in determining the output value. If the processing cell itself is NoData, the processing cell may receive a value in the output raster, provided at least one cell within the neighborhood has a valid value. This is the default. Unchecked—If any cell in a neighborhood has a value of NoData, including the processing cell, the output for the processing cell will be NoData. The presence of a NoData value implies that there is insufficient information to determine the statistic value for the neighborhood.	Boolean
Percentile value (Optional)	The percentile value that will be calculated. The default is 90, for the 90th percentile. The value can range from 0 to 100. The 0th percentile is essentially equivalent to the minimum statistic, and the 100th percentile is equivalent to the maximum statistic. A value of 50 will produce essentially the same result as the median statistic. This option is only supported if the Statistics type parameter is set to Percentile. If any other statistic type is specified, this parameter will be ignored.	Double

Return value

Label	Explanation	Data type
Output raster	The output focal statistics raster.	Raster

FocalStatistics(in_raster, {neighborhood}, {statistics_type}, {ignore_nodata}, {percentile_value})

Name	Explanation	Data type
in_raster	The raster for which the focal statistics for each input cell will be calculated.	Raster Layer
neighborhood (Optional)	The cells surrounding a processing cell that will be used in the statistic calculation. There are several predefined neighborhood types to choose from, or a custom kernel can be defined. Once the neighborhood type is selected, other parameters can be set to fully define the shape, size, and units of measure. The default neighborhood is a square rectangle with a width and height of three cells. The shape of the neighborhoods are defined by the `Neighborhood` class. The available neighborhood types are `NbrAnnulus`, `NbrCircle`, `NbrRectangle`, `NbrWedge`, `NbrIrregular` `,` and `NbrWeight`. The following are the forms of the available neighborhood types: `NbrAnnulus({innerRadius}, {outerRadius}, {units})` A ring or donut-shaped neighborhood defined by an inner radius and an outer radius. The minimum value for radius is 1 cell, and the outer radius must be larger than the inner. The maximum inner radius is 2046 cells, and the maximum outer radius is 2047 cells. The default annulus is an inner radius of 1 cell and an outer radius of 3 cells. `NbrCircle({radius}, {units}` A circular neighborhood with the given radius. The minimum value for radius is 1 cell, and the maximum value is 2047 cells. The default radius is 3 cells. `NbrRectangle({width}, {height}, {units})` A rectangular neighborhood defined by width and height. The minimum value for width or height is 1 cell, and the maximum value is 4096 cells. The default is a square with a width and height of 3 cells. `NbrWedge({radius}, {startAngle}, {endAngle}, {units})` A wedge-shaped neighborhood defined by a radius, a start angle, and an end angle. The minimum value for radius is 1 cell, and the maximum value is 2047 cells. The wedge extends counterclockwise from the starting angle to the ending angle. Angles are specified in degrees, with 0 or 360 representing east. Negative angles can be used. The default wedge is from 0 to 90 degrees, with a radius of 3 cells. `NbrIrregular(inKernelFile)` A custom neighborhood with specifications set by the identified kernel text file. The minimum value for width or height of the kernel is 1 cell, and the maximum value is 4096 cells. `NbrWeight(inKernelFile)` A custom neighborhood with specifications set by the identified kernel text file, which can apply weights to the members of the neighborhood. The minimum value for width or height of the kernel is 1 cell, and the maximum value is 4096 cells. For the `NbrAnnulus`, `Nbrcircle`, `NbrRectangle` and `NbrWedge` neighborhoods, the distance units for the parameters can be specified in `CELL` units or `MAP` units. Cell units is the default. For kernel neighborhoods, the first line in the kernel file defines the width and height of the neighborhood in numbers of cells. The subsequent lines indicate how the input value that corresponds to that location in the kernel will be processed. A value of 0 in the kernel file for either the irregular or the weight neighborhood type indicates the corresponding location will not be included in the calculation. For the irregular neighborhood, a value of 1 in the kernel file indicates that the corresponding input cell will be included in the operation. For the weight neighborhood, the value at each position indicates what the corresponding input cell value is to be multiplied by. Positive, negative, and decimal values can be used.	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 will be available. If the input raster is floating point, only the `MEAN`, `MAXIMUM`, `MEDIAN`, `MINIMUM`, `PERCENTILE`, `RANGE`, `STD`, and `SUM` statistic types will be available. `MEAN`—The mean (average value) of the cells in the neighborhood will be calculated. `MAJORITY`—The majority (value that occurs most often) of the cells in the neighborhood will be identified. `MAXIMUM`—The maximum (largest value) of the cells in the neighborhood will be identified. `MEDIAN`—The median of the cells in the neighborhood will be calculated. Median is equivalent to the 50th percentile. `MINIMUM`—The minimum (smallest value) of the cells in the neighborhood will be identified. `MINORITY`—The minority (value that occurs least often) of the cells in the neighborhood will be identified. `PERCENTILE`—A percentile of the cells in the neighborhood will be calculated. The 90th percentile is calculated by default. You can specify other values (from 0 to 100) using the `percentile_value` parameter. `RANGE`—The range (difference between largest and smallest value) of the cells in the neighborhood will be calculated. `STD`—The standard deviation of the cells in the neighborhood will be calculated. `SUM`—The sum of the cells in the neighborhood will be calculated. `VARIETY`—The variety (the number of unique values) of the cells in the neighborhood will be calculated.	String
ignore_nodata (Optional)	Specifies whether NoData values will be ignored by the statistic calculation. `DATA`—If a NoData value exists within a neighborhood, the NoData value will be ignored. Only cells within the neighborhood that have data values will be used in determining the output value. If the processing cell itself is NoData, the processing cell may receive a value in the output raster, provided at least one cell within the neighborhood has a valid value. This is the default. `NODATA`—If any cell in a neighborhood has a value of NoData, including the processing cell, the output for the processing cell will be NoData. The presence of a NoData value implies that there is insufficient information to determine the statistic value for the neighborhood.	Boolean
percentile_value (Optional)	The percentile value that will be calculated. The default is 90, for the 90th percentile. The value can range from 0 to 100. The 0th percentile is essentially equivalent to the minimum statistic, and the 100th percentile is equivalent to the maximum statistic. A value of 50 will produce essentially the same result as the median statistic. This option is only supported if the `statistics_type` parameter is set to `PERCENTILE`. If any other statistic type is specified, this parameter will be ignored.	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")

# Run FocalStatistics
outFocalStatistics = FocalStatistics(inRaster, neighborhood, "MINORITY",
                                     "")

# Save the output
outFocalStatistics.save("C:/sapyexamples/output/focalstatout")

Environments

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

Licensing information

Basic: Requires Spatial Analyst or Image Analyst
Standard: Requires Spatial Analyst or Image Analyst
Advanced: Requires Spatial Analyst or Image Analyst

Focal Statistics (Spatial Analyst Tools)

Summary

Illustration

Usage

Parameters

Return value

Environments

Licensing information

Related topics