Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS
A lock ( ) or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

ISIS Documentation

stats

Generates statistics about a cube

This program computes a set of statistics for the pixels in each selected band of an image cube, and outputs the results of each band. By default, all bands are processed. The stats program generates statistics that will help you find new insights in your data to make more accurate predictions and achieve better outcomes.

Histogram Computation

Stats uses a histogram to compute the mode and median DN values for a given cube. The minimum, maximum, and number of bins depends on the pixel type of the cube. Here are the minimum, maximum, and number of bins associated with supported pixel types:

Pixel Type Minimum Maximum Number of Bins
Unsigned Byte 0 * cube multiplier + base 255 * cube multiplier + base 256
Unsigned Word 0 * cube multiplier + base 65535 * cube multiplier + base 65536
Signed Word -32768.0 * cube multiplier + base 32767.0 * cube multiplier + base 65536
Unsigned Integer Minimum DN value in the cube Maximum DN value in the cube 65536
Signed Integer Minimum DN value in the cube Maximum DN value in the cube 65536
Real Minimum DN value in the cube Maximum DN value in the cube 65536

The cube multiplier and base can be found in the header of the cube.

Output:

The statistics are output to both the screen and the print.prt file in PVL format. Additionally, if the user specifies a file using the TO parameter, the statistics are written to that file in PVL format (default) or as a comma delimited text file (FLAT file), as specified by the FORMAT parameter. For multi-band images, each band has its own statistics information that will be appended to the output file. The contents of the PVL file can be read using the getkey program. The comma delimited text file can be imported into Excel or other applications. The statistics calculated and reported are as follows: 

      Average                 Total pixels

      Standard deviation      Valid pixels

      Variance                Over valid maximum pixels

      Median                  Under valid minimum pixels

      Mode                    Null pixels

      Skew                    Low representation saturation (LRS) pixels

      Minimum                 High representation saturation (HRS) pixels

      Maximum                 Low instrument saturation (LIS) pixels

      Sum                     High instrument saturation (HIS) pixels

If the output file exists and the APPEND parameter is set to "no," the contents will be overwritten.

How to Specify Bands:

You may process one or a few specific bands if you indicate the band(s) in which you desire to gather statistics. A band may be specified by simply placing a plus sign and the band number after the input filename (e.g., peaks.cub+3). For several bands, commas and hyphens are used to communicate effectively with the program as in the following example: peaks.cub+2,4-6.

Categories

Related Applications to Previous Versions of ISIS

This program replaces the following applications existing in previous versions of ISIS:
  • average
  • avg_sd
  • bandstats

Related Objects and Documents

Applications

History

Jeff Anderson2002-06-17 Original version written as "histo"
Stuart Sides2002-07-24 Changed name to "stats" and added logging mechanism
Jeff Anderson2002-12-30 Added TO parameter which allows the user to create an output file that can be read using the getkey program
Jeff Anderson2002-12-30 Tested for bands which contain only special pixels in order to prevent divide by zero errors.
Jeff Anderson2002-12-31 Added the name of the input cube to the log and label file
Kim Sides2003-05-13 Added application test
Stuart Sides2003-05-16 Modified schema location from astrogeology... to isis.astrogeology..."
Stuart Sides2003-05-30 Made changes to application test truth files to reflect -O1 optimization
Stuart Sides2003-05-30 Added modifications to apptest by Kim
Stuart Sides2003-07-29 Modified filename parameters to be cube parameters where necessary
Stuart Sides2003-11-07 Modified results pvl to not include the results group
Jacob Danton2006-01-23 Fixed appTest to comply to changes in iString
Steven Lambright2008-05-06 Added Above Range, Below Range reports
Steven Lambright2008-05-13 Removed references to CubeInfo
Steven Lambright2008-08-15 A bug where the VALIDMIN,VALIDMAX were ignored was fixed; these should always be used.
Stacy Alley2009-01-16 Added the Format option for the output file.
Sharmila Prasad2011-03-31 Added Band Keyword - displays the first physical band used to get the stats
James Alexander Crough2011-06-17 Changed the behavior of the program to process all bands of a cube, or, if an input cube attribute is specified, only those bands will be processed. Previously, the program only processed the first band.
Kimberly Oyama2013-11-12 Fixed spelling error in FORMAT=FLAT brief. Documentation updated and reviewed. Fixes #1681.
Jeffrey Covington2015-02-19 Updated documentation of FORMAT and APPEND parameters as well as general edits for clarity. Also added undocumented output statistics to the list in the description.
Austin Sanders2020-06-04 Updated to fill columns with N/A in cases where images contained only special or invalid pixels.

Parameters

Files

This specifies the input cube. The default is to calculate statistics for each band in the input cube, but this can be overridden using the band specifier (e.g., file.cub+3).
Type cube
File Mode input
Filter *.cub

This text file will contain the statistics for each individual band. If it is written in PVL format (default), the values can be read using the getkey program. This is useful for developing scripts. If it is written as a comma delimited text file (FLAT) the output can be easily imported into spreadsheet applications like Excel.
Type filename
File Mode output
Internal Default No output file is created
Filter *.txt

This is the format type for the output file. PVL format is the default. The format is ignored unless the TO parameter is specified.
Type string
Default PVL
Option List:
Option Brief Description
PVL Format the output file specified by TO as PVL. Output the results to a PVL formatted file specified by TO. This format can be read using the getkey program.
FLAT Format the output file specified by TO as a comma delimited text file. Output the results to a comma delimited text file specified by TO. This file format can easily be imported into spreadsheet applications like Excel.

If this option is not selected, the output from the stats application is appended to the output file. If this option is set to "NO" or "FALSE," any information in the TO file is overwritten.

Note: This will append the formatted results to the end of the TO file without regard to the formatting of the current contents.

Type boolean
Default TRUE

Settings

The statistics will exclude any DN values below this value.
Type double
Internal Default No minimum DN value

The statistics will exclude any DN values above this value.
Type double
Internal Default No maximum DN value

Example 1

Calculate statistics for all bands in a cube

This example shows the statistics computed for all bands in the input cube. When no band is specified by the user, stats default behavior is to calculate statistics for all bands in a cube.

Command Line

Command to run stats in the command line mode using all bands in peaks.cub and output the results to peaks0_stats.log.
stats from=peaks.cub to=peaks0_stats.log

Data File

Links open in a new window.
Output from stats application This is the results captured in "peaks0_stats.log" by the redirection of standard output.

Example 2

Calculate statistics for a single band from an input cube

This example shows the statistics computed from band 3 of the input cube. A band may be specified by simply placing the plus sign and the band number after the input filename.

Command Line

Command to run stats in the command line mode using the third band of peaks.cub and output the results to peaks1_stats.log.
stats from=peaks.cub+3 to=peaks1_stats.log

Data File

Links open in a new window.
Output from stats application This is the results captured in "peaks3_stats.log" by the redirection of standard output.

Example 3

Calculate statistics for multiple bands from an input cube

This example shows the statistics computed for selected bands of a cube. In addition to the plus suffix, the comma and hyphen are used to specify multiple bands from the input cube to process.

Command Line

Command to run stats in the command line mode using the second, fourth, fifth, and sixth bands of peaks.cub and output the results to peaks2_stats.log.
stats from=peaks.cub+2,4-6 to=peaks2_stats.log

Data File

Links open in a new window.
Output from stats application This is the results captured in "peaks2_stats.log" by the redirection of standard output.