
dstats(1)                    Khoros                     dstats(1)

PROGRAM
     dstats - dstats computes 1-D statistics of an input VIFF
     file.

SYNTAX
     dstats

     -i             input file

     [-m]           statistics operation masking file

     [-f]           output ASCII file

     [-o]           VIFF format output file

     [-all]         if yes, all stats saved

     [-mu]          if yes, mean is a band of output

     [-var]         if yes, variance is a band of output

     [-sd]          if yes, std deviation is a band of output

     [-rms]         if yes, rms is a band of output

     [-vmax]        if yes, maximum value is a band of output

     [-xmax]        if yes, x coord of max value is a band of
                    output

     [-vmin]        if yes, minimum value is a band of output

     [-xmin]        if yes, x coord of min value is a band of
                    output

     [-in]          if yes, integral value is a band of output

     [-pin]         if yes, pos part of integral is a band of
                    output

     [-nin]         if yes, neg part of integral is a band of
                    output

     [-pts]         if yes, num contributing pts is a band of
                    output

     [-ppts]        if yes, num positive pts is a band of output

     [-npts]        if yes, num negative pts is a band of output

     [-sk]          if yes, skewness is a band of output

     [-kur]         if yes, kurtosis is a band of output

     [-ent]         if yes, entropy is a band of output

     [-con]         if yes, contrast is a band of output

     [-d]           process dir. (0=down vectors, 1=across bands,
                    2=entire file):
                    1 (Process by Bands),
                    0 (direction of processing (1 = across bands,
                    0 = down vectors)),
                    or 2 (Process by Bands)
                       [default = 1]

     [-V]           Gives the version for dstats

     [-U]           Gives the usage for dstats

     [-P]           Prompts for command line options

     [-A [file1]]   Creates the answer file called dstats.ans or
                    file1

     [-a [file1]]   Uses dstats.ans or file1 as the answer file

DESCRIPTION
     dstats computes the mean, variance, standard deviation, RMS
     level, peaks with locations, integral, skew, kurtosis,
     entropy, and contrast for an input VIFF file.  Descriptions
     of how these statistics are calculated are given in the
     lvstats man page.

     Masking File
          A masking file can be specified (-m option) which will
          allow specified vectors to NOT be included in the
          statistics calculations.  Statistics for any vector
          that has a corresponding mask value of 0 will not be
          calculated.

     Output ASCII File
          The ASCII output device or file is specified after the
          -f option, a filename of # will send the output to
          stderr.

     VIFF Output File
          If the -o, VIFF output file, option is selected, the
          user must specify a file name and at least one statis-
          tic to be recorded in the file.  Each statistic will be
          stored as a band of the output file.  For example if
          the mean (-mu) and variance (-var) statistics options
          are selected, band 1 will contain the mean values of
          each vector of the input file and band 2 will contain
          the variance values.  The vector corresponding to x=0,
          y=0 is the statisitcal vector of the first vector of
          the input image, vector x=1, y=0 is the statistical
          vector of the second input vector, etc.

          All of the calculated statistics can be stored in the
          VIFF output file by selecting "Save ALL statistics"
          (set the -all flag to 1).  If any other statistics flag
          is TRUE though, the all flag is overridden and only
          those statistics specified are stored in the output
          VIFF file.  (-all defaults to TRUE, all other statistic
          flags default to FALSE)

          Information on how statistics are calculated can be
          found in lvstats(3).

     Process Direction
          The -d (process direction) option specifies in what
          direction the data will be processed.  If -d is set to
          0, statistics are calculated on each vector, which
          means that data stored in multiband format will be pro-
          cessed as a set of data sequences, where each sequence
          corresponds to a pixel location, and the points of each
          sequence are defined by the bands corresponding to that
          pixel location.  The direction of processing can be
          changed so that each band is processed as a signal
          (instead of each vector being a signal) by setting the
          -d option to 1.  For both vector and band process
          directions, each set of statistics will be computed and
          printed separately.  If the -d option is set to 2,
          statistics will be computed for all bands combined
          (dstats will treat a multiband file as single, continu-
          ous raster of data -- minimum/maximum data position
          values will reflect this convention).

REQUIRED ARGUMENTS
     -i     type: infile
            desc: input file

OPTIONAL ARGUMENTS
     -m     type: infile
            desc: statistics operation masking file

     -f     type: outfile
            desc: output ASCII file

     -o     type: outfile
            desc: VIFF format output file

     -all   type: boolean
            desc: if yes, all stats saved
            default: true

     -mu    type: boolean
            desc: if yes, mean is a band of output
            default: false

     -var   type: boolean
            desc: if yes, variance is a band of output
            default: false

     -sd    type: boolean
            desc: if yes, std deviation is a band of output
            default: false

     -rms   type: boolean
            desc: if yes, rms is a band of output
            default: false

     -vmax  type: boolean
            desc: if yes, maximum value is a band of output
            default: false

     -xmax  type: boolean
            desc: if yes, x coord of max value is a band of out-
            put
            default: false

     -vmin  type: boolean
            desc: if yes, minimum value is a band of output
            default: false

     -xmin  type: boolean
            desc: if yes, x coord of min value is a band of out-
            put
            default: false

     -in    type: boolean
            desc: if yes, integral value is a band of output
            default: false

     -pin   type: boolean
            desc: if yes, pos part of integral is a band of out-
            put
            default: false

     -nin   type: boolean
            desc: if yes, neg part of integral is a band of out-
            put
            default: false

     -pts   type: boolean
            desc: if yes, num contributing pts is a band of out-
            put
            default: false

     -ppts  type: boolean
            desc: if yes, num positive pts is a band of output
            default: false

     -npts  type: boolean
            desc: if yes, num negative pts is a band of output
            default: false

     -sk    type: boolean
            desc: if yes, skewness is a band of output
            default: false

     -kur   type: boolean
            desc: if yes, kurtosis is a band of output
            default: false

     -ent   type: boolean
            desc: if yes, entropy is a band of output
            default: false

     -con   type: boolean
            desc: if yes, contrast is a band of output
            default: false

     -d     type: integer
            desc: process dir. (0=down vectors, 1=across bands,
            2=entire file)
            allowed values:
            1 (Process by Bands),
            0 (direction of processing (1 = across bands, 0 =
            down vectors)),
            or 2 (Process by Bands)

EXAMPLES
     dstats -i file.xv -f ascii -o stat.xv -all 1
     Will create an ascii stat file and a VIFF stat file.  The
     VIFF stat file will contain all 20 statistic parameters and
     will therefore be 20 bands, one for each stat.  Since the -d
     option is not specified, dstats defaults to calculating sta-
     tistical information for each band separately.

     dstats -i file.xv -f ascii -o stat.xv -var y -sd y -d 2
     Will create an ascii stat file and a VIFF stat file.  The
     VIFF stat file will contain 2 statistic parameters and will
     therefore be 2 bands, one for variance and one for standard
     deviation.  Since the -d option is set to 2, dstats calcu-
     lates a single set of statistical information for the entire
     data file.

SEE ALSO
     intro(1), verror(3), vgparms(3), vutils(3)
     vstats(1), lvstats(3)

RESTRICTIONS
     dstats cannot work on VFF_TYP_BIT.

     If the -o (output VIFF file) option is specified, at least
     one statistic must be specified to be put in the output
     file.

     If -all is true for the output VIFF file, but any other of
     the statistics flags is set, the -all flag is ignored.

     Entropy and contrast are calculated only on VFF_TYP_BYTE
     files.  For all other valid data types, entropy and contrast
     values are not computed and 0.0 is returned.

COPYRIGHT
     Copyright 1991, University of New Mexico.  All rights
     reserved.

Khoros                    Release: 1.0                          1

