Show Navigation | Hide Navigation

You are here:
Extensions > Spatial Analyst > Spatial Analyst functional reference > Neighborhood (Spatial Analyst)

Focal Statistics
Release 9.3 Last modified September 7, 2011	Print all topics in : "Neighborhood (Spatial Analyst)"

Related Topics

Calculates a statistic on a raster over a specified neighborhood.

Learn more about how Focal Statistics works

Usage tips

Command line and Scripting

The values on the output raster depend on the operation.
When a circular, annulus-shaped, or wedge-shaped neighborhood is specified, and the center of the cell must be encompassed within the neighborhood, some of the outer diagonal cells may not be considered in the calculations. However, these cell locations will receive the resulting value from the calculations because they fall within the minimum-bounding rectangle (or the output neighborhood) of the three circular-type neighborhoods.
The Irregular and Weight neighborhood types require a Kernel file. 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.
Only for the statistics types of mean, standard deviation and sum can the Neighborhood type be set to Weight.
The following environment settings affect this tool:
- General: Current Workspace, Scratch Workspace, Output Coordinate system, Output Extent, Snap Raster.
- Raster Analysis: Cell size, Mask.
- Raster Storage: See the Raster Storage settings for the particular output raster format selected.

ArcObjects

When a circular, annulus-shaped, or wedge-shaped neighborhood is specified, and the center of the cell must be encompassed within the neighborhood, some of the outer diagonal cells may not be considered in the calculations. However, these cell locations will receive the resulting value from the calculations because they fall within the minimum-bounding rectangle (or the output neighborhood) of the three circular neighborhoods.
The output from the ArcObjects method is a raster object.
See the individual corresponding Map Algebra Focal function for the specific behavior of any statistic.

Command line syntax
An overview of the Command Line window
FocalStatistics_sa <in_raster> <out_raster> {neighborhood} {MEAN | MAJORITY | MAXIMUM | MEDIAN | MINIMUM | MINORITY | RANGE | STD | SUM | VARIETY} {DATA | NODATA}

Parameter	Explanation	Data Type
<in_raster>	The raster to perform the Focal Statistics calculations on.	Composite Geodataset
<out_raster>	The raster to be created.	Raster Dataset
{neighborhood}	Dictates the shape of the area around each cell used to calculate the statistic. ANNULUS, {inner_radius}, {outer_radius}, {CELL \| MAP} — A torus (donut-shaped) neighborhood defined by an {inner_radius} and an {outer_radius}. CIRCLE, {radius}, {CELL \| MAP} — A circular neighborhood with the given {radius}. The default is three cells. RECTANGLE, {width}, {height}, {CELL \| MAP} — A rectangular neighborhood with the given {height} and {width}. The default rectangle is a square of width 3 and height 3, in units of cells. If only one of {width} or {height} is specified, the result is a square. WEDGE, {radius}, {start_angle}, {end_angle}, {CELL \| MAP} — A wedge-shaped neighborhood. A wedge is specified by a {start_angle}, an {end_angle}, and a {radius}. 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 may be used. IRREGULAR, kernel_file — A custom neighborhood with specifications set by a user-defined file. WEIGHT, kernel_file — A custom neighborhood defined with an user-defined file, which can apply weights to the members of the neighborhood. {CELL \| MAP} — Defines the units as either {CELL} or {MAP}. The default neighborhood is a square RECTANGLE with a width and height of three cells.	Neighborhood
{MEAN \| MAJORITY \| MAXIMUM \| MEDIAN \| MINIMUM \| MINORITY \| RANGE \| STD \| SUM \| VARIETY}	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 value 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
{DATA \| NODATA}	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. NODATA — Specifies that if any cell in a neighborhood has a value of NoData, the output for each cell in the corresponding block will receive NoData. Whenever the NoData keyword is used, the presence of a NoData value implies that there is insufficient information to determine the statistic value for the neighborhood.	Boolean

Data types for geoprocessing tool parameters

Command line example

FocalStatistics_sa C:/data/raster1 C:/data/focalstat "Rectangle 5 6 Map" DATA

Scripting syntax
About getting started with writing geoprocessing scripts
FocalStatistics_sa (in_raster, out_raster, neighborhood, statistics_type, ignore_nodata)

Parameter	Explanation	Data Type
in_raster (Required)	The raster to perform the Focal Statistics calculations on.	Composite Geodataset
out_raster (Required)	The raster to be created.	Raster Dataset
neighborhood (Optional)	Dictates the shape of the area around each cell used to calculate the statistic. ANNULUS, {inner_radius}, {outer_radius}, {CELL \| MAP} — A torus (donut-shaped) neighborhood defined by an {inner_radius} and an {outer_radius}. CIRCLE, {radius}, {CELL \| MAP} — A circular neighborhood with the given {radius}. The default is three cells. RECTANGLE, {width}, {height}, {CELL \| MAP} — A rectangular neighborhood with the given {height} and {width}. The default rectangle is a square of width 3 and height 3, in units of cells. If only one of {width} or {height} is specified, the result is a square. WEDGE, {radius}, {start_angle}, {end_angle}, {CELL \| MAP} — A wedge-shaped neighborhood. A wedge is specified by a {start_angle}, an {end_angle}, and a {radius}. 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 may be used. IRREGULAR, kernel_file — A custom neighborhood with specifications set by a user-defined file. WEIGHT, kernel_file — A custom neighborhood defined with an user-defined file, which can apply weights to the members of the neighborhood. {CELL \| MAP} — Defines the units as either {CELL} or {MAP}. The default neighborhood is a square RECTANGLE with a width and height of three 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 value 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. NODATA — Specifies that if any cell in a neighborhood has a value of NoData, the output for each cell in the corresponding block will receive NoData. Whenever the NoData keyword is used, the presence of a NoData value implies that there is insufficient information to determine the statistic value for the neighborhood.	Boolean

Data types for geoprocessing tool parameters

Script example

# FocalStatistics_sample.py
# Description: 
#   Calculates a statistic on a raster over a specified neighborhood.
# Requirements: None
# Author: ESRI
# Date: Sept 6, 2005
# Import system modules
import arcgisscripting

# Create the Geoprocessor object
gp = arcgisscripting.create()

try:
    # Set local variables
    InRaster = "C:/data/raster1"
    OutRaster = "C:/data/focalstat"
    InNeighborhood = "Rectangle 5 6 Map"	
    InNoDataOption = "DATA"

    # Check out Spatial Analyst extension license
    gp.CheckOutExtension("Spatial")

    # Process: FocalStatistics
    gp.FocalStatistics_sa(InRaster, OutRaster, InNeighborhood, "", InNoDataOption)

except:
    # If an error occurred while running a tool, then print the messages.
    print gp.GetMessages()

Map Algebra syntax
See FocalMajority, FocalMax, FocalMean, FocalMedian, FocalMin, FocalMinority, FocalRange, FocalStd, FocalSum, FocalVariety, depending on the desired Focal statistic.

ArcObjects syntax
INeighborhoodOp::FocalStatistics (geoDataset As IGeoDataset, type As esriGeoAnalysisStatisticsEnum, nbrhood As IRasterNeighborhood, ignoreNoData As Boolean) As IGeoDataset

Parameter	Explanation
geoDataset	An input Raster, RasterDataset, RasterBand, or RasterDescriptor that identifies the values of the focal or processing cell and the values of the cells in its specified neighborhood.
type	An esriGeoAnalysisStatisticsEnum defining the focal statistic to calculate within each neighborhood. The enumeration types are: esriGeoAnalysisStatsMajority — Majority esriGeoAnalysisStatsMaximum — Maximum esriGeoAnalysisStatsMean — Mean esriGeoAnalysisStatsMedian — Median esriGeoAnalysisStatsMinimum — Minimum esriGeoAnalysisStatsMinority — Minority esriGeoAnalysisStatsRange — Range esriGeoAnalysisStatsStd — Standard Deviation esriGeoAnalysisStatsSum — Sum esriGeoAnalysisStatsVariety — Variety
nbrhood	A RasterNeighborhood defining the configuration of the neighborhoods within which the focal statistics will be calculated. INeighborhoodOp::FocalStatistics supports any neighborhood supported by RasterNeighborhood, such as rectangle, circle, annulus, wedge, and an irregularly-shaped neighborhood. The neighborhood will be defined by the minimum-bounding rectangle of the specified neighborhood. The minimum-bounding rectangle will include more cells than the specified neighborhood in certain cases, such as with a circle, annulus, and wedge.
ignoreNoData	A Boolean defining the manner in which NoData values within a neighborhood will influence the output results. If True, and if a NoData value exists within the neighborhood of the processing cell, the NoData value will be ignored. Only cells within the neighborhood that have data values will be used in determining the statistic. If False, and if any cell in a neighborhood has a value of NoData, the output for the processing cell of the neighborhood will be NoData. When False, the presence of a NoData value implies that there is insufficient information to determine the statistic of the values of the neighborhood.

ArcObjects example

' Create the RasterNeighborhoodOp object
Dim pNbrOp As INeighborhoodOp
Set pNbrOp = New RasterNeighborhoodOp

' Create the neighborhood object
Dim pNbr As IRasterNeighborhood
Set pNbr = New RasterNeighborhood
pNbr.SetCircle 3, esriUnitsCells

' Call a function to open a raster dataset
Dim pInputDataset As IGeoDataset
Set pInputDataset = OpenRasterDataset ("D:\SpatialData\", "inputraster")

' Create output using the method
Dim pOutputRaster As IRaster 
Set pOutputRaster = pNbrOp.FocalStatistics(pInputDataset, _
                      esriGeoAnalysisStatsMajority, pNbr, False)