| 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.
| 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 enabled for additional options. | 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 |
Available with Spatial Analyst license.
Summary
Calculates the statistics for a set of raster bands.
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.
Parameters
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.
| 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. | 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
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")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"
# Execute BandCollectionStats
BandCollectionStats([inRasterBand1, inRasterBand2], outStatFile, "DETAILED", "COMPUTE_HISTOGRAM", "256", outHistTable)Environments
Licensing information
- Basic: Requires Spatial Analyst
- Standard: Requires Spatial Analyst
- Advanced: Requires Spatial Analyst