Band Collection Statistics (Spatial Analyst Tools)

Summary

Calculates the statistics for a set of raster bands.

Learn more about how Band Collection Statistics works

Usage

When a multiband raster is specified as one of the Input raster bands (in_raster_bands in Python), all the bands will be used.

To process a selection of bands from a multiband raster, you can first create a new raster dataset composed of those particular bands with the Composite Bands tool, and use the result in the list of the Input raster bands (in_raster_bands in Python).
The raster bands must have a common intersection. If there are none, an error occurs and no output is created.
If the extents of the raster bands are not the same, the statistics will be calculated on the common spatial extent of all the input raster bands. The cell size will be that of the maximum of the input rasters.
For the Compute covariance and correlation matrices parameter, the default unchecked setting (BRIEF in scripting) indicates that only the minimum, maximum, mean, and standard deviation of the input raster bands will be computed. To calculate the covariance and correlation matrices in addition to these statistics, check this parameter on the tool dialog box (or use DETAILED in scripting).

A covariance matrix presents the variances of all raster bands along the diagonal from the upper left to lower right and covariances between all raster bands in the remaining entries. The correlation matrix provides the correlation coefficients between each combination of two input bands.
In the calculation of the covariance matrix, the mean value of the band is used for any input cells that are NoData.
When the Compute histogram parameter is checked, histogram statistics will be added to the output statistics file. Optionally, an output histogram table and output histogram chart can be created if they are specified.
In the output histogram table, the l<n>_count fields record the count of cells in layer <n> that fall in a particular bin. The l<n>_percent fields record the percentage of the cells reported in the count field among the total number of cells of layer <n> in the analysis area.
The statistics are written to the output file in a comma-separated values (CSV) format or a markdown format. The extension for the output must be .txt, .md, .csv, or .asc.
All the statistics calculated by this tool will be displayed in the Geoprocessing history pane except the histogram. If created, the histogram table and chart will appear in Standalone Tables in the Contents pane. See Work with stand-alone tables in maps to learn more.

Label	Explanation	Data type
Input Raster Bands	The input raster bands. They can be integer or floating point type.	Raster Layer
Output Statistics File	The output text or markdown file containing the statistics. A `.txt`, `.md`, `.csv`, or `.asc` extension is required. The default is `.txt`. The output statistics file uses a CSV format except when an `.md` extension is specified. In this case, the output file will be in markdown format.	File
Compute covariance and correlation matrices (Optional)	Specifies whether covariance and correlation matrices will be calculated. Checked—In addition to the basic statistical measures calculated with this parameter unchecked, the covariance and correlation matrices will also be calculated. Unchecked—Only the basic statistical measures (minimum, maximum, mean, and standard deviation) will be calculated for every layer. This is the default.	Boolean
Compute histogram (Optional)	Specifies whether histogram statistics will be calculated. When this parameter is checked, the Number of Histogram Bins, Output Histogram Table, and Output Histogram Name parameters will be supported. When this parameter is unchecked, these other parameters will not be supported. Checked—Histogram statistics will be calculated. Unchecked—Histogram statistics will not be calculated. This is the default.	Boolean
Number of Histogram Bins (Optional)	Specifies the number of histogram bins that will be used in the histogram calculation. The default value is 256. The minimum allowed value is 1. The maximum allowed value is 4096. The value of this parameter should be set according to the input data and the analysis application.	Long
Output Histogram Table (Optional)	The output table that will contain the histogram statistics for all the input bands. The format of the table is determined by the output location and path. By default, the output will be a geodatabase table if in a geodatabase workspace, and a dBASE table (`.dbf` file) if in a file workspace. To create an output histogram table, the Compute histogram parameter must be checked.	Table
Output Histogram Name (Optional)	The name of the output histogram for display. The histogram will be listed in the Contents pane under Standalone Tables. To create an output histogram chart, the Output Histogram Table parameter value must be specified.	String

BandCollectionStats(in_raster_bands, out_stat_file, {compute_matrices}, {compute_histogram}, {number_bins}, {out_histogram_table}, {out_histogram})

Name	Explanation	Data type
in_raster_bands [in_raster_band,...]	The input raster bands. They can be integer or floating point type.	Raster Layer
out_stat_file	The output text or markdown file containing the statistics. A `.txt`, `.md`, `.csv`, or `.asc` extension is required. The default is `.txt`. The output statistics file uses a CSV format except when an `.md` extension is specified. In this case, the output file will be in markdown format.	File
compute_matrices (Optional)	Specifies whether covariance and correlation matrices will be calculated. `DETAILED`—In addition to the basic statistical measures calculated with the `BRIEF` option, the covariance and correlation matrices will also be calculated. `BRIEF`—Only the basic statistical measures (minimum, maximum, mean, and standard deviation) will be calculated for every layer. This is the default.	Boolean
compute_histogram (Optional)	Specifies whether histogram statistics will be calculated. When this parameter is set to `COMPUTE_HISTOGRAM`, the `number_bins`, `out_histogram_table`, and `out_histogram` parameters will be supported. When this parameter is set to `NO_HISTOGRAM`, these other parameters will not be supported. `COMPUTE_HISTOGRAM`—Histogram statistics will be calculated. `NO_HISTOGRAM`—Histogram statistics will not be calculated. This is the default.	Boolean
number_bins (Optional)	Specifies the number of histogram bins that will be used in the histogram calculation. The default value is 256. The minimum allowed value is 1. The maximum allowed value is 4096. The value of this parameter should be set according to the input data and the analysis application.	Long
out_histogram_table (Optional)	The output table that will contain the histogram statistics for all the input bands. The format of the table is determined by the output location and path. By default, the output will be a geodatabase table if in a geodatabase workspace, and a dBASE table (`.dbf` file) if in a file workspace. To create an output histogram table, the `compute_histogram` parameter must be set to `COMPUTE_HISTOGRAM`.	Table
out_histogram (Optional)	The name of the output histogram for display. To create an output histogram chart, the `out_histogram_table` parameter value must be specified.	String

Code sample

BandCollectionStats example 1 (Python window)

This example calculates the statistics for a set of raster bands.

import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
BandCollectionStats("redlands", "c:/sapyexamples/output/redbandstats.txt", "BRIEF", "COMPUTE_HISTOGRAM", "256", "c:/sapyexamples/output/outtable01.dbf", "histogram01")

BandCollectionStats example 2 (stand-alone script)

This example calculates the statistics for a set of raster bands.

# Name: BandCollectionStats_Ex_02.py
# Description: Calculates the statistics for a set of raster bands.
# 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
inRasterBand1 = "sb/sbc1"
inRasterBand2 = "sb/sbc2"
outStatFile = "C:/sapyexamples/output/bandstatfile.txt"
outHistTable = "C:/sapyexamples/output/output.gdb/outtable01"

# Run BandCollectionStats
BandCollectionStats([inRasterBand1, inRasterBand2], outStatFile, "DETAILED", "COMPUTE_HISTOGRAM", "256", outHistTable)

Environments

Cell Size, Cell Size Projection Method, Current Workspace, Extent, Geographic Transformations, Mask, Output Coordinate System, Parallel Processing Factor, Scratch Workspace, Snap Raster

Licensing information