This document describes the purpose and use of the three iraf scripts:
SMOOTH.CL, INTENSITY.CL, and VELOCITY.CL
	   
		 * * * * * * * * * * * * * * * * * * * *

PURPOSE:
	
	These IRAF command language (cl) scripts have been developed to
 facilitate the reduction of radio or optical imaging spectroscopy
"data cubes" (e.g. with axes of right ascension, declination, and 
velocity) into a set of two-dimensional images representing various
moments of the data cube along the velocity (wavelength or frequency)
axis.  These moments include the total intensity, the mean and peak
velocity, and the profile dispersion (width).  A mechanism is provided
to mask out regions of insufficient signal strength and to enhance the
signal to noise ratio by smoothing the original data cube in all three
dimensions.  

	The operations are carried out in three separate scripts which
the user must invoke in turn: "smooth.cl", "intensity.cl", and
"velocity.cl".


DESCRIPTION OF USAGE:

	The three scripts were intended to be run in the order: smooth,
intensity, and velocity.  It is assumed that the input files are
consistent, i.e. In the case of the intensity.cl script, the input 
cube for mask-making ("mimage") would normally be related to the input
image ("image").  One may use a smoothed version of the input image as
"mimage" for the creation of the mask.  In the case of the velocity.cl
script, it is assumed that the "nrchan" file was derived from the
masked intensity file which produced the total intensity map, all of
which are inputs to this script.

	The spatial smoothing section of the smooth task uses a kernel 
 which extends out to four times the sigma of the smoothing gaussian
(in pixels) and the final smoothed image is not decimated.  When a
spatial smooth is done, the more smooth the output image, the longer
the task takes to run.  The user can change the smoothing kernel size
(default is a factor of four sigma) by simply changing its value in the
"gauss" task before running the "smooth.cl" script.  Except for very
small images, this task should be run in batch.  Timing information is
given in the help files for each of the tasks.

	In all of the scripts, none of the input images are over-
written. Instead, new images are created.  These new images will all
have the same header as the input image, with a few exceptions (the
smoothed file will have the header keyword values for BMAJ, BMIN
updated after smoothing).  Also, comments will be added to each output
file describing what it is.

	In these versions of the scripts, it is assumed that the input
image has a round point source response.  No provision has been made to
smooth with other than a normal gaussian whose width is the same in any
direction.  In addition, the sampling in the x and y direction are
assumed to be the same (i.e. the same number of arcseconds per pixel in
both directions).

	Certain header parameters are expected to appear in the headers
of the input images.  They are NAXIS, NAXIS1, NAXIS2, and NAXIS3 which
together describe the dimensions of the image.  Also, if the user
chooses not to provide an ascii file of velocities, the  velocity.cl
script will attempt to create one from keywords CRPIX3, CRVAL3, and
CDELT3 found in the header of the input image.  They are, respectively,
the reference pixel, its velocity in meters/sec, and the pixel width in
velocity units of meters/sec (usually the channel width).  If the
CDELT3 parameter is missing, the script will assume that the channel
width in velocity of the input image is 1 km/sec and will continue to
run. If either the CRVAL3 or CRPIX3 keyword is missing, the program
will terminate with a message.

	
BEFORE RUNNING THE SCRIPTS:
	
	The user must load the following IRAF packages in order
to run any one of the scripts:
         
	  images
	  stsdas.toolbox.tools
	  noao.proto
	  language 

	After loading these packages, unlearn the following tasks: 

	  imcalc
	  imarith
	  imdel
	  gauss
	  convol
	  blkavg
	  hedit

	If the user is starting with a FITS format file, first convert
it to an ST-format (hhh/hhd) file using the iraf task "strfits".  The
tasks should also run on imh/pix format files, but the file types of
the input and output images should be consistent.

	If the user is running tests with these scripts, it is advisable
to set clobber=yes.  This will enable output ascii files to be over-written
after an unsuccessful or interrupted run of a task, however, the user
will need to delete any images before re-running the task with the same
filenames.

	To run any one of these tasks in batch, the user should specify
all required parameters, and it is also important to set the logfile 
parameter.  Then a task can be run in batch by typing after the cl
prompt: `cl> taskname mode="h" &' For example, to run the intensity
task in batch, type:

         cl>  intensity mode="h" & batch

or, to run it in the background (in a UNIX shell) type:

	 cl>  intensity mode="h" &

Setting the mode to "h" or "hidden" will disable the interactive querry
for the task parameters, so that if a required parameter is missing,
the batch job will crash.  The user should read the help information
for the individual scripts to see which parameters are required, or
just type `lpar taskname'.  Those parameters not in parentheses are 
required.


MORE INFORMATION:
	
	Each of the scripts has an associated help file.  These files
have the same root name as the script, but with the extension `.hlp'. 
For example, one may access the help file for smooth.cl by typing:

		help smooth.hlp file+

The scripts themselves are, of course, simply ASCII files and may be
edited for specific applications.  Each script has a header with
pertinent information.  If more detail is needed, typing the name of any
one of the iraf/stsdas tasks that are used in the scripts will yield
more specific information. 


	These scripts were developed by Diane Gilmore and Ron Allen
at the Space Telescope Science Institute in 1990.


