Block Statistics (Spatial Analyst)

Available with Spatial Analyst license.

Summary

Partitions the input into non-overlapping blocks and calculates the statistic of the values within each block. The value is assigned to all of the cells in each block in the output.

Learn more about how Block Statistics works

Illustration

OutRas = BlockStatistics(InRas1, NbrRectangle(3,3,"CELL"), "MAXIMUM", "DATA")

Usage

• There are several neighborhood shapes and statistics types to choose from. The available statistics depend on the type of the input raster.

• When a circular, annulus-shaped, or wedge-shaped neighborhood is specified, depending on the size of the neighborhood, cells that are not perpendicular to the x- or y-axis may not be considered in the calculations. However, these cell locations will receive the resulting value from the calculations of the neighborhood because they fall within the minimum-bounding rectangle (or the output block) of these circular neighborhood types.

• 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 Block Statistics works for information about creating and using kernel files.

• For integer input rasters, the valid choices for Statistics type are: majority, maximum, mean, median, minimum, minority, range, standard deviation, sum, and variety. For float input rasters, the valid statistics are: maximum, mean, minimum, range, standard deviation, and sum. Majority, median, minority, and variety are not available.

• If the input raster is integer, the output raster will be integer for the following statistics: majority, maximum, median, minimum, minority, range, sum, and variety. The output will be float for the mean and standard deviation statistics.

  If the input raster is of float type, the output will be float for all of the available statistic types.

• For the Median setting of the Statistics type parameter, if a block has an odd number of cells, the values will be ranked and the middle value will be reported as the median. If a block has an even number of cells, the values will be ranked and the middle two values will be averaged to the nearest integer.

• For the Majority setting of the Statistics type parameter, if one cell value occurs most frequently in the block neighborhood (a single value with the highest frequency of occurrence), that value will be returned for that block of processing cells. If two or more cell values have the highest frequency of occurrence (a tie among cell values), no single majority value is identified, and the output for that block will be NoData. For the Minority setting, ties among the least frequently occurring values in a block will also be assigned NoData.

• The Neighborhood parameter can be set to Weight only for the Mean, Median, Minority, Standard deviation, and Sum statistics types.

• 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 raster	The raster for which the block statistics will be calculated.	Raster Layer
Neighborhood (Optional)	The cells of the processing block 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 torus (donut-shaped) neighborhood defined by an inner radius and an outer radius. The default annulus is an inner radius of one cell and an outer radius of three cells. Circle, Radius, Units type A circular neighborhood with the given radius. The default radius is three cells. Rectangle, Height, Width, Units type A rectangular neighborhood defined by height and width. The default is a square with a height and width of three cells. Wedge, Radius, Start angle, End angle, Units type A wedge-shaped neighborhood defined by a radius, the start angle, and the end angle. 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 three cells. Irregular, Kernel file A custom neighborhood with specifications set by the identified kernel text file. 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. 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, Minimum, 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. 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. 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 block 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. Unchecked—If any cell in a block neighborhood has a value of NoData, the output for each cell in the corresponding block will be NoData. The presence of a NoData value implies that there is insufficient information to determine the statistic value for the neighborhood.	Boolean

Return Value

Label	Explanation	Data Type
Output raster	The output block statistics raster.	Raster

Python

BlockStatistics(in_raster, {neighborhood}, {statistics_type}, {ignore_nodata})

Name	Explanation	Data Type
in_raster	The raster for which the block statistics will be calculated.	Raster Layer
neighborhood (Optional)	The cells of the processing block 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 torus (donut-shaped) neighborhood defined by an inner radius and an outer radius. The default annulus is an inner radius of one cell and an outer radius of three cells. NbrCircle({radius}, {units} A circular neighborhood with the given radius. The default radius is three cells. NbrRectangle({width}, {height}, {units}) A rectangular neighborhood defined by height and width. The default is a square with a height and width of three cells. NbrWedge({radius}, {startAngle}, {endAngle}, {units}) A wedge-shaped neighborhood defined by a radius, the start angle, and the end angle. 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 three cells. NbrIrregular(inKernelFile) A custom neighborhood with specifications set by the identified kernel text file. NbrWeight(inKernelFile) A custom neighborhood with specifications set by the identified kernel text file, which can apply weights to the members of the neighborhood. 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. 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. 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. 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. 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, MINIMUM, RANGE, STD, and SUM statistic types will be available.	String
ignore_nodata (Optional)	Specifies whether NoData values will be ignored by the statistic calculation. DATA—If a NoData value exists within a block 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. NODATA—If any cell in a block neighborhood has a value of NoData, the output for each cell in the corresponding block will be NoData. The presence of a NoData value implies that there is insufficient information to determine the statistic value for the neighborhood.	Boolean

Return Value

Name	Explanation	Data Type
out_raster	The output block statistics raster.	Raster

Code sample

BlockStatistics example 1 (Python window)

This sample calculates the minimum cell value within each non-overlapping annulus (doughnut-shaped) neighborhood in the input Grid raster.

import arcpy
from arcpy import env  
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
nbr = NbrAnnulus(1, 3, "MAP")
outBlockStat = BlockStatistics("block", nbr, "MINIMUM", "")
outBlockStat.save("C:/sapyexamples/output/blockstat")

BlockStatistics example 2 (stand-alone script)

This sample calculates the minimum cell value within each non-overlapping annulus (doughnut-shaped) neighborhood in the input Grid raster.

# Name: BlockStatistics_Ex_02.py
# Description: Calculates statistics for a nonoverlapping 
#              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 = "block"
nbr = NbrAnnulus(1, 3, "MAP")

# Execute BlockStatistics
outBlockStat = BlockStatistics(inRaster, nbr, "MINIMUM", "NODATA")

# Save the output 
outBlockStat.save("C:/sapyexamples/output/blockstat")

Environments

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

Licensing information

• Basic: Requires Spatial Analyst
• Standard: Requires Spatial Analyst
• Advanced: Requires Spatial Analyst