Focal Statistics (Spatial Analyst)

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

Focal Statistics illustration
OutRas = FocalStatistics(InRas1, NbrRectangle(3,3,MAP), "SUM", "")

Usage

Syntax

FocalStatistics (in_raster, {neighborhood}, {statistics_type}, {ignore_nodata})
ParameterExplanationData Type
in_raster

The raster to perform the focal statistics calculations on.

Raster Layer
neighborhood
(Optional)

The Neighborhood class dictates the shape of the area around each cell used to calculate the statistic.

The different types of neighborhood available are: NbrAnnulus, NbrCircle, NbrRectangle, NbrWedge, NbrIrregular, and NbrWeight.

The following are the forms of the neighborhoods:

  • NbrAnnulus({innerRadius}, {outerRadius}, {CELL | MAP})
  • NbrCircle({radius}, {CELL | MAP}
  • NbrRectangle({width}, {height}, {CELL | MAP})
  • NbrWedge({radius}, {start_angle}, {end_angle}, {CELL | MAP})
  • NbrIrregular(kernel_file)
  • NbrWeight(kernel_file)

The {CELL | MAP} parameter defines the distance units as either being Cell units or Map units.

The default neighborhood is a square NbrRectangle with a width and height of 3 cells.

Neighborhood
statistics_type
(Optional)

The statistic type to be calculated.

  • MEAN Calculates the mean (average value) of the cells in the neighborhood.
  • MAJORITY Calculates the majority (value that occurs most often) of the cells in the neighborhood.
  • MAXIMUM Calculates the maximum (largest value) of the cells in the neighborhood.
  • MEDIAN Calculates the median of the cells in the neighborhood.
  • MINIMUM Calculates the minimum (smallest value) of the cells in the neighborhood.
  • MINORITY Calculates the minority (value that occurs least often) of the cells in the neighborhood.
  • RANGE Calculates the range (difference between largest and smallest value) of the cells in the neighborhood.
  • STD Calculates the standard deviation of the cells in the neighborhood.
  • SUM Calculates the sum (total of all values) of the cells in the neighborhood.
  • VARIETY Calculates the variety (the number of unique values) of the cells in the neighborhood.

The default statistic type is MEAN.

String
ignore_nodata
(Optional)

Denotes whether NoData values are ignored by the statistic calculation.

  • DATA Specifies that 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. This is the default.
  • NODATASpecifies that if any cell in a neighborhood has a value of NoData, the output for the processing cell will be NoData. With this option, the presence of a NoData value implies that there is insufficient information to determine the statistic value for the neighborhood.
Boolean

Return Value

NameExplanationData Type
out_raster

The output focal statistics raster.

Raster

Code Sample

FocalStatistics example 1 (Python window)

This example calculates the least-frequently occuring 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
# Author: ESRI

# 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

Related Topics

Licensing Information

ArcView: Requires Spatial Analyst
ArcEditor: Requires Spatial Analyst
ArcInfo: Requires Spatial Analyst

6/29/2011