Basic Information on imstat

Task: imstat
Purpose: calculate and plot map statistics
Categories: map analysis

        IMSTAT calculates statistics for images.  These are the sum,
        mean, rms, maximum and minimum value of a region.  Statistics
        can be found for profiles or planes, specified using the axes
        keyword.
 
        The data can be converted to Kelvin, by using 'options=tb' and
        the beam keyword.
 
        Output can be written to the terminal, a log file, or a plot.
        The options keyword gives control over the plot.
 
        The plot header can be suppressed by using options=noheader.
        An alternative title can be put on the plot by options=title.
        A useful combination is 'options=noh,ti,title', to get only the
        string 'title', instead of the full header.
 

Key: in
        Standard keyword in. See the help on in for more information.
 

Key: region
        Standard keyword region. See the help on region for more information.
 

Key: axes
        One axis (for profiles) or two axes (for planes) for which
        statistics are to be calculated.  E.g. 'axes=spectral' computes
        statistics of each spectrum in the selected region - whether
        expressed as frequency, velocity, etc.
        'axes=longitude,latitude' would compute statistics for each
        celestial image plane in the dataset (regardless of
        orientation).
 
        axes is case insensitive, and may be specified explicitly by
        coordinate type (ctype), as listed by PRTHD.  In this it is not
        necessary to specify the algorithm code, e.g. 'RA' matches both
        'RA---NCP' and 'RA---SIN', while 'VOPT' matches 'VOPT-F2W'.
 
        Axes may also be specified via their order in the image as
        'x', 'y', 'z', 'a', 'b', 'c', and 'd' for axes 1 to 7.
 
        The following generic values are also understood: 'longitude'
        ('lng' or 'long'), 'latitude' (or 'lat'), and 'spectral' ('spc'
        or 'spec').
 
        The default is 'x,y' if the input is multi-dimensional,
        otherwise 'x'.
 

Key: plot
        Selects the statistic to be plotted.  Minimal matching is
        applied.  The default is 'rms'.
 
          'sum'         Plot the sum
          'mean'        Plot the mean
          'rms'         Plot the rms
          'rrms'        Plot the robust rms (median absolute
                        deviation from median *1.48)
          'maximum'     Plot the maximum
          'minimum'     Plot the minimum
 

Key: cutoff
        Data values below the cutoff are not used for the calculation
        of statistics.  Give one real value.  This may be followed by
        the string ',abs' to get a cutoff in the absolute value of the
        datavalues, or ',lower' to exclude all values above the cutoff.
        Default is no cutoff.
 

Key: device
        Standard keyword device. See the help on device for more information.
 

Key: options
        Options controlling the characteristics of the plot (minimal
        matching is done):
 
         'tb'          Convert the units to brightness temperature,
                       using the input for the beam keyword
         'hanning,#'   Hanning smooth the data first over # pixels (must
                       be an odd number)
         'boxcar,#'    Boxcar smooth the data first over # pixels
         'deriv,#'     Take the derivative after smoothing.  If #=1 a
                       one-sided derivative is taken, for #=2 its
                       two-sided.  Useful for Zeeman work.
 
         'noheader'    Do not write the header information, just the
                       numbers, producing an ASCII file for a plotting
                       program
         'nolist'      Do not write the statistics to the screen/logfile
         'eformat'     Always use format 'e' instead of 'g' to write
                       results
         'guaranteespaces' Make sure there is always a space between
                       columns (at the cost of precision)
 
         'xmin,#'      Give lower x-value on axis
         'xmax,#'      Give upper x-value on axis
         'ymin,#'      Give lower y-value on axis
         'ymax,#'      Give upper y-value on axis
                       (for these four options the default is
                        autoscaling)
         'title,#1,#2,#3' Put the string #1 at x-position #2 and
                       y-position #3, with positions measured in units
                       of the coordinates on the axes.  If 'title' is
                       the last option, the title is put in the upper
                       left hand corner.
         'style,#'     This selects the plot style.
                       #=connect means connect the datapoints
                       #=step means make one-bin wide connected
                       horizontal line segments
                       #=histo means bins are drawn as a horizontal line
                       surrounded by two vertical lines
 

Key: beam
        If options=tb is used, imstat calculates the sum divided by the
        sum of the beam to get the flux in the selected area, if the
        units of the input data are 'per beam'.  This is then converted
        to Kelvin by dividing by 2k/lambda^2 * omega, where omega is
        found from the beam keyword.
 
        If the name of a dataset is given for 'beam', imstat assumes it
        contains a beampattern and sums the data in a region of the same
        size as the input region.  Else, it assumes that 'beam' gives
        the major and minor axes of the beam in arcsec and it calculates
        the sum for a Gaussian beam of that size.
 
        If 'beam' is omitted, but 'options=tb' was selected, the beam is
        found from the header (items bmaj and bmin).  If neither is
        present, no conversion is done.
 

Key: log
        If specified, output is written to the file given by log=
        instead of to the terminal.
 
Revision: 1.10, 2015/08/11 06:16:34 UTC