Help for STATS

PURPOSE:  stats computes the statistics of specified training areas on
 multi-spectral data.  The output consists of page printer output, a
 statistics data set compatible with the multispectral classifier
 FASTCLAS, and (optionally) an image containing the scribed training
 areas.  Input multispectral data must be in separate VICAR data sets or
 in MSS format.  Refer to the help for program MSS.
EXECUTION:
The following is the execution statement format for stats:
	stats INP OUT PARAMS
where INP, OUT, PARAMS are parameters discussed in their respective
parameter sections.
 The training areas for the classes may be specified either in rectangular
or vertices format.  stats no longer allows some training fields in a given
training area to be in vertices format and some to be in rectangular
format.  Rectangular format is the default and is thus not 
specified explicitly.   The RECT parameter (which was present in the IBM
version of stats), for expliciltly specifying rectangular format, is no
longer used.  The VERT parameter is used to list any and every class using the
vertices format. 
  The training area for the class is composed of one or more training fields.
Each training field is a closed region of the image.  The format must be 
the same for all fields within a class.  In rectangular format the training 
fields are defined by starting line, starting sample, number of lines,
and number of samples.
  In vertices format, only the vertices (line number and sample number) of an
irregular area need be stated.  
EXAMPLES

1.    stats INP=(A, B, C, D)   OUT=ST  HIST=0 SPEC=0 EXCLUDE=0 VERT=2              CLASS1=( 50,60,20,20  85,100,10,15 )                                   CLASS2=( 125,50  140,60  150,40  130,30  125,50 )

In this example four spectral bands are input in separate VICAR images.
Histograms and spectral plots of all four bands and both classes are
produced.  Any pixel with a DN of 0 is excluded from the statistics.
The class 1 statistics come from two rectangular training fields.  The 
class 2 statistics come from an irregular training field.

2.    stats INP=MS OUT=(ST,SC) MSS=5  SPEC=0 'NOPRINT SCRIBE=2 VERT=1                  CLASS1=( 25,20  35,30  40,50  55,30  30,15  25,20                                   85,40 100,55  70,55  85,40 )                                      CLASS2=( 200,100,20,30 )                                                   CLASS3=( 150,140,5,10 )

In this example five spectral bands are input in MSS format (in one file).
Statistics are computed on all five bands.  Spectral plots of all five bands 
and all three classes are produced, but all other printer (terminal) output is
suppressed.  The second spectral band (in this case, extracted from the MSS
format input) is copied to the second output file and scribed with the training
areas.  Class 1 statistics are gathered from two irregular training fields.
Classes 2 and three both have one rectangular training field.
3.  The last example is the test procedure for stats.  This is
    a complete example that could be run by the user and that 
    demonstrates uses of the possible parameters.

     gen gen1 nl=128 ns=128
     gen gen2 nl=128 ns=128 sinc=2 linc=2
     gen gen3 nl=128 ns=128 sinc=4 linc=4
     !
     !  First tests will check standard image format files
     !
     ! Copy first band and scribe training areas on this image
     stats (gen1,gen2,gen3) (stat1,stat2) 'noprint       class1=(1,1,32,32) class2=(96,1,32,32) class3=(96,96,32,32)       class4=(1,96,32,32)
     ! Print Histograms for the DN values in each training area
     stats (gen1,gen2,gen3) stat1 hist=0       class1=(1,1,32,32) class2=(96,1,32,32) class3=(96,96,32,32)       class4=(1,96,32,32)
     ! Print Spectral Plot for all bands and classes
     stats (gen1,gen2,gen3) stat1 spec=0       class1=(1,1,32,32) class2=(96,1,32,32) class3=(96,96,32,32)       class4=(1,96,32,32)
     ! Try out Vertice format
     stats (gen1,gen2,gen3) stat1 hist=0 vert=5       class1=(1,1,32,32) class2=(96,1,32,32) class3=(96,96,32,32)       class4=(1,96,32,32) class5=(48,48,48,70,70,48,48,48)
     !
     !  Now check MSS format images
     !
     al mss 128 384
     mss (gen1,gen2,gen3) mss (1,1,128,128)
     ! Copy second band and scribe training areas on this image
     stats mss (stat1,stat2) mss=3 scribe=2       class1=(1,1,32,32) class2=(96,1,32,32) class3=(96,96,32,32)       class4=(1,96,32,32)
     ! Gather stats for first and third bands
     stats mss stat1 mss=3 band=(1,3) hist=0 'noprint       class1=(1,1,32,32) class2=(96,1,32,32) class3=(96,96,32,32)       class4=(1,96,32,32)
     ! Print spectral plots for second and third band for first and fourth class
     stats mss stat1 mss=3 splot=(1,4) spec=(2,3)       class1=(1,1,32,32) class2=(96,1,32,32) class3=(96,96,32,32)       class4=(1,96,32,32)
     ! Try out Vertice format
     stats mss (stat1,stat2) mss=3 vert=5       class1=(1,1,32,32) class2=(96,1,32,32) class3=(96,96,32,32)       class4=(1,96,32,32) class5=(48,48,48,70,70,48,48,48)
OPERATION:  If the scribe option is requested, stats begins by copying
 the specified input picture to the secondary output data set.  Then the first
 training area parameters are the processed and the training area is
 read from all input bands.  Statistics on this area are compiled and the
 area is scribed on the scribed picture.  After compiling statistics for
 all training fields for a given class, the statistics are written on the
 output statistics data set.  The record number on which they were written is
 the class number of that class.  The record contains the
 means, the number of pixels, and the covariance matrix for that class.  The
 record length is a function of the number of spectral bands used.  The
 maximum record length is 372 bytes which corresponds to 12 spectral bands.
 Maximum number of records is 50 since class numbers must range from 1 to
 50.  If desired, histograms of each training class in each band are
 printed.   Spectral plots of the spectral signatures
 can also be printed.  The 'EXCLUDE' option allows the user to specify
 certain DNs for which statistics are ignored.  This is useful, for
 instance, if the training areas lie at the edge of a skewed picture.  To
 prevent statistics from including pixels in the background skew,
 'EXCLUDE,0' could be specified.
      Page printer output includes the training areas for the class,
 means, and standard deviations for each band, and the covariance matrix.
 The covariance matrix is simply the covariance taken between all combina-
 tions of spectral band pairs.  The keyword NOPRINT supresses the page
 printer option.
RESTRICTIONS:  stats can handle up to 12 spectral bands in MSS format or
 in separate data set format, and compute statistics on 50 training
 classes.  The maximum size for any training field is 600 lines by 600
 samples.  The input files must have byte data format.
      Histograms and scribing must be performed in separate executions.
 If both are specified then the histograms will be deleted.
WRITTEN BY: J. D. Addington               30 September 1974

CONVERTED TO VAX BY:  A. J. Runkle	  22 Dec. 1983

CURRENT COGNIZANT PROGRAMMER: Steve Pohorsky

MADE PORTABLE FOR UNIX: CRI               31 OCT 1994


TIMING:  Execution time depends on the number and size of the training
 areas and the number of spectral bands.  Typical running time is between
 1 and 2 minutes.