IDL Help for Goddard Utilities

This page was created by the IDL library routine make_html_help. For more information on this routine, refer to the IDL Online Help Navigator or type:

     ? make_html_help

at the IDL command line prompt.

Last modified: Mon Feb 20 19:35:18 2006.


List of Routines


Routine Descriptions

ABSCAL

[Next Routine] [List of Routines]
 NAME:
       ABSCAL
 PURPOSE:
       Apply the FITS BZERO and BSCALE keyword values to a data array

 CALLING SEQUENCE:
       RESULT = ABSCAL( Value, Header, /DEBUG)

 INPUTS:
       VALUE -  Any scalar, vector, or array (usually an integer type giving a
               relative intensity).
       HEADER - A FITS  header array containing the absolute calibration
               keyword BSCALE, and optionally BZERO and BUNIT.

 OUTPUT:
       RESULT = BSCALE*VALUE + BZERO, where the BSCALE and BZERO scalars
               are taken from the FITS header.  
               If the absolute calibration keywords do not exist, then
               RESULT = VALUE, and !ERR = -1.

 OPTIONAL INPUT KEYWORD:
       /DEBUG - If DEBUG is set, then ABSCAL will print the
               calibration units given by the BUNIT keyword.

 REVISION HISTORY:
       Written W. Landsman, STX Corporation     January 1987
       Use DEBUG keyword instead of !DEBUG      September 1995
       Converted to IDL V5.0   W. Landsman   September 1997

(See goddard/pro/astrom/abscal.pro)


AD2XY

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
     AD2XY
 PURPOSE:
     Compute X and Y from native coordinates and a FITS  astrometry structure
 EXPLANATION:
     If a WCS projection (Calabretta & Greisen 2002, A&A, 395, 1077) is 
     present, then the procedure WCSXY2SPH is used to compute native 
     coordinates.   If distortion is present then this is corrected.  
     In all cases, the inverse of the CD matrix is applied and offset 
     from the reference pixel to obtain X and Y. 

     AD2XY is generally meant to be used internal to other procedures.   For 
     interactive purposes, use ADXY.

 CALLING SEQUENCE:
     AD2XY, a ,d, astr, x, y   

 INPUTS:
     A -     R.A. or longitude in DEGREES, scalar or vector
     D -     Dec. or longitude in DEGREES, scalar or vector
     ASTR - astrometry structure, output from EXTAST procedure containing:
        .CD   -  2 x 2 array containing the astrometry parameters CD1_1 CD1_2
               in DEGREES/PIXEL                                   CD2_1 CD2_2
        .CDELT - 2 element vector giving increment at reference point in
               DEGREES/PIXEL
        .CRPIX - 2 element vector giving X and Y coordinates of reference pixel
               (def = NAXIS/2) in FITS convention (first pixel is 1,1)
        .CRVAL - 2 element vector giving coordinates of the reference pixel 
               in DEGREES
        .CTYPE - 2 element vector giving projection types 
        .LONGPOLE - scalar longitude of north pole (default = 180) 
        .PV2 - Vector of additional parameter (e.g. PV2_1, PV2_2) needed in 
               some projections
        .DISTORT - Optional substructure specifying distortion parameters

 OUTPUTS:
     X     - row position in pixels, scalar or vector
     Y     - column position in pixels, scalar or vector

     X,Y will be in the standard IDL convention (first pixel is 0), and
     *not* the FITS convention (first pixel is 1)
 NOTES:
      AD2XY tests for presence of WCS coordinates by the presence of a dash 
      in the 5th character position in the value of CTYPE (e.g 'DEC--SIN').       
 PROCEDURES USED:
       TAG_EXIST(), WCSSPH2XY
 REVISION HISTORY:
     Converted to IDL by B. Boothman, SASC Tech, 4/21/86
     Use astrometry structure,  W. Landsman      Jan. 1994   
     Do computation correctly in degrees  W. Landsman       Dec. 1994
     Only pass 2 CRVAL values to WCSSPH2XY   W. Landsman      June 1995
     Don't subscript CTYPE      W. Landsman       August 1995        
     Converted to IDL V5.0   W. Landsman   September 1997
     Understand reversed X,Y (X-Dec, Y-RA) axes,   W. Landsman  October 1998
     Consistent conversion between CROTA and CD matrix W. Landsman October 2000
     No special case for tangent projection W. Landsman June 2003
     Work for non-WCS coordinate transformations W. Landsman Oct 2004

(See goddard/pro/astrom/ad2xy.pro)


ADSTRING

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       ADSTRING
 PURPOSE:
       Return RA and Dec as character string(s) in sexigesimal format.
 EXPLANATION:
       RA and Dec may be entered as either a 2 element vector or as
       two separate vectors (or scalars).  One can also specify the precision 
       of the declination in digits after the decimal point.

 CALLING SEQUENCE
       result = ADSTRING( ra_dec, precision, /TRUNCATE )           
               or
       result = ADSTRING( ra,dec,[ precision, /TRUNCATE ] )

 INPUTS:
       RA_DEC - 2 element vector giving the Right Ascension and declination
               in decimal degrees.
                     or
       RA     - Right ascension in decimal degrees, numeric scalar or vector
       DEC    - Declination in decimal degrees, numeric scalar or vector

 OPTIONAL INPUT:
       PRECISION  - Integer scalar (0-4) giving the number of digits after the 
               decimal of DEClination.   The RA is automatically 1 digit more.
               This parameter may either be the third parameter after RA,DEC 
               or the second parameter after [RA,DEC].  It is not available 
               for just DEC.   If no PRECISION parameter is passed, a 
               precision of 1 for both RA and DEC is returned to maintain 
               compatibility with past ADSTRING functions.    Values of 
               precision larger than 4 will be truncated to 4.    If
               PRECISION is 3 or 4, then RA and Dec should be input as 
               double precision.
 OPTIONAL INPUT KEYWORD:
       /TRUNCATE - if set, then the last displayed digit in the output is 
               truncated in precision rather than rounded.   This option is
               useful if ADSTRING() is used to form an official IAU name 
               (see http://vizier.u-strasbg.fr/Dic/iau-spec.htx) with 
               coordinate specification.   The IAU name will typically be
               be created by applying STRCOMPRESS/REMOVE) after the ADSTRING()
               call, e.g. 
              strcompress( adstring(ra,dec,0,/truncate), /remove)   ;IAU format
 OUTPUT:
       RESULT - Character string(s) containing HR,MIN,SEC,DEC,MIN,SEC formatted
               as ( 2I3,F5.(p+1),2I3,F4.p ) where p is the PRECISION 
               parameter.    If only a single scalar is supplied it is 
               converted to a sexigesimal string (2I3,F5.1).

 EXAMPLE:
       (1) Display CRVAL coordinates in a FITS header, H

       IDL> crval = sxpar(h,'CRVAL*')  ;Extract 2 element CRVAL vector (degs)
       IDL> print, adstring(crval)     ;Print CRVAL vector sexigesimal format

       (2)  print,adstring(30.42,-1.23,1)  ==>  ' 02 01 40.80  -01 13 48.0'
            print,adstring(30.42,+0.23)    ==>  ' 02 01 40.8   +00 13 48.0'    
            print,adstring(+0.23)          ==>  '+00 13 48.0'

       (3) The first two calls in (2) can be combined in a single call using
           vector input
              print,adstring([30.42,30.42],[-1.23,0.23], 1)
 PROCEDURES CALLED:
       FSTRING(), RADEC, SIXTY()

 REVISION HISTORY:
       Written   W. Landsman                      June 1988
       Addition of variable precision and DEC seconds precision fix. 
       ver.  Aug. 1990 [E. Deutsch]
       Output formatting spiffed up       October 1991 [W. Landsman]
       Remove ZPARCHECK call, accept 1 element vector  April 1992 [W. Landsman]
       Call ROUND() instead of NINT()    February 1996  [W. Landsman]
       Check roundoff past 60s           October 1997   [W. Landsman]
       Work for Precision =4             November 1997  [W. Landsman]
       Converted to IDL V5.0   W. Landsman 24-Nov-1997
       Major rewrite to allow vector inputs   W. Landsman  February 2000
       Fix possible error in seconds display when Precision=0 
                               P. Broos/W. Landsman April 2002
       Added /TRUNCATE keyword, put leading zeros in seconds display
                               P. Broos/W. Landsman September 2002
       Hours values always less than 24   W. Landsman September 2002
       Fix zero declinations for vector processing W. Landsman February 2004
       Fix possible problem in leading zero display W. Landsman June 2004

(See goddard/pro/astro/adstring.pro)


ADXY

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       ADXY
 PURPOSE:
       Use a FITS header to convert astronomical to pixel coordinates
 EXPLANATION:
       Use an image header to compute X and Y positions, given the
       RA and Dec (or longitude, latitude) in decimal degrees.  

 CALLING SEQUENCE:
       ADXY, HDR               ;Prompt for Ra and DEC 
       ADXY, hdr, a, d, x, y, [ /PRINT, ALT= ]

 INPUTS:
       HDR - FITS Image header containing astrometry parameters

 OPTIONAL INPUTS:
       A - Right ascension in decimal DEGREES, scalar or vector
       D - Declination in decimal DEGREES, scalar or vector        

       If A and D are not supplied, user will be prompted to supply
       them in either decimal degrees or HR,MIN,SEC,DEG,MN,SC format.

 OPTIONAL OUTPUT:
       X     - row position in pixels, same number of elements as A and D
       Y     - column position in pixels

       X and Y will be in standard IDL convention (first pixel is 0) and not
       the FITS convention (first pixel is 1).      As in FITS an integral
       value corresponds to the center of a pixel.
 OPTIONAL KEYWORD INPUT:
       /PRINT - If this keyword is set and non-zero, then results are displayed
               at the terminal.
       ALT -  single character 'A' through 'Z' or ' ' specifying an alternate 
             astrometry system present in the FITS header.    The default is
             to use the primary astrometry or ALT = ' '.   If /ALT is set, 
             then this is equivalent to ALT = 'A'.   See Section 3.3 of 
             Greisen & Calabretta (2002, A&A, 395, 1061) for information about
             alternate astrometry keywords.

 OPERATIONAL NOTES:
       If less than 5 parameters are supplied, or if the /PRINT keyword is
       set, then the X and Y positions are displayed at the terminal.

       If the procedure is to be used repeatedly with the same header,
       then it would be faster to use AD2XY.

 PROCEDURES CALLED:
       AD2XY, ADSTRING(), EXTAST, GETOPT(), TEN()

 REVISION HISTORY:
       W. Landsman                 HSTX          January, 1988
       Use astrometry structure   W. Landsman   January, 1994  
       Changed default ADSTRING format   W. Landsman    September, 1995
       Converted to IDL V5.0   W. Landsman   September 1997
       Check if latitude/longitude reversed in CTYPE keyword W. L. Feb. 2004
       Added ALT keyword   W. Landsman   September 2004
       Work for non-spherical coordinate transformation W. Landsman May 2005        

(See goddard/pro/astrom/adxy.pro)


AFHREAD

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
      AFhread
 PURPOSE:
      Subroutine of WFPCREAD to read a GEIS header from an HST STSDAS image.
 EXPLANATION:
       This procedure reads a GEIS header from an HST image.   It then looks
       if a .SHH file is present for FOC images to calculate better 
       astrometry by getting the current PSANGLV3 from this file.   Called by
        WFPCREAD.PRO

 CALLING SEQUENCE:
       AFhread, HdrFile, hdr

 INPUTS:
       HdrFile - scalar string giving name of STSDAS header for an FOC image   

 OUTPUTS:
       hdr - string array, FITS header for the FOC image.    The position
               angle of the V3 axis of HST (PSANGLV3) is added, if it could 
               be found in the .SHH file       
 PROCEDURE CALLS:
       STRN(), SXADDPAR, SXHREAD, SXPAR()
 REVISION HISTORY:
       Written         Eric W. Deutsch  (U. of Washington)    June, 1994
       Documentation update   W. Landsman  (HSTX)             July, 1994
       Converted to IDL V5.0   W. Landsman   September 1997
       Removed call to EXIST() function   W. Landsman        April 1999

(See goddard/pro/sdas/afhread.pro)


AIRTOVAC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       AIRTOVAC
 PURPOSE:
       Convert air wavelengths to vacuum wavelengths 
 EXPLANATION:
       Wavelengths are corrected for the index of refraction of air under 
       standard conditions.  Wavelength values below 2000 A will not be 
       altered.  Uses the IAU standard for conversion given in Morton 
       (1991 Ap.J. Suppl. 77, 119)

 CALLING SEQUENCE:
       AIRTOVAC, WAVE

 INPUT/OUTPUT:
       WAVE - Wavelength in Angstroms, scalar or vector
               WAVE should be input as air wavelength(s), it will be
               returned as vacuum wavelength(s).  WAVE is always converted to
               double precision upon return.

 EXAMPLE:
       If the air wavelength is  W = 6056.125 (a Krypton line), then 
       AIRTOVAC, W yields an vacuum wavelength of W = 6057.8019

 METHOD:
       See Morton (Ap. J. Suppl. 77, 119) for the formula used

 REVISION HISTORY
       Written W. Landsman                November 1991
       Converted to IDL V5.0   W. Landsman   September 1997

(See goddard/pro/astro/airtovac.pro)


AITOFF

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       AITOFF
 PURPOSE:
       Convert longitude, latitude to X,Y using an AITOFF projection.
 EXPLANATION:
       This procedure can be used to create an all-sky map in Galactic 
       coordinates with an equal-area Aitoff projection.  Output map 
       coordinates are zero longitude centered.

 CALLING SEQUENCE:
       AITOFF, L, B, X, Y 

 INPUTS:
       L - longitude - scalar or vector, in degrees
       B - latitude - same number of elements as L, in degrees

 OUTPUTS:
       X - X coordinate, same number of elements as L.   X is normalized to
               be between -180 and 180
       Y - Y coordinate, same number of elements as L.  Y is normalized to
               be between -90 and 90.

 NOTES:
       See AIPS memo No. 46, page 4, for details of the algorithm.  This
       version of AITOFF assumes the projection is centered at b=0 degrees.

 REVISION HISTORY:
       Written  W.B. Landsman  STX          December 1989
       Modified for Unix:
               J. Bloch        LANL SST-9      5/16/91 1.1
       Converted to IDL V5.0   W. Landsman   September 1997

(See goddard/pro/astro/aitoff.pro)


AITOFF_GRID

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       AITOFF_GRID

 PURPOSE:
       Produce an overlay of latitude and longitude lines over a plot or image
 EXPLANATION:
       The grid is plotted on the current graphics device. AITOFF_GRID 
       assumes that the ouput plot coordinates span the x-range of 
       -180 to 180 and the y-range goes from -90 to 90.

 CALLING SEQUENCE:

       AITOFF_GRID [,DLONG,DLAT, LABEL=, /NEW, CHARTHICK=, CHARSIZE=, _EXTRA=]

 OPTIONAL INPUTS:

       DLONG   = Optional input longitude line spacing in degrees. If left
                 out, defaults to 30.
       DLAT    = Optional input latitude line spacing in degrees. If left
                 out, defaults to 30.

 OPTIONAL INPUT KEYWORDS:

       LABEL           = Optional keyword specifying that the latitude and
                         longitude lines on the prime meridian and the
                         equator should be labeled in degrees. If LABELS is
                         given a value of 2, i.e. LABELS=2, then the longitude
                         labels will be in hours instead of degrees.
        CHARSIZE       = If /LABEL is set, then CHARSIZE specifies the size
                         of the label characters (passed to XYOUTS)
        CHARTHICK     =  If /LABEL is set, then CHARTHICK specifies the 
                         thickness of the label characters (passed to XYOUTS)
       /NEW          =   If this keyword is set, then AITOFF_GRID will create
                         a new plot grid, rather than overlay an existing plot.

       Any valid keyword to OPLOT such as COLOR, LINESTYLE, THICK can be 
       passed to AITOFF_GRID (though the _EXTRA facility) to to specify the
       color, style, or thickness of the grid lines.
 OUTPUTS:
       Draws grid lines on current graphics device.

 EXAMPLE:
       Create a labeled Aitoff grid of the Galaxy, and overlay stars at 
       specified Galactic longitudes, glong and latitudes, glat

       IDL> aitoff_grid,/label,/new        ;Create labeled grid
       IDL> aitoff, glong, glat, x,y      ;Convert to X,Y coordinates
       IDL> plots,x,y,psym=2              ;Overlay "star" positions

 PROCEDURES USED:
       AITOFF
 NOTES:
       If labeling in hours (LABEL=2) then the longitude spacing should be
       a multiple of 15 degrees

 AUTHOR AND MODIFICATIONS:

       J. Bloch        1.2     6/2/91
       Converted to IDL V5.0   W. Landsman   September 1997
       Create default plotting coords, if needed   W. Landsman  August 2000
       Added _EXTRA, CHARTHICK, CHARSIZE keywords  W. Landsman  March 2001
       Several tweaks, plot only hours not minutes W. Landsman January 2002

(See goddard/pro/astro/aitoff_grid.pro)


APER

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
      APER
 PURPOSE:
      Compute concentric aperture photometry (adapted from DAOPHOT) 
 EXPLANATION:
     APER can compute photometry in several user-specified aperture radii.  
     A separate sky value is computed for each source using specified inner 
     and outer sky radii.   

 CALLING SEQUENCE:
     APER, image, xc, yc, [ mags, errap, sky, skyerr, phpadu, apr, skyrad, 
                       badpix, /NAN, /EXACT, /FLUX, PRINT = , /SILENT, 
                       SETSKYVAL = ]
 INPUTS:
     IMAGE -  input image array
     XC     - vector of x coordinates. 
     YC     - vector of y coordinates

 OPTIONAL INPUTS:
     PHPADU - Photons per Analog Digital Units, numeric scalar.  Converts
               the data numbers in IMAGE to photon units.  (APER assumes
               Poisson statistics.)  
     APR    - Vector of up to 12 REAL photometry aperture radii.
     SKYRAD - Two element vector giving the inner and outer radii
               to be used for the sky annulus.   Ignored if the SETSKYVAL
              keyword is set.
     BADPIX - Two element vector giving the minimum and maximum value
               of a good pixel.   If badpix is not supplied or if BADPIX[0] is
               equal to BADPIX[1] then it is assumed that there are no bad
               pixels.     Note that fluxes will not be computed for any star
               with a bad pixel within the aperture area, but that bad pixels
               will be simply ignored for the sky computation.    The BADPIX
               parameter is ignored if the /NAN keyword is set.

 OPTIONAL KEYWORD INPUTS:
     /EXACT -  By default, APER counts subpixels, but uses a polygon 
             approximation for the intersection of a circular aperture with
             a square pixel (and normalize the total area of the sum of the
             pixels to exactly match the circular area).   If the /EXACT 
             keyword, then the intersection of the circular aperture with a
             square pixel is computed exactly.    The /EXACT keyword is much
             slower and is only needed when small (~2 pixels) apertures are
             used with very undersampled data.    
     /FLUX - By default, APER uses a magnitude system where a magnitude of
               25 corresponds to 1 flux unit.   If set, then APER will keep
              results in flux units instead of magnitudes.
     /NAN  - If set then APER will check for NAN values in the image.   /NAN
             takes precedence over the BADPIX parameter.   Note that fluxes 
             will not be computed for any star with a NAN pixel within the 
             aperture area, but that NAN pixels will be simply ignored for 
             the sky computation.
     PRINT - if set and non-zero then APER will also write its results to
               a file aper.prt.   One can specify the output file name by
               setting PRINT = 'filename'.
     READNOISE - Scalar giving the read noise (or minimum noise for any
              pixel.   This value is passed to the procedure mmm.pro when
              computing the sky, and is only need for images where
              the noise is low, and pixel values are quantized.   
     /SILENT -  If supplied and non-zero then no output is displayed to the
               terminal.
     SETSKYVAL - Use this keyword to force the sky to a specified value 
               rather than have APER compute a sky value.    SETSKYVAL 
               can either be a scalar specifying the sky value to use for 
               all sources, or a 3 element vector specifying the sky value, 
               the sigma of the sky value, and the number of elements used 
               to compute a sky value.   The 3 element form of SETSKYVAL
               is needed for accurate error budgeting.

 OUTPUTS:
     MAGS   -  NAPER by NSTAR array giving the magnitude for each star in
               each aperture.  (NAPER is the number of apertures, and NSTAR
               is the number of stars).   If the /FLUX keyword is not set, then
               a flux of 1 digital unit is assigned a zero point magnitude of 
               25.
     ERRAP  -  NAPER by NSTAR array giving error for each star.  If a 
               magnitude could not be determined then  ERRAP = 9.99 (if in 
                magnitudes) or ERRAP = !VALUES.F_NAN (if /FLUX is set).
     SKY  -    NSTAR element vector giving sky value for each star in 
               flux units
     SKYERR -  NSTAR element vector giving error in sky values

 EXAMPLE:
       Determine the flux and error for photometry radii of 3 and 5 pixels
       surrounding the position 234.2,344.3 on an image array, im.   Compute
       the partial pixel area exactly.    Assume that the flux units are in
       Poisson counts, so that PHPADU = 1, and the sky value is already known
       to be 1.3, and that the range [-32767,80000] for bad low and bad high
       pixels
      

       IDL> aper, im, 234.2, 344.3, flux, eflux, sky,skyerr, 1, [3,5], -1, $
            [-32767,80000],/exact, /flux, setsky = 1.3
       
 PROCEDURES USED:
       GETOPT, MMM, PIXWT(), STRN(), STRNUMBER()
 NOTES:
       Reasons that a valid magnitude cannot be computed include the following:
      (1) Star position is too close (within 0.5 pixels) to edge of the frame
      (2) Less than 20 valid pixels available for computing sky
      (3) Modal value of sky could not be computed by the procedure MMM
      (4) *Any* pixel within the aperture radius is a "bad" pixel
      (5) The total computed flux is negative

       APER was modified in June 2000 in two ways: (1) the /EXACT keyword was
       added (2) the approximation of the intersection of a circular aperture
       with square pixels was improved (i.e. when /EXACT is not used) 
 REVISON HISTORY:
       Adapted to IDL from DAOPHOT June, 1989   B. Pfarr, STX
       Adapted for IDL Version 2,               J. Isensee, July, 1990
       Code, documentation spiffed up           W. Landsman   August 1991
       TEXTOUT may be a string                  W. Landsman September 1995
       FLUX keyword added                       J. E. Hollis, February, 1996
       SETSKYVAL keyword, increase maxsky       W. Landsman, May 1997
       Work for more than 32767 stars           W. Landsman, August 1997
       Don't abort for insufficient sky pixels  W. Landsman  May 2000
       Added /EXACT keyword                     W. Landsman  June 2000 
       Allow SETSKYVAL = 0                      W. Landsman  December 2000 
       Set BADPIX[0] = BADPIX[1] to ignore bad pixels W. L.  January 2001     
       Fix chk_badpixel problem introduced Jan 01 C. Ishida/W.L. February 2001
       Set bad fluxes and error to NAN if /FLUX is set  W. Landsman Oct. 2001 
       Remove restrictions on maximum sky radius W. Landsman  July 2003
       Added /NAN keyword  W. Landsman November 2004
       Set badflux=0 if neither /NAN nor badpix is set  M. Perrin December 2004
       Added READNOISE keyword   W. Landsman January 2005

(See goddard/pro/idlphot/aper.pro)


ARCBAR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       ARCBAR
 PURPOSE:
       Draw an arc bar on an image showing the astronomical plate scale

 CALLING SEQUENCE:
       ARCBAR, hdr, arclen,[  COLOR= , /DATA, LABEL= , /NORMAL, POSITION =, 
                              /SECONDS, SIZE=, THICK= ]

 INPUTS:
       hdr - image FITS header with astrometry, string array
       arclen - numeric scalar giving length of bar in arcminutes (default)
               or arcseconds (if /SECONDS is set) 

 OPTIONAL KEYWORD INPUTS:
       COLOR - integer scalar specifying the color to draw the arcbar (using
               PLOTS), default = !P.COLOR
       /DATA - if set and non-zero, then the POSITION keyword is given in data
              units
       LABEL - string giving user defined label for bar.  Default label is size
               of bar in arcminutes
       /NORMAL - if this keyword is set and non-zero, then POSITION is given in
               normalized units
       POSITION - 2 element vector giving the (X,Y) position in device units 
               (or normalized units if /NORMAL is set, or data units if /DATA
               is set) at which to place the  scale bar.   If not supplied, 
               then the user will be prompted to place the cursor at the 
               desired position
       /SECONDS - if set, then arlen is specified in arcseconds rather than
               arcminutes
       SIZE  - scalar specifying character size of label, default = 1.0
       THICK -  Character thickness of the label, default = !P.THICK

 EXAMPLE:
       Place a 3' arc minute scale bar, at position 300,200 of the current
       image window, (which is associated with a FITS header, HDR)

       IDL> arcbar, HDR, 3, pos = [300,200]

 RESTRICTIONS:
       When using using a device with scalable pixels (e.g. postscript)
       the data coordinate system must be established before calling ARCBAR.
       If data coordinates are not set, then ARCBAR assumes that the displayed
       image size is given by the NAXIS1 keyword in the FITS header.
 PROCEDURE CALLS:
       AD2XY, EXTAST, GSSSADXY, SXPAR()
 REVISON HISTORY:
       written by L. Taylor (STX) from ARCBOX (Boothman)
       modified for Version 2 IDL,                     B. Pfarr, STX, 4/91
       New ASTROMETRY structures               W.Landsman,  HSTX, Jan 94
       Recognize a GSSS header                 W. Landsman June 94
       Added /NORMAL keyword                   W. Landsman Feb. 96
       Use NAXIS1 for postscript if data coords not set,  W. Landsman Aug 96
       Fixed typo for postscript W. Landsman   Oct. 96
       Account for zeropoint offset in postscript  W. Landsman   Apr 97
       Converted to IDL V5.0   W. Landsman   September 1997
       Added /DATA, /SECONDS keywords   W. Landsman    July 1998
       Use device-independent label offset  W. Landsman   August 2001

(See goddard/pro/astro/arcbar.pro)


ARROWS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
      ARROWS
 PURPOSE:
      To display "weathervane" directional arrows on an astronomical image 
 EXPLANATION:
      Overlays a graphic showing orientation of North and East.

 CALLING SEQUENCE:
      ARROWS,h, [ xcen, ycen, ARROWLEN= , CHARSIZE=  COLOR= , /DATA
                              FONT=, /NORMAL, /NOTVERTEX, THICK=  ]

 INPUTS:
       h - FITS or STSDAS header array, must include astrometry

 OPTIONAL INPUTS:
       xcen,ycen - numeric scalars, specifying the center position of
		arrows.   Position in device units unless the /NORMALIZED 
		keyword is specified.   If not supplied, then ARROWS
		will prompt for xcen and ycen

 OPTIONAL KEYWORD INPUTS:
       arrowlen  - length of arrows in terms of normal Y size of vector-drawn
                     character,  default  = 3.5, floating point scalar
       charsize  - character size, default = 2.0, floating point scalar
       color     - color that the arrows and NE letters should be.  Default
                    value is !P.COLOR
       Data - if this keyword is set and nonzero, the input center (xcen,
                 ycen) is understood to be in data coordinates
       font - IDL vector font number (1-20) to use to display NE letters.
                 For example, set font=13 to use complex italic font.
       NotVertex - Normally (historically) the specified xcen,ycen indicated
                   the position of the vertex of the figure.  If this
                   keyword is set, the xcen,ycen coordinates refer to a sort
                   of 'center of mass' of the figure.  This allows the
                   figure to always appear with the area irregardless of
                   the rotation angle.
       Normal - if this keyword is set and nonzero, the input center 
                (xcen,ycen) is taken to be in normalized coordinates.   The
                default is device coordinates.
       thick     - line thickness, default = 2.0, floating point scalar
 OUTPUTS:
       none
 EXAMPLE:
       Draw a weathervane at (400,100) on the currently active window, 
       showing the orientation of the image associated with a FITS header, hdr

       IDL> arrows, hdr, 400, 100

 METHOD:
       Uses EXTAST to EXTract ASTrometry from the FITS header.   The 
       directions of North and East are computed and the procedure
       ONE_ARROW called to create the "weathervane".

 PROCEDURES USED:
       GETROT - Computes rotation from the FITS header
       ONE_ARROW - Draw a labeled arrow	
       ZPARCHECK
 REVISON HISTORY:
       written by B. Boothman 2/5/86 
       Recoded with new procedures ONE_ARROW, ONE_RAY.  R.S.Hill,HSTX,5/20/92
       Added separate determination for N and E arrow to properly display
         arrows irregardless of handedness or other peculiarities and added
         /NotVertex keyword to improve positioning of figure. E.Deutsch 1/10/93
       Added /DATA and /NORMAL keywords W. Landsman      July 1993
       Recognize GSSS header    W. Landsman       June 1993
       Added /FONT keyword W. Landsman           April 1995
       Modified to work correctly for COLOR=0  J.Wm.Parker, HITC   1995 May 25
       Work correctly for negative CDELT values   W. Landsman   Feb. 1996
       Converted to IDL V5.0   W. Landsman   September 1997
       Use GETROT to compute rotation   W. Landsman    June 2003
       Restored /NotVertex keyword which was not working after June 2003 change
                  W. Landsman  January 2004

(See goddard/pro/astro/arrows.pro)


ASINH

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
     ASINH
 PURPOSE:
     Return the inverse hyperbolic sine of the argument
 EXPLANATION:
     The inverse hyperbolic sine is used for the calculation of asinh 
     magnitudes, see Lupton et al. (1999, AJ, 118, 1406)

 CALLING SEQUENCE
     result = asinh( x) 
 INPUTS:
     X - hyperbolic sine, numeric scalar or vector or multidimensional array 
        (not complex) 

 OUTPUT:
     result - inverse hyperbolic sine, same number of elements as X
              double precision if X is double, otherwise floating pt.

 METHOD:
     Expression given in  Numerical Recipes, Press et al. (1992), eq. 5.6.7 
     Note that asinh(-x) = -asinh(x) and that asinh(0) = 0. and that
     if y = asinh(x) then x = sinh(y).     

 REVISION HISTORY:
     Written W. Landsman                 February, 2001
     Work for multi-dimensional arrays  W. Landsman    August 2002
     Simplify coding, and work for scalars again  W. Landsman October 2003

(See goddard/pro/math/asinh.pro)


ASTDISP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	ASTDISP

 PURPOSE:
	Print astronomical and pixel coordinates in a standard format
 EXPLANATION:
	This procedure (ASTrometry DISPlay) prints the astronomical and
	pixel coordinates in a standard format.  X,Y must be supplied.  RA,DEC
	may also be supplied, and a data number (DN) may also be 
	supplied.   With use of the Coords= keyword, a string containing the 
	formatted data can be returned in addition or instead (with /silent) 
	of printing.

 CALLING SEQUENCE:
	ASTDISP, x, y, [Ra, Dec, DN, COORD = , /SILENT ]

 INPUT:
	X  - The X pixel coordinate(s), scalar or vector
	Y  - The Y pixel coordinate(s), scalar or vector

 OPTIONAL INPUTS:
	RA -  Right Ascention in *degrees*, scalar or vector
	DEC - DEClination in *degrees*, scalar or vector (if RA is supplied, DEC must also be supplied)
	DN -  Data Number or Flux values

	Each of the inputs X,Y, RA, DEC, DN should have the same number of 
		elements
 OPTIONAL INPUT KEYWORDS:
	SILENT    Prevents printing.  Only useful when used with Coords=
 OUTPUT:
	Printed positions in both degrees and sexigesimal format
	All passed variables remain unchanged
 OPTIONAL KEYWORD OUTPUT:
	COORDS    Returns the formatted coordinates in a string
 PROCEDURES CALLED:
	ADSTRING - used to format the RA and Dec
 HISTORY:
	10-AUG-90 Version 1 written by Eric W. Deutsch
	20-AUG-91 Converted to standard header.  Vectorized Code.  E. Deutsch
	20-NOV-92 Added Coords= and /silent.  E.Deutsch
	Converted to IDL V5.0   W. Landsman   September 1997

(See goddard/pro/astro/astdisp.pro)


ASTRMFIX

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       ASTRMFIX
 PURPOSE:
       Calculate a rough HST WFPC or FOC astrometry solution
 EXPLANATION:
       This program will calculate a rough HST WFPC or FOC astrometry solution
       using the keyword PSANGLEV3 which gives the angle of the V3 axis of
       HST.    Called by WFPCREAD.

 CALLING SEQUENCE:
       AstrmFix, hdr, chip

 INPUT - OUTPUT:
       hdr - FITS header (string array) from either WFPC or FOC.   Header will
               be updated with rough astrometry 

 INPUT:        
       chip - Scalar (typically 0-3) giving the WFPC chip to read.

 PROCEDURES CALLED:
       EXTAST, SXPAR(), SXADDPAR
 HISTORY:
       ??-???-???? Written by Eric W. Deutsch
       22-OCT-1992 Changed all calculations to double precision. (E. Deutsch)
       22-OCT-1992 Updated PC Pixel size of 0.04389 from WFPC IDT OV/SV manual(EWD)
       22-OCT-1992 Updated WF Pixel size of 0.1016 from WFPC IDT OV/SV manual(EWD)
       11-JAN-1993 Added warning message and changed CD001001... to CD1_1... (EWD)
       Converted to IDL V5.0   W. Landsman   September 1997
       Remove calls to obsolete !ERR variable  W. Landsman   December 2000

(See goddard/pro/sdas/astrmfix.pro)


ASTRO

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
     ASTRO
 PURPOSE:
     Interactive utility for precession and coordinate conversion.

 CALLING SEQUENCE:
     ASTRO, [ selection, EQUINOX =, /FK4]

 OPTIONAL INPUT:
      SELECTION - Scalar Integer (0-6) giving the the particular astronomical
              utility to be used.  (0) Precession, (1) RA, Dec (2000) to Galactic 
              coordinates, (2) Galactic to RA,Dec (2000) (3) RA,Dec (2000) to 
              Ecliptic, (4) Ecliptic to RA, Dec, (5) Ecliptic to Galactic, (6) Galactic
              to Ecliptic.   Program will prompt for SELECTION if this 
              parameter is omitted.

 OPTIONAL KEYWORD INPUT:
       EQUINOX - numeric scalar specifying the equinox to use when converting 
               between celestial and other coordinates.    If not supplied, 
               then the RA and Dec will be assumed to be in EQUINOX J2000.   
               This keyword is ignored by the precession utility.   For 
               example, to convert from RA and DEC (J1975) to Galactic 
               coordinates:

               IDL> astro, 1, E=1975
       /FK4 - If this keyword is set and nonzero, then calculations are done
              in the FK4 system.    For example, to convert from RA and Dec
              (B1975) to Galactic coordinates

               IDL> astro,1, E=1975,/FK4 
 METHOD:
      ASTRO uses PRECESS to compute precession, and EULER to compute
      coordinate conversions.   The procedure GET_COORDS is used to
      read the coordinates, and ADSTRING to format the RA,Dec output.

 NOTES:
      (1) ASTRO temporarily sets !QUIET to suppress compilation messages and
      keep a pretty screen display.   

      (2) ASTRO was changed in December 1998 to use J2000 as the default 
      equinox, **and may be incompatible with earlier calls.***
      
      (3) A nice online page for coordinate conversions is available at
       http://heasarc.gsfc.nasa.gov/cgi-bin/Tools/convcoord/convcoord.pl   
 PROCEDURES USED:
      Procedures: GET_COORDS, EULER       Function: ADSTRING
 REVISION HISTORY
      Written, W. Landsman November 1987
      Code cleaned up       W. Landsman   October 1991
      Added Equinox keyword, call to GET_COORDS, W. Landsman   April, 1992
      Allow floating point equinox input J. Parker/W. Landsman  July 1996
      Make FK5 the default, add FK4 keyword

(See goddard/pro/astro/astro.pro)


ASTROLIB

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       ASTROLIB
 PURPOSE:
       Add the non-standard system variables used by the IDL Astronomy Library
 EXPLANATION: 
       Also defines the environment variable or VMS 
       logical ASTRO_DATA pointing to the directory containing data files 
       associated with the IDL Astronomy library (system dependent).

 CALLING SEQUENCE:
       ASTROLIB

 INPUTS:
       None.

 OUTPUTS:
       None.

 METHOD:
       The non-standard system variables !PRIV, !DEBUG, !TEXTUNIT, and 
       !TEXTOUT are added using DEFSYSV.

 REVISION HISTORY:
       Written, Wayne Landsman, July 1986.
       Use DEFSYSV instead of ADDSYSVAR           December 1990
       Converted to IDL V5.0   W. Landsman   September 1997
       Test for system variable existence before definition    July 2001

(See goddard/pro/misc/astrolib.pro)


AUTOHIST

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       AUTOHIST

 PURPOSE:
       Draw a histogram using automatic bin-sizing.
 EXPLANATION
       AUTOHIST chooses a number of bins (initially, SQRT(2*N). If this leads 
       to a histogram in which > 1/5 of the central 50% of the bins are empty,
       it decreases the number of bins and tries again. The minimum # bins is 
       5. The max=199.     Called by HISTOGAUSS and HALFAGAUSS.

 CALLING SEQUENCE:
       AUTOHIST, Sample, XLines, Ylines, XCenters, YCenters, [/NOPLOT, ]
                             ...Plotting Keywords
 INPUT:
       Sample = the vector to be histogrammed

 OUTPUT:
       XLINES = vector of x coordinates of the points that trace the rectangular 
               histogram bins
       YLINES = vector of y coordinates. To draw the histogram plot YLINES vs 
                 XLINES
       XCENTERS = the x values of the bin centers
       YCENTERS = the corresponding y values

 OPTIONAL INPUT KEYWORDS:
       /NOPLOT  If set, nothing is drawn

       Any plotting keywords (e.g. XTITLE) may be supplied to AUTOHIST through
       the _EXTRA facility. 
 REVISION HISTORY:
       Written,   H. Freudenreich, STX, 1/91
       1998 March 17 - Changed shading of histogram.  RSH, RSTX
       V5.0 update, _EXTRA keywords  W. Landsman    April 2002
       Added NOCLIP keyword for POLYFILL call C. Paxson/W. Landsman July 2003

(See goddard/pro/robust/autohist.pro)


AVG

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       AVG
 PURPOSE:
       Return the average value of an array, or 1 dimension of an array
 EXPLANATION:
       Calculate the average value of an array (in which case AVG is identical
       to the RSI procedure mean.pro), or calculate the average
       value over one dimension of an array as a function of all the other
       dimensions.

 CALLING SEQUENCE:
       RESULT = AVG( ARRAY, [ DIMENSION, /NAN, /DOUBLE ] )

 INPUTS:
       ARRAY = Input array.  May be any type except string.

 OPTIONAL INPUT PARAMETERS:
       DIMENSION = Optional dimension to do average over, integer scalar

 OPTIONAL KEYWORD INPUT:
      /NAN - Set this keyword to cause the routine to check for occurrences of
            the IEEE floating-point value NaN in the input data.  Elements with
            the value NaN are treated as missing data.
      /DOUBLE - By default, if the input Array is double-precision, complex, 
                or double complex, the result is of the same type;  64 bit
                integers are also returned as double.   Otherwise the result
                the  result is floating-point.   Use of the /DOUBLE keyword 
                forces a double precision output.   Note that internal 
                computations are always done in double precision.
 OUTPUTS:
       The average value of the array when called with one parameter.

       If DIMENSION is passed, then the result is an array with all the
       dimensions of the input array except for the dimension specified,
       each element of which is the average of the corresponding vector
       in the input array.

       For example, if A is an array with dimensions of (3,4,5), then the
       command B = AVG(A,1) is equivalent to

                       B = FLTARR(3,5)
                       FOR J = 0,4 DO BEGIN
                               FOR I = 0,2 DO BEGIN
                                       B[I,J] = TOTAL( A[I,*,J] ) / 4.
                               ENDFOR
                       ENDFOR

 RESTRICTIONS:
       Dimension specified must be valid for the array passed; otherwise the
       input array is returned as the output array.
 PROCEDURE:
       AVG(ARRAY) = TOTAL(ARRAY, /DOUBLE)/N_ELEMENTS(ARRAY) when called with 
       one parameter.
 MODIFICATION HISTORY:
       William Thompson        Applied Research Corporation
       July, 1986              8201 Corporate Drive
                               Landover, MD  20785
       Converted to Version 2      July, 1990
       Replace SUM call with TOTAL    W. Landsman    May, 1992
       Converted to IDL V5.0   W. Landsman   September 1997
       Added /NAN keyword   W. Landsman      July 2000
       Accept a scalar input value    W. Landsman/jimm@berkeley   November 2000
       Internal calculations always in double precision W. Landsman March 2002
       Return NAN if all values in array are NAN  W. Landsman April 2002
       Fixed coding bug if all values in array are NAN W. Landsman Jan 2004

(See goddard/pro/math/avg.pro)


A_B

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
     A_b
 PURPOSE:
     Compute B band interstellar extinction according to the RC2.
 EXPLANATION:
     The predicted B band extinction is computed as a function of  
     Galactic position  using the 21 parameter function given by
     deVaucouleurs in the 2nd Reference Catalog of Galaxies (RC2).   Note 
     that this formula was not used for the RC3 and that reddenings
     were instead obtained from the Burstein-Heiles 21 cm maps.

 CALLING SEQUENCE:
     result = A_b( l2, b2)

 INPUT PARAMETERS
     l2 = Galactic longitude (degrees), scalar or vector
     b2 = Galactic latitude  (degrees), scalar or vector

 OUTPUT PARAMETERS
     RESULT - Interstellar extinction Ab in magnitudes, same number of 
             elements as input l2 and b2 parameters

 NOTES:
     The controversial aspect of the deVaucouleurs reddening curve
     is that it predicts an extinction of about 0.2 at the poles 

     The parameters used here differ from the ones printed in the RC2
     but are the ones actually used for entries in the catalog
     (see Rowan-Robinson 1985) 

     This procedure is mainly of historical interest only, and reddening
     is now better determined using dust maps, such as those available at
     http://astro.berkeley.edu/davis/dust/index.html
 REVISION HISTORY
     Written by R. Cornett and W. Landsman, STX October 1987
     Vectorized code      W. Landsman   STX    December 1992
     Converted to IDL V5.0   W. Landsman   September 1997

(See goddard/pro/astro/a_b.pro)


BARYVEL

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       BARYVEL
 PURPOSE:
       Calculates heliocentric and barycentric velocity components of Earth.

 EXPLANATION:
       BARYVEL takes into account the Earth-Moon motion, and is useful for 
       radial velocity work to an accuracy of  ~1 m/s.

 CALLING SEQUENCE:
       BARYVEL, dje, deq, dvelh, dvelb, [ JPL =  ] 

 INPUTS:
       DJE - (scalar) Julian ephemeris date.
       DEQ - (scalar) epoch of mean equinox of dvelh and dvelb. If deq=0
               then deq is assumed to be equal to dje.
 OUTPUTS: 
       DVELH: (vector(3)) heliocentric velocity component. in km/s 
       DVELB: (vector(3)) barycentric velocity component. in km/s

       The 3-vectors DVELH and DVELB are given in a right-handed coordinate 
       system with the +X axis toward the Vernal Equinox, and +Z axis 
       toward the celestial pole.      

 OPTIONAL KEYWORD SET:
       JPL - if /JPL set, then BARYVEL will call the procedure JPLEPHINTERP
             to compute the Earth velocity using the full JPL ephemeris.   
             The JPL ephemeris FITS file JPLEPH.405 must exist in either the 
             current directory, or in the directory specified by the 
             environment variable ASTRO_DATA.   Alternatively, the JPL keyword
             can be set to the full path and name of the ephemeris file.
             A copy of the JPL ephemeris FITS file is available in
                 http://idlastro.gsfc.nasa.gov/ftp/data/         
 PROCEDURES CALLED:
       Function PREMAT() -- computes precession matrix
       JPLEPHREAD, JPLEPHINTERP, TDB2TDT - if /JPL keyword is set
 NOTES:
       Algorithm taken from FORTRAN program of Stumpff (1980, A&A Suppl, 41,1)
       Stumpf claimed an accuracy of 42 cm/s for the velocity.    A 
       comparison with the JPL FORTRAN planetary ephemeris program PLEPH
       found agreement to within about 65 cm/s between 1986 and 1994

       If /JPL is set (using JPLEPH.405 ephemeris file) then velocities are 
       given in the ICRS system; otherwise in the FK4 system.   
 EXAMPLE:
       Compute the radial velocity of the Earth toward Altair on 15-Feb-1994
          using both the original Stumpf algorithm and the JPL ephemeris

       IDL> jdcnv, 1994, 2, 15, 0, jd          ;==> JD = 2449398.5
       IDL> baryvel, jd, 2000, vh, vb          ;Original algorithm
               ==> vh = [-17.07809, -22.80063, -9.885281]  ;Heliocentric km/s
               ==> vb = [-17.08083, -22.80471, -9.886582]  ;Barycentric km/s
       IDL> baryvel, jd, 20000, vh, vb, /jpl   ;JPL ephemeris
               ==> vh = [-17.10746, -22.78912, -9.879800]  ;Heliocentric km/s
               ==> vb = [-17.11591, -22.78269, -9.876785]  ;Barycentric km/s

       IDL> ra = ten(19,50,46.77)*15/!RADEG    ;RA  in radians
       IDL> dec = ten(08,52,3.5)/!RADEG        ;Dec in radians
       IDL> v = vb(0)*cos(dec)*cos(ra) + $   ;Project velocity toward star
               vb(1)*cos(dec)*sin(ra) + vb(2)*sin(dec) 

 REVISION HISTORY:
       Jeff Valenti,  U.C. Berkeley    Translated BARVEL.FOR to IDL.
       W. Landsman, Cleaned up program sent by Chris McCarthy (SfSU) June 1994
       Converted to IDL V5.0   W. Landsman   September 1997
        Added /JPL keyword  W. Landsman   July 2001

(See goddard/pro/astro/baryvel.pro)


BIWEIGHT_MEAN

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	BIWEIGHT_MEAN 

 PURPOSE:
	Calculate the center and dispersion (like mean and sigma) of a 
	distribution using bisquare weighting.

 CALLING SEQUENCE:
	Mean = BIWEIGHT_MEAN( Vector, [ Sigma, Weights ] ) 

 INPUTS:
	Vector = Distribution in vector form

 OUTPUT:
	Mean - The location of the center.

 OPTIONAL OUTPUT ARGUMENTS:

	Sigma = An outlier-resistant measure of the dispersion about the 
	      center, analogous to the standard deviation. 

	Weights = The weights applied to the data in the last iteration, 
                 floating point vector

 NOTES:
       Since a sample mean  scaled by sigma/sqrt(N), has a Student's T 
       distribution, the half-width of the  95% confidence interval for 
       the sample mean  can be determined as follows: 
          ABS( T_CVF( .975, .7*(N-1) )*SIGMA/SQRT(N) ) 
       where N = number of  points, and  0.975 = 1 - (1 - 0.95)/2. 
 PROCEDURES USED:
       ROBUST_SIGMA()
 REVISION HISTORY
	Written,  H. Freudenreich, STX, 12/89
	Modified 2/94, H.T.F.: use a biweighted standard deviation rather than
		median absolute deviation.
	Modified 2/94, H.T.F.: use the fractional change in SIGMA as the 
		convergence criterion rather than the change in center/SIGMA.
       Modified May 2002  Use MEDIAN(/EVEN)
       Modified October 2002, Faster computation of weights 
       Corrected documentation on 95% confidence interval of mean 
                 P.Broos/W. Landsman   July 2003 

(See goddard/pro/robust/biweight_mean.pro)


BLINK

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	BLINK
 PURPOSE:
	To allow the user to alternatively examine two or more windows within
	a single window.

 CALLING SEQUENCE:
	BLINK, Wndw [, T]

 INPUTS:
	Wndw  A vector containing the indices of the windows to blink.
	T     The time to wait, in seconds, between blinks.  This is optional
	      and set to 1 if not present.  

 OUTPUTS:
	None.

 PROCEDURE:
	The images contained in the windows given are written to a pixmap.
	The contents of the the windows are copied to a display window, in 
	order, until a key is struck.

 EXAMPLE:
	Blink windows 0 and 2 with a wait time of 3 seconds

	IDL> blink, [0,2], 3 

 MODIFICATION HISTORY:
	Written by Michael R. Greason, STX, 2 May 1990.
	Allow different size windows   Wayne Landsman    August, 1991
	Converted to IDL V5.0   W. Landsman   September 1997

(See goddard/pro/tv/blink.pro)


BLKSHIFT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   BLKSHIFT

 AUTHOR:
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov

 PURPOSE:
   Shift a block of data to a new position in a file (possibly overlapping)

 MAJOR TOPICS:
   File I/O

 CALLING SEQUENCE:

   BLKSHIFT, UNIT, POS, [ DELTA, TO=TO, /NOZERO, ERRMSG=ERRMSG, 
             BUFFERSIZE=BUFFERSIZE ]

 DESCRIPTION:

  BLKSHIFT moves a block of data forward or backward, to a new
  position in a data file.  The old and new positions of the block
  can overlap safely.

  The new position can be specified with either the DELTA parameter,
  which gives the number of bytes to move forward (positive delta) or
  backward (negative delta); or the TO keyword, which give the new
  absolute starting position of the block.

  The block can be moved beyond the current end of file point, in
  which case the intervening gap is filled with zeros (optionally).
  The gap left at the old position of the block is also optionally
  zero-filled.    If a set of data up to the end of the file is being
  moved forward (thus making the file smaller) and the IDL version is 
  5.6 or larger (so that the TRUNCATE_LUN procedure is available) then
  the file is truncated at the new end.

 INPUTS:

   UNIT - a logical unit number, opened for reading and writing.

   POS - POS[0] is the position of the block in the file, in bytes,
         before moving.  POS[1], if present, is the size of the block
         in bytes.  If POS[1] is not given, then the block is from
         POS[0] to the end of the file.

   DELTA - the (optional) offset in bytes between the old and new
           positions, from the start of the block.  Positive values
           indicate moving the data forward (toward the end of file),
           and negative values indicate moving the data backward
           (toward the beginning of the file).  One of DELTA and TO
           must be specified; DELTA overrides the TO keyword.

           Attempts to move the block beyond the end of the file will
           succeed.  A block can never be moved beyond the beginning
           of the file; it will be moved to the beginning instead.

 KEYWORD PARAMETERS:

   TO - the absolute file offset in bytes for the new start of the
        block.  One of DELTA and TO must be specified; DELTA
        overrides the TO keyword.

   NOZERO - if set, then newly created gaps will not be explicitly
            zeroed.  However, for some operating systems (Mac and
            VMS), zeroing is required and will be done anyway.

   ERRMSG - If defined and passed, then any error messages will be
            returned to the user in this parameter rather than
            depending on the MESSAGE routine in IDL.  If no errors
            are encountered, then a null string is returned.  In
            order to use this feature, ERRMSG must be defined first,
            e.g.
			ERRMSG = ''
			FXBGROW, ERRMSG=ERRMSG, ...
			IF ERRMSG NE '' THEN ...

   BUFFERSIZE - the maximum buffer size for transfers, in bytes.
                Larger values of this keyword impose larger memory
                requirements on the application; smaller values will
                lead to more transfer operations.
                Default: 32768 (bytes)

 MODIFICATION HISTORY:

   Written, CM, Apr 2000
   Documented and re-written, CM, 20 Jul 2000
   Renamed from FXSHIFT to BLKSHIFT, CM, 21 Jul 2000
   Documentation, CM, 12 Dec 2002
   Truncate if moving data block forward from  the end of file 
             using TRUNCATE_LUN   W. Landsman Feb. 2005 

(See goddard/pro/misc/blkshift.pro)


BOOST_ARRAY

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	BOOST_ARRAY
 PURPOSE:
	Append one array onto a destination array
 EXPLANATION:
	Add array APPEND to array DESTINATION, allowing the dimensions of
	DESTINATION to adjust to accomodate it.  If both input arrays have the
	same number of dimensions, then the output array will have one
	additional dimension.  Otherwise, the last dimension of DESTINATION
	will be incremented by one.
 CATEGORY:
	Utility
 CALLING SEQUENCE:
	BOOST_ARRAY, DESTINATION, APPEND
 INPUT:
	DESTINATION	= Array to be expanded.
	APPEND		= Array to append to DESTINATION.
 OUTPUTS:
	DESTINATION	= Expanded output array.
 RESTRICTIONS:
	DESTINATION and APPEND have to be either both of type string or both of
	numerical types.

	APPEND cannot have more dimensions than DESTINATION.

 MODIFICATION HISTOBY:
	Written Aug'88 (DMZ, ARC)
	Modified Sep'89 to handle byte arrays (DMZ)
	Modifed to version 2, Paul Hick (ARC), Feb 1991
	Removed restriction to 2D arrays, William Thompson (ARC), Feb 1992.
	Converted to IDL V5.0   W. Landsman   September 1997

(See goddard/pro/misc/boost_array.pro)


BOXAVE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       BOXAVE
 PURPOSE:
       Box-average a 1 or 2 dimensional array.
 EXPLANATION:   
       This procedure differs from the intrinsic REBIN function in the 
       following 2 ways: 

       (1) the box size parameter is specified rather than the output 
               array size
       (2) for INTEGER arrays, BOXAVE computes intermediate steps using REAL*4 
               arithmetic.   This is considerably slower than REBIN but avoids 
               integer truncation

       A version of BOXAVE() that supports 64 bit integers is available for
       V5.4 or later in http://idlastro.gsfc.nasa.gov/ftp/v54/
 CALLING SEQUENCE:
       result = BOXAVE( Array, Xsize,[ Ysize ] )     

 INPUTS:
       ARRAY - Two dimensional input Array to be box-averaged.  Array may be 
               one or 2 dimensions and of any type except character.   

 OPTIONAL INPUTS:
       XSIZE - Size of box in the X direction, over which the array is to
               be averaged.  If omitted, program will prompt for this 
               parameter.  
       YSIZE - For 2 dimensional arrays, the box size in the Y direction.
               If omitted, then the box size in the X and Y directions are 
               assumed to be equal

 OUTPUT:
       RESULT - Output array after box averaging.  If the input array has 
               dimensions XDIM by YDIM, then RESULT has dimensions
               XDIM/NBOX by YDIM/NBOX.  The type of RESULT is the same as
               the input array.  However, the averaging is always computed
               using REAL arithmetic, so that the calculation should be exact.
               If the box size did not exactly divide the input array, then
               then not all of the input array will be boxaveraged.

 PROCEDURE:
       BOXAVE boxaverages all points simultaneously using vector subscripting

 NOTES:
       If im_int is a 512 x 512 integer array, then the two statements

               IDL> im = fix(round(rebin(float(im_int), 128, 128)))
               IDL> im  = boxave( im_int,4)

       give equivalent results.   The use of REBIN is faster, but BOXAVE is
       is less demanding on virtual memory, since one does not need to make
       a floating point copy of the entire array.      

 REVISION HISTORY:
       Written, W. Landsman, October 1986
       Call REBIN for REAL*4 and REAL*8 input arrays, W. Landsman Jan, 1992
       Removed /NOZERO in output array definition     W. Landsman 1995
       Fixed occasional integer overflow problem      W. Landsman Sep. 1995
       Allow unsigned data types                      W. Landsman Jan. 2000

(See goddard/pro/image/boxave.pro)


BPRECESS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       BPRECESS
 PURPOSE:
       Precess positions from J2000.0 (FK5) to B1950.0 (FK4)
 EXPLANATION:
       Calculates the mean place of a star at B1950.0 on the FK4 system from
       the mean place at J2000.0 on the FK5 system.    

 CALLING SEQUENCE:
       bprecess, ra, dec, ra_1950, dec_1950, [ MU_RADEC = , PARALLAX = 
                                       RAD_VEL =, EPOCH =   ]

 INPUTS:
       RA,DEC - Input J2000 right ascension and declination in *degrees*.
               Scalar or N element vector

 OUTPUTS:
       RA_1950, DEC_1950 - The corresponding B1950 right ascension and 
               declination in *degrees*.    Same number of elements as
               RA,DEC but always double precision.

 OPTIONAL INPUT-OUTPUT KEYWORDS
       MU_RADEC - 2xN element double precision vector containing the proper 
                  motion in seconds of arc per tropical *century* in right 
                  ascension and declination.
       PARALLAX - N_element vector giving stellar parallax (seconds of arc)
       RAD_VEL  - N_element vector giving radial velocity in km/s

       The values of MU_RADEC, PARALLAX, and RADVEL will all be modified
       upon output to contain the values of these quantities in the
       B1950 system.  The parallax and radial velocity will have a very 
       minor influence on the B1950 position.   

       EPOCH - scalar giving epoch of original observations, default 2000.0d
           This keyword value is only used if the MU_RADEC keyword is not set.
 NOTES:
       The algorithm is taken from the Explanatory Supplement to the 
       Astronomical Almanac 1992, page 186.
       Also see Aoki et al (1983), A&A, 128,263

       BPRECESS distinguishes between the following two cases:
       (1) The proper motion is known and non-zero
       (2) the proper motion is unknown or known to be exactly zero (i.e.
               extragalactic radio sources).   In this case, the reverse of 
               the algorithm in Appendix 2 of Aoki et al. (1983) is used to 
               ensure that the output proper motion is  exactly zero. Better 
               precision can be achieved in this case by inputting the EPOCH 
               of the original observations.

       The error in using the IDL procedure PRECESS for converting between
       B1950 and J1950 can be up to 1.5", mainly in right ascension.   If
       better accuracy than this is needed then BPRECESS should be used.

       An unsystematic comparison of BPRECESS with the IPAC precession 
       routine (http://nedwww.ipac.caltech.edu/forms/calculator.html) always 
       gives differences less than 0.15".
 EXAMPLE:
       The SAO2000 catalogue gives the J2000 position and proper motion for
       the star HD 119288.   Find the B1950 position. 

       RA(2000) = 13h 42m 12.740s      Dec(2000) = 8d 23' 17.69''  
       Mu(RA) = -.0257 s/yr      Mu(Dec) = -.090 ''/yr

       IDL> mu_radec = 100D* [ -15D*.0257, -0.090 ]
       IDL> ra = ten(13, 42, 12.740)*15.D 
       IDL> dec = ten(8, 23, 17.69)
       IDL> bprecess, ra, dec, ra1950, dec1950, mu_radec = mu_radec
       IDL> print, adstring(ra1950, dec1950,2)
               ===> 13h 39m 44.526s    +08d 38' 28.63"

 REVISION HISTORY:
       Written,    W. Landsman                October, 1992
       Vectorized, W. Landsman                February, 1994
       Treat case where proper motion not known or exactly zero  November 1994
       Handling of arrays larger than 32767   Lars L. Christensen, march, 1995
       Converted to IDL V5.0   W. Landsman   September 1997
       Fixed bug where A term not initialized for vector input 
            W. Landsman        February 2000
       

(See goddard/pro/astro/bprecess.pro)


BREAK_PATH()

[Previous Routine] [Next Routine] [List of Routines]
 NAME: 
    BREAK_PATH()

 PURPOSE: 
     Breaks up a path string into its component directories.

 CALLING SEQUENCE: 
     Result = BREAK_PATH( PATHS [ /NoCurrent])

 INPUTS: 
     PATHS   = A string containing one or more directory paths.  The
               individual paths are separated by commas, although in UNIX, 
               colons can also be used.  In other words, PATHS has the same 
               format as !PATH, except that commas can be used as a separator 
               regardless of operating system.

               A leading $ can be used in any path to signal that what follows 
               is an environmental variable, but the $ is not necessary.  (In 
               VMS the $ can either be part of the path, or can signal logical
               names for compatibility with Unix.)  Environmental variables
               can themselves contain multiple paths.

 OUTPUT: 
      The result of the function is a string array of directories.
      Unless the NOCURRENT keyword is set, the first element of the array is 
      always the null string, representing the current directory.  All the 
      other directories will end in the correct separator character for the 
      current operating system.

 OPTIONAL INPUT KEYWORD:
      /NOCURRENT = If set, then the current directory (represented by
               the null string) will not automatically be prepended to the
               output.

 PROCEDURE CALLS:
      None.

 REVISION HISTORY:
       Version 1, William Thompson, GSFC, 6 May 1993.
               Added IDL for Windows compatibility.
       Version 2, William Thompson, GSFC, 16 May 1995
               Added keyword NOCURRENT
       Version 3, William Thompson, GSFC, 29 August 1995
               Modified to use OS_FAMILY
       Version 4, Zarro, GSFC, 4 August 1997
               Added trim to input
       Converted to IDL V5.0   W. Landsman 25-Nov-1997
       Fix directory character on Macintosh system   A. Ferro   February 2000
       Use STRSPLIT instead of STR_SEP()   W. Landsman    July 2002

(See goddard/pro/misc/break_path.pro)


BSORT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       BSORT
 PURPOSE:
       Function to sort data into ascending order, like a simple bubble sort.
 EXPLANATION:
       Original subscript order is maintained when values are equal (FIFO).
       (This differs from the IDL SORT routine alone, which may rearrange 
       order for equal values)

 CALLING SEQUENCE:  
       result = bsort( array, [ asort, /INFO, /REVERSE ] )

 INPUT:
       Array - array to be sorted

 OUTPUT:
       result - sort subscripts are returned as function value

 OPTIONAL OUTPUT:
       Asort - sorted array

 OPTIONAL KEYWORD INPUTS:
       /REVERSE - if this keyword is set, and non-zero, then data is sorted
                 in descending order instead of ascending order.
       /INFO = optional keyword to cause brief message about # equal values.

 HISTORY
       written by F. Varosi Oct.90:
       uses WHERE to find equal clumps, instead of looping with IF ( EQ ).
       compatible with string arrays, test for degenerate array 
       20-MAY-1991     JKF/ACC via T AKE- return indexes if the array to 
                       be sorted has all equal values.
       Aug - 91  Added  REVERSE keyword   W. Landsman      
       Always return type LONG    W. Landsman     August 1994
       Converted to IDL V5.0   W. Landsman   September 1997

(See goddard/pro/misc/bsort.pro)


CALZ_UNRED

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
     CALZ_UNRED
 PURPOSE:
     Deredden a galaxy spectrum using the Calzetti et al. (2000) recipe
 EXPLANATION:
     Calzetti et al.  (2000, ApJ 533, 682) developed a recipe for dereddening 
     the spectra of galaxies where massive stars dominate the radiation output,
     valid between 0.12 to 2.2 microns.     (CALZ_UNRED extrapolates between
     0.12 and 0.0912 microns.)   

 CALLING SEQUENCE:
     CALZ_UNRED, wave, flux, ebv, [ funred, R_V = ]
 INPUT:
      WAVE - wavelength vector (Angstroms)
      FLUX - calibrated flux vector, same number of elements as WAVE
               If only 3 parameters are supplied, then this vector will
               updated on output to contain the dereddened flux.
      EBV  - color excess E(B-V), scalar.  If a negative EBV is supplied,
               then fluxes will be reddened rather than deredenned.
               Note that the supplied color excess should be that derived for 
               the stellar  continuum, EBV(stars), which is related to the 
               reddening derived from the gas, EBV(gas), via the Balmer 
               decrement by EBV(stars) = 0.44*EBV(gas)

 OUTPUT:
      FUNRED - unreddened flux vector, same units and number of elements
               as FLUX.   FUNRED values will be zeroed outside valid domain
               Calz_unred (0.0912 - 2.2 microns).
           
 OPTIONAL INPUT KEYWORD:
       R_V - Ratio of total to selective extinction, default = 4.05.  
             Calzetti et al. (2000) estimate R_V = 4.05 +/- 0.80 from optical
             -IR observations of 4 starbursts.
 EXAMPLE:
       Estimate how a flat galaxy spectrum (in wavelength) between 1200 A 
       and 3200 A is altered by a reddening of E(B-V) = 0.1.   

       IDL> w = 1200 + findgen(40)*50      ;Create a wavelength vector
       IDL> f = w*0 + 1                    ;Create a "flat" flux vector
       IDL> calz_unred, w, f, -0.1, fnew  ;Redden (negative E(B-V)) flux vector
       IDL> plot,w,fnew                   

 NOTES:
       Use the 4 parameter calling sequence if you wish to save the 
               original flux vector.
 PROCEDURE CALLS:
      POLY()
 REVISION HISTORY:
       Written   W. Landsman        Raytheon  ITSS   December, 2000

(See goddard/pro/astro/calz_unred.pro)


CCM_UNRED

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
     CCM_UNRED
 PURPOSE:
     Deredden a flux vector using the CCM 1989 parameterization 
 EXPLANATION:
     The reddening curve is that of Cardelli, Clayton, and Mathis (1989 ApJ.
     345, 245), including the update for the near-UV given by O'Donnell 
     (1994, ApJ, 422, 158).   Parameterization is valid from the IR to the 
     far-UV (3.5 microns to 0.1 microns).    

     Users might wish to consider using the alternate procedure FM_UNRED
     which uses the extinction curve of Fitzpatrick (1999).
 CALLING SEQUENCE:
     CCM_UNRED, wave, flux, ebv, funred, [ R_V = ]      
             or 
     CCM_UNRED, wave, flux, ebv, [ R_V = ]      
 INPUT:
     WAVE - wavelength vector (Angstroms)
     FLUX - calibrated flux vector, same number of elements as WAVE
             If only 3 parameters are supplied, then this vector will
             updated on output to contain the dereddened flux.
     EBV  - color excess E(B-V), scalar.  If a negative EBV is supplied,
             then fluxes will be reddened rather than deredenned.

 OUTPUT:
     FUNRED - unreddened flux vector, same units and number of elements
             as FLUX

 OPTIONAL INPUT KEYWORD
     R_V - scalar specifying the ratio of total selective extinction
             R(V) = A(V) / E(B - V).    If not specified, then R_V = 3.1
             Extreme values of R(V) range from 2.75 to 5.3

 EXAMPLE:
     Determine how a flat spectrum (in wavelength) between 1200 A and 3200 A
     is altered by a reddening of E(B-V) = 0.1.   Assume an "average"
     reddening for the diffuse interstellar medium (R(V) = 3.1)

       IDL> w = 1200 + findgen(40)*50      ;Create a wavelength vector
       IDL> f = w*0 + 1                    ;Create a "flat" flux vector
       IDL> ccm_unred, w, f, -0.1, fnew  ;Redden (negative E(B-V)) flux vector
       IDL> plot,w,fnew                   

 NOTES:
     (1) The CCM curve shows good agreement with the Savage & Mathis (1979)
             ultraviolet curve shortward of 1400 A, but is probably
             preferable between 1200 and 1400 A.
     (2)  Many sightlines with peculiar ultraviolet interstellar extinction 
             can be represented with a CCM curve, if the proper value of 
             R(V) is supplied.
     (3)  Curve is extrapolated between 912 and 1000 A as suggested by
             Longo et al. (1989, ApJ, 339,474)
     (4) Use the 4 parameter calling sequence if you wish to save the 
               original flux vector.
     (5) Valencic et al. (2004, ApJ, 616, 912) revise the ultraviolet CCM
             curve (3.3 -- 8.0 um-1).    But since their revised curve does
             not connect smoothly with longer and shorter wavelengths, it is
             not included here.

 REVISION HISTORY:
       Written   W. Landsman        Hughes/STX   January, 1992
       Extrapolate curve for wavelengths between 900 and 1000 A   Dec. 1993
       Use updated coefficients for near-UV from O'Donnell   Feb 1994
       Allow 3 parameter calling sequence      April 1998
       Converted to IDLV5.0                    April 1998

(See goddard/pro/astro/ccm_unred.pro)


CHECKSUM32

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CHECKSUM32

 PURPOSE:
       To compute the 32bit checksum of an array (ones-complement arithmetic)

 EXPLANATION:
       The 32bit checksum is adopted in the FITS Checksum convention
       http://heasarc.gsfc.nasa.gov/docs/heasarc/fits/checksum.html

 CALLING SEQUENCE:
       CHECKSUM32, array, checksum, [/FROM_IEEE, /NoSAVE]

 INPUTS:
       array - any numeric idl array.  If the number of bytes in the array is 
               not a multiple of four then it is padded with zeros internally
               (the array is returned unchanged).   Convert a string array 
               (e.g. a FITS header) to bytes prior to calling CHECKSUM32.

 OUTPUTS:
       checksum - unsigned long scalar, giving sum of array elements using 
                  ones-complement arithmetic
 OPTIONAL INPUT KEYWORD:

      /FROM_IEEE - If this keyword is set, then the input is assumed to be in
           big endian format (e.g. an untranslated FITS array).   This keyword
           only has an effect on little endian machines (e.g. Linux boxes).

      /NoSAVE - if set, then the input array is not saved upon exiting.   Use 
           the /NoSave keyword to save time if the input array is not needed 
           in further computations. 
 METHOD:
       Uses TOTAL() to sum the array into a double precision variable.  The
       overflow bits beyond 2^32 are then shifted back to the least significant
       bits.    Due to the limited precision of a DOUBLE variable, the summing
       is done in chunks determined by MACHAR(). Adapted from FORTRAN code in
      heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/general/checksum/node30.html

      Could probably be done in a cleverer way (similar to the C
      implementation) but then the array-oriented TOTAL() function could not 
      be used.
 RESTRICTIONS:
       (1) Requires V5.2 or later (uses unsigned integers)
       (2) Not valid for object or pointer data types
 EXAMPLE:
       Find the 32 bit checksum of the array x = findgen(35)

       IDL> checksum32, x, s    ===> s =  2920022024
 FUNCTION CALLED:
       IS_IEEE_BIG(), N_BYTES()
 MODIFICATION HISTORY:
       Written    W. Landsman          June 2001
       Work correctly on little endian machines, added /FROM_IEEE and /NoSave
                  W. Landsman          November 2002
       Pad with zeros when array size not a multiple of 4 W.Landsman Aug 2003
       Always copy to new array, somewhat slower but more robust algorithm
           especially for Linux boxes   W. Landsman Sep. 2004 
       Sep. 2004 update not implemented correctly (sigh) W. Landsman Dec 2004         
       

(See goddard/pro/misc/checksum32.pro)


CHECK_FITS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CHECK_FITS
 PURPOSE:
       Check that keywords in a FITS header array match the associated data  
 EXPLANATION:
       Given a FITS array IM, and a associated FITS or STSDAS header HDR, this
       procedure will check that
               (1) HDR is a string array, and IM is defined and numeric   
               (2) The NAXISi values in HDR are appropriate to the dimensions 
                   of IM
               (3) The BITPIX value in HDR is appropriate to the datatype of IM
       If HDR contains a DATATYPE keyword (as in STSDAS headers), then this is 
       also checked against the datatype of of IM
       If the /UPDATE keyword is present, then the FITS header will be 
       modified, if necessary, to force agreement with the image array

 CALLING SEQUENCE:
       check_FITS, im, hdr, [ dimen, idltype, /UPDATE, /NOTYPE, /SDAS, /SILENT
                              ERRMSG = ]'

 INPUT PARAMETERS:
       IM -  FITS (or STSDAS) array, e.g. as read by READFITS
       HDR - FITS (or STSDAS) header (string array) associated with IM

 OPTIONAL OUTPUTS:
       dimen - vector containing actual array dimensions
       idltype- data type of the FITS array as specified in the IDL SIZE
               function (1 for BYTE, 2 for INTEGER*2, 3