Calculate Statistics (Data Management)

Summary

Calculates statistics for a raster dataset or a mosaic dataset.

Statistics are required for raster and mosaic datasets to perform certain tasks, such as applying a contrast stretch or classifying data.

Usage

  • A skip factor controls the portion of the raster that is used when calculating the statistics. The input value indicates the horizontal or vertical skip factor, where a value of 1 will use each pixel and a value of 2 will use every second pixel. The skip factor can only range from 1 to the number of columns/rows in the raster.

  • The skip factors for raster datasets stored in a file geodatabase or an enterprise geodatabase are quite different. First, if the x and y skip factors are different, the smaller skip factor will be used for both the x and y skip factors. Second, the skip factor is related to the pyramid level that most closely fits the skip factor chosen. If the skip factor value is not equal to the number of pixels in a pyramid (for example, if the skip factor is 5 and the closest pyramid level is 4 x 4 pixels, which is level 2), the software will round down to the next pyramid level (in this case, 2) and use that value as the skip factor.

  • A skip factor is not used for all raster formats. The raster formats that will calculate statistics and take advantage of the skip factor include TIFF, IMG, NITF, DTED, RAW, ADRG, CIB, CADRG, DIGEST, GIS, LAN, CIT, COT, ERMapper, ENVI DAT, BIL, BIP, BSQ, and geodatabase.

  • When using this tool to calculate statistics on a mosaic dataset, the statistics are calculated for the top-level mosaicked image, not for every raster contained in the mosaic dataset.

  • Specifying a skip factor for a mosaic dataset is recommended. as these datasets tend to be very large.

  • The Ignore Values option allows you to exclude a specific value from the calculation of statistics. You may want to ignore a value if it is a NoData value or if it will skew your calculation.

  • Calculating statistics on the Esri Grid and the RADARSAT2 formats always uses a skip factor of 1.

  • When using this tool to calculate statistics on a multidimensional mosaic dataset or a multidimensional raster, the statistics are calculated for each variable in the dataset.

Parameters

LabelExplanationData Type
Input Raster Dataset

The input raster dataset or mosaic dataset.

Mosaic Dataset; Mosaic Layer; Raster Dataset
X Skip Factor
(Optional)

The number of horizontal pixels between samples.

A skip factor controls the portion of the raster that is used when calculating the statistics. The input value indicates the horizontal or vertical skip factor, where a value of 1 will use each pixel and a value of 2 will use every second pixel. The skip factor can only range from 1 to the number of columns/rows in the raster.

The value must be greater than zero and less than or equal to the number of columns in the raster. The default is 1 or the last skip factor used.

The skip factors for raster datasets stored in a file geodatabase or an enterprise geodatabase are different. First, if the x and y skip factors are different, the smaller skip factor will be used for both the x and y skip factors. Second, the skip factor is related to the pyramid level that most closely fits the skip factor chosen. If the skip factor value is not equal to the number of pixels in a pyramid layer, the number is rounded down to the next pyramid level, and those statistics are used.

Long
Y Skip Factor
(Optional)

The number of vertical pixels between samples.

A skip factor controls the portion of the raster that is used when calculating the statistics. The input value indicates the horizontal or vertical skip factor, where a value of 1 will use each pixel and a value of 2 will use every second pixel. The skip factor can only range from 1 to the number of columns/rows in the raster.

The value must be greater than zero and less than or equal to the number of rows in the raster. The default is 1 or the last y skip factor used.

The skip factors for raster datasets stored in a file geodatabase or an enterprise geodatabase are different. First, if the x and y skip factors are different, the smaller skip factor will be used for both the x and y skip factors. Second, the skip factor is related to the pyramid level that most closely fits the skip factor chosen. If the skip factor value is not equal to the number of pixels in a pyramid layer, the number is rounded down to the next pyramid level, and those statistics are used.

Long
Ignore Values
(Optional)

The pixel values that are not to be included in the statistics calculation.

The default is no value or the last ignore value used.

Long
Skip Existing
(Optional)

Specifies whether statistics will be calculated only when they are missing or will be regenerated even if they exist.

  • Unchecked—Statistics will be calculated even if they already exist, and existing statistics will be overwritten. This is the default.
  • Checked—Statistics will only be calculated if they do not already exist.
Boolean
Area of Interest
(Optional)

The area in the dataset that will be used to calculate statistics, so they are not generated from the entire dataset. You can either browse to a feature class or create a polygon graphic on the display.

Feature Set

Derived Output

LabelExplanationData Type
Updated Input Raster Dataset

The output raster dataset.

Raster Dataset

arcpy.management.CalculateStatistics(in_raster_dataset, {x_skip_factor}, {y_skip_factor}, {ignore_values}, {skip_existing}, {area_of_interest})
NameExplanationData Type
in_raster_dataset

The input raster dataset or mosaic dataset.

Mosaic Dataset; Mosaic Layer; Raster Dataset
x_skip_factor
(Optional)

The number of horizontal pixels between samples.

A skip factor controls the portion of the raster that is used when calculating the statistics. The input value indicates the horizontal or vertical skip factor, where a value of 1 will use each pixel and a value of 2 will use every second pixel. The skip factor can only range from 1 to the number of columns/rows in the raster.

The value must be greater than zero and less than or equal to the number of columns in the raster. The default is 1 or the last skip factor used.

The skip factors for raster datasets stored in a file geodatabase or an enterprise geodatabase are different. First, if the x and y skip factors are different, the smaller skip factor will be used for both the x and y skip factors. Second, the skip factor is related to the pyramid level that most closely fits the skip factor chosen. If the skip factor value is not equal to the number of pixels in a pyramid layer, the number is rounded down to the next pyramid level, and those statistics are used.

Long
y_skip_factor
(Optional)

The number of vertical pixels between samples.

A skip factor controls the portion of the raster that is used when calculating the statistics. The input value indicates the horizontal or vertical skip factor, where a value of 1 will use each pixel and a value of 2 will use every second pixel. The skip factor can only range from 1 to the number of columns/rows in the raster.

The value must be greater than zero and less than or equal to the number of rows in the raster. The default is 1 or the last y skip factor used.

The skip factors for raster datasets stored in a file geodatabase or an enterprise geodatabase are different. First, if the x and y skip factors are different, the smaller skip factor will be used for both the x and y skip factors. Second, the skip factor is related to the pyramid level that most closely fits the skip factor chosen. If the skip factor value is not equal to the number of pixels in a pyramid layer, the number is rounded down to the next pyramid level, and those statistics are used.

Long
ignore_values
[ignore_value,...]
(Optional)

The pixel values that are not to be included in the statistics calculation.

The default is no value or the last ignore value used.

Long
skip_existing
(Optional)

Specifies whether statistics will be calculated only when they are missing or will be regenerated even if they exist.

  • OVERWRITEStatistics will be calculated even if they already exist, and existing statistics will be overwritten. This is the default.
  • SKIP_EXISTINGStatistics will only be calculated if they do not already exist.
Boolean
area_of_interest
(Optional)

The feature class that represents the area in the dataset that will be used to calculate statistics, so they are not generated from the entire dataset.

Feature Set

Derived Output

NameExplanationData Type
out_raster

The output raster dataset.

Raster Dataset

Code sample

CalculateStatistics example 1 (Python window)

This is a Python sample for the CalculateStatistics function.

import arcpy
arcpy.CalculateStatistics_management(
     "C:/data/image.tif", "5", "5", "0;255", 
     "SKIP_EXISTING", "c:/data/aoi.shp")
CalculateStatistics example 2 (stand-alone script)

This is a Python script sample for the CalculateStatistics function.

# Calculate Statistics for single raster dataset

import arcpy
arcpy.env.workspace = "C:/Workspace"
    
arcpy.CalculateStatistics_management("image.tif", "4", "6", "0;255;21")

Related topics