ISIS Application Documentation
stats | Standard View | TOC | Home |
Generates statistics about a cube
Description
Categories
Groups
Examples
History
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.
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 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.
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.
Name | Description |
---|---|
FROM | Input cube |
TO | Output file that contains the statistics |
FORMAT | Output file format (PVL or comma delimited text) |
APPEND | Append results to output file specified by TO. |
Name | Description |
---|---|
VALIDMIN | Minimum valid DN value |
VALIDMAX | Maximum valid DN value |
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: |
|
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 |
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 |
Calculate statistics for all bands in a cube
Output from stats application | This is the results captured in "peaks0_stats.log" by the redirection of standard output. |
---|
Calculate statistics for a single band from an input cube
Output from stats application | This is the results captured in "peaks3_stats.log" by the redirection of standard output. |
---|
Calculate statistics for multiple bands from an input cube
Output from stats application | This is the results captured in "peaks2_stats.log" by the redirection of standard output. |
---|
Jeff Anderson | 2002-06-17 | Original version written as "histo" |
Stuart Sides | 2002-07-24 | Changed name to "stats" and added logging mechanism |
Jeff Anderson | 2002-12-30 | Added TO parameter which allows the user to create an output file that can be read using the getkey program |
Jeff Anderson | 2002-12-30 | Tested for bands which contain only special pixels in order to prevent divide by zero errors. |
Jeff Anderson | 2002-12-31 | Added the name of the input cube to the log and label file |
Kim Sides | 2003-05-13 | Added application test |
Stuart Sides | 2003-05-16 | Modified schema location from astrogeology... to isis.astrogeology..." |
Stuart Sides | 2003-05-30 | Made changes to application test truth files to reflect -O1 optimization |
Stuart Sides | 2003-05-30 | Added modifications to apptest by Kim |
Stuart Sides | 2003-07-29 | Modified filename parameters to be cube parameters where necessary |
Stuart Sides | 2003-11-07 | Modified results pvl to not include the results group |
Jacob Danton | 2006-01-23 | Fixed appTest to comply to changes in iString |
Steven Lambright | 2008-05-06 | Added Above Range, Below Range reports |
Steven Lambright | 2008-05-13 | Removed references to CubeInfo |
Steven Lambright | 2008-08-15 | A bug where the VALIDMIN,VALIDMAX were ignored was fixed; these should always be used. |
Stacy Alley | 2009-01-16 | Added the Format option for the output file. |
Sharmila Prasad | 2011-03-31 | Added Band Keyword - displays the first physical band used to get the stats |
James Alexander Crough | 2011-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 Oyama | 2013-11-12 | Fixed spelling error in FORMAT=FLAT brief. Documentation updated and reviewed. Fixes #1681. |
Jeffrey Covington | 2015-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 Sanders | 2020-06-04 | Updated to fill columns with N/A in cases where images contained only special or invalid pixels. |