IDL Help for IDLUTILS

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:16 2006.


List of Routines


Routine Descriptions

ACSSIP_AD2XY

[Next Routine] [List of Routines]
  NAME:
    acssip_ad2xy

  PURPOSE:
    Read new ACS _flt.fits header to invert distortion matrix and
    find distorted x & y positions given tangent RA/Dec in arcseconds
    relative to the center pixel (CRPIX1,2). Will only work with headers 
    that have A_p_q, B_p_q keywords (after Aug 2004), 
    and are only found in extensions 1 (CCD #2) and 4 (CCD #1).

  CALLING SEQUENCE:
    acssip_xy2ad,  ra, dec, hdr, xd, yd

  INPUT:
    ra          : right ascension in arcseconds in the tangent plane from 
                  the pixel desginated by (CRPIX1-1, CRPIX2-1)
    dec         : declination in arcseconds
    hdr         : ACS header, designed for WFC, from HDU #1 or #4 in _flt files
    
  OUTPUT:
    xd          : distorted pixel column in native CCD frame
    yd          : distorted pixel row in native CCD frame

  SUBROUTINES CALLED:
    sxpar()

  COMMENTS: 
    Based on the reference of "The SIP Convention for Representing 
      Distortion in FITS Image Headers"
    by Shupe et al. 2005.

  BUGS:
    Doesn't do the tangent-plane projection correctly; i.e., this
      assumes that tan(theta)=theta.

  REVISION HISTORY
    Implemented by S. Burles during the lost year of 05. 

(See pro/astrom/acssip_ad2xy.pro)


ACSSIP_INVERT

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

  COMMENTS: 
    Based on the reference of "The SIP Convention for Representing 
      Distortion in FITS Image Headers", by Shupe et al. 2005.
    Iterates the distortion correction to invert the distortion pixel map

  EXAMPLE:

    adxy, hdr, ra, dec, xl, yl
    acssip_invert, xl, yl, hdr, x, y

  REVISION HISTORY:
    Implemented by S. Burles during the lost year of 05. 

(See pro/astrom/acssip_invert.pro)


ACSSIP_XY2AD

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

  PURPOSE:
    Read new ACS _flt.fits header to convert pixel locations into
    RA/Dec pairs relative to CRPIX1,2.  Will only work with headers
    that have A_p_q, B_p_q keywords (after Aug 2004), and are only found
    in extensions 1 (CCD #2) and 4 (CCD #1)

  CALLING SEQUENCE:
    acssip_xy2ad,  pix_col, pix_row, hdr, ra, dec

  INPUT:
    pix_col     : any dimension array containing pixel column positions
    pix_row     : any dimension array containing pixel row positions
    hdr         : ACS header, designed for WFC, from HDU #1 or #4 in _flt files
    
  OUTPUT:
    ra          : right ascension in arcseconds in the tangent plane from 
                  the pixel desginated by (CRPIX1-1, CRPIX2-1)
    dec         : declination in arcseconds

  SUBROUTINES CALLED:
    sxpar()

  COMMENTS: 
    Based on the reference of "The SIP Convention for Representing 
      Distortion in FITS Image Headers"
    by Shupe et al. 2005.

  BUGS:
    Doesn't do the tangent-plane projection correctly; i.e., this
      assumes that tan(theta)=theta.

  REVISION HISTORY
    Implemented by S. Burles during the lost year of 05. 

(See pro/astrom/acssip_xy2ad.pro)


ADJUST_ERROR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
     adjust_error
 PURPOSE:
     given data points, uncertainties, and mean value, determines
     what extra uncertainty yields chi^2/dof=1?
 CALLING SEQUENCE
      adjustment = adjust_error( x, xerr, mean=mean, dof=dof)
 INPUTS:
     x - [N] array of measurements
     xerr - [N] array of estimated measurement uncertainties
 OPTIONAL INPUTS:
     mean - mean value if known [default is computed from x, xerr]
     dof - degrees of freedom, defaults to N; value (even the
           default) is reduced by 1 if mean is not input
     tol - tolerance in adjustment in chi^2 units [default is
           0.01*sqrt(dof)]
     maxiter - maximum number of binary search iterations
 OUTPUT:
     adjustment - minimum uncertainty to add to each xerr (in
                  quadrature) to yield chi^2 <= dof 
 OPTIONAL OUTPUTS:
     niter - number of iterations executed
     chisq - chi^2 corresponding to adjustment
 METHOD:
     dunno
 REVISION HISTORY:
     Blanton & Hogg 2003-07-15 written, tested a bit

(See pro/math/adjust_error.pro)


ALM2HEALPIX

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

 PURPOSE:
   Compute healpix map from spherical harmonic transform (Alm)

 CALLING SEQUENCE:
   map = alm2healpix(nside, alm, lmax=lmax)

 INPUTS:
   nside   - healpix nside (number of pixels is 12*nside^2)
   alm     - dcomplex array of Alm coefficients (Alm[l, m])
                Of course this is zero for l<m
   
 KEYWORDS:
   lmax   - maximum l to compute (Default determined by alm array size)

 OUTPUTS:
   map    - healpix map

 OPTIONAL OUTPUTS:
   
 RESTRICTIONS:
   
 EXAMPLES:
   
 COMMENTS:
   Something is a little funny (part in 1 million) at the poles

 REVISION HISTORY:
   2003-Mar-14  Written by Douglas Finkbeiner, Princeton
   2003-Nov-12  Can do many maps at once, sped up - DPF & NP

(See pro/healpix/alm2healpix.pro)


ANGDIDIS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   angdidis
 PURPOSE:
   Compute angular diameter distancea (for c/H_0=1).
 CALLING SEQUENCE:
   D= angdidis(z,OmegaM,OmegaL, weq=weq)
 INPUTS:
   z       - redshift or vector of redshifts
   OmegaM  - Omega-matter at z=0
   OmegaL  - Omega-Lambda at z=0
 OPTIONAL INPUTS:
   weq     - Equation of state (Default=-1)
 KEYWORDS
 OUTPUTS:
   angular diameter distance in units of the Hubble length c/H_0
 COMMENTS:
 BUGS:
   May not work for pathological parts of the OmegaM-OmegaL plane.
 EXAMPLES:
 PROCEDURES CALLED:
   propmotdis()
 REVISION HISTORY:
   25-Jun-2000  Written by Hogg (IAS)
   2004-Sep-8, Added equation of state for OmegaL, Padmanabhan
   (Princeton)

(See pro/cosmography/angdidis.pro)


ANGLES_TO_XYZ

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
  angles_to_xyz
 PURPOSE:
  Convert spherical coordinates (r,phi,theta) into Cartesion coordinates
  (x,y,z).  The angles must be in the following ranges:
    0 <= phi < 360
    0 <= theta <= 180
  where theta=0 corresponds to the N pole, and theta=180 is the S pole.
  If you want to convert from RA and DEC, pass the following
  arguments (in degrees):  RA, 90-DEC
 REVISION HISTORY:
  2005-09-10  tweaked - Hogg (NYU)

(See pro/coord/angles_to_xyz.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 (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
     Bug fixed for multiple elements  M Blanton Mar 2002

(See pro/math/asinh2.pro)


ASTROM_ENGINE

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

 PURPOSE:
   Compute astrometric solution for a list of stars & catalogue stars

 CALLING SEQUENCE:
   gsa_out = astrom_engine( xpos, ypos, catlon, catlat, gsa_in, $
    [ search_rad=, search_scale=, search_angle=, $
    poserr=, nmatch=, catind=, obsind=, /radial, /verbose ] )

 INPUTS:
   xpos       - X positions in CCD coordinates
   ypos       - Y positions in CCD coordinates
   catlon     - Catalog star longitudes in the same coordinate system as GSA_IN
   catlat     - Catalog star latitutes in the same coordinate system as GSA_IN
   gsa_in     - Input GSSS structure with initial guess for astrometric
                solution
   radial     - (Not used.)

 OPTIONAL INPUTS:
   search_rad   - Unused ???
   search_scale - Unused ???
   search_angle - If set, then search for rotations offset by +/-SEARCH_ANGLE
                  relative to the input astrometric guess.
   poserr       - Maximum position error in CCD coordinates; default to 1.
                  No stars will be matched at distances further than this.
   verbose      - If set, then be verbose.

 OUTPUTS:
   gsa_out    - Output GSSS structure with astrometric solution;
                return 0 if astrometry failed

 OPTIONAL OUTPUTS:
   nmatch     - Number of matched objects with the input catalog.
   catind     - Indices of CATLON,CATLAT for matched objects.
   obsind     - Indices of XPOS,YPOS for matched objects.

 COMMENTS:
   We assume that we know the scale and rotation well enough, then solve
   for the X,Y offsets by correlating with catalog stars.

 BUGS:
   The match distances are **hard-wired** to 6 arcsec on the first iteration,
   and 3 arcsec on the 2nd iteration???

 PROCEDURES CALLED:
   angle_from_pairs()
   astrom_tweak
   gsssadxy
   gsssxyad
   offset_from_pairs

 REVISION HISTORY:
   10-Jun-2002  Written by D. Schlegel & D. Finkbeiner, Princeton.

(See pro/astrom/astrom_engine.pro)


ASTROM_TWEAK

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

 PURPOSE:
   Tweak astrometric solution, given a good initial guess

 CALLING SEQUENCE:
   gsa_out = astrom_tweak( gsa_in, catra, catdec, imx, imy, $
    [ dtheta=, errflag=, nmatch=, catind=, obsind=, /verbose ] )

 INPUTS:
   gsa_in     - Initial guess for astrometric solution (struct)
   cat        - Structure (with fields .ra, .dec) of catalogue positions
   im         - Structure (with fields .x, .y) of image star positions

 OPTIONAL KEYWORDS:
   dtheta     - Match distance between catalog and image stars;
                default to 5 arcsec
   verbose    - If set, then print sizes of offsets
  
 OUTPUTS:
   gsa_out    - returned guess for astrometric solution (struct);
                0 if solution failed

 OUTPUT OUTPUTS:
   errflag    - Set to 1 if fatal error occurs, 0 otherwise
   nmatch     - Number of matched stars
   catind     - Indices of CATLON,CATLAT for matched objects.
   obsind     - Indices of XPOS,YPOS for matched objects.

 COMMENTS:
   Uses preliminary solution given in astr structure to match image
   and catalogue stars within maxsep pixels of each other.  These
   are then used by astrom_warp to determine a new solution, returned
   in astr.
 
 BUGS:
   The terms AMDX[4],AMDY[4] in the GSSS structure should actually *not*
    be fit for since they are higher-order, but this was the easiest
    way to implement this code???

 PROCEDURES CALLED:
   djs_angle_match()
   gsssadxy
   gsssxyad

 REVISION HISTORY:
   02-Feb-2003  Written by D. Schlegel and D. Hogg, APO

(See pro/astrom/astrom_tweak.pro)


ATV

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       ATV
 
 PURPOSE: 
       Interactive display of 2-D images.

 CATEGORY: 
       Image display.

 CALLING SEQUENCE:
       atv [,array_name OR fits_file] [,min = min_value] [,max=max_value] 
           [,/linear] [,/log] [,/histeq] [,/block]
           [,/align] [,/stretch] [,header = header]

 REQUIRED INPUTS:
       None.  If atv is run with no inputs, the window widgets
       are realized and images can subsequently be passed to atv
       from the command line or from the pull-down file menu.

 OPTIONAL INPUTS:
       array_name: a 2-D data array to display
          OR
       fits_file:  a fits file name, enclosed in single quotes

 KEYWORDS:
       min:        minimum data value to be mapped to the color table
       max:        maximum data value to be mapped to the color table
       linear:     use linear stretch
       log:        use log stretch 
       histeq:     use histogram equalization
       block:      block IDL command line until ATV terminates
       align:      align image with previously displayed image
       stretch:    keep same min and max as previous image
       header:     FITS image header (string array) for use with data array
       
 OUTPUTS:
       None.  
 
 COMMON BLOCKS:
       atv_state:  contains variables describing the display state
       atv_images: contains the internal copies of the display image
       atv_color:  contains colormap vectors
       atv_pdata:  contains plot and text annotation information

 RESTRICTIONS:
       Requires IDL version 5.1 or greater.
       Requires Craig Markwardt's cmps_form.pro routine.
       Requires the GSFC IDL astronomy user's library routines.
       Some features may not work under all operating systems.

 SIDE EFFECTS:
       Modifies the color table.

 EXAMPLE:
       To start atv running, just enter the command 'atv' at the idl
       prompt, either with or without an array name or fits file name 
       as an input.  Only one atv window will be created at a time,
       so if one already exists and another image is passed to atv
       from the idl command line, the new image will be displayed in 
       the pre-existing atv window.

 MODIFICATION HISTORY:
       Written by Aaron J. Barth, with contributions by 
       Douglas Finkbeiner, Michael Liu, David Schlegel, and
       Wesley Colley.  First released 17 December 1998.

       This version is 1.4, last modified 23 June 2003.

       For the most current version, revision history, instructions,
       list of known bugs, and further information, go to:
              http://www.astro.caltech.edu/~barth/atv

       Hacked up by Finkbeiner 5 December 2003 to support healpix.
;-

(See pro/plot/atv.pro)


ATV_HEALCART_IND

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

 PURPOSE:
   Generate and cache healcart pixel index array and header for atv

 CALLING SEQUENCE:
   ind = atv_healcart_ind(image, nest=, header=)

 INPUTS:
   image   - healpix array

 KEYWORDS:
   nest    - indicate nested ordering

 OUTPUTS:
   ind     - index array

 OPTIONAL OUTPUTS:
   header  - mock FITS header for nonstandard HCT projection

 COMMENTS:
   Used by atv. 
   IDLUTILS version of wcsxy2sph.pro recognizes this projection, even
    though it is NOT STANDARD FITS!
   
 REVISION HISTORY:
   2003-May-10  Written by Douglas Finkbeiner, Princeton

(See pro/healpix/atv_healcart_ind.pro)


ATV_JOE_WRITEPS

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

 PURPOSE:
   Write a PostScript file of the current ATV display w/out using a widget

 CALLING SEQUENCE:
   atv_joe_writeps, filename, [ _EXTRA ]

 INPUTS:
   filename   - Name of PostScript file

 OPTIONAL INPUTS:
   aspect     - retain aspect ratio in .ps file
   _EXTRA     - Optional keywords for DEVICE

 OUTPUT:

 OPTIONAL OUTPUTS:

 COMMENTS:
   This routine allows one to send the current contents of the ATV window
   to a PostScript file without using a widget.  This makes it convenient
   for using ATV in a batch mode to make plots (though the ATV window will
   still pop up on your terminal).

   Note that there are a number of defaults set in the call to DEVICE
   that can be over-written in the call to this routine.

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:

 REVISION HISTORY:
   08-May-2003  Written by J. Hennawi and D. Schlegel, Princeton

(See pro/plot/atv_joe_writeps.pro)


BALKAN_PLOT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   balkan_plot
 PURPOSE:
   plot balkans of a set of polygons
 CALLING SEQUENCE:
   balkan_plot, poly [, /over , /noplot, balkans=, weight=, $
      poly=, shading=, verts= ]
 INPUTS:
   poly - [np] mangle polygon structures
 OPTIONAL KEYWORDS:
   /over - overplot previously existing plot
   /noplot - don't actually plot
 OPTIONAL OUTPUTS:
   poly - [np] polygons guessed from the input
   balkans - [nb] balkanized polygons
   weight - [nb] weight to add in each balkanized polygon
   shading - [nb] shading values based on exposure time
   verts - [nb] structure containing vertices 
                     .NVERTS - number of vertices
                     .RA - pointer to array of RA values
                     .DEC - pointer to array of DEC values
 COMMENTS:
   If you want better control over how things get plotted, call with
   the /noplot option and have it return the "verts" and "shading"
   outputs (or you can set the shading yourself based on the
   "weight" output). Then you can do something like the following
   inside your plotting routine:

    loadct, 0
    for i=0L, n_elements(verts)-1L do $
      if(allverts[i].nverts gt 0) then $
      polyfill, *verts[i].ra, *verts[i].dec, color=shading[i], $
      noclip=0

 REVISION HISTORY:
   2005-Jul-07   as exposure_plot for FITS files MRB (NYU)
   2005-Dec-07   rewritten for more generality MRB (NYU)

(See pro/mangle/balkan_plot.pro)


BEATDRIVE

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

 PURPOSE:
   test a new disk partition by writing it full of data and verifying

 CALLING SEQUENCE:
   beatdrive, path, fits=fits, size=size

 INPUTS:
   path   - path to beat on (will make with mkdir -p)

 KEYWORDS:
   fits   - set to write with writefits instead of writeu
   size   - multiply SDSS image size (5574656 bytes) by this factor
   
 OUTPUTS:
   lots of files!

 RESTRICTIONS:
   
 EXAMPLES:
   beatdrive, '/scr1/test'
   
 COMMENTS:
   data file size is 
   5574656 Bytes = 5444 kB = 5.3164 MB = 0.00519180 GB
   
 REVISION HISTORY:
   BOT         Written by Douglas Finkbeiner, Princeton
   10-Dec-2005 checked into idlutils/pro/misc

(See pro/misc/beatdrive.pro)


BEATDRIVE_CHECK

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

 PURPOSE:
   test a new disk partition by reading output of beatdrive.pro

 CALLING SEQUENCE:
   beatdrive_check, path, fits=fits, nocompare=nocompare

 INPUTS:
   path      - path given to beatdrive.pro

 KEYWORDS:
   fits      - set to read with readfits [not implemented]
   nocompare - turn off comparisons for speed.

 EXAMPLES:
   beatdrive_check, '/scr1/test'
   
 COMMENTS:
   data file size is 
   5574656 Bytes = 5444 kB = 5.3164 MB = 0.00519180 GB
   
 REVISION HISTORY:
   BOT         Written by Douglas Finkbeiner, Princeton
   10-Dec-2005 checked into idlutils/pro/misc

(See pro/misc/beatdrive_check.pro)


BH_RDFORT

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

 PURPOSE:
   Read 4*E(B-V) for Burstein & Heiles reddening maps.
   Read values directly from Michael Strauss' Fortran data files.

   This program returns identical results as from Michael Strauss'
   program, but does not allow the interpolation option.

   Regions with no data return values of -14, -99 or -396.  Valid
   data is always > -0.22.

 CALLING SEQUENCE:
   value = bh_rdfort( [ gall, galb, infile=infile, outfile=outfile, $
    bhpath=bhpath ] )

 INPUTS:

 OPTIONAL INPUTS:
   gall:       Galactic longitude(s) in degrees
   galb:       Galactic latitude(s) in degrees
   infile:     If set, then read LCOORD and BCOORD from this file
   outfile:    If set, then write results to this file
   bhpath:     Path name for BH data files

 OUTPUTS:
   value:      4*E(B-V) from Burstein & Heiles reddening maps

 PROCEDURES CALLED:
   readcol

 REVISION HISTORY:
   Written by D. Schlegel, 2 Oct 1997, Durham

(See pro/dust/bh_rdfort.pro)


BLANTON_ONED_MEANPLOT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   blanton_oned_meanplot
 PURPOSE:
   plot sliding mean of one quantity vs one other
 COMMENTS:
 INPUTS:
   x           - data values
   z           - quantity to average
 OPTIONAL INPUTS:
   weight      - weighting for data points; default unity
   xrange      - x range; default to the number > minnum area
   dxbin       - size of boxes in x-dir; default to a function of
                 first and second moments 
   levels      - contour levels; default to a function of image range
   minnum      - minimum number of points in a sliding box to plot;
                 default 100
 KEYWORDS:
 BUGS:
 REVISION HISTORY:
   2003-01-08  written - Hogg

(See pro/plot/blanton_oned_meanplot.pro)


BLANTON_WEIGHTED_MEAN_SURFACE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   blanton_weighted_mean_surface
 PURPOSE:
   make an image of the weighted mean for a 2-d set of measurements
 CALLING SEQUENCE:
   images = weighted_mean_surface(x,y,weight,quantity,xbin,ybin,dx,dy)
 INPUTS:
   x,y       - [N] values of measurements
   quantity  - [N] measurements themselves
   weight    - [N] weights for measurements
   xbin,ybin - [nx],[ny] vectors of coordinates of image pixel centers
   dx,dy     - size of sliding box in which means are taken
 OPTIONAL INPUTS:
   boot_seed - if set, use as seed for a bootstrap resampling trial
 OUTPUTS:
   images    - [nx,ny,4] output images of number of contributing
               points (image 0), total weight used (image 1), total
               square weight used (image 2), and weighted mean (image 3)
 COMMENTS:
 BUGS:
 REVISION HISTORY:
   2003-01-11  written - Hogg

(See pro/plot/blanton_weighted_mean_line.pro)


BSPLINE_ACTION

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

 PURPOSE:
      1) Construct banded bspline matrix, with dimensions [ndata, bandwidth]

 CALLING SEQUENCE:
   
   action = bspline_action( x, sset, x2=x2, lower=lower, upper=upper)

 INPUTS:
   x          - independent variable
   sset       - Structure to be returned with all fit parameters

 RETURNS:
   action     - b-spline action matrix

 OPTIONAL KEYWORDS:
   x2         - Orthogonal dependent variable for 2d fits

 OPTIONAL OUTPUTS:
   lower      - A list of pixel positions, each corresponding to the first
                occurence of position greater than breakpoint indx
   upper      - Same as lower, but denotes the upper pixel positions

 COMMENTS:
   Does not yet support the slatec function to directly return
   derivatives of the b-spline (ideriv). 

 EXAMPLES:

 PROCEDURES CALLED:

 REVISION HISTORY:
   11-Sep-2000 Written by Scott Burles, FNAL
    3-Jul-2001 Fundamental array organization bug fixed, S. Burles 

(See pro/bspline/bspline_action.pro)


BSPLINE_BKPTS

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

 PURPOSE:
   Choose bkpts for b-spline given different constraints

 CALLING SEQUENCE:
   
   fullbkpt = bspline_bkpts(x, nord=, bkpt=, $
    bkspace=, nbkpts=, everyn=, /silent)

 INPUTS:
   bkpt       - Breakpoint vector returned by efc
   nord       - Order for spline fit

 RETURNS:
   fullbkpt   - The fullbkpt vector required by evaluations with bvalu

 OPTIONAL KEYWORDS:
   bkspace    - Spacing of breakpoints in units of x
   everyn     - Spacing of breakpoints in good pixels
   nbkpts     - Number of breakpoints to span x range
                 minimum is 2 (the endpoints)
   silent     - Do not produce non-critical messages

 OPTIONAL OUTPUTS:
   bkpt       - breakpoints without padding

 COMMENTS:
   If both bkspace and nbkpts are passed, bkspace is used.

 EXAMPLES:

 PROCEDURES CALLED:
   none

 REVISION HISTORY:
   10-Mar-2000  Written by Scott Burles, FNAL

(See pro/bspline/bspline_bkpts.pro)


BSPLINE_FIT

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

 PURPOSE:
   Calculate a B-spline in the least-squares sense 
     based on two variables: x which is sorted and spans a large range
				  where bkpts are required
  		and 	      y which can be described with a low order
				  polynomial	

 CALLING SEQUENCE:
   error_code = bspline_fit(x, y, invvar, sset, $
    fullbkpt=, nord=, x2=, npoly=, yfit=)

 INPUTS:
   x          - Independent variable
   y          - Dependent variable
   invvar     - Inverse variance of Y
   sset       - Structure to be returned with all fit parameters
                (if not set, then it is created)

 OPTIONAL KEYWORDS:
   fullbkpt   - Pass fullbkpt to seed structure; if not set, then
                this is generated with CREATE_BSPLINESET()
   nord       - Order of b-splines; default to 4 (cubic)
   x2         - Orthogonal dependent variable
   npoly      - Order of x2 polynomial fit; default to the value in the
                SSET structure, or to 1.

 OUTPUTS:
   error_code - Non-negative numbers indicate ill-conditioned bkpts
                 0 is good
                -1 is dropped breakpoints, try again
                -2 is failure, should abort
   sset       - Structure with all fit parameters

 OPTIONAL OUTPUTS:
   yfit       - Evaluation of b-spline at X (and X2)

 COMMENTS:
   This code replaces efcmn and efc2d calls in the slatec library.

 BUGS:
   Do we need to sort X for this routine???

 EXAMPLES:

 PROCEDURES CALLED:
   bspline_action()
   bspline_maskpoints()
   bspline_valu()
   cholesky_band()
   cholesky_solve()
   create_bsplineset()

 REVISION HISTORY:
   20-Aug-2000 Written by Scott Burles, FNAL

(See pro/bspline/bspline_fit.pro)


BSPLINE_ITERFIT

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

 PURPOSE:
   Calculate a B-spline in the least squares sense with rejection

 CALLING SEQUENCE:
   sset = bspline_iterfit( )

 INPUTS:
   xdata      - Data x values
   ydata      - Data y values

 OPTIONAL KEYWORDS:
   invvar     - Inverse variance of y; if not set, then set to be
                consistent with the standard deviation.  This only matters
                if rejection is being done.
   nord       - Order for spline fit; default to 4.
   x2         - 2nd dependent variable for 2-D spline fitting.
   npoly      - Polynomial order to fit over 2nd variable (X2); default to 2.
   xmin       - Normalization minimum for X2; default to MIN(XDATA).
   xmax       - Normalization maximum for X2; default to MAX(XDATA).
   oldset     - If set, then use values of FULLBKPT, NORD, XMIN, XMAX, NPOLY
                from this structure.
   funcname   - If OLDSET is not specified and this is a 2-D B-spline,
                then the function for the second variable may be passed.
                The default is 'legendre' in the call to CREATE_BSPLINESET().
   maxiter    - Maximum number of rejection iterations; default to 10;
                set to 0 to disable rejection.
   upper      - Upper rejection threshhold; default to 5 sigma.
   lower      - Lower rejection threshhold; default to 5 sigma.
   requiren   - force at at least (requiren) data points between each set of bkpts.
   _EXTRA     - Keywords for BSPLINE_BKPTS(), BSPLINE_FIT and/or DJS_REJECT().

 OUTPUTS:
   sset       - Structure describing spline fit.
                Return 0 if too few good (INVVAR NE 0) points are passed.

 OPTIONAL OUTPUTS:
   outmask    - Output mask, set =1 for good points, =0 for bad points.
   fullbkpt   - If OLDSET is not specified, then the break points are
                chosen with a call to BSPLINE_BKPTS() which can be returned
                with this keyword.
   yfit       - B-spline fit evaluated at each data point.

 COMMENTS:
   Data points can be masked either by setting their weights to zero
   (INVVAR[]=0), or by using INMASK and setting bad elements to zero.
   INMASK is passed to DJS_REJECT().

   If OLDSET is used, then the output structure SSET will be a structure
   with the same name as OLDSET.  This will allow the two structures to
   be concatented, i.e.
     > junk = [oldset, sset]

   Although I'm not sure how to treat data points which fall outside
   minmax(bkpt), now I will set them equal to minmax with invvar = 0

 EXAMPLES:
   Construct a random function, and fit a B-spline to it without
   any rejection:
     IDL> x = findgen(1000)
     IDL> y = smooth(randomu(1234,1000),10)
     IDL> sset = bspline_iterfit(x,y,nord=3,maxiter=0,bkspace=10)
     IDL> yfit = bspline_valu(x,sset)

 PROCEDURES CALLED:
   bspline_bkpts()
   bspline_fit()
   create_bsplineset()
   djs_reject()

 REVISION HISTORY:
   05-Sep-2000  Written by D. Schlegel & S. Burles

(See pro/bspline/bspline_iterfit.pro)


BSPLINE_MASKPOINTS

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

 PURPOSE:
   Perform simple logic of which breakpoints to mask

 CALLING SEQUENCE:
   error_code = bspline_maskpoints(sset, errb, npoly)
   
 INPUTS:
   sset      - Bspline structure
   errb      - Errors returned from cholesky routines
   npoly     - Polynomial norder of 2d fit (default 1)

 RETURNS:
   error_code =  -1:   Breakpoints have been dropped, try again
                 -2:   Solution not possible, abort

 OUTPUTS:

 OPTIONAL KEYWORDS:

 OPTIONAL OUTPUTS:

 COMMENTS:

 EXAMPLES:

 PROCEDURES CALLED:

 REVISION HISTORY:
   12-Oct-2000 Written by Scott Burles, FNAL

(See pro/bspline/bspline_maskpoints.pro)


BSPLINE_RADIAL[1]

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

 PURPOSE:
   Calculate the action matrix for a Radial B-spline with PSF convolution

 CALLING SEQUENCE:
   sset = bspline_psf_action( )

 INPUTS:
   r          - independent radial coordinate
   theta      - independent angular coordinate (in radians)
   data       - Data values

 OPTIONAL KEYWORDS:
   invvar     - Inverse variance of data; if not set, then all data points
                 have weight of 1.0
   ntheta     - Vector of multipole identifiers
                 Each entry will correspond to an independent angular mode
                 Negative elements represent sin(abs(ntheta)*theta)
                 Positive elements represent cos(ntheta*theta)
                 Default is [0,-2,2]
   rbkpt      - This is analogous to bkpt keyword in bspline_iterfit
                This sets the breakpoint positions in the radial dimension
                 and does not include the boundary breakpoints.
                One can choose to use bkspace or everyn to also set rbkpt.
   _EXTRA     - Keywords for BSPLINE_BKPTS() and/or DJS_REJECT().

 OUTPUTS:
   sset       - Structure describing spline fit.
                Return 0 if too few good (INVVAR NE 0) points are passed.

 OPTIONAL OUTPUTS:
   outmask    - Output mask, set =1 for good points, =0 for bad points.
   yfit       - B-spline fit evaluated at each data point.

 COMMENTS:

   The calling is analogous to bspline_iterfit, so hopefully you're
   familiar with the 1d bsplines.  This fits a function in polar coordinates,
   and r, theta, and data must be supplied.  The number of free parameters
   is given by (Nbkpt + Nord - 1) * N_multipole.
     Nbkpt       = n_elements(bkpt)
     Nord        = the order of the bspline (default is 4)
     N_multipole = n_elements(ntheta)  

   See Bolton et al. 2005 for an official description of radial bsplines

 EXAMPLES:

 PROCEDURES CALLED:
   bspline_bkpts()
   bspline_workit()
   bspline_action()
   create_bsplineset()
   djs_reject()

 REVISION HISTORY:
   16-Aug-2005  Written by S. Burles & A. Bolton, MIT

(See pro/bspline/bspline_psf_action.pro)


BSPLINE_RADIAL[2]

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

 PURPOSE:
   Calculate a Radial B-spline in the least squares sense with rejection

 CALLING SEQUENCE:
   sset = bspline_radial( )

 INPUTS:
   r          - independent radial coordinate
   theta      - independent angular coordinate (in radians)
   data       - Data values

 OPTIONAL KEYWORDS:
   invvar     - Inverse variance of data; if not set, then all data points
                 have weight of 1.0
   ntheta     - Vector of multipole identifiers
                 Each entry will correspond to an independent angular mode
                 Negative elements represent sin(abs(ntheta)*theta)
                 Positive elements represent cos(ntheta*theta)
                 Default is [0,-2,2]
   rbkpt      - This is analogous to bkpt keyword in bspline_iterfit
                This sets the breakpoint positions in the radial dimension
                 and does not include the boundary breakpoints.
                One can choose to use bkspace or everyn to also set rbkpt.
   _EXTRA     - Keywords for BSPLINE_BKPTS() and/or DJS_REJECT().

 OUTPUTS:
   sset       - Structure describing spline fit.
                Return 0 if too few good (INVVAR NE 0) points are passed.

 OPTIONAL OUTPUTS:
   outmask    - Output mask, set =1 for good points, =0 for bad points.
   yfit       - B-spline fit evaluated at each data point.

 COMMENTS:

   The calling is analogous to bspline_iterfit, so hopefully you're
   familiar with the 1d bsplines.  This fits a function in polar coordinates,
   and r, theta, and data must be supplied.  The number of free parameters
   is given by (Nbkpt + Nord - 1) * N_multipole.
     Nbkpt       = n_elements(bkpt)
     Nord        = the order of the bspline (default is 4)
     N_multipole = n_elements(ntheta)  

   See Bolton et al. 2005 for an official description of radial bsplines

 EXAMPLES:

 PROCEDURES CALLED:
   bspline_bkpts()
   bspline_workit()
   bspline_action()
   create_bsplineset()
   djs_reject()

 REVISION HISTORY:
   22-Feb-2005  Written by S. Burles & A. Bolton, MIT

(See pro/bspline/bspline_radial.pro)


BSPLINE_RADIAL_VALU

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

 PURPOSE:
      1) Evaluate a radial bspline set (see bspline_radial) at the 2-d
        positions specified by the r and theta arrays

 CALLING SEQUENCE:
   
   radial_fit  = bspline_radial_valu( r, theta, sset, [mode = ] )

 INPUTS:
   x          - independent variable
   sset       - Structure to be returned with all fit parameters

 RETURNS:
   radial_fit - Evaluated b-spline fit

 OPTIONAL KEYWORDS:
   mode       - return just a single mode of the bspline fit, 
                must be GE 0 and LT n_elements(sset.ntheta)
                Default is to return the sum of all modes

 OPTIONAL OUTPUTS:
 
 COMMENTS:

 EXAMPLES:

 PROCEDURES CALLED:

 REVISION HISTORY:
   22-Feb-2005 Written by Scott Burles & Adam Bolton, MIT 

(See pro/bspline/bspline_radial_valu.pro)


BSPLINE_VALU

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

 PURPOSE:
      1) Evaluate a bspline set (see create_bsplineset) at specified
            x and x2 arrays

 CALLING SEQUENCE:
   
   yfit  = bspline_valu( x, sset, x2=x2, action=action, upper=upper, 
               lower=lower, mask=mask)

 INPUTS:
   x          - independent variable
   sset       - Structure to be returned with all fit parameters

 RETURNS:
   yfit       - Evaluated b-spline fit

 OPTIONAL KEYWORDS:
   x2         - Orthogonal dependent variable for 2d fits
   action     - This keyword is overwritten with b-spline action matrix
   lower,upper- Internal keywords used by action, maybe should replace
                action with a structure including lower and upper

 OPTIONAL OUTPUTS:
   mask       - a mask array of good (1's) bspline evalutions
 
 COMMENTS:
   the mask attempts to show regions where the bspline was ill-defined
    and breakpoints had been dropped.

 EXAMPLES:

 PROCEDURES CALLED:

 REVISION HISTORY:
   11-Sep-2000 Written by Scott Burles, FNAL

(See pro/bspline/bspline_valu.pro)


BVALU2D

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

 PURPOSE:
   Evaluate a bspline fit over 2 dependent variables

 CALLING SEQUENCE:
   
    z = bvalu2d(x, y, bkpt, coeff, ideriv=ideriv)

 INPUTS:
   x          - vector of x positions to evaluate
   y          - vector of y positions to evaluate
   bkpt       - Breakpoint vector returned by efc
   coeff      - B-spline coefficients calculated by efc 
		   2d in this case [npoly, nbkpt-nord]

 OPTIONAL KEYWORDS:

   ideriv     - Derivative to evaluate at x (default 0)

 OUTPUTS:
   z          - Evaluations corresponding to x positions

 OPTIONAL OUTPUTS:

 COMMENTS:

 EXAMPLES:


 PROCEDURES CALLED:
   slatec_bvalu


 REVISION HISTORY:
   13-Mar-2000  Written by Scott Burles, FNAL

(See pro/slatec/bvalu2d.pro)


CAP_DISTANCE

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

 PURPOSE:
   Return distance from coordinates to a cap, in degrees.

 CALLING SEQUENCE:
   cap_distance

 INPUTS:

 OPTIONAL INPUTS:

 OUTPUT:

 OPTIONAL OUTPUTS:

 COMMENTS:
   The sign is positive if in the cap, and negative if outside

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:
   angles_to_x()

 REVISION HISTORY:
   19-Jun-2003  Written by David Schlegel, Princeton.

(See pro/mangle/cap_distance.pro)


CATFITS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	catfits
 PURPOSE:
       Read and concatenate a bunch of binary FITS tables

 CALLING SEQUENCE:
	struc = catfits(flist)

 INPUTS:
       filst  - string array of FITS filenames to read and concatenate
		for each column of data to be read.  Allowed letters are 
 OUTPUTS:
	struc  - IDL structure

 REVISION HISTORY:
	Written  2001-Nov-28 D. Finkbeiner

(See pro/misc/catfits.pro)


CCM_FITRV.PRO

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   ccm_fitrv.pro

 PURPOSE:
   Does a simple fit to R_V and normalization

 CALLING SEQUENCE:
   R_V = ccm_fitrv(wave, redfac, [weight=, norm=norm, chi2=chi2])

 INPUTS:
   wave   : Wavelength [Ang] at which A is measured
   redfac : Measured A
   weight : Weight coefficients (by band)

 OUTPUTS:
   R_V    : Measured R_V

 OPTIONAL OUTPUTS:
   norm   : The measured normalization
   chi2   : Returned chi2 (unit weights assumed if none passed)
   
 COMMENTS:
    The chi2 is measured by func_ccm_fitrv.pro. See that function
    for weights etc.
    The reddening curve is computed by ccm_unred.pro
   
 REVISION HISTORY:
   2003-Sep-10  Written by D. Finkbeiner & N.Padmanabhan, Princeton

(See pro/dust/ccm_fitrv.pro)


CIRCLE_CAP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   circle_cap
 PURPOSE:
   Return a circular cap centered on a certain set of coordinates.
 CALLING SEQUENCE:
   cap=circle_cap(radius, [ra=, dec=, xyz= ])
 INPUTS:
   radius - proper radius of cap, in degrees
   ra, dec - coordinates of center
    OR
   xyz - xyz value of center (should be unit vector)
 COMMENTS:
   Use for the cap of a mangle polygon defining a circle.
   ra,dec inputs will override xyz inputs
 REVISION HISTORY:
   01-Oct-2002  Written by MRB (NYU)

(See pro/mangle/circle_cap.pro)


CMPS_FORM

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

 PURPOSE:
   This function puts up a form the user can configure a PostScript
   device driver. The function result (if the user selects either the
   ACCEPT or CREATE FILE buttons) can be sent directly to the DEVICE
   procedure by means of its _Extra keyword.  User's predefined
   configurations may be retrieved from a common block.

 AUTHOR:
   *********** CM 01 Feb 2000 VERSION *************
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov

   Based almost entirely on, but a totally revamped version of, CMPS_FORM by 
   FANNING SOFTWARE CONSULTING (David Fanning Ph.D.) http://www.dfanning.com

 MAJOR TOPICS:
   Device Drivers, Hardcopy Output, PostScript Output

 PROCEDURE:
   This is a pop-up form widget. It is a modal or blocking widget.
   Keywords appropriate for the PostScript DEVICE command are returned.

   Use your LEFT mouse button to move the "Plot Window" around the page.
   Use your RIGHT mouse button to draw your own "Plot Window" on the page.

 HELP:
   formInfo = CMPS_FORM(/Help)

 CALLING SEQUENCE:
    formInfo = CMPS_FORM(xoffset, yoffset, Cancel=cancelButton)

 OPTIONAL INPUTS:

    XOFFSET -- Optional xoffset of the top-level base of cmps_form. Default is
    to try to center the form on the display.

    YOFFSET -- Optional yoffset of the top-level base of cmps_form. Default is
    to try to center the form on the display.

 INPUT KEYWORD PARAMETERS:

    BITS_PER_PIXEL -- The initial configuration of the bits per pixel button.

    BLOCKING -- Set this keyword to make this a blocking widget under IDL 5.0.
    (All widget programs block under IDL 4.0.)

    COLOR -- The initial configuration of the color switch.

    DEFAULTS -- A stucture variable of the same type and structure as the
    RETURN VALUE of cmps_form. It will set initial conditions. This makes
    it possible to start cmps_form up again with the same values it had the
    last time it was called. For example:

       mysetup = cmps_form()
       newsetup = cmps_form(Defaults=mysetup)

    ENCAPSULATED -- The initial configuration of the encapsulated switch.

    FILENAME -- The initial filename to be used on the form.

    HELP -- Prints a helpful message in the output log.

    INCHES -- The initial configuration of the inches/cm switch.

    INITIALIZE -- If this keyword is set, the program immediately returns the
    "localdefaults" structure. This gives you the means to configue the
    PostScript device without interrupting the user.

    SELECT -- used only when INITIALIZE is set.  Set SELECT to a
              string which identifies the predefined configuration to
              be returned by cmps_form when INITIALIZE is set.  This is
              a convenient way to select a predefined config
              non-interactively.

    LANDSCAPE -- The initial configuration of the landscape/portrait switch.

    LOCALDEFAULTS -- A structure like the DEFAULTS structure. If specified,
    then it is added as a predefined configuration entry called "Local".
    See below for a further discussion of predefined configurations.

    PREDEFINED -- An alternate way to specify predefined
                  configurations.  Pass an array of structures to
                  populate the "predefined" dropbox in the
                  dialog. This array, if specified, overrides the the
                  common block technique.

    XOFFSET -- The initial XOffSet of the PostScript window.

    YOFFSET -- The initial YOffSet of the PostScript window.

    XSIZE -- The initial XSize of the PostScript window.

    YSIZE -- The initial YSize of the PostScript window.

    ASPECT -- The aspect ratio of the window (Y/X).  This keyword can
              substitute for one of XSIZE or YSIZE.
 
    PRESERVE_ASPECT -- Set this keyword if you want to hold the
                       aspect ratio constant.

    PAPERSIZE -- If set, allows user to specify the size of the paper
                 media to be printed on, as a scalar string.  NOTE:
                 this specification cannot be passed to DEVICE, but
                 can be selected for completeness's sake.  Default is
                 'Letter'.

    MARGINSIZE -- Size of the margins on all sides.  Default is 0.25 inches.
                  When MARGINSIZE is non-zero, a graphic cannot directly
                  abut the edge of the page.  This is normally a good thing,
                  since there is often a  non-printable region which borders
                  the page.

   DEFAULTPAPER -- Default paper size to use, when it is unspecified
                   in a predefined, "local", or "default"
                   configuration.  This value also overrides any
                   configuration from common blocks.  European users
                   will probably set this to 'A4'.

   PARENT -- if this widget is invoked by another widget program,
             then this keyword parameter must be set to the top level
             widget which is to serve as the group leader.  Failure
             to do so will result in unexpected behavior.  IDL 4
             programs do not need to pass this parameter.  Default:
             NONE.

 OUTPUT KEYWORD PARAMETERS

    CANCEL -- This is an OUTPUT keyword. It is used to check if the user
    selected the "Cancel" button on the form. Check this variable rather
    than the return value of the function, since the return value is designed
    to be sent directly to the DEVICE procedure. The varible is set to 1 if
    the user selected the "Cancel" button. Otherwise, it is set to 0.

    CREATE -- This output keyword can be used to determine if the user
    selected the 'Create File' button rather than the 'Accept' button.
    The value is 1 if selected, and 0 otherwise.

    PAPERSIZE -- If set to a named variable, any newly selected paper
    size is returned in that variable.

    XPAGESIZE -- Size of paper in "X" dimension, in units given by
                 the returned config structure.

    YPAGESIZE -- Size of paper in "Y" dimension, in units given by
                 the returned config structure.

    PAGEBOX -- specifies the page rectangle relative to the plot
               window, in normalized units.  A 4-vector of the form
               [XLL, YLL, XUR, YUR] is returned, giving the positions
               of the lower left (LL) and upper right (UR) corners of
               the page with respect to the plot window.  Thus, the
               following command:

                    PLOT, x, y, position=PAGEBOX

               will construct a graphic whose plot region exactly
               fills the page (with no margin around the edges).

               Naturally, the page is usually larger than the
               graphics window, so the normalized coordinates will
               usually fall outside the range [0,1].

               However, the bounding box constructed by the
               Postscript driver includes only the graphics window.
               Anything drawn outside of it may be clipped or
               discarded.

 RETURN VALUE:

     formInfo = { cmps_form_INFO, $
                  xsize:0.0, $        ; The x size of the plot
                  xoff:0.0, $         ; The x offset of the plot
                  ysize:0.0, $        ; The y size of the plot
                  yoff:0.0 $          ; The y offset of the plot
                  filename:'', $      ; The name of the output file
                  inches:0 $          ; Inches or centimeters?
                  color:0, $          ; Color on or off?
                  bits_per_pixel:0, $ ; How many bits per image pixel?
                  encapsulated:0,$    ; Encapsulated or regular PostScript?
                  isolatin1:0,$       ; Encoded with ISOLATIN1?
                  landscape:0 }       ; Landscape or portrait mode?

 USAGE:

  The calling procedure for this function in a widget program will
  look something like this:

     info.ps_config = cmps_form(/Initialize)

     formInfo = cmps_form(Cancel=canceled, Create=create, $
                          Defaults=info.ps_config)

     IF NOT canceled THEN BEGIN
        IF create THEN BEGIN
           thisDevice = !D.Name
           Set_Plot, "PS"
           Device, _Extra=formInfo

           Enter Your Graphics Commands Here!

           Device, /Close
           Set_Plot, thisDevice
           info.ps_config = formInfo
        ENDIF ELSE
           info.ps_config = formInfo
     ENDIF

 MAJOR FUNCTIONS and PROCEDURES:

   None. Designed to work originally in conjunction with XWindow, a
   resizable graphics window.  [ NOTE: this modified version of
   cmps_form, by Craig Markwardt, is incompatible with the original
   version of XWINDOW. ]

 MODIFICATION HISTORY:

   Based on cmps_form of : David Fanning, RSI, March 1995.
   Major rewrite by: Craig Markwardt, October 1997.
     - Drawing and updating of form and sample box are now modular
     - Option of storing more than one predefined postscript configuration
     - Selection of paper size by name
     - Access to predfined configurations through (optional) common
       block
   Several additions, CM, April 1998  VERSION CM2.0
     - better integration of paper sizes throughout program.
       Predefined configurations now also know about paper.
     - allow passing predefined configurations instead of using
       common block
     - addition of ISOLATIN selection, and streamlining of dialog
       appearance
   Fixed bug in INITIALIZE w.r.t. paper sizes, CM, Nov 1998
   Added SELECT keyword, CM, 09 Dec 1998
   Added Parent keyword to allow modal widgets in IDL 5, 19 Jan 1999
   Added "Choose" button for filename selection, 19 Sep 1999
   Added ability to program different button names, 19 Sep 1999
   Added ASPECT and PRESERVE_ASPECT, based on work by Aaron Barth, 18
     Oct 1999
   Removed NOCOMMON documentation and logic, 19 Oct 1999, CM
   Added aspect to cmps_form_numevents (per Aaron Barth), 18 Oct 1999
   Corrected small bug under Initialize keyword (inches), 18 Oct 1999
   Made call to *_pscoord more consistent, 18 Oct 1999
   Added XPAGESIZE, YPAGESIZE and PAGEBOX keywords, 19 Oct 1999
   Small cosmetic cleanup, CM, 01 Feb 2000

 COMMON BLOCKS:
 
   The user may store frequently used or helpful configurations in a 
   common block, and cmps_form() will attempt to access them.  This
   provides a way for the user to have persistent, named,
   configurations.

   NOTE: this format has changed since the last version.  You may
   have to quit your IDL session for the changes to take effect
   properly.  If you have place a predefined configuration in your
   startup file, you should review the new format.
   
     COMMON CMPS_FORM_CONFIGS, cmps_form_DEFAULT_PAPERSIZE, $
                               cmps_form_STDCONFIGS

        cmps_form_DEFAULT_PAPERSIZE - a string designating the default
                                    paper size, when none is given.
                                    The predefined configurations
                                    offerred by this program will
                                    respect the default value.  (See
                                    also the DEFAULTPAPER keyword.)

        cmps_form_STDCONFIGS - An array of cmps_form_CONFIG structures,
                             each containing information about one
                             predefined configuration, such as its
                             name and size of paper.  Each "config"
                             element is a cmps_form_INFO structure,
                             which contains the actual postscript
                             configuration.

   See the IDL source code cmps_form_LOAD_CONFIGS for an example of how
   to make a list of configurations.  One possibility would be to
   declare and populate the common block from within the user's
   start-up script, allowing the same configurations to appear in
   every session.

   cmps_form() takes its initial list of configurations from this
   common block if it exists.  A default list is provided ala the
   procedure cmps_form_LOAD_CONFIGS.  Any modifications that take place
   during the cmps_form() widget session are not transferred back to
   the common block upon return.  It might be useful to be able to do
   this, through some form of 'save' procedure.

   Also, if the PREDEFINED keyword is used, then the common block is
   not consulted.

(See pro/plot/cmps_form.pro)


CMP_FITS_FILES

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

 PURPOSE:
   Compare the contents of two FITS files.

 CALLING SEQUENCE:
   cmp_fits_files, filename1, filename2, [ /verbose ]

 INPUTS:
   filename1 - First FITS file
   filename2 - Second FITS file

 OPTIONAL INPUTS:
   verbose   - If set, then report extensions that are the same, as
               well as reporting any differences

 OUTPUTS:

 OPTIONAL OUTPUTS:

 COMMENTS:
   All HDUs are compared, both images and structures.
   Report a warning if the variable type is different, for example if
     one file contains a structure and the other an image, or if one
     contains an integer image and the other a floating-point image.
   For images, report a warning if the number of array elements disagree,
     or if any values disagree.
   For structures, report a warning if the number of structure tags disagree,
     or if any values disagree.

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:
   mrdfits()
   splog

 REVISION HISTORY:
   06-Nov-2003  Written by David Schlegel, Princeton.

(See pro/fits/cmp_fits_files.pro)


COMDIS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   comdis
 PURPOSE:
   Compute comoving line-of-sight distances (for c/H_0=1).
 CALLING SEQUENCE:
   D= comdis(z,OmegaM,OmegaL, weq=weq)
 INPUTS:
   z       - redshift or vector of redshifts
   OmegaM  - Omega-matter at z=0
   OmegaL  - Omega-Lambda at z=0
 OPTIONAL INPUTS:
   weq     - Equation of state (default=-1)
 KEYWORDS
 OUTPUTS:
   comoving line-of-sight distance in units of the Hubble length c/H_0
 COMMENTS:
 BUGS:
   The integrator is crude, slow and repetetive.
   May not work for pathological parts of the OmegaM-OmegaL plane.
 EXAMPLES:
 PROCEDURES CALLED:
   dcomdisdz()
 REVISION HISTORY:
   25-Jun-2000  Written by Hogg (IAS)
   2004-Sep-06  Added support for different equations of state,
         Padmanabhan (Princeton) 

(See pro/cosmography/comdis.pro)


COMDIS2

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   comdis2
 PURPOSE:
   Compute comoving line-of-sight distances (for c/H_0=1).
 CALLING SEQUENCE:
   D= comdis2(z,OmegaM,OmegaL,cdtable=cdtable,zmaxtable=zmaxtable)
 INPUTS:
   z       - redshift or vector of redshifts
   OmegaM  - Omega-matter at z=0
   OmegaL  - Omega-Lambda at z=0
 OPTIONAL INPUTS:
   cdtable - returns the lookup table calculated, so you can reuse
   zmaxtable - set max z value of lookup table
 KEYWORDS
 OUTPUTS:
   comoving line-of-sight distance in units of the Hubble length c/H_0
 COMMENTS:
   Call as: 
      dC = comdis2(z,OmegaM,OmegaL,cdtable=cdtable)
   if you call it multiple times, so it does not remake the the
   lookup table.
 BUGS:
   The integrator is crude, slow and repetitive.
   May not work for pathological parts of the OmegaM-OmegaL plane.
   Relies on interpolate() working
 EXAMPLES:
 PROCEDURES CALLED:
   dcomdisdz()
 REVISION HISTORY:
   2000-Jun-25  Written by Hogg (IAS)
   2002-Feb-20  Look-up table to increase speed; Blanton (NYU)

(See pro/cosmography/comdis2.pro)


CONSTRUCT_CAP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   construct_cap
 PURPOSE:
   Create the structure for a cap
 CALLING SEQUENCE:
   poly=construct_cap()
 INPUTS:
 OPTIONAL INPUTS:
 OUTPUTS:
 OPTIONAL INPUT/OUTPUTS:
 COMMENTS:
 EXAMPLES:
 BUGS:
 PROCEDURES CALLED:
 REVISION HISTORY:
   01-Oct-2002  Written by MRB (NYU)

(See pro/mangle/construct_cap.pro)


CONSTRUCT_POLYGON

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   construct_polygon
 PURPOSE:
   Create the structure for a polygon. 
   This has the number of caps stored, a bitmask indicating whether 
   to use each cap, the weight, and the area
 CALLING SEQUENCE:
   poly=construct_polygon()
 INPUTS:
 OPTIONAL INPUTS:
 OUTPUTS:
 OPTIONAL INPUT/OUTPUTS:
 COMMENTS:
 EXAMPLES:
 BUGS:
   Number of caps limited to 32
 PROCEDURES CALLED:
 REVISION HISTORY:
   01-Oct-2002  Written by MRB (NYU)

(See pro/mangle/construct_polygon.pro)


CONSTRUCT_VERTEX

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   construct_vertex
 PURPOSE:
   Create the structure for a vertex. 
 CALLING SEQUENCE:
   vertex=construct_vertex([maxnvertices= ])
 INPUTS:
 OPTIONAL INPUTS:
   maxnvertices - the maximum number of vertices allowed for any vertex
 OUTPUTS:
 OPTIONAL INPUT/OUTPUTS:
 COMMENTS:
 EXAMPLES:
 BUGS:
   Number of caps limited to 32
 PROCEDURES CALLED:
 REVISION HISTORY:
   01-Oct-2002  Written by MRB (NYU)

(See pro/mangle/construct_vertex.pro)


COPY_CAPS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   copy_caps
 PURPOSE:
   copy information about caps from one polygon to another
 CALLING SEQUENCE:
   copy_caps, poly1, poly2
 INPUTS:
 OPTIONAL INPUTS:
 OUTPUTS:
 OPTIONAL INPUT/OUTPUTS:
 COMMENTS:
   blows away old pointers
 EXAMPLES:
 BUGS:
   Number of caps limited to 32
 PROCEDURES CALLED:
 REVISION HISTORY:
   01-Oct-2002  Written by MRB (NYU)

(See pro/mangle/copy_caps.pro)


COUNT_FREELUN

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

 PURPOSE:
   Count the number of logical file pointers (LUNs) that are available

 CALLING SEQUENCE:
   num = count_freelun()

 INPUTS:

 OPTIONAL INPUTS:

 OUTPUTS:
   num        - Number of logical file pointers (LUNs) that can be allocated
                with GET_LUN before triggering an error

 OPTIONAL OUTPUTS:

 COMMENTS:

 EXAMPLES:

 BUGS:

 DATA FILES:

 PROCEDURES CALLED:

 REVISION HISTORY:
   02-Mar-2004  Written by D. Schlegel, Princeton

(See pro/misc/count_freelun.pro)


CPBACKUP

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

 PURPOSE:
   Copy a file to a backup file name.

 CALLING SEQUENCE:
   cpbackup, filename

 INPUTS:
   filename   - File to copy if it exists.

 OUTPUTS:

 COMMENTS:
   Make a backup copy of the specified file by appending ".1", ".2", etc.
   The first unused number is used as an appendix.

 EXAMPLES:

 BUGS:
   This is only written to work with a Unix file system, since it spawns
   the Unix "cp" command.

 PROCEDURES CALLED:

 REVISION HISTORY:
   11-Mar-2000  Written by D. Schlegel, Princeton

(See pro/misc/cpbackup.pro)


CROSSPROD

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

 PURPOSE:
   compute cross product of two vectors or arrays of vectors

 CALLING SEQUENCE:
   C=crossprod(A,B)

 INPUTS:
   A, B  - either [3] or [Nvec,3]

 OUTPUT:
   C     - either [3] or [Nvec,3]

 COMMENTS:
   If A and B are BOTH row vectors, return a row vector.  
    Otherwise, return [Nvec,3]

 REVISION HISTORY:
   2003-May-13  Written by Finkbeiner & Schlegel, Princeton

(See pro/coord/crossprod.pro)


CURRENT_MJD

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   current_mjd
 PURPOSE:
   Transform systime() to current MJD.
 CALLING SEQUENCE:
   mjd= current_mjd()
 INPUTS:
 OPTIONAL KEYWORDS:
 OUTPUTS:
 OPTIONAL OUTPUTS:
 COMMENTS:
   Your clock better be right when you ask for UT!
 EXAMPLES:
 BUGS:
   Relies on IDL 5.4 feature /utc for systime().
 PROCEDURES CALLED:
 REVISION HISTORY:
   2001-Feb-07  written by Hogg, NYU

(See pro/coord/current_mjd.pro)


DCOMDISDZ

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   dcomdisdz
 PURPOSE:
   Compute differential comoving line-of-sight distances (for c/H_0=1).
 CALLING SEQUENCE:
   dDdz= dcomdisdz(z,OmegaM,OmegaL, weq=weq)
 INPUTS:
   z       - redshift or vector of redshifts
   OmegaM  - Omega-matter at z=0
   OmegaL  - Omega-Lambda at z=0
 OPTIONAL INPUTS:
   weq     - Eq. of state (Default =-1)
 KEYWORDS
 OUTPUTS:
   differential comoving distance DD/dz in units of the Hubble length c/H_0
 COMMENTS:
 BUGS:
   May not work for pathological parts of the OmegaM-OmegaL plane.
 EXAMPLES:
 PROCEDURES CALLED:
 REVISION HISTORY:
   25-Jun-2000  Written by Hogg (IAS)
   2004-Sep-06  Added support for different equations of state,
         Padmanabhan (Princeton)

(See pro/cosmography/dcomdisdz.pro)


DCOMVOLDZ

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   dcomvoldz
 PURPOSE:
   Compute differential comoving volume element dV_c/dz per unit solid angle.
 CALLING SEQUENCE:
   dVdz= dcomvoldz(z,OmegaM,OmegaL)
 INPUTS:
   z       - redshift or vector of redshifts
   OmegaM  - Omega-matter at z=0
   OmegaL  - Omega-Lambda at z=0
 OPTIONAL INPUTS:
 KEYWORDS
 OUTPUTS:
   Comoving volume per steradian in units of the Hubble volume (c/H_0)^3
 COMMENTS:
   Formulae from Carrol, Press & Turner, 1992, Kolb & Turner, 1990, and my
   own calculation.
 BUGS:
   May not work for pathological parts of the OmegaM-OmegaL plane.
 EXAMPLES:
 PROCEDURES CALLED:
   dpropmotdisdz
   propmotdis
 REVISION HISTORY:
   2001-Mar-12  Written by Hogg (NYU)

(See pro/cosmography/dcomvoldz.pro)


DEC2HMS

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

 PURPOSE:
   convert decimal number to HH:MM:SS (base sixty)

 CALLING SEQUENCE:
   result = dec2hms(angle_in, double=double)

 INPUTS:
   angle_in  - angle [hours for RA, degrees for declination]

 KEYWORDS:
   double    - double precision math

 OUTPUTS:
   result    - string containing HH:MM:SS or DD:MM:SS

 EXAMPLES:
   ra_string  = dec2hms(ra_degree/15)
   dec_string = dec2hms(dec_degree)

 COMMENTS:
   This function does not convert from hours to degrees!
   Pass type double, or suffer 0.003 arcsec error
   There is some tom-foolery to prevent roundoff problems
     (like 1 -> '00 59 60.0') but if you aren't using /double
     you have no right to expect high precision anyway. 

 REVISION HISTORY:
   Written by Douglas Finkbeiner in ancient times
   2000-Nov-29 - double keyword added            - DPF
   2005-Sep-16 - call self recursively for array - DPF

(See pro/coord/dec2hms.pro)


DESTRUCT_POLYGON

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   destruct_polygon
 PURPOSE:
   Destroy the structure for a polygon. 
 CALLING SEQUENCE:
   destruct_polygon, poly
 INPUTS:
   poly - polygon to destroy
 OPTIONAL INPUTS:
 OUTPUTS:
 OPTIONAL INPUT/OUTPUTS:
 COMMENTS:
 EXAMPLES:
 BUGS:
 PROCEDURES CALLED:
 REVISION HISTORY:
   01-Oct-2002  Written by MRB (NYU)

(See pro/mangle/destruct_polygon.pro)


DFPSCLOSE

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

 PURPOSE:
   Finkbeiner's routine to close a PostScript file previously opened
   with DFPSOPEN, and revert to sending plots to the X-display.

 CALLING SEQUENCE:
   dfpsclose

 INPUTS:

 OPTIONAL INPUTS:

 OUTPUTS:

 OPTIONAL OUTPUTS:

 COMMENTS:

 EXAMPLES:

 PROCEDURES CALLED:

 REVISION HISTORY:
   The-Beginning-of-Time  Written by Doug Finkbeiner, Berkeley.
   05-Sep-1999  Modified and commented by David Schlegel, Princeton.
   06-Aug-2001  Check if X device is set already - DPF, Princeton

(See pro/plot/dfpsclose.pro)


DFPSPLOT

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

 PURPOSE:
   Finkbeiner's routine to open a PostScript file for plotting commands.
   Close with DFPSCLOSE.

 CALLING SEQUENCE:
   dfpsplot, filename, [/square, /landscape, ysize=ysize, $
    /encap, /color, _EXTRA=KeywordsForDevice ]

 INPUTS:
   filename   - File name to open

 OPTIONAL INPUTS:
   square     - Make the plotting area square.
   landscape  - Use landscape paper; default is to use portrait.
   ysize      - For portrait mode, the YSIZE can be changed from its
                default of 8-inches.  For landscape mode, the value
                of YSIZE is ignored.
   encap      - Force non-encapsulated file unless this keyword is set.
   color      - Force non-color file unless this keyword is set.

 OUTPUT:

 OPTIONAL OUTPUTS:

 COMMENTS:

 EXAMPLES:

 PROCEDURES CALLED:

 REVISION HISTORY:
   The-Beginning-of-Time  Written by Doug Finkbeiner, Berkeley.
   05-Sep-1999  Modified and commented by David Schlegel, Princeton.

(See pro/plot/dfpsplot.pro)


DIERFC

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

 PURPOSE:
       Inverse of the Complementary Error Function "erfc^{-1}(x)" 

 CALLING SEQUENCE:
   result = dierfc( input )

 INPUTS:
   input      - Arbitrary array of values from 0 to 2.
               (positive values returned for inputs between 0 and 1)
               exact 0 return NaN,    

 OUTPUTS:
   result     - The output array of type double, with range from
                  -infinity to +infinity.  

 OPTIONAL OUTPUTS:

 COMMENTS:
   The results outside of -20 < results < +20 may lack desired accuracy 

 EXAMPLES:
    inverse = dierfc([0.0,0.0027,0.0456,1.0d,1.6827,1.9])
    sigma = -sqrt(2.0) * inverse*sqrt(2.0)
    print, sigma, format='(6f10.4)'
      -Infinity   -3.0000   -1.9991    0.0000    1.0000    1.6449

 COPYRIGHT:
    Copyright(C) 1996 Takuya OOURA (email: ooura@mmm.t.u-tokyo.ac.jp).
    You may use, copy, modify this code for any purpose and
    without fee. You may distribute this ORIGINAL package.

 REVISION HISTORY:
   11-Jun-2002   Adapted by S. Burles, MIT

(See pro/math/dierfc.pro)


DISPLAY

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

 PURPOSE:
	This procedure will display an image with the TV command that fills
	the plotting window.  It handles scale, annotations, X and PostScript
	devices, aspect ratios, logarithmic scaling, and interpolation.  
	Masked values and values below <MIN> are mapped to !P.BACKGROUND.
	Values above <MAX> are mapped to !P.COLOR.

 CATEGORY:
	Image display.

 CALLING SEQUENCE:
	DISPLAY, Image, XS, YS

 INPUTS:
	Image:	Two-dimensional array to be displayed.

 OPTIONAL INPUTS:
	XS:	Vector of x-axis values.  The length must equal the number of
		rows in <Image>

	YS:	Vector of y-axis values.  The length must equal the number of
		columns in <Image>

 KEYWORD PARAMETERS:
	TITLE=	Set this keyword to a string containing the title annotation
		to be used by PLOT.

	XTITLE=	Set this keyword to a string containing the x-axis annotation
		to be used by PLOT.

	YTITLE=	Set this keyword to a string containing the y-axis annotation
		to be used by PLOT.

	SUBTITLE=
		Set this keyword to a string containing the subtitle annotation
		to be used by PLOT.

	ASPECT=	Set this keyword to the aspect ratio (width/height) of the
		pixels.  /ASPECT is the same as ASPECT=1 and produces square
		pixels.

	/INTERPOLATE:
		Set this switch to enable bilinear interpolation for pixels
		in the expanded image.  See /PS_FINE for information
		on using this switch on a PostScript device.

	MASKVALUE=
		Set this keyword to the value that pixels with bad data or
		no data have been flagged with.  These will be mapped to 0B.

	MIN=	The minimum value of <Image> to be considered.  If MIN is not
		provided, <Image> is searched for its minimum value.  All
		values less than MIN are set to !P.BACKGROUND in the Result.

	MAX=	The maximum value of <Image> to be considered.  If MAX is not
		provided, <Image> is searched for its maximum value.  All
		values greater than MAX are set to !P.COLOR in the Result.

	BOT=	The minimum value of the scaled result.  If TOP is not
		specified, 0B is used.

	TOP=	The maximum value of the scaled result.  If TOP is not
		specified, 255B is used.

	LEVELS=	Set this keyword to a vector of data value boundaries between
		which all elements of <Image> have the same scaled byte
		value.  e.g. LEVELS=[0,1,2,5] maps all values below 0 and
		above 5 to 0B, map values between 0 and 1 to 1B, map values
		between 1 and 2 to 128B, and map values between 2 and 5 to
		255B.  This does not plot contours.

	/LOG:	Set this switch to cause a logarithmic mapping.  This is
		overridden by the LEVELS keyword.

	PS_FINE=
		Set to the approximate number of elements along an axis to 
		use in interpolating on a PostScript device.  Interpolation
		to the full indexable range of a PostScript device would be
		unwise.  This is only useful with /INTERPOLATE and
		will increase the size of the PostScript file.  The default
		size is 256 if PS_FINE= is not set or <=0, 512 if 1 < PS_FINE=
		< 512, and take from the keyword if PS_FINE > 512.

	/NOERASE:
		Set the switch to prevent output device from being erased
		before the image, scales, and annotations are displayed.

	/NO_EXPAND:
		Set this switch to prevent the image from being expanded
		to fill the plotting window.  Scaling to byte type is still
		performed.

 SIDE EFFECTS:
	TV display is altered.

 SUBORDINATE ROUTINES:
	IMGSCL()
	IMGEXP()

 RESTRICTIONS:
	This routine may work for other devices, but it has only been tested
	on 'X' and 'PS'.

 PROCEDURE:
	Straight forward.  :-)

 EXAMPLE:
	LoadCT, 3
	image = SHIFT(DIST(20, 20), 10, 10)
	scale = FINDGEN(20) - 10.0
	DISPLAY, image, scale, scale, /INTERPOLATE, TITLE='!6Smooth Slope', $
		/ASPECT
	;Use CONTOUR with /OVERPLOT to overlay contours.
	CONTOUR, image, scale, scale, LEVELS=1.0+FINDGEN(4)*2.0, /OVERPLOT

	DISPLAY		;prints out a "Usage:" line

 MODIFICATION HISTORY:
 	Written by:	Fen Tamanaha, July 10, 1993.  Release 3.1
	July 13, 1993	Fen: (3.2) Fixed /No_Expand
	July 16, 1993	Fen: (3.3) Really fixed /No_Expand

(See pro/plot/display.pro)


DJS_ANGLE_GROUP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   djs_angle_group
 PURPOSE:
   Group objects using their coordinates on the sphere.

   Any coordinates within dtheta of one another are put in the same group.
   Note that if there is a string of successive objects on the sky, each
   separated by less than dtheta, then all of these objects are assigned
   to the same group.  This is incorrect in the sense that the first and
   last objects in the string may have a large separation; however, this
   is the only unambigious answer to the problem.

 CALLING SEQUENCE:
   ngroup = djs_angle_group( ra, dec, dtheta, $
    [gstart=gstart, gcount=gcount, gindx=gindx, units=units] )

 INPUTS:
   ra:         RA of point(s) in radians/degrees/hours
   dec:        DEC of point(s) in radians/degrees
   dtheta:     Maximum angular distance for points to be considered matches

 OPTIONAL INPUTS:
   units:      Set to
                  degrees - All angles in degrees
                  hrdeg - RA angles in hours, DEC angles and output in degrees
                  radians - All angles in radians
               Default to "degrees".

 OUTPUTS:
   ngroup:     Total number of groups.  If no matches are found, then this
               equals the number of objects.

 OPTIONAL OUTPUTS:
   gstart:     Vector of length "ngroup" with the starting index of each group.
   gcount:     Vector of length "ngroup" with the number of objects in each
               group.
   gindx:      Indices of objects in each group.  The i-th group will have
               its object indices stored in gindx(gstart:gstart+gcount-1).

 PROCEDURES CALLED:

 INTERNAL SUPPORT PROCEDURES:
   djs_search_around

 REVISION HISTORY:
   29-May-1997  Written by D. Schlegel, Durham
   24-Feb-1999  Converted to IDL 5 (DJS).

(See pro/coord/djs_angle_group.pro)


DJS_ANGLE_MATCH

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

 PURPOSE:
   Given two lists of coordinates on a sphere, find matches within an
   angular distance.  For each entry in list A, find all the entries
   in list B that lie within an angular distance dtheta.
   Optionally output up to mmax of these matches per entry, giving
   the index number of the matches in mindx, and the angular distance
   in mdist.

   If the lists A and B are different, then the total number of pairs
   is given by total(mcount).
   If the lists A and B are the same, then the total number of unique
   pairs is given by (total(mcount) - N_elements(raA)) / 2.

   This function loops over the objects in each list (sort of), so it's
   not very fast.

 CALLING SEQUENCE:
   ntot = djs_angle_match( raA, decA, [raB, decB,] dtheta=dtheta, $
    [ mcount=mcount, mindx=mindx, mdist=mdist, mmax=mmax, units=units ]

 INPUTS:
   raA:        RA of first point(s) in radians/degrees/hours
   decA:       DEC of first point(s) in radians/degrees
   dtheta:     Maximum angular distance for points to be considered matches

 OPTIONAL INPUTS:
   raB:        RA of second point(s) in radians/degrees/hours
   decB:       DEC of second point(s) in radians/degrees
   mmax:       Maximum number of matches per point.  Default to 1.
   units:      Set to
                  degrees - All angles in degrees
                  hrdeg - RA angles in hours, DEC angles and output in degrees
                  radians - All angles in radians
               Default to "degrees".

 OUTPUTS:
   ntot:       Total number of points A with one or more matches in B

 OPTIONAL OUTPUTS:
   mcount:     For each A, number of matches in B.  Vector of length A.
   mindx:      For each A, indices of matches in B, sorted by their distance.
               If mmax > 1, this array is of dimensions (mmax, A).
               For each A, only the values (0:mcount-1,A) are relevant.
               If mmax = 1, then the return value is a vector.
               Any unused array elements are set to -1.
   mdist:      For each A, distance to matches in B, sorted by their distance.
               If mmax > 1, this array is of dimensions (mmax, A).
               For each A, only the values (0:mcount-1,A) are relevant.
               If mmax = 1, then the return value is a vector.
               Any unused array elements are set to -1.

 COMMENTS:
   By specifying only one set of coordinates (raA, decA), matches are found
   within that list, but avoiding duplicate matches (i.e., matching 1 to 2
   and then 2 to 1) and avoiding matching an object with itself (i.e.,
   matching 1 to 1).  If you wish to include self-matches and duplicates,
   then call with raB=raA and decB=decA.

 PROCEDURES CALLED:
   djs_diff_angle()

 INTERNAL PROCEDURES:
   djs_angle_1match()
   djs_angle_2match()

 REVISION HISTORY:
   27-May-1997  Written by David Schlegel, Durham
   24-Feb-1999  Converted to IDL 5 (DJS)
   05-Mar-1999  Made the internal routines for more efficient matching
                within the same coordinate list without duplicates, e.g.
                by only specifying raA, decA and not raB, decB.

(See pro/coord/djs_angle_match.pro)


DJS_ANGLE_NMATCH

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

 PURPOSE:
   Given two lists of coordinates on a sphere, find matches within an
   angular distance.  For each entry in list B, return the number of
   matches in list A that lie within an angular distance dtheta.

   This function loops through list A, so it is very slow if that list is long.

   The angle dtheta can be the same for each object in A, or may be set
   to a vector of length A.

   A list of indices where B has a match in A is where(nmatch GT 0).

 CALLING SEQUENCE:
   nmatch = djs_angle_nmatch( raA, decA, raB, decB, dtheta, $
    [ units=units ]

 INPUTS:
   raA:        RA of first point(s) in radians/degrees/hours
   decA:       DEC of first point(s) in radians/degrees
   raB:        RA of second point(s) in radians/degrees/hours
   decB:       DEC of second point(s) in radians/degrees
   dtheta:     Maximum angular distance for points to be considered matches

 OPTIONAL INPUTS:
   units:      Set to
                  degrees - All angles in degrees
                  hrdeg - RA angles in hours, DEC angles and output in degrees
                  radians - All angles in radians
               Default to "degrees".

 OUTPUTS:
   nmatch:     For each B, number of matches with A

 PROCEDURES CALLED:
   djs_diff_angle()

 REVISION HISTORY:
   18-Jul-1997  Written by David Schlegel, Durham
                Modified from djs_angle_match().
   24-Feb-1999  Converted to IDL 5 (DJS)

(See pro/coord/djs_angle_nmatch.pro)


DJS_ANGPOS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   djs_angpos
 PURPOSE:
   Put an angle into the range [0, 360).

 CALLING SEQUENCE:
   result = djs_angpos(xval)

 INPUTS:
   xval

 OUTPUTS:
   result

 PROCEDURES CALLED:

 REVISION HISTORY:
   Written D. Schlegel, 17 June 1996, Durham

(See pro/coord/djs_angpos.pro)


DJS_ANGSGN

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   djs_angsgn
 PURPOSE:
  Put an angle into the range [-180, 180).

 CALLING SEQUENCE:
   result = djs_angsgn(xval)

 INPUTS:
   xval

 OUTPUTS:
   result

 PROCEDURES CALLED:

 REVISION HISTORY:
   Written D. Schlegel, 17 June 1996, Durham

(See pro/coord/djs_angsgn.pro)


DJS_ARROW

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

 PURPOSE:
   Modified version of ARROW to allow a string for the color(s)

 CALLING SEQUENCE:
   djs_arrow

 INPUT:

 OUTPUTS:

 PROCEDURES CALLED:

 REVISION HISTORY:
   Written by D. Schlegel, 11 Dec 1998, Princeton

(See pro/plot/djs_arrow.pro)


DJS_AVSIGCLIP

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

 PURPOSE:
   Average multiple images with sigma-rejection.

 CALLING SEQUENCE:
   result = djs_avsigclip( array, [ dimension, sigrej=, maxiter=, $
    inmask=, outmask= ] )

 INPUTS:
   array      - N-dimensional array

 OPTIONAL INPUTS:
   dimension  - The dimension over which to collapse the data.  If ommitted,
                assume that the last dimension is the one to collapse.
   sigrej     - Sigma for rejection; default to 3.0.
   maxiter    - Maximum number of sigma rejection iterations.  One iteration
                does no sigma rejection; default to 10 iterations.
   inmask     - Input mask, setting =0 for good elements

 OUTPUTS:
   result     - The output array.
   outmask    - Output mask, setting =0 for good elements, =1 for bad.
                Any pixels masked in INMASK are also masked in OUTMASK.

 OPTIONAL OUTPUTS:

 COMMENTS:
   The DIMENSION input is analogous to that used by the IDL built-in
   function TOTAL.

 EXAMPLES:
   Create a data cube of 10 random-valued 100x200 images.  At each pixel in
   the image, compute the average of the 10 values, but rejecting 3-sigma
   outliers:
   > array = randomu(123,100,200,10)
   > ave = djs_avsigclip(array, sigrej=3)


   If all points are masked in any given vector or array, a mean and
   dispersion are computed for all the points.  Is this the behaviour we want?
   If you want to replace those values with zeros instead, look at OUTMASK:
   > array = randomu(123,100,200)
   > inmask = bytarr(100,200)
   > inmask[*,8] = 1 ; mask all of row #8
   > ave = djs_avsigclip(array, 1, inmask=inmask, outmask=outmask)
   > ibad = where( total(1-outmask, 1) EQ 0)
   > if (ibad[0] NE -1) then ave[ibad] = 0 ; zero-out bad rows

 BUGS:

 PROCEDURES CALLED:
   Dynamic link to arravsigclip.c

 REVISION HISTORY:
   07-Jul-1999  Written by David Schlegel, Princeton.

(See pro/math/djs_avsigclip.pro)


DJS_AXIS

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

 PURPOSE:
   Modified version of AXIS

 CALLING SEQUENCE:
   djs_axis

 INPUT:

 OUTPUTS:

 PROCEDURES CALLED:
   TeXtoIDL()

 REVISION HISTORY:
   Written by D. Schlegel, 21 Jan 1998, Durham

(See pro/plot/djs_axis.pro)


DJS_BATCH

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

 PURPOSE:
   Batch processing script for running jobs locally or across a network.

 CALLING SEQUENCE:
   djs_batch, topdir, [localfile], [outfile], protocol, remotehost, $
    remotedir, command, [ priority=, selecthost=, wtime= ]

 INPUTS:
   topdir     - Local top-level directory for input and output files.
                Also use this directory for remote hosts where REMOTEDIR
                is not specified.
   localfile  - Array of pointers to input files on local machine [NPROGRAM].
                This input is optional.
   outfile    - Array of pointers to output files created on remote machine
                and copied to local machine upon completion [NPROGRAM]
                This input is optional.
   protocol   - List of protocols for remote hosts.  Valid values are:
                'ssh', 'ssh1', 'ssh2', 'rsh', or ''.  One must set to
                no protocol ('') if the remote host name is 'localhost'.
                Otherwise, one must always set a protocol.
   remotehost - List of remote hosts [NHOST]
   remotedir  - List of remote directories; scalar or [NHOST]
   command    - Command to execute to begin a job; scalar or [NPROGAM]

 OPTIONAL KEYWORDS:
   priority   - Priority for each job, where the jobs with the largest
                value are done first [NPROGRAM]
   selecthost - If set, then assign each job to only a host that matches
                the selected host per job [NPROGRAM]