Basic Information on imspec

Task: imspec
Purpose: plots spectra from image data
Categories: map analysis

        IMSPEC plots spectra.  The flux, primary-beam-corrected-flux,
        mean or sum of an area can be plotted.  Data can be averaged or
        summed in ra-dec, ra-vel or dec-vel (etc) planes, to obtain
        profiles along the vel, dec or ra axes, respectively.  See the
        description of the axes keyword.
 
        To get fluxes the sum of the beam in an area of the same size as
        the input region is calculated, using the beam 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.
        To write the spectrum to an ASCII file use options=list,noheader
        and log=logfile.
 
        The plotheader 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.
        imspec only recognizes rectangular boxes.  It will use the mask
        associated with the input image.
 
        The region specifications in the following examples are relative
        to the reference pixel and assume an (RA,Dec,spectral) cube:
 
        - Plot a spectrum with channel in the range [10:40] averaged
          over RA and Dec in the range RA:[-31,32] and Dec[-31,32]:
            region=relpix,box(-31,-31,32,32)(10,40)
            axes=ra,dec
 
        - Plot a profile in RA in the range RA:[-31,32], at Dec=0
          for spectral channel 10:
            region=relpix,box(-31,0,32,0)(10)
            axes=dec,spectral
 
        - Plot a set of profiles in RA in the range RA:[-31,32], for
          each Dec in the range Dec:[-31,32], for spectral channel 10:
            region=relpix,box(-31,-31,32,32)(10)
            axes=spectral
 
        - Plot a profile in Dec in the range dec:[-31,32] with RA
          averaged from RA:[-10,10], for spectral channel 10:
            region=relpix,box(-10,-31,10,32)(10)
            axes=ra,spectral
 

Key: axes
        One or two axes along which data are averaged to obtain a data
        point on the profile.  Combined with the region keyword, it can
        be used to get a profile as function of any coordinate.  E.g.
        'axes=spectral' averages each spectrum in the selected region -
        whether expressed as frequency, velocity, etc.
        'axes=longitude,latitude' averages 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
        This selects what will be plotted as function of e.g. velocity.
        To convert data to fluxes the input of the beam keyword is used.
        Minimal matching is applied.  The default is 'flux'.
 
         'mean'        Plot the mean
         'sum'         Plot the sum
         'flux'        Plot the flux
         'pbcflux'     Plot the primary-beam-corrected flux
                       (not yet implemented)
 

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
        The options control the characteristics of the plot.
        Possible options are (minimal matching is done):
 
         'tb'          Convert the units of mean or sum 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 it's
                       two-sided.  Useful for Zeeman work.
 
         'noheader'    Do not write the header information, just the
                       numbers, producing an ASCII file for a plotting
                       program
         'list'        Write the spectrum 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 plot=flux is used, imspec 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'.
        If the name of a dataset is given, it assumes this is a beam
        pattern 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 of a gaussian beam
        of that size.
        If 'beam' is omitted, but 'flux' was selected, the beam is found
        from the header (items bmaj and bmin).  If neither is present,
        the sum is assumed to be 1.
 

Key: log
        If specified, output is written to the file given by log=
        instead of to the terminal.
 
Revision: 1.12, 2019/08/13 05:15:56 UTC