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]
   wtime      - Sleep time between checking status of all jobs; default to
                600 seconds.

 OUTPUTS:

 COMMENTS:
   The file names will support wildcards.  For example, if you want to
   return all files from the directory REMOTEDIR/abc on the remote machine,
   then set OUTFILE = 'abc/*'.

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:

 INTERNAL SUPPORT ROUTINES:
   batch_spawn
   count_freelun()
   create_program_list()
   create_host_list()
   batch_if_done()
   batch_assign_job
   batch_finish_job

 REVISION HISTORY:
   17-Oct-2000  Written by D. Schlegel, Princeton

(See pro/misc/djs_batch.pro)


DJS_CEIL

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

 PURPOSE:
   Return smallest integer not less than xvalue.
   This is identical to the C library function "ceil()".

 CALLING SEQUENCE:
   result = djs_ceil(xvalue)

 INPUTS:
   xvalue

 OUTPUTS:
   result

 PROCEDURES CALLED:

 REVISION HISTORY:
   Written D. Schlegel, 27 November 1996, Durham

(See pro/math/djs_ceil.pro)


DJS_CONTOURPTS

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

 PURPOSE:
   Make a contour plot from point data, drawing contours only where the
   point density is high.

 CALLING SEQUENCE:
   djs_contourpts

 INPUT:
   xpt:
   ypt:

 OPTIONAL KEYWORDS:
   bin1:
   bin2:
   overplot:  If set, then use current plot limits and overplot.
   nlevels:
   levels:
   loglevels: If set, then select NLEVEL (or 6) log-spaced levels
   nopoints:  If set, then do not plot any point data (only contours).
   psym:      Keyword for plotting point data; default to 3
   color:     Keyword for plotting point data

 OUTPUTS:

 OPTIONAL OUTPUTS:
   level0:    Lowest contour level
   ilow:      Indices for points outside the lowest contour level.

 PROCEDURES CALLED:
   djs_icolor()
   djs_oplot

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

(See pro/plot/djs_contourpts.pro)


DJS_CORRELATE

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

 PURPOSE:
   Compute a cross-correlation function using weights (or masks).

 CALLING SEQUENCE:
   result = djs_correlate( x, y, [ lags, xweight=, yweight= ] )

 INPUTS:
   x          - Vector
   y          - Vector, which may have a different number of elements from X

 OPTIONAL INPUTS:
   lags       - A scalar or integer vector specifying the lags at which
                to compute the cross-correlation; default to one lag at 0.
   xweight    - Vector of weights for X; default to 1 for all points
   yweight    - Vector of weights for Y; default to 1 for all points

 OUTPUTS:
   result     - The output vector, with one result per LAG value.

 OPTIONAL OUTPUTS:

 COMMENTS:
   This routine is similar to the IDL routine C_CORRELATE(), but with a
   few notable differences.  The X and Y vectors do not wrap when they are
   shifted, but rather only overlapping elements are compared at each lag.
   Because of this, X and Y do not have to have the same number of dimensions.
   A weight (or mask) can be assigned to each element of X,Y using the
   XWEIGHT,YWEIGHT keywords.  These weights can effectively be used to
   mask out regions of each vector by setting the weight to 1 for good
   pixels and 0 for bad ones.

   Each pixel of both X and Y are effectively weighted by XWEIGHT*YWEIGHT
   appropriately shifted before the multiplication.

 EXAMPLES:

 BUGS:
   The C routine only supports type FLOAT.

 PROCEDURES CALLED:
   Dynamic link to ccorrelate.c

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

(See pro/math/djs_correlate.pro)


DJS_DIFF_ANGLE

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

 PURPOSE:
   Compute the angular distance between two points on a sphere.

 CALLING SEQUENCE:
   adist = djs_diff_angle( ra, dec, ra0, dec0, [ units=units ] )

 INPUTS:
   ra1:        RA of first point(s) in radians/degrees/hours
   dec1:       DEC of first point(s) in radians/degrees
   ra2:        RA of second point(s) in radians/degrees/hours
   dec2:       DEC of second point(s) in radians/degrees

 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:
   adist:      Angular distance(s) in radians if UNITS is set to 'radians',
               or in degrees otherwise

 COMMENTS:
   Note that either (ra1,dec1) or (rap,decp) must be scalars or 1-element
   arrays, or all must be arrays of the same length.

 PROCEDURES CALLED:

 REVISION HISTORY:
   14-May-1997  Written by D. Schlegel, Durham

(See pro/coord/djs_diff_angle.pro)


DJS_FLOOR

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

 PURPOSE:
   Return largest integer not greater than xvalue.
   This is identical to the C library function "floor()".

 CALLING SEQUENCE:
   result = djs_floor(xvalue)

 INPUTS:
   xvalue

 OUTPUTS:
   result

 PROCEDURES CALLED:

 REVISION HISTORY:
   Written D. Schlegel, 27 November 1996, Durham

(See pro/math/djs_floor.pro)


DJS_HEX2BIN

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

 PURPOSE:
   Convert hexadecimal number(s) to binary numbers.

 CALLING SEQUENCE:
   binval = djs_hex2bin(hexval, [ndigit=ndigit])

 INPUTS:
   hexval:   String or array of strings containing hexadecimal number(s)

 OPTIONAL INPUTS:
   ndigit:   Number of binary digits in output; if not supplied, then the
             minimum number of digits are used

 OUTPUTS:
   intval:   Byte array(s) of binary values, dimensioned intval(ndigit,nnum)

 EXAMPLE:
   PRINT, DJS_HEX_TO_BINARY( '1a' )
   IDL prints the result
     0   1   0   1   1

   One can truncate to only the 4 least significan digits by setting NDIGIT:
   PRINT, DJS_HEX_TO_BINARY( '1a', NDIGIT=4 )
   IDL prints the result
     0   1   0   1

   PRINT, DJS_HEX_TO_BINARY( ['1a', '2b', '3'] )
   IDL prints the result
     0   1   0   1   1   0
     1   1   0   1   0   1
     1   1   0   0   0   0

 PROCEDURES CALLED:
   djs_hex2int()
   djs_int2bin()

 REVISION HISTORY:
   Written D. Schlegel, 30 June 1997, Durham

(See pro/math/djs_hex2bin.pro)


DJS_HEX2INT

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

 PURPOSE:
   Convert hexadecimal number(s) to long integer(s).

 CALLING SEQUENCE:
   intval = djs_hex2int(hexval)

 INPUTS:
   hexval:   String or array of strings containing hexadecimal number(s)

 OUTPUTS:
   intval:   Long integer or array or long integers

 EXAMPLE:
   PRINT, DJS_HEX_TO_INT( '1a' )
   IDL prints the result
     26

   PRINT, DJS_HEX_TO_INT( ['1a', '2b', '3'] )
   IDL prints the result
     26  43   3

 PROCEDURES CALLED:

 REVISION HISTORY:
   Written D. Schlegel, 30 June 1997, Durham

(See pro/math/djs_hex2int.pro)


DJS_ICOLOR

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

 PURPOSE:
   Internal routine for converting a color name to an index.

 CALLING SEQUENCE:
   icolor = djs_icolor(color)

 INPUT:
   color:

 OUTPUTS:
   icolor

 PROCEDURES CALLED:

 REVISION HISTORY:
   Written by D. Schlegel, 27 September 1997, Durham

(See pro/plot/djs_icolor.pro)


DJS_INT2BIN

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

 PURPOSE:
   Convert integer number(s) to binary numbers.

 CALLING SEQUENCE:
   binval = djs_int2bin(val, [ndigit=ndigit])

 INPUTS:
   val:      Integer number(s)

 OPTIONAL INPUTS:
   ndigit:   Number of binary digits in output; if not supplied, then the
             minimum number of digits are used

 OUTPUTS:
   binval:   Byte array(s) of binary values

 PROCEDURES CALLED:
   djs_floor()

 REVISION HISTORY:
   Written D. Schlegel, 30 June 1997, Durham
   31-Jul-1998  DJS - Subscripts modified to IDL 5 convention.
   03-Aug-1999  DJS - Modified to work with signed integers by
                first converting to unsigned integers.

(See pro/math/djs_int2bin.pro)


DJS_ITERSTAT

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

 PURPOSE:
   Compute the mean, median and/or sigma of data with iterative sigma clipping.

 CALLING SEQUENCE:
   djs_iterstat, image, [sigrej=, maxiter=, mean=, median=, sigma=, mask=]

 INPUTS:
   image:      Input data

 OPTIONAL INPUTS:
   sigrej:     Sigma for rejection; default to 3.0
   maxiter:    Maximum number of sigma rejection iterations; default to 10

 OUTPUTS:

 OPTIONAL OUTPUTS:
   mean:       Computed mean
   median:     Computed median
   sigma:      Computed sigma
   mask:       Mask set to 1 for good points, and 0 for rejected points

 PROCEDURES CALLED:

 COMMENTS:
   This routine is based upon Mark Dickinson's IRAF (!) script ITERSTAT.
   It iteratively rejects outliers as determined by SIGREJ.  It stops
   when one of the following conditions is met:
   (1) The maximum number of iterations, as set by MAXITER, is reached.
   (2) No new pixels are rejected, as compared to the previous iteration.
   (3) At least 2 pixels remain from which to compute statistics.  If not,
       then the returned values are based upon the previous iteration.

 BUGS:

 REVISION HISTORY:
   16-Jun-1999  Written by David Schlegel, Princeton
   11-Sep-2000  Speeded up by Hogg and Eisenstein
   18-Sep-2000  Note change in MASK values to =1 for good (unrejected) points.

(See pro/math/djs_iterstat.pro)


DJS_LAXISGEN

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

 PURPOSE:
   Return a longword integer array with the specified dimensions.
   Each element of the array is set equal to its index number along
   the dimension IAXIS.

 CALLING SEQUENCE:
   result = djs_laxisgen( dimens, [ iaxis=iaxis ] )

 INPUT:
   dimens:     Vector of the dimensions for the result.
               Only up to 3 dimensions can be specified.
   iaxis:      Axis number to use for indexing RESULT.  The first dimension
               is axis number 0, the second 1, etc.  Default to 0.

 OUTPUTS:
   result:     Output array

 PROCEDURES CALLED:

 REVISION HISTORY:
   Written by D. Schlegel, 7 Oct 1997, Durham
   Modified 12 May 1998 to pass one vector with all dimensions.

(See pro/misc/djs_laxisgen.pro)


DJS_LAXISNUM

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

 PURPOSE:
   Return a longword integer array with the specified dimensions.
   Each element of the array is set equal to its index number in
   the specified axis.

 CALLING SEQUENCE:
   result = djs_laxisnum( dimens, [ iaxis= ] )

 INPUT:
   dimens:     Vector of the dimensions for the result.
               Only up to 3 dimensions can be specified.
   iaxis:      Axis number to use for indexing RESULT.  The first dimension
               is axis number 0, the second 1, etc.  Default to 0.

 OUTPUTS:
   result:     Output array

 PROCEDURES CALLED:

 REVISION HISTORY:
   15-Jun-2001  Written by D. Schlegel, Princeton

(See pro/misc/djs_laxisnum.pro)


DJS_LOCATE_FILE()

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

 PURPOSE:
   Locate full file name (including path) of a file, searching IDL paths

 CALLING SEQUENCE:
   fullname = djs_locate_file( filename )

 INPUT:
   filename:   File name to find somewhere in path, including any extensions

 OUTPUTS:
   fullname:   File name of first located file (including full path),
               or '' if no matches found

 PROCEDURES CALLED:
   os_family()

 REVISION HISTORY:
   Written by D. Schlegel, 27 May 1997, Durham
   Modified version of GETPRO in Goddard library.

(See pro/misc/djs_locate_file.pro)


DJS_LOCKFILE

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

 PURPOSE:
   Test if a file is already "locked", and lock it if not.

 CALLING SEQUENCE:
   res = djs_lockfile( filename, [ lun=, append= ] )

 INPUT:
   filename:   File name

 OPTIONAL INPUTS:
   lun:        If this argument exists, then open FILENAME for read/write
               access and return the pointer (LUN number) for that file.
               Do this only if we are able to lock the file.
   append:     If set, then append to any file that already exists if
               opening the file using LUN.  Ignored if the LUN argument
               is not present.

 OUTPUTS:
   res:        Return 0 if file already locked, or 1 if not in which case
               we would have just locked it.

 COMMENTS:
   For Unix systems running IDL 5.4 or later, we use the SPAWN command
   to create a symbolic link from FILENAME.lock -> FILENAME.  This can
   be done atomically, such that it is impossible for two processes
   to build that same link at once.

   For other operating systems or ealier versions of IDL (which do
   not allow SPAWN to return an error), we use a lock file which
   has a single byte written to it to indicate that FILENAME should
   be locked (as determined by any subsequent calls to this routine).

   For all OS-es, unlock files with DJS_UNLOCKFILE.

 BUGS:

 PROCEDURES CALLED:

 REVISION HISTORY:
   30-Apr-2000  Written by D. Schlegel, APO

(See pro/misc/djs_lockfile.pro)


DJS_MASKINTERP

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

 PURPOSE:
   Interpolate over masked pixels in a vector, image or 3-D array.

 CALLING SEQUENCE:
   ynew = djs_maskinterp( yval, mask, [ xval, iaxis=, /const ] )

 INPUTS:
   yval       - Y values; 1-, 2-, or 3-dimensional
   mask       - Mask values correspoding to YVAL; interpolate over all pixels
                where MASK is not 0

 OPTIONAL INPUTS:
   xval       - X (abscissa) values corresponding to YVAL; otherwise a
                regular grid is assumed
   iaxis      - Axis along which to interpolate if YVAL has more than one
                dimension; required keyword in that case; dimensions are
                0-indexed, so the X axis is IAXIS=0
   const      - The default is to linearly interpolate beyond the endpoints
                of good data.  Setting this keyword instead copied the
                first (last) good points for the data beyond the first (last)
                good points.

 OUTPUTS:
   ynew       - Y values after linearly interpolating over masked pixels

 COMMENTS:
   The IDL function INTERPOL is used for linear interpolation.

   If no good points exist in a vector, then that vector is returned
   unchanged.

 EXAMPLES:
   Create a sin-wave function, and interpolate across points at the beginning
   and in the middle of this function:
     xval=findgen(100)/10
     yval=sin(xval)
     splot,xval,yval
     mask=bytarr(100)
     mask[0:10]=1
     mask[40:60]=1
     ynew = djs_maskinterp(yval, mask, xval)
     plot,xval,yval
     oplot,xval,ynew,ps=2

 BUGS:
   This routine only supports 1-D, 2-D, and 3-D arrays.

 PROCEDURES CALLED:

 INTERNAL SUPPORT ROUTINS:
   djs_maskinterp1()

 REVISION HISTORY:
   27-Jan-2000  Written by David Schlegel, Princeton.

(See pro/image/djs_maskinterp.pro)


DJS_MEAN

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

 PURPOSE:
   Return the mean value of an array.

 CALLING SEQUENCE:
   result = djs_mean(array)

 INPUTS:
   array      - Array of numbers

 OUTPUTS:
   result     - Computed mean

 PROCEDURES CALLED:

 COMMENTS:
   This function is faster than the IDL function MEAN(), and will not crash
   when passed a 1-element array.

 REVISION HISTORY:
   06-Oct-1997  Written by David Schlegel, Durham.

(See pro/math/djs_mean.pro)


DJS_MEDIAN

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

 PURPOSE:
   Return the median of an image either with a filtering box or by collapsing
   the image along one of its dimensions.

 CALLING SEQUENCE:
   result = djs_median( array, [ dimension, width=, boundary= ] )

 INPUTS:
   array      - N-dimensional array

 OPTIONAL INPUTS:
   dimension  - The dimension over which to compute the median, starting
                at one.  If this argument is not set, the median of all array
                elements (or all elements within the median window described
                by WIDTH) are medianed.
   width      - Width of median window; scalar value.
                It is invalid to specify both DIMENSION and WIDTH.
   boundary   - Boundary condition:
                'none': Do not median filter within WIDTH/2 pixels of
                        the edge; this is the default for both this
                        routine and MEDIAN().
                'nearest': Use the value of the nearest boundary pixel.
                        NOT IMPLEMENTED
                'reflect': Reflect pixel values around the boundary.
                'wrap': Wrap pixel values around the boundary.
                        NOT IMPLEMENTED
                These boundary conditions only take effect if WIDTH is set,
                and if ARRAY is either 1-dimensional or 2-dimensional.

 OUTPUTS:
   result     - The output array.  If neither DIMENSION nor WIDTH are set,
                then RESULT is a scalar.  If DIMENSION is not set and WIDTH
                is set, then RESULT has the same dimensions as ARRAY.
                If DIMENSION is set and WIDTH is not

 OPTIONAL OUTPUTS:

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

   I should like to add the functionality of having WIDTH be an N-dimensional
   smoothing box.  For example, one should be able to median a 2-D image
   with a 3x5 filtering box.

 EXAMPLES:
   Create a 2-D image and compute the median of the entire image:
   > array = findgen(100,200)
   > print, djs_median(array)

   Create a data cube of 3 random-valued 100x200 images.  At each pixel in
   the image, compute the median of the 3:
   > array = randomu(123,100,200,3)
   > medarr = djs_median(array,3)

   Create a random-valued 2-D image and median-filter with a 9x9 filtering box:
   > array = randomu(123,100,200)
   > medarr = djs_median(array,9)

 BUGS:
   The C routine only supports type FLOAT.

 PROCEDURES CALLED:
   Dynamic link to arrmedian.c

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

(See pro/math/djs_median.pro)


DJS_MODFITS

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

 PURPOSE:
   Wrapper for MODFITS that allows the header to increase in size,
   and that works with g-zipped files.

 CALLING SEQUENCE:
   djs_modfits, filename, data, [hdr, exten_no=, /delete_data]

 INPUTS:
   filename  - FITS file name; if the name ends in the suffix ".gz",
               then the file is g-unzipped first, modified, then re-g-zipped.
   data      - New data array or structure for extension EXTEN_NO;
               if this is undefined or zero, then don't modify the data.

 OPTIONAL INPUTS:
   hdr       - New FITS header for extension EXTEN_NO
   exten_no  - FITS extension number to modify; default to 0.
   delete_data - If set, then delete this data.  Note that this cannot
               be accomplished by setting DATA=0, since that simply says
               to not change the data array/structure (to be consistent
               with the functionality of MODFITS).

 OUTPUTS:

 OPTIONAL OUTPUTS:

 COMMENTS:

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:
   modfits
   mrdfits()
   mwrfits
   readfits()
   writefits

 INTERNAL PROCEDURES:
   bitsperpixel()

 REVISION HISTORY:
   17-May-2000  Written by David Schlegel, Princeton.

(See pro/fits/djs_modfits.pro)


DJS_MOSAIC_RGB

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   djs_mosaic_rgb
 PURPOSE:
   Make color (RGB) images from 3 FITS files, and overplot text and points
 CALLING SEQUENCE:
   djs_mosaic_rgb, prefix
 INPUTS:
   prefix        - start of filenames
 OPTIONAL KEYWORDS:
   resizefactor  - factor by which to scale the JPG relative to the
                   fits files; default 0.5
   stretch       - factor by which to multiply the default RGB
                   scales; default 1.0
   rotation      - integer to pass to IDL rotate command; default 0
   xtext         - X position for text [NTEXT]
   ytext         - Y position for text [NTEXT]
   text          - Text [NTEXT]
   colortext     - Colors for text; dimensioned either [3] or [3,NTEXT],
                   where [255,0,0] is red, [0,255,0] is green, etc.
   xplot         - X position for points [NPOINTS]
   yplot         - Y position for points [NPOINTS]
   colorplot     - Colors for points; dimensioned either [3] or [3,NPOINTS],
                   where [255,0,0] is red, [0,255,0] is green, etc.
   _EXTRA        - Keywords to pass to XYOUTS and PLOT, such as
                   CHARSIZE, PSYM, etc
 COMMENTS:
   Stretch is constant in f_lambda
 EXAMPLES:
   djs_mosaic_rgb, 'marla-001'
 BUGS:
   Memory issues with asinh etc.
   The current implementation is very slow if COLORTEXT or COLORPLOT
     are 2-dimensional arrays.
 REVISION HISTORY:
   2003-11-24  written - Hogg
   2004-01-03  Modified (generalized) by D. Schlegel, Princeton

(See pro/rgbcolor/djs_mosaic_rgb.pro)


DJS_NEFF

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

 PURPOSE:
   Return the neff statistic (effective number of pixels)
     neff = [ SUM(image) ]^2 / SUM(image^2)

 CALLING SEQUENCE:
   neff = djs_neff(image, [sigimg, nerr=nerr] )

 INPUTS:
   image:      An image of any number of dimensions

 OPTIONAL INPUTS:
   sigimg:     Image of errors for computing nerr

 OUTPUTS:
   neff:       Return value of neff

 OPTIONAL OUTPUTS:
   nerr:       Error in neff, if sigimg is specified

 PROCEDURES CALLED:

 COMMENTS:
   If computing this statistic for an object on an image, the background
   (sky) level should first be removed.  However, the image need not be
   renormalized.  For an object of constant surface brightness, Neff equals
   the number of pixels subtended by the object.  For a Gaussian profile
   that is well-sampled, Neff = 4 * pi * sigma^2.

 REVISION HISTORY:
   10-Sep-1998  Written by D Schlegel, Princeton

(See pro/djsphot/djs_neff.pro)


DJS_OPLOT

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

 PURPOSE:
   Modified version of OPLOT.

 CALLING SEQUENCE:
   djs_oplot, [x,] y

 INPUT:
   x:
   y:

 OUTPUTS:

 COMMENTS:
   Allows COLOR, PSYM, and SYMSIZE to be vectors.
   Also allows COLOR to be string descriptions of eight possible colors.
   If string descriptors are used, then load a basic 8-color color table.

 PROCEDURES CALLED:
   djs_icolor()

 REVISION HISTORY:
   Written by D. Schlegel, 27 September 1997, Durham

(See pro/plot/djs_oplot.pro)


DJS_OPLOTERR

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

 PURPOSE:
   Modified version of OPLOTERR and DJS_OPLOT.

   Allows COLOR, PSYM, and SYMSIZE to be vectors.
   Also allows COLOR to be string descriptions of eight possible colors.
   If string descriptors are used, then load a basic 8-color color table.

 CALLING SEQUENCE:
   djs_oploterr, [x,] y, xerr=xerr, yerr=yerr, xlog=xlog, ylog=ylog, $
    cap=cap, xlen=xlen, ylen=ylen, $
    color=color, psym=psym, symsize=symsize

 INPUT:
   x:
   y:

 OPTIONAL INPUTS:
   xerr:   Error in X; or -1 for upper limit arrow, -2 for lower limit arrow
   yerr:   Error in Y; or -1 for upper limit arrow, -2 for lower limit arrow
   xlog:   If set, take the logarithm of X and its error
   ylog:   If set, take the logarithm of Y and its error
   cap:    If set, place caps on error bars
   xlen:   Length of upper/lower limit bars in X; default to 6% of plot range
   ylen:   Length of upper/lower limit bars in Y; default to 6% of plot range

 OUTPUTS:

 PROCEDURES CALLED:

 REVISION HISTORY:
   Written by D. Schlegel, 5 February 1998, Durham

(See pro/plot/djs_oploterr.pro)


DJS_PHOT

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

 PURPOSE:
   Driver for aperture photometry with the option of re-centering and
   sky-subtraction.

 CALLING SEQUENCE:
   flux = djs_phot( xcen, ycen, objrad, skyrad, image, [invvar, $
    calg=, cbox=, cmaxiter=, cmaxshift=, $
    fwhm=, fixfw=, ceps=, $
    salg=, srejalg=, smaxiter=, $
    lorej=, hirej=, $
    flerr=, skyval=, skyrms=, skyerr=, peakval=, /quick, /exact ] )

 INPUTS:
   xcen:       X center(s)
   ycen:       Y center(s)
   objrad:     Radius for aperture on object, or a vector of such radii.
   skyrad:     A 2-element array with two radii to define an annulus,
               or a scalar to define a circular aperture, or undefined
               for no sky calculation
   image:      FITS data array, as read from readfits().

 OPTIONAL INPUTS:
   invvar:     Inverse variance image, for computing the errors FLERR
   ----------- FOR CENTERING ALGORITHM
   calg:       Centering algorithm.  Choose from iweight, gauss1, gauss2, none.
                 iweight = intensity-weighted center, computed independently
                           in both X and Y
                 gauss1  = gaussian fit, including a constant term, computed
                           independently in both X and Y
                 gauss2  = not implemented
                 none    = no centering
               Default to iweight.
   cbox:       Centering box width.  Default to 7.
   cmaxiter:   Maximum number of iterations for centering algorithm.
               Default to 10.
   cmaxshift:  Maximum center shift.  If this shift is exceeded in either
               X or Y, then return the center position passed in XCEN,YCEN.
               A value of 0 imposes no maximum shift.  Default to 3.
   fwhm:       FWHM for gauss1 or gauss2 centering algorithms.  If this is
               a scalar, then the same value is used for both X and Y.
               If this is a vector, then the first two elements are used
               for X and Y respectively.
   fixfw:      If set and nonzero, then fix the FWHM for gauss1 or gauss2 fits.
   ceps:       Stop iterating when relative shifts in both X and Y are less
               than this value.  Default to 0.

   ----------- FOR SKY FITTING ALGORITHM
   salg:       Sky fitting algorithm.  Choose from mean, median, mode, none.
               Default to "mean" if SKYRAD is set, or "none" otherwise.
   srejalg:    Rejection algorithm.  Choose from none, sigclip, pclip.
                 sigclip = sigma clipping; reject outliers that are
                           more than lorej*sigma below skyval or hirej*sigma
                           above skyval
                 pclip   = percentile clipping; reject the lowest lorej
                           fraction and the highest hirej fraction of points
                 none    = no rejection
               Default to sigclip
   smaxiter:   Maximum number of srejalg iterations.  Default to 10.
   lorej:      If srejalg="sigclip", then the number of standard deviations
               below skyval to clip (default to 3.0).
               If srejalg="pclip", then fraction of low pixels to clip
               (default to 0.05).
   hirej:      If srejalg="sigclip", then the number of standard deviations
               above skyval to clip (default to 3.0).
               If srejalg="pclip", then fraction of high pixels to clip
               (default to 0.05).
 
 KEYWORDS:
   exact       Use slow photo-based photfrac algorithm (Not thoroughly tested)
               Requires image to be centered such that xcen and ycen
               are integer values. If set, does not recalculate
               center.
   quick       Use faster photfrac algorithm (Not thoroughly tested)

 OUTPUTS:
   flux:       Total flux within each circular aperture defined by objrad,
               minus the sky contribution within each aperture [NOBJ,NRAD].
   xcen:       Re-centered X position (modified).
   ycen:       Re-centered X position (modified).

 OPTIONAL OUTPUTS:
   flerr:      Flux error from the sky background uncertainty within
               the object aperture(s) [NOBJ,NRAD]
   skyval:     Sky value in counts per unit area [NOBJ].
   skyrms:     RMS of sky pixels about skyval, again in counts per unit area.
               This assumes that each unit area is independent.  The RMS
               is computed for only the values that remain after all the
               rejection iterations [NOBJ].
   skyerr:     The error in skyval assuming that each pixel is independent.
               This is skyrms divided by the square root of the number of
               pixels [NOBJ].
   peakval:    Peak pixel value (before sky-subtraction)

 COMMENTS:
   Sub-pixel sampling of the circular apertures is handled exactly.
   If /exact keyword is set, input xcen, ycen must be integers or 
     the code bombs. See exact_photfrac.pro for more details, but 
     basically exact_photfrac is much simpler to implement if the 
     object is already centered, which doesn't cost you precision.
   For similar reasons, if /exact is set, djs_phot will not try to
     recentroid your object.
 PROCEDURES CALLED:
   djs_photcen
   djs_photfrac
   djs_photsky()

 REVISION HISTORY:
   28-Nov-1996  Written by D. Schlegel, Durham.
   01-Jun-2000  Major revisions: change XYCEN to XCEN,YCEN; remove use
                of FITS headers; make IDL 5 compliant (DJS).
   02-Nov-2000  objrad, skyrad recast as floats (D. Finkbeiner)
                  If they are ints, 1% errors may arise. 

(See pro/djsphot/djs_phot.pro)


DJS_PHOTCEN

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

 PURPOSE:
   Recenter an object position.

 CALLING SEQUENCE:
   djs_photcen, xcen, ycen, image, $
    [ calg=, cbox=, cmaxiter=, cmaxshift=, fwhm=, /fixfw, ceps=, qmaxshift= ]

 INPUTS:
   xcen:       X center(s)
   ycen:       Y center(s)
   image:      2-dimensional image

 OPTIONAL INPUTS:
   calg:       Centering algorithm.  Choose from iweight, gauss1, gauss2, none.
                 iweight = intensity-weighted center, computed independently
                           in both X and Y
                 gauss1  = gaussian fit, including a constant term, computed
                           independently in both X and Y
                 gauss2  = 2D gaussian fit, including a constant term
                 none    = no centering
               Default to iweight.
   cbox:       Centering box width.  Default to 7.
   cmaxiter:   Maximum number of iterations for centering algorithm.
               Default to 10.
   cmaxshift:  Maximum center shift.  If this shift is exceeded in either
               X or Y, then return the center position passed in XCEN, YCEN.
               A value of 0 imposes no maximum shift.  Default to 3.
   fwhm:       FWHM for gauss1 or gauss2 centering algorithms.  If this is
               a scalar, then the same value is used for both X and Y.
               If this is a vector, then the first two elements are used
               for X and Y respectively.
   fixfw:      If set and nonzero, then fix the FWHM for gauss1 or gauss2 fits.
   ceps:       Stop iterating when relative shifts in both X and Y are less
               than this value.  Default to 0.

 OUTPUTS:
   xcen:       Re-centered X position (modified).
   ycen:       Re-centered X position (modified).

 OPTIONAL OUTPUS:
   qmaxshift:  Return 1 if maximum shift was reached in either X or Y.
               Return 0 otherwise.

 PROCEDURES CALLED:
   curvefit()
   djs_ceil()
   djs_floor()
   gauss2dfit()

 REVISION HISTORY:
   01-Dec-1996  Written by D. Schlegel, Durham.
   10-Aug-1998  Added option for calg='gauss2' (DJS).
   01-Jun-2000  Major revisions: change XYCEN to XCEN,YCEN; remove use
                of FITS headers; make IDL 5 complient (DJS).

(See pro/djsphot/djs_photcen.pro)


DJS_PHOTFRAC

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

 PURPOSE:
   Create a list of pixel numbers and their fractional contribution to
   an annular region.

 CALLING SEQUENCE:
   djs_photfrac, xcen, ycen, Rvec, xdimen=, ydimen=, $
    [ xPixNum=, yPixNum=, pixnum=, fracs=, fillfrac= ]

 INPUTS:
   xcen:       X center(s)
   ycen:       Y center(s)
   Rvec:       Either a 2-element array with two radii to define an annulus,
               or a scalar to define a circular aperature.

 OPTIONAL INPUTS:
   xdimen:     Number of X pixels.
   ydimen:     Number of Y pixels.

 OUTPUTS:
   pixnum:     Pixel number, 0-indexed, for referencing array using one index.
   xPixNum:    Pixel number in X, 0-indexed.
   yPixNum:    Pixel number in Y, 0-indexed.
   fracs:      Return value of covering fraction of the annulus
               over the pixel number.
   fillfrac:   Ratio of returned pixel areas to the annulus area;
               this ratio should equal 1.0 if the aperature falls completely
               within the image boundaries

 COMMENTS:
   The total counts within this region is given by
     totcounts = total( pData(pixnum) * fracs )
   The area within this region is given by
     area = total(fracs)
   The average counts is given by
     totcounts = total( pData(pixnum) * fracs ) / total(fracs)
   To test for bad pixels, e.g. values greater than vmax, within
   the aperature,
     if (where(pData(pixnum) GT vmax) EQ -1) then <no bad values> $
     else <bad values exist>

   If no pixels within the given annulus are found, then return pixnum=-1.

 BUGS:
   - can wrap around on edge of you use PixNum.  XPixNum,YPixNum do
     not exhibit this problem

 PROCEDURES CALLED:
   djs_ceil()
   djs_floor()

 REVISION HISTORY:
   Written D. Schlegel, 27 November 1996, Durham
   Bug identified - 2 Nov 2000, D. Finkbeiner 

(See pro/djsphot/djs_photfrac.pro)


DJS_PHOTSKY

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

 PURPOSE:
   Compute the sky value within an annulus.

   At present, fractional pixels are not treated properly; this is because
   we need a sort routine that carries index numbers, such as NR indexx().

 CALLING SEQUENCE:
   skyval = djs_photsky( xcen, ycen, skyrad, image, $
    [ salg=, srejalg=, smaxiter=, $
    lorej=, hirej=, skyrms=, skyerr= ] )

 INPUTS:
   xcen:       X center(s)
   ycen:       Y center(s)
   skyrad:     A 2-element array with two radii to define an annulus,
               or a scalar to define a circular aperature, or undefined or 0
               for no sky calculation
   image:      FITS data array, as read from readfits().

 OPTIONAL INPUTS:
   salg:       Sky fitting algorithm.  Choose from mean, median, mode, none.
               Default to "mean" if SKYRAD is set, or "none" otherwise.
   srejalg:    Rejection algorithm.  Choose from none, sigclip, pclip.
                 sigclip = sigma clipping; reject outliers that are
                           more than lorej*sigma below skyval or hirej*sigma
                           above skyval
                 pclip   = percentile clipping; reject the lowest lorej
                           fraction and the highest hirej fraction of points
                 none    = no rejection
               Default to sigclip
   smaxiter:   Maximum number of srejalg iterations.  Default to 10.
   lorej:      If srejalg="sigclip", then the number of standard deviations
               below skyval to clip (default to 3.0).
               If srejalg="pclip", then fraction of low pixels to clip
               (default to 0.05).
   hirej:      If srejalg="sigclip", then the number of standard deviations
               above skyval to clip (default to 3.0).
               If srejalg="pclip", then fraction of high pixels to clip
               (default to 0.05).
   quick:      Set to use quick_photfrac (much faster)
   exact:      Set to use exact_photfrac (slower)

 OUTPUTS:
   skyval:     Sky value in counts per pixel.
   skyrms:     RMS of sky pixels about skyval, again in counts per pixel.
               This assumes that each pixel is independent.  The RMS
               is computed for only the values that remain after all the
               rejection iterations.
   skyerr:     The error in skyval assuming that each pixel is independent.
               This is skyrms divided by the square root of the number of
               pixels.

 PROCEDURES CALLED:
   djs_photfrac

 REVISION HISTORY:
   28-Nov-1996  Written by D. Schlegel, Durham.
   01-Jun-2000  Major revisions: change XYCEN to XCEN,YCEN; remove use
                of FITS headers; make IDL 5 complient (DJS).

(See pro/djsphot/djs_photsky.pro)


DJS_PLANCK

[Previous Routine] [Next Routine] [List of Routines]
     DJS_PLANCK returns the spectral radiance of a blackbody.

DESCRIPTION:  
    IDL function to return the spectral radiance of a blackbody,
    i.e. the Planck curve, in units of either MJy/steradian (I_nu)
    or watts/cm^2/steradian (nu_I_nu).
    The blackbody temperature and either frequency (in icm or GHz)
    or wavelength (in microns) are inputs to the function.  The
    routine also optionally returns the derivative with respect to 
    temperature, in units of MJy/sr/K or W/cm^2/sr/K.

CALLING SEQUENCE:  
     RESULT = DJS_PLANCK (temperature, nu_or_lambda [,dBdT] $
              [,UNITS=units], [/MJY], [/WCM2])

ARGUMENTS (I = input, O = output, [] = optional):
     RESULT        O   flt [arr]  Spectral radiance at each wavelength. 
                                  Units: W/cm^2/sr/K if /WCM2 specified
                                         MJy/sr      if /MJY specfied
     TEMPERATURE   I   flt        Temperature of blackbody, in K.
     NU_OR_LAMBDA  I   flt        Frequency or wavelength at which to 
                                  calculate spectrum. Units are as 
                                  specified with UNITS keyword.
     dBdT         [O]  flt [arr]  Derivative of Planck with respect to 
                                  temperature. 
     UNITS        [I]  str        'Microns', 'icm', or 'GHz' to 
                                  identify units of NU_OR_LAMBDA. Only 
                                  first character is required.  If 
                                  left out, default is 'microns'.
     /MJY          I   key        Sets output units to MJy/sr
     /WCM2         I   key        Sets output units to W/cm^2/sr

WARNINGS:
     1.  One of /MJY or /WCM2 MUST be specified.  
     2.  Routine gives incorrect results for T < 1 microKelvin and
            wavelengths shortward of 1.e-10 microns.  (So sue me).

EXAMPLE:
     To produce a 35 K spectrum in MJy/sr at 2, 4, 6, 8, 10 microns:

       wavelength = 2. + 2.*findgen(5)
       temp = 35.
       blackbody = djs_planck(temp, wavelength, units='micron', /mjy)

     One could also get back the derivative by including it in the
     call:
       blackbody = djs_planck(temp, wavelength, deriv, units='m', /mjy)
#
COMMON BLOCKS:
     None

PROCEDURE (AND OTHER PROGRAMMING NOTES): 
     Identifies units using the UNITS keyword, then converts the 
     supplied independent variable into microns to evaluate the 
     Planck function.  Uses Rayleigh-Jeans and Wien approximations 
     for the low- and high-frequency end, respectively.  Reference: 
     Allen, Astrophysical Quantities, for the Planck formula.

PERTINENT ALGORITHMS, LIBRARY CALLS, ETC.:
     None
  
MODIFICATION HISTORY:
    Written by Rich Isaacman, General Sciences Corp.  17 April 1991
    Revised by RBI 27 Jan 1992 to use updated fundamental constants 
         (SPR 9449)
    Revised by RBI 29 Jan 1992 to calculate derivatives only when 
         necessary
    Revised by RBI 3 Feb 1992 to redimension output to a scalar if only 
       a single wavelength is supplied  (SPR 9459)
    Revised by RBI 6 Mar 92 to return either MJy/sr or (!) W/cm^2/sr
    Revised by RBI 1 Jun 92 to fix single-wavelength failure when no
       derivative is requested (SPR 9738), and to use MESSAGE.
    RBI corrected error in derivative calculation SPR 9817 (17 Jul 92)
    RBI corrected error in Wien and RJ tails SPR 10392 (24 Dec 92)
	 but didn't get it quite right (Piper/Kryszak, 28-Dec-92)
    Revised by David Schlegel 10-Mar-1999 to allow calling with temperature
        and/or wavelength as a vector; converted to IDL-5; renamed from
        PLANCK() to DJS_PLANCK().  Note that this code was copied from
        the COBE analysis software.

 SPR 9616
.TITLE
 Routine DJS_PLANCK

(See pro/dust/djs_planck.pro)


DJS_PLOT

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

 PURPOSE:
   Modified version of PLOT

 CALLING SEQUENCE:
   djs_plot, [x,] y

 INPUT:
   x:
   y:

 OUTPUTS:

 COMMENTS:
   Pass COLOR, PSYM, and SYMSIZE to djs_oplot.

 PROCEDURES CALLED:
   djs_oplot
   TeXtoIDL()

 REVISION HISTORY:
   Written by D. Schlegel, 27 September 1997, Durham

(See pro/plot/djs_plot.pro)


DJS_PLOTLIMITBOX

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

 PURPOSE:
   Plot a box that bounds the given limits in X and Y.

 CALLING SEQUENCE:
   djs_plotlimitbox, xrange, yrange

 INPUT:
   xrange:    Range in X
   yrange:    Range in Y

 OUTPUTS:

 PROCEDURES CALLED:
   djs_oplot

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

(See pro/plot/djs_plotlimitbox.pro)


DJS_POSMOD

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

 PURPOSE:
   Return the non-negative modulus x % y, in the range [0,y).

 CALLING SEQUENCE:
   result = djs_posmod(x, y)

 INPUTS:
   xvalue

 OUTPUTS:
   result

 PROCEDURES CALLED:

 REVISION HISTORY:
   Written D. Schlegel, 15 May 1997, Durham

(See pro/math/djs_posmod.pro)


DJS_READCOL

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	DJS_READCOL
 PURPOSE:
	Read a free-format ASCII data file with columns of data into IDL 
	variables.  Lines of data not meeting the specified format (e.g. 
	comments) are ignored.  Columns may be separated by commas or spaces.
	Use READFMT to read a fixed-format ASCII file.   Use RDFLOAT for
	much faster I/O (but less flexibility).

 CALLING SEQUENCE:
	DJS_READCOL, name, v1, [ v2, v3, v4, v5, ...  v25 , 
             FORMAT = , /DEBUG ,  /SILENT , SKIPLINE = , NUMLINE = ]

 INPUTS:
	NAME - Name of ASCII data file, scalar string.  In VMS, an extension of 
		.DAT is assumed, if not supplied.

 OPTIONAL INPUT KEYWORDS:
	FORMAT - scalar string containing a letter specifying an IDL type
		for each column of data to be read.  Allowed letters are 
		A - string data, B - byte, D - double precision, F- floating 
		point, I - integer, L - longword, and X - skip a column.

		Columns without a specified format are assumed to be floating 
		point.  Examples of valid values of FMT are

	'A,B,I'        ;First column to read as 6 character string, then 
			1 column of byte data, 1 column integer data
	'L,L,L,L'       ;Four columns will be read as longword arrays.
	' '             ;All columns are floating point

	If a FORMAT keyword string is not supplied, then all columns are 
	assumed to be floating point.

	SILENT - Normally, READCOL will display each line that it skips over.
		If SILENT is set and non-zero then these messages will be 
		suppressed.
	DEBUG - If this keyword is non-zero, then additional information is
		 printed as READCOL attempts to read and interpret the file.
	SKIPLINE - Scalar specifying number of lines to skip at the top of file
		before reading.   Default is to start at the first line.
	NUMLINE - Scalar specifying number of lines in the file to read.  
		Default is to read the entire file

 OUTPUTS:
	V1,V2,V3,...V15 - IDL vectors to contain columns of data.
		Up to 25 columns may be read.  The type of the output vectors
		are as specified by FORMAT.

 EXAMPLES:
	Each row in a file POSITION.DAT contains a star name and 6 columns
	of data giving an RA and Dec in sexigesimal format.   Read into IDL 
	variables.     (NOTE: The star names must not contain internal spaces.)

	IDL> FMT = 'A,I,I,F,I,I,F'
	IDL> READCOL,'POSITION',F=FMT,name,hr,min,sec,deg,dmin,dsec  

	The HR,MIN,DEG, and DMIN variables will be integer vectors.

	Alternatively, all except the first column could be specified as
	floating point.

	IDL> READCOL,'POSITION',F='A',name,hr,min,sec,deg,dmin,dsec 

	To read just the variables HR,MIN,SEC
	IDL> READCOL,'POSITION',F='X,I,I,F',HR,MIN,SEC

 RESTRICTIONS:
	This procedure is designed for generality and not for speed.
	If a large ASCII file is to be read repeatedly, it may be worth
	writing a specialized reader.

	Columns to be read as strings must not contain spaces or commas, 
	since these are interpreted as column delimiters.    Use READFMT
	to read such files.

	Numeric values are converted to specified format.  For example,
	the value 0.13 read with an 'I' format will be converted to 0.

 PROCEDURES CALLED
	GETTOK(), NUMLINES(), REPCHR(), STRNUMBER(), ZPARCHECK

 REVISION HISTORY:
	Written         W. Landsman                 November, 1988
	Modified	     J. Bloch 			June, 1991
	(Fixed problem with over allocation of logical units.)
	Added SKIPLINE and NUMLINE keywords  W. Landsman    March 92
	Read a maximum of 25 cols.  Joan Isensee, Hughes STX Corp., 15-SEP-93.
	Call NUMLINES() function W. Lansdman          Feb. 1996

(See pro/misc/djs_readcol.pro)


DJS_READILINES()

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

 PURPOSE:
   Read selected lines of an ASCII file as one character string for each line.
   If NHEAD is specified and greater than zero, then that number
   of lines is read in first as header strings in HEAD.

 CALLING SEQUENCE:
   Data = djs_readilines( infile, indx=indx, [ nhead=nhead, Head=Head ] )

 INPUT:
   infile:      Input file name

 OPTIONAL INPUT:
   nhead:       Number of lines in header
   indx:        Line numbers to read (0-indexed); if not set, then
                default to reading all data lines in their current order.
                The indices start with 0 for the first data line.

 OUTPUTS:
   Data:        Array of strings, one for each data line

 OPTIONAL OUTPUTS:
   Head:        Array of strings, one for each header line

 PROCEDURES CALLED:

 REVISION HISTORY:
   Written by D. Schlegel, 29 May 1997, Durham

(See pro/misc/djs_readilines.pro)


DJS_READLINES()

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

 PURPOSE:
   Read an ASCII file as one character string for each line.
   If NHEAD is specified and greater than zero, then that number
   of lines is read in first as header strings in HEAD.

 CALLING SEQUENCE:
   Data = djs_readlines( infile, [ nhead=nhead, Head=Head ] )

 INPUT:
   infile:      Input file name

 OPTIONAL INPUT:
   nhead:       Number of lines in header

 OUTPUTS:
   Data:        Array of strings, one for each data line

 OPTIONAL OUTPUTS:
   Head:        Array of strings, one for each header line

 PROCEDURES CALLED:

 REVISION HISTORY:
   Written by D. Schlegel, 29 May 1997, Durham

(See pro/misc/djs_readlines.pro)


DJS_READMANY

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

 PURPOSE:
   Read many FITS 2-D images into a data cube.

 CALLING SEQUENCE:
   cube = djs_readmany( files, [hdr=] )

 INPUTS:
   files:      FITS file names (array of strings)

 OUTPUTS:
   cube:       Data cube with dimensions [NAXIS1, NAXIS2, nfile]

 OPTIONAL OUTPUTS:
   hdr:        Header for first image

 COMMENTS:
   Additional keywords are passed to the function READFITS().
   At present, the output image is always typed FLOAT.

 PROCEDURES CALLED:
   readfits()

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

(See pro/fits/djs_readmany.pro)


DJS_REJECT

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

 PURPOSE:
   Routine to reject points when doing an iterative fit to data.

 CALLING SEQUENCE:
   qdone = djs_reject(ydata, ymodel, outmask=, [ inmask=, $
    sigma=, invvar=, upper=, lower=, maxdev=, $
    maxrej=, groupsize=, groupdim=, grow=, /sticky ] )

 INPUTS:
   ydata      - Data values
   ymodel     - Fit values

 REQUIRED KEYWORDS:
   outmask    - Output mask, usually from previous calls to DJS_REJECT(),
                set =1 for good points, =0 for bad points.
                If /STICKY is set, then bad pixels accumulate in this mask
                between calls.  Otherwise, this mask is only used to determine
                if the rejection iterations are complete (e.g., to set QDONE).
                This keyword is required to be present, though need not be set.

 OPTIONAL KEYWORDS:
   inmask     - Input mask, set =1 for good points, =0 for bad points;
                bad points always have OUTMASK=0 also.
   sigma      - Errors in YDATA, used to reject based upon UPPER and LOWER.
   invvar     - Inverse variance in YDATA, used to reject based upon UPPER
                and LOWER; cannot specify both SIGMA and INVVAR.
   upper      - Reject points with YDATA > YMODEL + UPPER * SIGMA.
   lower      - Reject points with YDATA < YMODEL - LOWER * SIGMA.
   maxdev     - Reject points with abs(YDATA - YMODEL) > MAXDEV.
   maxrej     - Maximum number of points to reject this iteration.  If /STICKY
                is set, then this number of points can be rejected per
                iteration.  If either GROUPDIM or GROUPSIZE is a vector,
                then this quantity should be as well.
   groupdim   - Dimension along which to group the data; set to 1 to group
                along the 1st dimension, 2 for the 2nd dimension, etc.
                If YDATA has dimensions [100,200], then setting GROUPDIM=2
                is equivalent to grouping the data with GROUPSIZE=100.
                In either case, there are 200 groups, specified by [*,i].
   groupsize  - If this and MAXREJ are set, then reject a maximum of MAXREJ
                points per group of GROUPSIZE points.  If GROUPDIM is also
                set, then this specifies sub-groups within that.
   groupbadpix- Overrides the other groupsizes:  This associates each
                consectuive string of bad pixels as a group.  And maxrej
                is applied to each group of bad pixels.
                ***Unlikely to Work with Multi-Dimension Data***
   sticky     - If set, then points rejected in OUTMASK are kept rejected.
                Otherwise, if a fit (YMODEL) changes between iterations,
                points can alternate from being rejected to not rejected.
   grow       - Also nearest neighbors of rejected points (default 0)

 OUTPUTS:
   qdone      - Set to 0 if YMODEL is not set (usually the first call to
                this routine), or if the points marked as rejected in OUTMASK
                changes; set to 1 when the same points are rejected as from
                a previous call.

 OPTIONAL OUTPUTS:

 COMMENTS:
   If neither SIGMA nor INVVAR are set, then a scalar value of SIGMA is
   determined from the data points, excluding those points masked either
   with INMASK or OUTMASK.

   If the number of points rejected is limited with MAXREJ, then only the
   worst points are rejected.  The worst points are those with the largest
   deviation in terms of sigma (if UPPER or LOWER are set), or the largest
   number of multiples of MAXDEV from YMODEL (if MAXDEV is set).

   For example, if this is a 2-D array with GROUPDIM=1, then loop over each
   column of the data.  If GROUPDIM=2, then loop over each row.

   Note that UPPER, LOWER and MAXDEV can all be set.

 EXAMPLES:
   Construct an array of random numbers.  Reject high outliers, rejecting
   at most 1 point per iteration, for a maximum of 3 iterations:
     ydata = randomn(123,1000)
     ymodel = 0 * ydata
     sigma = 0 * ydata + 1
     outmask = 0
     maxiter = 3
     for iiter=0, maxiter do $
      if djs_reject(ydata, ymodel, outmask=outmask, upper=3, $
       maxrej=1, /sticky) then iiter = maxiter

   Usually, one would want to re-fit YMODEL between rejection iterations.
   The following does a weighted cubic fit to the data, but rejecting all
   points that deviate by more than 2-sigma from the fit.
     xdata = findgen(1000)
     ydata = randomn(123,1000)
     sigma = 0 * ydata + 1
     iiter = 0
     maxiter = 10
     outmask = 0 * ydata + 1 ; Begin with all points good
     while (NOT keyword_set(qdone) AND iiter LE maxiter) do begin
        qdone = djs_reject(ydata, ymodel, outmask=outmask, upper=2, lower=2)
        res = polyfitw(xdata, ydata, outmask/sigma^2, 2, ymodel)
        iiter = iiter + 1
     endwhile

 BUGS:
   Check case of no good points, or only 1 point with a value of 0
   (which might confuse keyword_set()). ???

 PROCEDURES CALLED:
   djs_laxisnum()

 REVISION HISTORY:
   30-Aug-2000  Written by D. Schlegel, Princeton
   11-Dec-2001  Slight changes to groupsize algorithm and add grow

(See pro/math/djs_reject.pro)


DJS_RGB_MAKE

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

 PURPOSE:
   Creates JPEG from three images or FITS files

 CALLING SEQUENCE:
   djs_rgb_make, rimage, gimage, bimage, [ name=, origin=, scales=, $
    nonlinearity=, satvalue=, rebinfactor=, overlay=, quality= ]

 INPUTS:
   rimage,gimage,bimage - Input 2-dimensional images or names of FITS files;
                 the dimensions of all images must agree

 OPTIONAL KEYWORDS:
   name        - Name of the output JPEG file; default to 'test.jpg'
   origin      - Subtract these zero-point values from the input images
                 before any other scalings; default to [0,0,0]
   scales      - Multiplicative scaling for each image; default to [1,1,1]
   nonlinearity- Nonlinearity constant, =0 for linear, =Inf for logarithmic;
                 default to 3
   satvalue    - Saturation value (before applying rescaling with SCALES, but
                 after applying ORIGIN) for which we should group pixels
                 into saturated "objects"; default to 100;
                 set to zero to disable
   rebinfactor - Integer by which to rebin pixels in the x and y
                 directions; eg, a rebinfactor of 2 halves the number
                 of pixels in each direction and quarters the total
                 number of pixels in the image
   overlay     - Optional overlay image, which must be dimensionsed as
                 [NX/REBINFACTOR,NY/REBINFACTOR,3]
   quality     - Quality for WRITE_JPEG; default to 75 per cent

 OUTPUTS:

 COMMENTS:
   This routine is based upon Nick Wherry's code NW_RGB_MAKE.
   The main difference is that saturated pixels are grouped into
   contiguous "objects", which are then assigned a color based upon
   the sum of all the pixels in that object.

   The nonlinearity function applied is
     RIMAGE = RIMAGE * asinh(b*r)/(b*r)
     GIMAGE = GIMAGE * asinh(b*r)/(b*r)
     BIMAGE = BIMAGE * asinh(b*r)/(b*r)
   where "b" is the input NONLINEARITY parameter and we define at each pixel
     r = (RIMAGE + GIMAGE + BIMAGE)

   Note that there are two types of saturation.  The first is that objects
   can be considered saturated if they exceed SATVALUE in any of the input
   images.  For such objects, contiguous saturated pixels are combined into
   one "object" with the mean color of all included pixels.
   The second type of saturation is of the RGB image.  This saturation is
   dealt with at the pixel level, and each pixel rescaled in all three images
   such that the brightest color hits the JPEG limit (of 255), but the
   colors (ratios between the RGB images) are preserved.

 EXAMPLES:

 BUGS:

 REVISION HISTORY:
   10-May-2004 - Written by D. Schlegel, Princeton;
                 based upon Nick Wherry's code NW_RGB_MAKE

(See pro/rgbcolor/djs_rgb_make.pro)


DJS_SELECTLINES

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

 PURPOSE:
   Select the line numbers specified by INDX of a file, and print either
   to the standard output or to another file.

   This is not yet optimized for very large files, as it will read in
   all of the requested lines (though not all the lines) into memory first.

 CALLING SEQUENCE:
   djs_selectlines, infile, [ indx=indx, nhead=nhead, outfile=outfile ]

 INPUTS:
   infile:      Input file name

 OPTIONAL INPUTS:
   indx:        Array of line numbers to select (0-indexed); default to all.
                The indices start with 0 for the first data line.
   nhead:       Number of lines in header
   outfile:     Output file name; if not set then print to terminal

 OUTPUTS:

 PROCEDURES CALLED:
   djs_readilines()

 REVISION HISTORY:
   Written by D. Schlegel, 25 September 1997, Durham

(See pro/misc/djs_selectlines.pro)


DJS_SFIT

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

 PURPOSE:
   Surface-fitting code to tabulated data (optionally with errors).

 CALLING SEQUENCE:
   acoeff = djs_sfit( fval, xval, yval, degreex, degreey, $
    [ sqivar=, yfit= ] )

 INPUTS:
   fval       - Function values at XVAL,YVAL.
   xval       - X coordinate values
   yval       - Y coordinate values
   degreex    - Degree of polynomial fit in X; 1 for linear, 2 for quadratic
   degreey    - Degree of polynomial fit in Y; 1 for linear, 2 for quadratic

 OPTIONAL INPUTS:
   sqivar     - Inverse sigma, which are the weights

 OUTPUTS:
   acoeff     - Fit coefficients as [DEGREEX+1,DEGREEY+1] array

 OPTIONAL OUTPUTS:
   yfit       - Fit values

 COMMENTS:

 EXAMPLES:
   Create a random 2-dimensional field with a gradient in the X direction,
   and fit to a quadratic function in both X and Y:
     IDL> xval = dindgen(100) # replicate(1,100) / 100.
     IDL> yval = replicate(1,100) # dindgen(100) / 100.
     IDL> image = smooth(randomu(1234,100,100),11,/edge) + 0.2*xval^2
     IDL> acoeff = djs_sfit(image,xval,yval,2,2,yfit=yfit)
   Display the original image, and then the residual between that
   image and the fit:
     IDL> atv, image
     IDL> atv, image - yfit

 BUGS:

 PROCEDURES CALLED:

 INTERNAL SUPPORT ROUTINS:

 REVISION HISTORY:
   25-Oct-2002  Written by David Schlegel, Princeton.

(See pro/image/djs_sfit.pro)


DJS_UNLOCKFILE

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

 PURPOSE:
   Unlock a file if locked with DJS_LOCKFILE().

 CALLING SEQUENCE:
   djs_unlockfile, filename, [lun= ]

 INPUT:
   filename:   File name

 OPTIONAL INPUTS:
   lun:        If this argument exists, then close the file associated
               with this LUN number.  This is useful if FILENAME has
               been opened with DJS_LOCKFILE().

 OUTPUTS:

 COMMENTS:
   We use a lock file, which is either a symbolic link or a file with
   a single byte written to it, to indicate that FILENAME has been
   locked by DJS_LOCKFILE().  This routine deletes that file.

 BUGS:

 PROCEDURES CALLED:

 REVISION HISTORY:
   30-Apr-2000  Written by D. Schlegel, APO

(See pro/misc/djs_unlockfile.pro)


DJS_XYOUTS

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

 PURPOSE:
   Modified version of XYOUTS

 CALLING SEQUENCE:
   djs_xyouts

 INPUT:

 OUTPUTS:

 COMMENTS:
   Allows COLOR, and CHARSIZE to be vectors.
   Also allows COLOR to be string descriptions of eight possible colors.
   If string descriptors are used, then load a basic 8-color color table.

 PROCEDURES CALLED:
   djs_icolor()
   TeXtoIDL()

 REVISION HISTORY:
   16-Apr-2000 Written by D. Schlegel, Princeton

(See pro/plot/djs_xyouts.pro)


DLOOKBACKDZ

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   dlookbackdz
 PURPOSE:
   Compute differential lookback time dt/dz (for c/H_0=1).
 CALLING SEQUENCE:
   dtdz= dlookbackdz(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:
   differential lookback time per unit redshift, units of the Hubble time 1/H_0
 COMMENTS:
 BUGS:
   May not work for pathological parts of the OmegaM-OmegaL plane.
 EXAMPLES:
 PROCEDURES CALLED:
 REVISION HISTORY:
   2001-May-12  Written by Hogg (NYU)

(See pro/cosmography/dlookbackdz.pro)


DOTPRODUCT_SPHERE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   dotproduct_sphere
 PURPOSE:
   Compute the cosign of the angle between two unit vectors on the
   sphere.  This formula is from Jackson, pg 101.  (Or see my notes
   of 6 Dec 92).  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 the dot product between RA and DEC coordinates,
   pass the following arguments (in radians):
     RA1, DEC1+90, RA2, DEC2+90

 CALLING SEQUENCE:
   dotproduct_sphere( phi1, theta1, phi2, theta2, [/degrees, /hrdeg] )

 INPUTS:
   phi1:       RA of first point(s) in radians
   theta1:     DEC of first point(s) in radians
   phi2:       RA of second point(s) in radians
   theta2:     DEC of second point(s) in radians

 OPTIONAL INPUTS:
   degrees:    If set, then all angles are in degrees
   hrdeg:      If se, then RA angles in hours and DEC angles in degrees

 OUTPUTS:
   cosgamma:   Cosine of the angle between the two positions

(See pro/coord/dotproduct_sphere.pro)


DPF_NEST2RING

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

 PURPOSE:
   Convert healpix nested pixel number to ring pixel number

 CALLING SEQUENCE:
   dpf_nest2ring, nside, ipnest, ipring

 INPUTS:
   nside  - healpix nside
   ipnest - nested pixel number

 OUTPUTS:
   ipring - ring pixel number

 EXAMPLES:
   
 COMMENTS:
   Usage is same as Hivon's nest2ring, only this is 4 times as fast.

 REVISION HISTORY:
   2003-Dec-04  Written by Douglas Finkbeiner, Princeton

(See pro/healpix/dpf_nest2ring.pro)


DPF_PIX2ANG_NEST

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

 PURPOSE:
   Compute coordinates for HEALPix pixel numbers, nested order

 CALLING SEQUENCE:
   dpf_pix2ang_nest, nside, ipix, theta, phi, double=double

 INPUTS:
   nside   - healpix nside
   ipix    - pixel numbers
 
 OUTPUTS:
   theta   - angle from north pole [radians]
   phi     - longitude angle [radians]

 EXAMPLES:
   
 COMMENTS:
   Calling syntax is same as pix2ang_nest and agrees to machine 
     precision. 
   This routine has somewhat better performance when called for the
     full sky than pix2ang_nest. 
   
 REVISION HISTORY:
   2004-Jun-08  Written by Douglas Finkbeiner, Princeton

(See pro/healpix/dpf_pix2ang_nest.pro)


DPF_PIX2ANG_RING

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

 PURPOSE:
   Compute coordinates for HEALPix pixel numbers

 CALLING SEQUENCE:
   dpf_pix2ang_ring, nside, ipix, theta, phi, double=double

 INPUTS:
   nside   - healpix nside
   ipix    - pixel numbers
 
 OUTPUTS:
   theta   - angle from north pole [radians]
   phi     - longitude angle [radians]

 EXAMPLES:
   
 COMMENTS:
   Calling syntax is same as pix2ang_ring and agrees to machine 
     precision. 
   This routine has somewhat better performance when called for the
     full sky than pix2ang_ring. 
   
 REVISION HISTORY:
   2003-Dec-06  Written by Douglas Finkbeiner, Princeton

(See pro/healpix/dpf_pix2ang_ring.pro)


DPROPDISDZ

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   dpropdisdz
 PURPOSE:
   Compute differential proper line-of-sight distances (for c/H_0=1).
 CALLING SEQUENCE:
   dDdz= dpropdisdz(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:
   differential proper 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:
   dcomdisdz()
 REVISION HISTORY:
   25-Jun-2000  Written by Hogg (IAS)

(See pro/cosmography/dpropdisdz.pro)


DPROPMOTDISDZ

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   dpropmotdisdz
 PURPOSE:
   Compute differential proper motion distance dD/dz for c=H_0=1.
 CALLING SEQUENCE:
   dDdz= dpropmotdisdz(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:
   differential proper motion 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:
   2001-Mar-12  Written by Hogg (NYU)

(See pro/cosmography/dpropmotdisdz.pro)


DUSTPLOT

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

 PURPOSE:
   Make a PostScript plot of the dust maps in a rectalinear projection.

 CALLING SEQUENCE:
   dustplot

 INPUTS:

 OPTIONAL INPUTS:
   latrange:   Latitude range; default to [-30,30]
   lonrange:   Longitude range; default to [-30,30]
   rangestr:   3-element string with plot limits and units;
               default to ['0.0', '1.0', 'A(B)']
               Valid entries for RANGESTR[2] are:
                  A(B)
                  A(I)
                  E(B-V)
                  I100
                  T
   csys:       Coordinate system:
               'gal': Galactic coordinates (default)
               'equ1950': Equatorial coordinates, epoch 1995
               'equ2000': Equatorial coordinates, epoch 2000
               'ecl': Ecliptic coordinates
   tspace:     Tick spacing for grid overlay; default to 5 deg
   pixpdeg:    Pixels per degree; default to 500 pixels across the image
   filename:   Output file name; default to "test.ps"
   encap:      If set, then produce encapsulated PostScript
   ctnum:      Color table number; default to 23 (Purple-Red + Stripes)
   invert:     Invert color map
   colorbar:   Plot color bar on bottom of page
   nonames:    If set, then disable the title string on the top,
               and our names on the bottom

 OUTPUTS:

 PROCEDURES CALLED:
   adstring()
   djs_laxisgen()
   dust_getval()
   euler
   jprecess

 REVISION HISTORY:
   Written D. Schlegel, 18 June 1999, Princeton

(See pro/dust/dustplot.pro)


DUST_GETMAP

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

 PURPOSE:
   Reproject dust map to projection described by a FITS header

 CALLING SEQUENCE:
   image=dust_getmap(hdr, mapname, ipath=, bhpath=)

 INPUTS:
   hdr      - FITS astrometric header.  Must be parsed properly by extast
   mapname  - one of the following (case insensitive)
               BH  : Burstein-Heiles 4*E(B-V)
               I100: 100-micron map in MJy/Sr
               X   : X-map, temperature-correction factor
               T   : Temperature map in degrees Kelvin for n=2 emissivity
               IX  : Temperature-corrected 100-micron map in MJy/Sr
               Ebv : E(B-V) in magnitudes
               mask: 8-bit mask
   
 OPTIONAL INPUTS:
   ipath    - path for dust maps; default is $DUST_DIR/maps
   bhpath   - path name for BH maps
 
 OUTPUTS:
   image    - reprojected dust/IRAS/whatever image
   
 EXAMPLES:
   To read in an halpha map, then generate a dust map in the same
    projection: 

   halpha = readfits('Halpha.fits', hdr)
   dust   = dust_getmap(hdr, 'Ebv')

 COMMENTS:
   Params ipath and bhpath are passed to dust_getval. 
   Keywords /noloop and /interp are always set. 
   The other keywords of dust_getval have no meaning in this
     context. 
   
 REVISION HISTORY:
   2003-Jan-30   Written by Douglas Finkbeiner, Princeton
   2003-Feb-07   Precess headers if necessary

(See pro/dust/dust_getmap.pro)


DUST_GETVAL

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

 PURPOSE:
   Read values from BH files or our dust maps.

 CALLING SEQUENCE:
   value = dust_getval( [ gall, galb, infile=infile, skipline=skipline, $
    outfile=outfile, map=map, interp=interp, noloop=noloop, verbose=verbose, $
    ipath=ipath, bhpath=bhpath ] )

 INPUTS:

 OPTIONAL INPUTS:
   gall:       Galactic longitude(s) in degrees
   galb:       Galactic latitude(s) in degrees
   map:        Set to one of the following (default is 'Ebv'):
               BH  : Burstein-Heiles 4*E(B-V)
               I100: 100-micron map in MJy/Sr
               X   : X-map, temperature-correction factor
               T   : Temperature map in degrees Kelvin for n=2 emissivity
               IX  : Temperature-corrected 100-micron map in MJy/Sr
               Ebv : E(B-V) in magnitudes
               mask: 8-bit mask
   infile:     If set, then read GALL and GALB from this file
   skipline:   Number of lines to skip at the top of the input file
   outfile:    If set, then write results to this file
   interp:     Set this flag to return a linearly interpolated value
               from the 4 nearest pixels.
               This is disabled if map='mask'.
   noloop:     Set this flag to read all values at once without a FOR loop.
               This is a faster option for reading a large number of values,
               but requires reading an entire FITS image into memory.
               (Actually, the smallest possible sub-image is read.)
   verbose:    Set this flag for verbose output, printing pixel coordinates
               and map values.  Setting NOLOOP disables this option.
   ipath:      Path name for dust maps; default to path set by the
               environment variable $DUST_DIR/maps, or to the current
               directory.
   bhpath:     Path name for BH maps

 OUTPUTS:
   value:      Value(s) from Lambert-projection maps.

 COMMENTS:
   These data are based upon the following paper:
   "Maps of Dust IR Emission for Use in Estimation of Reddening
   and CMBR Foregrounds", Schlegel, D., Finkbeiner, D., & Davis, M.,
   ApJ, 1998, 500, 525.

   Either the coordinates GALL and GALB must be set, or these coordinates
   must exist in the file INFILE.  Output is written to the variable VALUE
   and/or the file OUTFILE.

 EXAMPLES:
   Read the reddening value E(B-V) at Galactic (l,b)=(12,+34.5), 
   interpolating from the nearest 4 pixels, and return result in VALUE.
   > value = dust_getval(12, 34.5, /interp)

   Read the temperature map at positions listed in the file 'dave.in',
   interpolating from the nearest 4 pixels, and output to file 'dave.out'.
   The path name for the temperature maps is '/u/schlegel/'.
   > value = dust_getval(map='T', ipath='/u/schlegel/', /interp, $
     infile='dave.in', outfile='dave.out')

 DATA FILES FOR SFD MAPS:
   SFD_dust_4096_ngp.fits
   SFD_dust_4096_sgp.fits
   SFD_i100_4096_ngp.fits
   SFD_i100_4096_sgp.fits
   SFD_mask_4096_ngp.fits
   SFD_mask_4096_sgp.fits
   SFD_temp_ngp.fits
   SFD_temp_sgp.fits
   SFD_xmap_ngp.fits
   SFD_xmap_sgp.fits

 DATA FILES FOR BH MAPS:
   hinorth.dat
   hisouth.dat
   rednorth.dat
   redsouth.dat

 PROCEDURES CALLED:
   bh_rdfort()
   djs_int2bin()
   readcol
   wcs_getval()

 REVISION HISTORY:
   25-Sep-1997  Written by David Schlegel, Durham
   19-Jan-1998  DJS - Modified for general release.
   30-Mar-1998  DJS - Modified to read SGP mask file for b<0, since it was
                incorrectly reading the NGP mask.
   19-May-1998  DJS - Subscripts modified to IDL 5 convention.
   30-Jul-1998  DJS - Added default file path names for any users at Princeton
                or at Berkeley.
   18-Mar-1999  DJS - Allow call with GALL=0 or GALB=0.
   31-Mar-1999  DJS - Modified to use wcs_getval() instead of lambert_getval()

(See pro/dust/dust_getval.pro)


DUST_INTFILTER

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

 PURPOSE:
   Integrate the extinction curve over a given source function + filter curve.

 CALLING SEQUENCE:
   avec = dust_intfilter( ixval, ffilename=, sfilename=, [ atmfilename=, $
    rv=, anorm=, dlam=, zsource=, /debug  ] )

 INPUTS:
   ixval      - Temperature-corrected 100-micron flux (IX) from SFD maps,
                in MJy/sr (scalar or vector).

 REQUIRED KEYWORDS:
   ffilename  - ASCII file with wavelengths in Ang (1st column) and throughput
                (2nd column) for the filter response curve.
   sfilename  - ASCII file with wavelengths in Ang (1st column) and flux in
                f_lambda (2nd column) for the source function.  Note that
                since we assume f_lambda (flux/Ang), we multiply this
                by one power of the wavelength to convert to a flux in
                photon number per Angstrom.

 OPTIONAL KEYWORDS:
   atmfilename- ASCII file with wavelengths in Ang (1st column) and magnitudes
                of atmospheric extinction (2nd column).  If specified,
                then the filter response is multiplied by 10^(-ATM/2.5).
   rv         - Extinction curve parameter R_V; default to 3.1.
   anorm      - Normalization factor for multiplying IX to obtain
                extinction at 1 micron; default to SFD normalization
                of (1.319)*(0.0184) mag/(MJy/sr).
   dlam       - Spacing of numeric integration in Angstroms; default
                to 1 Ang.
   zsource    - Redshift of source; default to 0.
   debug      - If set, then make debugging plots with SPLOT.

 OUTPUTS:
   avec       - Extinction in magnitudes (same dimensions as IXVAL).

 COMMENTS:
   The Galactic extinction curve is that from O'Donnell (1994)
   and Cardelli, Clayton & Mathis (1989).

   The integrations (and optional debugging plots) are limited to
   the wavelength range within which the filter curve is positive-valued.

   The filter curve, source function, and atmospheric extinction curve
   are cached between calls.  If the same file is specified on a
   subsequent call, then those cached values are used.

 PROCEDURES CALLED:
   ext_odonnell()
   numlines()
   readcol

 DATA FILES:

 REVISION HISTORY:
   01-Dec-2002  Written by D. Schlegel, Princeton

(See pro/dust/dust_intfilter.pro)


DUST_SDSSFILTER

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

 PURPOSE:
   Integrate the extinction curve over a selection of source fuctions and
   the SDSS filters.

 CALLING SEQUENCE:
   aval = dust_sdssfilter( ixval, [ source=, zsource=, rv=, anorm=, dlam=, /debug ] )

 INPUTS:
   ixval      - Temperature-corrected 100-micron flux (IX) from SFD maps,
                in MJy/sr [NDATA].

 OPTIONAL INPUTS:
   source     - Source function.  Options are:
                  'Fstar': Hot F-star model from Kurucz at T_eff=7000K
                  'Galaxy': SDSS mean galaxy spectrum
                  'QSO': SDSS mean QSO spectrum
                Default to 'Galaxy'.
   zsource    - Redshift of source; default to 0.
   rv         - Extinction curve parameter R_V; default to 3.1.
   anorm      - Normalization factor for multiplying IX to obtain
                extinction at 1 micron; default to SFD normalization
                of (1.319)*(0.0184) mag/(MJy/sr).
   dlam       - Spacing of numeric integration in Angstroms; default
                to 1 Ang.
   debug      - If set, then make debugging plots with SPLOT.
   old        - If set, then use the original SDSS filters curves
                used for the SFD paper.

 OUTPUTS:
   avec       - Extinction in magnitudes [5,NDATA].

 COMMENTS:

 EXAMPLES:
   Given a set of Galactic coordinates L,B, evaluate the SFD-predicted
   extinction in the 5 SDSS filters for a source with the spectrum of an F star:
     IDL> aval = dust_sdssfilter(dust_getval(l, b, map='IX', /interp), source='Fstar')

   Compare the predicted extinction at a given dust value of IX=10. for two
   different values of R_V (5.5 vs. 3.1):
     IDL> print, dust_sdssfilter(10., rv=5.5) / dust_sdssfilter(10.)

 PROCEDURES CALLED:
   dust_intfilter()
   mrdfits()
   sxpar()

 DATA FILES:
   $IDLUTILS_DIR/data/filters/kurucz_fstar.dat
   $IDLUTILS_DIR/data/filters/kpno_atmos.dat
   $IDLUTILS_DIR/data/filters/sdss_1994_u_noatm.dat
   $IDLUTILS_DIR/data/filters/sdss_1994_g_noatm.dat
   $IDLUTILS_DIR/data/filters/sdss_1994_r_noatm.dat
   $IDLUTILS_DIR/data/filters/sdss_1994_i_noatm.dat
   $IDLUTILS_DIR/data/filters/sdss_1994_z_noatm.dat
   $IDLUTILS_DIR/data/filters/sdss_jun2001_u_atm.dat
   $IDLUTILS_DIR/data/filters/sdss_jun2001_g_atm.dat
   $IDLUTILS_DIR/data/filters/sdss_jun2001_r_atm.dat
   $IDLUTILS_DIR/data/filters/sdss_jun2001_i_atm.dat
   $IDLUTILS_DIR/data/filters/sdss_jun2001_z_atm.dat
   $IDLUTILS_DIR/data/filters/sdss_meangalaxy_52223.dat

 DATA FILES:

 REVISION HISTORY:
   01-Dec-2002  Written by D. Schlegel, Princeton

(See pro/dust/dust_sdssfilter.pro)


EFC2D

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

 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:
   
   coeff = efc2d(x, y, z, invsig, npoly, nbkptord, fullbkpt)

 INPUTS:
   x          - data x values
   y          - data y values
   z          - data z values
   invsig     - inverse error array of y
   npoly      - Order of polynomial (as a function of y)
   nbkptord   - Order of b-splines (4 is cubic)
   fullbkpt   - Breakpoint vector returned by efc

 RETURNS:
   coeff      - B-spline coefficients calculated by efc

 OUTPUTS:

 OPTIONAL KEYWORDS:

 OPTIONAL OUTPUTS:

 COMMENTS:
	This IDL proc is an extension of efcmn

 EXAMPLES:

   x = findgen(100)
   y = randomu(200, 100, /normal)
   zmodel = 10.0*sin(x/10.0) + y
   z = zmodel + randomu(100,100,/normal)
   invsig = fltarr(100) + 1.0
   fullbkpt = [-3.0,-2.0,-1.0,findgen(11)*10.0,101.0,102.0,103.0]
   npoly = 2L
   nbkptord = 4L
   coeff = efc2d(x, y, z, invsig, npoly, nbkptord, fullbkpt)

   zfit = bvalu2d(x, y, fullbkpt, coeff)


 PROCEDURES CALLED:

   efc_idl in src/slatec/idlwrapper.c
         which wraps to efc.o in libslatecidl.so

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

(See pro/slatec/efc2d.pro)


EFCMN

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

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

 CALLING SEQUENCE:
   
   coeff = efcmn(x, y, invsig, nord, fullbkpt)

 INPUTS:
   x          - data x values
   y          - data y values
   invsig     - inverse error array of y
   nord       - Order of b-splines (default 4: cubic)
   fullbkpt       - Breakpoint vector returned by efc

 RETURNS:
   coeff      - B-spline coefficients calculated by efc

 OUTPUTS:

 OPTIONAL KEYWORDS:

 OPTIONAL OUTPUTS:

 COMMENTS:
	This IDL proc mimics efc.f

 EXAMPLES:

   x = findgen(100)
   y = randomu(100,100)
   invsig = fltarr(100) + 1.0
   fullbkpt = [-3.0,-2.0,-1.0,findgen(12)*10.0,101.0,102.0,103.0]
   nord = 4L

   coeff = efcmn(x, y, invsig, nord, fullbkpt)

   xfit = findgen(10)*10.0
   yfit = slatec_bvalu(xfit, fullbkpt, coeff)


 PROCEDURES CALLED:

   efc_idl in src/slatec/idlwrapper.c
         which wraps to efc.o in libslatecidl.so

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

(See pro/slatec/efcmn.pro)


EMBED_STAMP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   embed_stamp
 PURPOSE:
   Add to one image the parts which are overlapped by a second image 
 CALLING SEQUENCE:
   embed_stamp,full_image,stamp_image,xlo,ylo
 INPUTS:
   full_image - [full_nx, full_ny] image to add to
   stamp_image - [stamp_nx, stamp_ny] image to add by
   xlo, ylo - position in full_image of lower left corner of lower left
              pixel of stamp
 OUTPUTS:
   full_image - resulting image
 REVISION HISTORY:
   2003-01-20  Written - Blanton

(See pro/image/embed_stamp.pro)


EM_PCA

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
    em_pca
 PURPOSE: (one line)
    Perform E-M PCA to get first k principal components
 DESCRIPTION:
    Uses Sam Roweis' Expectation Maximization version of PCA to
    efficiently find the first k principal components for a
    distribution in p (>k) dimensions. The procedure guesses an
    initial set of eigenvectors (stored the in [p,k] dimensional
    matrix "eigenvec") and applies the following iteration to the
    [p,N] dimensional "data":

         hidden= ( eigenvec^T . eigenvec )^{-1} . eigenvec^T . data
         eigenvec= data . hidden^T . (hidden . hidden^T)^{-1}

    From:
    Neural Information Processing Systems 10 (NIPS'97) pp.626-632
    available at:
    http://www.cs.toronto.edu/~roweis/papers/empca.ps.gz
 CATEGORY:
    Mathematical
 CALLING SEQUENCE:
    em_pca, data, k, eigenvec, hidden [, tol=, maxiter=, niter=, /verbose]
 INPUTS:
    data - [p,N] data to be PCAed
    k - number of eigenvectors desired (<p)
 OPTIONAL INPUT PARAMETERS:
    tol - tolerance of convergence (default 0.)
    maxiter - maximum number of iterations (default 20)
 KEYWORD PARAMETERS:
    /verbose - verbose output
    /nofix - don't do the final real PCA
 OUTPUTS:
    eigenvec - [p,k] matrix of k leading eigenvectors
    hidden - [k] matrix of "hidden" variables (the lower dimensional
             representation of the data)
 OPTIONAL OUTPUTS:
    niter - number of iterations used
 COMMON BLOCKS:
 SIDE EFFECTS:
 BUGS:
    Somewhat untested.
 RESTRICTIONS:
    Does not implement Sam's Sensible-PCA procedure
 PROCEDURE:
 MODIFICATION HISTORY:
    2003-01-26 - Written by Michael Blanton (NYU)

(See pro/math/em_pca.pro)


EM_PCA_SPARSE_MATRIX

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
    em_pca_sparse_matrix
 PURPOSE: (one line)
    Perform E-M PCA to get first k principal components of large sparse matrix
 DESCRIPTION:
    Uses Sam Roweis's algorithm (described in em_pca.pro in detail)
    but takes an initial sparse matrix rather than a data set as
    input. (in the lle_sm format)
 CATEGORY:
    Mathematical
 CALLING SEQUENCE:
    em_pca_sparse_matrix, matrix, k, eigenvec, hidden [, tol=, $
       maxiter=, niter=, /verbose]
 INPUTS:
    matrix - sparse matrix to be PCAd
    k - number of eigenvectors desired (<p)
 OPTIONAL INPUT PARAMETERS:
    tol - tolerance of convergence (default 0.)
    maxiter - maximum number of iterations (default 20)
 KEYWORD PARAMETERS:
    /verbose - verbose output
    /nofix - don't do the final real PCA
 OUTPUTS:
    eigenvec - [p,k] matrix of k leading eigenvectors
 OPTIONAL OUTPUTS:
    niter - number of iterations used
 COMMON BLOCKS:
 SIDE EFFECTS:
 BUGS:
    not completed yet
 RESTRICTIONS:
    Does not implement Sam's Sensible-PCA procedure
 PROCEDURE:
 MODIFICATION HISTORY:
    2003-01-26 - Written by Michael Blanton (NYU)

(See pro/math/em_pca_sparse_matrix.pro)


ERROR_MESSAGE

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

 PURPOSE:

    The purpose of this function  is to have a device-independent
    error messaging function. The error message is reported
    to the user by using DIALOG_MESSAGE if widgets are
    supported and MESSAGE otherwise.

    In general, the ERROR_MESSAGE function is not called directly.
    Rather, it is used in a CATCH error handler. Errors are thrown
    to ERROR_MESSAGE with the MESSAGE command. A typical CATCH error
    handler is shown below.

       Catch, theError
       IF theError NE 0 THEN BEGIN
          Catch, /Cancel
          ok = Error_Message(/Traceback, /Error)
          RETURN
       ENDIF

    Error messages would get into the ERROR_MESSAGE function by
    throwing an error with the MESSAGE command, like this:

       IF test NE 1 THEN Message, 'The test failed.'

 AUTHOR:

   FANNING SOFTWARE CONSULTING
   David Fanning, Ph.D.
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: davidf@dfanning.com
   Coyote's Guide to IDL Programming: http://www.dfanning.com/

 CATEGORY:

    Utility.

 CALLING SEQUENCE:

    ok = Error_Message(the_Error_Message)

 INPUTS:

    the_Error_Message: This is a string argument containing the error
       message you want reported. If undefined, this variable is set
       to the string in the !Error_State.Msg system variable.

 KEYWORDS:

    ERROR: Set this keyword to cause Dialog_Message to use the ERROR
       reporting dialog. Note that a bug in IDL causes the ERROR dialog
       to be used whether this keyword is set to 0 or 1!

    INFORMATIONAL: Set this keyword to cause Dialog_Message to use the
       INFORMATION dialog instead of the WARNING dialog. Note that a bug
       in IDL causes the ERROR dialog to be used if this keyword is set to 0!

    TITLE: Set this keyword to the title of the DIALOG_MESSAGE window. By
       default the keyword is set to 'System Error' unless !ERROR_STATE.NAME
       equals "IDL_M_USER_ERR", in which case it is set to "Trapped Error'.

    TRACEBACK: Setting this keyword results in an error traceback
       being printed to standard output with the PRINT command. Set to
       1 (ON) by default. Use TRACEBACK=0 to turn this functionality off.

 OUTPUTS:

    Currently the only output from the function is the string "OK".

 RESTRICTIONS:

    The WARNING Dialog_Message dialog is used by default.

 EXAMPLE:

    To handle an undefined variable error:

    IF N_Elements(variable) EQ 0 THEN $
       ok = Error_Message('Variable is undefined', /Traceback)

 MODIFICATION HISTORY:

    Written by: David W. Fanning, 27 April 1999.
    Added the calling routine's name in the message and NoName keyword. 31 Jan 2000. DWF.
    Added _Extra keyword. 10 February 2000. DWF.
    Forgot to add _Extra everywhere. Fixed for MAIN errors. 8 AUG 2000. DWF.
    Adding call routine's name to Traceback Report. 8 AUG 2000. DWF.
    Added ERROR, INFORMATIONAL, and TITLE keywords. 19 SEP 2002. DWF.
    Removed the requirement that you use the NONAME keyword with the MESSAGE
      command when generating user-trapped errors. 19 SEP 2002. DWF.
    Added distinctions between trapped errors (errors generated with the
      MESSAGE command) and IDL system errors. Note that if you call ERROR_MESSAGE
      directly, then the state of the !ERROR_STATE.NAME variable is set
      to the *last* error generated. It is better to access ERROR_MESSAGE
      indirectly in a Catch error handler from the MESSAGE command. 19 SEP 2002. DWF.

(See pro/psconfig/error_message.pro)


ETALAMBDA_TO_RADEC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   etalambda_to_radec
 PURPOSE:
   convert from eta, lambda (SDSS survey coordinates) to RA, Dec
 CALLING SEQUENCE:
   etalambda_to_radec, eta,lambda,ra,dec
 INPUTS:
   eta     SDSS survey coordinate eta (deg)
   lambda  SDSS survey coordinate lambda (deg)
 OPTIONAL OUTPUTS:
   ra      RA (deg), J2000
   dec     Dec (deg), J2000
 BUGS:
   Location of the survey center is hard-wired, not read from astrotools.
 REVISION HISTORY:
   2001-Jul-21  written by Hogg (NYU)
   2002-Oct-04  modified by Blanton (NYU)

(See pro/coord/etalambda_to_radec.pro)


ETA_TO_STRIPE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   eta_to_stripe
 PURPOSE:
   find the stripe which an eta value is in; hardwired to what astrotools 
   v5_6 does; except it uses lambda to deal with southern stripes
 CALLING SEQUENCE:
   etalambda_to_stripe, eta, stripe
 INPUTS:
   eta      value of eta (survey lat) in deg
   lambda   value of lambda (survey long) in deg
 OUTPUTS:
   stripe   Survey Stripe #
 BUGS:
   Location of the survey center is hard-wired, not read from astrotools.
 REVISION HISTORY:
   2002-Feb-20  written by Blanton (NYU)

(See pro/coord/eta_to_stripe.pro)


EULER_2000

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
     EULER_2000
 PURPOSE:
     Transform between Galactic, celestial, and ecliptic coordinates.
 EXPLANATION:
     Use the procedure ASTRO to use this routine interactively

 CALLING SEQUENCE:
      EULER_2000, AI, BI, AO, BO, [ SELECT, /FK4 ] 

 INPUTS:
       AI - Input Longitude in DEGREES, scalar or vector.  If only two 
               parameters are supplied, then  AI and BI will be modified to 
               contain the output longitude and latitude.
       BI - Input Latitude in DEGREES

 OPTIONAL INPUT:
       SELECT - Integer (1-6) specifying type of coordinate transformation.  

      SELECT   From          To        |   SELECT      From            To
       1     RA-Dec (2000)  Galactic   |     4       Ecliptic      RA-Dec    
       2     Galactic       RA-DEC     |     5       Ecliptic      Galactic  
       3     RA-Dec         Ecliptic   |     6       Galactic      Ecliptic  

      If omitted, program will prompt for the value of SELECT
      Celestial coordinates (RA, Dec) should be given in equinox J2000 
      unless the /FK4 keyword is set.
 OUTPUTS:
       AO - Output Longitude in DEGREES
       BO - Output Latitude in DEGREES

 INPUT KEYWORD:
       /FK4 - If this keyword is set and non-zero, then input and output 
             celestial and ecliptic coordinates should be given in equinox 
             B1950.

 NOTES:
       EULER was changed in December 1998 to use J2000 coordinates as the 
       default, ** and may be incompatible with earlier versions***.
 REVISION HISTORY:
       Written W. Landsman,  February 1987
       Adapted from Fortran by Daryl Yentis NRL
       Converted to IDL V5.0   W. Landsman   September 1997
       Made J2000 the default, added /FK4 keyword  W. Landsman December 1998
       Renamed to euler_2000.pro by D. Finkbeiner 15 Apr 1999
       -------------------
       Memory managment improved 16 April 1999 - D. Finkbeiner. 
        - now makes heavy use of "temporary" function to deallocate
          arrays
        - arguments of atan() are now floats, since atan is the
          limiting factor on memory usage, and numerical precision is
          not such a big deal for atan. 
        - These changes reduce memory usage by 58%, but cause
          differences of up to .03 arcsec relative to the standard
          version of euler.  If you are interested in higher
          precision than this, DO NOT USE THIS ROUTINE!
       -------------------

(See pro/coord/euler_2000_fast.pro)


EXACT_PHOTFRAC

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

 PURPOSE:
   Create list of contribution of pixels to circular or annular aperture

 CALLING SEQUENCE:
   exact_photfrac, xcen, ycen, radius [, fracs=, xdimen=, ydimen=, ]
           pixnum=, xpixnum=, ypixnum= ]

 INPUTS:
   xcen - X center(s) (LONG) 
   ycen - Y center(s) (LONG) 
   radius - radius of aperture (if 2-element array, inner and outer
            radii of annulus) 

 OPTIONAL INPUTS:
   xdimen - number of pixels upon a side to output [default - radius+1]
   ydimen - number of pixels upon a side to output [default - radius+1]
   safefactor - we set strictly to zero all pixels outside
                max(radius)*safefactor [default 1.2]

 OUTPUTS:
   fracs- contribution of each pixel to image
   pixnum - Pixel number, 0-indexed, for referencing array using one index.
   xPixNum - Pixel number in X, 0-indexed.
   yPixNum - Pixel number in Y, 0-indexed.

 COMMENTS:
   Uses Robert Lupton's Aperture Photometry scheme to measure seeing-
   and pixel-convolved aperture photometry in band-limited images.

   xcen and ycen MUST be integers. This simplifies the caching 
   of the weights considerably. Note that for band-limited images 
   (the only kind that this code works for) you can always sshift 
   the image to get the center of the object at the center of a 
   pixel (ie. an integer pixel number). 

 BUGS:

 PROCEDURES CALLED:

 REVISION HISTORY:
   Started - 22-Aug-2003 M. Blanton (NYU)

(See pro/image/exact_photfrac.pro)


EXTRACT_PROFMEAN

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   extract_profmean
 PURPOSE:
   Extract a photoesque radial profile
 CALLING SEQUENCE
   extract_profmean, image, center, profmean, proferr $
     [,profradius=profradius] [,invvar=invvar] 
 INPUTS:
   image       - [nx,ny] image
   center      - [2] center of extraction (LONG)
 OPTIONAL INPUTS:
   invvar      - [nx,ny] inverse variance image; default to unity
   profradius  - [nrad] defining profile, in pixels; default to PHOTO aps
 KEYWORDS:
 OUTPUTS:
   nprof         - number of "good" profmean values (based on image
                   size alone)
   profmean      - [nrad] annular fluxes
   profmean_ivar - [nrad] uncertainties
   qstokes       - if present, calculates Stokes Q parameter in each circle
                   (not within annuli)
   ustokes       - if present, calculates Stokes U parameter in each circle
                   (not within annuli)
 OPTIONAL INPUT/OUTPUTS:
   cache         - cache storing photfracs for re-use
 COMMENTS:
   Image must be centered on the center pixel. 
 DEPENDENCIES:
   idlutils
 BUGS:
 REVISION HISTORY:
   2002-09-04  Written - Blanton
   2002-09-12  Modified to use djsphot - Hogg

(See pro/image/extract_profmean.pro)


EXT_CCM

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

 PURPOSE:
   Return extinction curve from CCM (1989), defined in the wavelength
   range [1250,33333] Angstroms.

 CALLING SEQUENCE:
   Alam = ext_ccm( lambda, [ Rv ] )

 INPUTS:
   lambda:      Wavelength(s) in Angstroms

 OPTIONAL INPUTS:
   Rv:          Value of R_V; default to 3.1

 OUTPUTS:
   Alam:        Return value A(lambda)/A(V)

 COMMENTS:
   Reference is Cardelli, J.A., Clayton, G.C., & Mathis, J.S. 1989,
   ApJ, 345, 245-256.

 PROCEDURES CALLED:

 REVISION HISTORY:
   Written D. Schlegel, 8 September 1997, Durham

(See pro/dust/ext_ccm.pro)


EXT_ODONNELL

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

 PURPOSE:
   Return extinction curve from Odonnell (1994), defined in the wavelength
   range [3030,9091] Angstroms.  Outside this range, use CCM (1989).

 CALLING SEQUENCE:
   Alam = ext_odonnell( lambda, [ Rv ] )

 INPUTS:
   lambda:      Wavelength(s) in Angstroms

 OPTIONAL INPUTS:
   Rv:          Value of R_V (scalar); default to 3.1

 OUTPUTS:
   Alam:        Return value A(lambda)/A(V)

 COMMENTS:
   Reference is O'Donnell, J. E. 1994, ApJ, 422, 158-163.

 PROCEDURES CALLED:
   ext_ccm()

 REVISION HISTORY:
   Written D. Schlegel, 8 September 1997, Durham

(See pro/dust/ext_odonnell.pro)


EX_MAX

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   ex_max
 PURPOSE:
   expectation-maximization iterative multi-gaussian fit to data
 INPUTS:
   weight      [N] array of data-point weights
   point       [d,N] array of data points - N vectors of dimension d
   amp         [M] array of gaussian amplitudes
   mean        [d,M] array of gaussian mean vectors
   var         [d,d,M] array of gaussian variance matrices
 OPTIONAL INPUTS:
   maxiterate  maximum number of iterations; default to 1000
   qa          name for QA plot PostScript file
   label       [d] array of QA plot axis labels; default 'x_i'
 OUTPUTS:
   amp         updated amplitudes
   mean        updated means
   var         updated variances
 OPTIONAL OUTPUTS:
   entropy     final entropy, relative to one-gaussian case
   probability [N,M] array of probabilities of point i in gaussian j
   exponent    [N,M] array of exponents for point i in gaussian j
 BUGS:
   Hogg is pretty sure that the "probability" calculation in the
   middle of the iteration is WRONG -- see in-code comments.
   Entropy calculation could be wrong; see in-code comments.
   Stopping condition is hard-wired.
 DEPENDENCIES:
   idlutils
 REVISION HISTORY:
   2001-Aug-06  written by Blanton and Hogg (NYU)
   2001-Oct-02  added data-point weights - Hogg

(See pro/math/ex_max.pro)


EX_MAX_PLOT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   ex_max_plot
 PURPOSE:
   plot ex_max outputs or other N-dimensional data sets
 INPUTS:
   weight       [N] array of data-point weights
   point        [d,N] array of data points - N vectors of dimension d
   amp          [M] array of gaussian amplitudes
   mean         [d,M] array of gaussian mean vectors
   var          [d,d,M] array of gaussian variance matrices
   psfilename   name for PostScript file; if no filename is given, then the
                  plots will simply be sent to the currently active device
 OPTIONAL INPUTS:
   nsig         number of sigma for half-width of each plot; default 5
   label        [d] array of axis labels; default 'x_i'
   contlevel    confidence levels for contouring; defaults in source code
   range        [2,d] array of plotting ranges
   textlabel    [q] vector of text labels
   textpos      [d,q] array of text label positions
   box          [2,d] array of coordinates for d-dimensional box
   xdims,ydims  indices of data dimensions to use on each x and y axis
   npix_x,npix_y  number of pixels in x and y dimensions of each panel
   sqrt         sqrt stretch on image
   log          logarithmic stretch on image
   axis_char_scale  size of characters on labels
   overpoints   [d,P] set of points to overplot a red box on each panel
   model_npix_factor  for gaussians, use this factor to scale down pixel size
   panellabels  label string for each panel (size of xdims, ydims arrays)
   quantfrac    vector of fractions at which to plot quantiles on conditional
                   panels
   default_font  font command to send to set font for plotting
   pthick       thickness of plot lines
   yrangefudge  fudge range on histograms (default 1.)
 KEYWORDS:
   nomodel      don't show model fits as greyscales or histograms
   nodata       don't show data as greyscales or histograms
   noellipse    don't show ellipses on 2-d plots
   bw           show ellipses in b/w
   conditional  plot the conditional distribution of y on x 
   nogreyscale  don't plot the greyscale
 OUTPUTS:
 OPTIONAL OUTPUTS:
   quantile     output array of quantile positions; read the source code
   quantneff    the effective number of data points contributing to the medians
   twodimages   set of all of the 2-dimensional projections 
                (doesn't save the gaussian model unless
                model_npix_factor==1)
 BUGS:
   Greyscales need work?
 DEPENDENCIES:
 REVISION HISTORY:
   2001-10-22  written - Hogg
   2002-03-22  many added features - Blanton

(See pro/plot/ex_max_plot.pro)


EX_MAX_PROBABILITY

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   ex_max_probability
 PURPOSE:
   Return probabilities given ex_max results
 INPUTS:
   point       [d,N] array of data points - N vectors of dimension d
   amp         [M] array of gaussian amplitudes
   mean        [d,M] array of gaussian mean vectors
   var         [d,d,M] array of gaussian variance matrices
 OPTIONAL INPUTS:
 OUTPUTS:
 OPTIONAL OUTPUTS:
   probability [N,M] array of probabilities of point i in gaussian j
 BUGS:
   should be called by ex_max for consistency (would involve
   including entropy calc here)
 DEPENDENCIES:
   idlutils
 REVISION HISTORY:
   2002-Nov-20  Blaton

(See pro/math/ex_max_probability.pro)


FAC_FLUX2TEMP

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

 PURPOSE:
   Compute factor to convert from flux/sr to brightness temp

 CALLING SEQUENCE:
   fac_flux2temp, nu_ghz

 INPUTS:
   nu_ghz -    frequency in GHz

 OUTPUTS:
   <value> -   conversion factor (micro-K) / (MJy/sr)

 PROCEDURES CALLED:
   fac_temp2flux()

 COMMENTS:
   see fac_temp2flux.pro 
   We call fac_temp2flux so that these routines are the inverse of
   each other by construction. 

 REVISION HISTORY:
   Written by D. Finkbeiner, 10 March, 1999 - Berkeley

(See pro/dust/fac_flux2temp.pro)


FAC_TEMP2FLUX

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

 PURPOSE:
   Compute factor to convert from brightness temp to flux/sr

 CALLING SEQUENCE:
   fac_temp2flux, nu

 INPUTS:
   nu_ghz -    frequency in GHz

 OUTPUTS:
   <value> -   conversion factor (MJy/sr) / (micro-K)

 PROCEDURES CALLED:
   <none>

 COMMENTS:

 REVISION HISTORY:
   Written by D. Finkbeiner, 10 March, 1999 - Berkeley
   Modified 16 March, 1999 to handle integer nu_ghz argument - DPF

(See pro/dust/fac_temp2flux.pro)


FASTCONV

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
    FASTCONV
 PURPOSE:
    Perform a convolution faster by binning both the image and
    kernel down by a factor of BINFACTOR. 

 CALLING SEQUENCE:
     Fastcon, image, kernel, binfactor
 INPUTS:
     image - input array to be convolved
     kernel - array to convolve image with - e.g. a Gaussian
     binfactor - factor to bin down by (must divide both image and 
                 kernel dimensions)
 OUTPUTS:


 REVISION HISTORY:
   Written D. Finkbeiner, 3 Sept 96
 2  May 1997     Add nodisplay keyword
 3  May 1997     Add edge_wrap keyword
 30 March 1998   Allow non-square arrays (introduced bug)
 24 April 1998   Bug found - failed to divide by binfactor before
                  rebinning.  Bug fixed. 
 29 June 1998    Add disc keyword to allow disc smoothing (DPF)

(See pro/image/fastconv.pro)


FCHEBYSHEV

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        FCHEBYSHEV
 PURPOSE:
       Compute the first M terms in a CHEBYSHEV polynomial expansion.
 EXPLANATION:
       Meant to be used as a supplied function to SVDFIT.

 CALLING SEQUENCE:
       result = FCHEBYSHEV( X, M )

 INPUTS:
       X - the value of the independent variable, scalar or vector
       M - number of term of the CHEBYSHEV expansion to compute, integer scalar 

 OUTPUTS:
       result - (N,M) array, where N is the number of elements in X and M
               is the order.   Contains the value of each CHEBYSHEV term for
               each value of X
 EXAMPLE:
       (1) If x = 2.88 and M = 3 then 
       IDL> print, fchebyshev(x,3)   ==>   [1.00, 2.88, 15.5888]

       (2) Find the coefficients to an M term Chebyshev polynomial that gives
               the best least-squares fit to a dataset (x,y)
               IDL> coeff = SVDFIT( x,y,M,func='fchebyshev')
       
 METHOD:

 REVISION HISTORY:
       04-Aug-1999  Written by Scott Burles by hacking FLEGENDRE code
                    by Landsman in the Goddard libraries.

(See pro/trace/fchebyshev.pro)


FCHEBYSHEV_SPLIT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        FCHEBYSHEV_SPLIT
 PURPOSE:
       Compute the first M terms in a CHEBYSHEV polynomial expansion,
       but modified to allow a split in the baseline at X=0.
 EXPLANATION:
       Meant to be used as a supplied function to SVDFIT.

 CALLING SEQUENCE:
       result = FCHEBYSHEV_SPLIT( X, M )

 INPUTS:
       X - the value of the independent variable, scalar or vector
       M - number of term of the CHEBYSHEV expansion to compute, integer scalar 
           The first two elements describe the constant value which is
           different on each side of X=0.

 OUTPUTS:
       result - (N,M) array, where N is the number of elements in X and M
               is the order.   Contains the value of each CHEBYSHEV term for
               each value of X
 EXAMPLE:
       (1) If x = 2.88 and M = 3 then 
       IDL> print, fchebyshev_split(x,3)   ==>   [1.00, 1.00, 2.88]

       (2) Find the coefficients to an M term Chebyshev polynomial that gives
               the best least-squares fit to a dataset (x,y)
               IDL> coeff = SVDFIT( x,y,M,func='fchebyshev_split')
       
 METHOD:

 REVISION HISTORY:
       04-Aug-1999  Written by Scott Burles by hacking FLEGENDRE code
                    by Landsman in the Goddard libraries.

(See pro/trace/fchebyshev_split.pro)


FILEANDPATH

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

 PURPOSE:
   Split a file name into the path and the file name.

 CALLING SEQUENCE:
   filename = fileandpath(fullname, [path= ])

 INPUTS:
   fullname   - File name(s) which may include disk and/or directory
                specifications.

 OUTPUT:
   filename   - File name(s) without any disk or directory specifications.

 OPTIONAL OUTPUT:
   path       - Disk and directory specification(s).

 COMMENTS:
   This routine is meant to absorb any operating system dependencies.

 EXAMPLES:
   For Unix:
   IDL> print, fileandpath('data/all/one.dat', path=path)
        one.dat
   IDL> print, path
        data/all

 BUGS:

 PROCEDURES CALLED:
   fdecomp

 REVISION HISTORY:
   30-May-2000  Written by David Schlegel, Princeton.

(See pro/misc/fileandpath.pro)


FILL_BSPLINE

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

 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:
   
   coeff = fill_bspline(x, y, z, invsig, npoly, nbkptord, fullbkpt)

 INPUTS:
   x          - data x values
   y          - data y values
   z          - data z values
   invsig     - inverse error array of y
   npoly      - Order of polynomial (as a function of y)
   nbkptord   - Order of b-splines (4 is cubic)
   fullbkpt   - Breakpoint vector returned by efc

 RETURNS:
   coeff      - B-spline coefficients calculated by efc

 OUTPUTS:

 OPTIONAL KEYWORDS:

 OPTIONAL OUTPUTS:

 COMMENTS:
   please sort x for this routine?  This might not be necessary
   replacement for efcmn and efc2d which calls slatec library

 EXAMPLES:


 PROCEDURES CALLED:

   efc_idl in src/slatec/idlwrapper.c
         which wraps to efc.o in libslatecidl.so

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

(See pro/bspline/fill_bspline.pro)


FINDBKPT

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

 PURPOSE:
   Choose bkpts for b-spline given different constraints

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

 INPUTS:
   bkpt       - Breakpoint vector returned by efc

 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/slatec/findbkpt.pro)


FINDOPFILE

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

 PURPOSE:
   Find the op file corresponding to a specified MJD.

 CALLING SEQUENCE:
   filename = findopfile( expres, mjd, [ indir, /abort_notfound, /silent ] )

 INPUTS:
   expres     - Op file names to match which may include any wildcards
                other other expressions valid for the function FINDFILE().
   mjd        - Number (MJD) for matching corresponding op file.

 OPTIONAL INPUT:
   indir      - Input directory
   abort_notfound - If set and no files are found to match the expression,
                    then abort with the MESSAGE command; otherwise return ''.
   silent     - If set, then don't output any text.

 OUTPUTS:
   filename   - Matched file name without path information

 OPTIONAL OUTPUTS:

 COMMENTS:
   The MJD for the op file is determined from the file name itself
   by looking at whatever number is immediately after the first '-'.
   For example, the file 'opBC-52000.par' is interpreted as having
   MJD=52000.

   The matching op file is the one with the same MJD as that requested,
   or the last one preceding the requested MJD.  If the requested MJD
   precedes any for the existing op files, then return the op file
   with the lowest MJD.  For example, if we have two opBC files
   'opBC-50000.par' and 'opBC-52000.par', then the first is returned
   for all MJDs up to 51999, and the latter used for MJD=52000 and later.

 EXAMPLES:
   Find the opBC file in the directory $IDLSPEC2D_DIR/examples
   that is appropriate for data taken on MJD=52000:
     IDL> indir = getenv('IDLSPEC2D_DIR')+'/examples'
     IDL> filename = findopfile('opBC*.par', 52000, indir)

 BUGS:

 PROCEDURES CALLED:
   djs_filepath()
   fileandpath()
   splog

 INTERNAL SUPPORT ROUTINES:

 DATA FILES:

 REVISION HISTORY:
   27-Feb-2002  Written by Scott Burles & David Schlegel.
                Broken out from an internal function of SDSSPROC.

(See pro/sdss/findopfile.pro)


FIND_SB

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   find_sb
 PURPOSE:
   Find objects in a 2-d image with a gaussian filter
 CALLING SEQUENCE
   find_sb, sub, wt, x=x, y=y, flux=flux, $
       [sigma=, hpix=, hmin=]
 INPUTS:
   sub         - skysubtracted image 
   wt          - inverse variance weight (0 or 1 for CR mask is OK)
 OPTIONAL INPUTS:
   sigma       - sigma of gaussian filter in pixels  (1.0 is default)
   hpix        - half-pixel width of convolution filter  (2 is default)
   hmin        - minimum flux threshold  
   curvr       - the maximum allowed log ratio of curvature along the 
                     major/minor axes  (basically checking for roundness).
                   default is 2.
 KEYWORDS:
 OUTPUTS:
   x          - column pixel positions of flux peak (sorted be decreasing flux)
   y          - row pixel position                  "
   flux       - gaussian filtered flux estimate
   pa_degrees - a guess at the PA of the object from the x-axis
   ab         - a guess at the minor/major axis ratio
 COMMENTS:
 DEPENDENCIES:
   idlutils
 BUGS:
   No checks on neighboring peaks
   Not tested yet with real inverse variance weighting
   Not sure that I have PA calculated correctly
 REVISION HISTORY:
   2005-11-30  Written - Burles

(See pro/image/find_sb.pro)


FIRST_COVERAGE

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

 PURPOSE:
   Read the FIRST survey coverage maps.

 CALLING SEQUENCE:
   skyrms = first_coverage(ra, dec)

 OPTIONAL INPUTS:
   ra:          Right ascensions [J2000 deg]
   dec:         Declinations [J2000 deg]

 OUTPUTS:
   skyrms:      Returned RMS noise in mJy/beam

 COMMENTS:
   These images give the RMS in mJy/beam tabulated on a ~3 arcmin grid
   in RA and DEC.  However, the WCS headers in these FITS files are invalid.

 BUGS:
   The coordinates in these FITS headers have been interpreted to be
   for the *center* of each pixel, though there is no documentation as
   to whether this is the correct interpretation.

 DATA FILES:
   The following data files can be copied from:
     http://sundog.stsci.edu/first/catalogs/
   and should be put in a directory pointed to by the environment
   variable $FIRST_DIR:
     $FIRST_DIR/coverage-north-3arcmin-03apr11.fits
     $FIRST_DIR/coverage-south-3arcmin-01oct15.fits

 PROCEDURES CALLED:
   headfits()
   mrdfits()

 REVISION HISTORY:
   Written D. Schlegel, 18 July 2003, Princeton
    31 July 2003 - /silent keyword added to read - DPF

(See pro/first/first_coverage.pro)


FIRST_READ

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

 PURPOSE:
   Read the FIRST catalog (and generate IDL save sets)

 CALLING SEQUENCE:
   bigdat = first_read( [ racen, deccen, radius, node=, incl=, hwidth=, $
    columns= ] )

 OPTIONAL INPUTS:
   racen:       Central RA for selecting a region of stars [J2000 deg]
   deccen:      Central DEC for selecting a region of stars [J2000 deg]
   radius:      Radius for selecting a region of stars [deg]
   node:        Node of great circle for selecting a stripe of stars [deg]
   incl:        Inclination of great circle for selecting a stripe [deg]
   hwidth:      Half-width of great circle for selecting a stripe [deg]
   columns:     Select only these columns from the data files.
                Must include 'FIRST_RA' and 'FIRST_DEC' if a circular or
                great circle region is selected.

 OUTPUTS:
   bigdat:      Returned structure containing data

 COMMENTS:
   To trim to objects within a circle, RACEN, DECCEN and RADIUS must
   all be set.

   To trim to objects along a great circle, NODE, INCL and HWIDTH must
   all be set.

   The equinox of the returned data is always J2000.

 BUGS:

 DATA FILES:
   The following data files can be copied from:
     http://sundog.stsci.edu/first/catalogs/
   and should be put in a directory pointed to by the environment
   variable $FIRST_DIR:
     $FIRST_DIR/catalog_03apr11.bin
   This file must be uncompressed.

 INTERNAL SUPPORT ROUTINES:
   first_convert()
   first_testwrite()
   first_readascii()
   first_rdindex
   first_readfits()
   first_readfile()

 PROCEDURES CALLED:
   djs_diff_angle()
   mrdfits()
   mwrfits
   radec_to_munu
   splog

 REVISION HISTORY:
   Written D. Schlegel, 18 July 2003, Princeton

(See pro/first/first_read.pro)


FITS_PURGE_NANS

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

 PURPOSE:
   Purge invalid (NaN) values from FITS headers

 CALLING SEQUENCE:
   fits_purge_nans, hdr, [ /verbose ]

 INPUTS:
   hdr       - FITS header

 OPTIONAL INPUTS:
   verbose   - If set, then report which keywords are being disposed

 OUTPUTS:
   hdr       - (Modified)

 OPTIONAL OUTPUTS:

 COMMENTS:
   This procedure removes header keywords that are not strings,
   but are returned by SXPAR() as NaN-valued (as determined by
   the FINITE() function).

   This procedure was written to deal with raw SDSS headers that
   sometimes contain header lines like 'ALT     = NaN', where the
   NaN is not contained in quotes.

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:
   splog
   sxpar

 REVISION HISTORY:
   14-Jul-2004  Written by David Schlegel, Princeton.

(See pro/fits/fits_purge_nans.pro)


FITS_WAIT

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

 PURPOSE:
   Wait for a FITS file to be fully written to disk.

 CALLING SEQUENCE:
   qdone = fits_wait(filename, [deltat=, tmax=, _EXTRA=KeywordsForFitsRead ])

 INPUTS:
   filename  - FITS file name.

 OPTIONAL INPUTS:
   deltat    - Time to wait between attempts to check file; default to 10 sec.
   tmax      - Maximum time to check file; default to 300 sec.
   _EXTRA    - Keywords to pass to FITS_READ, such as /HEADER_ONLY or EXTEN=.

 OUTPUTS:
   qdone     - Return 0 if the file was never read as a valid FITS file;
               return 1 if it was.

 OPTIONAL OUTPUTS:

 COMMENTS:
   The purpose of this routine is to be able to test when a FITS file
   has been fully written to disk.  This is useful for real-time processes
   that must check this.  The Goddard routine FITS_READ is used to
   determine when a file is fully written.

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:
   fits_read

 REVISION HISTORY:
   02-Oct-2000  Written by David Schlegel, Princeton.

(See pro/fits/fits_wait.pro)


FLOATCOMPRESS

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

 PURPOSE:
   Make floating-point data more compressible by trimming binary digits. 
   The routine keeps the ndig most signifcant binary digits. 
   If keyword nsig is passed, the algorithm rounds to the nearest
   power of two less than nsig*sigma, where sigma is evaluated from
   the passed array (with 5 sigma outlier rejection). 

 CALLING SEQUENCE:
   out = floatcompress(data, ndig=ndig, nsig=nsig)

 INPUTS:
   data       - input data (type float or double)
                  WARNING: input data array is nuked to save memory
                  on large arrays. 

 OPTIONAL KEYWORDS:
   ndig       - number of binary significant digits to keep
   nsig       - number of sigma at which to round data

 OUTPUTS:
   out        - output data array with ndig significant binary digits
                kept and the rest zeroed. 

 COMMENTS:
   This function does not compress the data in an array, but fills
   unnecessary digits of the IEEE floating point representation with
   zeros.  This makes the data more compressible by standard
   compression routines such as compress or gzip. 
 
   The default is to retain 10 binary digits instead of the usual 23
   bits (or 52 bits for double precision), introducing a fractional
   error strictly less than 1/1024).  This is adequate for most
   astronomical images, and results in images that compress a factor
   of 2-4 with gzip. 

 EXAMPLES:
   image = readfits('map.fits')              ; read in FITS image
   outimage = floatcompress(image,ndig=8)    ; keep 8 binary digits
   writefits,'mapsmall.fits',outimage        ; write image
   
   Then from the UNIX shell
   > gzip -8 mapsmall.fits

   (level 8 gzip is slower but more effective than average this is
       good for files that will be zipped once and unzipped many times)
 
 PERFORMANCE:
   On the typical maps of the ISM, gzip -8 compression factor is
   ~2.1.  Mileage may vary.  For some images, a factor of 4-5 is possible.

 BUGS:
   None known, but it is possible that there are floating point
   values that are corrupted due to round off errors.  Results should
   be double-checked.   

 PROCEDURES CALLED:

 REVISION HISTORY:
   05-Jul-2000 Written by Doug Finkbeiner (UC Berkeley)
   16-Sep-2000 Put in current format and commented -DPF
   22-Sep-2000 Added nsig keyword
   22-Jun-2002 Deals with Infs and NaNs - DPF

(See pro/misc/floatcompress.pro)


FRAC_PROFMEAN

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   frac_profmean
 PURPOSE:
   Get the radius of a certain light fraction, given the total light radius 
 CALLING SEQUENCE
   radfrac= frac_profmean(frac, nprof, profmean, radtot $
                          [,profradius=profradius] )
 INPUTS:
   frac        - fraction desired
   nprof       - number of annuli to trust
   profmean    - [nrad,ncent] annular fluxes
   radtot      - total light radius 
 OPTIONAL INPUTS:
   profradius  - [nrad] defining profile, in pixels; default to PHOTO aps
 KEYWORDS:
 OUTPUTS:
   radfrac     - radius containing frac fraction of the light in radtot
 COMMENTS:
 DEPENDENCIES:
   idlutils
 BUGS:
   no indication of whether fit is sensible
 REVISION HISTORY:
   2003-09-15  Written - Blanton

(See pro/image/frac_profmean.pro)


FSC_DROPLIST

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

 PURPOSE:

   The purpose of this compound widget is to provide an alternative
   to the DROPLIST widget offered in the IDL distribution. What has
   always annoyed me about a droplist is that you can't get the current
   "value" of a droplist easily. This compound widget makes this and
   other tasks much easier.

 AUTHOR:

   FANNING SOFTWARE CONSULTING
   David Fanning, Ph.D.
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: davidf@dfanning.com
   Coyote's Guide to IDL Programming: http://www.dfanning.com/

 CATEGORY:

   General programming.

 CALLING SEQUENCE:

   droplistObj = FSC_Droplist(parent, Title='Animals: ", Value=['Dog'. 'Cat', 'Coyote'], Index=2)

   The return value of the FSC_Droplist (droplistObj in this example) is
   an object reference. Interaction with the droplist will occur through
   object methods.

 INPUT PARAMETERS:

   parent -- The parent widget ID of the compound widget. Required.

 INPUT KEYWORDS:

 Any keyword that is appropriate for the Widget_Droplist function can be used.
 In addition, these keywords are explicitly defined.

   EVENT_FUNC -- Set this keyword to the name of an Event Handler Function.
   EVENT_PRO -- Set this keyword to the name of an Event Handler Procedure.
   FORMAT -- A format specifier for the "format" of the values in the droplist.
   INDEX -- The index number of the current selection.
   SPACES -- A two-element array that indicates the number of blank spaces to be added
             to the the beginning and end of the formatted values. If a single number
             is provided, this number of blank spaces is added to both the beginning
             and the end of the value.
   TITLE -- The title of the droplist widget.
   UNAME -- The user name of the droplist widget. (Only available in IDL 5.2 and higher.)
   UVALUE -- The normal "user value" of the droplist.
   VALUE -- An array of the droplist "selections". May be any data type.

 COMMON BLOCKS:

   None.

 DEPENDENCIES:

   Requires ERROR_MESSAGE from the Coyote Library..

 EVENT STRUCTURE:

   An event is returned each time the droplist value is changed. The event structure
   is defined like this:

   event = { FSC_DROPLIST_EVENT, $ ; The name of the event structure.
             ID: 0L, $             ; The ID of the compound widget's top-level base.
             TOP: 0L, $            ; The widget ID of the top-level base of the hierarchy.
             HANDLER: 0L, $        ; The event handler ID. Filled out by IDL.
             INDEX: 0L, $          ; The index number of the current selection.
             SELECTION:Ptr_New() $ ; A pointer to the current selection "value".
             SELF:Obj_New() }      ; The object reference of the compound widget.

 PUBLIC OBJECT METHODS:

   GetID -- A function with no arguments that returns the widget identifier
      of the droplist widget.

      droplistID = droplistObj->GetID()

   GetIndex -- A function with no arguments that returns the index
      number of the current droplist selection.

      currentIndex = droplistObj->GetIndex()

   GetSelection -- A function with no arguments that returns the current
      droplist selection.

      currentSelection = droplistObj->GetSelection()

   GetUValue -- A function with no arguments that returns the "user value"
      of the compound widget i.e., the value set with the UVALUE keyword).

      myUValue = droplistObj->GetUValue()

   GetValues -- A function with no arguments that returns the "values" or
      "selections" for the droplist.

      possibleSelections = droplistObj->GetValues()

   Resize -- A procedure that sets the X screen size of the droplist. It is
      defined like this:

      PRO Resize, newSize, ParentSize=parentSize

      The "newSize" keyword is the new X screen size. If this argument is
      missing, the screen X size of the compound widget's parent is used.
      The parentSize keyword is an output keyword that returns the X screen
      size of the compound widget's parent.

      droplistObj->Resize, 400

      Note that not all devices (e.g., X Windows devices) support droplist resizing.

   SetIndex -- A procedure that sets the current droplist selection based on
      the given index. This is equivalent to Widget_Control, droplistID, Set_Droplist_Select=newIndex

      droplistObj->SetIndex, newIndex

   SetSelection -- Whereas a regular droplist widget can only be set by index
      number, this compound widget can also be set by a "selection". The new selection
      can be any data type and corresponds to one of the "values" of the droplist.

      droplistObj->SetSelection, newSelection


 EXAMPLE:

   An example program is provided at the end of the FSC_DROPLIST code. To run it,
   type these commands:

      IDL> .Compile FSC_DROPLIST
      IDL> Example

 MODIFICATION HISTORY:

   Written by: David Fanning, 17 Jan 2000. DWF.
   Added FORMAT and SPACES keywords 28 April 2000. DWF.
   Fixed a small problem with event processing when the EVENT_FUNC keyword
      was used. 29 Dec 2000. DWF.

(See pro/psconfig/fsc_droplist.pro)


FSC_FIELD

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

 PURPOSE:

   The purpose of this compound widget is to provide an alternative
   to the CW_FIELD widget offered in the IDL distribution. One weakness
   of the CW_FIELD compound widget is that the text widgets do not
   look editable to the users on Windows platforms. This program
   corrects that deficiency and adds some features that I think
   will be helpful. For example, you can now assign an event handler
   to the compound widget, ask for positive numbers only, and limit
   the number of digits in a number, or the number of digits to the
   right of a decimal point. The program is written as a widget object,
   which allows the user to call object methods directly, affording
   even more flexibility in use. This program replaces the earlier
   programs FSC_INPUTFIELD and COYOTE_FIELD.

   The program consists of a label widget next to a one-line text widget.
   The "value" of the compound widget is shown in the text widget. If the
   value is a number, it will not be possible (generally) to type
   alphanumeric values in the text widget. String values behave like
   strings in any one-line text widget.

 AUTHOR:

   FANNING SOFTWARE CONSULTING
   David Fanning, Ph.D.
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: davidf@dfanning.com
   Coyote's Guide to IDL Programming: http://www.dfanning.com/

 CATEGORY:

   General programming.

 TYPICAL CALLING SEQUENCE:

   fieldID = FSC_FIELD(parent, Title="X Size:", Value=256, Object=fieldObject, Digits=3)

 INPUT PARAMETERS:

   parent -- The parent widget ID of the compound widget. Required.

 INPUT KEYWORDS:

   COLUMN        Set this keyword to have the Label widget above the Text widget.
                 The default is to have the Label widget in a row with the Text widget.

   CR_ONLY       Set this keyword if you only want Carriage Return events returned to
                 your event handler. If this keyword is not set, all events are returned.
                 Setting this keyword has no effect unless either the EVENT_PRO or
                 EVENT_FUNC keyword is used.

   DECIMAL       Set this keyword to the number of digits to the right of the decimal
                 point in floating point or double precision numbers. Ignored for STRING values.

   DIGITS        Set this keyword to the number of digits permitted in integer numbers.

   EVENT_FUNC    Set this keyword to the name of an event handler function. If this
                 keyword is undefined and the Event_Pro keyword is undefined,
                 all compound widget events are handled internally and not
                 passed on to the parent widget.

   EVENT_PRO     Set this keyword to the name of an event handler procedure. If this
                 keyword is undefined and the Event_Func keyword is undefined,
                 all compound widget events are handled internally and not
                 passed on to the parent widget.

   FIELDFONT     The font name for the text in the text widget.

   FRAME         Set this keyword to put a frame around the compound widget.

   LABEL_LEFT    Set this keyword to align the text on the label to the left.

   LABEL_RIGHT   Set this keyword to align the text on the label to the right.

   LABELFONT     The font name for the text in the label widget.

   LABELSIZE     The X screen size of the label widget.

   NAME          A string containing the name of the object. The default is ''.

   NOEDIT        Set this keyword to allow no user editing of the input text widget.

   NONSENSITIVE  Set this keyword to make the input text widget non-sensitive.

   POSITIVE      Set this keyword if you want only positive numbers allowed.

   SCR_XSIZE     The X screen size of the compound widget.

   SCR_YSIZE     The Y screen size of the compound widget.

   TITLE         The string text placed on the label widget.

   UNDEFINED     Set this keyword to the value to use for "undefined" values. If
                 not set, then !Value.F_NAN is used for numerical fields and a
                 NULL string is used for string fields. This applies to values
                 obtained with the GET_VALUE method or the GET_VALUE function.

   UVALUE        A user value for any purpose.

   VALUE         The "value" of the compound widget. Any type of integer, floating, or string
                 variable is allowed. The data "type" is determined automatically from the
                 value supplied with this keyword. Be sure you set the type appropriately for
                 your intended use of the value.

   XSIZE         The X size of the text widget in the usual character units.

 OUTPUT KEYWORDS:

   OBJECT        Set this keyword to a named variable to receive the compound widget's
                 object reference. This is required if you wish to call methods on the object.
                 Note that the object reference is also available in the event structure
                 generated by the widget object. Note that the object reference will be
                 necessary if you want to get or set values in the compound widget.

 COMMON BLOCKS:

   None.

 RESTRICTIONS:

   None.

 EVENT STRUCTURE:

   All events are handled internally unless either the Event_Pro or Event_Func
   keywords are used to assign an event handler to the compound widget. By
   default all events generated by the text widget are passed to the assigned
   event handler. If you wish to receive only Carriage Return events, set the
   CR_Only keyword.

   event = { FSC_FIELD_EVENT, $   ; The name of the event structure.
             ID: 0L, $            ; The ID of the compound widget's top-level base.
             TOP: 0L, $           ; The widget ID of the top-level base of the hierarchy.
             HANDLER: 0L, $       ; The event handler ID. Filled out by IDL.
             OBJECT: Obj_New(), $ ; The "self" object reference. Provided so you can call methods.
             VALUE: Ptr_New(), $  ; A pointer to the widget value.
             TYPE:""              ; A string indicating the type of data in the VALUE field.
           }

   Note that if the field is "empty", the VALUE will be a pointer
   to an undefined variable. You should check this value before you
   use it. You code will look something like this:

     IF N_Elements(*event.value) EQ 0 THEN $
         Print, 'Current Value UNDEFINED.' ELSE $
         Print, 'Current Value: ', *event.value

 GETTING and SETTING VALUES:

   Almost all the properties of the widget can be obtained or set via
   the object's GetProperty and SetProperty methods (described below).
   Traditional compound widgets have the ability to get and set the "value"
   of the compound widget identifier (e.g., fieldID in the calling
   sequence above). Unfortunately, it is impossible to retreive a variable
   in this way when the variable is undefined. In practical terms, this
   means that the undefined variable must be set to *something*. You can
   determine what that something is with the UNDEFINED keyword, or I will set
   it to !VALUES.F_NAN for numerical fields and to the null string for string
   fields. In any case, you will have to check for undefined variables before
   you try to do something with the value. For a numerical field, the code
   might look something like this:

      fieldID = FSC_FIELD(parent, Title="X Size:", Value=256, Object=fieldObject, Digits=3)
      currentValue = fieldObject->Get_Value()
      IF Finite(currentValue) EQ 0 THEN Print, 'Value is Undefined' ELSE Print, currentValue

   Additional examples are provided in the numerical example fields in Example Program below.

   Setting the value of the compound widget is the same as calling the Set_Value
   method on the object reference. In other words, these two statements are equivalent.

        fieldObject->Set_Value, 45.4
        Widget_Control, fieldID, Set_Value=45.4

   The data type of the value is determined from the value itself. Be sure you set it appropriately.

 OBJECT PROCEDURE METHODS:

   GetProperty -- This method allows various properties of the widget to be
       returned via output keywords. The keywords that are available are:

       CR_Only -- A flag, if set, means only report carriage return events.
       DataType -- The data type of the field variable.
       Decimal -- Set this keyword to the number of digits to the right of the decimal
              point in FLOATVALUE and DOUBLEVALUE numbers.
       Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
       Event_Func -- The name of the event handler function.
       Event_Pro -- The name of the event handler function.
       Name -- A scalar string name of the object.
       NoEdit -- A 1 means the widget is non-editable.
       NonSensitive -- A 1 means the widget is non-sensitive.
       NonSensitive -- Set this keyword to make the widget non-sensitive.
       Positive -- Indicates if the Positive number flag is set (1) or not (0).
       UValue -- The user value assigned to the compound widget.
       Value -- The "value" of the compound widget.

   MoveTab -- This method moves the focus to the widget identified in the "next" field,
        which must be set with the SetTabNext method. No parameters. Called automatically
        when a TAB character is typed in the text widget.

   Resize -- This method allows you to resize the compound widget's text field.
        The value parameter is an X screen size for the entire widget. The text
        widget is sized by using the value obtained from this value minus the
        X screen size of the label widget.

          objectRef->Resize, screen_xsize_value

   Set_Value -- This method allows you to set the "value" of the field. It takes
       one positional parameter, which is the value.

          objectRef->Set_Value, 5


   SetEdit -- This procedure turns editing on (value of 1) or off (value of 0).

   SetProperty -- This method allows various properties of the widget to be
       set via input keywords. The keywords that are available are:

       CR_Only -- Set this keyword if you only want Carriage Return events.
       Decimal -- Set this keyword to the number of digits to the right of the decimal
              point in FLOATVALUE and DOUBLEVALUE numbers.
       Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
       Event_Func -- Set this keyword to the name of an Event Function.
       Event_Pro -- Set this keyword to the name of an Event Procedure.
       LabelSize --  The X screen size of the Label Widget.
       Name -- A scalar string name of the object. (default = '')
       NoEdit -- Set this keyword to make the widget non-editable.
       NonSensitive -- Set this keyword to make the widget non-sensitive.
       Positive -- Set this keyword to indicate only positive numbers are allowed.
       Scr_XSize -- The X screen size of the text widget.
       Scr_YSize -- The Y screen size of the text widget.
       Title -- The text to go on the Label Widget.
       UValue -- A user value for any purpose.
       Value -- The "value" of the compound widget.
       XSize -- The X size of the Text Widget.

   SetSensitive -- This procedure turns text widget sensitivity on (value of 1) or off (value of 0).

 OBJECT FUNCTION METHODS:

      Get_Value -- Returns the "value" of the field. No parameters. Will be undefined
          if a "number" field is blank. Should be checked before using:

          IF N_Elements(objectRef->Get_Value()) NE 0 THEN Print, Value is: ', objectRef->Get_Value()

      GetID -- Returns the widget identifier of the compound widget's top-level base.
         (The first child of the parent widget.) No parameters.

      GetLabelSize -- Returns the X screen size of the label widget. No parameters.

      GetTextID -- Returns the widget identifier of the compound widget's text widget.
         No parameters.

      GetTextSize -- Returns the X screen size of the text widget. No parameters.


 PRIVATE OBJECT METHODS:

   Although there is really no such thing as a "private" method in IDL's
   object implementation, some methods are used internally and not meant to
   be acessed publicly. Here are a few of those methods. I list them because
   it may be these private methods are ones you wish to override in subclassed
   objects.

      MoveTab -- This method moves the cursor to end of the text in the widget identified
        by the nexttab field. (This will be set with the SetTabNext method.)

      Text_Events -- The main event handler method for the compound widget. All
        text widget events are processed here.

      ReturnValue -- This function method accepts a string input value and converts
        it to the type of data requested by the user.

      Validate -- This function method examines all text input and removes unwanted
        characters, depending upon the requested data type for the field. It makes it
        impossible, for example, to type alphanumeric characters in an INTEGER field.

 EXAMPLE:

   An example program is provided at the end of the FSC_FIELD code. To run it,
   type these commands:

      IDL> .Compile FSC_Field
      IDL> Example

 MODIFICATION HISTORY:

   Written by: David Fanning, 18 October 2000. Based heavily on an earlier
      FSC_INPUTFIELD program and new ideas about the best way to write
      widget objects.
   Added LABEL_LEFT, LABEL_RIGHT, and UNDEFINED keywords. 29 Dec 2000. DWF.
   Modified the way the value is returned in the GET_VALUE method and the
      GET_VALUE function. Modified Example program to demonstrate. 30 Dec 2000. DWF.
   Added NOEDIT and NONSENSITIVE keywords, with corresponding SETEDIT and SETSENNSITIVE
      methods. 19 Jan 2001. DWF.
   Actually followed through with the changes I _said_" I made 29 Dec 2000. (Don't ask....) 13 June 2001. DWF.
   Added GetTextSize and GetLabelSize methods for obtaining the X screen
      size of the text and label widgets, respectively. 21 July 2001. DWF.
   Fixed a problem in SetProperty method where I was setting self.xsize, which doesn't exist. 24 April 2002. DWF.

(See pro/psconfig/fsc_field.pro)


FSC_FILESELECT

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

 PURPOSE:

   The purpose of this compound widget is to provide a means
   by which the user can type or select a file name. The
   program is written as an "object widget", meaning that
   the guts of the program is an object of class FSC_FILESELECT.
   This is meant to be an example of the obvious advantages of
   writing compound widget programs as objects.

 AUTHOR:

   FANNING SOFTWARE CONSULTING
   David Fanning, Ph.D.
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: davidf@dfanning.com
   Coyote's Guide to IDL Programming: http://www.dfanning.com/

 CATEGORY:

   General programming.

 CALLING SEQUENCE:

   filenameID = FSC_FileSelect(parent)

 INPUT PARAMETERS:

   parent -- The parent widget ID of the compound widget. Required.

 INPUT KEYWORDS:

   Event_Pro -- The event handler procedure for this compound widget.By default: "".
   Event_Func -- The event handler function for this compound widget. By default: "".

      If neither EVENT_PRO or EVENT_FUNC is defined, program events are handled internally by the compound widget.

   DirectoryName -- The initial name of the directory. By defaut: current directory.
   Filename -- The initial file name in the filename text widget.
   Filter -- The file filter. By default: "*".
   Frame -- Set this keyword for a frame around the compound widget.
   LabelFont -- The font for the label widget. By default: "".
   LabelName -- The text on the label widgt. By default: "Filename: ".
   LabelSize -- The X screen size of the label widget. By default: 0.
   MustExist -- A flag that indicates selected files must exist. By default: 0.
   NoMaxSize -- A flag to prohibit automatic text widget sizing. By default: 0.

     If this keyword is not set, the compound widget will automatically resize itself to
     the largest widget in its parent base widget. It will do this by changing the size of
     the text widgets holding the file and directory names.

   Read -- Set this keyword to have file selection for reading a file. By default: 1.
   SelectDirectory -- The default directory for file selection. In other words, this is the
     default directory for DIALOG_PICKFILE, which is accessed via the BROWSE buttons.
   SelectFont -- The font for the "Browse" button. By default: "".
   SelectTitle -- The title bar text on the file selection dialog. By default: "Select a File...".
   TextFont -- The font for the filename text widget. By default: "".
   UValue -- User value for any purpose.
   Write -- Set this keyword to open a file for writing. By default: 0.
   XSize -- The X size of the text widget holding the filename. By default: StrLen(filename) * 1.5 > 40.

 OUTPUT KEYWORDS:

   ObjectRef -- Assign this keyword to an output variable that will hold the internal object reference.
                With the object reference you can call object methods to easily change many properties of
                the compound widget.

 COMMON BLOCKS:

   None.

 RESTRICTIONS:

   Probably doesn't work correctly on VMS systems :-( If you can help, please
   contact me. I don't have a VMS system to test on.

 EVENT STRUCTURE:

   All events are handled internally unless either the Event_Pro or Event_Func
   keywords are used to assign an event handler to the compound widget. All events
   generated by the text widgets are passed to the assigned event handler.

   event = { CW_FILESELECT, $     ; The name of the event structure.
             ID: 0L, $            ; The ID of the compound widget's top-level base.
             TOP: 0L, $           ; The widget ID of the top-level base of the hierarchy.
             HANDLER: 0L, $       ; The event handler ID. Filled out by IDL.
             Basename: "", $      ; The base filename without directory specifiers.
             Filename: "", $      ; The fully qualified filename.
             Directory: "", $     ; The name of the current file directory.
           }

 EXAMPLE:

   An example program is provided at the end of the FSC_FILESELECT code. To run it,
   type these commands:

      IDL> .Compile fsc_fileselect
      IDL> Example

   Or, if you want to obtain the object reference, type this:

      IDL> Example, theObject

   Now you can call the object's methods. For example:

      IDL theObject->SetProperty, XSize=150

 GETTING and SETTING VALUES:

   So as not to disrupt the accepted paradigm in using compound widgets, you
   can use the return value of the FSC_FILESELECT function with WIDGET_CONTROL to
   get and set the "value" of the widget.

       Widget_Control, filenameID, Set_Value='C:\RSI\IDL52\DATA\cyclone.dat'

   The program will automatically separate the file name portion of the value
   from the directory portion and put things in the correct text widgets.

   Similarly, you can get the "value" of the widget:

       Widget_Control, filenameID, Set_Value=theValue
       Print, theValue

           C:\RSI\IDL52\DATA\cyclone.dat

   The return value is the fully qualified file path to the file.

 USING OBJECT METHODS to CHANGE PROGRAM PROPERTIES:

   If you obtain the object reference, you have a great deal more control
   over the properties of the compound widget. You obtain the object reference
   by calling the function like this:

      filenameID = FSC_FILESELECT(parent, ObjectRef=theObject)

 OBJECT PROCEDURE METHODS:

   GetProperty -- This method allows various properties of the widget to be
       returned via output keywords. The keywords that are available are:

      DirectoryName -- The current directory.
      Event_Func -- The name of the event handler function for this compound widget.
      Event_Pro -- The name of the event handler procedure for this compound widget.
      Filename -- The current base filename.
      Filter -- The current file filter.
      LabelName -- The text on the label widget.
      LabelSize -- The X screen size of the label widget.
      MustExist -- A flag that indicates selected files must exist to be selected.
      Parent -- The parent widget of the compound widget.
      Read=read -- The file selection for reading flag.
      SelectTitle -- The title bar text on the file selection dialog.
      TLB -- The top-level base of the compound widget.
      UValue -- The user value of the compound widget.
      Write -- The file selection for writing flag.
      XSize -- The X size of the text widget holding the filename.

   LabelSize -- This method makes sure that the directory name and file name labels
      are the same size. Normally, this procedure is called internally. No parameters.

   MatchSize -- This method resizes the compound widget so that it is as long as the
      the longest widget in the parent base widget. This is done automatically upon
      realization unless the NOMAXSIZE keyword is set. The method aids in writing
      resizeable widget programs.

   SetProperty -- This method allows various properties of the widget to be
       set via input keywords. The keywords that are available are:

      DirectoryName -- The current directory.
      Event_Func -- The name of the event handler function for this compound widget.
      Event_Pro -- The name of the event handler procedure for this compound widget.
      Filename -- The current base filename.
      Filter -- The current file filter.
      LabelName -- The text on the label widget.
      LabelSize -- The X screen size of the label widget.
      MustExist -- A flag that indicates selected files must exist to be selected.
      Read -- The file selection for reading flag.
      SelectTitle -- The title bar text on the file selection dialog.
      UValue -- The user value of the compound widget.
      Write -- The file selection for writing flag.
      XSize -- The X size of the text widget holding the filename.

 OBJECT FUNCTION METHODS:

      GetFileName -- Returns the fully qualified filename. No parameters.

      GetTLB -- Returns the top-level base ID of the compound widget. No Parameters.

      Inspect_DirectoryName -- Inspects the directory name for correctness. Requires one positional parameter.

        directoryName -- The name of the directory from the directory text widget.
        textSelection -- The current text selection position.

        At the moment all this does is remove any blank characters from either
        end of the directory name and makes sure the last character of the directory
        name does not end in a subdirectory specifier (except for VMS).

     Inspect_Filename -- Inspects the file name for correctness. Requires one positional parameter.

        filename -- The name of the file from the filename text widget.
        textSelection -- The current text selection position.

        At the moment all this does is remove any blank characters from either
        end of the file name

 MODIFICATION HISTORY:

   Written by: David W. Fanning, 21 NOV 1999.
   Fixed bug in File Name selection button. 18 MAR 2000. DWF.
   Fixed an error in which directory the Browse buttons should start
       searching. 29 SEP 2000. DWF.
   Previously returned events only for typing in text widgets. Now
       Browse button events are also returned. 29 SEP 2000. DWF.
   Fixed a bug in setting the file filter. 29 SEP 2000. DWF.
   Removed the Directory Browse button 10 AUG 2002. DWF.
   Added ERROR_MESSAGE to error handling. 10 AUG 2002. DWF.
   Changed the ability to specify a file filter as a string array, instead
       of just as a scalar string. This required the use of a pointer, which
       meant that I had to remove the FILTER field from the CW_FILESELECT
       event structure to avoid likely memory leakage. This is a dangerous
       change because it means programs that relied on this (I expect there
       are very, very few) will break and it goes against my philosopy of
       keeping my programs backward compatible. Let me know if you have
       problems. In testing, I discoved no problems in my own code. 31 OCT 2002. DWF.
   Fixed a problem with DIALOG_PICKFILE that sometimes allowed users to change
       directories without selecting a file. 3 Nov 2002. DWF.

(See pro/psconfig/fsc_fileselect.pro)


FSC_INPUTFIELD

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

 PURPOSE:

   The purpose of this compound widget is to provide an alternative
   to the CW_FIELD widget offered in the IDL distribution. What has
   always bothered me about CW_FIELD is that the text widgets do not
   look editable to the users on Windows platforms. This program
   corrects that deficiency and adds some features that I think
   would be helpful. For example, you can now assign an event handler
   to the compound widget. The program is written entirely as an object.
   A companion program, COYOTE_FIELD, has much the same functionality,
   but is written as a traditional compound widget. The point of writing
   the same program in two different ways is to give you the opportunity
   to compare and contrast the two methods. I personally think there
   is no substitute for the power of object programs. :-)

 AUTHOR:
   FANNING SOFTWARE CONSULTING
   David Fanning, Ph.D.
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: davidf@dfanning.com
   Coyote's Guide to IDL Programming: http://www.dfanning.com/

 CATEGORY:

   General programming.

 CALLING SEQUENCE:

   objectRef = FSC_INPUTFIELD(parent, Title='X Size: ", Value=256, /IntegerValue)

 INPUT PARAMETERS:

   parent -- The parent widget ID of the compound widget. Required.

 INPUT KEYWORDS:

   Column -- Set this keyword to have the Label Widget above the Text Widget.
   CR_Only -- Set this keyword if you only want Carriage Return events. If
              this keyword is not set, all events are returned. No events
              are returned unless the EVENT_PRO or EVENT_FUNC keywords are used.
   Decimal -- Set this keyword to the number of digits to the right of the decimal
              point in FLOATVALUE and DOUBLEVALUE numbers.
   Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
   DoubleValue -- Set this keyword if you want DOUBLE values returned.
   Event_Func -- Set this keyword to the name of an Event Function. If this
                 keyword is undefined and the Event_Pro keyword is undefined,
                 all compound widget events are handled internally and not
                 passed on to the parent widget.
   Event_Pro -- Set this keyword to the name of an Event Procedure. If this
                keyword is undefined and the Event_Func keyword is undefined,
                all compound widget events are handled internally and not
                passed on to the parent widget.
   FieldFont -- The font name for the text in the Text Widget.
   FloatValue -- Set this keyword for FLOAT values.
   Frame -- Set this keyword to put a frame around the compound widget.
   IntegerValue -- Set this keyword for INTEGER values.
   LabelFont -- The font name for the text in the Label Widget.
   LabelSize -- The X screen size of the Label Widget.
   LongValue -- Set this keyword for LONG values.
   Name -- A scalar string name of the object. (default = '')
   Positive -- Set this keyword if you want only positive numbers allowed.
   Row=row -- Set this keyword to have the Label beside the Text Widget. (The default.)
   Scr_XSize -- The X screen size of the compound widget.
   Scr_YSize -- The Y screen size of the compound widget.
   StringValue -- Set this keyword for STRING values. (The default.)
   Title -- The text to go on the Label Widget.
   UValue -- A user value for any purpose.
   Value -- The "value" of the compound widget.
   XSize -- The X size of the Text Widget.

 COMMON BLOCKS:

   None.

 RESTRICTIONS:

   None.

 EVENT STRUCTURE:

   All events are handled internally unless either the Event_Pro or Event_Func
   keywords are used to assign an event handler to the compound widget. By
   default all events generated by the text widget are passed to the assigned
   event handler. If you wish to receive only Carriage Return events, set the
   CR_Only keyword.

   event = { FSC_FIELD, $         ; The name of the event structure.
             ID: 0L, $            ; The ID of the compound widget's top-level base.
             TOP: 0L, $           ; The widget ID of the top-level base of the hierarchy.
             HANDLER: 0L, $       ; The event handler ID. Filled out by IDL.
             ObjRef: Obj_New(), $ ; The "self" object reference. Provided so you can call methods.
             Value: Ptr_New(), $  ; A pointer to the widget value.
             Type:""              ; A string indicating the type of data in the VALUE field.
           }                      ; Values are "INT", "LONG", "FLOAT", "DOUBLE", or "STRING".

 GETTING and SETTING VALUES:

   Almost all the properties of the widget can be obtained or set via
   the object's GetProperty and SetProperty methods (described below).
   But since traditional compound widgets have the ability to get and
   set the value of the compound widget, this capability is implemented
   as special methods.

   To get the value of the field, do this: value = objectRef->Get_Value()
   To set the value of the field, so this: objectRef->Set_Value, value, /IntegerValue

   The proper keyword should be used to set the data type of the value. If a keyword
   is not used, the data type is determined from the value itself.

 OBJECT PROCEDURE METHODS:

   GetProperty -- This method allows various properties of the widget to be
       returned via output keywords. The keywords that are available are:

       CR_Only -- A flag, if set, means only report carriage return events.
       DataType -- The data type of the field variable.
       Decimal -- Set this keyword to the number of digits to the right of the decimal
              point in FLOATVALUE and DOUBLEVALUE numbers.
       Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
       Event_Func -- The name of the event handler function.
       Event_Pro -- The name of the event handler function.
       Positive -- Indicates if the Positive number flag is set (1) or not (0).
       UValue -- The user value assigned to the compound widget.
       Value -- The "value" of the compound widget.
     Name -- A scalar string name of the object.

   MoveTab -- This method moves the focus to the widget identified in the "next" field,
        which must be set with the SetTabNext method. No parameters. Called automatically
        when a TAB character is typed in the text widget.

   Resize -- This method allows you to resize the compound widget's text field.
        The value parameter is an X screen size for the entire widget. The text
        widget is sized by using the value obtained from this value minus the
        X screen size of the label widget.

          objectRef->Resize, screen_xsize_value

   Set_Value -- This method allows you to set the "value" of the field. It takes
       one positional parameter, which is the value.

          objectRef->Set_Value, 5

       Keywords available are these to set the type of the data. If keywords
       are not used, the data type is determined from the value.

       DoubleValue -- Set this keyword if you want DOUBLE values returned.
       FloatValue -- Set this keyword for FLOAT values.
       IntegerValue --  Set this keyword for INTEGER values.
       LongValue -- Set this keyword for LONG values.
       StringValue -- Set this keyword for STRING values. (The default.)

   SetProperty -- This method allows various properties of the widget to be
       set via input keywords. The keywords that are available are:

       CR_Only -- Set this keyword if you only want Carriage Return events.
       Decimal -- Set this keyword to the number of digits to the right of the decimal
              point in FLOATVALUE and DOUBLEVALUE numbers.
       Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
       DoubleValue -- Set this keyword if you want DOUBLE values returned.
       Event_Func -- Set this keyword to the name of an Event Function.
       Event_Pro -- Set this keyword to the name of an Event Procedure.
       FloatValue -- Set this keyword for FLOAT values.
       IntegerValue --  Set this keyword for INTEGER values.
       LabelSize --  The X screen size of the Label Widget.
       LongValue -- Set this keyword for LONG values.
       Name -- A scalar string name of the object. (default = '')
       Positive -- Set this keyword to indicate only positive numbers are allowed.
       Scr_XSize -- The X screen size of the text widget.
       Scr_YSize -- The Y screen size of the text widget.
       StringValue -- Set this keyword for STRING values. (The default.)
       Title -- The text to go on the Label Widget.
       UValue -- A user value for any purpose.
       Value -- The "value" of the compound widget.
       XSize -- The X size of the Text Widget.

 OBJECT FUNCTIONS METHODS:

      Get_Value -- Returns the "value" of the field. No parameters. Will be undefined
          if a "number" field is blank. Should be checked before using:

          IF N_Elements(objectRef->Get_Value()) NE 0 THEN Print, Value is: ', objectRef->Get_Value()

      GetID -- Returns the widget identifier of the compound widget's top-level base.
         (The first child of the parent widget.) No parameters.

      GetLabelSize -- Returns the X screen size of the label widget. No parameters.

      GetTextID -- Returns the widget identifier of the compound widget's text widget.
         No parameters.

      GetTextSize -- Returns the X screen size of the text widget. No parameters.

 PRIVATE OBJECT METHODS:

   Although there is really no such thing as a "private" method in IDL's
   object implementation, some methods are used internally and not meant to
   be acessed publicly. Here are a few of those methods. I list them because
   it may be these private methods are ones you wish to override in subclassed
   objects.

      MoveTab -- This method moves the cursor to end of the text in the widget identified
        by the nexttab field. (This will be set with the SetTabNext method.)

      Text_Events -- The main event handler method for the compound widget. All
        text widget events are processed here.

      ReturnValue -- This function method accepts a string input value and converts
        it to the type of data requested by the user.

      Validate -- This function method examines all text input and removes unwanted
        characters, depending upon the requested data type for the field. It makes it
        impossible, for example, to type alphanumeric characters in an INTEGER field.

 EXAMPLE:

   An example program is provided at the end of the FSC_INPUTFIELD code. To run it,
   type these commands:

      IDL> .Compile FSC_InputField
      IDL> Example

 MODIFICATION HISTORY:

   Written by: David Fanning, 23 NOV 1999.
   Added DECIMAL and DIGITS keywords, 2 Jan 2000, DWF.
   Changed the calling sequence to that of a function rather than an object
      creation call. This is more familiar to users of compound widgets. 4 Jan 00. DWF.
   Added GetID and Resize methods. 7 Jan 00. DWF.
   Added the Positive keyword and functionality. 12 Jan 00. DWF
   Modified (slightly) the behavior on deleting characters. 12 Jan 00. DWF.
   If a number field is blank, the Get_Value method will now return an undefined variable.
      Be sure you check this value before you use it for something! 17 Jan 00. DWF.
   Fixed a small typo: "aveDecimal" to "haveDecimal". 10 March 2000. DWF.
   Added the ability to tab between FSC_INPUTFIELD widgets with the SetTabNext,
      MoveTab, and GetTextID methods. 31 July 2000. DWF.
   Added NAME field property, a scalar string name for the object 2 AUG 2000 BT
   Added ObjRef field to the FSC_FIELD event structure and added field selection
      for the TAB events added 31 July. 7 AUG 2000. DWF
   Added GetTextSize and GetLabelSize methods for obtaining the X screen
      size of the text and label widgets, respectively. 30 Jan 2001. DWF.

(See pro/psconfig/fsc_inputfield.pro)


FSC_PLOTWINDOW

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

 PURPOSE:

   The purpose of this compound widget is to create a resizeable
   "plot window" inside a larger "page window". I'm not sure it
   has any value except as a utility routine for the PostScript
   configuration object FSC_PSCONFIG__DEFINE, but it's a neat
   program anyway. :-)

 AUTHOR:

   FANNING SOFTWARE CONSULTING
   David Fanning, Ph.D.
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: davidf@dfanning.com
   Coyote's Guide to IDL Programming: http://www.dfanning.com/

 CATEGORY:

   Utility routine for FSC_PSCONFIG__DEFINE.

 CALLING SEQUENCE:

   plotwindowObject = CW_PlotWindow(parent)

 REQUIRED INPUT PARAMETERS:

   parent - The parent base widget of this compound widget.

 RETURN VALUE:

   plotwindowObject - The object reference of the compound widget.

 KEYWORDS:

   COLOR - If set, display the window in "color". This is the default on 24-bit devices.
   DEBUG - Set this keyword to turn traceback error handling on in the error handling code.
   EVENT_PRO - The event procedure for the widget. Required for events to be generated. Otherwise, all events are handled internally.
   LANDSCAPE - If set, display the page in landscape mode. Otherwise the page is display in portrait mode.
   PAGESIZE - The "pagesize" of the widget. Possible values are: "LETTER", "LEDGER", "LEGAL", "A4", and "DISPLAY".
   UNITS - A string indicating INCHES or CENTIMETER units. DEVICE units represented by a null string, "".
   UVALUE - A user value for the caller of this program.
   WINDOWCOLOR - A three-element array specifying the background window color (RGB).
   WINDOWSIZE - The size of the "window" on the page. A four-element array of normalized coordinates in the form [x0, y0, x1, y1].

 EVENT STRUCTURE:

   The event structure that is returned from this compound widget is defined like this,
   where the sizes and offsets locate the target "window" on the page in normalized units:

      event = {ID:0L, TOP:0L, HANDLER:0L, XSize:0.0, YSize:0.0, XOffset:0.0, YOffset:0.0}

 MODIFICATIONS:

   Written by David Fanning, 31 January 2000.
   Fixed a small bug that prevented it working on Macintosh computers. 26 Sept 2000. DWF.
   Added a "DISPLAY" page size, so the program can be used to position
      plots and other graphics in a display window. The "page area" will
      have the same aspect ratio is the current graphics window. 17 March 2001. DWF.

(See pro/psconfig/fsc_plotwindow.pro)


FSC_PSCONFIG__DEFINE

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

 PURPOSE:

   The purpose of this program is to implement an object that
   can keep track of--and allow the user to change--the current
   configuration of the PostScript device.

 AUTHOR:

   FANNING SOFTWARE CONSULTING
   David Fanning, Ph.D.
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: davidf@dfanning.com
   Coyote's Guide to IDL Programming: http://www.dfanning.com/

 CATEGORY:

   General programming.

 DOCUMENTATION:

   Complete documentation for the FSC_PSCONFIG object, including
   keyword and method descriptions, and example programs using the object
   can be found on the Coyote's Guide to IDL Programming web page:

     http://www.dfanning.com/programs/docs/fsc_psconfig.html

   Or, if you would prefer, you can download a self-contained PDF file:

     http://www.dfanning.com/programs/docs/fsc_psconfig.pdf

 KEYWORDS:

   Any keyword accepted by the FSC_PSCONFIG object can be used with
   this program. Here are a few of the most popular keywords.

   Bits_per_Pixel - The number of image bits saved for each image pixel: 2, 4, or 8. The default is 8.
   Color - Set this keyword to select Color PostScript output. Turned on by default.
   DefaultSetup - Set this keyword to the "name" of a default style. Current styles (you can easily
     create and add your own to the source code) are the following:

       "System (Portrait)" - The normal "default" system set-up. Also, "System".
       "System (Landscape)" - The normal "default" landscape system set-up.
       "Centered (Portrait)" - The window centered on the page. Also, "Center" or "Centered".
       "Centered (Landscape)" - The window centered on the landscape page. Also, "Landscape".
       "Square (Portrait)" - A square plot, centered on the page.
       "Square (Landscape)" - A square plot, centered on the landscape page.
       "Figure (Small)" - A small encapsulated figure size, centered on page. Also, "Encapsulated" or "Encapsulate".
       "Figure (Large)" - A larger encapsulated figure size, centered on page. Also, "Figure".
       "Color (Portrait)" - A "centered" plot, with color turned on. Also, "Color".
       "Color (Landscape)" - A "centered" landscape plot, with color turned on.

   Directory - Set this keyword to the name of the starting directory. The current directory is used by default.
   Encapsulate - Set this keyword to select Encapsulated PostScript output. Turned off by default.
   European - Set this keyword to indicate "european" mode (i.e., A4 page and centimeter units). Turned off by default.
   Filename - Set thie keyword to the name of the PostScript file. The default is "idl.ps".
   Inches - Set this keyword to indicate sizes and offsets are in inches as opposed to centimeters. Set by European keyword by default.
   Landscape - Set this keyword to select Landscape page output. Portrait page output is the default.
   PageType - Set this keyword to the "type" of page. Possible values are:
       "Letter" - 8.5 by 11 inches. (Default, unless the European keyword is set.)
       "Legal" - 8.5 by 14 inches.
       "Ledger" - 11 by 17 inches.
       "A4" - 21.0 by 29.7 centimeters. (Default, if the European keyword is set.)
   XOffset - Set this keyword to the X Offset. Uses "System (Portrait)" defaults. (Note: offset calculated from lower-left corner of page.)
   XSize - Set this keyword to the X size of the PostScript "window". Uses "System (Portrait)" defaults.
   YOffset - Set this keyword to the Y Offset. Uses "System (Portrait)" defaults. (Note: offset calculated from lower-left corner of page.)
   YSize - Set this keyword to the Y size of the PostScript "window". Uses "System (Portrait)" defaults.

   In addition, the following keywords can be used:

   CANCEL -- An output keyword that will be set to 1 if the user
   chooses the Cancel button on the form. It will be 0 otherwise.

   FONTINFO -- Set this keyword is you wish to have font information
   appear on the form. The default is to not include font information.

   FONTTYPE -- Set this keyword to a named variable that will indicate
   the user's preference for font type. Values will be -1 (Hershey fonts),
   0 (hardware fonts), and 1 (true-type fonts). This keyword will always
   return -1 unless the FONTINFO keyword has also been set.

   GROUP_LEADER -- Set this keyword to a widget identifier of the widget
   you wish to be a group leader for this program.

 EXAMPLE:

   A simple sequence of using the object would look something like this:

     psObject = Obj_New("FSC_PSCONFIG")
     psObject->GUI
     psKeywords = psObject->GetKeywords()
     thisDevice = !D.Name
     Set_Plot, 'PS'
     Device, _Extra=psKeywords
     TVImage, image
     Device, /Close_File
     Set_Plot, thisDevice
     Obj_Destroy, psObject

  Note that the object can also be called from the PS_CONFIG interface:

     psKeywords = PSConfig()

 OTHER PROGRAMS NEEDED:

   The following programs are required to run this one:

     fsc_droplist.pro
     fsc_fileselect.pro
     fsc_field.pro
     fsc_plotwindow

 MODIFICATIONS:

   Written by David W. Fanning, 31 January 2000.
   Added capability to call GUI methods when the current graphics device
      doesn't support windows. Device is restored when the GUI exits. 11 May 2000. DWF.
   Changed the default value for the Color keyword to 1. 16 May 2000. DWF.
   Fixed a bug where filename changed when switching Setups. 8 AUG 2000. DWF.
   Fixed a bug when saving setup in Landscape mode. 8 AUG 2000. DWF.
   Added the ability to Get and Set the object's name via the SetProperty
      and a very abbreviated GetProperty method. Also added a GetName method. 26 SEP 2000. DWF.
   Fixed a problem in which the proper configuration was not restored if in Landscape mode. 20 Nov 2000. DWF.
   Made a number of modifications at the request of Martin Schultz. 4 Dec 2000. DWF.
   Fixed a bug when setting file  and directory names with the SetProperty method. 18 Dec 2000. DWF.
   Fixed a small problem in initializing the page size properly. 3 Jan 2001. DWF.
   Corrected a problem that resulted from a change to FSC_DROPLIST. 6 Jan 2001. DWF.
   Added the ability to restore the font type instead of always reverting to !P.Font. 7 Jan 2001. DWF.
   Increased the length of the file/directory name fields. 7 Jan 2001. DWF.
   Fixed another problem with Landscape mode interacting with A4 paper size. 7 Jan 2001. DWF.
   Seems I only half fixed the previous problem. :-( 26 April 2001. DWF.
   Forgot to update program to reflect change in FSC_FIELD. Fixed 26 April 2001. DWF.
   Changed BOOKMAN keyword to BKMAN to avoid conflict with BOOKSTYLE keyword. 26 April 2001. DWF.
   Modified the System Defaults to say "None" if none is used. Improved documentation. 10 September 2001. DWF.
   Added the ability to specify a filename at the same time as a Default Setup. 10 September 2001. DWF.
   Fixed a small problem in not setting new page sizes appropriately. 22 May 2002. DWF.

(See pro/psconfig/fsc_psconfig__define.pro)


FUNC_CCM_FITRV, PARAMS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   func_ccm_fitrv, params

 PURPOSE:
   compute chi2 for the ccm_fitrv function

 CALLING SEQUENCE:
   called via a fitting program -- see ccm_fitrv.pro

 INPUTS:
   params   -   R_V  = params[0];   norm = params[1]

 OUTPUTS:
   chi2     -  chi squared for fit. 

 COMMENTS:
   wavelength, redfac, and weights are passed via common block. 
   unit weights are assumed if none are passed. 

 REVISION HISTORY:
   2003-Sep-10  Written by D. Finkbeiner & N.Padmanabhan, Princeton

(See pro/dust/func_ccm_fitrv.pro)


FUNC_FIT

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

 PURPOSE:
   Fit X, Y positions to a functional form.

 CALLING SEQUENCE:
   res = func_fit( x, y, ncoeff, [invvar=, function_name=, $
    ia=, inputans=, yfit=, double=double, _EXTRA= ]

 INPUTS:
   x          - X values (independent variable)
   y          - Y values (dependent variable)
   ncoeff     - Number of coefficients to fit
   invvar     - Weight values (inverse variance)

 OPTIONAL KEYWORDS:
   function_name - Function to fit; options are:
                'legendre'
                'chebyshev'
                Default to 'legendre'
   ia         - Array specifying free (1) and fixed (0) variables [NCOEFF]
   inputans   - If holding parameters fixed, set this array to those values
                [NCOEFF]
   double     - If set, or if X, Y, or INVVAR are double-precision, then
                return double-precision values
   _EXTRA     - Optional keywords for fitting function

 OUTPUTS:
   res        - Fit coefficients [NCOEFF]

 OPTIONAL OUTPUTS:
   yfit       - Fit evaluated at the points X

 COMMENTS:

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:
   fchebyshev()
   flegendre()
   fpoly()

 REVISION HISTORY:
   10-Sep-1999  Written by S. Burles
   16-Nov-1999  Modified by D. Schlegel to never fit more coefficients
                than there are data points.
   10-Jul-2001  Added fpoly, S. Burles

(See pro/trace/func_fit.pro)


GAREA

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   garea
 PURPOSE:
   Calculate area of spherical polygon by calling mangle utility garea
 CALLING SEQUENCE:
   area=garea(polygon [, tol=, /verbose])
 INPUTS:
   polygon - spherical polygon specification
 OPTIONAL INPUTS:
   tol - tolerance (arcsec)
   verbose - don't suppress garea output
 OUTPUTS:
 OPTIONAL INPUT/OUTPUTS:
 COMMENTS:
 EXAMPLES:
 BUGS:
 PROCEDURES CALLED:
 REVISION HISTORY:
   07-Nov-2002  Written by Mike Blanton, NYU

(See pro/mangle/garea.pro)


GAUSS1

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

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

 PURPOSE:
   Compute Gaussian curve given the mean, sigma and area.

 MAJOR TOPICS:
   Curve and Surface Fitting

 CALLING SEQUENCE:
   YVALS = GAUSS1(XVALS, [MEAN, SIGMA, AREA], SKEW=skew)

 DESCRIPTION:

  This routine computes the values of a Gaussian function whose
  X-values, mean, sigma, and total area are given.  It is meant to be
  a demonstration for curve-fitting.

  XVALS can be an array of X-values, in which case the returned
  Y-values are an array as well.  The second parameter to GAUSS1
  should be an array containing the MEAN, SIGMA, and total AREA, in
  that order.

 INPUTS:
   X - Array of X-values.

   [MEAN, SIGMA, AREA] - the mean, sigma and total area of the 
                         desired Gaussian curve.

 INPUT KEYWORD PARAMETERS:

   SKEW - You may specify a skew value.  Default is no skew.

   PEAK - if set then AREA is interpreted as the peak value rather
          than the area under the peak.

 RETURNS:

   Returns the array of Y-values.

 EXAMPLE:

   p = [2.2D, 1.4D, 3000.D]
   x = dindgen(200)*0.1 - 10.
   y = gauss1(x, p)

   Computes the values of the Gaussian at equispaced intervals
   (spacing is 0.1).  The gaussian has a mean of 2.2, standard
   deviation of 1.4, and total area of 3000.

 REFERENCES:

 MODIFICATION HISTORY:
   Written, Jul 1998, CM
   Correct bug in normalization, CM, 01 Nov 1999
   Optimized for speed, CM, 02 Nov 1999
   Added copyright notice, 25 Mar 2001, CM
   Added PEAK keyword, 30 Sep 2001, CM

  $Id: gauss1.pro,v 1.2 2006/02/07 22:38:32 schlegel Exp $

(See pro/mpfit/gauss1.pro)


GAUSS1P

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

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

 PURPOSE:
   Compute Gaussian curve given the mean, sigma and area (procedure).

 MAJOR TOPICS:
   Curve and Surface Fitting

 CALLING SEQUENCE:
   GAUSS1, XVALS, [MEAN, SIGMA, AREA], YVALS, SKEW=skew

 DESCRIPTION:

  This routine computes the values of a Gaussian function whose
  X-values, mean, sigma, and total area are given.  It is meant to be
  a demonstration for curve-fitting.

  XVALS can be an array of X-values, in which case the returned
  Y-values are an array as well.  The second parameter to GAUSS1
  should be an array containing the MEAN, SIGMA, and total AREA, in
  that order.

 INPUTS:
   X - Array of X-values.

   [MEAN, SIGMA, AREA] - the mean, sigma and total area of the 
                         desired Gaussian curve.

   YVALS - returns the array of Y-values.


 KEYWORD PARAMETERS:

   SKEW - You may specify a skew value.  Default is no skew.

 EXAMPLE:

   p = [2.2D, 1.4D, 3000.D]
   x = dindgen(200)*0.1 - 10.
   gauss1p, x, p, y

   Computes the values of the Gaussian at equispaced intervals
   (spacing is 0.1).  The gaussian has a mean of 2.2, standard
   deviation of 1.4, and total area of 3000.

 REFERENCES:

 MODIFICATION HISTORY:
   Transcribed from GAUSS1, 13 Dec 1999, CM
   Added copyright notice, 25 Mar 2001, CM

  $Id: gauss1p.pro,v 1.2 2006/02/07 22:38:32 schlegel Exp $

(See pro/mpfit/gauss1p.pro)


GAUSS2

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

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

 PURPOSE:
   Compute Gaussian curve given the mean, sigma and area.

 MAJOR TOPICS:
   Curve and Surface Fitting

 CALLING SEQUENCE:
   YVALS = GAUSS2(X, Y, [XCENT, YCENT, SIGMA, PEAK])

 DESCRIPTION:

  This routine computes the values of a Gaussian function whose
  X-values, mean, sigma, and total area are given.  It is meant to be
  a demonstration for curve-fitting.

  XVALS can be an array of X-values, in which case the returned
  Y-values are an array as well.  The second parameter to GAUSS1
  should be an array containing the MEAN, SIGMA, and total AREA, in
  that order.

 INPUTS:
   X - 2-dimensional array of "X"-values.
   Y - 2-dimensional array of "Y"-values.

   XCENT - X-position of gaussian centroid.
   YCENT - Y-position of gaussian centroid.

   SIGMA - sigma of the curve (X and Y widths are the same).

   PEAK - the peak value of the gaussian function.

 RETURNS:

   Returns the array of Y-values.

 EXAMPLE:

   p = [2.2D, -0.7D, 1.4D, 3000.D]
   x = (dindgen(200)*0.1 - 10.) # (dblarr(200) + 1)
   y = (dblarr(200) + 1) # (dindgen(200)*0.1 - 10.)
   z = gauss2(x, y, p)

   Computes the values of the Gaussian at equispaced intervals in X
   and Y (spacing is 0.1).  The gaussian has a centroid position of
   (2.2, -0.7), standard deviation of 1.4, and peak value of 3000.

 REFERENCES:

 MODIFICATION HISTORY:
   Written, 02 Oct 1999, CM
   Added copyright notice, 25 Mar 2001, CM

  $Id: gauss2.pro,v 1.2 2006/02/07 22:38:32 schlegel Exp $

(See pro/mpfit/gauss2.pro)


GAUSSPIX1D

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

 PURPOSE:
   Routine to evaluate a 1D gaussian function (plus polynomial terms)
   integrated over a pixel of width 1.

 CALLING SEQUENCE:
   gausspix, x, a, f, pder

 INPUTS:
   x          - Dependent variable [NX].
   a          - Coefficients:
                A[0] = center of the Gaussian in X
                A[1] = sigma width of the Gaussian
                A[2] = normalization of the Gaussian; total area = A[1] * A[2]
                A[3...] = polynomial coefficients for background terms

 OPTIONAL INPUTS:

 OUTPUTS:
   f          - Evaluated function [NX].
   pder       - Array of partial derivatives [NX,NCOEFF].

 OPTIONAL OUTPUTS:

 COMMENTS:
   This routine can be passed as a function to the IDL CURVEFIT function.

   If X is type DOUBLE, then the return values are also type DOUBLE;
   otherwise they are type FLOAT.

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:

 REVISION HISTORY:
   04-Aug-2000  Written by D. Schlegel, Princeton

(See pro/math/gausspix1d.pro)


GAUSS_OVERLAP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	  gauss_overlap
 PURPOSE: (one line)
   calculate log integral, covariance, and mean of product of two gaussians
 DESCRIPTION:
   calculate log integral, covariance, and mean of product of two gaussians
 CATEGORY:
       Numerical
 CALLING SEQUENCE:
	  gauss_overlap,mean1,covar1,mean2,covar2,mean=mean,covar=covar, $
	    logint=logint, invcovar=invcovar, /input_invcovar
 INPUTS:
	  mean1 - [N] mean of first gaussian
	  covar1 - [N, N] covariance of first gaussian
	  mean2 - [N] mean of second gaussian
	  covar2 - [N, N] covariance of second gaussian
 OPTIONAL INPUT PARAMETERS:
 KEYWORD PARAMETERS:
   /input_invcovar - covar1, covar2 are actually inverse covars
 OUTPUTS:
   mean - mean of global gaussian
   covar - covariance of global gaussian
   invcovar - inverse covariance of global gaussian
   logint - natural log of integral of global gaussian
 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
 PROCEDURE:
 MODIFICATION HISTORY:
	  Blanton and Roweis 2003-02-18j 

(See pro/math/gauss_overlap.pro)


GRIDND

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   gridnd
 PURPOSE:
   determine positions on a grid, for easy access
 CALLING SEQUENCE:
   gridnd, x [, ix=, grid=, ngrid=, binsize=, igrid= ]
 INPUTS:
   x - [M,N] positions in M-dimensions
 OPTIONAL INPUTS:
   binsize - grid size (default 1.)
 OUTPUTS:
   grid - [nx[0]*nx[1]*...*nx[M-1]] set of pointers to particles in
          each cell
   ngrid - [nx[0]*nx[1]*nx[2]*...*nx[M-1]] number of particles in
           each cell
   igrid - [N] position in grid
   xminmax - [2,M] limits of grid
   nx - [M] dimensions of grid
 COMMENTS:
   This code is BETA! Use at your own risk.
 REVISION HISTORY:
   12-Oct-2005  Written by Mike Blanton, NYU

(See pro/math/gridnd.pro)


GROUP_INDX

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   group_indx
 PURPOSE:
   given group indices, yield multiplicity, plus an index linked list
 CALLING SEQUENCE:
   group_indx, ingroup, multgroup=multgroup, firstgroup=firstgroup, $
      nextgroup=nextgroup
 INPUTS:
   ingroup - [N] group # of each element
 OUTPUTS:
   multgroup - [Ngroup] multiplicity of each group
   firstgroup - [Ngroup] first member of each group
   nextgroup - [N] for each member, the next member of its group
               (-1) if no more
 COMMENTS:
 BUGS:
 REVISION HISTORY:
   2003-03-05 written by Michael Blanton (NYU)

(See pro/misc/group_indx.pro)


GROUP_ON_MATCHES

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   group_on_matches
 PURPOSE:
   given a list of objects and matches between them, find the groups
 CALLING SEQUENCE:
   group_on_matches, matches [, first=, next=, mult=, in=]
 INPUTS:
   matches - [N] array of pointers to list of which objects are matched
 OUTPUTS:
   first - [Ngroup] first member of each group
   mult - [Ngroup] multiplicity of each group
   in - [N] what group an object is in 
   next - [N] next member of group an object is in (-1 if last)
 REVISION HISTORY:
   2005-Oct-3  Written by Mike Blanton, NYU

(See pro/math/group_on_matches.pro)


GROW_OBJECT

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

 PURPOSE:
   Identify objects as the contiguous non-zero pixels in an image.

 CALLING SEQUENCE:
   mask = grow_object( image, [ xstart=, ystart=, putval=, /diagonal, nadd= ]

 INPUTS:
   image      - Integer-valued image vector or array, where non-zero pixel
                values indicate that an object touches that pixel.

 OPTIONAL INPUTS:
   xstart     - Starting X position(s) for assembling the object; default to
                settting all pixels where IMAGE != 0.
   ystart     - Starting Y position(s) for assembling the object; default to
                settting all pixels where IMAGE != 0.
   putval     - Object ID(s) to put in MASK as positive-valued long integer;
                default to a unique integer (starting at 1) for each object.
                This can either be a scalar, or a vector with one element
                per XSTART,YSTART position.
   diagonal   - If set, then consider diagonally-offset pixels as contigous
                as well as pixels simply to the left, right, down, or up.

 OUTPUTS:
   mask       - Mask with object IDs; zeros indicate that there is no object
                in that pixel, and positive values are used as object IDs.
                Negative values are not allowed.

 OPTIONAL OUTPUTS:
   nadd       - Number of pixels added to all objects

 COMMENTS:
   Find the pixels that make up an "object" as the contiguous non-zero
   pixels in IMAGE that touch the pixel XSTART,YSTART.  All such pixels
   have MASK set to PUTVAL.

   If XSTART,YSTART,PUTVAL are not specified, then all objects are found
   in the image and assigned unique object IDs in MASK starting at 1.
   Note that in this case, max(MASK) is the number of objects.

   The memory usage is 9*(nx+2)*(ny+2) bytes in addition to the input
   image, where [nx,ny] are the dimensions of the input image.

 EXAMPLES:
   Create a random image of 0s and 1s, and identify all contiguous pixels
   as objects:
   IDL> image=smooth(randomu(123,100,100),5) GT 0.55 & mask = 0
   IDL> mask = grow_object(image)

 BUGS:

 PROCEDURES CALLED:
   Dynamic link to grow_obj.c

 REVISION HISTORY:
   20-May-2003  Written by D. Schlegel, Princeton

(See pro/image/grow_object.pro)


GSC_NSKY

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

 PURPOSE:
   Generate IDL structure for GSC catalogue at dec > -30 and m < 18.0

 CALLING SEQUENCE:
   gsc_nsky, [ catall ]
 
 INPUTS:
   <data files in $PHOTO_DATA/gsc>

 OUTPUTS:
   <data file (binary FITS table) in $PHOTO_DATA/kocat>

 OPTIONAL OUTPUTS:
   catall  - Structure containing all objects dec > -30 deg

 INPUT FILES:
   $GSC_DIR/n????/*.gsc
   $GSC_DIR/s????/*.gsc

 OUTPUT FILES:
   $GSC_DIR/gsc-Nsky.fits

 EXAMPLES:

 COMMENTS:
   Note: these catalogues are written as F9.5 ASCII FITS tables.  So 
    there is no reason to read them as double precision(?)
   For more information see gsc/readme.txt
   This can take a long time to run. 

 PROCEDURES CALLED:
   djs_angle_match()
   gsc_read_table()
   mwrfits

 REVISION HISTORY:
   Written 2002-Mar-27 by D. Finkbeiner

(See pro/astrom/gsc_nsky.pro)


GSC_READ_TABLE

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

 PURPOSE:
   Read one table from the GSC (Guide star catalogue)

 CALLING SEQUENCE:
   cat=gsc_read_table(fname, maglim=maglim, poserrlim=poserrlim)

 INPUTS:
   fname      - file name(s) of catalogue FITS table (e.g. 0060.gsc )
                      (can be array)
 KEYWORDS:
   maglim     - array of [lomag, himag] magnitudes to keep
   poserrlim  - discard stars with poserr higher than this limit
	
 OUTPUTS:
   cat        - structure returned by function call

 EXAMPLES:

 COMMENTS:
   Note: these catalogues are written as F9.5 ASCII FITS tables.  So 
   there is no reason to read them as double precision(?)

 REVISION HISTORY:
   2002-Mar-27  Written by D. Finkbeiner, Princeton

(See pro/astrom/gsc_read_table.pro)


GSSSPUTAST

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
    GSSSPUTAST
 PURPOSE:
    Put GSSS astrometry parameters into a given FITS header.

 CALLING SEQUENCE:
     gsssputast, hdr, astr

 INPUTS:
     hdr   - FITS header, string array.   HDR will be updated to contain
               the supplied astrometry.
     astr  - IDL structure containing the GSSS Astrometry information
               .CTYPE[2]   =  ['RA---GSS','DEC--GSS'] 
               .CRVAL[2]   = plate center Ra, Dec (from PLTRAH, PLTRAM etc.)
               .XLL,.YLL   = offsets lower lefthand corner (integers)
               .AMDX[13],.AMDY[13] = 12 transformation coefficients
               .XSZ,.YSZ   = X and Y pixel size in microns
               .PLTSCL     = plate scale in arc sec/mm
               .PPO3,.PPO6 = orientation coefficients

 OUTPUTS:
      hdr - (Modified) FITS header with updated astrometry cards.
            A brief HISTORY record is also added.

 REVISION HISTORY:
   Written 4 Nov 2000 - D. Finkbeiner

(See pro/astrom/gsssputast.pro)


GVERTS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   gverts
 PURPOSE:
   Get vertices along edge of a polygon
 CALLING SEQUENCE:
   verts=gverts(polygon)
 INPUTS:
   polygon - spherical polygon specification
 OUTPUTS:
   verts - [3,N] locations of vertices
 OPTIONAL INPUT/OUTPUTS:
 COMMENTS:
 EXAMPLES:
 BUGS:
 PROCEDURES CALLED:
 REVISION HISTORY:
   31-Jan-2002  Written by Mike Blanton, NYU

(See pro/mangle/gverts.pro)


HDR2STRUCT

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

 PURPOSE:
   Convert a string array with the format of a FITS header 
       into a single structure

 CALLING SEQUENCE:
   struct = hdr2struct(hdr)

 INPUTS:
   hdr:        FITS-(like) header (array of strings)

 OUTPUTS:
   struct:     Single structure with keyword(s) and comment(s)

 OPTIONAL INPUTS:

 COMMENTS:
   Only passes back anonymous structures as it appends as it works
    through all the header keywords.  Use struct_append to make an
    array from an array of headers.

 PROCEDURES CALLED:
   headfits()

 REVISION HISTORY:
   17-Jul-2001 Written by Burles

(See pro/fits/hdr2struct.pro)


HEALCART_HEADER

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

 PURPOSE:
   Generate mock header for healcart image

 CALLING SEQUENCE:
   header=healcart_header([ind, nside=nside])

 OPTIONAL INPUTS:
   ind      - healcart index array, used only for size information

 KEYWORDS:
   nside    - used for size information

 OUTPUTS:
   header   - FITS header appropriate for atv

 RESTRICTIONS:
   Must be used with idlutils version of atv and xy2ad.

 EXAMPLES:
   
 COMMENTS:
   Defines header for the approximately Cartesian reprojection of the 
    healpix map defined by healcart_ind.pro.
    atv knows how to use this header, even though it is not standard
    FITS. 

   Either nside or ind MUST be set. 

 REVISION HISTORY:
   2003-May-10  Written by Douglas Finkbeiner, Princeton

(See pro/healpix/healcart_header.pro)


HEALCART_IND

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

 PURPOSE:
   Generate index list for healcart projection

 CALLING SEQUENCE:
   ind = healcart_ind(data, /nest)

 INPUTS:
   data  - array to determine size (not used for anything else)
            if single element, interpret as Nside. 

 KEYWORDS:
   nest  - return index list for nested ordering

 OUTPUTS:
   ind   - index array to transform healpix to quasi-cartesian

 EXAMPLES:
   ind = healcart_ind(kband, /nest)
   atv, kband[ind]

 COMMENTS:
   This routine returns indices for the "healcart" projection, 
    which preserves the ring -> row mapping but stretches in
    longitude to make a (nearly) Cartesian projection. 
   This routine should only be used for examining healpix maps -- any
    quantitative computations should only be done on the healpix sphere. 

   Note: there are 4N-1 rows, not 4N

 REVISION HISTORY:
   2003-Feb-12  Written by Douglas Finkbeiner, Princeton

(See pro/healpix/healcart_ind.pro)


HEALNPIX

[Previous Routine] [Next Routine] [List of Routines]
 Returns the number of healpix pixels
 for a given resolution.

 npix = healnpix(res,[/nside])

 If nside is set, then it returns nside

 Nikhil Padmanabhan, Princeton, 
 July 29,2003

(See pro/healpix/healnpix.pro)


HEALPIX2ALM

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

 PURPOSE:
   Compute spherical harmonic transform (Alm) of a healpix map

 CALLING SEQUENCE:
   Alm = healpix2alm(data, lmax=lmax)

 INPUTS:
   data   - healpix array [npix, nmap] (must be real)
   
 KEYWORDS:
   lmax   - maximum l to compute (Default???)

 OUTPUTS:
   Alm    - dcomplex array of Alm[l, m, nmap] (lmax by lmax)

 OPTIONAL OUTPUTS:
   
 RESTRICTIONS:
   
 EXAMPLES:
   
 COMMENTS:
  Note - the Ylm are not even perfectly orthonormal on the healpix sphere
   print,total(spher_harm(theta,phi,5,3,/doub)*conj(spher_harm(theta,phi,9,3,/doub)))*!dpi*4,format='(F20.10)'
   
 REVISION HISTORY:
   2003-Feb-19  Written by Douglas Finkbeiner, Princeton
   2003-Nov-12  Can call with multiple maps at a time - DPF & NP

(See pro/healpix/healpix2alm.pro)


HEALPIX_CL

[Previous Routine] [Next Routine] [List of Routines]
 
 A rapid power spectrum computation
 code. Doesn't try to do *anything*
 fancy or clever --- just straight
 spherical transforms and averaging.

 cl =  healpix_cl(data, [lmax=lmax], cross=cross_data)

 data === healpix array in ring format (can be multiple maps)
 lmax=lmax === lmax sent to healpix2alm
 cross === If you want to compute a cross power spectrum, 
           then send the second healpix map here. Must be the
           same resolution

 Nikhil Padmanabhan, Princeton 
 August 25, 2003

(See pro/healpix/healpix_cl.pro)


HEALPIX_RING_WEIGHT

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

 PURPOSE:
   read healpix ring weight files

 CALLING SEQUENCE:
   wt = healpix_ring_weight(nside, iring=iring)

 INPUTS:
   nside   - healpix nside
   
 OUTPUTS:
   wt = the ring weights (4*nside-1 element array)

 OPTIONAL OUTPUTS:
   iring = ring number index array for each pixel (12*nside^2 array)
   
 RESTRICTIONS:
   breaks at nside > 8192

 BUGS:
   The method of computing iring is really dumb and slow, but works. 
   
 COMMENTS:
   Gorski stores weight-1 as a float; we return weight as a double.
   Because the weight array is symmetric, Gorski only stores half; we 
     return the whole array for simplicity. 
   The new mrdfits() (in v5_0_2b) replaces a " " in binary fits table
   field names with "_" instead of removing it.  Current version of
   this routine works with both new and old mrdfits().
   
 REVISION HISTORY:
   2003-Mar-11  Written by Douglas Finkbeiner, Princeton
   2003-Nov-12  Cache outputs - DPF & NP
   2004-Aug-09  Fix fatal bug with new mrdfits().

(See pro/healpix/healpix_ring_weight.pro)


HEAL_REBIN

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

 PURPOSE:
   rebin ring ordered healpix maps to different Nside

 CALLING SEQUENCE:
   newmap = heal_rebin(oldmap, newnside)

 INPUTS:
   oldmap   - original map, ring order

 OUTPUTS:
   newmap   - new rebinned map, ring order

 EXAMPLES:
   
 COMMENTS:
   Only call with ring-ordered maps.
   Use IDL rebin() if your map is already nested order. 

 REVISION HISTORY:
   2003-Dec-04  Written by Douglas Finkbeiner, Princeton

(See pro/healpix/heal_rebin.pro)


HEAL_SMOOTH

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

 PURPOSE:
   Smooth ring-ordered healpix maps with spherical harmonic convolution

 CALLING SEQUENCE:
   smooth_map = heal_smooth(map, fwhm_arcmin, nside=, alm=, lmax= )

 INPUTS:
   map         - healpix map
   fwhm_arcmin - fwhm of gaussian smoothing kernel (arcmin)
   nside       - set if map not set and alms passed
   alm         - set if alms already known (saves time)
   lmax        - maximum l value to use

 OPTIONAL INPUTS:
   
 KEYWORDS:
   
 OUTPUTS:
   
 OPTIONAL OUTPUTS:
   
 EXAMPLES:
   
 COMMENTS:
   Input maps must be ring ordered - use nest2ring otherwise
   
 REVISION HISTORY:
   2003-Mar-14  Written by Douglas Finkbeiner, Princeton
   2004-Aug-16  Avoid floating underflow in beam transform - DPF

(See pro/healpix/heal_smooth.pro)


HELIOCENTRIC

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

 PURPOSE:
   Compute correction term to add to velocities to convert to heliocentric.

 CALLING SEQUENCE:
   vcorr = heliocentric( ra, dec, [ epoch, jd=, tai=, $
    longitude=, latitude=, altitude= ] )

 INPUTS:
   ra             - Right ascension [degrees]
   dec            - Declination [degrees]
   epoch          - Epoch of observation for RA, DEC; default to 2000.

 OPTIONAL KEYWORDS:
   jd             - Decimal Julian date.  Note this should probably be
                    type DOUBLE.
   tai            - Number of seconds since Nov 17 1858; either JD or TAI
                    must be specified.  Note this should probably either
                    be type DOUBLE or LONG64.
   longitude      - Longitude of observatory;
                    default to (360-105.820417) deg for APO
   latitute       - Latitude of observatory; default to 32.780361 deg for APO
   altitude       - Altitude of observatory in meters;
                    default to 2788 m for APO

 OUTPUTS:
   vcorr          - Velocity correction term, in km/s, to add to measured
                    radial velocity to convert it to the heliocentric frame.

 OPTIONAL OUTPUTS:

 COMMENTS:

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:
   baryvel
   ct2lst

 REVISION HISTORY:
   09-May-2000  Written by S. Burles & D. Schlegel

(See pro/coord/heliocentric.pro)


HELIO_TO_LG

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   helio_to_lg
 PURPOSE:
   Convert heliocentric redshifts to Local-Group-centric redshifts.
 CALLING SEQUENCE:
   z_lg = helio_to_lg(z_helio,ra,dec)
 INPUTS:
   z_helio   - heliocentric redshift
   RA        - right ascension (deg, J2000)
   Dec       - declination (deg, J2000)
 OUTPUTS:
   z_lg      - local-group-centric redshift
 REVISION HISTORY:
   Originally imported by Hogg, 2002-08 or so.
   MRB corrected sign error in correction 2004-04-08 (affected tags
   v5_0_0 and previous)

(See pro/coord/helio_to_lg.pro)


HMS2DEC

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

 PURPOSE:
   convert base-sixty string to decimal

 CALLING SEQUENCE:
   decimal = hms2dec(hmsstring)

 INPUTS:
   hmsstring - e.g. 'HH:MM:SS.S' or 'HHhMMmSS.S' or 'HH MM SS.S' etc. 

 OUTPUTS:
   decimal  - double-precision decimal number

 RESTRICTIONS:
   
 EXAMPLES:
   ra = hms2dec(ra_string)*15

 COMMENTS:
   The strpos() loop below looks awkward but is probably a lot 
    faster than repstr()
   I left most of the 20th century code intact, so I wouldn't
    introduce any change in behavior. 

 REVISION HISTORY:
   Written by Douglas Finkbeiner in ancient times
   2000-Nov-29 fixed to handle "d" properly! - DPF
   2005-Sep-16 call self recursively for array - DPF

(See pro/coord/hms2dec.pro)


HOGG_ARROW

[Previous Routine] [Next Routine] [List of Routines]
 NAME:				Hogg_ARROW
 PURPOSE:	Draw a vector(s) with an arrow head
 CATEGORY:	Graphics
 CALLING SEQUENCE:
	Hogg_ARROW, x0, y0, x1, y1
 INPUTS:
	(x0, y0) = coordinates of beginning of vector(s).  May be arrays
		or scalars. Coordinates are in DEVICE coordinates
		unless otherwise specified.
	(x1, y1) = coordinates of endpoint (head) of vector.
		x0, y0, x1, y1 must all have the same number of elements.
 KEYWORD PARAMETERS:
	DATA - if set, implies that coordinates are in data coords.
	NORMALIZED - if set, coordinates are specified in normalized coords.
	HSIZE = size of arrowhead.  Default = 1/64th the width of the device,
		(!D.X_SIZE / 64.).
		If the size is positive, it is assumed to be in device
		coordinate units.  If it is NEGATIVE, then the head length
		is set to the vector length * abs(hsize), giving heads
		proportional in size to the bodies.  The size is defined as
		the length of each of the lines (separated by 60 degrees)
		that make the head.
	COLOR = drawing color.  Default = highest color index.
	HTHICK = thickness of heads.  Default = 1.0.
	SOLID = if set, make a solid arrow, using polygon fills, looks better
		for thick arrows.
	THICK = thickness of body.    Default = 1.0.
       HEAD_ANGLE = half-angle of arrow head in degrees.  Default = 30.0
 OUTPUTS:
	No explicit outputs.
 SIDE EFFECTS:
 RESTRICTIONS:
 PROCEDURE:
	Straightforward.
	Examples:
  		Draw an arrow from (100,150) to (300,350) in DEVICE units.
	Hogg_ARROW, 100, 150,  300, 350

		Draw a sine wave with arrows from the line Y=0 to
		sin(x/4).
	X = FINDGEN(50)
	Y = SIN(x/4)		;Make sin wave
	PLOT, X, Y
	Hogg_ARROW, X, REPLICATE(0,50), X, Y, /DATA
 MODIFICATION HISTORY:
	DMS, Feb, 1992.
	DMS, Sept, 1992.  Added /SOLID.
       2005-03-08 - added head_angle -- Hogg (NYU)

(See pro/plot/hogg_arrow.pro)


HOGG_AUTOCROP_IMAGE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_autocrop_image
 PURPOSE:
   remove whitespace border on image read by read_image
 REVISION HISTORY:
   2003-01-31  written - Hogg

(See pro/plot/hogg_autocrop_image.pro)


HOGG_BWIFY

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_bwify
 PURPOSE:
   make b/w JPG image from color JPG image
 INPUTS:
   infile       - file name of color image
   outfile      - file name for b/w image
 OPTIONAL INPUTS:
   rebinfactor  - make outfile smaller by factor rebinfactor
 BUGS:
   - Just uses the r image; it should have various options for how to
     make the b/w image from the color one.
   - Always inverts; this should be an option.
 REVISION HISTORY:
   2004-01-07  commented - Hogg

(See pro/rgbcolor/hogg_bwify.pro)


HOGG_DIRECTIONS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_directions
 PURPOSE:
   Overplot directions to other sky locations on a picture of the
   sky.
 INPUTS:
   aref,dref  - reference RA,Dec
   aa,dd      - RA,Dec lists for things to point to
   name       - list of names of those things
   hdr        - FITS header with relevant astrometry structure
 OPTIONAL INPUTS:
   length     - length of arrows in degrees; default 1/60
 OUTPUTS:
   [overlay on currently open plot]
 BUGS:
   - Not tested.
   - Doesn't work with GSSS headers.
   - Hacks from nw_ad_grid duplicated here, stupidly.
 REVISION HISTORY:
   2005-09-11  started - Hogg (NYU)

(See pro/rgbcolor/hogg_directions.pro)


HOGG_GREYSCALE_PLOT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_greyscale_plot
 PURPOSE:
   Make a pretty greyscale plot from an astronomical image.
 CALLING SEQUENCE:
   hogg_greyscale_plot, data,filename
 INPUTS:
   data       the image
   filename   name for the output PostScript file
 OPTIONAL INPUTS:
   pixscale   units per pixel, eg arcmin/pixel
   scalename  units, eg "arcmin"
   lo,hi      levels to appear totally black (lo) and totally white (hi)
              (these are in terms of sigma if sigma keyword is set); if
              hi<lo, the image is made negative
   title      title for the plot
   xpt,ypt    x and y vectors of points to overplot -- set symbols with
                psym and !P.SYMSIZE
   psym       plotting symbol (may be vector)
 OUTPUTS:
              a PostScript file called filename
 KEYWORDS:
   sigma      when set, take lo and hi to be in terms of the sigma in the
              center part of the image from djs_iterstat, and relative to the
              mean from iterstat
   noaxes     don't plot axes and labels
 COMMENTS:
   The source code can be easily modified to include contouring.  In fact
   the next revision ought to add optional contouring keywords and inputs.
 BUGS/FEATURES:
   There may be something wrong with the axes; check few-pixel images.
   No contouring available (but see "COMMENTS" and the source code).
   Probably doesn't work on multi-plot pages; not really checked.
 REVISION HISTORY:
   1999-08-01  Written - Hogg
   2001-05-01  Fonts improved - Hogg
   2002-09-16  Added overplotting - Hogg

(See pro/plot/hogg_greyscale_plot.pro)


HOGG_HISTOGRAM

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_histogram
 PURPOSE:
   Multi-dimensional histogramming function.
 CALLING SEQUENCE:
   hist = hogg_histogram(data,range,nbin,weight=weight,err=err)
 INPUTS:
   data     - [d,M] array of d-dimensional data values
   range    - [2,d] min and max value for every dimension
   nbin     - [d] array of numbers of bins in each direction
 OPTIONAL INPUTS:
   weight   - [M] array of weights for the data points
 OUTPUTS:
   hist     - [d,P] array of numbers of points (or total weight) in each bin
 OPTIONAL OUTPUTS:
   err      - [d,P] array of Poisson errors
 BUGS:
   Slow -- very slow.
   Not memory-efficient.
   Doesn't deal well with small bin sizes.
   Doesn't output grid bin positions.
 COMMENTS:
   Doesn't divide by bin "volumes".
 REVISION HISTORY:
   2003-07-17  written - Hogg (NYU and NYC Criminal Court)

(See pro/image/hogg_histogram.pro)


HOGG_IAU_NAME

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_iau_name
 PURPOSE:
   properly format astronomical source names to the IAU convention
 INPUTS:
   ra         - J2000 deg
   dec        - J2000 deg
   prefix     - survey prefix
 OPTIONAL INPUTS:
   precision  - how many decimal places to put on dec; ra gets one more
 COMMENTS:
   Defaults to SDSS name conventions.
   Don't EVER use goddard/pro/astro/adstring.pro.
 BUGS:
   Enforces J2000 "J".
   Doesn't deal properly with precision<0 names, which *can* exist.
 REVISION HISTORY:
   2004-10-24  started by Hogg (NYU)

(See pro/misc/hogg_iau_name.pro)


HOGG_IMAGE_OVERLAY

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_image_overlay
 PURPOSE:
   Bitmap PostScript file to make an image overlay.
 CALLING SEQUENCE:
   overlay= hogg_image_overlay(psfile,naxis1,naxis2)
 EXAMPLES:
 INPUTS:
   psfile     - input filename
   naxis1     - width in pixels to make overlay
   naxis2     - height in pixels
 OPTIONAL INPUTS:
   factor     - integer factor to use for antialiasing; default 2;
                set to 1 for no antialiasing
 OUTPUT:
   overlay    - overlay with plot material added
 COMMENTS:
 BUGS:
   - Relies on horrifying UNIX bitmapping code.
   - Makes insecure intermediate PPM file.
 DEPENDENCIES:
   pstopnm etc
 REVISION HISTORY:
   2004-02-28  written - Hogg

(See pro/rgbcolor/hogg_image_overlay.pro)


HOGG_IMAGE_OVERLAY_PLOT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_image_overlay_plot
 PURPOSE:
   Make bitmapped overlay for rgb images.
 CALLING SEQUENCE:
   hogg_image_overlay_plot, xx,yy,naxis1,naxis2,overlay, $
                            [extras for plot procedure]
 EXAMPLES:
 INPUTS:
   xx,yy      - points to plot
   naxis1     - width in pixels to make overlay
   naxis2     - height in pixels
   overlay    - overlay to be added to (fine if not set)
   [extras]   - plotting inputs, just like for "plot" procedure
 OPTIONAL INPUTS:
   factor     - integer factor to use for antialiasing; default 2;
                set to 1 for no antialiasing
 OUTPUT:
   overlay    - overlay with plot material added
 COMMENTS:
   - Never makes axes!
 BUGS:
   - Relies on horrifying UNIX bitmapping code.
   - Makes insecure intermediate PS file.
 DEPENDENCIES:
   pstopnm etc
 REVISION HISTORY:
   2004-02-28  written - Hogg

(See pro/rgbcolor/hogg_image_overlay_plot.pro)


HOGG_INTERVAL

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_interval
 PURPOSE:
   find best interval for tickmarks on a plot
 INPUTS:
   range     - the range for the axis
 OPTIONAL INPUTS:
   nticks    - the approximate, desired number of ticks; default 5
 BUGS:
   Goes insane if range contains NaN.
 REVISION HISTORY:
   2002-03-25  written - Hogg

(See pro/plot/hogg_interval.pro)


HOGG_ITERATED_AD2XY

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_iterated_ad2xy
 PURPOSE:
   Same as ad2xy, but assuming that xy2ad is perfect.
 COMMENTS:
   Starts with a first guess that everything is at (x,y)=(0,0) and
     then uses Newton's method to iterate to the correct (x,y)
     values.
 INPUTS:
   a,d    - vectors of RA,Dec
   astr   - astrometric structure
 OPTIONAL INPUTS:
   tol    - maximum allowed angular difference (deg) between input
            a,d values and the values obtained by running xy2ad on
            the output; default to 0.01/3600.0 (0.01 arcsec)
 OUTPUTS:
   x,y    - vectors of x,y
 REVISION HISTORY:
   2005-09-04  started - Hogg (NYU)

(See pro/astrom/hogg_iterated_ad2xy.pro)


HOGG_ITER_LINFIT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_iter_linfit
 PURPOSE:
   Perform iterated linear least-squares fit with sigma-clipping.
 COMMENTS:
   Solves the over-constrained equation yy=aa##xx, where the yy are
     the "data" and the xx are the "parameters".
 CALLING SEQUENCE:
   hogg_iter_linfit, aa,yy,ww,xx [,covar=covar]
 INPUTS:
   aa      - input matrix, either transposition is fine
   yy      - input vector of data in equation yy=aa##xx
   ww      - weights for the components of yy; should be proportional to
             (1/err^2); these are assumed to be exactly (1/err)^2 if keyword
             "truesigma" is set
 OPTIONAL INPUTS:
   nsigma  - number of sigma for clipping; defaults to 3.0
   maxiter - maximum number of clipping iterations; defaults to 100
 KEYWORDS
   median  - clip by deviation from median rather than from mean
   verbose - output blow-by-blow
   sacred  - don't update ww values to indicate clipped-out data points
   truesigma - don't rescale weights and covariance matrix -- assume that the
               supplied weights are exactly 1/sigma^2
 OUTPUTS:
   xx      - output parameters in equation yy=aa##xx
   covar   - covariance matrix for the fit parameters
   ww      - ww values set to zero where data points clipped, and re-
             scaled so that chisq^2 is unity per degree of freedom, unless
             keyword "sacred" is set
 EXAMPLE:
   Linear regression of ydata (with inverse variance ydata_ivar) on
   xdata, with 5-sigma clipping:
     aa= dblarr(2,n_elements(xdata))
     aa[0,*]=1.D0
     aa[1,*]=xdata
     hogg_iter_linfit, aa, ydata, ydata_ivar, coeffs, covar=covar, nsigma=5
   Resulting coefficients are in coeffs[0] and coeffs[1] 
 BUGS:
   Covariance matrix is an approximation which assumes that the rms of the
     fit is consistent with the errors in the yy, or something like that.
     This could be changed if the input weights were always the true
     1/sigma^2 values.
 REVISION HISTORY:
   2000-Jun-03  written by Hogg, IAS
   2000-Jun-12  output covariance matrix - Hogg
   2000-Sep-06  added sacred keyword and updated ww matrix - Hogg
   2001-Apr-10  allow rejected points to return to fit - Hogg

(See pro/math/hogg_iter_linfit.pro)


HOGG_MAKE_ASTR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_make_astr
 PURPOSE:
   Generate the astrometric header for a particular pointing and
   orientation.
 CALLING SEQUENCE:
   astr= hogg_make_astr(racen,deccen,dra,ddec $
                        [,pixscale=pixscale] [etc])
 INPUTS:
   racen    - Central RA [deg]
   deccen   - Central DEC [deg]
   dra      - Size in the X dimension; default to 0.5 deg
   ddec     - Size in the Y dimension; default to 0.5 deg

 OPTIONAL INPUTS:
   pixscale    - Pixel scale (deg); default 1.0/3600
   orientation - angle (deg) for the north vector to make relative to
                 straight up (y direction), CCW being positive
   npixround   - round array dimensions (naxis1 and naxis2) to nearest
                 factor of npixround; default to 8.
 KEYWORDS:
   orthographic  - Make orthographic "-SIN" header instead of
                   gnomonic "-TAN" header.
 OUTPUTS:
   astr     - Astrometry structure with NAXIS keyword added
 OPTIONAL OUTPUTS:
   pixscale  - Set, if not input
 COMMENTS:
 EXAMPLES:
 BUGS:
 REVISION HISTORY:
   2003-Nov-21   Written by D. Schlegel (Princeton) & D. Hogg (NYU)
   2003-Dec-02   Modified to produce simpler headers - Hogg
   2004-Apr-18   Use make_astr to define astrom structure - DPF
   2004-Jun-17   Modified to make "orthographic" headers on request - Hogg
   2005-Aug-31   Changed name and put into idlutils - Hogg

(See pro/astrom/hogg_make_astr.pro)


HOGG_MAKE_IMAGE_LABEL

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_make_image_label
 PURPOSE:
   make text label for RGB images
 CALLING SEQUENCE:
   label= hogg_make_image_label(title,naxis1, [subtitle1=,subtitle2=])
 EXAMPLES:
   label= hogg_make_image_label('M51',2048, $
     subtitle1='data from the Sloan Digital Sky Survey', $
     subtitle2='image by Hogg, Wherry, Blanton, Finkbeiner, Schlegel')
 INPUTS:
   title      - main title text
   naxis1     - width in pixels to make the label
 OPTIONAL INPUTS:
   subtitle1  - first subtitle
   subtitle2  - second subtitle; defaults to idlutils plug
 OUTPUT:
   label      - [naxis1,n2] image containing text
 COMMENTS:
 BUGS:
   - Format and label padding all hard-wired.
   - Makes insecure temporary LaTeX file etc.
   - Relies on horrifying UNIX bitmapping code.
   - Slightly odd behavior if subtitles 1 and 2 are both empty.
 DEPENDENCIES:
   LaTeX etc
   pstopnm etc
 REVISION HISTORY:
   2003-12-05  written - Hogg

(See pro/rgbcolor/hogg_make_image_label.pro)


HOGG_MANYD_MEANPLOT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_manyd_meanplot
 PURPOSE:
   plot N+1-dimensional data sets, in the mean!
 INPUTS:
   weight       [N] array of data-point weights
   point        [d,N] array of data points - N vectors of dimension d
   zdim         index of quantity to be averaged in the plots
   psfilename   name for PostScript file; if no filename is given, then the
                  plots will simply be sent to the currently active device
 OPTIONAL INPUTS:
   nsig         number of sigma for half-width of each plot; default 5
   dbin         [d] array of bin widths for averaging
   label        [d] array of axis labels; default 'x_i'
   range        [2,d] array of plotting ranges
   xdims,ydims  indices of data dimensions to use on each x and y axis
   axis_char_scale size of characters on labels
   default_font font command to send to set font for plotting
 KEYWORDS:
   [etc]        [options for hogg_meanplot, see documentation]
 OUTPUTS:
 OPTIONAL OUTPUTS:
 BUGS:
   WAY too much duplicated code with hogg_manyd_scatterplot.
 DEPENDENCIES:
 REVISION HISTORY:
   2003-01-12  translated from hogg_manyd_scatterplot

(See pro/plot/hogg_manyd_meanplot.pro)


HOGG_MANYD_SCATTERPLOT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_manyd_scatterplot
 PURPOSE:
   plot N-dimensional data sets
 INPUTS:
   weight       [N] array of data-point weights
   point        [d,N] array of data points - N vectors of dimension d
   psfilename   name for PostScript file; if no filename is given, then the
                  plots will simply be sent to the currently active device
 OPTIONAL INPUTS:
   nsig         number of sigma for half-width of each plot; default 5
   label        [d] array of axis labels; default 'x_i'
   range        [2,d] array of plotting ranges
   xdims,ydims  indices of data dimensions to use on each x and y axis
   axis_char_scale size of characters on labels
   default_font font command to send to set font for plotting
   extrafun     name of procedure to call after each plot for overplotting
                (procedure takes two inputs: d1 and d2 indicating
                x and y dimensions of the current plot)
   title        puts string title on top of page
 KEYWORDS:
   nodata       don't plot anything at all, just axes!
   meanweight      - plot the mean of the weight values that land in
                     that pixel, rather than the total; don't use
                     with /conditional!
   [etc]        [options for hogg_scatterplot, see documentation]
 OUTPUTS:
 OPTIONAL OUTPUTS:
   manyd        [nx,ny,NX,NY] data
 BUGS:
   Can get infinite plot ranges.
 DEPENDENCIES:
   hogg_plot_defaults
   hogg_scatterplot
   plus much, much more
 REVISION HISTORY:
   2002-12-14  re-constructed from ex_max_plot -- Hogg

(See pro/plot/hogg_manyd_scatterplot.pro)


HOGG_MCMC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_mcmc
 PURPOSE:
   Make a Markov Chain Monte Carlo chain.
 INPUTS:
   seed       - random number seed for randomu()
   step_func  - function that takes a step in parameter space
   like_func  - function that computes the likelihood
   nstep      - number of links
   pars       - initial parameters (can be an array or structure)
 KEYWORDS:
   log        - like_func returns log_e(likelihood), not straight
                likelihood
 OUTPUTS:
   pars       - array of parameters, sorted from most to least likely
   like       - array of likelihoods for the pars
 REVISION HISTORY:
   2005-03-31  started - Hogg

(See pro/mcmc/hogg_mcmc.pro)


HOGG_MCMC_STEP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_mcmc_step
 PURPOSE:
   Make one step in a Markov Chain Monte Carlo.
 INPUTS:
   seed       - random number seed for randomu()
   pars       - initial parameters (can be an array or structure)
   like       - initial likelihood
   step_func  - function that takes a step in parameter space
   like_func  - function that computes the likelihood
 KEYWORDS:
   log        - like_func returns log_e(likelihood), not straight
                likelihood
 OUTPUTS:
   newpars    - new parameters
   newlike    - new likelihood
 BUGS:
   - I made up the algorithm based on things I sort-of remember.
 REVISION HISTORY:
   2005-03-31  started - Hogg

(See pro/mcmc/hogg_mcmc_step.pro)


HOGG_MCMC_TEST

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_mcmc_test
 PURPOSE:
   Test the hogg_mcmc code.
 REVISION HISTORY:
   2005-03-31  started - Hogg

(See pro/mcmc/hogg_mcmc_test.pro)


HOGG_MEANPLOT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_meanplot
 PURPOSE:
   plot sliding mean of one quantity vs two others
 COMMENTS:
   Doesn't overplot -- only plots.  This is because IDL blots
     out any other information on the plot anyway.
 INPUTS:
   x,y         - data values
   z           - quantity to average
 OPTIONAL INPUTS:
   weight      - weighting for data points; default unity
   xrange      - x range; default to the number > minnum area
   yrange      - y range; same default
   dxbin       - size of boxes in x-dir; default to a function of
                 first and second moments 
   dybin       - size of boxes in y-dir; same default
   levels      - contour levels; default to a function of image range
   minnum      - minimum number of points in a sliding box to plot;
                 default 100
   c_colors    - fill colors
   c_thick     - contour line thicknesses
   axis_char_scale - scale to apply to axis labels
   nearest     - take mean over nearest few points based on this number
                 (instead of a fixed smoothing scale)
 KEYWORDS:
   nofill      - don't fill the contours with color
   noperimeter - don't plot contour at minnum
   nobox       - don't plot box
   nolines     - don't plot lines between contours
   nodata      - don't plot anything other than axes
   maskonly    - plot only the minnum mask
   nocontourlabels  - don't label the contours
   input_mean  - don't recalculate means, use input in bin_mean
   overplot    - don't remake axes, just plot over
 OPTIONAL INPUT/OUTPUTS:
   bin_mean    - calculated mean value (or input mean value if 
                 /input_mean set) in each bin
   bin_scatter - calculated scatter around the mean in each bin
   bin_weight  - total weight in each bin
   bin_number  - total number of data points in each bin
 COMMENTS:
   "nearest" input should be used with caution --- this is generally
     a BAD way to smooth!
 REVISION HISTORY:
   2003-01-08  written - Hogg

(See pro/plot/hogg_meanplot.pro)


HOGG_MRDFITS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   HOGG_MRDFITS
 PURPOSE:
   Wrapper on MRDFITS() to read in a FITS file one chunk at a time
 CALLING SEQUENCE:
 INPUTS:
   see MRDFITS
 KEYWORDS:
   see MRDFITS
   nrowchunk  - Number of rows to read at a time; default to 2880
 COMMENTS:
   Useful when "columns" is set, so you can get a couple
   of columns without holding the whole file in memory
 OUTPUTS:
   see MRDFITS
 REVISION HISTORY:
   2002-02-08  written by Hogg

(See pro/fits/hogg_mrdfits.pro)


HOGG_NAME2RADEC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_name2radec
 PURPOSE:
   Takes properly-formatted iau name in "J" format and converts it into ra,dec
   USE AT YOUR OWN RISK; NO IMPLIED WARRANTY
 EXAMPLES:
   IDL> hogg_name2radec, 'SDSS_J013713.84-092820.4',ra,dec
   IDL> print, ra,dec
        24.307671      -9.4723336
   IDL> print, hogg_iau_name(ra,dec)
   SDSS J013713.84-092820.4
 INPUTS:
   name       - name
 OUTPUTS:
   ra         - J2000 deg
   dec        - J2000 deg
 OPTIONAL INPUTS:
 COMMENTS:
   Doesn't require anything particular *before* the J, but it assumes
     (dumbly) that the RA begins at the last J.
 BUGS:
   USE AT YOUR OWN RISK; NO IMPLIED WARRANTY
   Requires J2000 "J".
   Ultra-brittle.
 REVISION HISTORY:
   2004-10-22  started by you know who

(See pro/misc/hogg_name2radec.pro)


HOGG_NED_NAME2RADEC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_ned_name2radec
 PURPOSE:
   Takes a name, throws it at NED, retreives RA, Dec (J2000)
   USE AT YOUR OWN RISK; NO IMPLIED WARRANTY
 INPUTS:
   name       - name
 OUTPUTS:
   ra         - J2000 deg
   dec        - J2000 deg
 OPTIONAL INPUTS:
 COMMENTS:
 BUGS:
   Does nasty things to the name to format it for URL-ifying.
   USE AT YOUR OWN RISK; NO IMPLIED WARRANTY.
   Relies on NED not changing in any substantial way!
 DEPENDENCIES:
   wget
 REVISION HISTORY:
   2005-02-01  started by you know who

(See pro/misc/hogg_ned_name2radec.pro)


HOGG_OPLOT_COVAR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_oplot_covar
 PURPOSE:
   Wrapper for oplot that plots covariance ellipses.
 CALLING SEQUENCE:
   hogg_oplot_covar, x,y,covar,...
 INPUT:
   x,y     - [N] arrays of points
   covar   - [2,2,N] array of symmetric covariance matrices
 KEYWORDS:
   fill    - make filled rather than outlined ellipses
 OPTIONAL INPUTS:
   nsigma  - plot n-sigma ellipse (default to 1)
   color   - color or vector of [N] colors
   thick   - line thickness or vector of [N] line thicknesses
   [keywords for IDL plot]
 COMMENTS:
   Allows color to be a [N] array.
 REVISION HISTORY:
   2002-04-11  written by Hogg

(See pro/plot/hogg_oplot_covar.pro)


HOGG_PLOTHIST

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_plothist
 PURPOSE:
   plot histogram of weighted points
 INPUTS:
   x           - data values
 OPTIONAL INPUTS:
   weight      - weighting for data points; default unity
   npix        - number of bins in range
   xrange      - x range; default minmax(x)
   yrange      - y range; default chosen dumbly!
   [etc]       - extras passed to "plot" command
 KEYWORDS:
   overplot    - overplot, don't plot anew
   ploterr     - plot Poisson error bars too
   log         - take log_10 before plotting
   meanweight  - plot the mean of the weights in each bin rather than
                 the total of the weights; don't divide by binwidth
   totalweight - plot the total weight; don't divide by binwidth
   dontplot    - just calculate, do not plot anything
 OPTIONAL OUTPUTS:
   xvec        - [npix] vector of x values of grid pixel centers
   hist        - the histogram itself (ie, the total weight in each
                 bin divided by the binwidth).
   err         - the Poisson uncertainties on each point (ie, the
                 sqrt of the sum of the squares of the weights,
                 divided by the binwidth).
 COMMENTS:
   Divides total weight in each bin by binwidth, unless /totalweight
   or /meanweight is set.
 BUGS:
   Doesn't check inputs.
   Super-slow!
 REVISION HISTORY:
   2002-12-14  written -- Hogg

(See pro/plot/hogg_plothist.pro)


HOGG_PLOT_DEFAULTS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_plot_defaults
 PURPOSE:
   Set plotting defaults for all "hogg_" plots
 CALLING SEQUENCE:
   hogg_plot_defaults
 REVISION HISTORY:
   2003-01-08  written - Hogg

(See pro/plot/hogg_plot_defaults.pro)


HOGG_READ_POSTSCRIPT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_read_postscript
 PURPOSE:
   read in a postscript file as an IDL data image
 INPUTS:
   filename
 OPTIONAL INPUTS:
   resolution   - in dots per inch; default 75
 KEYWORDS:
   noantialias  - don't do Hogg's antialiasing trick
 OUTPUTS:
   image        - [3,N,N] array of byte images for R,G,B planes
 BUGS:
   Makes DUMB temporary files; I am sure there is a way to make smart ones.
 REVISION HISTORY:
   2003-01-31  written - Hogg

(See pro/plot/hogg_read_postscript.pro)


HOGG_RGB_ENTROPY

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_rgb_entropy
 PURPOSE:
   Compute "entropy" of an RGB representation of an image
 INPUTS:
   colors    - [nx,ny,3] image of values in range [0.0,1.0]
   bits      - number of bits to assign per pixel per color (default 4)
 OUTPUT:
   entropy   - entropy of the representation
 BUGS:
 REVISION HISTORY:
   2004-03-20  started - Hogg

(See pro/rgbcolor/hogg_rgb_entropy.pro)


HOGG_SCATTERPLOT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_scatterplot
 PURPOSE:
   plot greyscale scatterplot with contours
 COMMENTS:
   Doesn't overplot -- only plots.  This is because the IDL tvscl blots
     out any other information on the plot.
   Compares cumulated grid to the *total* weight -- ie, including points
     outside the range (which is what you want; trust me).
 INPUTS:
   x,y         - data values
 OPTIONAL INPUTS:
   weight      - weighting for data points; default unity
   xnpix       - width of greyscale grid in pixels; default 0.3*sqrt(N)
   ynpix       - height of greyscale grid in pixels; same default
   xrange      - x range; default minmax(x)
   yrange      - y range; default minmax(y)
   levels      - contour levels; default in source code
   quantiles   - quantiles to plot on conditional plot; default
                 [0.25,0.5,0.75]
   cthick      - thickness for contours
   exponent    - stretch greyscale at exponent power; default 1.0
   satfrac     - fraction of pixels to saturate in greyscale; default 0
   darkest     - darkest shade at saturation; default 127; lower darker
   outliers_psym    - NEEDS DOCUMENTATION
   outliers_color   - NEEDS DOCUMENTATION
   outliers_symsize - NEEDS DOCUMENTATION
   [etc]       - extras passed to "plot" command
 KEYWORDS:
   conditional     - normalize each column separately
   labelcont       - label contours with numbers
   internal_weight - use only the points in the image to determine
                     contours
   nogreyscale     - don't plot the greyscale
   adqgreyscale    - do greyscale in the "ADQ" style (only works when
                     conditional is set)
   outliers        - NEEDS DOCUMENTATION
   meanweight      - plot the mean of the weight values that land in
                     that pixel, rather than the total; don't use
                     with /conditional!
 OPTIONAL OUTPUTS:
   xvec        - [xnpix] vector of x values of grid pixel centers
   yvec        - [ynpix] vector of y values of grid pixel centers
   grid        - the greyscale grid [xnpix,ynpix] that was plotted
   cumimage    - the cumulated grid [xnpix,ynpix] that was contoured
   outquantiles - the plotted quantiles (when /conditional is set)
   ioutliers   - indices of outlier points
 COMMENTS:
   When output, the grid is in units of unit_weight, not in 
   unit_weight per unit_x per unit_y (as you would want to do if 
   you wanted to directly compare two results using different
   resolution grids); the user will have to convert to that themselves.
 BUGS:
   Doesn't check inputs.
   Ought to specify saturation not as a fraction of pixels, but as a fraction
     of the total weight (ie, saturate inside a particular, specifiable
     confidence region).  This mod is trivial.
   Ought to specify min and max grey levels, and contour colors.
   Contour thicknesses hard-coded to unity.
 DEPENDENCIES:
   hogg_histogram
   plus much, much more
 REVISION HISTORY:
   2002-12-04  written --- Hogg

(See pro/plot/hogg_scatterplot.pro)


HOGG_SKY_DIRECTION

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_sky_direction
 PURPOSE:
   Return the direction (Delta-alpha,Delta-delta) of one RA, Dec
   relative to a reference RA, Dec.
 CALLING SEQUENCE:
   hogg_sky_direction, aref,dref,ap,dp,Da,Dd
 INPUT:
   aref,dref  - reference RA,Dec
   ap,dp      - RA,Dec of the point to which the arrow points
 OUTPUT:
   Da         - Delta-alpha (small change in RA*cos(Dec)) for arrow
   Dd         - Delta-delta (small change in Dec) for arrow
 COMMENTS:
   - Da,Dd comprise a vector of arbitrary length; it is the user's
     responsibility to re-scale it.
   - Da is not a change in RA, but a change in RA*cos(Dec).
 BUGS:
   - Inputs must all be scalars or else hell breaks loose.
 REVISION HISTORY:
   2005-09-10  started - Hogg (NYU)

(See pro/coord/hogg_sky_direction.pro)


HOGG_SNAP_INTEGER

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_snap_integer
 PURPOSE:
   Randomly snap floats or doubles to nearest integers up and down so
     that the mean is correct on average.
 CALLING SEQUENCE:
   ii= hogg_snap_integer(seed,xx)
 INPUTS:
   seed - long seed for randomu
   xx   - array of floating point numbers
 OUTPUTS:
   ii   - array of integers
 BUGS:
   Relies on "true" being 1.
 REVISION HISTORY:
   2003-08-13  written - Hogg

(See pro/math/hogg_snap_integer.pro)


HOGG_STRSPLIT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_strsplit
 PURPOSE:
   split strings on whitespace, except inside double quotes, plus other
     stuff specialized for yanny_read
 BUGS:
   demolishes the string
 REVISION HISTORY:
   2002-10-10  written - Hogg

(See pro/yanny/hogg_strsplit.pro)


HOGG_TP_SHIFT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_tp_shift
 PURPOSE:
   Shift tangent point on the sphere (CRVAL, in RA, Dec units),
   adjusting simultaneously the CD matrix (to deal with coordinate
   issues near the celestial poles).  The idea is to shift the WCS
   without substantially rotating the tangent-plane coordinates, even
   when near the poles.
 INPUTS:
   astr   - astrometry structure
   crval  - new crval (tangent point on the sphere) to insert
 OUTPUTS:
          - new astrometry structure
 REVISION HISTORY:
   2005-08-21  started - Hogg (NYU)

(See pro/astrom/hogg_tp_shift.pro)


HOGG_UNQUOTED_REGEX

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_unquoted_regex
 PURPOSE:
   return the regex which matches the first occurence of the given
     regex not inside quotemarks
 INPUT:
   regex      - naked regular expression
 OPTIONAL INPUT:
   quotemark  - thing to use as the quotation mark, default to '"'
 REVISION HISTORY:
   2002-10-11  written - Hogg

(See pro/yanny/hogg_unquoted_regex.pro)


HOGG_USERSYM

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_usersym
 PURPOSE:
   make an n-sided plotting point
 USAGE:
   hogg_usersym, N [,scale=scale,/diagonal]
   plot, x,y,psym=8
 INPUTS:
   N           - number of sides on the polygon
 OPTIONAL INPUTS:
   scale       - linear size
   _extra      - keywords for usersym (see usersym help page)
                 eg, /fill or thick=thick
 KEYWORDS
   diagonal    - rotate symbol through 1/2 of 1/N turns
 REVISION HISTORY:
   2002-04-09  written - Hogg

(See pro/plot/hogg_usersym.pro)


HOGG_WEIGHTED_MEAN_SURFACE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   hogg_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
   nearest   - use nearest few points based on this number, rather 
               than a fixed smoothing (use with caution!)
 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/hogg_weighted_mean_surface.pro)


HST_GUIDETEST

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

 PURPOSE:
   Decide if a list of potential HST guide stars are good by looking
   at the 2MASS and UCAC catalogs

 CALLING SEQUENCE:
   hst_guidetest, [ ra, dec, name=, filename=, searchrad=, select_tags=, $
    goodrad= ]

 INPUTS:

 OPTIONAL INPUTS:
   ra         - RA for each star [degrees]
   dec        - Declination for each star [degrees]
   name       - Name for each star; default to STAR-1, STAR-2, etc.
   filename   - Input ASCII file name with at least 3 columns:
                name, RA, Dec (where the coordinates are in degrees);
                if set, then this overrides the inputs RA, DEC, NAME
   searchrad  - Search radius between input coorinates and 2MASS and UCAC;
                default to 5./3600 degrees
   goodrad    - Maximum distance for a "good" HST guide star; default
                to 1.5/3600 arcsec
   select_tags- Names of tags to print

 OUTPUTS:

 OPTIONAL OUTPUTS:

 COMMENTS:
   The default is to return the following:
     NAME - The object names either from the first column of FILENAME,
            or from the input NAME
     DIST - Distance in arcsec to the nearest 2MASS star
     BL_FLG - Blend flags in J,H,K-bands, should be "111"
     CC_FLG - Contamination flags in J,H,K-bands, should be "000"
     GAL_CONTAM - Extended source contamination flag, should be "0"
     MP_FLG - Minor planet flag, should be "0"
     UCAC_DIST - Distance in arcsec to the nearest UCAC star
     GOOD - Set to "BAD" if there is not a 2MASS and UCAC isolated star
            within GOODRAD arcsec, or if any of the other, above flags have
            suspicious values; note that it will always say "BAD" for
            stars at high declination where UCAC does not have coverage

   Note that the UCAC astrometric catalog includes stars in the
   magnitude range R = [8,16] (approximately) from declination -90
   to between Dec +40 and +52.  It discards stars within 3 arcsec
   of any other star.

   Refer to the following 2MASS documentation for a description
   of the 2MASS data structure:
     http://tdc-www.harvard.edu/software/catalogs/tmc.format.html

   Refer to the following web site for the UCAC astrometric catalog:
     http://ad.usno.navy.mil/ucac/

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:
   djs_diff_angle()
   struct_addtags()
   struct_print
   struct_selecttags()
   tmass_read()
   ucac_read()

 REVISION HISTORY:
   09-Jul-2005  Written by D. Schlegel, LBL

(See pro/2mass/hst_guidetest.pro)


IAU_TO_RADEC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   iau_to_radec
 PURPOSE:
   convert an IAU name to RA and DEC
 CALLING SEQUENCE:
   iau_to_radec, name, ra, dec
 INPUTS:
   name - IAU name
 OUTPUTS:
   ra, dec - coords
 REVISION HISTORY:
   2005-10-24  Blanton (NYU)

(See pro/misc/iau_to_radec.pro)


IDLUTILS_SO_EXT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   idlutils_so_ext
 PURPOSE:
   returns appropriate dynamic library extension given arch
 CALLING SEQUENCE:
   so_ext= idlutils_so_ext()
 COMMENTS:
   necessary to deal with non-standard .dylib extension on darwin
 REVISION HISTORY:
   20-Feb-2004  Written by M. Blanton, NYU

(See pro/misc/idlutils_so_ext.pro)


IDLUTILS_VERSION

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

 PURPOSE:
   Return the version name for the product idlutils

 CALLING SEQUENCE:
   vers = idlutils_version()

 INPUTS:

 OUTPUTS:
   vers       - Version name for the product idlutils

 COMMENTS:
   If this version is not tagged by CVS, then we return 'NOCVS: TOPLEVEL'
   where TOPLEVEL is the last directory in the environment variable
   $IDLUTILS_DIR.  For example, if you are using a version of the code
   in the directory '/u/schlegel/idlutils/v0_0', then this returns
   'NOCVS:v0_0'.

 BUGS:

 PROCEDURES CALLED:

; REVISION HISTORY:
   01-Dec-1999  Written by D. Schlegel, Princeton.

(See pro/misc/idlutils_version.pro)


IMGEXP

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

 PURPOSE:
	This function expands the array <Image> to fill the current plotting
	window.  This routine works for both X and PostScript devices.  The
	optional scales <XS> and <YS> are likewise transformed and returned
	in option parameters <Out_XS> and <Out_YS>.

 CATEGORY:
	Image expansion.

 CALLING SEQUENCE:
	Result = IMGEXP(Image, XS, YS, Out_XS, Out_YS, X_Ran, Y_Ran)

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

 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:
	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_INTERP_SIZE for information
		on using this switch on a PostScript device.

	MASKVALUE=
		Set this keyword to the value that uninterpolated pixels around
		the border of the image should be given.  The default is 
		-9999.0.  Interpolation is not performed beyond the centers of
		the original pixels.

	PS_INTERP_SIZE=
		Since PostScript devices have scalable pixels it is necessary
		to force expansion to at most this many pixels in either
		dimension.  The default is 256.  (It's really more complicated
		than this.  Read the code if you need to know.)

	POSITION=
		Set this keyword to the variable that is to hold the four-
		element vector containing the device coordinates of the
		plotting region that will contain the expanded image.  This
		is designed to be used by subsequent TV and PLOT commands.

	/NO_EXPAND:
		Set this switch to prevent the image from being expanded
		to fill the plotting window.  An aspect ration of 1:1 is
		forced for PostScript output so that it conforms to the X
		window view.

 OUTPUTS:
	Result:	This function returns an expanded version of the input <Image>
		possibly interpolated.

 OPTIONAL OUTPUTS:
	Out_XS:	Vector of x-axis values corresponding the the expanded image.

	Out_YS:	Vector of y-axis values corresponding the the expanded image.

	X_Ran:	Two-element vector that contains the full x-axis range
		including the width of the pixels.  It is designed to be used
		as input to the PLOT command.
	
	Y_Ran:	Two-element vector that contains the full y-axis range
		including the height of the pixels.  It is designed to be used
		as input to the PLOT command.
	
 RESTRICTIONS:
	This routine may work for other devices, but it has only been tested
	on 'X' and 'PS'.

 PROCEDURE:
	Straight forward.  :-)

 EXAMPLE:
	p = 0
	big = IMGEXP(small, lon, lat, biglon, biglat, xr, yr, Position=p)
	TVSCL, big, p(0), p(1), /Device
	Plot, [0,1], /NoData, /NoErase, Position=p, /Device, $
		XRange=xr, YRange=yr

	junk = IMGSCL( )	;prints out a "Usage:" line

 MODIFICATION HISTORY:
 	Written by:	Fen Tamanaha, July 9, 1993.  Release 2.1
	July 16, 1993	Fen: (2.2) Added /No_Expand keyword
       Jan 10, 2000    D. Finkbeiner - added _extra pass-through to Plot

(See pro/plot/imgexp.pro)


IMGSCL

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

 PURPOSE:
	This function mimics BYTSCL() except that it maps the input range
	into a byte range from 1 through TOP.  A byte value of 0 is reserved
	for elements containing MASKVALUE usually assigned for bad pixels or
	those without data.  The function can also perform logarithmic scaling
	of the data into byte values.  Use of the LEVELS keyword will scale
	all value within a given level to a single byte value.

 CATEGORY:
	Image scaling.

 CALLING SEQUENCE:
	Result = IMGSCL(Array)

 INPUTS:
	Array:	Two-dimensional array to be expanded.

 KEYWORD PARAMETERS:
	MIN=	The minimum value of Array to be considered.  If MIN is not
		provided, Array is searched for its minimum value.  All
		values less than or equal to MIN are set to 1 in the Result.

	MAX=	The maximum value of Array to be considered.  If MAX is not
		provided, Array is searched for its maximum value.  All
		values greater than or equal to MAX are set to TOP in the
		Result.

	TOP=	The maximum value of the scaled result.  If TOP is not
		specified, 255 is used. Note that the minimum value of the
		scaled result is always 1 (NOT 0 as in BYTSCL).

	LEVELS=	Set this keyword to a vector of data value boundaries between
		which all elements of the Array 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.

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

	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.

 OUTPUTS:
	Result:	This function returns a byte array between 1 and TOP for data
		in Array between MIN and MAX.

 RESTRICTIONS:

 PROCEDURE:
	Straight forward.  :-)

 EXAMPLE:
	image = IMGSCL(array, Min=-1, Top=!D.Table_Size-1, /Log, Mask=-9999.0)
	TV, image

	image = IMGSCL(array, Levels=[0,1,2,4,8,16,32])
	TV, image		;plot with 6 colors plus the background

 MODIFICATION HISTORY:
 	Written by:	Fen Tamanaha, July 10, 1993.  Release 2.1

(See pro/plot/imgscl.pro)


INTERP_PROFMEAN

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

 PURPOSE:
   Interpolates a radial profile of the sort output by photo

 CALLING SEQUENCE:
   interp_profmean,nprof,profmean,radius,maggies, [maggieserr=, profradius= $
      proferr=, radiusscale=, maggiesscale=]

 INPUTS:
   nprof - number of measured elements in the profile 
   profmean - values (in maggies) in the profile [15]
   radius - a set of values to interpolate to [N]
   maggies - calculated maggies

 OPTIONAL INPUTS:
   proferr - errors in profile
   profradius - boundaries of annuli in profile (set to photo default
                in arcsec)
   radiusscale - asinh scale for radii
   maggiesscale - asinh scale for maggieses

 OUTPUTS:
   maggieserr - calculated error

 OPTIONAL INPUT/OUTPUTS:

 COMMENTS:
   Set up for using the profMean in the fpObjc files of the SDSS,
   input and output in maggies (or any linear measure of surface 
   brightness)

 EXAMPLES:

 BUGS:
   Slow.

 PROCEDURES CALLED:

 REVISION HISTORY:
   16-Jan-2002  Written by Mike Blanton, NYU

(See pro/image/interp_profmean.pro)


INTRV

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

 PURPOSE:
   Find the segment between breakpoints which contain each value in
   the array x.  The minimum breakpoint is nbkptord -1, and the maximum
   is nbkpt - nbkptord - 1.  This routine is required by the bspline
   IDL routines, and is similar in function to the slatec version.

 CALLING SEQUENCE:
   
   indx  = intrv(x, fullbkpt, nbkptord)

 INPUTS:
   x          - data x values
   fullbkpt   - Breakpoint vector returned by efc
   nbkptord   - Order of b-splines (4 is cubic)

 RETURNS:
   indx       - position of array elements with respect to breakpoints.

 OUTPUTS:

 OPTIONAL KEYWORDS:

 OPTIONAL OUTPUTS:

 COMMENTS:
   does the same function as intrv, although slower but easier to follow
    sorting is done here
   Again, assumes x is monotonically increasing

 EXAMPLES:

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

(See pro/bspline/intrv.pro)


ISHEALPIX

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

 PURPOSE:
   Determine if array represents a healpix image

 CALLING SEQUENCE:
   type = ishealpix(image)

 INPUTS:
   image   - input array to be tested
   npix    - number of pixels - set if image not set

 KEYWORDS:
   silent  - suppress messages. 
   true    - test for true color (not implemented)

 OUTPUTS:
   type    - image type; 1=healpix, 0=not healpix

 COMMENTS:
   Define healpix as an array of 12*2^(2*N) pixels for pos. integer N.
   A looser definition is possible for ring ordering, but not for
    nested ordering. 
   Must set either image or npix
   
 REVISION HISTORY:
   2003-Dec-05   Written by Douglas Finkbeiner, Princeton

(See pro/healpix/ishealpix.pro)


IS_CAP_USED

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   is_cap_used
 PURPOSE:
   Returns whether a cap is used in use_caps
 CALLING SEQUENCE:
   is_cap_used,use_caps,indx
 INPUTS:
   use_caps - bit mask indicating which cap is used
   indx - number indicating which cap we are interestedin
 OPTIONAL INPUTS:
 OUTPUTS:
 OPTIONAL INPUT/OUTPUTS:
 COMMENTS:
 EXAMPLES:
 BUGS:
   Number of caps limited to 32
 PROCEDURES CALLED:
 REVISION HISTORY:
   09-Nov-2002  Written by MRB (NYU)

(See pro/mangle/is_cap_used.pro)


IS_FILE_READABLE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   is_file_readable
 CALLING SEQUENCE:
   good= is_file_readable(filename,/compress)
 OUTPUT:
   good  - 1 if good, 0 if bad
 BUGS:
   - NOT extensively tested.
 REVISION HISTORY:
   2005-06-03  converted from Schlegel email to code - Hogg

(See pro/misc/is_file_readable.pro)


IS_IN_CAP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   is_in_cap
 PURPOSE:
   Is an xyz (or radec) position in a given cap?
 CALLING SEQUENCE:
   result=is_in_cap(ra=, dec=, xyz=, cap )
 INPUTS:
   ra - set of ra values
   dec - set of dec values
   xyz - xyz value(s) (overrides ra and dec)
   cap - single cap to check
 OPTIONAL INPUTS:
 OUTPUTS:
 OPTIONAL INPUT/OUTPUTS:
 COMMENTS:
   Either ra and dec, or xyz must be set; xyz overrides ra and dec
 EXAMPLES:
 BUGS:
 PROCEDURES CALLED:
 REVISION HISTORY:
   01-Oct-2002  Written by MRB (NYU)

(See pro/mangle/is_in_cap.pro)


IS_IN_POLYGON

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   is_in_polygon
 PURPOSE:
   Is an xyz (or radec) position in a given polygon?
 CALLING SEQUENCE:
   result=is_in_polygon(xyz=, ra=, dec= , polygon)
 INPUTS:
   ra - set of ra values
   dec - set of dec values
   xyz - xyz value(s) (overrides ra and dec)
   polygon - polygon with caps to check
 OPTIONAL INPUTS:
   ncaps - override polygon.ncaps (if ncaps < polygon.ncaps)
 OUTPUTS:
 OPTIONAL INPUT/OUTPUTS:
 COMMENTS:
   Either ra and dec, or xyz must be set; xyz overrides ra and dec
 EXAMPLES:
 BUGS:
 PROCEDURES CALLED:
 REVISION HISTORY:
   01-Oct-2002  Written by MRB (NYU)

(See pro/mangle/is_in_polygon.pro)


IS_IN_WINDOW

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   is_in_window
 PURPOSE:
   Is an xyz (or radec) position in any of a given list of polygons?
 CALLING SEQUENCE:
   result=is_in_window(xyz=, ra=, dec= , polygons)
 INPUTS:
   polygons - polygons with caps to check
 OPTIONAL INPUTS:
   ra - [N] set of ra values
   dec - [N] set of dec values
   xyz - [3,N] xyz value(s) (overrides ra and dec)
   ncaps - override polygon.ncaps (if ncaps < polygon.ncaps)
 OUTPUTS:
   result - [N] 1 if in window, 0 otherwise
 OPTIONAL OUTPUTS:
   in_polygon - [N] which polygon each ra,dec is in (-1 if none)
 COMMENTS:
   Either ra and dec, or xyz must be set; xyz overrides ra and dec
 REVISION HISTORY:
   01-Oct-2002  Written by MRB (NYU)

(See pro/mangle/is_in_window.pro)


LABELLOC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   labelloc
 PURPOSE:
   convert fractional positions in X and Y to those appropriate for xyouts
 CALLING SEQUENCE:
   labelloc, xfrac, yfrac, xloc, yloc
 INPUTS:
   xfrac,yfrac - fractional distances from axes in x and y
 OUTPUTS:
   xloc, yloc - units appropriate for xyouts
 REVISION HISTORY:
   2003-11-21  started - Blanton

(See pro/misc/labelloc.pro)


LEGENDRE_ZERO

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

 PURPOSE:
   Compute zeros of the m=0 Legendre polynomials

 CALLING SEQUENCE:
   thzero = legendre_zero(l)

 INPUTS:
   l - order of Legendre polynomial Pl0(x) to compute
   
 KEYWORDS:
   
 OUTPUTS:
   thzero  - theta values of zeros [radians]

 EXAMPLES:
   
 COMMENTS:
   Just calls fx_root.  We need the common block and the function
     legfn. 

 REVISION HISTORY:
   2003-Feb-21  Written by Douglas Finkbeiner, Princeton

(See pro/math/legendre_zero.pro)


LG_TO_HELIO

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   lg_to_helio
 PURPOSE:
   Convert to heliocentric redshifts from Local-Group-centric redshifts.
 CALLING SEQUENCE:
   z_helio = lg_to_helio(z_lg,ra,dec)
 INPUTS:
   z_lg   - local-group-centric redshift
   RA        - right ascension (deg, J2000)
   Dec       - declination (deg, J2000)
 OUTPUTS:
   z_helio      - heliocentric redshift
 REVISION HISTORY:
   Originally imported by Hogg, 2002-08 or so.
   MRB corrected sign error in correction 2004-04-08 (affected tags
   v5_0_0 and previous)

(See pro/coord/lg_to_helio.pro)


LL2UV

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

  PURPOSE:
    To convert from longitude/latitude to unit vectors

  CALLING SEQUENCE:
    uv = ll2uv(lon_lat)

  INPUT:
    (n,2) longitude/latitude array

  OUTPUT:
    (n,3) unit vector array

  SUBROUTINES CALLED:
    None

  REVISION HISTORY

 SPR 9923 26-AUG-1992  Change unit vector output array to float type
 J.M. Gales
 29-March-2001  Added double keyword - Doug Finkbeiner, Princeton

(See pro/astrom/ll2uv.pro)


LLE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
    lle
 PURPOSE: (one line)
    Perform local linear embedding
 DESCRIPTION:
    Uses Sam Roweis's local linear embedding technique to reduce the 
    dimensionality of a data set.
 CATEGORY:
    Mathematical
 CALLING SEQUENCE:
    lle, data, ncoords, coords, weights=weights
 INPUTS:
    data - [p,N] data to be reduced
    ncoords - number of output dimensions desired
 OUTPUTS: 
    coords - [ncoords,N] embedding coordinates
 OPTIONAL OUTPUTS PARAMETERS:
    weights - reconstruction weights
 OPTIONAL INPUT PARAMETERS:
 KEYWORD PARAMETERS:
 COMMON BLOCKS:
 SIDE EFFECTS:
 BUGS:
    Not completed yet, do not use
 RESTRICTIONS:
 PROCEDURE:
 MODIFICATION HISTORY:
    2003-05-14 - Written by Michael Blanton (NYU)

(See pro/math/lle.pro)


LLE_SM

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	  lle_sm
 PURPOSE: (one line)
   create sparse matrix from full matrix for LLE routines
 DESCRIPTION:
   rather crappy sparse matrix format for NxM matrix:
      .N - number of rows
      .M - number of columns
      .VALS - each nonzero value
      .NINDX - row of each nonzero value 
      .MINDX - column of each nonzero value 
   but it handles nonsquare matrices
 CATEGORY:
       Numerical
 CALLING SEQUENCE:
   sparse_matrix= lle_sm(full_matrix)
 INPUTS:
   full_matrix - complete NxM matrix 
 OPTIONAL INPUT PARAMETERS:
 KEYWORD PARAMETERS:
 OUTPUTS:
   sparse_matrix - full_matrix transformed into above format
 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
   always at double precision
 PROCEDURE:
 MODIFICATION HISTORY:
	  Blanton 2003-05-26 

(See pro/math/lle_sm.pro)


LLE_SM_FULL

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	  lle_sm_full
 PURPOSE: (one line)
   create full matrix from full matrix for LLE routines
 DESCRIPTION:
   rather crappy sparse matrix format for NxM matrix:
      .N - number of rows
      .M - number of columns
      .VALS - each nonzero value
      .NINDX - row of each nonzero value 
      .MINDX - column of each nonzero value 
   but it handles nonsquare matrices
 CATEGORY:
       Numerical
 CALLING SEQUENCE:
   full_matrix= lle_sm_full(sparse_matrix)
 INPUTS:
   sparse_matrix - matrix in above format
 OPTIONAL INPUT PARAMETERS:
 KEYWORD PARAMETERS:
 OUTPUTS:
   full_matrix - complete NxM matrix 
 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
   always at double precision
 PROCEDURE:
 MODIFICATION HISTORY:
	  Blanton 2003-05-26 

(See pro/math/lle_sm_full.pro)


LLE_SM_MULT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	  lle_sm_mult
 PURPOSE: (one line)
   multiply two sparse matrices kind of efficiently for LLE routines
 DESCRIPTION:
   rather crappy sparse matrix format for NxM matrix:
      .N - number of rows
      .M - number of columns
      .VALS - each nonzero value
      .NINDX - row of each nonzero value 
      .MINDX - column of each nonzero value 
   but it handles nonsquare matrices
 CATEGORY:
       Numerical
 CALLING SEQUENCE:
   cc= lle_sm_mult(aa,bb)
 INPUTS:
   aa - [N,M] sparse matrix input
   bb - [M,P] sparse matrix input
 OPTIONAL INPUT PARAMETERS:
 KEYWORD PARAMETERS:
 OUTPUTS:
   cc - [N,P] sparse matrix output (should be equal to idl's aa#bb) 
 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
   always at double precision
 PROCEDURE:
 MODIFICATION HISTORY:
	  Blanton 2003-05-26 

(See pro/math/lle_sm_mult.pro)


LLE_SM_TRANSPOSE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	  lle_sm_transpose
 PURPOSE: (one line)
   transpose a sparse matrix for the LLE routines
 DESCRIPTION:
   transposes the rather crappy sparse matrix format for NxM matrix:
      .N - number of rows
      .M - number of columns
      .VALS - each nonzero value
      .NINDX - row of each nonzero value 
      .MINDX - column of each nonzero value 
   but it handles nonsquare matrices
 CATEGORY:
       Numerical
 CALLING SEQUENCE:
   mattrans= lle_sm_transpose(mat)
 INPUTS:
   mat - matrix in above format
 OPTIONAL INPUT PARAMETERS:
 KEYWORD PARAMETERS:
 OUTPUTS:
   mattrans - transposed matrix in above format
 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
 PROCEDURE:
 MODIFICATION HISTORY:
	  Blanton 2003-05-26 

(See pro/math/lle_sm_transpose.pro)


LOCAL_EXTRAGALACTIC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   local_extragalactic
 PURPOSE:
   returns list of local extragalactic locations and names to plot
 CALLING SEQUENCE:
   local_extragalactic, ra, dec, cz_lg, names, list=list
 OPTIONAL INPUTS:
   list - list of names to match to (default: 
       ['VIRGO_CLUSTER', 'URSA_MAJOR_CLUSTER', $
        'PISCES_CLUSTER', 'COMA_CLUSTER' ] )
 OUTPUTS:
   ra - [N] ra (J2000 deg)
   dec - [N] dec (J2000 deg)
   cz_lg - [N] local group frame cz
   names - [N] object name

(See pro/coord/local_extragalactic.pro)


LOGSUM

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	  logsum
 PURPOSE: (one line)
   sum quantities when you have them as logs (preserving dynamic range)
 CATEGORY:
       Numerical
 CALLING SEQUENCE:
   res= logsum(logs [,/double])
 KEYWORD PARAMETERS:
   /double - assume double precision input (otherwise assumes float)
 RESTRICTIONS:
   seems to not have expected precision
 MODIFICATION HISTORY:
	  Blanton and Roweis 2003-02-18 

(See pro/math/logsum.pro)


LOOKBACK

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   lookback
 PURPOSE:
   Compute lookback time (for c/H_0=1).
 CALLING SEQUENCE:
   t= lookback(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:
   lookback time in units of the Hubble time 1/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:
   dlookbackdz()
 REVISION HISTORY:
   2001-May-12  Written by Hogg (NYU)

(See pro/cosmography/lookback.pro)


LOOKFORGZIP

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

 PURPOSE:
   Look for a gzip-ed file, 

 CALLING SEQUENCE:
   thisfile = lookforgzip( filename, count= )

 INPUTS:
   filename   - Input file name w/out any ".gz" or ".Z" extension

 OPTIONAL KEYWORDS:

 OUTPUTS:
   thisfile   - Returns input file name with no extension if it exists,
                otherwise a ".gz" extension if that exists,
                otherwise a ".Z" extension if that exists,
                otherwise '' if none of the above exist.

 OPTIONAL OUTPUTS:
   count      - Number of files that matched

 COMMENTS:
   This routine uses FINDFILE().

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:

 REVISION HISTORY:
   20-Oct-2000  Written by S. Burles, FNAL

(See pro/misc/lookforgzip.pro)


LUMDIS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   lumdis
 PURPOSE:
   Compute luminosity distances (for c/H_0=1).
 CALLING SEQUENCE:
   D= lumdis(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:
   luminosity 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/lumdis.pro)


MAKE_DEC_CAP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   make_dec_cap
 PURPOSE:
   Creates a structure containing a cap expressing a limit in dec
 CALLING SEQUENCE:
   cap=make_dec_cap(declimit, [,sign= ]
 INPUTS:
   declimit - limit on dec 
 OPTIONAL INPUTS:
   sign - sign of the cap (default 1.)
 OUTPUTS:
 OPTIONAL INPUT/OUTPUTS:
 COMMENTS:
 EXAMPLES:
 BUGS:
 PROCEDURES CALLED:
 REVISION HISTORY:
   01-Oct-2002  Written by MRB (NYU)

(See pro/mangle/make_dec_cap.pro)


MAKE_HTML_HELP

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

 PURPOSE:
	Given a list of IDL procedure files (.PRO), VMS text library 
       files (.TLB), or directories that contain such files, this procedure 
       generates a file in the HTML format that contains the documentation 
       for those routines that contain a DOC_LIBRARY style documentation 
       template.  The output file is compatible with World Wide Web browsers.

 CATEGORY:
	Help, documentation.

 CALLING SEQUENCE:
	MAKE_HTML_HELP, Sources, Outfile

 INPUTS:
     Sources:  A string or string array containing the name(s) of the
		.pro or .tlb files (or the names of directories containing 
               such files) for which help is desired.  If a source file is 
               a VMS text library, it must include the .TLB file extension.  
               If a source file is an IDL procedure, it must include the .PRO
               file extension.  All other source files are assumed to be
               directories.
     Outfile:	The name of the output file which will be generated.

 KEYWORDS:
     TITLE:	If present, a string which supplies the name that
		should appear as the Document Title for the help.
     VERBOSE:	Normally, MAKE_HTML_HELP does its work silently.
		Setting this keyword to a non-zero value causes the procedure
		to issue informational messages that indicate what it
		is currently doing. !QUIET must be 0 for these messages
               to appear.
     STRICT:   If this keyword is set to a non-zero value, MAKE_HTML_HELP will 
               adhere strictly to the HTML format by scanning the 
               the document headers for characters that are reserved in 
               HTML (<,>,&,").  These are then converted to the appropriate 
               HTML syntax in the output file. By default, this keyword
               is set to zero (to allow for faster processing).

     LINKFILES: If this keyword is set to a non-zero value,
                MAKE_HTML_HELP will generate "file" links to the idl
                procedures documented on the web page created by this
                code. 
 COMMON BLOCKS:
	None.

 SIDE EFFECTS:
	A help file with the name given by the Outfile argument is
	created.

 RESTRICTIONS:
	The following rules must be followed in formatting the .pro
	files that are to be searched.
		(a) The first line of the documentation block contains
		    only the characters ";+", starting in column 1.
               (b) There must be a line which contains the string "NAME:",
                   which is immediately followed by a line containing the
                   name of the procedure or function being described in
                   that documentation block.  If this NAME field is not
                   present, the name of the source file will be used.
		(c) The last line of the documentation block contains
		    only the characters ";-", starting in column 1.
		(d) Every other line in the documentation block contains
		    a ";" in column 1.

       Note that a single .pro file can contain multiple procedures and/or
       functions, each with their own documentation blocks. If it is desired
       to have "invisible" routines in a file, i.e. routines which are only
       for internal use and should not appear in the help file, simply leave
       out the ";+" and ";-" lines in the documentation block for those
       routines.

	No reformatting of the documentation is done.

 MODIFICATION HISTORY:
       July 5, 1995, DD, RSI. Original version.
       July 13, 1995, Mark Rivers, University of Chicago. Added support for
               multiple source directories and multiple documentation
               headers per .pro file.
       July 17, 1995, DD, RSI. Added code to alphabetize the subjects;
               At the end of each description block in the HTML file,
               added a reference to the source .pro file.
       July 18, 1995, DD, RSI. Added STRICT keyword to handle angle brackets.
       July 19, 1995, DD, RSI. Updated STRICT to handle & and ".
               Changed calling sequence to accept .pro filenames, .tlb
               text librarie names, and/or directory names.
               Added code to set default subject to name of file if NAME
               field is not present in the doc header.
       February 10, 1998, MWC, UC Berkeley. Added purpose to the line
               which is output for each routine in the tableof
               contents. This used to just contain the name.
       April 1, 1998, MWC, UC Berkeley.  Added option to create file
               link to the location of the procedure being documented.

(See pro/misc/make_html_help.pro)


MAKE_RA_CAP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   make_ra_cap
 PURPOSE:
   Creates a structure containing a cap expressing a limit in ra
 CALLING SEQUENCE:
   cap=make_ra_cap(ralimit, [,sign= ])
 INPUTS:
   ralimit - limit on ra 
 OPTIONAL INPUTS:
   sign - sign of the cap (default 1.)
 REVISION HISTORY:
   01-Oct-2002  Written by MRB (NYU)

(See pro/mangle/make_ra_cap.pro)


MAP_NEST2RING

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

 PURPOSE:
   Convert a full-sky map in nested order to ring order

 CALLING SEQUENCE:
   ringmap=map_nest2ring(nestmap)

 INPUTS:
   nestmap  - healpix map in nested order

 OUTPUTS:
   ringmap  - healpix map in ring order

 COMMENTS:
   
 REVISION HISTORY:
   2003-Dec-04  Written by Douglas Finkbeiner, Princeton

(See pro/healpix/map_nest2ring.pro)


MAP_RING2NEST

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

 PURPOSE:
   Convert a full-sky map in ring order to nested order

 CALLING SEQUENCE:
   nestmap=map_ring2nest(ringmap)

 INPUTS:
   ringmap  - healpix map in ring order

 OUTPUTS:
   nestmap  - healpix map in nested order

 COMMENTS:
   
 REVISION HISTORY:
   2003-Dec-04  Written by Douglas Finkbeiner, Princeton

(See pro/healpix/map_ring2nest.pro)


MATCHND

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   matchnd
 PURPOSE:
   match two sets of points on a grid
 CALLING SEQUENCE:
   matchnd, x1, x2, distance [, m1=, m2=, d12=, nmatch= ]
 INPUTS:
   x1 - [M,N1] positions in M-dimensions
   x2 - [M,N2] positions in M-dimensions
   distance - match distance
 OUTPUTS:
   m1 - [nmatch] matches to x1
   m2 - [nmatch] matches to x2
   d12 - [nmatch] distance between matches
   nmatch - number of matches
 COMMENTS:
   This code is BETA! Use at your own risk.
 REVISION HISTORY:
   12-Oct-2005  Written by Mike Blanton, NYU

(See pro/math/matchnd.pro)


MEMSHIFT

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

 PURPOSE:
   Shift elements in an array, which can be a structure array.

 CALLING SEQUENCE:
   memshift, array, isrc, idest, nmove

 INPUTS:
   array      - Array of any type except string or pointer; structures
                are allowed
   isrc       - Starting position in memory to copy from
   idest      - Starting position in memory to copy to
   nmove      - Number of array elements to copy

 OPTIONAL INPUTS:

 OUTPUT:
   array      - (Modified.)

 OPTIONAL OUTPUTS:

 COMMENTS:
   This routine is equivalent to the IDL command:
     array[idest:idest+nmove-1] = array[isrc:isrc+nmove-1]
   but is faster, at least on the Linux platform.  Note that the
   memory in the source and destination can be overlapping.
   The C code calls the Unix memmove() function.

   If an attempt is made to copy out-of-bounds, then this procedure
   intentionally crashes using the MESSAGE function.

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:
   Dynamic link to memshift.o

 REVISION HISTORY:
   18-Oct-2003  Written by David Schlegel, Princeton.

(See pro/math/memshift.pro)


MJD2DATELIST

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

 PURPOSE:
   Construct a list of MJDs and date strings spanning a range of MJDs
   (useful for plot limits).

 CALLING SEQUENCE:
   mjd2datelist, mjstart, [ mjend, step=, mjdlist=, datelist= ]

 INPUTS:
   mjstart    - Starting modified Julian date to span.

 OPTIONAL INPUTS:
   mjend      - Ending modified Julian date to span; if not set, then
                only the date string for MJSTART is returned.
   step       - Step in either 'year', '6month', 'month', or 'day';
                default to 'year', or 'day' if MJEND not set.

 OUTPUTS:

 OPTIONAL OUTPUTS:
   mjlist     - List of modified Julian dates (MJDs)
   datelist   - List of dates in the form DD-MMM-YYYY, where MMM is
                the first three letters of the month name.

 COMMENTS:
   This routine returns a list of MJDs and date strings spaced by
   the amount specified by STEP that span the range [MJSTART,MJEND].
   If using STEP='year', the output list will be on the first date
   of each year and [MJSTART,MJEND] will fall internal to that list.
   If using STEP='month', the output list will be on each 01-Jan
   and 01-Jul.  If using STEP='month', the output list will be on
   the first of each month.

 EXAMPLES:
   Construct a list of all the Jan 1st dates that span the dates
   of the SDSS spectroscopic survey:
     IDL> mjd2datelist, 51433, 52356, mjdlist=mjdlist, datelist=datelist
     IDL> print, mjdlist
          51179.500   51544.500   51910.500   52275.500   52640.500
     IDL> print, datelist
          01-Jan-1999 01-Jan-2000 01-Jan-2001 01-Jan-2002 01-Jan-2003

 BUGS:

 PROCEDURES CALLED:

 INTERNAL SUPPORT ROUTINES:

 REVISION HISTORY:
   26-Mar-2002  Written by D. Schlegel, Princeton

(See pro/coord/mjd2datelist.pro)


MMEVAL

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   mmeval
 PURPOSE:
   evaluate a matrix multiply sparsely
 CALLING SEQUENCE:
   mmeval, cc, bb, aa
 INPUTS:
   cc - sparse matrix struct (see below) [nz,ny]
   bb - [nx, nz] matrix 
   aa - [nx, ny] matrix 
 OUTPUTS:
   cc - sparse matrix struct (see below) [nz,ny]
 COMMENTS:
   The matrix multiply of bb.aa is evaluated specified by the sparse
   matrix structure of cc.
   The sparse matrix structure referred to above is:
       .VAL[NVAL]      - actual values in matrix
       .X[NVAL]        - columns for each value in matrix
       .NX             - number of columns
       .NY             - number of rows
       .ROWSTART[NY]   - starting position of each row in VAL, X
       .NXROW[NY]      - number of columns in each now 
   This code is called by nmf_sparse.
 REVISION HISTORY:
   2005-Feb-5  Written by Mike Blanton, NYU
               Adapted from Matlab code of Sam Roweis

(See pro/math/mmeval.pro)


MMSPARSE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   mmsparse
 PURPOSE:
   multiply a regular matrix by a sparse matrix
 CALLING SEQUENCE:
   mmsparse, cc, bb, aasparse 
 INPUTS:
   bb - sparse matrix struct (see below) [nx, nz] of inverse var
   aasparse - sparse matrix struct (see below) [nx, ny] 
 OUTPUTS:
   cc - [nz, ny] result
 COMMENTS:
   The sparse matrix structure referred to above is:
       .VAL[NVAL]      - actual values in matrix
       .X[NVAL]        - columns for each value in matrix
       .NX             - number of columns
       .NY             - number of rows
       .ROWSTART[NY]   - starting position of each row in VAL, X
       .NXROW[NY]      - number of columns in each now 
   This code is called by nmf_sparse.
 REVISION HISTORY:
   2005-Feb-5  Written by Mike Blanton, NYU
               Adapted from Matlab code of Sam Roweis

(See pro/math/mmsparse.pro)


MODFITSCARD

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

 PURPOSE:
   Modify FITS card(s) in a file without changing the data.

 CALLING SEQUENCE:
   modfitscard, filename, card, value, [ comment, /delete, $
    _EXTRA=KeywordsForSxaddpar ]

 INPUTS:
   filename  - File name(s) to modify; this can be an array of file names,
               and it can include wildcards
   card      - Name of FITS card(s) to add or modify

 OPTIONAL INPUTS:
   value     - New value(s) for FITS card; mandatory card if DELETE not set;
               must have the same number of elements as CARD.
   comment   - Comment to appear in the card after its value; passed to
               the routine SXADDPAR.  If specified, it must have the same
               number of elements as CARD.
   delete    - If set, then delete all cards CARD from the header;
               VALUE is ignored if set.

 OUTPUTS:

 OPTIONAL OUTPUTS:

 COMMENTS:

 EXAMPLES:
   Modify the value of the DATE keyword in the primary header of all FITS
   files with '666' or '777' in the file name:
   IDL> modfitscard, ['*666*.fits','*777*.fits'], 'DATE', '1994-03-23'

 BUGS:
   This routine calls DJS_MODFITS, which allows the size of the header
   to be changed.

   Wildcards are not supported for CARD, so you cannot say something like
   IDL> modfitscard, 'test.fits', 'DATE*', '1994-03-23' ; Will not work!

 PROCEDURES CALLED:
   djs_modfits
   headfits()
   sxaddpar

 REVISION HISTORY:
   19-Apr-2000  Written by David Schlegel, Princeton.

(See pro/fits/modfitscard.pro)


MOON_ZENITH

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

 PURPOSE:
   Compute zenith angle of moon, given TAI

 CALLING SEQUENCE:
   zenithang = moon_zenith(TAI, [longitude=, latitude=])

 INPUTS:
   TAI            - time in seconds since MJD 0

 OPTIONAL KEYWORDS:
   longitude      - longitude of observatory [deg] - default to APO
   latitude       - latitude of observatory [deg]
 
 OUTPUTS:
   zenithang      - zenith angle of the moon [deg]


 COMMENTS:
   TAI must be specified.

 BUGS:
   Uses geocentric coords, should correct for position on Earth

 PROCEDURES CALLED:
   moonpos

 REVISION HISTORY:
   2001-Apr-06  Written by D. Finkbeiner, APO

(See pro/coord/moon_zenith.pro)


MPCHILIM

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

 AUTHOR:
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov
   UPDATED VERSIONs can be found on my WEB PAGE: 
      http://cow.physics.wisc.edu/~craigm/idl/idl.html

 PURPOSE:
   Compute confidence limits for chi-square statistic

 MAJOR TOPICS:
   Curve and Surface Fitting, Statistics

 CALLING SEQUENCE:
   DELCHI = MPCHILIM(PROB, DOF, [/SIGMA, /CLEVEL, /SLEVEL ])

 DESCRIPTION:

  The function MPCHILIM() computes confidence limits of the
  chi-square statistic for a desired probability level.  The returned
  values, DELCHI, are the limiting chi-squared values: a chi-squared
  value of greater than DELCHI will occur by chance with probability
  PROB:

    P_CHI(CHI > DELCHI; DOF) = PROB

  In specifying the probability level the user has three choices:

    * give the confidence level (default);

    * give the significance level (i.e., 1 - confidence level) and
      pass the /SLEVEL keyword; OR

    * give the "sigma" of the probability (i.e., compute the
      probability based on the normal distribution) and pass the
      /SIGMA keyword.

  Note that /SLEVEL, /CLEVEL and /SIGMA are mutually exclusive.

 INPUTS:

   PROB - scalar or vector number, giving the desired probability
          level as described above.

   DOF - scalar or vector number, giving the number of degrees of
         freedom in the chi-square distribution.

 RETURNS:

  Returns a scalar or vector of chi-square confidence limits.

 KEYWORD PARAMETERS:

   SLEVEL - if set, then PROB describes the significance level.

   CLEVEL - if set, then PROB describes the confidence level
            (default).

   SIGMA - if set, then PROB is the number of "sigma" away from the
           mean in the normal distribution.

 EXAMPLES:

   print, mpchilim(0.99d, 2d, /clevel)

   Print the 99% confidence limit for a chi-squared of 2 degrees of
   freedom.

   print, mpchilim(5d, 2d, /sigma)

   Print the "5 sigma" confidence limit for a chi-squared of 2
   degrees of freedom.  Here "5 sigma" indicates the gaussian
   probability of a 5 sigma event or greater. 
       P_GAUSS(5D) = 1D - 5.7330314e-07

 REFERENCES:

   Algorithms taken from CEPHES special function library, by Stephen
   Moshier. (http://www.netlib.org/cephes/)

 MODIFICATION HISTORY:
   Completed, 1999, CM
   Documented, 16 Nov 2001, CM
   Reduced obtrusiveness of common block and math error handling, 18
     Nov 2001, CM

  $Id: mpchilim.pro,v 1.1 2006/02/07 22:38:32 schlegel Exp $

(See pro/mpfit/mpchilim.pro)


MPCHITEST

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

 AUTHOR:
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov
   UPDATED VERSIONs can be found on my WEB PAGE: 
      http://cow.physics.wisc.edu/~craigm/idl/idl.html

 PURPOSE:
   Compute the probability of a given chi-squared value

 MAJOR TOPICS:
   Curve and Surface Fitting, Statistics

 CALLING SEQUENCE:
   PROB = MPCHITEST(CHI, DOF, [/SIGMA, /CLEVEL, /SLEVEL ])

 DESCRIPTION:

  The function MPCHITEST() computes the probability for a value drawn
  from the chi-square distribution to equal or exceed the given value
  CHI.  This can be used for confidence testing of a measured value
  obeying the chi-squared distribution.

    P_CHI(X > CHI; DOF) = PROB

  In specifying the returned probability level the user has three
  choices:

    * return the confidence level when the /CLEVEL keyword is passed;
      OR

    * return the significance level (i.e., 1 - confidence level) when
      the /SLEVEL keyword is passed (default); OR

    * return the "sigma" of the probability (i.e., compute the
      probability based on the normal distribution) when the /SIGMA
      keyword is passed.

  Note that /SLEVEL, /CLEVEL and /SIGMA are mutually exclusive.

 INPUTS:

   CHI - chi-squared value to be tested.

   DOF - scalar or vector number, giving the number of degrees of
         freedom in the chi-square distribution.

 RETURNS:

  Returns a scalar or vector of probabilities, as described above,
  and according to the /SLEVEL, /CLEVEL and /SIGMA keywords.

 KEYWORD PARAMETERS:

   SLEVEL - if set, then PROB describes the significance level
            (default).

   CLEVEL - if set, then PROB describes the confidence level.

   SIGMA - if set, then PROB is the number of "sigma" away from the
           mean in the normal distribution.

 EXAMPLES:

   print, mpchitest(1300d,1252d)

   Print the probability for a chi-squared value with 1252 degrees of
   freedom to exceed a value of 1300, as a confidence level.

 REFERENCES:

   Algorithms taken from CEPHES special function library, by Stephen
   Moshier. (http://www.netlib.org/cephes/)

 MODIFICATION HISTORY:
   Completed, 1999, CM
   Documented, 16 Nov 2001, CM
   Reduced obtrusiveness of common block and math error handling, 18
     Nov 2001, CM

  $Id: mpchitest.pro,v 1.1 2006/02/07 22:38:32 schlegel Exp $

(See pro/mpfit/mpchitest.pro)


MPCURVEFIT

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

 AUTHOR:
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov
   UPDATED VERSIONs can be found on my WEB PAGE: 
      http://cow.physics.wisc.edu/~craigm/idl/idl.html

 PURPOSE:
   Perform Levenberg-Marquardt least-squares fit (replaces CURVEFIT)

 MAJOR TOPICS:
   Curve and Surface Fitting

 CALLING SEQUENCE:
   YFIT = MPCURVEFIT(X, Y, WEIGHTS, P, [SIGMA,] FUNCTION_NAME=FUNC, 
                     ITER=iter, ITMAX=itmax, 
                     CHISQ=chisq, NFREE=nfree, DOF=dof, 
                     NFEV=nfev, COVAR=covar, [/NOCOVAR, ] [/NODERIVATIVE, ]
                     FUNCTARGS=functargs, PARINFO=parinfo,
                     FTOL=ftol, XTOL=xtol, GTOL=gtol, TOL=tol,
                     ITERPROC=iterproc, ITERARGS=iterargs,
                     NPRINT=nprint, QUIET=quiet, 
                     ERRMSG=errmsg, STATUS=status)

 DESCRIPTION:

  MPCURVEFIT fits a user-supplied model -- in the form of an IDL
  function -- to a set of user-supplied data.  MPCURVEFIT calls
  MPFIT, the MINPACK-1 least-squares minimizer, to do the main
  work.

  Given the data and their uncertainties, MPCURVEFIT finds the best
  set of model parameters which match the data (in a least-squares
  sense) and returns them in the parameter P.  

  MPCURVEFIT returns the best fit function.
  
  The user must supply the following items:
   - An array of independent variable values ("X").
   - An array of "measured" *dependent* variable values ("Y").
   - An array of weighting values ("WEIGHTS").
   - The name of an IDL function which computes Y given X ("FUNC").
   - Starting guesses for all of the parameters ("P").

  There are very few restrictions placed on X, Y or FUNCT.  Simply
  put, FUNCT must map the "X" values into "Y" values given the
  model parameters.  The "X" values may represent any independent
  variable (not just Cartesian X), and indeed may be multidimensional
  themselves.  For example, in the application of image fitting, X
  may be a 2xN array of image positions.

  MPCURVEFIT carefully avoids passing large arrays where possible to
  improve performance.

  See below for an example of usage.
   
 USER FUNCTION

  The user must define a function which returns the model value.  For
  applications which use finite-difference derivatives -- the default
  -- the user function should be declared in the following way:

    PRO MYFUNCT, X, P, YMOD
     ; The independent variable is X
     ; Parameter values are passed in "P"
     YMOD = ... computed model values at X ...
    END

  The returned array YMOD must have the same dimensions and type as
  the "measured" Y values.

  User functions may also indicate a fatal error condition
  using the ERROR_CODE common block variable, as described
  below under the MPFIT_ERROR common block definition.

  See the discussion under "ANALYTIC DERIVATIVES" and AUTODERIVATIVE
  in MPFIT.PRO if you wish to compute the derivatives for yourself.
  AUTODERIVATIVE is accepted and passed directly to MPFIT.  The user
  function must accept one additional parameter, DP, which contains
  the derivative of the user function with respect to each parameter
  at each data point, as described in MPFIT.PRO.

 CONSTRAINING PARAMETER VALUES WITH THE PARINFO KEYWORD

  The behavior of MPFIT can be modified with respect to each
  parameter to be fitted.  A parameter value can be fixed; simple
  boundary constraints can be imposed; limitations on the parameter
  changes can be imposed; properties of the automatic derivative can
  be modified; and parameters can be tied to one another.

  These properties are governed by the PARINFO structure, which is
  passed as a keyword parameter to MPFIT.

  PARINFO should be an array of structures, one for each parameter.
  Each parameter is associated with one element of the array, in
  numerical order.  The structure can have the following entries
  (none are required):
  
     .VALUE - the starting parameter value (but see the START_PARAMS
              parameter for more information).
  
     .FIXED - a boolean value, whether the parameter is to be held
              fixed or not.  Fixed parameters are not varied by
              MPFIT, but are passed on to MYFUNCT for evaluation.
  
     .LIMITED - a two-element boolean array.  If the first/second
                element is set, then the parameter is bounded on the
                lower/upper side.  A parameter can be bounded on both
                sides.  Both LIMITED and LIMITS must be given
                together.
  
     .LIMITS - a two-element float or double array.  Gives the
               parameter limits on the lower and upper sides,
               respectively.  Zero, one or two of these values can be
               set, depending on the values of LIMITED.  Both LIMITED
               and LIMITS must be given together.
  
     .PARNAME - a string, giving the name of the parameter.  The
                fitting code of MPFIT does not use this tag in any
                way.  However, the default ITERPROC will print the
                parameter name if available.
  
     .STEP - the step size to be used in calculating the numerical
             derivatives.  If set to zero, then the step size is
             computed automatically.  Ignored when AUTODERIVATIVE=0.
             This value is superceded by the RELSTEP value.

     .RELSTEP - the *relative* step size to be used in calculating
                the numerical derivatives.  This number is the
                fractional size of the step, compared to the
                parameter value.  This value supercedes the STEP
                setting.  If the parameter is zero, then a default
                step size is chosen.

     .MPSIDE - the sidedness of the finite difference when computing
               numerical derivatives.  This field can take four
               values:

                  0 - one-sided derivative computed automatically
                  1 - one-sided derivative (f(x+h) - f(x)  )/h
                 -1 - one-sided derivative (f(x)   - f(x-h))/h
                  2 - two-sided derivative (f(x+h) - f(x-h))/(2*h)

              Where H is the STEP parameter described above.  The
              "automatic" one-sided derivative method will chose a
              direction for the finite difference which does not
              violate any constraints.  The other methods do not
              perform this check.  The two-sided method is in
              principle more precise, but requires twice as many
              function evaluations.  Default: 0.

     .MPMAXSTEP - the maximum change to be made in the parameter
                  value.  During the fitting process, the parameter
                  will never be changed by more than this value in
                  one iteration.

                  A value of 0 indicates no maximum.  Default: 0.
  
     .TIED - a string expression which "ties" the parameter to other
             free or fixed parameters.  Any expression involving
             constants and the parameter array P are permitted.
             Example: if parameter 2 is always to be twice parameter
             1 then use the following: parinfo(2).tied = '2 * P(1)'.
             Since they are totally constrained, tied parameters are
             considered to be fixed; no errors are computed for them.
             [ NOTE: the PARNAME can't be used in expressions. ]

     .MPPRINT - if set to 1, then the default ITERPROC will print the
                parameter value.  If set to 0, the parameter value
                will not be printed.  This tag can be used to
                selectively print only a few parameter values out of
                many.  Default: 1 (all parameters printed)

  
  Future modifications to the PARINFO structure, if any, will involve
  adding structure tags beginning with the two letters "MP".
  Therefore programmers are urged to avoid using tags starting with
  the same letters; otherwise they are free to include their own
  fields within the PARINFO structure, and they will be ignored.
  
  PARINFO Example:
  parinfo = replicate({value:0.D, fixed:0, limited:[0,0], $
                       limits:[0.D,0]}, 5)
  parinfo(0).fixed = 1
  parinfo(4).limited(0) = 1
  parinfo(4).limits(0)  = 50.D
  parinfo(*).value = [5.7D, 2.2, 500., 1.5, 2000.]
  
  A total of 5 parameters, with starting values of 5.7,
  2.2, 500, 1.5, and 2000 are given.  The first parameter
  is fixed at a value of 5.7, and the last parameter is
  constrained to be above 50.

 INPUTS:
   X - Array of independent variable values.

   Y - Array of "measured" dependent variable values.  Y should have
       the same data type as X.  The function FUNCT should map
       X->Y.

   WEIGHTS - Array of weights to be used in calculating the
             chi-squared value.  If WEIGHTS is specified then the ERR
             parameter is ignored.  The chi-squared value is computed
             as follows:

                CHISQ = TOTAL( (Y-FUNCT(X,P))^2 * ABS(WEIGHTS) )

             Here are common values of WEIGHTS:

                1D/ERR^2 - Normal weighting (ERR is the measurement error)
                1D/Y     - Poisson weighting (counting statistics)
                1D       - Unweighted

   P - An array of starting values for each of the parameters of the
       model.  The number of parameters should be fewer than the
       number of measurements.  Also, the parameters should have the
       same data type as the measurements (double is preferred).

       Upon successful completion the new parameter values are
       returned in P.

       If both START_PARAMS and PARINFO are passed, then the starting
       *value* is taken from START_PARAMS, but the *constraints* are
       taken from PARINFO.
 
   SIGMA - The formal 1-sigma errors in each parameter, computed from
           the covariance matrix.  If a parameter is held fixed, or
           if it touches a boundary, then the error is reported as
           zero.

           If the fit is unweighted (i.e. no errors were given, or
           the weights were uniformly set to unity), then SIGMA will
           probably not represent the true parameter uncertainties.

           *If* you can assume that the true reduced chi-squared
           value is unity -- meaning that the fit is implicitly
           assumed to be of good quality -- then the estimated
           parameter uncertainties can be computed by scaling SIGMA
           by the measured chi-squared value.

              DOF     = N_ELEMENTS(X) - N_ELEMENTS(P) ; deg of freedom
              CSIGMA  = SIGMA * SQRT(CHISQ / DOF)     ; scaled uncertainties

 RETURNS:

   Returns the array containing the best-fitting function.

 KEYWORD PARAMETERS:

   CHISQ - the value of the summed, squared, weighted residuals for
           the returned parameter values, i.e. the chi-square value.

   COVAR - the covariance matrix for the set of parameters returned
           by MPFIT.  The matrix is NxN where N is the number of
           parameters.  The square root of the diagonal elements
           gives the formal 1-sigma statistical errors on the
           parameters IF errors were treated "properly" in MYFUNC.
           Parameter errors are also returned in PERROR.

           To compute the correlation matrix, PCOR, use this:
           IDL> PCOR = COV * 0
           IDL> FOR i = 0, n-1 DO FOR j = 0, n-1 DO $
                PCOR(i,j) = COV(i,j)/sqrt(COV(i,i)*COV(j,j))

           If NOCOVAR is set or MPFIT terminated abnormally, then
           COVAR is set to a scalar with value !VALUES.D_NAN.

   DOF - number of degrees of freedom, computed as
             DOF = N_ELEMENTS(DEVIATES) - NFREE
         Note that this doesn't account for pegged parameters (see
         NPEGGED).

   ERRMSG - a string error or warning message is returned.

   FTOL - a nonnegative input variable. Termination occurs when both
          the actual and predicted relative reductions in the sum of
          squares are at most FTOL (and STATUS is accordingly set to
          1 or 3).  Therefore, FTOL measures the relative error
          desired in the sum of squares.  Default: 1D-10

   FUNCTION_NAME - a scalar string containing the name of an IDL
                   procedure to compute the user model values, as
                   described above in the "USER MODEL" section.

   FUNCTARGS - A structure which contains the parameters to be passed
               to the user-supplied function specified by FUNCT via
               the _EXTRA mechanism.  This is the way you can pass
               additional data to your user-supplied function without
               using common blocks.

               By default, no extra parameters are passed to the
               user-supplied function.

   GTOL - a nonnegative input variable. Termination occurs when the
          cosine of the angle between fvec and any column of the
          jacobian is at most GTOL in absolute value (and STATUS is
          accordingly set to 4). Therefore, GTOL measures the
          orthogonality desired between the function vector and the
          columns of the jacobian.  Default: 1D-10

   ITER - the number of iterations completed.

   ITERARGS - The keyword arguments to be passed to ITERPROC via the
              _EXTRA mechanism.  This should be a structure, and is
              similar in operation to FUNCTARGS.
              Default: no arguments are passed.

   ITERPROC - The name of a procedure to be called upon each NPRINT
              iteration of the MPFIT routine.  It should be declared
              in the following way:

              PRO ITERPROC, FUNCT, p, iter, fnorm, FUNCTARGS=fcnargs, $
                PARINFO=parinfo, QUIET=quiet, ...
                ; perform custom iteration update
              END
         
              ITERPROC must either accept all three keyword
              parameters (FUNCTARGS, PARINFO and QUIET), or at least
              accept them via the _EXTRA keyword.
          
              FUNCT is the user-supplied function to be minimized,
              P is the current set of model parameters, ITER is the
              iteration number, and FUNCTARGS are the arguments to be
              passed to FUNCT.  FNORM should be the
              chi-squared value.  QUIET is set when no textual output
              should be printed.  See below for documentation of
              PARINFO.

              In implementation, ITERPROC can perform updates to the
              terminal or graphical user interface, to provide
              feedback while the fit proceeds.  If the fit is to be
              stopped for any reason, then ITERPROC should set the
              common block variable ERROR_CODE to negative value (see
              MPFIT_ERROR common block below).  In principle,
              ITERPROC should probably not modify the parameter
              values, because it may interfere with the algorithm's
              stability.  In practice it is allowed.

              Default: an internal routine is used to print the
                       parameter values.

   ITMAX - The maximum number of iterations to perform.  If the
             number is exceeded, then the STATUS value is set to 5
             and MPFIT returns.
             Default: 200 iterations

   NFEV - the number of FUNCT function evaluations performed.

   NFREE - the number of free parameters in the fit.  This includes
           parameters which are not FIXED and not TIED, but it does
           include parameters which are pegged at LIMITS.

   NOCOVAR - set this keyword to prevent the calculation of the
             covariance matrix before returning (see COVAR)

   NODERIVATIVE - if set, then the user function will not be queried
                  for analytical derivatives, and instead the
                  derivatives will be computed by finite differences
                  (and according to the PARINFO derivative settings;
                  see above for a description).

   NPRINT - The frequency with which ITERPROC is called.  A value of
            1 indicates that ITERPROC is called with every iteration,
            while 2 indicates every other iteration, etc.  Note that
            several Levenberg-Marquardt attempts can be made in a
            single iteration.
            Default value: 1

   PARINFO - Provides a mechanism for more sophisticated constraints
             to be placed on parameter values.  When PARINFO is not
             passed, then it is assumed that all parameters are free
             and unconstrained.  Values in PARINFO are never 
             modified during a call to MPFIT.

             See description above for the structure of PARINFO.

             Default value:  all parameters are free and unconstrained.

   QUIET - set this keyword when no textual output should be printed
           by MPFIT

   STATUS - an integer status code is returned.  All values other
            than zero can represent success.  It can have one of the
            following values:

	   0  improper input parameters.
         
	   1  both actual and predicted relative reductions
	      in the sum of squares are at most FTOL.
         
	   2  relative error between two consecutive iterates
	      is at most XTOL
         
	   3  conditions for STATUS = 1 and STATUS = 2 both hold.
         
	   4  the cosine of the angle between fvec and any
	      column of the jacobian is at most GTOL in
	      absolute value.
         
	   5  the maximum number of iterations has been reached
         
	   6  FTOL is too small. no further reduction in
	      the sum of squares is possible.
         
	   7  XTOL is too small. no further improvement in
	      the approximate solution x is possible.
         
	   8  GTOL is too small. fvec is orthogonal to the
	      columns of the jacobian to machine precision.

   TOL - synonym for FTOL.  Use FTOL instead.

   XTOL - a nonnegative input variable. Termination occurs when the
          relative error between two consecutive iterates is at most
          XTOL (and STATUS is accordingly set to 2 or 3).  Therefore,
          XTOL measures the relative error desired in the approximate
          solution.  Default: 1D-10

   YERROR - upon return, the root-mean-square variance of the
            residuals.


 EXAMPLE:

   ; First, generate some synthetic data
   npts = 200
   x  = dindgen(npts) * 0.1 - 10.                  ; Independent variable 
   yi = gauss1(x, [2.2D, 1.4, 3000.])              ; "Ideal" Y variable
   y  = yi + randomn(seed, npts) * sqrt(1000. + yi); Measured, w/ noise
   sy = sqrt(1000.D + y)                           ; Poisson errors

   ; Now fit a Gaussian to see how well we can recover
   p0 = [1.D, 1., 1000.]                           ; Initial guess
   yfit = mpcurvefit(x, y, 1/sy^2, p0, $           ; Fit a function
                     FUNCTION_NAME='GAUSS1P',/autoderivative)
   print, p

   Generates a synthetic data set with a Gaussian peak, and Poisson
   statistical uncertainty.  Then the same function is fitted to the
   data to see how close we can get.  GAUSS1 and GAUSS1P are
   available from the same web page.


 COMMON BLOCKS:

   COMMON MPFIT_ERROR, ERROR_CODE

     User routines may stop the fitting process at any time by
     setting an error condition.  This condition may be set in either
     the user's model computation routine (MYFUNCT), or in the
     iteration procedure (ITERPROC).

     To stop the fitting, the above common block must be declared,
     and ERROR_CODE must be set to a negative number.  After the user
     procedure or function returns, MPFIT checks the value of this
     common block variable and exits immediately if the error
     condition has been set.  By default the value of ERROR_CODE is
     zero, indicating a successful function/procedure call.

 REFERENCES:

   MINPACK-1, Jorge More', available from netlib (www.netlib.org).
   "Optimization Software Guide," Jorge More' and Stephen Wright, 
     SIAM, *Frontiers in Applied Mathematics*, Number 14.

 MODIFICATION HISTORY:
   Translated from MPFITFUN, 25 Sep 1999, CM
   Alphabetized documented keywords, 02 Oct 1999, CM
   Added QUERY keyword and query checking of MPFIT, 29 Oct 1999, CM
   Check to be sure that X and Y are present, 02 Nov 1999, CM
   Documented SIGMA for unweighted fits, 03 Nov 1999, CM
   Changed to ERROR_CODE for error condition, 28 Jan 2000, CM
   Copying permission terms have been liberalized, 26 Mar 2000, CM
   Propagated improvements from MPFIT, 17 Dec 2000, CM
   Corrected behavior of NODERIVATIVE, 13 May 2002, CM
   Documented RELSTEP field of PARINFO (!!), CM, 25 Oct 2002
   Make more consistent with comparable IDL routines, 30 Jun 2003, CM
   Minor documentation adjustment, 03 Feb 2004, CM
   Fix error in documentation, 26 Aug 2005, CM

  $Id: mpcurvefit.pro,v 1.2 2006/02/07 22:38:32 schlegel Exp $

(See pro/mpfit/mpcurvefit.pro)


MPFIT

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

 AUTHOR:
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov
   UPDATED VERSIONs can be found on my WEB PAGE: 
      http://cow.physics.wisc.edu/~craigm/idl/idl.html

 PURPOSE:
   Perform Levenberg-Marquardt least-squares minimization (MINPACK-1)

 MAJOR TOPICS:
   Curve and Surface Fitting

 CALLING SEQUENCE:
   parms = MPFIT(MYFUNCT, start_parms, FUNCTARGS=fcnargs, NFEV=nfev,
                 MAXITER=maxiter, ERRMSG=errmsg, NPRINT=nprint, QUIET=quiet, 
                 FTOL=ftol, XTOL=xtol, GTOL=gtol, NITER=niter, 
                 STATUS=status, ITERPROC=iterproc, ITERARGS=iterargs,
                 COVAR=covar, PERROR=perror, BESTNORM=bestnorm,
                 PARINFO=parinfo)

 DESCRIPTION:

  MPFIT uses the Levenberg-Marquardt technique to solve the
  least-squares problem.  In its typical use, MPFIT will be used to
  fit a user-supplied function (the "model") to user-supplied data
  points (the "data") by adjusting a set of parameters.  MPFIT is
  based upon MINPACK-1 (LMDIF.F) by More' and collaborators.

  For example, a researcher may think that a set of observed data
  points is best modelled with a Gaussian curve.  A Gaussian curve is
  parameterized by its mean, standard deviation and normalization.
  MPFIT will, within certain constraints, find the set of parameters
  which best fits the data.  The fit is "best" in the least-squares
  sense; that is, the sum of the weighted squared differences between
  the model and data is minimized.

  The Levenberg-Marquardt technique is a particular strategy for
  iteratively searching for the best fit.  This particular
  implementation is drawn from MINPACK-1 (see NETLIB), and seems to
  be more robust than routines provided with IDL.  This version
  allows upper and lower bounding constraints to be placed on each
  parameter, or the parameter can be held fixed.

  The IDL user-supplied function should return an array of weighted
  deviations between model and data.  In a typical scientific problem
  the residuals should be weighted so that each deviate has a
  gaussian sigma of 1.0.  If X represents values of the independent
  variable, Y represents a measurement for each value of X, and ERR
  represents the error in the measurements, then the deviates could
  be calculated as follows:

    DEVIATES = (Y - F(X)) / ERR

  where F is the analytical function representing the model.  You are
  recommended to use the convenience functions MPFITFUN and
  MPFITEXPR, which are driver functions that calculate the deviates
  for you.  If ERR are the 1-sigma uncertainties in Y, then

    TOTAL( DEVIATES^2 ) 

  will be the total chi-squared value.  MPFIT will minimize the
  chi-square value.  The values of X, Y and ERR are passed through
  MPFIT to the user-supplied function via the FUNCTARGS keyword.

  Simple constraints can be placed on parameter values by using the
  PARINFO keyword to MPFIT.  See below for a description of this
  keyword.

  MPFIT does not perform more general optimization tasks.  See TNMIN
  instead.  MPFIT is customized, based on MINPACK-1, to the
  least-squares minimization problem.

 USER FUNCTION

  The user must define a function which returns the appropriate
  values as specified above.  The function should return the weighted
  deviations between the model and the data.  For applications which
  use finite-difference derivatives -- the default -- the user
  function should be declared in the following way:

    FUNCTION MYFUNCT, p, X=x, Y=y, ERR=err
     ; Parameter values are passed in "p"
     model = F(x, p)
     return, (y-model)/err
    END

  See below for applications with analytical derivatives.

  The keyword parameters X, Y, and ERR in the example above are
  suggestive but not required.  Any parameters can be passed to
  MYFUNCT by using the FUNCTARGS keyword to MPFIT.  Use MPFITFUN and
  MPFITEXPR if you need ideas on how to do that.  The function *must*
  accept a parameter list, P.
  
  In general there are no restrictions on the number of dimensions in
  X, Y or ERR.  However the deviates *must* be returned in a
  one-dimensional array, and must have the same type (float or
  double) as the input arrays.

  User functions may also indicate a fatal error condition using the
  ERROR_CODE common block variable, as described below under the
  MPFIT_ERROR common block definition (by setting ERROR_CODE to a
  number between -15 and -1).

 ANALYTIC DERIVATIVES
 
  In the search for the best-fit solution, MPFIT by default
  calculates derivatives numerically via a finite difference
  approximation.  The user-supplied function need not calculate the
  derivatives explicitly.  However, if you desire to compute them
  analytically, then the AUTODERIVATIVE=0 keyword must be passed.  As
  a practical matter, it is often sufficient and even faster to allow
  MPFIT to calculate the derivatives numerically, and so
  AUTODERIVATIVE=0 is not necessary.

  Also, the user function must be declared with one additional
  parameter, as follows:

    FUNCTION MYFUNCT, p, dp, X=x, Y=y, ERR=err
     model = F(x, p)
     
     if n_params() GT 1 then begin
       ; Compute derivatives
       dp = make_array(n_elements(x), n_elements(p), value=x(0)*0)
       for i = 0, n_elements(p)-1 do $
         dp(*,i) = FGRAD(x, p, i)
     endif
    
     return, (y-model)/err
    END

  where FGRAD(x, p, i) is a user function which must compute the
  derivative of the model with respect to parameter P(i) at X.  When
  finite differencing is used for computing derivatives (ie, when
  AUTODERIVATIVE=1), the parameter DP is not passed.  Therefore
  functions can use N_PARAMS() to indicate whether they must compute
  the derivatives or not.

  Derivatives should be returned in the DP array. DP should be an m x
  n array, where m is the number of data points and n is the number
  of parameters.  dp(i,j) is the derivative at the ith point with
  respect to the jth parameter.  
  
  The derivatives with respect to fixed parameters are ignored; zero
  is an appropriate value to insert for those derivatives.  Upon
  input to the user function, DP is set to a vector with the same
  length as P, with a value of 1 for a parameter which is free, and a
  value of zero for a parameter which is fixed (and hence no
  derivative needs to be calculated).  This input vector may be
  overwritten as needed.

  If the data is higher than one dimensional, then the *last*
  dimension should be the parameter dimension.  Example: fitting a
  50x50 image, "dp" should be 50x50xNPAR.
  
 CONSTRAINING PARAMETER VALUES WITH THE PARINFO KEYWORD

  The behavior of MPFIT can be modified with respect to each
  parameter to be fitted.  A parameter value can be fixed; simple
  boundary constraints can be imposed; limitations on the parameter
  changes can be imposed; properties of the automatic derivative can
  be modified; and parameters can be tied to one another.

  These properties are governed by the PARINFO structure, which is
  passed as a keyword parameter to MPFIT.

  PARINFO should be an array of structures, one for each parameter.
  Each parameter is associated with one element of the array, in
  numerical order.  The structure can have the following entries
  (none are required):
  
     .VALUE - the starting parameter value (but see the START_PARAMS
              parameter for more information).
  
     .FIXED - a boolean value, whether the parameter is to be held
              fixed or not.  Fixed parameters are not varied by
              MPFIT, but are passed on to MYFUNCT for evaluation.
  
     .LIMITED - a two-element boolean array.  If the first/second
                element is set, then the parameter is bounded on the
                lower/upper side.  A parameter can be bounded on both
                sides.  Both LIMITED and LIMITS must be given
                together.
  
     .LIMITS - a two-element float or double array.  Gives the
               parameter limits on the lower and upper sides,
               respectively.  Zero, one or two of these values can be
               set, depending on the values of LIMITED.  Both LIMITED
               and LIMITS must be given together.
  
     .PARNAME - a string, giving the name of the parameter.  The
                fitting code of MPFIT does not use this tag in any
                way.  However, the default ITERPROC will print the
                parameter name if available.
  
     .STEP - the step size to be used in calculating the numerical
             derivatives.  If set to zero, then the step size is
             computed automatically.  Ignored when AUTODERIVATIVE=0.
             This value is superceded by the RELSTEP value.

     .RELSTEP - the *relative* step size to be used in calculating
                the numerical derivatives.  This number is the
                fractional size of the step, compared to the
                parameter value.  This value supercedes the STEP
                setting.  If the parameter is zero, then a default
                step size is chosen.

     .MPSIDE - the sidedness of the finite difference when computing
               numerical derivatives.  This field can take four
               values:

                  0 - one-sided derivative computed automatically
                  1 - one-sided derivative (f(x+h) - f(x)  )/h
                 -1 - one-sided derivative (f(x)   - f(x-h))/h
                  2 - two-sided derivative (f(x+h) - f(x-h))/(2*h)

              Where H is the STEP parameter described above.  The
              "automatic" one-sided derivative method will chose a
              direction for the finite difference which does not
              violate any constraints.  The other methods do not
              perform this check.  The two-sided method is in
              principle more precise, but requires twice as many
              function evaluations.  Default: 0.

     .MPMAXSTEP - the maximum change to be made in the parameter
                  value.  During the fitting process, the parameter
                  will never be changed by more than this value in
                  one iteration.

                  A value of 0 indicates no maximum.  Default: 0.
  
     .TIED - a string expression which "ties" the parameter to other
             free or fixed parameters as an equality constraint.  Any
             expression involving constants and the parameter array P
             are permitted.
             Example: if parameter 2 is always to be twice parameter
             1 then use the following: parinfo(2).tied = '2 * P(1)'.
             Since they are totally constrained, tied parameters are
             considered to be fixed; no errors are computed for them.
             [ NOTE: the PARNAME can't be used in expressions. ]

     .MPPRINT - if set to 1, then the default ITERPROC will print the
                parameter value.  If set to 0, the parameter value
                will not be printed.  This tag can be used to
                selectively print only a few parameter values out of
                many.  Default: 1 (all parameters printed)

     .MPFORMAT - IDL format string to print the parameter within
                 ITERPROC.  Default: '(G20.6)' An empty string will
                 also use the default.

  
  Future modifications to the PARINFO structure, if any, will involve
  adding structure tags beginning with the two letters "MP".
  Therefore programmers are urged to avoid using tags starting with
  the same letters; otherwise they are free to include their own
  fields within the PARINFO structure, and they will be ignored.
  
  PARINFO Example:
  parinfo = replicate({value:0.D, fixed:0, limited:[0,0], $
                       limits:[0.D,0]}, 5)
  parinfo(0).fixed = 1
  parinfo(4).limited(0) = 1
  parinfo(4).limits(0)  = 50.D
  parinfo(*).value = [5.7D, 2.2, 500., 1.5, 2000.]
  
  A total of 5 parameters, with starting values of 5.7,
  2.2, 500, 1.5, and 2000 are given.  The first parameter
  is fixed at a value of 5.7, and the last parameter is
  constrained to be above 50.


 HARD-TO-COMPUTE FUNCTIONS: "EXTERNAL" EVALUATION

  The normal mode of operation for MPFIT is for the user to pass a
  function name, and MPFIT will call the user function multiple times
  as it iterates toward a solution.

  Some user functions are particularly hard to compute using the
  standard model of MPFIT.  Usually these are functions that depend
  on a large amount of external data, and so it is not feasible, or
  at least highly impractical, to have MPFIT call it.  In those cases
  it may be possible to use the "(EXTERNAL)" evaluation option.

  In this case the user is responsible for making all function *and
  derivative* evaluations.  The function and Jacobian data are passed
  in through the EXTERNAL_FVEC and EXTERNAL_FJAC keywords,
  respectively.  The user indicates the selection of this option by
  specifying a function name (MYFUNCT) of "(EXTERNAL)".  No
  user-function calls are made when EXTERNAL evaluation is being
  used.

  At the end of each iteration, control returns to the user, who must
  reevaluate the function at its new parameter values.  Users should
  check the return value of the STATUS keyword, where a value of 9
  indicates the user should supply more data for the next iteration,
  and re-call MPFIT.  The user may refrain from calling MPFIT
  further; as usual, STATUS will indicate when the solution has
  converged and no more iterations are required.

  Because MPFIT must maintain its own data structures between calls,
  the user must also pass a named variable to the EXTERNAL_STATE
  keyword.  This variable must be maintained by the user, but not
  changed, throughout the fitting process.  When no more iterations
  are desired, the named variable may be discarded.


 INPUTS:
   MYFUNCT - a string variable containing the name of the function to
             be minimized.  The function should return the weighted
             deviations between the model and the data, as described
             above.

             For EXTERNAL evaluation of functions, this parameter
             should be set to a value of "(EXTERNAL)".

   START_PARAMS - An array of starting values for each of the
                  parameters of the model.  The number of parameters
                  should be fewer than the number of measurements.
                  Also, the parameters should have the same data type
                  as the measurements (double is preferred).

                  This parameter is optional if the PARINFO keyword
                  is used (but see PARINFO).  The PARINFO keyword
                  provides a mechanism to fix or constrain individual
                  parameters.  If both START_PARAMS and PARINFO are
                  passed, then the starting *value* is taken from
                  START_PARAMS, but the *constraints* are taken from
                  PARINFO.
 
 RETURNS:

   Returns the array of best-fit parameters.


 KEYWORD PARAMETERS:

   AUTODERIVATIVE - If this is set, derivatives of the function will
                    be computed automatically via a finite
                    differencing procedure.  If not set, then MYFUNCT
                    must provide the (analytical) derivatives.
                    Default: set (=1) 
                    NOTE: to supply your own analytical derivatives,
                      explicitly pass AUTODERIVATIVE=0

   BESTNORM - the value of the summed squared weighted residuals for
              the returned parameter values, i.e. TOTAL(DEVIATES^2).

   COVAR - the covariance matrix for the set of parameters returned
           by MPFIT.  The matrix is NxN where N is the number of
           parameters.  The square root of the diagonal elements
           gives the formal 1-sigma statistical errors on the
           parameters IF errors were treated "properly" in MYFUNC.
           Parameter errors are also returned in PERROR.

           To compute the correlation matrix, PCOR, use this example:
           IDL> PCOR = COV * 0
           IDL> FOR i = 0, n-1 DO FOR j = 0, n-1 DO $
                PCOR(i,j) = COV(i,j)/sqrt(COV(i,i)*COV(j,j))

           If NOCOVAR is set or MPFIT terminated abnormally, then
           COVAR is set to a scalar with value !VALUES.D_NAN.

   DOF - number of degrees of freedom, computed as
             DOF = N_ELEMENTS(DEVIATES) - NFREE
         Note that this doesn't account for pegged parameters (see
         NPEGGED).

   ERRMSG - a string error or warning message is returned.

   EXTERNAL_FVEC - upon input, the function values, evaluated at
                   START_PARAMS.  This should be an M-vector, where M
                   is the number of data points.

   EXTERNAL_FJAC - upon input, the Jacobian array of partial
                   derivative values.  This should be a M x N array,
                   where M is the number of data points and N is the
                   number of parameters.  NOTE: that all FIXED or
                   TIED parameters must *not* be included in this
                   array.

   EXTERNAL_STATE - a named variable to store MPFIT-related state
                    information between iterations (used in input and
                    output to MPFIT).  The user must not manipulate
                    or discard this data until the final iteration is
                    performed.

   FASTNORM - set this keyword to select a faster algorithm to
              compute sum-of-square values internally.  For systems
              with large numbers of data points, the standard
              algorithm can become prohibitively slow because it
              cannot be vectorized well.  By setting this keyword,
              MPFIT will run faster, but it will be more prone to
              floating point overflows and underflows.  Thus, setting
              this keyword may sacrifice some stability in the
              fitting process.
              
   FTOL - a nonnegative input variable. Termination occurs when both
          the actual and predicted relative reductions in the sum of
          squares are at most FTOL (and STATUS is accordingly set to
          1 or 3).  Therefore, FTOL measures the relative error
          desired in the sum of squares.  Default: 1D-10

   FUNCTARGS - A structure which contains the parameters to be passed
               to the user-supplied function specified by MYFUNCT via
               the _EXTRA mechanism.  This is the way you can pass
               additional data to your user-supplied function without
               using common blocks.

               Consider the following example:
                if FUNCTARGS = { XVAL:[1.D,2,3], YVAL:[1.D,4,9],
                                 ERRVAL:[1.D,1,1] }
                then the user supplied function should be declared
                like this:
                FUNCTION MYFUNCT, P, XVAL=x, YVAL=y, ERRVAL=err

               By default, no extra parameters are passed to the
               user-supplied function, but your function should
               accept *at least* one keyword parameter.  [ This is to
               accomodate a limitation in IDL's _EXTRA
               parameter-passing mechanism. ]

   GTOL - a nonnegative input variable. Termination occurs when the
          cosine of the angle between fvec and any column of the
          jacobian is at most GTOL in absolute value (and STATUS is
          accordingly set to 4). Therefore, GTOL measures the
          orthogonality desired between the function vector and the
          columns of the jacobian.  Default: 1D-10

   ITERARGS - The keyword arguments to be passed to ITERPROC via the
              _EXTRA mechanism.  This should be a structure, and is
              similar in operation to FUNCTARGS.
              Default: no arguments are passed.

   ITERPRINT - The name of an IDL procedure, equivalent to PRINT,
               that ITERPROC will use to render output.  ITERPRINT
               should be able to accept at least four positional
               arguments.  In addition, it should be able to accept
               the standard FORMAT keyword for output formatting; and
               the UNIT keyword, to redirect output to a logical file
               unit (default should be UNIT=1, standard output).
               These keywords are passed using the ITERARGS keyword
               above.  The ITERPRINT procedure must accept the _EXTRA
               keyword.

   ITERPROC - The name of a procedure to be called upon each NPRINT
              iteration of the MPFIT routine.  ITERPROC is always
              called in the final iteration.  It should be declared
              in the following way:

              PRO ITERPROC, MYFUNCT, p, iter, fnorm, FUNCTARGS=fcnargs, $
                PARINFO=parinfo, QUIET=quiet, DOF=dof, ...
                ; perform custom iteration update
              END
         
              ITERPROC must either accept all three keyword
              parameters (FUNCTARGS, PARINFO and QUIET), or at least
              accept them via the _EXTRA keyword.
          
              MYFUNCT is the user-supplied function to be minimized,
              P is the current set of model parameters, ITER is the
              iteration number, and FUNCTARGS are the arguments to be
              passed to MYFUNCT.  FNORM should be the chi-squared
              value.  QUIET is set when no textual output should be
              printed.  DOF is the number of degrees of freedom,
              normally the number of points less the number of free
              parameters.  See below for documentation of PARINFO.

              In implementation, ITERPROC can perform updates to the
              terminal or graphical user interface, to provide
              feedback while the fit proceeds.  If the fit is to be
              stopped for any reason, then ITERPROC should set the
              common block variable ERROR_CODE to negative value
              between -15 and -1 (see MPFIT_ERROR common block
              below).  In principle, ITERPROC should probably not
              modify the parameter values, because it may interfere
              with the algorithm's stability.  In practice it is
              allowed.

              Default: an internal routine is used to print the
                       parameter values.

   ITERSTOP - Set this keyword if you wish to be able to stop the
              fitting by hitting the predefined ITERKEYSTOP key on
              the keyboard.  This only works if you use the default
              ITERPROC.

   ITERKEYSTOP - A keyboard key which will halt the fit (and if
                 ITERSTOP is set and the default ITERPROC is used).
                 ITERSTOPKEY may either be a one-character string
                 with the desired key, or a scalar integer giving the
                 ASCII code of the desired key.  
                 Default: 7b (control-g)

                 NOTE: the default value of ASCI 7 (control-G) cannot
                 be read in some windowing environments, so you must
                 change to a printable character like 'q'.

   MAXITER - The maximum number of iterations to perform.  If the
             number is exceeded, then the STATUS value is set to 5
             and MPFIT returns.
             Default: 200 iterations

   NFEV - the number of MYFUNCT function evaluations performed.

   NFREE - the number of free parameters in the fit.  This includes
           parameters which are not FIXED and not TIED, but it does
           include parameters which are pegged at LIMITS.

   NITER - the number of iterations completed.

   NOCOVAR - set this keyword to prevent the calculation of the
             covariance matrix before returning (see COVAR)

   NPEGGED - the number of free parameters which are pegged at a
             LIMIT.

   NPRINT - The frequency with which ITERPROC is called.  A value of
            1 indicates that ITERPROC is called with every iteration,
            while 2 indicates every other iteration, etc.  Be aware
            that several Levenberg-Marquardt attempts can be made in
            a single iteration.  Also, the ITERPROC is *always*
            called for the final iteration, regardless of the
            iteration number.
            Default value: 1

   PARINFO - Provides a mechanism for more sophisticated constraints
             to be placed on parameter values.  When PARINFO is not
             passed, then it is assumed that all parameters are free
             and unconstrained.  Values in PARINFO are never 
             modified during a call to MPFIT.

             See description above for the structure of PARINFO.

             Default value:  all parameters are free and unconstrained.

   PERROR - The formal 1-sigma errors in each parameter, computed
            from the covariance matrix.  If a parameter is held
            fixed, or if it touches a boundary, then the error is
            reported as zero.

            If the fit is unweighted (i.e. no errors were given, or
            the weights were uniformly set to unity), then PERROR
            will probably not represent the true parameter
            uncertainties.  

            *If* you can assume that the true reduced chi-squared
            value is unity -- meaning that the fit is implicitly
            assumed to be of good quality -- then the estimated
            parameter uncertainties can be computed by scaling PERROR
            by the measured chi-squared value.

              DOF     = N_ELEMENTS(X) - N_ELEMENTS(PARMS) ; deg of freedom
              PCERROR = PERROR * SQRT(BESTNORM / DOF)   ; scaled uncertainties

   QUIET - set this keyword when no textual output should be printed
           by MPFIT

   RESDAMP - a scalar number, indicating the cut-off value of
             residuals where "damping" will occur.  Residuals with
             magnitudes greater than this number will be replaced by
             their logarithm.  This partially mitigates the so-called
             large residual problem inherent in least-squares solvers
             (as for the test problem CURVI, http://www.maxthis.com/-
             curviex.htm).  A value of 0 indicates no damping.
             Default: 0

             Note: RESDAMP doesn't work with AUTODERIV=0

   STATUS - an integer status code is returned.  All values greater
            than zero can represent success (however STATUS EQ 5 may
            indicate failure to converge).  It can have one of the
            following values:

        -16  a parameter or function value has become infinite or an
             undefined number.  This is usually a consequence of
             numerical overflow in the user's model function, which
             must be avoided.

        -15 to -1 
             these are error codes that either MYFUNCT or ITERPROC
             may return to terminate the fitting process (see
             description of MPFIT_ERROR common below).  If either
             MYFUNCT or ITERPROC set ERROR_CODE to a negative number,
             then that number is returned in STATUS.  Values from -15
             to -1 are reserved for the user functions and will not
             clash with MPFIT.

	   0  improper input parameters.
         
	   1  both actual and predicted relative reductions
	      in the sum of squares are at most FTOL.
         
	   2  relative error between two consecutive iterates
	      is at most XTOL
         
	   3  conditions for STATUS = 1 and STATUS = 2 both hold.
         
	   4  the cosine of the angle between fvec and any
	      column of the jacobian is at most GTOL in
	      absolute value.
         
	   5  the maximum number of iterations has been reached
         
	   6  FTOL is too small. no further reduction in
	      the sum of squares is possible.
         
	   7  XTOL is too small. no further improvement in
	      the approximate solution x is possible.
         
	   8  GTOL is too small. fvec is orthogonal to the
	      columns of the jacobian to machine precision.

          9  A successful single iteration has been completed, and
             the user must supply another "EXTERNAL" evaluation of
             the function and its derivatives.  This status indicator
             is neither an error nor a convergence indicator.

   XTOL - a nonnegative input variable. Termination occurs when the
          relative error between two consecutive iterates is at most
          XTOL (and STATUS is accordingly set to 2 or 3).  Therefore,
          XTOL measures the relative error desired in the approximate
          solution.  Default: 1D-10


 EXAMPLE:

   p0 = [5.7D, 2.2, 500., 1.5, 2000.]
   fa = {X:x, Y:y, ERR:err}
   p = mpfit('MYFUNCT', p0, functargs=fa)

   Minimizes sum of squares of MYFUNCT.  MYFUNCT is called with the X,
   Y, and ERR keyword parameters that are given by FUNCTARGS.  The
   resulting parameter values are returned in p.


 COMMON BLOCKS:

   COMMON MPFIT_ERROR, ERROR_CODE

     User routines may stop the fitting process at any time by
     setting an error condition.  This condition may be set in either
     the user's model computation routine (MYFUNCT), or in the
     iteration procedure (ITERPROC).

     To stop the fitting, the above common block must be declared,
     and ERROR_CODE must be set to a negative number.  After the user
     procedure or function returns, MPFIT checks the value of this
     common block variable and exits immediately if the error
     condition has been set.  This value is also returned in the
     STATUS keyword: values of -1 through -15 are reserved error
     codes for the user routines.  By default the value of ERROR_CODE
     is zero, indicating a successful function/procedure call.

   COMMON MPFIT_PROFILE
   COMMON MPFIT_MACHAR
   COMMON MPFIT_CONFIG

     These are undocumented common blocks are used internally by
     MPFIT and may change in future implementations.

 THEORY OF OPERATION:

   There are many specific strategies for function minimization.  One
   very popular technique is to use function gradient information to
   realize the local structure of the function.  Near a local minimum
   the function value can be taylor expanded about x0 as follows:

      f(x) = f(x0) + f'(x0) . (x-x0) + (1/2) (x-x0) . f''(x0) . (x-x0)
             -----   ---------------   -------------------------------  (1)
     Order    0th          1st                      2nd

   Here f'(x) is the gradient vector of f at x, and f''(x) is the
   Hessian matrix of second derivatives of f at x.  The vector x is
   the set of function parameters, not the measured data vector.  One
   can find the minimum of f, f(xm) using Newton's method, and
   arrives at the following linear equation:

      f''(x0) . (xm-x0) = - f'(x0)                            (2)

   If an inverse can be found for f''(x0) then one can solve for
   (xm-x0), the step vector from the current position x0 to the new
   projected minimum.  Here the problem has been linearized (ie, the
   gradient information is known to first order).  f''(x0) is
   symmetric n x n matrix, and should be positive definite.

   The Levenberg - Marquardt technique is a variation on this theme.
   It adds an additional diagonal term to the equation which may aid the
   convergence properties:

      (f''(x0) + nu I) . (xm-x0) = -f'(x0)                  (2a)

   where I is the identity matrix.  When nu is large, the overall
   matrix is diagonally dominant, and the iterations follow steepest
   descent.  When nu is small, the iterations are quadratically
   convergent.

   In principle, if f''(x0) and f'(x0) are known then xm-x0 can be
   determined.  However the Hessian matrix is often difficult or
   impossible to compute.  The gradient f'(x0) may be easier to
   compute, if even by finite difference techniques.  So-called
   quasi-Newton techniques attempt to successively estimate f''(x0)
   by building up gradient information as the iterations proceed.

   In the least squares problem there are further simplifications
   which assist in solving eqn (2).  The function to be minimized is
   a sum of squares:

       f = Sum(hi^2)                                         (3)

   where hi is the ith residual out of m residuals as described
   above.  This can be substituted back into eqn (2) after computing
   the derivatives:

       f'  = 2 Sum(hi  hi')     
       f'' = 2 Sum(hi' hj') + 2 Sum(hi hi'')                (4)

   If one assumes that the parameters are already close enough to a
   minimum, then one typically finds that the second term in f'' is
   negligible [or, in any case, is too difficult to compute].  Thus,
   equation (2) can be solved, at least approximately, using only
   gradient information.

   In matrix notation, the combination of eqns (2) and (4) becomes:

        hT' . h' . dx = - hT' . h                          (5)

   Where h is the residual vector (length m), hT is its transpose, h'
   is the Jacobian matrix (dimensions n x m), and dx is (xm-x0).  The
   user function supplies the residual vector h, and in some cases h'
   when it is not found by finite differences (see MPFIT_FDJAC2,
   which finds h and hT').  Even if dx is not the best absolute step
   to take, it does provide a good estimate of the best *direction*,
   so often a line minimization will occur along the dx vector
   direction.

   The method of solution employed by MINPACK is to form the Q . R
   factorization of h', where Q is an orthogonal matrix such that QT .
   Q = I, and R is upper right triangular.  Using h' = Q . R and the
   ortogonality of Q, eqn (5) becomes

        (RT . QT) . (Q . R) . dx = - (RT . QT) . h
                     RT . R . dx = - RT . QT . h         (6)
                          R . dx = - QT . h

   where the last statement follows because R is upper triangular.
   Here, R, QT and h are known so this is a matter of solving for dx.
   The routine MPFIT_QRFAC provides the QR factorization of h, with
   pivoting, and MPFIT_QRSOLV provides the solution for dx.
   
 REFERENCES:

   MINPACK-1, Jorge More', available from netlib (www.netlib.org).
   "Optimization Software Guide," Jorge More' and Stephen Wright, 
     SIAM, *Frontiers in Applied Mathematics*, Number 14.
   More', Jorge J., "The Levenberg-Marquardt Algorithm:
     Implementation and Theory," in *Numerical Analysis*, ed. Watson,
     G. A., Lecture Notes in Mathematics 630, Springer-Verlag, 1977.

 MODIFICATION HISTORY:
   Translated from MINPACK-1 in FORTRAN, Apr-Jul 1998, CM
   Fixed bug in parameter limits (x vs xnew), 04 Aug 1998, CM
   Added PERROR keyword, 04 Aug 1998, CM
   Added COVAR keyword, 20 Aug 1998, CM
   Added NITER output keyword, 05 Oct 1998
      D.L Windt, Bell Labs, windt@bell-labs.com;
   Made each PARINFO component optional, 05 Oct 1998 CM
   Analytical derivatives allowed via AUTODERIVATIVE keyword, 09 Nov 1998
   Parameter values can be tied to others, 09 Nov 1998
   Fixed small bugs (Wayne Landsman), 24 Nov 1998
   Added better exception error reporting, 24 Nov 1998 CM
   Cosmetic documentation changes, 02 Jan 1999 CM
   Changed definition of ITERPROC to be consistent with TNMIN, 19 Jan 1999 CM
   Fixed bug when AUTDERIVATIVE=0.  Incorrect sign, 02 Feb 1999 CM
   Added keyboard stop to MPFIT_DEFITER, 28 Feb 1999 CM
   Cosmetic documentation changes, 14 May 1999 CM
   IDL optimizations for speed & FASTNORM keyword, 15 May 1999 CM
   Tried a faster version of mpfit_enorm, 30 May 1999 CM
   Changed web address to cow.physics.wisc.edu, 14 Jun 1999 CM
   Found malformation of FDJAC in MPFIT for 1 parm, 03 Aug 1999 CM
   Factored out user-function call into MPFIT_CALL.  It is possible,
     but currently disabled, to call procedures.  The calling format
     is similar to CURVEFIT, 25 Sep 1999, CM
   Slightly changed mpfit_tie to be less intrusive, 25 Sep 1999, CM
   Fixed some bugs associated with tied parameters in mpfit_fdjac, 25
     Sep 1999, CM
   Reordered documentation; now alphabetical, 02 Oct 1999, CM
   Added QUERY keyword for more robust error detection in drivers, 29
     Oct 1999, CM
   Documented PERROR for unweighted fits, 03 Nov 1999, CM
   Split out MPFIT_RESETPROF to aid in profiling, 03 Nov 1999, CM
   Some profiling and speed optimization, 03 Nov 1999, CM
     Worst offenders, in order: fdjac2, qrfac, qrsolv, enorm.
     fdjac2 depends on user function, qrfac and enorm seem to be
     fully optimized.  qrsolv probably could be tweaked a little, but
     is still <10% of total compute time.
   Made sure that !err was set to 0 in MPFIT_DEFITER, 10 Jan 2000, CM
   Fixed small inconsistency in setting of QANYLIM, 28 Jan 2000, CM
   Added PARINFO field RELSTEP, 28 Jan 2000, CM
   Converted to MPFIT_ERROR common block for indicating error
     conditions, 28 Jan 2000, CM
   Corrected scope of MPFIT_ERROR common block, CM, 07 Mar 2000
   Minor speed improvement in MPFIT_ENORM, CM 26 Mar 2000
   Corrected case where ITERPROC changed parameter values and
     parameter values were TIED, CM 26 Mar 2000
   Changed MPFIT_CALL to modify NFEV automatically, and to support
     user procedures more, CM 26 Mar 2000
   Copying permission terms have been liberalized, 26 Mar 2000, CM
   Catch zero value of zero a(j,lj) in MPFIT_QRFAC, 20 Jul 2000, CM
      (thanks to David Schlegel <schlegel@astro.princeton.edu>)
   MPFIT_SETMACHAR is called only once at init; only one common block
     is created (MPFIT_MACHAR); it is now a structure; removed almost
     all CHECK_MATH calls for compatibility with IDL5 and !EXCEPT;
     profiling data is now in a structure too; noted some
     mathematical discrepancies in Linux IDL5.0, 17 Nov 2000, CM
   Some significant changes.  New PARINFO fields: MPSIDE, MPMINSTEP,
     MPMAXSTEP.  Improved documentation.  Now PTIED constraints are
     maintained in the MPCONFIG common block.  A new procedure to
     parse PARINFO fields.  FDJAC2 now computes a larger variety of
     one-sided and two-sided finite difference derivatives.  NFEV is
     stored in the MPCONFIG common now.  17 Dec 2000, CM
   Added check that PARINFO and XALL have same size, 29 Dec 2000 CM
   Don't call function in TERMINATE when there is an error, 05 Jan
     2000
   Check for float vs. double discrepancies; corrected implementation
     of MIN/MAXSTEP, which I still am not sure of, but now at least
     the correct behavior occurs *without* it, CM 08 Jan 2001
   Added SCALE_FCN keyword, to allow for scaling, as for the CASH
     statistic; added documentation about the theory of operation,
     and under the QR factorization; slowly I'm beginning to
     understand the bowels of this algorithm, CM 10 Jan 2001
   Remove MPMINSTEP field of PARINFO, for now at least, CM 11 Jan
     2001
   Added RESDAMP keyword, CM, 14 Jan 2001
   Tried to improve the DAMP handling a little, CM, 13 Mar 2001
   Corrected .PARNAME behavior in _DEFITER, CM, 19 Mar 2001
   Added checks for parameter and function overflow; a new STATUS
     value to reflect this; STATUS values of -15 to -1 are reserved
     for user function errors, CM, 03 Apr 2001
   DAMP keyword is now a TANH, CM, 03 Apr 2001
   Added more error checking of float vs. double, CM, 07 Apr 2001
   Fixed bug in handling of parameter lower limits; moved overflow
     checking to end of loop, CM, 20 Apr 2001
   Failure using GOTO, TERMINATE more graceful if FNORM1 not defined,
     CM, 13 Aug 2001
   Add MPPRINT tag to PARINFO, CM, 19 Nov 2001
   Add DOF keyword to DEFITER procedure, and print degrees of
     freedom, CM, 28 Nov 2001
   Add check to be sure MYFUNCT is a scalar string, CM, 14 Jan 2002
   Addition of EXTERNAL_FJAC, EXTERNAL_FVEC keywords; ability to save
     fitter's state from one call to the next; allow '(EXTERNAL)'
     function name, which implies that user will supply function and
     Jacobian at each iteration, CM, 10 Mar 2002
   Documented EXTERNAL evaluation code, CM, 10 Mar 2002
   Corrected signficant bug in the way that the STEP parameter, and
     FIXED parameters interacted (Thanks Andrew Steffl), CM, 02 Apr
     2002
   Allow COVAR and PERROR keywords to be computed, even in case of
     '(EXTERNAL)' function, 26 May 2002
   Add NFREE and NPEGGED keywords; compute NPEGGED; compute DOF using
     NFREE instead of n_elements(X), thanks to Kristian Kjaer, CM 11
     Sep 2002
   Hopefully PERROR is all positive now, CM 13 Sep 2002
   Documented RELSTEP field of PARINFO (!!), CM, 25 Oct 2002
   Error checking to detect missing start pars, CM 12 Apr 2003
   Add DOF keyword to return degrees of freedom, CM, 30 June 2003
   Always call ITERPROC in the final iteration; add ITERKEYSTOP
     keyword, CM, 30 June 2003
   Correct bug in MPFIT_LMPAR of singularity handling, which might
     likely be fatal for one-parameter fits, CM, 21 Nov 2003
     (with thanks to Peter Tuthill for the proper test case)
   Minor documentation adjustment, 03 Feb 2004, CM
   Correct small error in QR factorization when pivoting; document
     the return values of QRFAC when pivoting, 21 May 2004, CM
   Add MPFORMAT field to PARINFO, and correct behavior of interaction
     between MPPRINT and PARNAME in MPFIT_DEFITERPROC (thanks to Tim
     Robishaw), 23 May 2004, CM
   Add the ITERPRINT keyword to allow redirecting output, 26 Sep
     2004, CM
   Correct MAXSTEP behavior in case of a negative parameter, 26 Sep
     2004, CM
   Fix bug in the parsing of MINSTEP/MAXSTEP, 10 Apr 2005, CM
   Fix bug in the handling of upper/lower limits when the limit was
     negative (the fitting code would never "stick" to the lower
     limit), 29 Jun 2005, CM
   Small documentation update for the TIED field, 05 Sep 2005, CM

  $Id: mpfit.pro,v 1.2 2006/02/07 22:38:32 schlegel Exp $

(See pro/mpfit/mpfit.pro)


MPFIT2DFUN

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

 AUTHOR:
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov
   UPDATED VERSIONs can be found on my WEB PAGE: 
      http://cow.physics.wisc.edu/~craigm/idl/idl.html

 PURPOSE:
   Perform Levenberg-Marquardt least-squares fit to a 2-D IDL function

 MAJOR TOPICS:
   Curve and Surface Fitting

 CALLING SEQUENCE:
   parms = MPFIT2DFUN(MYFUNCT, X, Y, Z, ERR, start_parms, ...)

 DESCRIPTION:

  MPFIT2DFUN fits a user-supplied model -- in the form of an IDL
  function -- to a set of user-supplied data.  MPFIT2DFUN calls
  MPFIT, the MINPACK-1 least-squares minimizer, to do the main
  work.  MPFIT2DFUN is a specialized version for two-dimensional 
  data.

  Given the data and their uncertainties, MPFIT2DFUN finds the best set
  of model parameters which match the data (in a least-squares
  sense) and returns them in an array.
  
  The user must supply the following items:
   - Two arrays of independent variable values ("X", "Y").
   - An array of "measured" *dependent* variable values ("Z").
   - An array of "measured" 1-sigma uncertainty values ("ERR").
   - The name of an IDL function which computes Z given (X,Y) ("MYFUNCT").
   - Starting guesses for all of the parameters ("START_PARAMS").

  There are very few restrictions placed on X, Y, Z, or MYFUNCT.
  Simply put, MYFUNCT must map the (X,Y) values into Z values given
  the model parameters.  The (X,Y) values are usually the independent
  X and Y coordinate positions in the two dimensional plane, but need
  not be.

  MPFIT2DFUN carefully avoids passing large arrays where possible to
  improve performance.

  See below for an example of usage.
   
 USER FUNCTION

  The user must define a function which returns the model value.  For
  applications which use finite-difference derivatives -- the default
  -- the user function should be declared in the following way:

    FUNCTION MYFUNCT, X, Y, P
     ; The independent variables are X and Y
     ; Parameter values are passed in "P"
     ZMOD = ... computed model values at (X,Y) ...
     return, ZMOD
    END

  The returned array YMOD must have the same dimensions and type as
  the "measured" Z values.

  User functions may also indicate a fatal error condition
  using the ERROR_CODE common block variable, as described
  below under the MPFIT_ERROR common block definition.

  See the discussion under "ANALYTIC DERIVATIVES" and AUTODERIVATIVE
  in MPFIT.PRO if you wish to compute the derivatives for yourself.
  AUTODERIVATIVE is accepted and passed directly to MPFIT.  The user
  function must accept one additional parameter, DP, which contains
  the derivative of the user function with respect to each parameter
  at each data point, as described in MPFIT.PRO.

 CREATING APPROPRIATELY DIMENSIONED INDEPENDENT VARIABLES

  The user must supply appropriate independent variables to
  MPFIT2DFUN.  For image fitting applications, this variable should
  be two-dimensional *arrays* describing the X and Y positions of
  every *pixel*.  [ Thus any two dimensional sampling is permitted,
  including irregular sampling. ]
  
  If the sampling is regular, then the x coordinates are the same for
  each row, and the y coordinates are the same for each column.  Call
  the x-row and y-column coordinates XR and YC respectively.  You can
  then compute X and Y as follows:
  
      X = XR # (YC*0 + 1)             eqn. 1
      Y = (XR*0 + 1) # YC             eqn. 2
  
  For example, if XR and YC have the following values:
  
    XR = [  1, 2, 3, 4, 5,]  ;; X positions of one row of pixels
    YC = [ 15,16,17 ]        ;; Y positions of one column of
                                pixels
  
  Then using equations 1 and 2 above will give these values to X and
  Y:
  
     X :  1  2  3  4  5       ;; X positions of all pixels
          1  2  3  4  5
          1  2  3  4  5
  
     Y : 15 15 15 15 15       ;; Y positions of all pixels
         16 16 16 16 16
         17 17 17 17 17
  
  Using the above technique is suggested, but *not* required.  You
  can do anything you wish with the X and Y values.  This technique
  only makes it easier to compute your model function values.

 CONSTRAINING PARAMETER VALUES WITH THE PARINFO KEYWORD

  The behavior of MPFIT can be modified with respect to each
  parameter to be fitted.  A parameter value can be fixed; simple
  boundary constraints can be imposed; limitations on the parameter
  changes can be imposed; properties of the automatic derivative can
  be modified; and parameters can be tied to one another.

  These properties are governed by the PARINFO structure, which is
  passed as a keyword parameter to MPFIT.

  PARINFO should be an array of structures, one for each parameter.
  Each parameter is associated with one element of the array, in
  numerical order.  The structure can have the following entries
  (none are required):
  
     .VALUE - the starting parameter value (but see the START_PARAMS
              parameter for more information).
  
     .FIXED - a boolean value, whether the parameter is to be held
              fixed or not.  Fixed parameters are not varied by
              MPFIT, but are passed on to MYFUNCT for evaluation.
  
     .LIMITED - a two-element boolean array.  If the first/second
                element is set, then the parameter is bounded on the
                lower/upper side.  A parameter can be bounded on both
                sides.  Both LIMITED and LIMITS must be given
                together.
  
     .LIMITS - a two-element float or double array.  Gives the
               parameter limits on the lower and upper sides,
               respectively.  Zero, one or two of these values can be
               set, depending on the values of LIMITED.  Both LIMITED
               and LIMITS must be given together.
  
     .PARNAME - a string, giving the name of the parameter.  The
                fitting code of MPFIT does not use this tag in any
                way.  However, the default ITERPROC will print the
                parameter name if available.
  
     .STEP - the step size to be used in calculating the numerical
             derivatives.  If set to zero, then the step size is
             computed automatically.  Ignored when AUTODERIVATIVE=0.
             This value is superceded by the RELSTEP value.

     .RELSTEP - the *relative* step size to be used in calculating
                the numerical derivatives.  This number is the
                fractional size of the step, compared to the
                parameter value.  This value supercedes the STEP
                setting.  If the parameter is zero, then a default
                step size is chosen.

     .MPSIDE - the sidedness of the finite difference when computing
               numerical derivatives.  This field can take four
               values:

                  0 - one-sided derivative computed automatically
                  1 - one-sided derivative (f(x+h) - f(x)  )/h
                 -1 - one-sided derivative (f(x)   - f(x-h))/h
                  2 - two-sided derivative (f(x+h) - f(x-h))/(2*h)

              Where H is the STEP parameter described above.  The
              "automatic" one-sided derivative method will chose a
              direction for the finite difference which does not
              violate any constraints.  The other methods do not
              perform this check.  The two-sided method is in
              principle more precise, but requires twice as many
              function evaluations.  Default: 0.

     .MPMINSTEP - the minimum change to be made in the parameter
                  value.  During the fitting process, the parameter
                  will be changed by multiples of this value.  The
                  actual step is computed as:

                     DELTA1 = MPMINSTEP*ROUND(DELTA0/MPMINSTEP)

                  where DELTA0 and DELTA1 are the estimated parameter
                  changes before and after this constraint is
                  applied.  Note that this constraint should be used
                  with care since it may cause non-converging,
                  oscillating solutions.

                  A value of 0 indicates no minimum.  Default: 0.

     .MPMAXSTEP - the maximum change to be made in the parameter
                  value.  During the fitting process, the parameter
                  will never be changed by more than this value.

                  A value of 0 indicates no maximum.  Default: 0.
  
     .TIED - a string expression which "ties" the parameter to other
             free or fixed parameters.  Any expression involving
             constants and the parameter array P are permitted.
             Example: if parameter 2 is always to be twice parameter
             1 then use the following: parinfo(2).tied = '2 * P(1)'.
             Since they are totally constrained, tied parameters are
             considered to be fixed; no errors are computed for them.
             [ NOTE: the PARNAME can't be used in expressions. ]
  
  Future modifications to the PARINFO structure, if any, will involve
  adding structure tags beginning with the two letters "MP".
  Therefore programmers are urged to avoid using tags starting with
  the same letters; otherwise they are free to include their own
  fields within the PARINFO structure, and they will be ignored.
  
  PARINFO Example:
  parinfo = replicate({value:0.D, fixed:0, limited:[0,0], $
                       limits:[0.D,0]}, 5)
  parinfo(0).fixed = 1
  parinfo(4).limited(0) = 1
  parinfo(4).limits(0)  = 50.D
  parinfo(*).value = [5.7D, 2.2, 500., 1.5, 2000.]
  
  A total of 5 parameters, with starting values of 5.7,
  2.2, 500, 1.5, and 2000 are given.  The first parameter
  is fixed at a value of 5.7, and the last parameter is
  constrained to be above 50.

 INPUTS:
   MYFUNCT - a string variable containing the name of an IDL
             function.  This function computes the "model" Z values
             given the X,Y values and model parameters, as described above.

   X - Array of "X" independent variable values, as described above.
       These values are passed directly to the fitting function
       unmodified.

   Y - Array of "Y" independent variable values, as described
       above. X and Y should have the same data type.

   Z - Array of "measured" dependent variable values.  Z should have
       the same data type as X and Y.  The function MYFUNCT should
       map (X,Y)->Z.

   ERR - Array of "measured" 1-sigma uncertainties.  ERR should have
         the same data type as Z.  ERR is ignored if the WEIGHTS
         keyword is specified.

   START_PARAMS - An array of starting values for each of the
                  parameters of the model.  The number of parameters
                  should be fewer than the number of measurements.
                  Also, the parameters should have the same data type
                  as the measurements (double is preferred).

                  This parameter is optional if the PARINFO keyword
                  is used (see MPFIT).  The PARINFO keyword provides
                  a mechanism to fix or constrain individual
                  parameters.  If both START_PARAMS and PARINFO are
                  passed, then the starting *value* is taken from
                  START_PARAMS, but the *constraints* are taken from
                  PARINFO.
 
 RETURNS:

   Returns the array of best-fit parameters.

 KEYWORD PARAMETERS:

   BESTNORM - the value of the summed, squared, weighted residuals
              for the returned parameter values, i.e. the chi-square value.

   COVAR - the covariance matrix for the set of parameters returned
           by MPFIT.  The matrix is NxN where N is the number of
           parameters.  The square root of the diagonal elements
           gives the formal 1-sigma statistical errors on the
           parameters IF errors were treated "properly" in MYFUNC.
           Parameter errors are also returned in PERROR.

           To compute the correlation matrix, PCOR, use this:
           IDL> PCOR = COV * 0
           IDL> FOR i = 0, n-1 DO FOR j = 0, n-1 DO $
                PCOR(i,j) = COV(i,j)/sqrt(COV(i,i)*COV(j,j))

           If NOCOVAR is set or MPFIT terminated abnormally, then
           COVAR is set to a scalar with value !VALUES.D_NAN.

   DOF - number of degrees of freedom, computed as
             DOF = N_ELEMENTS(DEVIATES) - NFREE
         Note that this doesn't account for pegged parameters (see
         NPEGGED).

   ERRMSG - a string error or warning message is returned.

   FTOL - a nonnegative input variable. Termination occurs when both
          the actual and predicted relative reductions in the sum of
          squares are at most FTOL (and STATUS is accordingly set to
          1 or 3).  Therefore, FTOL measures the relative error
          desired in the sum of squares.  Default: 1D-10

   FUNCTARGS - A structure which contains the parameters to be passed
               to the user-supplied function specified by MYFUNCT via
               the _EXTRA mechanism.  This is the way you can pass
               additional data to your user-supplied function without
               using common blocks.

               By default, no extra parameters are passed to the
               user-supplied function.

   GTOL - a nonnegative input variable. Termination occurs when the
          cosine of the angle between fvec and any column of the
          jacobian is at most GTOL in absolute value (and STATUS is
          accordingly set to 4). Therefore, GTOL measures the
          orthogonality desired between the function vector and the
          columns of the jacobian.  Default: 1D-10

   ITERARGS - The keyword arguments to be passed to ITERPROC via the
              _EXTRA mechanism.  This should be a structure, and is
              similar in operation to FUNCTARGS.
              Default: no arguments are passed.

   ITERPROC - The name of a procedure to be called upon each NPRINT
              iteration of the MPFIT routine.  It should be declared
              in the following way:

              PRO ITERPROC, MYFUNCT, p, iter, fnorm, FUNCTARGS=fcnargs, $
                PARINFO=parinfo, QUIET=quiet, ...
                ; perform custom iteration update
              END
         
              ITERPROC must either accept all three keyword
              parameters (FUNCTARGS, PARINFO and QUIET), or at least
              accept them via the _EXTRA keyword.
          
              MYFUNCT is the user-supplied function to be minimized,
              P is the current set of model parameters, ITER is the
              iteration number, and FUNCTARGS are the arguments to be
              passed to MYFUNCT.  FNORM should be the
              chi-squared value.  QUIET is set when no textual output
              should be printed.  See below for documentation of
              PARINFO.

              In implementation, ITERPROC can perform updates to the
              terminal or graphical user interface, to provide
              feedback while the fit proceeds.  If the fit is to be
              stopped for any reason, then ITERPROC should set the
              common block variable ERROR_CODE to negative value (see
              MPFIT_ERROR common block below).  In principle,
              ITERPROC should probably not modify the parameter
              values, because it may interfere with the algorithm's
              stability.  In practice it is allowed.

              Default: an internal routine is used to print the
                       parameter values.

   MAXITER - The maximum number of iterations to perform.  If the
             number is exceeded, then the STATUS value is set to 5
             and MPFIT returns.
             Default: 200 iterations

   NFEV - the number of MYFUNCT function evaluations performed.

   NITER - the number of iterations completed.

   NOCOVAR - set this keyword to prevent the calculation of the
             covariance matrix before returning (see COVAR)

   NPRINT - The frequency with which ITERPROC is called.  A value of
            1 indicates that ITERPROC is called with every iteration,
            while 2 indicates every other iteration, etc.  Note that
            several Levenberg-Marquardt attempts can be made in a
            single iteration.
            Default value: 1

   PARINFO - Provides a mechanism for more sophisticated constraints
             to be placed on parameter values.  When PARINFO is not
             passed, then it is assumed that all parameters are free
             and unconstrained.  Values in PARINFO are never 
             modified during a call to MPFIT.

             See description above for the structure of PARINFO.

             Default value:  all parameters are free and unconstrained.

   PERROR - The formal 1-sigma errors in each parameter, computed
            from the covariance matrix.  If a parameter is held
            fixed, or if it touches a boundary, then the error is
            reported as zero.

            If the fit is unweighted (i.e. no errors were given, or
            the weights were uniformly set to unity), then PERROR
            will probably not represent the true parameter
            uncertainties.  *If* you can assume that the true reduced
            chi-squared value is unity -- meaning that the fit is
            implicitly assumed to be of good quality -- then the
            estimated parameter uncertainties can be computed by
            scaling PERROR by the measured chi-squared value.

              DOF     = N_ELEMENTS(Z) - N_ELEMENTS(PARMS) ; deg of freedom
              PCERROR = PERROR * SQRT(BESTNORM / DOF)   ; scaled uncertainties

   QUIET - set this keyword when no textual output should be printed
           by MPFIT

   STATUS - an integer status code is returned.  All values other
            than zero can represent success.  It can have one of the
            following values:

	   0  improper input parameters.
         
	   1  both actual and predicted relative reductions
	      in the sum of squares are at most FTOL.
         
	   2  relative error between two consecutive iterates
	      is at most XTOL
         
	   3  conditions for STATUS = 1 and STATUS = 2 both hold.
         
	   4  the cosine of the angle between fvec and any
	      column of the jacobian is at most GTOL in
	      absolute value.
         
	   5  the maximum number of iterations has been reached
         
	   6  FTOL is too small. no further reduction in
	      the sum of squares is possible.
         
	   7  XTOL is too small. no further improvement in
	      the approximate solution x is possible.
         
	   8  GTOL is too small. fvec is orthogonal to the
	      columns of the jacobian to machine precision.

   WEIGHTS - Array of weights to be used in calculating the
             chi-squared value.  If WEIGHTS is specified then the ERR
             parameter is ignored.  The chi-squared value is computed
             as follows:

                CHISQ = TOTAL( (Z-MYFUNCT(X,Y,P))^2 * ABS(WEIGHTS) )

             Here are common values of WEIGHTS:

                1D/ERR^2 - Normal weighting (ERR is the measurement error)
                1D/Z     - Poisson weighting (counting statistics)
                1D       - Unweighted

   XTOL - a nonnegative input variable. Termination occurs when the
          relative error between two consecutive iterates is at most
          XTOL (and STATUS is accordingly set to 2 or 3).  Therefore,
          XTOL measures the relative error desired in the approximate
          solution.  Default: 1D-10

   YFIT - the best-fit model function, as returned by MYFUNCT.

 EXAMPLE:

   p  = [2.2D, -0.7D, 1.4D, 3000.D]
   x  = (dindgen(200)*0.1 - 10.) # (dblarr(200) + 1)
   y  = (dblarr(200) + 1) # (dindgen(200)*0.1 - 10.)
   zi = gauss2(x, y, p)
   sz = sqrt(zi>1)
   z  = zi + randomn(seed, 200, 200) * sz

   p0 = [0D, 0D, 1D, 10D]
   p = mpfit2dfun('GAUSS2', x, y, z, sz, p0)
   
   Generates a synthetic data set with a Gaussian peak, and Poisson
   statistical uncertainty.  Then the same function (but different
   starting parameters) is fitted to the data to see how close we can
   get.

   It is especially worthy to notice that the X and Y values are
   created as full images, so that a coordinate is attached to each
   pixel independently.  This is the format that GAUSS2 accepts, and
   the easiest for you to use in your own functions.


 COMMON BLOCKS:

   COMMON MPFIT_ERROR, ERROR_CODE

     User routines may stop the fitting process at any time by
     setting an error condition.  This condition may be set in either
     the user's model computation routine (MYFUNCT), or in the
     iteration procedure (ITERPROC).

     To stop the fitting, the above common block must be declared,
     and ERROR_CODE must be set to a negative number.  After the user
     procedure or function returns, MPFIT checks the value of this
     common block variable and exits immediately if the error
     condition has been set.  By default the value of ERROR_CODE is
     zero, indicating a successful function/procedure call.


 REFERENCES:

   MINPACK-1, Jorge More', available from netlib (www.netlib.org).
   "Optimization Software Guide," Jorge More' and Stephen Wright, 
     SIAM, *Frontiers in Applied Mathematics*, Number 14.

 MODIFICATION HISTORY:
   Written, transformed from MPFITFUN, 26 Sep 1999, CM
   Alphabetized documented keywords, 02 Oct 1999, CM
   Added example, 02 Oct 1999, CM
   Tried to clarify definitions of X and Y, 29 Oct 1999, CM
   Added QUERY keyword and query checking of MPFIT, 29 Oct 1999, CM
   Check to be sure that X, Y and Z are present, 02 Nov 1999, CM
   Documented PERROR for unweighted fits, 03 Nov 1999, CM
   Changed to ERROR_CODE for error condition, 28 Jan 2000, CM
   Copying permission terms have been liberalized, 26 Mar 2000, CM
   Propagated improvements from MPFIT, 17 Dec 2000, CM
   Documented RELSTEP field of PARINFO (!!), CM, 25 Oct 2002
   Add DOF keyword to return degrees of freedom, CM, 23 June 2003
   Minor documentation adjustment, 03 Feb 2004, CM
   Fix the example to prevent zero errorbars, 28 Mar 2005, CM
   Defend against users supplying strangely dimensioned X and Y, 29
     Jun 2005, CM

  $Id: mpfit2dfun.pro,v 1.2 2006/02/07 22:38:32 schlegel Exp $

(See pro/mpfit/mpfit2dfun.pro)


MPFIT2DPEAK

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

 AUTHOR:
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov
   UPDATED VERSIONs can be found on my WEB PAGE: 
      http://cow.physics.wisc.edu/~craigm/idl/idl.html

 PURPOSE:
   Fit a gaussian, lorentzian or Moffat model to data

 MAJOR TOPICS:
   Curve and Surface Fitting

 CALLING SEQUENCE:
   yfit = MPFIT2DPEAK(Z, A [, X, Y, /TILT ...] )

 DESCRIPTION:

   MPFIT2DPEAK fits a gaussian, lorentzian or Moffat model using the
   non-linear least squares fitter MPFIT.  MPFIT2DPEAK is meant to be
   a drop-in replacement for IDL's GAUSS2DFIT function (and requires
   MPFIT and MPFIT2DFUN).

   The choice of the fitting function is determined by the keywords
   GAUSSIAN, LORENTZIAN and MOFFAT.  By default the gaussian model
   function is used.  [ The Moffat function is a modified Lorentzian
   with variable power law index. ]  The two-dimensional peak has
   independent semimajor and semiminor axes, with an optional
   rotation term activated by setting the TILT keyword.  The baseline
   is assumed to be a constant.

      GAUSSIAN      A(0) + A(1)*exp(-0.5*u)
      LORENTZIAN    A(0) + A(1)/(u + 1)
      MOFFAT        A(0) + A(1)/(u + 1)^A(7)

      u = ( (x-A(4))/A(2) )^2 + ( (y-A(5))/A(3) )^2

         where x and y are cartesian coordinates in rotated
         coordinate system if TILT keyword is set.

   The returned parameter array elements have the following meanings:

      A(0)   Constant baseline level
      A(1)   Peak value
      A(2)   Peak half-width (x) -- gaussian sigma or half-width at half-max
      A(3)   Peak half-width (y) -- gaussian sigma or half-width at half-max
      A(4)   Peak centroid (x)
      A(5)   Peak centroid (y)
      A(6)   Rotation angle (radians) if TILT keyword set
      A(7)   Moffat power law index if MOFFAT keyword set

   By default the initial starting values for the parameters A are
   estimated from the data.  However, explicit starting values can be
   supplied using the ESTIMATES keyword.  Also, error or weighting
   values can optionally be provided; otherwise the fit is
   unweighted.

 RESTRICTIONS:

   If no starting parameter ESTIMATES are provided, then MPFIT2DPEAK
   attempts to estimate them from the data.  This is not a perfect
   science; however, the author believes that the technique
   implemented here is more robust than the one used in IDL's
   GAUSS2DFIT.  The author has tested cases of strong peaks, noisy
   peaks and broad peaks, all with success.


 INPUTS:

   Z - Two dimensional array of "measured" dependent variable values.
       Z should be of the same type and dimension as (X # Y).

   X - Optional vector of x positions for a single row of Z.

          X(i) should provide the x position of Z(i,*)

       Default: X values are integer increments from 0 to NX-1

   Y - Optional vector of y positions for a single column of Z.

          Y(j) should provide the y position of Z(*,j)

       Default: Y values are integer increments from 0 to NY-1

 OUTPUTS:
   A - Upon return, an array of best fit parameter values.  See the
       table above for the meanings of each parameter element.


 RETURNS:

   Returns the best fitting model function as a 2D array.

 KEYWORDS:

   ** NOTE ** Additional keywords such as PARINFO, BESTNORM, and
              STATUS are accepted by MPFIT2DPEAK but not documented
              here.  Please see the documentation for MPFIT for the
              description of these advanced options.

   CHISQ - the value of the summed squared residuals for the
           returned parameter values.

   CIRCULAR - if set, then the peak profile is assumed to be
              azimuthally symmetric.  When set, the parameters A(2)
              and A(3) will be identical and the TILT keyword will
              have no effect.

   DOF - number of degrees of freedom, computed as
             DOF = N_ELEMENTS(DEVIATES) - NFREE
         Note that this doesn't account for pegged parameters (see
         NPEGGED).

   ERROR - upon input, the measured 1-sigma uncertainties in the "Z"
           values.  If no ERROR or WEIGHTS are given, then the fit is
           unweighted.

   ESTIMATES - Array of starting values for each parameter of the
               model.
               Default: parameter values are estimated from data.

   GAUSSIAN - if set, fit a gaussian model function.  The Default.
   LORENTZIAN - if set, fit a lorentzian model function.
   MOFFAT - if set, fit a Moffat model function.

   MEASURE_ERRORS - synonym for ERRORS, for consistency with built-in
                    IDL fitting routines.

   NEGATIVE - if set, and ESTIMATES is not provided, then MPFIT2DPEAK
              will assume that a negative peak is present -- a
              valley.  Specifying this keyword is not normally
              required, since MPFIT2DPEAK can determine this
              automatically.

   NFREE - the number of free parameters in the fit.  This includes
           parameters which are not FIXED and not TIED, but it does
           include parameters which are pegged at LIMITS.

   PERROR - upon return, the 1-sigma uncertainties of the parameter
            values A.  These values are only meaningful if the ERRORS
            or WEIGHTS keywords are specified properly.

            If the fit is unweighted (i.e. no errors were given, or
            the weights were uniformly set to unity), then PERROR
            will probably not represent the true parameter
            uncertainties.  

            *If* you can assume that the true reduced chi-squared
            value is unity -- meaning that the fit is implicitly
            assumed to be of good quality -- then the estimated
            parameter uncertainties can be computed by scaling PERROR
            by the measured chi-squared value.

              DOF     = N_ELEMENTS(Z) - N_ELEMENTS(A)   ; deg of freedom
              PCERROR = PERROR * SQRT(BESTNORM / DOF)   ; scaled uncertainties

   QUIET - if set then diagnostic fitting messages are suppressed.
           Default: QUIET=1 (i.e., no diagnostics)

   SIGMA - synonym for PERROR (1-sigma parameter uncertainties), for
           compatibility with GAUSSFIT.  Do not confuse this with the
           Gaussian "sigma" width parameter.

   TILT - if set, then the major and minor axes of the peak profile
          are allowed to rotate with respect to the image axes.
          Parameter A(6) will be set to the clockwise rotation angle
          of the A(2) axis in radians.

   WEIGHTS - Array of weights to be used in calculating the
             chi-squared value.  If WEIGHTS is specified then the ERR
             parameter is ignored.  The chi-squared value is computed
             as follows:

                CHISQ = TOTAL( (Z-MYFUNCT(X,Y,P))^2 * ABS(WEIGHTS) )

             Here are common values of WEIGHTS:

                1D/ERR^2 - Normal weighting (ERR is the measurement error)
                1D/Y     - Poisson weighting (counting statistics)
                1D       - Unweighted

             The ERROR keyword takes precedence over any WEIGHTS
             keyword values.  If no ERROR or WEIGHTS are given, then
             the fit is unweighted.


 EXAMPLE:

 ; Construct a sample gaussian surface in range [-5,5] centered at [2,-3]
   x = findgen(100)*0.1 - 5. & y = x
   xx = x # (y*0 + 1)
   yy = (x*0 + 1) # y
   rr = sqrt((xx-2.)^2 + (yy+3.)^2)

 ; Gaussian surface with sigma=0.5, peak value of 3, noise with sigma=0.2
   z = 3.*exp(-(rr/0.5)^2) + randomn(seed,100,100)*.2

 ; Fit gaussian parameters A
   zfit = mpfit2dpeak(z, a, x, y)

 REFERENCES:

   MINPACK-1, Jorge More', available from netlib (www.netlib.org).
   "Optimization Software Guide," Jorge More' and Stephen Wright, 
     SIAM, *Frontiers in Applied Mathematics*, Number 14.

 MODIFICATION HISTORY:

   New algorithm for estimating starting values, CM, 31 Oct 1999
   Documented, 02 Nov 1999
   Small documentation fixes, 02 Nov 1999
   Documented PERROR for unweighted fits, 03 Nov 1999, CM
   Copying permission terms have been liberalized, 26 Mar 2000, CM
   Small cosmetic changes, 21 Sep 2000, CM
   Corrected bug introduced by cosmetic changes, 11 Oct 2000, CM :-)
   Added POSITIVE keyword, 17 Nov 2000, CM
   Removed TILT in common, in favor of FUNCTARGS approach, 23 Nov
     2000, CM
   Added SYMMETRIC keyword, documentation for TILT, and an example,
     24 Nov 2000, CM
   Changed SYMMETRIC to CIRCULAR, 17 Dec 2000, CM
   Really change SYMMETRIC to CIRCULAR!, 13 Sep 2002, CM
   Add error messages for SYMMETRIC and CIRCLE, 08 Nov 2002, CM
   Make more consistent with comparable IDL routines, 30 Jun 2003, CM
   Defend against users supplying strangely dimensioned X and Y, 29
     Jun 2005, CM

  $Id: mpfit2dpeak.pro,v 1.2 2006/02/07 22:38:32 schlegel Exp $

(See pro/mpfit/mpfit2dpeak.pro)


MPFITELLIPSE

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

 AUTHOR:
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov
   UPDATED VERSIONs can be found on my WEB PAGE: 
      http://cow.physics.wisc.edu/~craigm/idl/idl.html

 PURPOSE:
   Approximate fit to points forming an ellipse

 MAJOR TOPICS:
   Curve and Surface Fitting

 CALLING SEQUENCE:
   parms = MPFITELLIPSE(X, Y, start_parms, [/TILT, WEIGHTS=wts, ...])

 DESCRIPTION:

   MPFITELLIPSE fits a closed elliptical or circular curve to a two
   dimensional set of data points.  The user specifies the X and Y
   positions of the points, and an optional set of weights.  The
   ellipse may also be tilted at an arbitrary angle.

   The best fitting ellipse parameters are returned from by
   MPFITELLIPSE as a vector, whose values are:

      P(0)   Ellipse semi axis 1
      P(1)   Ellipse semi axis 2   ( = P(0) if CIRCLE keyword set)
      P(2)   Ellipse center - x value
      P(3)   Ellipse center - y value
      P(4)   Ellipse rotation angle (radians) if TILT keyword set

   The user may specify an initial set of trial parameters, but by
   default MPFITELLIPSE will estimate the parameters automatically.

   Users should be aware that in the presence of large amounts of
   noise, namely when the measurement error becomes significant
   compared to the ellipse axis length, then the estimated parameters
   become unreliable.  Generally speaking the computed axes will
   overestimate the true axes.  For example when (SIGMA_R/R) becomes
   0.5, the radius of the ellipse is overestimated by about 40%.

   Users can weight their data as they see appropriate.  However, the
   following prescription for the weighting appears to be the correct
   one, and produces values comparable to the typical chi-squared
   value.

     WEIGHTS = 0.75/(SIGMA_X^2 + SIGMA_Y^2)

   where SIGMA_X and SIGMA_Y are the measurement error vectors in the
   X and Y directions respectively.  However, it should be pointed
   out that this weighting is only appropriate for a set of points
   whose measurement errors are comparable.  If a more robust
   estimation of the parameter values is needed, the so-called
   orthogonal distance regression package should be used (ODRPACK,
   available in FORTRAN at www.netlib.org).

 INPUTS:

   X - measured X positions of the points in the ellipse.
   Y - measured Y positions of the points in the ellipse.

   START_PARAMS - an array of starting values for the ellipse
                  parameters, as described above.  This parameter is
                  optional; if not specified by the user, then the
                  ellipse parameters are estimated automatically from
                  the properties of the data.

 RETURNS:

   Returns the best fitting model ellipse parameters.

 KEYWORDS:

   ** NOTE ** Additional keywords such as PARINFO, BESTNORM, and
              STATUS are accepted by MPFITELLIPSE but not documented
              here.  Please see the documentation for MPFIT for the
              description of these advanced options.

   PERROR - upon return, the 1-sigma uncertainties of the returned
            ellipse parameter values.  These values are only
            meaningful if the WEIGHTS keyword is specified properly.

            If the fit is unweighted (i.e. no errors were given, or
            the weights were uniformly set to unity), then PERROR
            will probably not represent the true parameter
            uncertainties.  

   QUIET - if set then diagnostic fitting messages are suppressed.
           Default: QUIET=1 (i.e., no diagnostics)

   CIRCULAR - if set, then the curve is assumed to be a circle
              instead of ellipse.  When set, the parameters P(0) and
              P(1) will be identical and the TILT keyword will have
              no effect.

   TILT - if set, then the major and minor axes of the ellipse
          are allowed to rotate with respect to the data axes.
          Parameter P(4) will be set to the clockwise rotation angle
          of the P(0) axis in radians.

   WEIGHTS - Array of weights to be used in calculating the
             chi-squared value.  If WEIGHTS is specified then the ERR
             parameter is ignored.  The chi-squared value is computed
             as follows:

                CHISQ = TOTAL( (Z-MYFUNCT(X,Y,P))^2 * ABS(WEIGHTS)^2 )

             Users may wish to follow the guidelines for WEIGHTS
             described above.


 EXAMPLE:

 ; Construct a set of points on an ellipse, with some noise
   ph0 = 2*!pi*randomu(seed,50)
   x =  50. + 32.*cos(ph0) + 4.0*randomn(seed, 50)
   y = -75. + 65.*sin(ph0) + 0.1*randomn(seed, 50)

 ; Compute weights function
   weights = 0.75/(4.0^2 + 0.1^2)

 ; Fit ellipse and plot result
   p = mpfitellipse(x, y)
   plot, x, y, psym=1
   phi = dindgen(101)*2D*!dpi/100
   oplot, p(2)+p(0)*cos(phi), p(3)+p(1)*sin(phi)

 REFERENCES:

   MINPACK-1, Jorge More', available from netlib (www.netlib.org).
   "Optimization Software Guide," Jorge More' and Stephen Wright, 
     SIAM, *Frontiers in Applied Mathematics*, Number 14.

 MODIFICATION HISTORY:

   Ported from MPFIT2DPEAK, 17 Dec 2000, CM
   More documentation, 11 Jan 2001, CM
   Example corrected, 18 Nov 2001, CM
   Change CIRCLE keyword to the correct CIRCULAR keyword, 13 Sep
      2002, CM
   Add error messages for SYMMETRIC and CIRCLE, 08 Nov 2002, CM
   Found small error in computation of _EVAL (when CIRCULAR) was set;
      sanity check when CIRCULAR is set, 21 Jan 2003, CM

  $Id: mpfitellipse.pro,v 1.1 2006/02/07 22:38:32 schlegel Exp $

(See pro/mpfit/mpfitellipse.pro)


MPFITEXPR

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

 AUTHOR:
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov
   UPDATED VERSIONs can be found on my WEB PAGE: 
      http://cow.physics.wisc.edu/~craigm/idl/idl.html

 PURPOSE:
   Perform Levenberg-Marquardt least-squares fit to arbitrary expression

 MAJOR TOPICS:
   Curve and Surface Fitting

 CALLING SEQUENCE:
   MYFUNCT = 'X*(1-X)+3'
   parms = MPFITEXPR(MYFUNCT, XVAL, YVAL, ERR, start_parms, ...)

 DESCRIPTION:

  MPFITEXPR fits a user-supplied model -- in the form of an arbitrary IDL
  expression -- to a set of user-supplied data.  MPFITEXPR calls
  MPFIT, the MINPACK-1 least-squares minimizer, to do the main
  work.

  Given the data and their uncertainties, MPFITEXPR finds the best set
  of model parameters which match the data (in a least-squares
  sense) and returns them in an array.
  
  The user must supply the following items:
   - An array of independent variable values ("X").
   - An array of "measured" *dependent* variable values ("Y").
   - An array of "measured" 1-sigma uncertainty values ("ERR").
   - A text IDL expression which computes Y given X.
   - Starting guesses for all of the parameters ("START_PARAMS").

  There are very few restrictions placed on X, Y or the expression of
  the model.  Simply put, the expression must map the "X" values into
  "Y" values given the model parameters.  The "X" values may
  represent any independent variable (not just Cartesian X), and
  indeed may be multidimensional themselves.  For example, in the
  application of image fitting, X may be a 2xN array of image
  positions.

  Some rules must be obeyed in constructing the expression.  First,
  the independent variable name *MUST* be "X" in the expression,
  regardless of the name of the variable being passed to MPFITEXPR.
  This is demonstrated in the above calling sequence, where the X
  variable passed in is called "XVAL" but the expression still refers
  to "X".  Second, parameter values must be referred to as an array
  named "P".

  If you do not pass in starting values for the model parameters,
  MPFITEXPR will attempt to determine the number of parameters you
  intend to have (it does this by looking for references to the array
  variable named "P").  When no starting values are passed in, the
  values are assumed to start at zero.

  MPFITEXPR carefully avoids passing large arrays where possible to
  improve performance.

  See below for an example of usage.

 EVALUATING EXPRESSIONS

  This source module also provides a function called MPEVALEXPR.  You
  can use this function to evaluate your expression, given a list of
  parameters.  This is one of the easier ways to compute the model
  once the best-fit parameters have been found.  Here is an example:

       YMOD = MPEVALEXPR(MYFUNCT, XVAL, PARMS)

  where MYFUNCT is the expression (see MYFUNCT below), XVAL is the
  list of "X" values, and PARMS is an array of parameters.  The
  returned array YMOD contains the expression MYFUNCT evaluated at
  each point in XVAL.

 PASSING PRIVATE DATA TO AN EXPRESSION

  The most complicated optimization problems typically involve other
  external parameters, in addition to the fitted parameters.  While
  it is extremely easy to rewrite an expression dynamically, in case
  one of the external parameters changes, the other possibility is to
  use the PRIVATE data structure.

  The user merely passes a structure to the FUNCTARGS keyword.  The
  user expression receives this value as the variable PRIVATE.
  MPFITEXPR nevers accesses this variable so it can contain any
  desired values.  Usually it would be an IDL structure so that any
  named external parameters can be passed to the expression.


 CONSTRAINING PARAMETER VALUES WITH THE PARINFO KEYWORD

  The behavior of MPFIT can be modified with respect to each
  parameter to be fitted.  A parameter value can be fixed; simple
  boundary constraints can be imposed; limitations on the parameter
  changes can be imposed; properties of the automatic derivative can
  be modified; and parameters can be tied to one another.

  These properties are governed by the PARINFO structure, which is
  passed as a keyword parameter to MPFIT.

  PARINFO should be an array of structures, one for each parameter.
  Each parameter is associated with one element of the array, in
  numerical order.  The structure can have the following entries
  (none are required):
  
     .VALUE - the starting parameter value (but see the START_PARAMS
              parameter for more information).
  
     .FIXED - a boolean value, whether the parameter is to be held
              fixed or not.  Fixed parameters are not varied by
              MPFIT, but are passed on to MYFUNCT for evaluation.
  
     .LIMITED - a two-element boolean array.  If the first/second
                element is set, then the parameter is bounded on the
                lower/upper side.  A parameter can be bounded on both
                sides.  Both LIMITED and LIMITS must be given
                together.
  
     .LIMITS - a two-element float or double array.  Gives the
               parameter limits on the lower and upper sides,
               respectively.  Zero, one or two of these values can be
               set, depending on the values of LIMITED.  Both LIMITED
               and LIMITS must be given together.
  
     .PARNAME - a string, giving the name of the parameter.  The
                fitting code of MPFIT does not use this tag in any
                way.  However, the default ITERPROC will print the
                parameter name if available.
  
     .STEP - the step size to be used in calculating the numerical
             derivatives.  If set to zero, then the step size is
             computed automatically.  Ignored when AUTODERIVATIVE=0.
             This value is superceded by the RELSTEP value.

     .RELSTEP - the *relative* step size to be used in calculating
                the numerical derivatives.  This number is the
                fractional size of the step, compared to the
                parameter value.  This value supercedes the STEP
                setting.  If the parameter is zero, then a default
                step size is chosen.

     .MPSIDE - the sidedness of the finite difference when computing
               numerical derivatives.  This field can take four
               values:

                  0 - one-sided derivative computed automatically
                  1 - one-sided derivative (f(x+h) - f(x)  )/h
                 -1 - one-sided derivative (f(x)   - f(x-h))/h
                  2 - two-sided derivative (f(x+h) - f(x-h))/(2*h)

              Where H is the STEP parameter described above.  The
              "automatic" one-sided derivative method will chose a
              direction for the finite difference which does not
              violate any constraints.  The other methods do not
              perform this check.  The two-sided method is in
              principle more precise, but requires twice as many
              function evaluations.  Default: 0.

     .MPMINSTEP - the minimum change to be made in the parameter
                  value.  During the fitting process, the parameter
                  will be changed by multiples of this value.  The
                  actual step is computed as:

                     DELTA1 = MPMINSTEP*ROUND(DELTA0/MPMINSTEP)

                  where DELTA0 and DELTA1 are the estimated parameter
                  changes before and after this constraint is
                  applied.  Note that this constraint should be used
                  with care since it may cause non-converging,
                  oscillating solutions.

                  A value of 0 indicates no minimum.  Default: 0.

     .MPMAXSTEP - the maximum change to be made in the parameter
                  value.  During the fitting process, the parameter
                  will never be changed by more than this value.

                  A value of 0 indicates no maximum.  Default: 0.
  
     .TIED - a string expression which "ties" the parameter to other
             free or fixed parameters.  Any expression involving
             constants and the parameter array P are permitted.
             Example: if parameter 2 is always to be twice parameter
             1 then use the following: parinfo(2).tied = '2 * P(1)'.
             Since they are totally constrained, tied parameters are
             considered to be fixed; no errors are computed for them.
             [ NOTE: the PARNAME can't be used in expressions. ]
  
  Future modifications to the PARINFO structure, if any, will involve
  adding structure tags beginning with the two letters "MP".
  Therefore programmers are urged to avoid using tags starting with
  the same letters; otherwise they are free to include their own
  fields within the PARINFO structure, and they will be ignored.
  
  PARINFO Example:
  parinfo = replicate({value:0.D, fixed:0, limited:[0,0], $
                       limits:[0.D,0]}, 5)
  parinfo(0).fixed = 1
  parinfo(4).limited(0) = 1
  parinfo(4).limits(0)  = 50.D
  parinfo(*).value = [5.7D, 2.2, 500., 1.5, 2000.]
  
  A total of 5 parameters, with starting values of 5.7,
  2.2, 500, 1.5, and 2000 are given.  The first parameter
  is fixed at a value of 5.7, and the last parameter is
  constrained to be above 50.

 INPUTS:
   MYFUNCT - a string variable containing an IDL expression.  The
             only restriction is that the independent variable *must*
             be referred to as "X" and model parameters *must* be
             referred to as an array called "P".  Do not use symbol
             names beginning with the underscore, "_".

             The expression should calculate "model" Y values given
             the X values and model parameters.  Using the vector
             notation of IDL, this can be quite easy to do.  If your
             expression gets complicated, you may wish to make an IDL
             function which will improve performance and readibility.

             The resulting array should be of the same size and
             dimensions as the "measured" Y values.

   X - Array of independent variable values.

   Y - Array of "measured" dependent variable values.  Y should have
       the same data type as X.  The function MYFUNCT should map
       X->Y.

   ERR - Array of "measured" 1-sigma uncertainties.  ERR should have
         the same data type as Y.  ERR is ignored if the WEIGHTS
         keyword is specified.

   START_PARAMS - An array of starting values for each of the
                  parameters of the model.  The number of parameters
                  should be fewer than the number of measurements.
                  Also, the parameters should have the same data type
                  as the measurements (double is preferred).

                  This parameter is optional if the PARINFO keyword
                  is used (see MPFIT).  The PARINFO keyword provides
                  a mechanism to fix or constrain individual
                  parameters.  If both START_PARAMS and PARINFO are
                  passed, then the starting *value* is taken from
                  START_PARAMS, but the *constraints* are taken from
                  PARINFO.

                  If no parameters are given, then MPFITEXPR attempts
                  to determine the number of parameters by scanning
                  the expression.  Parameters determined this way are
                  initialized to zero.  This technique is not fully
                  reliable, so users are advised to pass explicit
                  parameter starting values.
 

 RETURNS:

   Returns the array of best-fit parameters.


 KEYWORD PARAMETERS:

   BESTNORM - the value of the summed, squared, weighted residuals
              for the returned parameter values, i.e. the chi-square value.

   COVAR - the covariance matrix for the set of parameters returned
           by MPFIT.  The matrix is NxN where N is the number of
           parameters.  The square root of the diagonal elements
           gives the formal 1-sigma statistical errors on the
           parameters IF errors were treated "properly" in MYFUNC.
           Parameter errors are also returned in PERROR.

           To compute the correlation matrix, PCOR, use this:
           IDL> PCOR = COV * 0
           IDL> FOR i = 0, n-1 DO FOR j = 0, n-1 DO $
                PCOR(i,j) = COV(i,j)/sqrt(COV(i,i)*COV(j,j))

           If NOCOVAR is set or MPFIT terminated abnormally, then
           COVAR is set to a scalar with value !VALUES.D_NAN.

   DOF - number of degrees of freedom, computed as
             DOF = N_ELEMENTS(DEVIATES) - NFREE
         Note that this doesn't account for pegged parameters (see
         NPEGGED).

   ERRMSG - a string error or warning message is returned.

   FTOL - a nonnegative input variable. Termination occurs when both
          the actual and predicted relative reductions in the sum of
          squares are at most FTOL (and STATUS is accordingly set to
          1 or 3).  Therefore, FTOL measures the relative error
          desired in the sum of squares.  Default: 1D-10

   FUNCTARGS - passed directly to the expression as the variable
               PRIVATE.  Any user-private data can be communicated to
               the user expression using this keyword.
               Default: PRIVATE is undefined in user expression

   GTOL - a nonnegative input variable. Termination occurs when the
          cosine of the angle between fvec and any column of the
          jacobian is at most GTOL in absolute value (and STATUS is
          accordingly set to 4). Therefore, GTOL measures the
          orthogonality desired between the function vector and the
          columns of the jacobian.  Default: 1D-10

   ITERARGS - The keyword arguments to be passed to ITERPROC via the
              _EXTRA mechanism.  This should be a structure, and is
              similar in operation to FUNCTARGS.
              Default: no arguments are passed.

   ITERPROC - The name of a procedure to be called upon each NPRINT
              iteration of the MPFIT routine.  It should be declared
              in the following way:

              PRO ITERPROC, MYFUNCT, p, iter, fnorm, FUNCTARGS=fcnargs, $
                PARINFO=parinfo, QUIET=quiet, ...
                ; perform custom iteration update
              END
         
              ITERPROC must either accept all three keyword
              parameters (FUNCTARGS, PARINFO and QUIET), or at least
              accept them via the _EXTRA keyword.
          
              MYFUNCT is the user-supplied function to be minimized,
              P is the current set of model parameters, ITER is the
              iteration number, and FUNCTARGS are the arguments to be
              passed to MYFUNCT.  FNORM should be the
              chi-squared value.  QUIET is set when no textual output
              should be printed.  See below for documentation of
              PARINFO.

              In implementation, ITERPROC can perform updates to the
              terminal or graphical user interface, to provide
              feedback while the fit proceeds.  If the fit is to be
              stopped for any reason, then ITERPROC should set the
              common block variable ERROR_CODE to negative value (see
              MPFIT_ERROR common block below).  In principle,
              ITERPROC should probably not modify the parameter
              values, because it may interfere with the algorithm's
              stability.  In practice it is allowed.

              Default: an internal routine is used to print the
                       parameter values.

   MAXITER - The maximum number of iterations to perform.  If the
             number is exceeded, then the STATUS value is set to 5
             and MPFIT returns.
             Default: 200 iterations

   NFEV - the number of MYFUNCT function evaluations performed.

   NFREE - the number of free parameters in the fit.  This includes
           parameters which are not FIXED and not TIED, but it does
           include parameters which are pegged at LIMITS.

   NITER - the number of iterations completed.

   NOCOVAR - set this keyword to prevent the calculation of the
             covariance matrix before returning (see COVAR)

   NPEGGED - the number of free parameters which are pegged at a
             LIMIT.

   NPRINT - The frequency with which ITERPROC is called.  A value of
            1 indicates that ITERPROC is called with every iteration,
            while 2 indicates every other iteration, etc.  Note that
            several Levenberg-Marquardt attempts can be made in a
            single iteration.
            Default value: 1

   PARINFO - Provides a mechanism for more sophisticated constraints
             to be placed on parameter values.  When PARINFO is not
             passed, then it is assumed that all parameters are free
             and unconstrained.  Values in PARINFO are never 
             modified during a call to MPFIT.

             See description above for the structure of PARINFO.

             Default value:  all parameters are free and unconstrained.

   PERROR - The formal 1-sigma errors in each parameter, computed
            from the covariance matrix.  If a parameter is held
            fixed, or if it touches a boundary, then the error is
            reported as zero.

            If the fit is unweighted (i.e. no errors were given, or
            the weights were uniformly set to unity), then PERROR
            will probably not represent the true parameter
            uncertainties.  

            *If* you can assume that the true reduced chi-squared
            value is unity -- meaning that the fit is implicitly
            assumed to be of good quality -- then the estimated
            parameter uncertainties can be computed by scaling PERROR
            by the measured chi-squared value.

              DOF     = N_ELEMENTS(X) - N_ELEMENTS(PARMS) ; deg of freedom
              PCERROR = PERROR * SQRT(BESTNORM / DOF)   ; scaled uncertainties

   QUIET - set this keyword when no textual output should be printed
           by MPFIT

   STATUS - an integer status code is returned.  All values other
            than zero can represent success.  It can have one of the
            following values:

	   0  improper input parameters.
         
	   1  both actual and predicted relative reductions
	      in the sum of squares are at most FTOL.
         
	   2  relative error between two consecutive iterates
	      is at most XTOL
         
	   3  conditions for STATUS = 1 and STATUS = 2 both hold.
         
	   4  the cosine of the angle between fvec and any
	      column of the jacobian is at most GTOL in
	      absolute value.
         
	   5  the maximum number of iterations has been reached
         
	   6  FTOL is too small. no further reduction in
	      the sum of squares is possible.
         
	   7  XTOL is too small. no further improvement in
	      the approximate solution x is possible.
         
	   8  GTOL is too small. fvec is orthogonal to the
	      columns of the jacobian to machine precision.

   WEIGHTS - Array of weights to be used in calculating the
             chi-squared value.  If WEIGHTS is specified then the ERR
             parameter is ignored.  The chi-squared value is computed
             as follows:

                CHISQ = TOTAL( (Y-MYFUNCT(X,P))^2 * ABS(WEIGHTS) )

             Here are common values of WEIGHTS:

                1D/ERR^2 - Normal weighting (ERR is the measurement error)
                1D/Y     - Poisson weighting (counting statistics)
                1D       - Unweighted

   XTOL - a nonnegative input variable. Termination occurs when the
          relative error between two consecutive iterates is at most
          XTOL (and STATUS is accordingly set to 2 or 3).  Therefore,
          XTOL measures the relative error desired in the approximate
          solution.  Default: 1D-10

   YFIT - the best-fit model function, as returned by MYFUNCT.


 EXAMPLE:

   ; First, generate some synthetic data
   x  = dindgen(200) * 0.1 - 10.                   ; Independent variable 
   yi = gauss1(x, [2.2D, 1.4, 3000.]) + 1000       ; "Ideal" Y variable
   y  = yi + randomn(seed, 200) * sqrt(yi)         ; Measured, w/ noise
   sy = sqrt(y)                                    ; Poisson errors

   ; Now fit a Gaussian to see how well we can recover
   expr = 'P(0) + GAUSS1(X, P(1:3))'               ; fitting function
   p0 = [800.D, 1.D, 1., 500.]                     ; Initial guess
   p = mpfitexpr(expr, x, y, sy, p0)               ; Fit the expression
   print, p

   plot, x, y                                      ; Plot data
   oplot, x, mpevalexpr(expr, x, p)                ; Plot model

   Generates a synthetic data set with a Gaussian peak, and Poisson
   statistical uncertainty.  Then a model consisting of a constant
   plus Gaussian is fit to the data.


 COMMON BLOCKS:

   COMMON MPFIT_ERROR, ERROR_CODE

     User routines may stop the fitting process at any time by
     setting an error condition.  This condition may be set in either
     the user's model computation routine (MYFUNCT), or in the
     iteration procedure (ITERPROC).

     To stop the fitting, the above common block must be declared,
     and ERROR_CODE must be set to a negative number.  After the user
     procedure or function returns, MPFIT checks the value of this
     common block variable and exits immediately if the error
     condition has been set.  By default the value of ERROR_CODE is
     zero, indicating a successful function/procedure call.


 REFERENCES:

   MINPACK-1, Jorge More', available from netlib (www.netlib.org).
   "Optimization Software Guide," Jorge More' and Stephen Wright, 
     SIAM, *Frontiers in Applied Mathematics*, Number 14.

 MODIFICATION HISTORY:
   Written, Apr-Jul 1998, CM
   Added PERROR keyword, 04 Aug 1998, CM
   Added COVAR keyword, 20 Aug 1998, CM
   Added NITER output keyword, 05 Oct 1998
      D.L Windt, Bell Labs, windt@bell-labs.com;
   Added ability to return model function in YFIT, 09 Nov 1998
   Parameter values can be tied to others, 09 Nov 1998
   Added MPEVALEXPR utility function, 09 Dec 1998
   Cosmetic documentation updates, 16 Apr 1999, CM
   More cosmetic documentation updates, 14 May 1999, CM
   Made sure to update STATUS value, 25 Sep 1999, CM
   Added WEIGHTS keyword, 25 Sep 1999, CM
   Changed from handles to common blocks, 25 Sep 1999, CM
     - commons seem much cleaner and more logical in this case.
   Alphabetized documented keywords, 02 Oct 1999, CM
   Added QUERY keyword and query checking of MPFIT, 29 Oct 1999, CM
   Check to be sure that X and Y are present, 02 Nov 1999, CM
   Documented PERROR for unweighted fits, 03 Nov 1999, CM
   Removed ITERPROC='' when quiet EQ 1, 10 Jan 2000, CM
   Changed to ERROR_CODE for error condition, 28 Jan 2000, CM
   Updated the EXAMPLE, 26 Mar 2000, CM
   Copying permission terms have been liberalized, 26 Mar 2000, CM
   Propagated improvements from MPFIT, 17 Dec 2000, CM
   Correct reference to _WTS in MPFITEXPR_EVAL, 25 May 2001, CM
      (thanks to Mark Fardal)
   Added useful FUNCTARGS behavior (as yet undocumented), 04 Jul
      2002, CM
   Documented FUNCTARGS/PRIVATE behavior, 22 Jul 2002, CM
   Added NFREE and NPEGGED keywords, 13 Sep 2002, CM
   Documented RELSTEP field of PARINFO (!!), CM, 25 Oct 2002
   Add DOF keyword, CM, 31 Jul 2003
   Add FUNCTARGS keyword to MPEVALEXPR, CM 08 Aug 2003
   Minor documentation adjustment, 03 Feb 2004, CM

  $Id: mpfitexpr.pro,v 1.2 2006/02/07 22:38:32 schlegel Exp $

(See pro/mpfit/mpfitexpr.pro)


MPFITFUN

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

 AUTHOR:
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov
   UPDATED VERSIONs can be found on my WEB PAGE: 
      http://cow.physics.wisc.edu/~craigm/idl/idl.html

 PURPOSE:
   Perform Levenberg-Marquardt least-squares fit to IDL function

 MAJOR TOPICS:
   Curve and Surface Fitting

 CALLING SEQUENCE:
   parms = MPFITFUN(MYFUNCT, X, Y, ERR, start_params, ...)

 DESCRIPTION:

  MPFITFUN fits a user-supplied model -- in the form of an IDL
  function -- to a set of user-supplied data.  MPFITFUN calls
  MPFIT, the MINPACK-1 least-squares minimizer, to do the main
  work.

  Given the data and their uncertainties, MPFITFUN finds the best set
  of model parameters which match the data (in a least-squares
  sense) and returns them in an array.
  
  The user must supply the following items:
   - An array of independent variable values ("X").
   - An array of "measured" *dependent* variable values ("Y").
   - An array of "measured" 1-sigma uncertainty values ("ERR").
   - The name of an IDL function which computes Y given X ("MYFUNCT").
   - Starting guesses for all of the parameters ("START_PARAMS").

  There are very few restrictions placed on X, Y or MYFUNCT.  Simply
  put, MYFUNCT must map the "X" values into "Y" values given the
  model parameters.  The "X" values may represent any independent
  variable (not just Cartesian X), and indeed may be multidimensional
  themselves.  For example, in the application of image fitting, X
  may be a 2xN array of image positions.

  MPFITFUN carefully avoids passing large arrays where possible to
  improve performance.

  See below for an example of usage.

 USER FUNCTION

  The user must define a function which returns the model value.  For
  applications which use finite-difference derivatives -- the default
  -- the user function should be declared in the following way:

    FUNCTION MYFUNCT, X, P
     ; The independent variable is X
     ; Parameter values are passed in "P"
     YMOD = ... computed model values at X ...
     return, YMOD
    END

  The returned array YMOD must have the same dimensions and type as
  the "measured" Y values.

  User functions may also indicate a fatal error condition
  using the ERROR_CODE common block variable, as described
  below under the MPFIT_ERROR common block definition.

  See the discussion under "ANALYTIC DERIVATIVES" and AUTODERIVATIVE
  in MPFIT.PRO if you wish to compute the derivatives for yourself.
  AUTODERIVATIVE is accepted by MPFITFUN and passed directly to
  MPFIT.  The user function must accept one additional parameter, DP,
  which contains the derivative of the user function with respect to
  each parameter at each data point, as described in MPFIT.PRO.

 CONSTRAINING PARAMETER VALUES WITH THE PARINFO KEYWORD

  The behavior of MPFIT can be modified with respect to each
  parameter to be fitted.  A parameter value can be fixed; simple
  boundary constraints can be imposed; limitations on the parameter
  changes can be imposed; properties of the automatic derivative can
  be modified; and parameters can be tied to one another.

  These properties are governed by the PARINFO structure, which is
  passed as a keyword parameter to MPFIT.

  PARINFO should be an array of structures, one for each parameter.
  Each parameter is associated with one element of the array, in
  numerical order.  The structure can have the following entries
  (none are required):
  
     .VALUE - the starting parameter value (but see the START_PARAMS
              parameter for more information).
  
     .FIXED - a boolean value, whether the parameter is to be held
              fixed or not.  Fixed parameters are not varied by
              MPFIT, but are passed on to MYFUNCT for evaluation.
  
     .LIMITED - a two-element boolean array.  If the first/second
                element is set, then the parameter is bounded on the
                lower/upper side.  A parameter can be bounded on both
                sides.  Both LIMITED and LIMITS must be given
                together.
  
     .LIMITS - a two-element float or double array.  Gives the
               parameter limits on the lower and upper sides,
               respectively.  Zero, one or two of these values can be
               set, depending on the values of LIMITED.  Both LIMITED
               and LIMITS must be given together.
  
     .PARNAME - a string, giving the name of the parameter.  The
                fitting code of MPFIT does not use this tag in any
                way.  However, the default ITERPROC will print the
                parameter name if available.
  
     .STEP - the step size to be used in calculating the numerical
             derivatives.  If set to zero, then the step size is
             computed automatically.  Ignored when AUTODERIVATIVE=0.
             This value is superceded by the RELSTEP value.

     .RELSTEP - the *relative* step size to be used in calculating
                the numerical derivatives.  This number is the
                fractional size of the step, compared to the
                parameter value.  This value supercedes the STEP
                setting.  If the parameter is zero, then a default
                step size is chosen.

     .MPSIDE - the sidedness of the finite difference when computing
               numerical derivatives.  This field can take four
               values:

                  0 - one-sided derivative computed automatically
                  1 - one-sided derivative (f(x+h) - f(x)  )/h
                 -1 - one-sided derivative (f(x)   - f(x-h))/h
                  2 - two-sided derivative (f(x+h) - f(x-h))/(2*h)

              Where H is the STEP parameter described above.  The
              "automatic" one-sided derivative method will chose a
              direction for the finite difference which does not
              violate any constraints.  The other methods do not
              perform this check.  The two-sided method is in
              principle more precise, but requires twice as many
              function evaluations.  Default: 0.

     .MPMINSTEP - the minimum change to be made in the parameter
                  value.  During the fitting process, the parameter
                  will be changed by multiples of this value.  The
                  actual step is computed as:

                     DELTA1 = MPMINSTEP*ROUND(DELTA0/MPMINSTEP)

                  where DELTA0 and DELTA1 are the estimated parameter
                  changes before and after this constraint is
                  applied.  Note that this constraint should be used
                  with care since it may cause non-converging,
                  oscillating solutions.

                  A value of 0 indicates no minimum.  Default: 0.

     .MPMAXSTEP - the maximum change to be made in the parameter
                  value.  During the fitting process, the parameter
                  will never be changed by more than this value.

                  A value of 0 indicates no maximum.  Default: 0.
  
     .TIED - a string expression which "ties" the parameter to other
             free or fixed parameters.  Any expression involving
             constants and the parameter array P are permitted.
             Example: if parameter 2 is always to be twice parameter
             1 then use the following: parinfo(2).tied = '2 * P(1)'.
             Since they are totally constrained, tied parameters are
             considered to be fixed; no errors are computed for them.
             [ NOTE: the PARNAME can't be used in expressions. ]
  
  Future modifications to the PARINFO structure, if any, will involve
  adding structure tags beginning with the two letters "MP".
  Therefore programmers are urged to avoid using tags starting with
  the same letters; otherwise they are free to include their own
  fields within the PARINFO structure, and they will be ignored.
  
  PARINFO Example:
  parinfo = replicate({value:0.D, fixed:0, limited:[0,0], $
                       limits:[0.D,0]}, 5)
  parinfo(0).fixed = 1
  parinfo(4).limited(0) = 1
  parinfo(4).limits(0)  = 50.D
  parinfo(*).value = [5.7D, 2.2, 500., 1.5, 2000.]
  
  A total of 5 parameters, with starting values of 5.7,
  2.2, 500, 1.5, and 2000 are given.  The first parameter
  is fixed at a value of 5.7, and the last parameter is
  constrained to be above 50.

 INPUTS:
   MYFUNCT - a string variable containing the name of an IDL function.
             This function computes the "model" Y values given the
             X values and model parameters, as desribed above.

   X - Array of independent variable values.

   Y - Array of "measured" dependent variable values.  Y should have
       the same data type as X.  The function MYFUNCT should map
       X->Y.

   ERR - Array of "measured" 1-sigma uncertainties.  ERR should have
         the same data type as Y.  ERR is ignored if the WEIGHTS
         keyword is specified.

   START_PARAMS - An array of starting values for each of the
                  parameters of the model.  The number of parameters
                  should be fewer than the number of measurements.
                  Also, the parameters should have the same data type
                  as the measurements (double is preferred).

                  This parameter is optional if the PARINFO keyword
                  is used (see MPFIT).  The PARINFO keyword provides
                  a mechanism to fix or constrain individual
                  parameters.  If both START_PARAMS and PARINFO are
                  passed, then the starting *value* is taken from
                  START_PARAMS, but the *constraints* are taken from
                  PARINFO.
 

 RETURNS:

   Returns the array of best-fit parameters.


 KEYWORD PARAMETERS:

   BESTNORM - the value of the summed squared residuals for the
              returned parameter values.

   COVAR - the covariance matrix for the set of parameters returned
           by MPFIT.  The matrix is NxN where N is the number of
           parameters.  The square root of the diagonal elements
           gives the formal 1-sigma statistical errors on the
           parameters IF errors were treated "properly" in MYFUNC.
           Parameter errors are also returned in PERROR.

           To compute the correlation matrix, PCOR, use this:
           IDL> PCOR = COV * 0
           IDL> FOR i = 0, n-1 DO FOR j = 0, n-1 DO $
                PCOR(i,j) = COV(i,j)/sqrt(COV(i,i)*COV(j,j))

           If NOCOVAR is set or MPFIT terminated abnormally, then
           COVAR is set to a scalar with value !VALUES.D_NAN.

   CASH - when set, the fit statistic is changed to a derivative of
          the CASH statistic.  The model function must be strictly
          positive.

   DOF - number of degrees of freedom, computed as
             DOF = N_ELEMENTS(DEVIATES) - NFREE
         Note that this doesn't account for pegged parameters (see
         NPEGGED).

   ERRMSG - a string error or warning message is returned.

   FTOL - a nonnegative input variable. Termination occurs when both
          the actual and predicted relative reductions in the sum of
          squares are at most FTOL (and STATUS is accordingly set to
          1 or 3).  Therefore, FTOL measures the relative error
          desired in the sum of squares.  Default: 1D-10

   FUNCTARGS - A structure which contains the parameters to be passed
               to the user-supplied function specified by MYFUNCT via
               the _EXTRA mechanism.  This is the way you can pass
               additional data to your user-supplied function without
               using common blocks.

               By default, no extra parameters are passed to the
               user-supplied function.

   GTOL - a nonnegative input variable. Termination occurs when the
          cosine of the angle between fvec and any column of the
          jacobian is at most GTOL in absolute value (and STATUS is
          accordingly set to 4). Therefore, GTOL measures the
          orthogonality desired between the function vector and the
          columns of the jacobian.  Default: 1D-10

   ITERARGS - The keyword arguments to be passed to ITERPROC via the
              _EXTRA mechanism.  This should be a structure, and is
              similar in operation to FUNCTARGS.
              Default: no arguments are passed.

   ITERPROC - The name of a procedure to be called upon each NPRINT
              iteration of the MPFIT routine.  It should be declared
              in the following way:

              PRO ITERPROC, MYFUNCT, p, iter, fnorm, FUNCTARGS=fcnargs, $
                PARINFO=parinfo, QUIET=quiet, ...
                ; perform custom iteration update
              END
         
              ITERPROC must either accept all three keyword
              parameters (FUNCTARGS, PARINFO and QUIET), or at least
              accept them via the _EXTRA keyword.
          
              MYFUNCT is the user-supplied function to be minimized,
              P is the current set of model parameters, ITER is the
              iteration number, and FUNCTARGS are the arguments to be
              passed to MYFUNCT.  FNORM should be the
              chi-squared value.  QUIET is set when no textual output
              should be printed.  See below for documentation of
              PARINFO.

              In implementation, ITERPROC can perform updates to the
              terminal or graphical user interface, to provide
              feedback while the fit proceeds.  If the fit is to be
              stopped for any reason, then ITERPROC should set the
              common block variable ERROR_CODE to negative value (see
              MPFIT_ERROR common block below).  In principle,
              ITERPROC should probably not modify the parameter
              values, because it may interfere with the algorithm's
              stability.  In practice it is allowed.

              Default: an internal routine is used to print the
                       parameter values.

   MAXITER - The maximum number of iterations to perform.  If the
             number is exceeded, then the STATUS value is set to 5
             and MPFIT returns.
             Default: 200 iterations

   NFEV - the number of MYFUNCT function evaluations performed.

   NFREE - the number of free parameters in the fit.  This includes
           parameters which are not FIXED and not TIED, but it does
           include parameters which are pegged at LIMITS.

   NITER - the number of iterations completed.

   NOCOVAR - set this keyword to prevent the calculation of the
             covariance matrix before returning (see COVAR)

   NPEGGED - the number of free parameters which are pegged at a
             LIMIT.

   NPRINT - The frequency with which ITERPROC is called.  A value of
            1 indicates that ITERPROC is called with every iteration,
            while 2 indicates every other iteration, etc.  Note that
            several Levenberg-Marquardt attempts can be made in a
            single iteration.
            Default value: 1

   PARINFO - Provides a mechanism for more sophisticated constraints
             to be placed on parameter values.  When PARINFO is not
             passed, then it is assumed that all parameters are free
             and unconstrained.  Values in PARINFO are never 
             modified during a call to MPFIT.

             See description above for the structure of PARINFO.

             Default value:  all parameters are free and unconstrained.

   PERROR - The formal 1-sigma errors in each parameter, computed
            from the covariance matrix.  If a parameter is held
            fixed, or if it touches a boundary, then the error is
            reported as zero.

            If the fit is unweighted (i.e. no errors were given, or
            the weights were uniformly set to unity), then PERROR
            will probably not represent the true parameter
            uncertainties.  

            *If* you can assume that the true reduced chi-squared
            value is unity -- meaning that the fit is implicitly
            assumed to be of good quality -- then the estimated
            parameter uncertainties can be computed by scaling PERROR
            by the measured chi-squared value.

              DOF     = N_ELEMENTS(X) - N_ELEMENTS(PARMS) ; deg of freedom
              PCERROR = PERROR * SQRT(BESTNORM / DOF)   ; scaled uncertainties

   QUIET - set this keyword when no textual output should be printed
           by MPFIT

   STATUS - an integer status code is returned.  All values other
            than zero can represent success.  It can have one of the
            following values:

	   0  improper input parameters.
         
	   1  both actual and predicted relative reductions
	      in the sum of squares are at most FTOL.
         
	   2  relative error between two consecutive iterates
	      is at most XTOL
         
	   3  conditions for STATUS = 1 and STATUS = 2 both hold.
         
	   4  the cosine of the angle between fvec and any
	      column of the jacobian is at most GTOL in
	      absolute value.
         
	   5  the maximum number of iterations has been reached
         
	   6  FTOL is too small. no further reduction in
	      the sum of squares is possible.
         
	   7  XTOL is too small. no further improvement in
	      the approximate solution x is possible.
         
	   8  GTOL is too small. fvec is orthogonal to the
	      columns of the jacobian to machine precision.

   WEIGHTS - Array of weights to be used in calculating the
             chi-squared value.  If WEIGHTS is specified then the ERR
             parameter is ignored.  The chi-squared value is computed
             as follows:

                CHISQ = TOTAL( (Y-MYFUNCT(X,P))^2 * ABS(WEIGHTS) )

             Here are common values of WEIGHTS:

                1D/ERR^2 - Normal weighting (ERR is the measurement error)
                1D/Y     - Poisson weighting (counting statistics)
                1D       - Unweighted

   XTOL - a nonnegative input variable. Termination occurs when the
          relative error between two consecutive iterates is at most
          XTOL (and STATUS is accordingly set to 2 or 3).  Therefore,
          XTOL measures the relative error desired in the approximate
          solution.  Default: 1D-10

   YFIT - the best-fit model function, as returned by MYFUNCT.

   
 EXAMPLE:

   ; First, generate some synthetic data
   npts = 200
   x  = dindgen(npts) * 0.1 - 10.                  ; Independent variable 
   yi = gauss1(x, [2.2D, 1.4, 3000.])              ; "Ideal" Y variable
   y  = yi + randomn(seed, npts) * sqrt(1000. + yi); Measured, w/ noise
   sy = sqrt(1000.D + y)                           ; Poisson errors

   ; Now fit a Gaussian to see how well we can recover
   p0 = [1.D, 1., 1000.]                   ; Initial guess (cent, width, area)
   p = mpfitfun('GAUSS1', x, y, sy, p0)    ; Fit a function
   print, p

   Generates a synthetic data set with a Gaussian peak, and Poisson
   statistical uncertainty.  Then the same function is fitted to the
   data (with different starting parameters) to see how close we can
   get.


 COMMON BLOCKS:

   COMMON MPFIT_ERROR, ERROR_CODE

     User routines may stop the fitting process at any time by
     setting an error condition.  This condition may be set in either
     the user's model computation routine (MYFUNCT), or in the
     iteration procedure (ITERPROC).

     To stop the fitting, the above common block must be declared,
     and ERROR_CODE must be set to a negative number.  After the user
     procedure or function returns, MPFIT checks the value of this
     common block variable and exits immediately if the error
     condition has been set.  By default the value of ERROR_CODE is
     zero, indicating a successful function/procedure call.

 REFERENCES:

   MINPACK-1, Jorge More', available from netlib (www.netlib.org).
   "Optimization Software Guide," Jorge More' and Stephen Wright, 
     SIAM, *Frontiers in Applied Mathematics*, Number 14.

 MODIFICATION HISTORY:
   Written, Apr-Jul 1998, CM
   Added PERROR keyword, 04 Aug 1998, CM
   Added COVAR keyword, 20 Aug 1998, CM
   Added ITER output keyword, 05 Oct 1998
      D.L Windt, Bell Labs, windt@bell-labs.com;
   Added ability to return model function in YFIT, 09 Nov 1998
   Analytical derivatives allowed via AUTODERIVATIVE keyword, 09 Nov 1998
   Parameter values can be tied to others, 09 Nov 1998
   Cosmetic documentation updates, 16 Apr 1999, CM
   More cosmetic documentation updates, 14 May 1999, CM
   Made sure to update STATUS, 25 Sep 1999, CM
   Added WEIGHTS keyword, 25 Sep 1999, CM
   Changed from handles to common blocks, 25 Sep 1999, CM
     - commons seem much cleaner and more logical in this case.
   Alphabetized documented keywords, 02 Oct 1999, CM
   Added QUERY keyword and query checking of MPFIT, 29 Oct 1999, CM
   Corrected EXAMPLE (offset of 1000), 30 Oct 1999, CM
   Check to be sure that X and Y are present, 02 Nov 1999, CM
   Documented PERROR for unweighted fits, 03 Nov 1999, CM
   Changed to ERROR_CODE for error condition, 28 Jan 2000, CM
   Corrected errors in EXAMPLE, 26 Mar 2000, CM
   Copying permission terms have been liberalized, 26 Mar 2000, CM
   Propagated improvements from MPFIT, 17 Dec 2000, CM
   Added CASH statistic, 10 Jan 2001
   Added NFREE and NPEGGED keywords, 11 Sep 2002, CM
   Documented RELSTEP field of PARINFO (!!), CM, 25 Oct 2002
   Add DOF keyword to return degrees of freedom, CM, 23 June 2003

  $Id: mpfitfun.pro,v 1.2 2006/02/07 22:38:32 schlegel Exp $

(See pro/mpfit/mpfitfun.pro)


MPFITPEAK

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

 AUTHOR:
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov
   UPDATED VERSIONs can be found on my WEB PAGE: 
      http://cow.physics.wisc.edu/~craigm/idl/idl.html

 PURPOSE:
   Fit a gaussian, lorentzian or Moffat model to data

 MAJOR TOPICS:
   Curve and Surface Fitting

 CALLING SEQUENCE:
   yfit = MPFITPEAK(X, Y, A, NTERMS=nterms, ...)

 DESCRIPTION:

   MPFITPEAK fits a gaussian, lorentzian or Moffat model using the
   non-linear least squares fitter MPFIT.  MPFITPEAK is meant to be a
   drop-in replacement for IDL's GAUSSFIT function (and requires
   MPFIT and MPFITFUN).

   The choice of the fitting function is determined by the keywords
   GAUSSIAN, LORENTZIAN and MOFFAT.  By default the gaussian model
   function is used.  [ The Moffat function is a modified Lorentzian
   with variable power law index. (Moffat, A. F. J. 1969, Astronomy &
   Astrophysics, v. 3, p. 455-461) ]

   The functional form of the baseline is determined by NTERMS and
   the function to be fitted.  NTERMS represents the total number of
   parameters, A, to be fitted.  The functional forms and the
   meanings of the parameters are described in this table:

                 GAUSSIAN#          Lorentzian#         Moffat#

   Model     A(0)*exp(-0.5*u^2)   A(0)/(u^2 + 1)   A(0)/(u^2 + 1)^A(3)

   A(0)         Peak Value          Peak Value        Peak Value
   A(1)        Peak Centroid       Peak Centroid     Peak Centroid
   A(2)       Gaussian Sigma           HWHM%             HWHM%
   A(3)         + A(3)    *          + A(3)   *      Moffat Index
   A(4)         + A(4)*x  *          + A(4)*x *         + A(4)   *
   A(5)                                                 + A(5)*x *

   Notes: # u = (x - A(1))/A(2)
          % Half-width at half maximum
          * Optional depending on NTERMS

   By default the initial starting values for the parameters A are
   estimated from the data.  However, explicit starting values can be
   supplied using the ESTIMATES keyword.  Also, error or weighting
   values can optionally be provided; otherwise the fit is
   unweighted.

   MPFITPEAK fits the peak value of the curve.  The area under a
   gaussian peak is A(0)*A(2)*SQRT(2*!DPI); the area under a
   lorentzian peak is A(0)*A(2)*!DPI.

 RESTRICTIONS:

   If no starting parameter ESTIMATES are provided, then MPFITPEAK
   attempts to estimate them from the data.  This is not a perfect
   science; however, the author believes that the technique
   implemented here is more robust than the one used in IDL's
   GAUSSFIT.  The author has tested cases of strong peaks, noisy
   peaks and broad peaks, all with success.

   Users should be aware that if the baseline term contains a strong
   linear component then the automatic estimation may fail.  For
   automatic estimation to work the peak amplitude should dominate
   over the the maximum baseline.

 INPUTS:
   X - Array of independent variable values, whose values should
       monotonically increase.

   Y - Array of "measured" dependent variable values.  Y should have
       the same data type and dimension as X.


 OUTPUTS:
   A - Upon return, an array of NTERMS best fit parameter values.
       See the table above for the meanings of each parameter
       element.


 RETURNS:

   Returns the best fitting model function.

 KEYWORDS:

   ** NOTE ** Additional keywords such as PARINFO, BESTNORM, and
              STATUS are accepted by MPFITPEAK but not documented
              here.  Please see the documentation for MPFIT for the
              description of these advanced options.

   CHISQ - the value of the summed squared residuals for the
           returned parameter values.

   DOF - number of degrees of freedom, computed as
             DOF = N_ELEMENTS(DEVIATES) - NFREE
         Note that this doesn't account for pegged parameters (see
         NPEGGED).

   ERROR - upon input, the measured 1-sigma uncertainties in the "Y"
           values.  If no ERROR or WEIGHTS are given, then the fit is
           unweighted.

   ESTIMATES - Array of starting values for each parameter of the
               model.  The number of parameters should at least be
               three (four for Moffat), and if less than NTERMS, will
               be extended with zeroes.
               Default: parameter values are estimated from data.

   GAUSSIAN - if set, fit a gaussian model function.  The Default.
   LORENTZIAN - if set, fit a lorentzian model function.
   MOFFAT - if set, fit a Moffat model function.

   MEASURE_ERRORS - synonym for ERRORS, for consistency with built-in
                    IDL fitting routines.

   NEGATIVE / POSITIVE - if set, and ESTIMATES is not provided, then
                         MPFITPEAK will assume that a
                         negative/positive peak is present.
                         Default: determined automatically

   NFREE - the number of free parameters in the fit.  This includes
           parameters which are not FIXED and not TIED, but it does
           include parameters which are pegged at LIMITS.

   NTERMS - An integer describing the number of fitting terms.
            NTERMS must have a minimum value, but can optionally be
            larger depending on the desired baseline.  

            For gaussian and lorentzian models, NTERMS must be three
            (zero baseline), four (constant baseline) or five (linear
            baseline).  Default: 4

            For the Moffat model, NTERMS must be four (zero
            baseline), five (constant baseline), or six (linear
            baseline).  Default: 5

   PERROR - upon return, the 1-sigma uncertainties of the parameter
            values A.  These values are only meaningful if the ERRORS
            or WEIGHTS keywords are specified properly.

            If the fit is unweighted (i.e. no errors were given, or
            the weights were uniformly set to unity), then PERROR
            will probably not represent the true parameter
            uncertainties.  

            *If* you can assume that the true reduced chi-squared
            value is unity -- meaning that the fit is implicitly
            assumed to be of good quality -- then the estimated
            parameter uncertainties can be computed by scaling PERROR
            by the measured chi-squared value.

              DOF     = N_ELEMENTS(X) - N_ELEMENTS(PARMS) ; deg of freedom
              PCERROR = PERROR * SQRT(BESTNORM / DOF)   ; scaled uncertainties

   QUIET - if set then diagnostic fitting messages are suppressed.
           Default: QUIET=1 (i.e., no diagnostics)

   SIGMA - synonym for PERROR (1-sigma parameter uncertainties), for
           compatibility with GAUSSFIT.  Do not confuse this with the
           Gaussian "sigma" width parameter.

   WEIGHTS - Array of weights to be used in calculating the
             chi-squared value.  If WEIGHTS is specified then the ERROR
             keyword is ignored.  The chi-squared value is computed
             as follows:

                CHISQ = TOTAL( (Y-MYFUNCT(X,P))^2 * ABS(WEIGHTS) )

             Here are common values of WEIGHTS:

                1D/ERR^2 - Normal weighting (ERR is the measurement error)
                1D/Y     - Poisson weighting (counting statistics)
                1D       - Unweighted

             The ERROR keyword takes precedence over any WEIGHTS
             keyword values.  If no ERROR or WEIGHTS are given, then
             the fit is unweighted.

   YERROR - upon return, the root-mean-square variance of the
            residuals.


 EXAMPLE:

   ; First, generate some synthetic data
   npts = 200
   x  = dindgen(npts) * 0.1 - 10.                  ; Independent variable 
   yi = gauss1(x, [2.2D, 1.4, 3000.]) + 1000       ; "Ideal" Y variable
   y  = yi + randomn(seed, npts) * sqrt(1000. + yi); Measured, w/ noise
   sy = sqrt(1000.D + y)                           ; Poisson errors

   ; Now fit a Gaussian to see how well we can recover the original
   yfit = mpfitpeak(x, y, a, error=sy)
   print, p

   Generates a synthetic data set with a Gaussian peak, and Poisson
   statistical uncertainty.  Then the same function is fitted to the
   data.

 REFERENCES:

   MINPACK-1, Jorge More', available from netlib (www.netlib.org).
   "Optimization Software Guide," Jorge More' and Stephen Wright, 
     SIAM, *Frontiers in Applied Mathematics*, Number 14.

 MODIFICATION HISTORY:

   New algorithm for estimating starting values, CM, 31 Oct 1999
   Documented, 02 Nov 1999
   Small documentation fixes, 02 Nov 1999
   Slight correction to calculation of dx, CM, 02 Nov 1999
   Documented PERROR for unweighted fits, 03 Nov 1999, CM
   Copying permission terms have been liberalized, 26 Mar 2000, CM
   Change requirements on # elements in X and Y, 20 Jul 2000, CM
      (thanks to David Schlegel <schlegel@astro.princeton.edu>)
   Added documentation on area under curve, 29 Aug 2000, CM
   Added POSITIVE and NEGATIVE keywords, 17 Nov 2000, CM
   Added reference to Moffat paper, 10 Jan 2001, CM
   Added usage message, 26 Jul 2001, CM
   Documentation clarification, 05 Sep 2001, CM
   Make more consistent with comparable IDL routines, 30 Jun 2003, CM
   Assumption of sorted data was removed, CM, 06 Sep 2003, CM
   Add some defensive code against divide by zero, 30 Nov 2005, CM

  $Id: mpfitpeak.pro,v 1.2 2006/02/07 22:38:32 schlegel Exp $

(See pro/mpfit/mpfitpeak.pro)


MPFTEST

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

 AUTHOR:
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov
   UPDATED VERSIONs can be found on my WEB PAGE: 
      http://cow.physics.wisc.edu/~craigm/idl/idl.html

 PURPOSE:
   Compute the probability of a given F value

 MAJOR TOPICS:
   Curve and Surface Fitting, Statistics

 CALLING SEQUENCE:
   PROB = MPFTEST(F, DOF1, DOF2, [/SIGMA, /CLEVEL, /SLEVEL ])

 DESCRIPTION:

  The function MPFTEST() computes the probability for a value drawn
  from the F-distribution to equal or exceed the given value of F.
  This can be used for confidence testing of a measured value obeying
  the F-distribution (i.e., for testing the ratio of variances, or
  equivalently for the addition of parameters to a fitted model).

    P_F(X > F; DOF1, DOF2) = PROB

  In specifying the returned probability level the user has three
  choices:

    * return the confidence level when the /CLEVEL keyword is passed;
      OR

    * return the significance level (i.e., 1 - confidence level) when
      the /SLEVEL keyword is passed (default); OR

    * return the "sigma" of the probability (i.e., compute the
      probability based on the normal distribution) when the /SIGMA
      keyword is passed.

  Note that /SLEVEL, /CLEVEL and /SIGMA are mutually exclusive.

  For the ratio of variance test, the two variances, VAR1 and VAR2,
  should be distributed according to the chi-squared distribution
  with degrees of freedom DOF1 and DOF2 respectively.  The F-value is
  computed as:

     F = (VAR1/DOF1) / (VAR2/DOF2)

  and then the probability is computed as:

     PROB = MPFTEST(F, DOF1, DOF2, ... )


  For the test of additional parameters in least squares fitting, the
  user should perform two separate fits, and have two chi-squared
  values.  One fit should be the "original" fit with no additional
  parameters, and one fit should be the "new" fit with M additional
  parameters.

    CHI1 - chi-squared value for original fit

    DOF1 - number of degrees of freedom of CHI1 (number of data
           points minus number of original parameters)

    CHI2 - chi-squared value for new fit

    DOF2 - number of degrees of freedom of CHI2

  Note that according to this formalism, the number of degrees of
  freedom in the "new" fit, DOF2, should be less than the number of
  degrees of freedom in the "original" fit, DOF1 (DOF2 < DOF1); and
  also CHI2 < CHI1.

  With the above definition, the F value is computed as:

    F = ( (CHI1-CHI2)/(DOF1-DOF2) )   /  (CHI2/DOF2)

  where DOF1-DOF2 is equal to M, and then the F-test probability is
  computed as:

     PROB = MPFTEST(F, DOF1-DOF2, DOF2, ... )

  Note that this formalism assumes that the addition of the M
  parameters is a small peturbation to the overall fit.  If the
  additional parameters dramatically changes the character of the
  model, then the first "ratio of variance" test is more appropriate,
  where F = (CHI1/DOF1) / (CHI2/DOF2).

 INPUTS:

   F - ratio of variances as defined above.

   DOF1 - number of degrees of freedom in first variance component.

   DOF2 - number of degrees of freedom in second variance component.


 RETURNS:

  Returns a scalar or vector of probabilities, as described above,
  and according to the /SLEVEL, /CLEVEL and /SIGMA keywords.

 KEYWORD PARAMETERS:

   SLEVEL - if set, then PROB describes the significance level
            (default).

   CLEVEL - if set, then PROB describes the confidence level.

   SIGMA - if set, then PROB is the number of "sigma" away from the
           mean in the normal distribution.

 EXAMPLE:

   chi1 = 62.3D & dof1 = 42d
   chi2 = 54.6D & dof2 = 40d

   f = ((chi1-chi2)/(dof1-dof2)) / (chi2/dof2)
   print, mpftest(f, dof1-dof2, dof2)

   This is a test for addition of parameters.  The "original"
   chi-squared value was 62.3 with 42 degrees of freedom, and the
   "new" chi-squared value was 54.6 with 40 degrees of freedom.
   These values reflect the addition of 2 parameters and the
   reduction of the chi-squared value by 7.7.  The significance of
   this set of circumstances is 0.071464757.

 REFERENCES:

   Algorithms taken from CEPHES special function library, by Stephen
   Moshier. (http://www.netlib.org/cephes/)

 MODIFICATION HISTORY:
   Completed, 1999, CM
   Documented, 16 Nov 2001, CM
   Reduced obtrusiveness of common block and math error handling, 18
     Nov 2001, CM
   Added documentation, 30 Dec 2001, CM
   Documentation corrections (thanks W. Landsman), 17 Jan 2002, CM
   Example docs were corrected (Thanks M. Perez-Torres), 17 Feb 2002,
     CM
   Example corrected again (sigh...), 13 Feb 2003, CM

  $Id: mpftest.pro,v 1.1 2006/02/07 22:38:32 schlegel Exp $

(See pro/mpfit/mpftest.pro)


MPNORMLIM

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

 AUTHOR:
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov
   UPDATED VERSIONs can be found on my WEB PAGE: 
      http://cow.physics.wisc.edu/~craigm/idl/idl.html

 PURPOSE:
   Compute confidence limits for normally distributed variable

 MAJOR TOPICS:
   Curve and Surface Fitting, Statistics

 CALLING SEQUENCE:
   Z = MPNORMLIM(PROB, [/CLEVEL, /SLEVEL ])

 DESCRIPTION:

  The function MPNORMLIM() computes confidence limits of a normally
  distributed variable (with zero mean and unit variance), for a
  desired probability level.  The returned values, Z, are the
  limiting values: a the magnitude of a normally distributed value
  is greater than Z by chance with a probability PROB:

    P_NORM(ABS(X) > Z) = PROB

  In specifying the probability level the user has two choices:

    * give the confidence level (default);

    * give the significance level (i.e., 1 - confidence level) and
      pass the /SLEVEL keyword; OR

  Note that /SLEVEL and /CLEVEL are mutually exclusive.

 INPUTS:

   PROB - scalar or vector number, giving the desired probability
          level as described above.

 RETURNS:

  Returns a scalar or vector of normal confidence limits.

 KEYWORD PARAMETERS:

   SLEVEL - if set, then PROB describes the significance level.

   CLEVEL - if set, then PROB describes the confidence level
            (default).

 EXAMPLE:

   print, mpnormlim(0.99d, /clevel)

   Print the 99% confidence limit for a normally distributed
   variable.  In this case it is about 2.58 sigma.

 REFERENCES:

   Algorithms taken from CEPHES special function library, by Stephen
   Moshier. (http://www.netlib.org/cephes/)

 MODIFICATION HISTORY:
   Completed, 1999, CM
   Documented, 16 Nov 2001, CM
   Reduced obtrusiveness of common block and math error handling, 18
     Nov 2001, CM

  $Id: mpnormlim.pro,v 1.1 2006/02/07 22:38:32 schlegel Exp $

(See pro/mpfit/mpnormlim.pro)


MPNORMTEST

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

 AUTHOR:
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov
   UPDATED VERSIONs can be found on my WEB PAGE: 
      http://cow.physics.wisc.edu/~craigm/idl/idl.html

 PURPOSE:
   Compute the probability of a given normally distributed Z value

 MAJOR TOPICS:
   Curve and Surface Fitting, Statistics

 CALLING SEQUENCE:
   PROB = MPNORMTEST(Z, [/CLEVEL, /SLEVEL ])

 DESCRIPTION:

  The function MPNORMTEST() computes the probability for the
  magnitude of a value drawn from the normal distribution to equal or
  exceed the given value Z.  This can be used for confidence testing
  of a measured value obeying the normal distribution.

    P_NORM(ABS(X) > Z) = PROB

  In specifying the returned probability level the user has two
  choices:

    * return the confidence level when the /CLEVEL keyword is passed;
      OR

    * return the significance level (i.e., 1 - confidence level) when
      the /SLEVEL keyword is passed (default).

  Note that /SLEVEL and /CLEVEL are mutually exclusive.

 INPUTS:

   Z - the value to best tested.  Z should be drawn from a normal
       distribution with zero mean and unit variance.  If a given
       quantity Y has mean MU and standard deviation STD, then Z can
       be computed as Z = (Y-MU)/STD.

 RETURNS:

  Returns a scalar or vector of probabilities, as described above,
  and according to the /SLEVEL and /CLEVEL keywords.

 KEYWORD PARAMETERS:

   SLEVEL - if set, then PROB describes the significance level
            (default).

   CLEVEL - if set, then PROB describes the confidence level.

 EXAMPLES:

   print, mpnormtest(5d, /slevel)

   Print the probability for the magnitude of a randomly distributed
   variable with zero mean and unit variance to exceed 5, as a
   significance level.

 REFERENCES:

   Algorithms taken from CEPHES special function library, by Stephen
   Moshier. (http://www.netlib.org/cephes/)

 MODIFICATION HISTORY:
   Completed, 1999, CM
   Documented, 16 Nov 2001, CM
   Reduced obtrusiveness of common block and math error handling, 18
     Nov 2001, CM
   Corrected error in handling of CLEVEL keyword, 05 Sep 2003

  $Id: mpnormtest.pro,v 1.1 2006/02/07 22:38:32 schlegel Exp $

(See pro/mpfit/mpnormtest.pro)


MQLADVANCE

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

 PURPOSE:
   Generate MODIFIED associated Legendre polynomials one l at a time

 CALLING SEQUENCE:
   mqladvance, x, m, Mql_1, Mql, lmax=lmax

 INPUTS:
   x       - argument of Plm; in some cases x=cos(theta)
   m       - m (scalar, double precision)
   Mql_1   - Plm array, (Nx, lmax) of P_lm(x,l) for given m-1
   
 KEYWORDS:
   lmax    - set to lmax on first call; default determined from Mql_1

 OUTPUTS:
   Mql     - Plm array, (Nx, lmax) of P_lm(x,l) for given m

 RESTRICTIONS:
   Do not exceed m=lmax!

 EXAMPLES:
   see healpix2alm.pro

 COMMENTS:
   Based on prescription in Numerical Recipes. 

   Must set either lmax (first time) or mql_1 (afterwards)

   NOTE:  The Plms are the associated Legendre polynomials times 
      sqrt((l-m)!/(l+m)!) for convenience in generating Ylms. 

   First written years ago at Berkeley
   Appears to be good to roughly machine roundoff error

   This code is the same recursion as plmadvance, but runs
     faster.  plmadvance is deprecated. 

 REVISION HISTORY:
   2003-Feb-19  Written by Douglas Finkbeiner, Princeton
   2003-Nov-13  Comments fixed up - DPF
   2004-Aug-16  trap floating underflow - DPF

(See pro/healpix/mqladvance.pro)


MULTI_PSF_FIT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   multi_psf_fit
 PURPOSE:
   given an image and a psf, fit a multiple psf model to the image
 CALLING SEQUENCE:
   multi_psf_fit, image, invvar, psf [, x=, y=, flux=, npsf= ]
 INPUTS:
   image - [N,M] image to fit
   invvar - [N,M] inverse variance image
   psf - [P,P] psf image (assumed to be centered at P/2)
 OPTIONAL INPUTS:
   npsf - number of psfs to fit (default to 2)
 OPTIONAL KEYWORDS:
   /silent - call mpfit silently
 OUTPUTS:
   x - [npsf] x centers of best fit
   y - [npsf] y centers of best fit
   flux - [npsf] fluxes of best fit
 COMMENTS:
   Uses 'find' to get starting positions and then calls 'mpfit'. 
 BUGS:
   Only well-tested for double-psf case.  
 REVISION HISTORY:
   31-Mar-2002  Written by Mike Blanton, NYU

(See pro/image/multi_psf_fit.pro)


MUNU_TO_RADEC

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

 PURPOSE:
   Convert from SDSS great circle coordinates to equatorial coordinates.

 CALLING SEQUENCE:
   munu_to_radec, mu, nu, [ ra, dec, stripe=, node=, incl=, phi= ]

 INPUTS:
   mu         - Mu coordinate, scalar or array (degrees)
   nu         - Nu coordinate, scalar or array (degrees)

 OPTIONAL INPUTS:
   stripe     - Stripe number for SDSS coordinate system.  If specified,
                the NODE,INCL are ignored; scalar or array with same
                dimensions as MU.
   node       - Node of great circle on the J2000 celestial equator (degrees),
                scalar or array with same dimensions as MU.
   incl       - Inclination of great circle relative to the J2000
                celestial equator (degrees); scalar or array with same
                dimensions as MU.

 OUTPUTS:

 OPTIONAL OUTPUTS:
   ra         - Right ascension (J2000 degrees)
   dec        - Declination (J2000 degrees)
   phi        - Counter-clockwise position angle w.r.t. north for an arc
                in the +nu direction.

 COMMENTS:
   Either STRIPE or NODE,INCL must be specified.

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:
   cirrange
   stripe_to_incl()

 REVISION HISTORY:
   20-Feb-2002  Written by M. Blanton, NYU
   03-Oct-2002  Modified by David Schlegel, Princeton.

(See pro/coord/munu_to_radec.pro)


MWRFITS_CHUNKS

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

 PURPOSE:
   Write a FITS binary table in chunks.

 CALLING SEQUENCE:
   mwrfits_chunks, input, filename, [ header, chunksize=, /append, $
    /silent, _EXTRA=KeywordsForMwrfits ]

 INPUTS:
   input     - Structure to be written.

 OPTIONAL INPUTS:
   chunksize - Number of rows to write in each sub-write.
   append    - If set, then append to an existing HDU.  In this case,
               it is up to the user to be certain that the INPUT
               structure is identical to that in the existing file.
               Any string elements in INPUT must be of equal length or shorter
               than the existing strings in the file.
   silent    - If set, then suppress informational messages.

 OUTPUTS:

 OPTIONAL OUTPUTS:

 COMMENTS:
   This procedure can be used instead of MWRFITS to write a large
   FITS binary table without doubling the memory usage.

   If using the /APPEND option, any string elements will be trimmed to
   the length allowed by the existing data in the output file.
   But at least it won't crash!

 BUGS:

 PROCEDURES CALLED:
   fxpar()
   fxposit()
   host_to_ieee
   ieee_to_host
   mwrfits

 INTERNAL SUPPORT PROCEDURES:
   mwrbin_append

 REVISION HISTORY:
   05-Jun-2002  Written by David Schlegel, Princeton, based upon
                e-mail from Tom McGlynn.

(See pro/fits/mwrfits_chunks.pro)


NEAR_LIST

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

 PURPOSE:
   return index list of positions near a given central position

 CALLING SEQUENCE:
   ind=near_list(racen, deccen, ra, dec, rad, count=count)

 INPUTS:
   racen, deccen - (RA,dec) of central position [deg]
   ra, dec       - list of coords to test       [deg]
   radius        - radius to search within      [deg]
   
 OPTIONAL OUTPUTS:
   count         - number of elements returned

 COMMENTS:
   Assumes same equinox for input and output coords. 
   
 REVISION HISTORY:
   2001-May-25  Written by Douglas Finkbeiner, Princeton

(See pro/coord/near_list.pro)


NMF_SPARSE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   nmf_sparse
 PURPOSE:
   non-negative PCA routine, sparse version
 CALLING SEQUENCE:
   nmf_sparse, data, data_ivar, ncomp, mmatrix, tol, templates=,
   coeffs=
 INPUTS:
   data - sparse matrix struct (see below) [Nd, Nk] of data
   data_ivar - sparse matrix struct (see below) [Nd, Nk] of inverse var
   ncomp - number of basis vectors sought
   mmatrix - [Nd, Nf] transformation from desired basis to observed coords
             (observed coords are in Nd dimensions, desired basis is
             in Nf dimensions)
   tol - tolerance of fit
 INPUT/OUTPUTS:
   templates - [nf, ncomp] initial guess at templates
   coeffs - [ncomp, nk] initial guess at coefficients
 COMMENTS:
   Nk are the number of data points
   Nd are the number of types of measurements
   Nf are the number of model components
   
   The sparse matrix structure referred to above is:
       .VAL[NVAL]      - actual values in matrix
       .X[NVAL]        - columns for each value in matrix
       .NX             - number of columns
       .NY             - number of rows
       .ROWSTART[NY]   - starting position of each row in VAL, X
       .NXROW[NY]      - number of columns in each now 
 REVISION HISTORY:
   2005-Feb-5  Written by Mike Blanton, NYU
               Adapted from Matlab code of Sam Roweis

(See pro/math/nmf_sparse.pro)


NNLS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   nnls
 PURPOSE:
   non-negative least-square fitting routine
 COMMENTS:
   See documentation in $IDLUTILS_DIR/src/math/nnls.f.

(See pro/math/nnls.pro)


NONNEG_MULT_UPDATE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	 nonneg_mult_update
 PURPOSE: (one line)
	 Apply an SSL multiplicative update to iterate nonnegative quadratic problem 
 DESCRIPTION:
  Using the method of Sha, Saul, & Lee (2002), "Multiplicative
  updates for nonnegative quadratic programming in support vector
  machines" (UPenn Tech Report MS-CIS-02-19), apply a multiplicative
  update to an attempted solution to a nonnegative quadratic problem
  (QP with box constraints):

     F(v) = (1/2) v^T.A.v + b^T.v for v_i >= 0 for all i.

  It requires the user to supply a function avfunc(vec,sign) which returns
  A+.v if sign>0. and A-.v if sign<0, where:
  
     A+_ij = A_ij for A_ij>0.
             0.   otherwise

     A-_ij = |A_ij|  for A_ij<0.
             0.      otherwise
 
 CATEGORY:
       Numerical
 CALLING SEQUENCE:
	 new = nonneg_mult_update(old,avfunc,b)
 INPUTS:
	 old - start vector
  avfunc - function which returns A+.v or A-.v, depending
  b - vector
 OPTIONAL INPUT PARAMETERS:
 KEYWORD PARAMETERS:
 OUTPUTS:
  factor - return the factor used in this vector
 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
  Untested.
 PROCEDURE:
 MODIFICATION HISTORY:
	  Written 2003-01-02 MRB (NYU) at suggestion of Sam Roweis

(See pro/math/nonneg_mult_update.pro)


NONNEG_MULT_UPDATE_SOLVE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	 nonneg_mult_update_solve
 PURPOSE: (one line)
	 Use nonneg_mult_update to iterate to convergence
 DESCRIPTION:
  From some starting point, iterates to convergence a
  box-constrained QP problem: 

     F(v) = (1/2) v^T.A.v + b^T.v for v_i >= 0 for all i.

  Uses the method of Sha, Saul, & Lee (2002), "Multiplicative
  updates for nonnegative quadratic programming in support vector
  machines" (UPenn Tech Report MS-CIS-02-19).

  It requires the user to supply a function avfunc(vec,sign) which returns
  A+.v if sign>0. and A-.v if sign<0, where:
  
     A+_ij = A_ij for A_ij>0.
             0.   otherwise

     A-_ij = |A_ij|  for A_ij<0.
             0.      otherwise
 
  Alternatively, if /matrix is set, nonneg_mult_update_solve will
  interpret the input avfunc as a matrix and construct the
  appropriate functions. 
 CATEGORY:
       Numerical
 CALLING SEQUENCE:
	 solution = nonneg_mult_update_solve(start,avfunc,b)
 INPUTS:
	 start - start vector
  avfunc - function which returns A+.v or A-.v, depending
  b - vector
 OPTIONAL INPUT PARAMETERS:
 KEYWORD PARAMETERS:
  /matrix - indicates that avfunc is actually just the matrix A,
            and the default A+/-.v function should be used
 OUTPUTS:
	 Return value is the shifted array.
 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
  Tested only in simple cases.
 PROCEDURE:
 MODIFICATION HISTORY:
	  Written 2003-01-02 MRB (NYU) at suggestion of Sam Roweis

(See pro/math/nonneg_mult_update_solve.pro)


NW_AD_GRID

[Previous Routine] [Next Routine] [List of Routines]
NAME:
  nw_ad_grid
PURPOSE:
  Creates AD coordinate grid
CALLING SEQUENCE:
  nw_ad_grid,rain,decin,hdr,[dra=,ddec=,name=,linethick=,color=,/nolabels]
INPUTS:
  hdr         - header of the FITS image to be overlayed
OPTIONAL INPUTS:
  dra,ddec    - spacing of grid lines
  linethick   - thickness of line in unrebinned pixels -- assuming
                the PS file has xsize=7.5in!
  color       - dur
OPTIONAL KEYWORDS:
  nolabels    - don't label grid lines
  gsss        - use gsss not usual WCS
OPTIONAL OUTPUTS:
OUTPUTS:
  [adds to currently open plot]
DEPENDENCIES:
BUGS:
  - Requires PS file to have xsize=7.5in!  Can this be read from a
    "bang" variable?
REVISION HISTORY:
  7/8/04 written - wherry

(See pro/rgbcolor/nw_ad_grid.pro)


NW_ARCSINH

[Previous Routine] [Next Routine] [List of Routines]
NAME:
  nw_arcsinh
PURPOSE:
  scales the fits image by a degree of nonlinearity specified by user
INPUTS:
  colors      - (NXxNYx3) array that contains the R/G/B images
OPTIONAL INPUTS:
  nonlinearity- 'b'
              - b=0 for linear fit, b=Inf for logarithmic
              - default is 3
KEYWORDS:

OUTPUTS:
  The image
COMMENTS:
  The input image must be background-subtracted (ie, have zero background).
BUGS:
  
REVISION HISTORY:
  11/07/03 written - wherry
  11/12/03 changed radius - wherry

(See pro/rgbcolor/nw_arcsinh.pro)


NW_CUT_TO_BOX

[Previous Routine] [Next Routine] [List of Routines]
NAME:
  nw_cut_to_box
PURPOSE:
  Limits the pixel values of the image to a 'box', so that the colors
  do not saturate to white but to a specific color.
INPUTS:
  colors      - (NXxNYx3) array that contains the R/G/B images
OPTIONAL INPUTS:
  origin      - (3x1) array containing R0/G0/B0
              - default is [0,0,0]
KEYWORDS:

OUTPUTS:
  The color limited image
BUGS:
  
REVISION HISTORY:
  11/07/03 written - wherry
  11/12/03 changed default origin - wherry

(See pro/rgbcolor/nw_cut_to_box.pro)


NW_FLOAT_TO_BYTE

[Previous Routine] [Next Routine] [List of Routines]
NAME:
  nw_float_to_byte
PURPOSE:
  Converts an array of floats in [0.0,1.0] to bytes in [0,255].
INPUTS:
  image       - image array of any dimensions; data range should be
                0.0 to 1.0
OPTIONAL INPUTS:
  bits        - number of bits per element; default 8; must be LE 8
KEYWORDS:
  none
OUTPUTS:
  The float-value image
REVISION HISTORY:
  2003-03-10  written - wherry
  2004-03-20  bits keyword - Hogg

(See pro/rgbcolor/nw_float_to_byte.pro)


NW_REBIN_IMAGE

[Previous Routine] [Next Routine] [List of Routines]
NAME:
  nw_rebin_image
PURPOSE:
  Divide the dimensions of the image by specified value
CALLING SEQUENCE:
  colors= nw_rebin_image(colors,rebin)
INPUTS:
  colors      - [NX,NY,3] array containing the R, G, and B images
  rebin       - factor by which to reduce the size of the output
                image from the input image; ie, if passed a 200x200
                image and rebin=2, it will return a 100x100 image; if
                passed rebin=0.5, it will return a 400x400 image.
OPTIONAL INPUTS:
  none
KEYWORDS:
  none
OUTPUTS:
  The resized image 
BUGS:
  Non-robust checking for whether or not to use IDL "rebin".
DEPENDENCIES:

REVISION HISTORY:
  11/14/03 written - wherry

(See pro/rgbcolor/nw_rebin_image.pro)


NW_RGB_MAKE

[Previous Routine] [Next Routine] [List of Routines]
NAME:
  nw_rgb_make
PURPOSE:
  Creates JPEG (or TIFF) from images
CALLING SEQUENCE:
  nw_rgb_make, Rim, Gim, Bim, [name=, scales=, nonlinearity=, $
      origin=, rebinfactor=, /saturatetowhite]
INPUTS:
  Rim,Gim,Bim - R, G, and B fits file names, or data arrays
OPTIONAL INPUTS:
  name        - name of the output jpeg file
  scales      - (3x1) array to scale the R/G/B
              - defaults are [1.,1.,1.]
  nonlinearity- 'b'
              - b=0 for linear fit, b=Inf for logarithmic
              - default is 3
  origin      - (3x1) array containing R0/G0/B0
              - default is [0,0,0]
  rebinfactor - integer by which to rebin pixels in the x and y
                directions; eg, a rebinfactor of 2 halves the number
                of pixels in each direction and quarters the total
                number of pixels in the image.
  quality     - quality input for WRITE_JPEG
  overlay     - [nx/rebinfactor,ny/rebinfactor,3] image to overlay on
                the input images
OPTIONAL KEYWORDS:
  saturatetowhite  - saturate high-value pixels to white rather than to color
  tiff        - make tiff instead of jpeg
  dpitiff     - set TIFF "dots per inch" resolution (only if /tiff set)
  invert      - ???
OPTIONAL OUTPUTS:
  
EXAMPLE:
  
KEYWORDS:
  none
OUTPUTS:
  JPEG (or TIFF)
DEPENDENCIES:
  
BUGS:
  If the code congridded before making the initial colors matrix, it
  would use less memory and be faster.
  
REVISION HISTORY:
 12/03/03 written - wherry

(See pro/rgbcolor/nw_rgb_make.pro)


NW_SCALE_RGB

[Previous Routine] [Next Routine] [List of Routines]
NAME:
  nw_scale_rgb
PURPOSE:
  mulitiplies the RGB image by their respective scales
CALLING SEQUENCE:
  nw_scale_rgb, colors, [scales=]
INPUTS:
  colors      - (NXxNYx3) array containing the R, G, and B
OPTIONAL INPUTS:
  scales      - (3x1) array to scale the R/G/B
              - defaults are [1.,1.,1.]
KEYWORDS:
  none
OUTPUTS:
  The RGB image 
COMMENTS:
  The input image must be background-subtracted (ie, have zero background).
BUGS:
  
DEPENDENCIES:

REVISION HISTORY:
  11/07/03 written - wherry

(See pro/rgbcolor/nw_scale_rgb.pro)


OFFSET_FROM_PAIRS

[Previous Routine] [Next Routine] [List of Routines]
 BUGS:
   - No correct code header!

 D. Finkbeiner - modified to compare probabilities of first and
                 second peaks.  -DPF 4 Nov 2000
 set errflag if best value on edge - DPF 26 Nov 2000

(See pro/astrom/offset_from_pairs.pro)


PLANCKCORR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   planckcorr
 PURPOSE:
   Compute factor to convert from brightness temp to thermodynamic temp

 CALLING SEQUENCE:
   planckcorr, nu_ghz

 INPUTS:
   nu_ghz -    frequency in GHz

 OUTPUTS:
   <value> -   conversion factor

 PROCEDURES CALLED:
   <none>

 COMMENTS:
   This conversion factor corresponds to the PLNCKCOR FITS header
   keyword found in COBE/DMR data files produced by NASA.
   For comparison, their results for 31.5, 53, and 90 GHz are

   PLNCKCOR=             1.025724 /  Thermodynamic temperature = 
   PLNCKCOR=             1.074197 /  Thermodynamic temperature =  
   PLNCKCOR=             1.225941 /  Thermodynamic temperature =
   COMMENT                        /   PLNCKCOR * antenna temperature  

 REVISION HISTORY:
   Written by D. Finkbeiner, 10 March, 1999 - Berkeley

(See pro/dust/planckcorr.pro)


PLOT_POLY

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   plot_poly
 PURPOSE:
   plots a mangle polygon (or passes back what you need to plot it)
 CALLING SEQUENCE:
   plot_poly, poly [, offset=, xrange=, yrange=, filename=, /fill, $
      /nooutline, xsize=, ysize=, /over, color=, minside=, dangle=, $
      outline_thick=, splot=, /aitoff ]
 INPUTS:
   poly - mangle polygon (e.g. one created by construct_polygon())
 OPTIONAL INPUTS:
   offset - offset to apply to ra
   xrange, yrange - ranges to pass to plot
   filename, xsize, ysize - PS file to output to (and its sizes)
   minsize, dangle - pass to gverts
 OPTIONAL KEYWORDS:
   /fill - fill
   /over - over plot on current device
   /nooutine - do not outline
 COMMENTS:
 EXAMPLES:
 BUGS:
 PROCEDURES CALLED:
 REVISION HISTORY:
   01-Oct-2002  Written by MRB (NYU)

(See pro/mangle/plot_poly.pro)


POLYGON_OVERLAP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   polygon_overlap
 PURPOSE:
   create the polygon which is the overlap between two polygons
 CALLING SEQUENCE:
   newpoly= polygon_overlap(poly1,poly2)
 INPUTS:
   poly1 - first input polygon
   poly2 - second input polygon
 OPTIONAL INPUTS:
 OUTPUTS:
   newpoly - output polygon
 OPTIONAL INPUT/OUTPUTS:
 COMMENTS:
   To get the area of the overlap (in sterradians):
     newpoly=polygon_overlap(poly1,poly2)
     print, newpoly.str
 EXAMPLES:
 BUGS:
 PROCEDURES CALLED:
 REVISION HISTORY:
   31-Jan-2003  Written by MRB (NYU)

(See pro/mangle/polygon_overlap.pro)


POLYWARP_ROTATE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   polywarp_rotate
 PURPOSE:
   wrapper on polywarp to do a simple rotation
 CALLING SEQUENCE
   newim= polywarp_rotate( im , theta,  [center=] )
 INPUTS:
   im       - [nx,ny] original image
   theta    - angle of rotation (counter-clockwise is position)
 OPTIONAL INPUTS:
   center    - [2] x/y center to rotate about 
                (default [(nx-1)*0.5, (ny-1)*0.5])
 OUTPUTS:
   newim    - [nx,ny] final image
 COMMENTS:
   polywarp uses a cubic approximation to the sinc function. 
   this routine rotates the image about its center. 
 REVISION HISTORY:
   2004-04-15  Written - Blanton (NYU)

(See pro/image/polywarp_rotate.pro)


POLYWARP_SHIFT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   polywarp_shift
 PURPOSE:
   wrapper on polywarp to do a simple shift
 CALLING SEQUENCE
   newim= polywarp_rotate( im , shift )
 INPUTS:
   im       - [nx,ny] original image
   shift    - [2] x,y shift
 OUTPUTS:
   newim    - [nx,ny] final image
 COMMENTS:
   polywarp uses a cubic approximation to the sinc function. 
 REVISION HISTORY:
   2004-04-15  Written - Blanton (NYU)

(See pro/image/polywarp_shift.pro)


POLY_ITER

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

 PURPOSE:
   Calls IDL poly_fit iteratively with outlier rejection

 CALLING SEQUENCE:
   poly_iter, x, y, ndeg, nsig, yfit, coeff=coeff

 INPUTS:
   x, y    - indep, dep variables
   ndeg    - degree of polynomial 
   yfit    - fit y at given x values

 OUTPUTS:
   coeff   - array of coefficients

 COMMENTS:

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:
   poly_fit

 REVISION HISTORY:
   moved from hoggpt 10-Jan-2002

(See pro/math/poly_iter.pro)


POPULATE_IMAGE

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

 PURPOSE:
   Populate a vector or image with weights at the specified positions.

 CALLING SEQUENCE:
   populate_image, image, x, [y, weights=, assign=]

 INPUTS:
   image      - Image vector or array
   x          - X coordinate(s) of locations to populate, 0-indexed

 OPTIONAL INPUTS:
   y          - Y coordinate(s) of locations to populate, 0-indexed
   weights    - Weight(s) to add at each X or X,Y position
   assign     - Assignment scheme:
                'ngp': nearest grid point assignment; default
                'cic': cloud-in-cell assignment

 OUTPUTS:
   image      - (Modified)

 COMMENTS:
   If IMAGE is type double, then that image and X and Y are all treated
   as double-precision in the assignment code.  Otherwise, all values
   are treated as floating-point.

 BUGS:

 PROCEDURES CALLED:
   Dynamic link to pop_image.c

 REVISION HISTORY:
   17-May-2000  Written by D. Schlegel, Princeton

(See pro/image/populate_image.pro)


PPMTOMPEG

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

 PURPOSE:
   Wrapper for ppmtompeg, the open-source UNIX mpeg writer

 CALLING SEQUENCE:
   ppmtompeg, bytcube, [ output, tmpdir= ]
 
 INPUTS:
   bytcube  - Byte array [X,Y,NFRAME]
   output   - Output file name; default 'idl.mpeg'

 KEYWORDS:
   tmpdir   - temp directory to do dirty work in; default to '/tmp/mpeg1234/'

 OUTPUTS:

 COMMENTS:
   A single mpeg file is written.
   Temporary files are removed after the MPEG file is made.

 EXAMPLES:
   ppmtompeg, bytscl(imagecube, min=800, max=1600), 'movie.mpeg'

 PROCEDURES CALLED:
   rmfile

 INTERNAL SUPPORT PROCEDURES:
   ppmtompeg_parameters

 REVISION HISTORY:
   2002-Mar-29  Douglas Finkbeiner, Princeton University
                  dfink@astro.princeton.edu

(See pro/mpeg/ppmtompeg.pro)


PREDICT_SYNC

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

 PURPOSE:
   Read predictions of synchtron emission and return sky intensity.

 CALLING SEQUENCE:
   value = predict_sync( [ gall, galb, nu=nu, infile=infile, $
    skipline=skipline, outfile=outfile, interp=interp, $
    noloop=noloop, verbose=verbose, ipath=ipath, units=units ] )

 INPUTS:

 OPTIONAL INPUTS:
   gall:       Galactic longitude(s) in degrees
   galb:       Galactic latitude(s) in degrees
   nu:         Frequency in GHz.  If this is a vector, it must be the same
               dimension as GALL and GALB.  If this is a scalar, then it
               applies to all positions GALL, GALB.
   infile:     If set, then read GALL, GALB from this file.  If NU is not
               set, then NU is read as the 3rd column of this same file.
   skipline:   Number of lines to skip at the top of the input file
   outfile:    If set, then write results to this file
   interp:     Set this flag to return a linearly interpolated value
               from the 4 nearest pixels.
   noloop:     Set this flag to read all values at once without a FOR loop.
               This is a faster option for reading a large number of values,
               but requires reading an entire FITS image into memory.
               (Actually, the smallest possible sub-image is read.)
   verbose:    Set this flag for verbose output, printing pixel coordinates
               and map values.  Setting NOLOOP disables this option.
   ipath:      Path name for synchrotron maps; default to path set by the
               environment variable $DUST_DIR/map, or to the current
               directory.
   units:      Units for output values:
               'MJy'    : MJy/sr (default)
               'microK' : brightness (antenna) temperature [micro-Kelvin]
               'thermo' : thermodynamic temperature [micro-Kelvin]

 OUTPUTS:
   value:      Predicted emission value(s) from synchtrotron maps

 COMMENTS:
   These predictions are based upon the following radio surveys:
     408 MHz - Haslam et al. 1981, A&A, 100, 209
     1420 MHz - Reich & Reich 1986, A&AS, 63, 205
     2326 MHz - Jonas, Baart, & Nicolson 1998 MNRAS, 297, 977
   A detailed description of this data product may be found in:
   "Extrapolation of the Haslam 408 MHz survey to CMBR Frequencies",
   by D. P. Finkbeiner, & M. Davis, in preparation.

   Either the coordinates GALL, GALB and NU must be set, or their values
   must exist in the file INFILE.  Output is written to the variable VALUE
   and/or the file OUTFILE.

 EXAMPLES:
   Read the predicted synchtrotron emission at Galactic (l,b)=(12,+34.5) 
   interpolating from the nearest 4 pixels, and return result in VALUE.
   > value = predict_sync(12, 34.5, nu=3000, /interp)

 PROCEDURES CALLED:
   fac_flux2temp()
   planckcorr()
   rdfloat
   wcs_getval()

 DATA FILES:
   Haslam_clean_ngp.fits
   Haslam_clean_sgp.fits
   Synch_Beta_ngp.fits
   Synch_Beta_sgp.fits

 REVISION HISTORY:
   17-Mar-1999  Written by David Schlegel, Princeton
                & Doug Finkbeiner, Berkeley

(See pro/dust/predict_sync.pro)


PREDICT_THERMAL

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

 PURPOSE:
   Read predictions of thermal dust emission from Finkbeiner et al. maps
   and return sky intensity.

 CALLING SEQUENCE:
   value = predict_thermal( [ gall, galb, nu=nu, infile=infile, $
    skipline=skipline, outfile=outfile, resolution=resolution, model=model, $
    interp=interp, noloop=noloop, verbose=verbose, ipath=ipath, units=units ] )

 INPUTS:

 OPTIONAL INPUTS:
   gall:       Galactic longitude(s) in degrees
   galb:       Galactic latitude(s) in degrees
   nu:         Frequency in GHz.  If this is a vector, it must be the same
               dimension as GALL and GALB.  If this is a scalar, then it
               applies to all positions GALL, GALB.
   resolution: Set to one of the following (default is 'I4096'):
               'I4096' : IRAS 4096^2 map (highest-resolution; default)
               'I2048' : IRAS 2048^2 map
               'I1024' : IRAS 1024^2 map
               'D1024' : DIRBE 1024^2 map
   model:      Model number (default to 8):
               1: One-component, nu^1.5 emissivity
               2: One-component, nu^1.7 emissivity
               3: One-component, nu^2.0 emissivity
               4: One-component, nu^2.2 emissivity
               5: Two-component, alpha1=1.5, alpha2=2.6, Pollack et al. model
               6: Two-component, both nu^2 emissivities, fit f+q
               7: Two-component, alpha1=1.5, alpha2=2.6, fit f+q
               8: Two-component, alpha1=1.67, alpha2=2.70, fit alphas+f+q
   infile:     If set, then read GALL, GALB from this file.  If NU is not
               set, then NU is read as the 3rd column of this same file.
   skipline:   Number of lines to skip at the top of the input file
   outfile:    If set, then write results to this file
   interp:     Set this flag to return a linearly interpolated value
               from the 4 nearest pixels.
   noloop:     Set this flag to read all values at once without a FOR loop.
               This is a faster option for reading a large number of values,
               but requires reading an entire FITS image into memory.
               (Actually, the smallest possible sub-image is read.)
   verbose:    Set this flag for verbose output, printing pixel coordinates
               and map values.  Setting NOLOOP disables this option.
   ipath:      Path name for dust maps; default to path set by the
               environment variable $DUST_DIR/map, or to the current
               directory.
   units:      Units for output values:
               'MJy'    : MJy/sr (default)
               'microK' : brightness (antenna) temperature [micro-Kelvin]
               'thermo' : thermodynamic temperature [micro-Kelvin]
                          assuming T(CMB) = 2.73 K

 OUTPUTS:
   value:      Predicted emission value(s) from Lambert-projection maps

 COMMENTS:
   These predictions are based upon the following paper:
   "Extrapolation of Galactic Dust Emission at 100 Microns to CMBR
   Frequencies using FIRAS", Finkbeiner, D. P., Davis, M., & Schlegel, D. J.,
   ApJ, 1999, submitted (5 March 1999)

   Either the coordinates GALL, GALB and NU must be set, or their values
   must exist in the file INFILE.  Output is written to the variable VALUE
   and/or the file OUTFILE.

 EXAMPLES:
   Read the predicted thermal emission from dust at Galactic (l,b)=(12,+34.5) 
   interpolating from the nearest 4 pixels, and return result in VALUE.
   > value = predict_thermal(12, 34.5, nu=3000, /interp)

 PROCEDURES CALLED:
   djs_planck()
   fac_flux2temp()
   planckcorr()
   rdfloat
   wcs_getval()

 DATA FILES:
   FINK_Rmap_ngp.fits
   FINK_Rmap_sgp.fits
   SFD_d100_1024_ngp.fits
   SFD_d100_1024_sgp.fits
   SFD_i100_1024_ngp.fits
   SFD_i100_1024_sgp.fits
   SFD_i100_2048_ngp.fits
   SFD_i100_2048_sgp.fits
   SFD_i100_4096_ngp.fits
   SFD_i100_4096_sgp.fits

 INTERNAL PROCEDURES:
   kfactor()

 REVISION HISTORY:
   10-Mar-1999  Written by David Schlegel, Princeton

(See pro/dust/predict_thermal.pro)


PROPMOTDIS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   propmotdis
 PURPOSE:
   Compute proper motion distances (for c/H_0=1).
 CALLING SEQUENCE:
   D= propmotdis(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:
   proper motion 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:
   comdis()
 REVISION HISTORY:
   25-Jun-2000  Written by Hogg (IAS)
   2004-Sep-8, Added equation of state for OmegaL, Padmanabhan (Princeton)

(See pro/cosmography/propmotdis.pro)


PSCONFIG

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

 PURPOSE:

   This program is simply a function wrapper for the FSC_PSCONFIG
   object program (fsc_psconfig__define.pro). It was written so
   that it could serve as a drop-in replacement for the PS_FORM
   program it replaces. It calls the object program's graphical
   user interface as a modal widget and returns the DEVICE keywords
   collected from the form in a form that is appropriate for
   configuring the PostScript device.

 AUTHOR:

   FANNING SOFTWARE CONSULTING
   David Fanning, Ph.D.
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: davidf@dfanning.com
   Coyote's Guide to IDL Programming: http://www.dfanning.com/

 CALLING SEQUENCE:

   psKeywords = PSConfig()

 CATEGORY:

   Configuring PostScript output.

 DOCUMENTATION:

   Complete documentation for the FSC_PSCONFIG object, including
   keyword and method descriptions, and example programs using the object
   can be found on the Coyote's Guide to IDL Programming web page:

     http://www.dfanning.com/programs/docs/fsc_psconfig.html

 INPUT:

    psConfigObject -- An optional FSC_PSCONFIG object reference can be
       passed as an argument to the function. The object is not destroyed
       if passed in as an argument.

       psObject = Obj_New("FSC_PSCONFIG")
       keywords = PSConfig(psObject)

    Having the object means that you have an on-going and current record
    of exactly how your PostScript device is configured. Be sure to destroy
    the object when you are finished with it.

 KEYWORDS:

   Any keyword accepted by the FSC_PSCONFIG object can be used with
   this program. Here are a few of the most popular keywords.

   Bits_per_Pixel - The number of image bits saved for each image pixel: 2, 4, or 8. The default is 8.
   Color - Set this keyword to select Color PostScript output. Turned on by default.
   DefaultSetup - Set this keyword to the "name" of a default style. Current styles (you can easily
     create and add your own to the source code) are the following:

       "System (Portrait)" - The normal "default" system set-up. Also, "System".
       "System (Landcape)" - The normal "default" landscape system set-up.
       "Centered (Portrait)" - The window centered on the page. Also, "Center" or "Centered".
       "Centered (Landscape)" - The window centered on the landscape page. Also, "Landscape".
       "Square (Portrait)" - A square plot, centered on the page.
       "Square (Landscape)" - A square plot, centered on the landscape page.
       "Figure (Small)" - A small encapsulated figure size, centered on page. Also, "Encapsulated" or "Encapsulate".
       "Figure (Large)" - A larger encapsulated figure size, centered on page. Also, "Figure".
       "Color (Portrait)" - A "centered" plot, with color turned on. Also, "Color".
       "Color (Landscape)" - A "centered" landscape plot, with color turned on.

   Directory - Set this keyword to the name of the starting directory. The current directory is used by default.
   Encapsulate - Set this keyword to select Encapsulated PostScript output. Turned off by default.
   European - Set this keyword to indicate "european" mode (i.e., A4 page and centimeter units). Turned off by default.
   Filename - Set thie keyword to the name of the PostScript file. The default is "idl.ps".
   Inches - Set this keyword to indicate sizes and offsets are in inches as opposed to centimeters. Set by European keyword by default.
   Landscape - Set this keyword to select Landscape page output. Portrait page output is the default.
   PageType - Set this keyword to the "type" of page. Possible values are:
       "Letter" - 8.5 by 11 inches. (Default, unless the European keyword is set.)
       "Legal" - 8.5 by 14 inches.
       "Ledger" - 11 by 17 inches.
       "A4" - 21.0 by 29.7 centimeters. (Default, if the European keyword is set.)
   XOffset - Set this keyword to the X Offset. Uses "System (Portrait)" defaults. (Note: offset calculated from lower-left corner of page.)
   XSize - Set this keyword to the X size of the PostScript "window". Uses "System (Portrait)" defaults.
   YOffset - Set this keyword to the Y Offset. Uses "System (Portrait)" defaults. (Note: offset calculated from lower-left corner of page.)
   YSize - Set this keyword to the Y size of the PostScript "window". Uses "System (Portrait)" defaults.

   In addition, the following keywords can be used:

   CANCEL -- An output keyword that will be set to 1 if the user
   chooses the Cancel button on the form. It will be 0 otherwise.

   FONTINFO -- Set this keyword is you wish to have font information
   appear on the form. The default is to not include font information.

   FONTTYPE -- Set this keyword to a named variable that will indicate
   the user's preference for font type. Values will be -1 (Hershey fonts),
   0 (hardware fonts), and 1 (true-type fonts). This keyword will always
   return -1 unless the FONTINFO keyword has also been set.

   GROUP_LEADER -- Set this keyword to a widget identifier of the widget
   you wish to be a group leader for this program.

 EXAMPLE:

   To have the user specify PostScript configuration parameters, use
   the program like this:

     keywords = PSConfig(Cancel=cancelled)
     IF cancelled THEN RETURN
     thisDevice = !D.Name
     Set_Plot, 'PS'
     Device, _Extra=keywords
     Plot, findgen(11) ; Or whatever graphics commands you use.
     Device, /Close_File
     Set_Plot, thisDevice

 OTHER PROGRAMS NEEDED:

   The following programs are required to run this one:

     fsc_droplist.pro
     fsc_fileselect.pro
     fsc_inputfield.pro
     fsc_plotwindow
     fsc_psconfig__define.pro

 MODIFICATIONS:

   Written by David Fanning, 31 January 2000.

(See pro/psconfig/psconfig.pro)


PSF_REJECT_CR

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

 PURPOSE:
   Find pixels contaminated by cosmic rays (CRs) using PSF criteria

 CALLING SEQUENCE:
   cr = psf_reject_cr(image, ivar, psfvals, satmask=, $
            nsigma=, cfac=, niter=, c2fudge=)

 INPUTS:
   image     - image to test
   ivar      - inverse variance of image
   psfvals   - values of psf at 1 pix and sqrt(2) pixels from center
   satmask   - saturated pixel mask (1=saturated)
   nsigma    - minimum value (in sigma) for condition 2 [default 6]
   cfac      - consistency factor [in sigma] for condition 3 [def 3]
   niter     - max number of iterations [def 6]
               c2fudge   - fudge factor to multiply psfvals by on
                           first pass [def 0.8] 

 OUTPUTS:
   cr        - byte array, same size as image (1=CR)

 EXAMPLES:
   

 COMMENTS:
   Algorithms designed by R Lupton and J. Gunn, implemented in C by Lupton,
    re-implemented by M. Blanton as reject_cr. 
    Now completely rewritten by D. Finkbeiner as psf_reject_cr.
    see Lupton's CR.c in photo product for more. 

   do NOT need to call with zeroed image
   Lupton's screed is at: http://www.astro.princeton.edu/~rhl/photomisc/

 REVISION HISTORY:
   2005-Mar-09  Written by Douglas Finkbeiner, Princeton

(See pro/image/psf_reject_cr.pro)


PSF_REJECT_CR_SINGLE[1]

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

 PURPOSE:
   test a list of "suspect" pixels for cosmic rays (CRs)

 CALLING SEQUENCE:
   result=psf_reject_cr_single(im, gd, ivar, satmask, min_sigma, $
         c3fac, psfvals, ind0, neighbor=neighbor)

 INPUTS:
   im        - image to test
   gd        - array of "good pixels" to use (1=good)
   ivar      - inverse variance of image
   satmask   - saturated pixel mask (1=saturated)
   min_sigma - minimum value (in sigma) for condition 2
   c3fac     - consistency factor [in sigma] for condition 3
   psfvals   - values of psf at 1 pix and sqrt(2) pixels from center
   ind0      - index list of pixels to investigate

 OUTPUTS:
   result    - byte array of results, same length as ind0 (1=CR)

 OPTIONAL OUTPUTS:
   neighbor  - index list of neighbors of just-found CRs

 EXAMPLES:
   always called by psf_reject_cr

 COMMENTS:
   Algorithms designed by R Lupton and J. Gunn, implemented in C by Lupton,
    re-implemented by M. Blanton as reject_cr. 
    Now completely rewritten by D. Finkbeiner as psf_reject_cr.
    see psf_reject_cr for more details. 
   gd indicates which pixels may be safely used for interpolate and
    background determination.  gd gets updated as CRs are zapped. 
   
 REVISION HISTORY:
   2005-Mar-09  Written by Douglas Finkbeiner, Princeton

(See pro/image/dpf_reject_cr.pro)


PSF_REJECT_CR_SINGLE[2]

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

 PURPOSE:
   test a list of "suspect" pixels for cosmic rays (CRs)

 CALLING SEQUENCE:
   result=psf_reject_cr_single(im, gd, ivar, satmask, min_sigma, $
         c3fac, psfvals, ind0, neighbor=neighbor)

 INPUTS:
   im        - image to test
   gd        - array of "good pixels" to use (1=good)
   ivar      - inverse variance of image
   satmask   - saturated pixel mask (1=saturated)
   min_sigma - minimum value (in sigma) for condition 2
   c3fac     - consistency factor [in sigma] for condition 3
   psfvals   - values of psf at 1 pix and sqrt(2) pixels from center
   ind0      - index list of pixels to investigate

 OUTPUTS:
   result    - byte array of results, same length as ind0 (1=CR)

 OPTIONAL OUTPUTS:
   neighbor  - index list of neighbors of just-found CRs

 EXAMPLES:
   always called by psf_reject_cr

 COMMENTS:
   Algorithms designed by R Lupton and J. Gunn, implemented in C by Lupton,
    re-implemented by M. Blanton as reject_cr. 
    Now completely rewritten by D. Finkbeiner as psf_reject_cr.
    see psf_reject_cr for more details. 
   gd indicates which pixels may be safely used for interpolate and
    background determination.  gd gets updated as CRs are zapped. 
   
 REVISION HISTORY:
   2005-Mar-09  Written by Douglas Finkbeiner, Princeton

(See pro/image/psf_reject_cr_single.pro)


QUICK_PHOTFRAC

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

 PURPOSE:
   Create a list of pixel numbers and their fractional contribution to
   an annular region.

 CALLING SEQUENCE:
   quick_photfrac, xcen, ycen, Rvec, xdimen=, ydimen=, /ragged, $
    [ xPixNum=, yPixNum=, pixnum=, fracs=, fillfrac= ]

 INPUTS:
   xcen:       X center(s)
   ycen:       Y center(s)
   Rvec:       Either a 2-element array with two radii to define an annulus,
               or a scalar to define a circular aperature.

 OPTIONAL INPUTS:
   xdimen:     Number of X pixels.
   ydimen:     Number of Y pixels.
   ragged:     Use ragged edges (weights either 0 or 1) - faster

 OUTPUTS:
   pixnum:     Pixel number, 0-indexed, for referencing array using one index.
   xPixNum:    Pixel number in X, 0-indexed.
   yPixNum:    Pixel number in Y, 0-indexed.
   fracs:      Return value of covering fraction of the annulus
               over the pixel number.
   fillfrac:   Ratio of returned pixel areas to the annulus area;
               this ratio should equal 1.0 if the aperature falls completely
               within the image boundaries

 COMMENTS:
   The total counts within this region is given by
     totcounts = total( pData(pixnum) * fracs )
   The area within this region is given by
     area = total(fracs)
   The average counts is given by
     totcounts = total( pData(pixnum) * fracs ) / total(fracs)

   If no pixels within the given annulus are found, then return pixnum=-1.

 BUGS:
   The area can be calculated with TOTAL(FRACS), and will differ
   slightly from the analytic area within a circle.

 PROCEDURES CALLED:
   djs_ceil()
   djs_floor()

 REVISION HISTORY:
   Written by D. Finkbeiner, 2000-Nov-02
  derived from djs_photfrac
   Written D. Schlegel, 27 November 1996, Durham
   

(See pro/djsphot/quick_photfrac.pro)


QU_TO_BAPHI

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   qu_to_baphi
 PURPOSE:
   transform q and u values to b/a and pih
 CALLING SEQUENCE:
   qu_to_baphi, q, u, ba, phi
 INPUTS:
   q - Stokes q parameter
   u - Stokes u parameter
 OPTIONAL INPUTS:
 OUTPUTS:
   ba - b/a
   phi - angle phi
 OPTIONAL INPUT/OUTPUTS:
 DATA DEPENDENCIES:
 COMMENTS:
 EXAMPLES:v
 BUGS:
 PROCEDURES CALLED:
 REVISION HISTORY:
   10-Aug-2002  Written by Mike Blanton, NYU

(See pro/image/qu_to_baphi.pro)


QZAP.PRO

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

 PURPOSE:
   Remove cosmic rays from a 2-D image.

 CALLING SEQUENCE:
   qzap, name, outname, [ outmaskname, skyfiltsize=skyfiltsize, $
    boxsize=boxsize, nsigma=nsigma, /nofluxratio, maxiter=maxiter, $
    fluxcompare=fluxcompare, nrings=nrings, path=path, nzap=nzap ]

 INPUTS:
   name       - 2-D image array, or name of input FITS file.
   outname    - Output image array, or name of output FITS file.

 OPTIONAL INPUTS:
   outmaskname- Output mask array, or name of output FITS file.
   skyfiltsize- Boxsize for computing local sky value; default to 15.
   boxsize    - Boxsize for computing local median; default to 5.
   nsigma     - Rejection threshhold in sigma; default to 4.
   fluxratio  - Comparison value for identifying cosmics; default to 0.15
   maxiter    - Number of zapping iterations; default to 2.
   nofluxcompare - Set to disable the flux comparison algorithm, which
                is the "black magic" heart of this routine.
   nrings     - Radius of cosmic ray neighbors to also zap; default to 1.
   path       - Input/output path name

 OPTIONAL OUTPUTS:
   NZAP       - Number of pixels zapped.

 COMMENTS:
   Based on the tried and true IRAF QZAP routine by Mark Dickinson.
   Results from IDL qzap.pro and IRAF QZAP are found to be virtually
   identical.

 PROCEDURES CALLED:
   djs_iterstat

 REVISION HISTORY:
   20-Aug-1999  Written by Cullen Blake & David Schlegel, Princeton

(See pro/image/qzap.pro)


RADEC2STRING

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   radec2string
 PURPOSE:
   converts RA and DEC to string versions
 CALLING SEQUENCE:
   radec2string, ra, dec, outstring [, rahr=, ramin=, rasec=, $
     decdeg=, decmin=, decsec=, rastr=, decstr=, precision= ]
 INPUTS:
   ra - deg
   dec - deg
 OPTIONAL INPUTS:
   precision  - how many decimal places to put on dec; ra gets one more
 OUTPUTS:
   outstring - output string of form xx:xx:xx.xxx[+|-]xx:xx:xx.xx
 OPTIONAL OUTPUTS:
   rahr, ramin, rasec - components of first half of string
   decdeg, decmin, decsec - components of second half of string
   rastr, decstr - first and second halves separately
 COMMENTS:
   Defaults to SDSS name conventions.
   Don't EVER use goddard/pro/astro/adstring.pro.
   Hacked from hogg_iau_name
 BUGS:
   Doesn't deal properly with precision<0 
 REVISION HISTORY:
   2005-10-24  Blanton (NYU)

(See pro/misc/radec2string.pro)


RADEC_GREATCIRCLE

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

 PURPOSE:
   Solve for the great circle for a set of RA,DEC positions at a set of times.

 CALLING SEQUENCE:
   fitval = radec_greatcircle(ralist, declist, xposlist, yposlist, $
    [ timelist, start_parms, maxiter=, fixed=, muerr=, nuerr=, $
    /debug, niter=, status=, muresid=, nuresid= ] )

 INPUTS:
   ralist     - RA coordinates (degrees) [NPOINTS]
   declist    - DEC coordinates (degrees) [NPOINTS]
   xposlist   - X positions, perpendicular to scan direction [NPOINTS]
   yposlist   - Y positions, along the scan direction [NPOINTS]

 OPTIONAL INPUTS:
   timelist   - Time stamps.  If specified, then a time^2 term is
                also fit along the scan direction, for a total of
                6 fit parameters instead of 5 [NPOINTS].
   start_parms- Initial guess for the great circle fit [NPARM].
   maxiter    - Maximum number of iterations for fit; default to 5000
   fixed      - If set, then fit for each parameter where this is 0,
                and fit for each parameter where this is 1 [NPARM].
   muerr      - Error of each point in MU coordinate; default to 1 arcsec;
                either a scalar or of length [NPOINTS]; used for chi^2
   nuerr      - Error of each point in NU coordinate; default to 1 arcsec;
                either a scalar or of length [NPOINTS]; used for chi^2
   debug      - If set, then plot the MU,NU deviations in units of arcsec
                at each iteration of the fit.  Also, don't call MPFIT()
                with /QUIET, but print its verbose output on each iteration.

 OUTPUTS:
   fitval     - Best-fit parameters [NPARM].

 OPTIONAL OUTPUTS:
   niter      - Number of iterations performed.
   status     - Return status from MPFIT() function, set to a non-zero
                value if an error occurred.
   muresid    - MU coordinate residuals from best-fit
   nuresid    - NU coordinate residuals from best-fit

 COMMENTS:
   The fit parameters are as follows:
     FITVAL[0] - Starting MU coordinate from [0,360) degrees
     FITVAL[1] - Node of great circle from [0,360) degrees
     FITVAL[2] - Inclination of great circle from [0,180) degrees
     FITVAL[3] - Perpendicular offset of scan from the great circle [degrees];
                 this is what is called XBORE for SDSS imaging scans.
                 Fix this parameter to zero if you want to fit exactly along
                 a great circle, and not offset from it.
     FITVAL[4] - Tracking rate in degrees per unit of YPOSLIST;
                 for example, if YPOSLIST is is units of pixels,
                 this is in units of degrees/pixel
     FITVAL[5] - Optional parameter for fitting a quadratic term in time

   The set of parametric equations to convert from xposlist,yposlist,timelist
   to ra,dec are as follows:
     mu = FITVAL[0] + yposlist * FITVAL[4] + FITVAL[5] * timelist^2
     nu = xposlist + FITVAL[3]
     xx = cos(mu-node) * cos(nu)
     yy = sin(mu-node) * cos(nu) * cos(FITVAL[2]) - sin(nu) * sin(FITVAL[2])
     zz = sin(mu-node) * cos(nu) * sin(FITVAL[2]) + sin(nu) * cos(FITVAL[2])
     ra = (180/!pi) * atan(yy,xx) + FITVAL[1]
     dec = (180/!pi) * asin(zz)

  Note that one can change the sign of the inclination by adding 180 degrees
  to the node.

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:
   cirrange
   djs_plot
   mpfit()
   radec_to_munu

 INTERNAL SUPPPORT ROUTINES:
   radec_gcfn()

 REVISION HISTORY:
   21-Nov-2002  Written by David Schlegel, Princeton.

(See pro/coord/radec_greatcircle.pro)


RADEC_TO_ETALAMBDA

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   radec_to_etalambda
 PURPOSE:
   convert from RA, Dec to eta, lambda (SDSS survey coordinates)
 CALLING SEQUENCE:
   radec_to_etalambda, ra,dec,eta,lambda,stripenumber=stripenumber
 INPUTS:
   ra      RA (deg), J2000
   dec     Dec (deg), J2000
 OUTPUTS:
   eta     SDSS survey coordinate eta (deg)
   lambda  SDSS survey coordinate lambda (deg)
 OPTIONAL OUTPUTS:
   stripenumber   SDSS survey stripe number (integer)
 BUGS:
   Location of the survey center is hard-wired (in etalambda_to_radec.pro);
     it should be read from astrotools.
 REVISION HISTORY:
   2001-Jul-21  written by Hogg (NYU)
   2002-Oct-04  modified by Blanton (NYU)

(See pro/coord/radec_to_etalambda.pro)


RADEC_TO_MUNU

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

 PURPOSE:
   Convert from equatorial coordinates to SDSS great circle coordinates.

 CALLING SEQUENCE:
   radec_to_munu, ra, dec, [ mu, nu, stripe=, node=, incl=, phi= ]

 INPUTS:
   ra         - Right ascension (J2000 degrees)
   dec        - Declination (J2000 degrees)

 OPTIONAL INPUTS:
   stripe     - Stripe number for SDSS coordinate system.  If specified,
                the NODE,INCL are ignored; scalar or array with same
                dimensions as MU.
   node       - Node of great circle on the J2000 celestial equator (degrees),
                scalar or array with same dimensions as MU.
   incl       - Inclination of great circle relative to the J2000

 OUTPUTS:

 OPTIONAL OUTPUTS:
   mu         - Mu coordinate, scalar or array (degrees)
   nu         - Nu coordinate, scalar or array (degrees)
   phi        - Counter-clockwise position angle w.r.t. north for an arc
                in the +nu direction.

 COMMENTS:
   Either STRIPE or NODE,INCL must be specified.

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:
   cirrange
   stripe_to_incl()

 REVISION HISTORY:
   20-Feb-2002  Written by M. Blanton, NYU
   03-Oct-2002  Modified by David Schlegel, Princeton.

(See pro/coord/radec_to_munu.pro)


RDSS_FITS

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

 PURPOSE:
   Read a FITS file into IDL data and header variables

 CALLING SEQUENCE:
   image = rdss_fits( filename, [ hdr, /nofloat, /silent ] )

 INPUTS:
   filename   - Scalar string containing the name of the FITS file  
                (including extension) to be read.   If the filename has
                a *.gz extension, it will be treated as a gzip compressed
                file.   If it has a .Z extension, it will be treated as a
                Unix compressed file.

 OPTIONAL KEYWORDS:
   nofloat    - If set, then keep data as unsigned integers.
   silent     - suppress informational messages

 OUTPUTS:
   image      - FITS data array constructed from designated record.
                If the specified file was not found, then return -1.

 OPTIONAL OUTPUTS:
   hdr        - String array containing the header from the FITS file.

 COMMENTS:
   This routine will read a simple FITS image, or convert a non-standard
   SDSS image that uses unsigned 16-bit integers.  One can pass any other
   keywords expected by READFITS().

 EXAMPLES:

 PROCEDURES CALLED:
   mrdfits()
   sxaddpar
   sxdelpar
   sxpar()

 REVISION HISTORY:
   13-May-1999  Written by David Schlegel, Princeton.
   07-Jan-2001  Finkbeiner - added /silent because of U16 message

(See pro/fits/rdss_fits.pro)


READ_BINARY_POLYGONS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   read_binary_polygons
 PURPOSE:
   Read a "polygon" format binary file written by mangle, and return
   in the IDL structure format
 CALLING SEQUENCE:
   read_binary_polygons, infile, polygons, id [, unit=]
 INPUTS:
   infile - input file name
 OPTIONAL INPUTS:
   unit - if present, read from given unit
 OUTPUTS:
   polygons - arrays of structures (eg those made by construct_field_polygon) 
   id - array of id's for polygons (should be unique)
 OPTIONAL INPUT/OUTPUTS:
 COMMENTS:
 EXAMPLES:
 BUGS:
 PROCEDURES CALLED:
 REVISION HISTORY:
   27-Sep-2003  Written by MRB (NYU)

(See pro/mangle/read_binary_polygons.pro)


READ_FITS_POLYGONS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   read_fits_polygons
 PURPOSE:
   Read a "polygon" format fits file 
 CALLING SEQUENCE:
   read_fits_polygons, infile, polygons
 INPUTS:
   infile - input file name
 OPTIONAL INPUTS:
 OUTPUTS:
   polygons - arrays of structures (eg those made by construct_field_polygon) 
 OPTIONAL INPUT/OUTPUTS:
 COMMENTS:
   The main point of this is to extract the xcaps and cmcaps columns
   and replace them with caps.x and caps.cm
 EXAMPLES:
 BUGS:
 PROCEDURES CALLED:
 REVISION HISTORY:
   30-Nov-2002  Written by MRB (NYU)

(See pro/mangle/read_fits_polygons.pro)


READ_MANGLE_POLYGONS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   read_mangle_polygons
 PURPOSE:
   Read a "polygon" format ascii file written by mangle, and return
   in the IDL structure format
 CALLING SEQUENCE:
   read_mangle_polygons, infile, polygons, id [, unit=]
 INPUTS:
   infile - input file name
 OPTIONAL INPUTS:
   unit - if present, read from given unit
 OUTPUTS:
   polygons - arrays of structures (eg those made by construct_field_polygon) 
   id - array of id's for polygons (should be unique)
 OPTIONAL INPUT/OUTPUTS:
 COMMENTS:
 EXAMPLES:
 BUGS:
 PROCEDURES CALLED:
 REVISION HISTORY:
   30-Nov-2002  Written by MRB (NYU)

(See pro/mangle/read_mangle_polygons.pro)


READ_MANGLE_VERTICES

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   read_mangle_vertices
 PURPOSE:
   Read in a set of vertices, mangle style
 CALLING SEQUENCE:
   read_mangle_vertices, infile, vertices, id
 INPUTS:
   infile - input file name
 OPTIONAL INPUTS:
 OUTPUTS:
   vertices - arrays of structures (eg those made by
              construct_field_vertex) 
   id - array of id's for vertices (should be unique)
   weight - arrays of weights for each vertex
   str - area of each vertex?
 OPTIONAL INPUT/OUTPUTS:
 COMMENTS:
 EXAMPLES:
 BUGS:
 PROCEDURES CALLED:
 REVISION HISTORY:
   30-Nov-2002  Written by MRB (NYU)

(See pro/mangle/read_mangle_vertices.pro)


READ_TBL

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   read_tbl
 PURPOSE:
   Read .tbl/.hdr format files output by postgres (like those of 2MASS)
 CALLING SEQUENCE:
   table= read_tbl(filebase [, chunksize=])
 INPUTS:
   filebase - filebase for filebase.hdr and filebase.tbl files
 OPTIONAL INPUTS:
   chunksize - size of chunks to read in at a time before converting [1000]
 COMMENTS:
   Returns a structure in "table"
   Not very extensively tested
 BUGS:
   I don't know if I've included ALL possible types in type2var
 REVISION HISTORY:
   2003-01-29 written by Michael Blanton (NYU)

(See pro/misc/read_tbl.pro)


REBIN_SPECTRUM

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

 PURPOSE:
   Rebin a 1-D spectrum using CIC assignment onto arbitrary pixel boundaries.

 CALLING SEQUENCE:
   yflux = rebin_spectrum( xflux, xwave, ywave )

 INPUTS:
   xflux      - Flux vector [NOLD]
   xwave      - Wavelengths of pixel edges for input XFLUX [NOLD+1],
                or the central wavelength of each pixel [NOLD]
   ywave      - Wavelengths of pixel edges for output YFLUX [NNEW+1],
                or the central wavelength of each pixel [NNEW]

 OPTIONAL INPUTS:

 OUTPUTS:
   yflux      - Rebinned spectrum

 COMMENTS:
   This function does a straight cloud-in-cell re-assignment of flux
   from one spectrum to another.  The boundaries of the flux in pixel #i,
   XFLUX[i], in the first spectrum is assumed to be uniformly distributed
   between the wavelengths [XWAVE[i],XWAVE[i+1]].  This flux is re-assigned
   to YFLUX, whose pixel #j is assumed to cover [YWAVE[j],YWAVE[j+1]].
   This algorithm is strictly flux-conserving for the wavelengths that
   overlap.

   If one wavelength grid is an integral multiple of the other, than this
   is equivalent to using the IDL REBIN command.  For example, the following
   exactly puts the flux from the XFLUX spectrum into bins twice as big:
     IDL> xflux=randomu(1234,100)
     IDL> xwave=findgen(101)
     IDL> ywave=findgen(51)*2
     IDL> yflux=rebin_spectrum(xflux,xwave,ywave)
   This could also be accomplished with
     IDL> yflux2=rebin(xflux,50)
   In this example, the two pixels of the input spectrum span the
   wavelengths [0,1] and [1,2].  The first pixel of the output spectrum
   spans [0,2].

   Both XWAVE and YWAVE must be in strictly ascending order, and cannot
   repeat any wavelengths within those vectors.

   One can also call this routine with XWAVE having the same number of
   elements as XFLUX.  In that case, we assume that the wavelengths are
   at the center of each pixel, and internal to this routine compute
   (by linear interpolation) where the pixel boundaries are.  For this case,
   we also interpret YWAVE as being at the pixel centers.

 BUGS:
   This should probably be implmented in C for better speed.
   We do not test that XWAVE and YWAVE are strictly ascending.

 PROCEDURES CALLED:

 REVISION HISTORY:
   18-Jan-2003  Written by D. Schlegel, Princeton

(See pro/image/rebin_spectrum.pro)


REJECT_CR

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

 PURPOSE:
   Detects cosmic rays by finding features sharper than the PSF

 CALLING SEQUENCE:
   reject_cr, image, image_ivar, psfvals, rejects, nsig=nsig, $
     cfudge=cfudge, c2fudge=c2fudge

 INPUTS:
   image - [nx,ny] input image (sky-subtracted)
   image_ivar - [nx,ny] variance image
   psfvals - [2] values of psf at 1 pix and sqrt(2) pixels from center

 OPTIONAL INPUTS:
   nsig - number of sigma above background required (default 6)
   cfudge - number of sigma inconsistency required (default 3.)
   c2fudge - fudge factor applied to psf (default 0.8)
   threshold - threshold flux to keep a CR (default 0.)
   niter - number of iterations to search for neighbors (default 3)
   ignoremask - do not process pixels with this set to 1

 OUTPUTS:
   rejects - [nrejects] list of rejected pixels (-1 if none)
   nrejects - number of rejected pixels

 COMMENTS:
   Ignores pixels with image_ivar set to zero. 

 BUGS:

 PROCEDURES CALLED:

 REVISION HISTORY:
   Started - 18-Nov-2003 M. Blanton (NYU)

(See pro/image/reject_cr.pro)


RESTORE_SYSVARS

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

 PURPOSE:
   restore plot system variabls from structure created by sysvars

 CALLING SEQUENCE:
   restore_sysvars, state

 INPUTS:
   state  - structure containing previous values of !p,!d,!x,!y,!z
   
 EXAMPLES:
   state = sysvars(/print)
     <code to print stuff>
   restore_sysvars, state
   
 REVISION HISTORY:
   2001-Aug-06  Written by Douglas Finkbeiner, Princeton

(See pro/plot/restore_sysvars.pro)


RMFILE

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

 PURPOSE:
   Delete file from disk.

 CALLING SEQUENCE:
   rmfile, filename

 INPUTS:
   filename   - File to delete.

 OUTPUTS:

 COMMENTS:

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:

 REVISION HISTORY:
   14-Oct-1999  Written by D. Schlegel, APO

(See pro/misc/rmfile.pro)


RSEX

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

 PURPOSE:
       Read in arbitrary SExtractor format catalogs.

 INPUTS:
       A SExtractor-format catalog

 KEYWORD PARAMETERS:

 OUTPUTS:
       Returns a structure with all catalog entries, using field
       names for tagnames. 

 COMMON BLOCKS:
       None.

 RESTRICTIONS:
       None.

 PROCEDURE:
       Use syntax
       cs = rsex('catalog.cat')

 COMMENTS:
       Uses native header information & data themselves.  
       Correctly reads longs, strings, and doubles.  

 PROCEDURES USED:
       FILE_SEARCH
       CREATE_STRUCT
       VALID_NUM
       VALID_NUM_ARR

 MODIFICATION HISTORY:
 LAM = L. Moustakas
       LAM '04may02 - fixed problem case of there being an array of
                      values based on the last header tag position.
                      will now work with that case after special
                      check. 
       LAM '04feb04 - converted from the old lrsex.pro; adapted to
                      detect and read longs, strings, and doubles.  
       LAM '04may02 - correctly identifies and reads arrays at the
                      end of the header
       LAM '04dec07 - changed findfile use to file_search 

(See pro/misc/rsex.pro)


SDSS_FLAGNAME

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

 PURPOSE:
   Return bitmask labels corresponding to bit numbers.

 CALLING SEQUENCE:
   label = sdss_flagname(flagprefix, flagvalue, [ /concat, /silent ] )

 INPUTS:
   flagprefix - Flag name (scalar string).  The following are supported:
                SPPIXMASK, TARGET, TTARGET.
   flagvalue  - Signed long with any number of its bits set.

 OPTIONAL KEYWORDS:
   concat     - If set, then concatenate all of the output labels in
                LABEL into a single whitespace-separated string.
   silent     - If set, then don't print a warning when there is no bit label
                corresponding to one of the bit values.

 OUTPUTS:
   label      - String name(s) corresponding to each non-zero bit in FLAGVALUE.

 OPTIONAL OUTPUTS:

 COMMENTS:
   This function is the inverse of SDSS_FLAGVAL().

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:
   splog
   yanny_free
   yanny_read

 DATA FILES:
   $IDLUTILS_DIR/data/sdss/sdssMaskbits.par

 REVISION HISTORY:
   01-Apr-2002 Written by D. Schlegel, Princeton.

(See pro/sdss/sdss_flagname.pro)


SDSS_FLAGVAL

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

 PURPOSE:
   Return bitmask values corresponding to labels.

 CALLING SEQUENCE:
   value = sdss_flagval(flagprefix, label)

 INPUTS:
   flagprefix - Flag name (scalar string).  The following are supported:
                SPPIXMASK, TARGET, TTARGET.
   label      - String name(s) corresponding to each non-zero bit in FLAGVALUE.

 OPTIONAL KEYWORDS:

 OUTPUTS:
   value      - Signed long with any number of its bits set.

 OPTIONAL OUTPUTS:

 COMMENTS:
   This function is the inverse of SDSS_FLAGNAME().

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:
   splog
   yanny_free
   yanny_read

 DATA FILES:
   $IDLUTILS_DIR/data/sdss/sdssMaskbits.par

 REVISION HISTORY:
   02-Apr-2002 Written by D. Schlegel, Princeton.

(See pro/sdss/sdss_flagval.pro)


SETFITPARM.PRO

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

 AUTHOR:
	F.Bringezu, denet - Internetservice, Halle Germany,
	bringezu@denet.de

 PURPOSE:
   Provide a widget interface for creating a parinfo structure.
   This parinfo structure can by used by mpfit routines of Craig B. Markwardt.

 MAJOR TOPICS:
   Widget, mpfit.

 CALLING SEQUENCE:
   parinfo=SetFitParm(used_parinfo)

 DESCRIPTION:

   SetFitParm creates PARINFO using a widget interface.
   PARINFO provides constraints for paramters used by the mpfit routines.

   PARINFO is an array of structures, one for each parameter.

   A detailed description can be found in the documentation of mpcurvefit.pro
   This routine creates an array that contains a structure for each element.
   The structure has the following entries.

   - VALUE (DOUBLE): The starting parameter
   - FIXED (BOOLEAN): 1 fix the parameter, 0 don't fix it at the
     point given in VALUE.
   - LIMITS (DBLARRAY(2)): Set upper and lower limit.
   - LIMITED (BOOLEAN ARRAY 2):  Fix the limit.


   The parameter OLDPARINFO is optional. OLDPARINFO is used to set
   the default values in the widget.

   You can simply run:
   test=SetFitParm() to create the array for the first time.
   Once the array is created it can be used to set the default values
   in the widget by calling

   test2=SetFitParm(test)

 INPUTS:


 OPTIONAL INPUTS:

   OLDFITPARM - The default values of the new array

 INPUT KEYWORD PARAMETERS:

   PARENT - if this widget is to be a child, set this keyword to the
            parent widget ID.

 OUTPUT KEYWORD PARAMETERS:

   CANCEL - if the user selected the cancel button on the SETFITPARM
            widget, then this keyword will be set upon exit.

 OUTPUTS:
   PARINFO array of structures

 SEE ALSO:
   mpcurvefit

 MODIFICATION HISTORY:
   Written, FB, 12/1999
   Documented, FB, Jan 2000
   Generalized positioning code, CM 01 Feb 2000

(See pro/mpfit/setfitparm.pro)


SET_USE_CAPS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   set_use_caps
 PURPOSE:
   Set the bits in use_caps for a polygon such 
   that a certain list of caps are being used. Unless
   /allow_doubles is set, this routine automatically
   sets use_caps such that no two caps with use_caps
   set are identical. If /add is set, this routine 
   doesn't set use_caps to zero before proceeding. 
 CALLING SEQUENCE:
   set_use_caps,polygon,list [, /allow_doubles, add=add]
 INPUTS:
   polygon - [Npoly] polygon or polygons to alter
   list - [Nindices] list of indices to set in each polygon
 OPTIONAL INPUTS:
 OUTPUTS:
 OPTIONAL INPUT/OUTPUTS:
 COMMENTS:
  If there are two caps identical except for the sign of cm, we 
  turn off *all* the caps --- it is zero!
 EXAMPLES:
 BUGS:
   Number of caps limited to 32
 PROCEDURES CALLED:
 REVISION HISTORY:
   09-Nov-2002  Written by MRB (NYU)

(See pro/mangle/set_use_caps.pro)


SHUFFLE_INDX

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   shuffle_indx
 PURPOSE:
   yield an index to randomly rearrange an array 
 CALLING SEQUENCES:
   indx= shuffle_indx(num [, seed=, num_sub=])
 INPUTS:
   num - number of elements in an array
 OPTIONAL INPUTS:
   seed - seed to pass to randomu
   num_sub - only get the first num_sub elements of the rearranged array
 OUTPUTS:
   indx - [num] or [num_sub] index of the shuffled rearrangement
 BUGS:
 Written MRB 2003-03-02

(See pro/misc/shuffle_indx.pro)


SIGMA_PBAR_P

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

 PURPOSE:
   Annihilation cross section of pbar on p as a function of sqrt(s)
   
 CALLING SEQUENCE:
   sigma = sigma_pbar_p(E_in)

 INPUTS:
   E_in    - Input energy, default is sqrt(s) [MeV]
             if /labframe set, then total energy of pbar in p rest-frame.

 KEYWORDS:
   labframe - set to interpret energy argument as total energy of
              pbar in rest from of proton, appropriate for
              anti-proton cosmic rays.

 OUTPUTS:
   sigma    - cross section in barns.  (1 barn = 1E-24 cm^2)

 OPTIONAL OUTPUTS:
   
 RESTRICTIONS:
   If total energy is LESS than the rest mass of the two particles,
   print warnings.

 EXAMPLES:
     sig = sigma_pbar_p(sqrts)

 COMMENTS:
   Cross section formula taken from
     http://atlas.web.cern.ch/Atlas/GROUPS/SOFTWARE/OO/domains/simulation/G4PhysicsStudies/documentation/ameline/node70.html
   sqrt(s) is in MeV and corresponds to center of mass total energy
   (including rest mass of the two particles)
   s = (p1+p2)^2 where p1 and p2 are the 4-vectors (E,px,py,pz), and 
    the "square" operation uses the Minkowski metric (1,-1,-1,-1) and c=1.
   
 REVISION HISTORY:
   2006-Feb-04  Written by Douglas Finkbeiner, Princeton

(See pro/physics/sigma_pbar_p.pro)


SLATEC_BVALU

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

 PURPOSE:
   Evaluate a bspline 

 CALLING SEQUENCE:
   
    y = slatec_bvalu(x, fullbkpt, coeff, ideriv=ideriv)

 INPUTS:
   x          - Vector of positions to evaluate
   fullbkpt   - Breakpoint vector returned by SLATEC_EFC()
   coeff      - B-spline coefficients calculated by SLATEC_EFC()

 OPTIONAL KEYWORDS:
   ideriv     - Derivative to evaluate at x; default to 0

 OUTPUTS:
   y          - Evaluations corresponding to x positions

 OPTIONAL OUTPUTS:

 COMMENTS:

 EXAMPLES:

 PROCEDURES CALLED:
   Dynamic link to bvalu_idl in slatec/src/idlwrapper.c,
   which calls bvalu.f in the library "libslatecidl.so".

 REVISION HISTORY:
   15-Oct-1999  Written by Scott Burles, Chicago

(See pro/slatec/slatec_bvalu.pro)


SLATEC_EFC

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

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

 CALLING SEQUENCE:
   
   fullbkpt = slatec_efc(x, y, coeff, bkpt=bkpt, nord=nord, $
    invsig=invsig, bkspace=bkspace, nbkpts=nbkpts, everyn=everyn, /silent)

 INPUTS:
   x          - data x values
   y          - data y values

 OPTIONAL INPUTS:
   bkpt       - Breakpoint vector returned by efc (without padding)

 OPTIONAL KEYWORDS:
   nord       - Order of b-splines (default 4: cubic)
   invsig     - Inverse of sigma for weighted fit
   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
   x2         - 2nd dependent variable for 2d fitting
   npoly      - polynomial order to fit over 2nd variable, default 2


 OUTPUTS:
   coeff      - B-spline coefficients calculated by efc
   fullbkpt   - The fullbkpt vector required by evaluations with bvalu

 OPTIONAL OUTPUTS:
   bkpt       - Breakpoints without padding

 COMMENTS:
   If both bkspace and nbkpts are passed, bkspace is used.
   X values must be sorted.

 EXAMPLES:

   x = findgen(100)
   y = randomu(100,100)
   fullbkpt = slatec_efc(x, y, coeff, bkspace = 10.0)

   xfit = findgen(10)*10.0
   yfit = bvalu(xfit, fullbkpt, coeff)


 PROCEDURES CALLED:
   findbkpt()

   efc_idl in src/slatec/idlwrapper.c
         which wraps to efc.o in libslatecidl.so

 REVISION HISTORY:
   15-Oct-1999  Written by Scott Burles, Chicago

(See pro/slatec/slatec_efc.pro)


SLATEC_SPLINEFIT

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

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

 CALLING SEQUENCE:
   
   fullbkpt = slatec_splinefit(x, y, coeff, invvar=, x2=, npoly=, $
    bkpt=, fullbkpt=, maxiter=, upper=, lower=, $
    rejper=, /eachgroup, /secondkludge, $
    mask=, _EXTRA=KeywordsForEfc)

 INPUTS:
   x          - Data x values
   y          - Data y values
   bkpt       - Breakpoint vector returned by SLATEC_EFC()

 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.
   x2         - 2nd dependent variable for 2-D fitting 
   npoly      - Polynomial order to fit over 2nd variable (X2); default to 2.
   maxiter    - maximum number of iterations (default 5)
   upper      - Sigma rejection threshold for positive deviations; default to 5
   lower      - Sigma rejection threshold for negative deviations; default to 5
   rejper     - Alternative rejection algorithm, rejecting at most the
                fraction REJPER of the points per iteration (but rejecting
                at least one point if there are any bad ones).
   eachgroup  - Alternative rejection algorithm ???
   secondkludge - ???

 KEYWORDS FOR SLATEC_EFC:
   nord
   bkspace
   nbkpts
   everyn

 OUTPUTS:
   fullbkpt   - The fullbkpt vector required by evaluations with
                SLATEC_BVALU().  Return -1 if the spline fit fails
                due to all points (or all but 1) being rejected.

 OPTIONAL OUTPUTS:
   coeff      - B-spline coefficients calculated by SLATEC_EFC().
   bkpt       - Breakpoints without padding
   mask       - Mask array, set to 0 for good points and 1 for rejected points

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

 EXAMPLES:

   x = findgen(100)
   y = randomu(100,100)
   fullbkpt = slatec_splinefit(x, y, coeff, invvar=invvar, nbkpts=10)

   xfit = findgen(10)*10.0
   yfit = slatec_bvalu(xfit, fullbkpt, coeff)

 PROCEDURES CALLED:
   slatec_bvalu()
   slatec_efc()

 REVISION HISTORY:
   15-Oct-1999  Written by Scott Burles, Chicago

(See pro/slatec/slatec_splinefit.pro)


SOLVE_POLY_RATIO

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

 PURPOSE:
   Compute the polynomial function that multiplies one spectrum
   to agree with another

 CALLING SEQUENCE:
   solve_poly_ratio( xvector, aflux, bflux, aivar, [ bivar, npoly=, nback=, $
    inparams=, yfit=, ymult=, yadd=, acoeff=, totchi2=, status=, perror ] )

 INPUTS:
   xvector    - X axis from which to construct polynomial terms; this vector
                should be well-conditioned (for example, in the range [0,1])
                such that raising it to powers does not result in numeric
                overflows [NPIX]
   aflux      - Flux vector to be rescaled [NPIX]
   bflux      - Reference flux vector [NPIX]
   aivar      - Inverse variance for AFLUX [NPIX]

 OPTIONAL INPUTS:
   bivar      - Inverse variance for BFLUX [NPIX]
   npoly      - Number of polynomial terms for multiplying AFLUX; this must
                be a positive integer; default to 1
   nback      - Number of polynomial terms to add to AFLUX
   inparams   - Starting guess for polynomial + additive terms if the
                second method is used (specifying AIVAR,BIVAR) [NPOLY+NBACK];
                if not set, then a fit is first performed without
                allowing the errors AIVAR to be rescaled with the flux
   status     - Return value from MPFIT if using the 2nd fit method
   perror     - Return value from MPFIT if using the 2nd fit method

 OUTPUTS:
   yfit       - Rescaled AFLUX with additive, background terms:
                AFLUX * SUM{i=0,NPOLY-1} XVECTOR^i + SUM{j=0,NBACK-1} XVECTOR^j

 OPTIONAL OUTPUTS:
   ymult      - Final multiplicative polynomial [NPIX]
   yadd       - Final addditive polynomial [NPIX]
   acoeff     - All coefficicents, starting with the multiplicative
                [NMULT+NBACK]
   totchi2    - Total chi^2

 COMMENTS:
   Fit for the polynomial vector multiplying one vector to agree
   with another such that
     BFLUX = polynomial * AFLUX + background

   The polynomials are defined such that:
      YFIT = YMULT * AFLUX + YADD

   There are two modes of operation for this routine.
   The simpler algorithm is if AIVAR is specified but not BIVAR.
   One is minimzing the sum of the squares of the chi values:
     chi = (BFLUX - polynomial * AFLUX - background) * sqrt(AIVAR)
   That is a linear problem that we solve with SVD.

   The second algorithm has an error associates with each input vector.
   The problem is now nonlinear, because BIVAR is rescaled appropriately
   with BFLUX.  The errors are the quadrature sum from AIVAR and the
   rescaled BIVAR.
   The errors are rescaled at every function evaluation, but we
   only allow the errors to get smaller by up to a factor of 1e4,
   and we only allow them to get larger slowly (as the square root).
   This should very strongly constrain the flux-corrrection vectors
   from going too small (or negative), or too large.

 EXAMPLES:

 BUGS:

 DATA FILES:

 PROCEDURES CALLED:
   mpfit()

 INTERNAL SUPPORT ROUTINES:
   solve_poly_fn()
   solve_poly_chi_fn()
   solve_poly_vectors()
   solve_poly_ratio2()
   solve_poly_ratio1()

 REVISION HISTORY:
   05-Feb-2004  Written by D. Schlegel, Princeton

(See pro/math/solve_poly_ratio.pro)


SORTINPLACE

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

 PURPOSE:
   Sort an array in-place, without making a second copy of the data

 CALLING SEQUENCE:
   sortinplace, a, isort

 INPUTS:
   a          - Array of any data type
   isort      - Indices for sorting the A array, such as an index
                list returned by the SORT() function

 OPTIONAL INPUTS:

 OUTPUTS:
   a          - (Modified)

 OPTIONAL OUTPUTS:

 COMMENTS:
   This routine is particularly useful when sorting in-place a large
   array of structures.  More simply, one would execute
      a = a[isort]
   but the above command makes a second copy of the array "a".

 EXAMPLES:

 BUGS:
   The index list ISORT must be a unique list of indices into
   the array A, with no duplicate entries and no out-of-bounds
   values (such as -1).

 DATA FILES:

 PROCEDURES CALLED:

 INTERNAL SUPPORT ROUTINES:

 REVISION HISTORY:
   29-May-2004  Written by D. Schlegel, Princeton

(See pro/misc/sortinplace.pro)


SPHEREGROUP

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

 PURPOSE:
   Perform friends-of-friends grouping given ra/dec type coords 

 CALLING SEQUENCE:
   ingroup = spheregroup( ra, dec, linklength, [chunksize=], $
     [multgroup=], [firstgroup=], [nextgroup=] )

 INPUTS:
   ra         - ra coordinates in degrees (N-dimensional array)
   dec        - dec coordinates in degrees (N-dimensional array)
   linklength - linking length for groups (degrees)

 OPTIONAL INPUTS:
   chunksize  - the algorithm breaks the sphere up into a bunch of
                regions with a characteristic size chunksize
                (degrees). By default this is max(1.,4*linklength)

 OUTPUTS:
   ingroup    - group number of each object (N-dimensional array);
                -1 if no groups

 OPTIONAL INPUT/OUTPUTS:
   multgroup  - multiplicity of each group 
   firstgroup - first member of each group 
   nextgroup  - index of next member of group for each object

 COMMENTS:
   The code breaks the survey region into chunks which overlap by
   about linklength. Friends-of-friends is run on each chunk
   separately. Finally, the bookkeeping is done to combine the
   results (i.e. joining groups across chunk boundaries). This should
   scale as area*density^2, 

   It is important that chunksize is >=4.*linklength, and this is
   enforced.

   firstgroup and nextgroup form a primitive "linked list", which 
   can be used to step through a particular group, as in the example 
   below.

 EXAMPLES:
   Group a set of points on a scale of 55'', then step through
   members of the third group:

   > ingroup=spheregroup(ra,dec,.0152778,multgroup=mult, $
   > firstgroup=first, nextgroup=next)
   > indx=firstgroup[2]
   > for i = 0, multgroup[2] do begin & $
   > print,ra[indx],dec[indx] & $
   > indx=nextgroup[indx]  & $
   > end

   Of course, you could just "print,ra[where(ingroup eq 2)]", but I
   wanted to demostrate how the linked list worked.

 BUGS:
   Behavior at poles not well tested.

 PROCEDURES CALLED:
   Dynamic link to spheregroup.c

 REVISION HISTORY:
   19-Jul-2001  Written by Mike Blanton, Fermiland

(See pro/spheregroup/spheregroup.pro)


SPHEREMATCH

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

 PURPOSE:
   Take two sets of ra/dec coords and efficiently match them. It 
   returns all matches between the sets of objects, and the distances
   between the objects. The matches are returned sorted by increasing
   distance. A parameter "maxmatch" can be set to the number of matches 
   returned for each object in either list. Thus, maxmatch=1 (the default)
   returns the closest possible set of matches. maxmatch=0 means to
   return all matches

 CALLING SEQUENCE:
   spherematch, ra1, dec1, ra2, dec2, matchlength, match1, match2, $
     		       distance12, [maxmatch=maxmatch]

 INPUTS:
   ra1         - ra coordinates in degrees (N-dimensional array)
   dec1        - dec coordinates in degrees (N-dimensional array)
   ra2         - ra coordinates in degrees (N-dimensional array)
   dec2        - dec coordinates in degrees (N-dimensional array)
   matchlength - distance which defines a match (degrees)

 OPTIONAL INPUTS:
   maxmatch    - Return only maxmatch matches for each object, at
                 most. Defaults to maxmatch=1 (only the closest
                 match for each object). maxmatch=0 returns all
                 matches.

 OUTPUTS:
   match1     - List of indices of matches in list 1; -1 if no matches
   match2     - List of indices of matches in list 2; -1 if no matches
   distance12 - Distance of matches; 0 if no matches

 OPTIONAL OUTPUTS:

 COMMENTS:
   The code breaks the survey region into chunks of size
   4*matchlength. Matches are then performed by considering only 
   objects in a given chunk and neighboring chunks. This makes the
   code fast.

   The matches are returned sorted by distance.

 EXAMPLES:

 BUGS:
   Behavior at poles not well tested.

 PROCEDURES CALLED:
   Dynamic link to spherematch.c

 REVISION HISTORY:
   20-Jul-2001  Written by Mike Blanton, Fermiland

(See pro/spheregroup/spherematch.pro)


SPLOG

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

 PURPOSE:
   Logging routine for writing to standard output and/or a log file.

 CALLING SEQUENCE:
   splog, v1, v2 ..., [, _EXTRA=extra, /noname, prelog=, filename=, $
    /append, /close, /no_stdout ]

 INPUTS:
   v1, v2 ... - The expressions to be passed to PRINT or PRINTF

 OPTIONAL KEYWORDS:
   _EXTRA     - Any keywords for PRINT or PRINTF, such as FORMAT
   noname     - If set, then suppress printing name of calling routine
   prelog     - If set, then print this string immediately after the
                name of the calling routine on each line, i.e. 'b1'
   filename   - If specified, then open this file for text output
   append     - If set at the same time as FILENAME, then append to this file;
                default is to overwrite file
   close      - If set, then close the output file
   no_stdout  - If set, then do not print anything to the standard output.

 OUTPUTS:

 OPTIONAL OUTPUTS:

 COMMENTS:
   The output is formatted just like with the IDL PRINT command, except
   that extraneous whitespace is removed from non-STRING elements unless
   a FORMAT keyword is used.

 EXAMPLES:
   Open a file for text output, write to it, then close it:
     splog, filename='test.log'
     splog, 'This is a test', 123.4, format='(a,f8.2)'
     splog, /close
   Alternatively, this can all be done on one line
     splog, filename='test.log', /close, $
      'This is a test', 123.4, format='(a,f8.2)'

 BUGS:

 PROCEDURES CALLED:

 REVISION HISTORY:
   17-Nov-1999  Written by D. Schlegel, Princeton

(See pro/misc/splog.pro)


SPLOT

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

 PURPOSE:
   Interactive plotting tool for 1-D (spectral) data.

 CALLING SEQUENCE:
   splot, [x], y, $
    [color=, psym=, symsize=, thick=, xoffset=, yoffset= ]

   soplot, [x], y, [/autoscale], $
    [color=, psym=, symsize=, thick= ]

   sxyouts, x, y, string, [alignment=, charsize=, charthick=, color=, $
    font=, orientation= ]

   spolyfill, x, y, [ color=, fill=0, /image_interp, /line_fill, pattern=, $
    spacing= ]

   serase, [nerase, /norefresh]

 INPUTS:

 OUTPUT:

 COMMENTS:
   This code is based upon Aaron Barth's ATV procedure.

 EXAMPLES:

 BUGS:
   Doesn't use the passed XRANGE, YRANGE properly yet...
   Move around widgets to be more compact above plotting window.
   Write splot_readfits.
   Make POSITION= changeable based upon CHARSIZE.
   Gaussian fitting or integrated gaussian fitting.
   Allow one to step through an image row at a time? Or link to ATV?
   Use the WCS in splot_gettrack.
   Add widget button option to fix Y range or let it float, or fix YMIN=0.
   Include options for plotting contours, etc?
   Options for XLOG, YLOG
   For FITS files, take XTITLE, YTITLE from header
   Option to pass header as param in SPLOT

 PROCEDURES CALLED:
   fits_read

 INTERNAL SUPPORT ROUTINES:
   splot_gausspix
   splot_startup
   splot_clearkeylist
   splot_displayall
   splot_readfits
   splot_writeeps
   splot_cleartext
   splot_zoom
   splot_gettrack
   splot_event
   splot_shutdown
   splot_resize
   splot_icolor()
   splot_setheader
   splot_headinfo
   splot_headinfo_event
   splot_plot1plot
   splot_plot1poly
   splot_plot1text
   splot_plotwindow
   splot_plotall
   spolyfill
   sxyouts
   splot_move_cursor
   splot_set_minmax
   splot_get_minmax
   splot_refresh
   splot_help
   splot_help_event
   splot_plotparam_refresh
   splot_plotparam
   splot_plotparam_event
   serase
   splot_autoscale
   soplot
   splot

 REVISION HISTORY:
   28-Sep-1999  Written by David Schlegel, Princeton.
   19-Jun-2001  Gaussfit amplitude was wrong - fixed - D. Finkbeiner
   27-May-2004  add plugin keyword for coordinate plugins - D. Finkbeiner

(See pro/plot/splot.pro)


SQUAREPHOT

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

 PURPOSE:
   Simple (square) aperature photometry.

 COMMENTS:
   This routine has all the same calling arguments as DJS_PHOT(), but
   does not use most of them.  The sky is computed as the median of the
   entire image.  The flux is computed from square aperatures.  Nothing
   else is computed.  This proc is basically for testing purposes.

 CALLING SEQUENCE:
   03-Jun-2000  Written by D. Schlegel, Princeton.

(See pro/djsphot/squarephot.pro)


SSHIFT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	sshift
 PURPOSE: (one line)
	Shift data using a damped sinc function for fractional part.
 DESCRIPTION:

	This function will shift an array of data pointed to by x and
	extending for n points.  The amount of the shift is given by shift.
	The result of the operation is placed at xp.  A shift that is within
	0.0001 of a whole number is treated to be that of the whole number.  If
	the shift is by an integral number of pixels then the shift involves
	reindexing the data, no interpolation is done.  If the shift is some
	non-integral amount then the data is resampled using a damped sinc
	function.

	The sense of the shift is as follows: think of the array plotted on a
	fixed scale.  A shift of 1 corresponds to shifting the data by one data
	point to the right relative to the fixed scale, ie. x[3]=xp[4].

	The data will fall off one end or another of the output vector as a
	result of the shift.  However, this is not as significant as the edge
	effect, the convolution is not complete for any data point within 10
	points of the edge, so those points cannot be trusted.  The missing
	points in the convolution are assumed to be equal to the end points.

 CATEGORY:
       Numerical
 CALLING SEQUENCE:
	xp = sshift(x,shift)
 INPUTS:
	x     - Input data array to be shifted.
	shift - Amount to shift (negative to left).
 OPTIONAL INPUT PARAMETERS:
 KEYWORD PARAMETERS:
 OUTPUTS:
	Return value is the shifted array.
 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
	The input and output arrays cannot be the same.
 PROCEDURE:
 MODIFICATION HISTORY:
	Adapted from Zodiac routine: shiftc/sshift
	  Marc W. Buie, Lowell Observatory, 1992 October 2

(See pro/math/sshift.pro)


SSHIFT2D

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
    sshift2d
 PURPOSE: (one line)
    Shift a 2-D array using a damped sinc function for the fractional part.
 DESCRIPTION:

 CATEGORY:
    Mathematical
 CALLING SEQUENCE:
    result = sshift2d( array, shiftvec )
 INPUTS:
    array    : Array to be shifted.
    shiftvec : Vector of two elements: [ xshift, yshift ].
 OPTIONAL INPUT PARAMETERS:

 KEYWORD PARAMETERS:

 OUTPUTS:
    The shifted array is returned as the function value.
 COMMON BLOCKS:

 SIDE EFFECTS:

 RESTRICTIONS:

 PROCEDURE:

 MODIFICATION HISTORY:
    February, 1993:
    Copied from "sincshift.pro" written by John Spencer, Lowell Observatory.
    Very minor modifications by Doug Loucks, Lowell Observatory.

(See pro/math/sshift2d.pro)


SSHIFTROTATE

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

 PURPOSE:
   Routine to sinc-shift and rotate a 2-D image, but preserving scale.

 CALLING SEQUENCE:
   newimg =  sshiftrotate( image, [ theta, xshift=, yshift=, xcen=, ycen=, $
    /bigger, xoffset=, yoffset= ]

 INPUTS:
   image      - Image (2-dimensional)

 OPTIONAL KEYWORDS:
   theta      - Rotate image counter-clockwise this angle [degrees] about
                the 0-indexed point XCEN,YCEN; default to 0 degrees
   xshift    - Shift in X direction
   yshift    - Shift in Y direction
   xcen       - Center X position for rotation; default to the center of
                the image
   ycen       - Center Y position for rotation; default to the center of
                the image
   bigger     - If set, then keep the bigger image necessary for containing
                the shifted + rotated image.

 OUTPUTS:
   newimg     - Rotated and shifted image

 OPTIONAL OUTPUTS:
   xoffset    - If /BIGGER is set, then this contains the integer pixel
                offset in the X direction of the enlarged image.
   yoffset    - If /BIGGER is set, then this contains the integer pixel
                offset in the Y direction of the enlarged image.

 COMMENTS:
   When both a shifT (XSHIFT,YSHIFT) and a rotation (THETA) are specified,
   the resulting image is as if the shift is performed first, and the
   rotation second.

 EXAMPLES:
   Generate a random image and rotate by 30 degrees:
     IDL> image = smooth(randomu(1234,200,200),5)
     IDL> newimg = sshiftrotate(image,30)

 BUGS:
   The sinc shifts need not do all pixels in each row each time, only
     the "active" area!???  This will just be for a speed improvement.
   Special-case rotations of 0,90,180,270 !???
   Optionally return a mask of the illuminated region???
   Optionally fill in missing regions with some value???
   Allow double-precision for the image, or for the arithmatic???

 PROCEDURES CALLED:
   cirrange
   sshift()

 REVISION HISTORY:
   18-Sep-2002  Written by D. Schlegel, Princeton

(See pro/math/sshiftrotate.pro)


STRING2RADEC

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

 PURPOSE:
   Convert hours, min, sec + deg, min, sec to ra dec in floating degrees

 CALLING SEQUENCE:
   string2radec, rahour, ramin, rasec, decdeg, decmin, decsec, ra, dec 
 INPUTS:
   rahour - hours in ra (string)
   ramin - minutes in ra (string)
   rasec - seconds in ra (string)
   decdeg - degrees in dec (string) 
   decmin - arcminutes in dec (string)
   decsec - arcseconds in dec (string)
 OUTPUTS:
   ra - ra in degrees
   dec - dec in degrees
 COMMENTS:
   The sign in dec is set by the sign in "decdeg", so that you need
   to propagate the negative in "-00" to the whole expression

 BUGS:

 PROCEDURES CALLED:

 REVISION HISTORY:
   18-Nov-2003  Michael Blanton, NYU

(See pro/misc/string2radec.pro)


STRIPE_TO_ETA

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

 PURPOSE:
   Convert from SDSS great circle coordinates to equatorial coordinates.

 CALLING SEQUENCE:
   eta = stripe_to_eta(stripe)

 INPUTS:
   stripe     - Stripe number for SDSS coordinate system.  If specified,
                the NODE,INCL are ignored; scalar or array.

 OPTIONAL INPUTS:

 OUTPUTS:
   eta        - Eta in SDSS (lambda,eta) coordinate system (degrees);
                scalar or array with same dimensions as STRIPE.

 OPTIONAL OUTPUTS:

 COMMENTS:

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:

 REVISION HISTORY:
   20-Feb-2002  Written by M. Blanton, NYU
   03-Oct-2002  Modified by David Schlegel, Princeton.

(See pro/coord/stripe_to_eta.pro)


STRIPE_TO_INCL

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

 PURPOSE:
   Convert from SDSS stripe number to an inclination relative to the equator.

 CALLING SEQUENCE:
   inc = stripe_to_incl(stripe)

 INPUTS:
   stripe     - Stripe number for SDSS coordinate system.  If specified,
                the NODE,INCL are ignored; scalar or array.

 OPTIONAL INPUTS:

 OUTPUTS:
   incl       - Inclination of great circle relative to the J2000
                celestial equator (degrees); scalar or array with same
                dimensions as STRIPE.

 OPTIONAL OUTPUTS:

 COMMENTS:

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:
   stripe_to_eta()

 REVISION HISTORY:
   20-Feb-2002  Written by M. Blanton, NYU
   03-Oct-2002  Modified by David Schlegel, Princeton.

(See pro/coord/stripe_to_incl.pro)


STRUCT_ADDTAGS

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

 PURPOSE:
   Add tags from one structure (array) to another

 CALLING SEQUENCE:
   outstruct = struct_addtags(astruct, bstruct)

 INPUTS:
   astruct    - First structure, which can be an array
   bstruct    - Second structure, which can be an array

 OPTIONAL INPUTS:

 OUTPUTS:
   outstruct  - Ouput structure array

 OPTIONAL OUTPUTS:

 COMMENTS:
   The dimensions of the output array match that of ASTRUCT.  For example,
   if ASTRUCT has dimensions [5,10], and BSTRUCT has dimensions [2,25],
   the output structure has dimensions [5,10].

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:
   copy_struct
   copy_struct_inx

 REVISION HISTORY:
   28-Jun-2000  Written by D. Schlegel, Princeton

(See pro/misc/struct_addtags.pro)


STRUCT_APPEND

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

 PURPOSE:
   Append more array elements to a structure.

 CALLING SEQUENCE:
   outstruct = struct_append( struct1, struct2, [ /force ] )

 INPUTS:
   struct1    - First structure; the output structure will match the tags
                in this, and match the name if it's a named structure.
   struct2    - Second structure to append to the first.

 OPTIONAL INPUTS:
   force      - If set, then append these two structures, even if one or
                both are arrays of zeros rather than actual structures.

 OUTPUTS:

 OPTIONAL OUTPUTS:

 COMMENTS:
   If either structure is undefined are set to zero, then return the other
   one only.  If one of the structures is defined (and non-zero), but not
   a structure, then a blank structure is put in its place.

 EXAMPLES:
   > a={one:1,two:2}
   > b={one:11,three:33}
   > print,struct_append(a,b)
     {       1       2}{      11       0}

 BUGS:

 PROCEDURES CALLED:
   headfits()

 REVISION HISTORY:
   26-Jun-2000  Written by David Schlegel, Princeton.

(See pro/misc/struct_append.pro)


STRUCT_PRINT

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

 PURPOSE:
   Formatted print of a structure to standard out, a file, or an array.

 CALLING SEQUENCE:
   struct_print, struct, [ lun=, filename=, tarray=, /no_head, /html, $
    fdigit=, ddigit=, alias=, formatcodes= ]

 INPUTS:
   struct     - Structure

 OPTIONAL INPUTS:
   filename   - Output file name; open and close this file
   lun        - LUN number for an output file if one is already open
                (overrides FILENAME)
   no_head    - Do not print the header lines that label the columns,
                and do not increase the width of a column to occomodate
                the column name.
   html       - If set, then output as an HTML table
   fdigit     - Number of digits for type FLOAT numbers; default to 5.
   ddigit     - Number of digits for type DOUBLE numbers; default to 7.
   alias      - Set up aliases to convert from the IDL structure
                to the FITS column name.  The value should be
                a STRARR(2,*) value where the first element of
                each pair of values corresponds to a column
                in the structure and the second is the name
                to be used in the FITS file.
                The order of the alias keyword is compatible with
                use in MWRFITS,MRDFITS.
   formatcodes- Explicit format codes for specific structure elements.
                The value should be a STRARR(2,*) value where teh first
                element of each pair of values corresponds to a column
                name (before applying any ALIAS), and the second is the
                format code, such as "a10" for a 10-character string,
                or "f10.5" for a floating-point value with 5 places after
                the decimal point.  Note that this may truncate the
                names in the two-line header if the format is fewer
                characters than that name length.

 OUTPUTS:

 OPTIONAL OUTPUTS:
   tarray     - String array for output

 COMMENTS:
   If neither FILENAME or LUN is set and TARRAY is not returned,
   then write to the standard output.

 EXAMPLES:

 BUGS:
   If FORMATCODES is used, then it is possible to have numeric values
   that do not fit within the specified format, which are then printed
   as asterisks.  For example, printing the value 123.4 with the format
   code "f3.1" will result in printing "***".

 PROCEDURES CALLED:

 INTERNAL SUPPORT ROUTINES:
   struct_checktype()

 REVISION HISTORY:
   01-Nov-2000  Written by David Schlegel, Princeton.

(See pro/misc/struct_print.pro)


STRUCT_SELECTTAGS

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

 PURPOSE:
   Trim a structure to a specified list of tags using SELECT and EXCEPT

 CALLING SEQUENCE:
   outstruct = struct_selecttags(tdat, [ select_tags=, except_tags= ])

 INPUTS:
   tdat       - Input structure, which can be an array

 OPTIONAL INPUTS:
   except_tags- Option string array of column names to not return.
                This can include wildcards.
                Set to ' ' to not exclude any tags.
   select_tags- Option string array of column names to return, which
                takes priority over EXCEPT_TAGS.
                This can include wildcards.

 OUTPUTS:
   outstruct  - Ouput structure array

 OPTIONAL OUTPUTS:

 COMMENTS:

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:

 REVISION HISTORY:
   11-Nov-2003  Written by D. Schlegel, Princeton, broken out of SDSS_READOBJ

(See pro/misc/struct_selecttags.pro)


STRUCT_TRIMTAGS

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

 PURPOSE:
   Trim a structure to a list of selected and/or excluded tags

 CALLING SEQUENCE:
   outstruct = struct_trimtags(instruct, [ select_tags=, except_tags=, $
    format= ]

 INPUTS:
   instruct   - Input structure, which can be an array

 OPTIONAL INPUTS:
   select_tags- List of tag names to include; this can use wildcards.
   except_tags- List of tag names to exclude; this can use wildcards.
   format     - If set, then convert all tags to strings using this
                array of format codes (one per output tag).  These format
                codes should not include parentheses.  For example,
                they could be ['f7.2','a'].

 OUTPUTS:
   outstruct  - Ouput structure array

 OPTIONAL OUTPUTS:

 COMMENTS:
   The selection based upon SELECT_TAGS is performed before excluding
   tags based upon EXCEPT_TAGS.  The order of the tags in the output
   structure is the same as the order set by SELECT_TAGS, which allows
   one to re-order the tags in a structure.

 EXAMPLES:

 BUGS:
   No checks are done to assure that tags are not selected multiple
   times (which will crash this code).
   No checks are done that FORMAT has the correct number of elements,
   which could also crash this code.

 PROCEDURES CALLED:
   copy_struct
   copy_struct_inx

 REVISION HISTORY:
   05-Jun-2002  Written by D. Schlegel, Princeton

(See pro/misc/struct_trimtags.pro)


STR_SEP

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

 PURPOSE:
    This routine cuts a string into pieces which are separated by the 
    separator string.
 CATEGORY:
    String processing.
 CALLING SEQUENCE:
    arr = STR_SEP(str, separator)

 INPUTS:
    str - The string to be separated.
    separator - The separator.

 KEYWORDS:
    ESC = escape character.  Only valid if separator is a single character.
		Characters following the escape character are treated
		literally and not interpreted as separators.
		For example, if the separator is a comma,
		and the escape character is a backslash, the character
		sequence 'a\,b' is a single field containing the characters
		'a,b'.
    REMOVE_ALL = if set, remove all blanks from fields.
    TRIM = if set, remove only leading and trailing blanks from fields.

 OUTPUT: 
    An array of strings as function value.

 COMMON BLOCKS:
    None

 SIDE EFFECTS:
    No known side effects.

 RESTRICTIONS:
    None.

 EXAMPLE:
    array = STR_SEP ("ulib.usca.test", ".")

 MODIFICATION HISTORY:
	July 1992, AH,	CreaSo		Created.
	December, 1994, DMS, RSI	Added TRIM and REMOVE_ALL.

(See pro/TeXtoIDL/str_sep.pro)


SXASCII_READ

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

 PURPOSE:

 CALLING SEQUENCE:
   sxascii_read, filename, [ pstr, hdr=hdr]

 INPUTS:
   filename   - Input file name for Yanny parameter file

 OPTIONAL INPUTS:

 OUTPUT:

 OPTIONAL OUTPUTS:
   pstr       - Only one structure can be returned
   hdr        - hdr will include the query

 COMMENTS:
   Return 0's if the file does not exist.

   Read and write variables that are denoted INT in the Yanny file
   as IDL-type LONG, and LONG as IDL-type LONG64.  This is because
   Yanny files assume type INT is a 4-byte integer, whereas in IDL
   that type is only 2-byte.

 EXAMPLES:

 BUGS:
   Not set up yet to deal with multi-dimensional arrays.

   Not yet tested with char?

 PROCEDURES CALLED:
   needs to compile yanny_read.pro to run

 INTERNAL SUPPORT ROUTINES:

 REVISION HISTORY:
   16-May-2001  Written by S Burles, FNAL
   18-Jun-2002  Revisions (better or worse?)

(See pro/yanny/sxascii_read.pro)


SXCOMBINEPAR

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

 PURPOSE:
   Combine values of specified header cards from many FITS headers.

 CALLING SEQUENCE:
   sxcombinepar, hdrarr, cardname, outhdr, [ func=, weights=, /zeros, $
    outcard=, _EXTRA=KeywordsForSxaddpar ]

 INPUTS:
   hdrarr     - Array of pointers to FITS headers
   cardname   - Name(s) of header cards to average
   outhdr     - Output header

 OPTIONAL KEYWORDS:
   func       - Function to apply:
                  'average'
                  'median'
                  'min'
                  'max'
                  'total'
                Default to 'average'
   weights    - If set, then weight each of the input headers by these weights;
                only applicable when the function type is 'average'.
   zeros      - If set, then include zero values when determining the
                average or other function.  But never use the zeros
                returned by SXPAR() if a header is missing that card
                altogether.
   outcard    - Card name(s) in output header; if not specified, then use
                the same name as in CARDNAME.
   _EXTRA     - Optional keywords for SXADDPAR (such as BEFORE,AFTER,FORMAT).

 OUTPUTS:
   outhdr     - (Modified.)

 COMMENTS:

 BUGS:

 PROCEDURES CALLED:
   sxaddpar
   sxpar()

 REVISION HISTORY:
   31-Jan-2002  Written by D. Schlegel, Princeton

(See pro/fits/sxcombinepar.pro)


SYSVARS

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

 PURPOSE:
   store IDL system variables in a structure for later restoration 

 CALLING SEQUENCE:
   state = sysvars(print=print, X=X)

 KEYWORDS:
   print  - set default Postscript settings
   X      - set default X settings

 OUTPUTS:
   state  - structure containing previous values of !p,!d,!x,!y,!z

 EXAMPLES:
   state = sysvars(/print)
     <code to print stuff>
   restore_sysvars, state

 COMMENTS:
   Use restore_sysvars to restore !{p,x,y,z}.  !d is a readonly, but
   is carried along for the ride. 

 REVISION HISTORY:
   2001-Aug-06  Written by Douglas Finkbeiner, Princeton

(See pro/plot/sysvars.pro)


TAG_INDX

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   tag_indx
 PURPOSE:
   Returns the column number of the given tag to the given structure
   (-1 if none)
 CALLING SEQUENCE:
   indx=tag_indx(struct,name)   
 INPUTS:
   struct - a structure
   name - name of tag to search for
 OPTIONAL INPUTS:
 OUTPUTS:
 OPTIONAL INPUT/OUTPUTS:
 COMMENTS:
 EXAMPLES:
 BUGS:
 PROCEDURES CALLED:
 REVISION HISTORY:
   06-Sep-2002  Written by Mike Blanton, NYU

(See pro/misc/tag_indx.pro)


TAI2AIRMASS

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

 PURPOSE:
   Compute airmass.

 CALLING SEQUENCE:
   airmass = tai2airmass( ra, dec, [ equinox, jd=, tai=, mjd=, $
    longitude=, latitude=, altitude=, ha=, ipa= ] )

 INPUTS:
   ra             - Right ascension [degrees]
   dec            - Declination [degrees]
   equinox        - Equinox of observation for RA, DEC; default to 2000.

 OPTIONAL KEYWORDS:
   jd             - Decimal Julian date.  Note this should probably be
                    type DOUBLE.
   tai            - Number of seconds since Nov 17 1858
                    Note this should probably either be type DOUBLE or LONG64.
   mjd            - Modified Julian date.
   longitude      - Longitude of observatory;
                    default to (360-105.820417) deg for APO
   latitute       - Latitude of observatory; default to 32.780361 deg for APO
   altitude       - Altitude of observatory; default to 2788 m for APO
   node           - Node of great circle on the sky (degrees); required
                    if returning IPA.
   incl           - Inclination of great circle on the sky (degrees); required
                    if returning IPA.

 OUTPUTS:
   airmass        - Airmass; 1.0 for zenith

 OPTIONAL OUTPUTS:
   ha             - Hour angle (degrees)
   ipa            - Position angle for image rotator (degrees)

 COMMENTS:
   TAI, JD, or MJD must be specified.

   This routine only returns sec(z) for the airmass.
   Formula from Smart, Spherical Astronomy.

 EXAMPLES:

 BUGS:
   Outputs SLIGHTLY different airmasses from those computed by the PT
     system.  We think that they may be going to second order.
   EQUINOX does nothing except for the IPA calculation!
   ALTITUDE is unused!

 PROCEDURES CALLED:
   ct2lst
   ll2uv()
   precess

 REVISION HISTORY:
   10-May-2000  Written by D. Schlegel, Princeton, & D. Hogg, IAS
   02-Jun-2000  Fixed minor bugs, Schlegel
   05-Nov-2000  Added HA keyword

(See pro/coord/tai2airmass.pro)


TEXTOIDL[1]

[Previous Routine] [Next Routine] [List of Routines]
 SPECIAL NOTE: 
       The file textoidl_trans_sub_super.pro contains two functions,
       textoidl_trans_sub_super, and textoidl_sub_sup.  The former is the
       generic routine for processing TeX sub/superscripts, the
       latter is used only by textoidl_trans_sub_super and has no general
       utility.  Hence it lives here.  You will see documentation for
       textoidl_trans_sub_super second if you use DOC_LIBRARY.

(See pro/TeXtoIDL/textoidl.pro)


TEXTOIDL[2]

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       TEXTOIDL
 PURPOSE:
       Convert a valid TeX string to a valid IDL string for plot labels.
 CATEGORY:
       text/strings
 CALLING SEQUENCE:
       new = textoidl(old)
 INPUTS:
       old            -- TeX string to be converted.  Will not be     in
                         modified.  old may be a string array.
 KEYWORD PARAMETERS:
       FONT           -- Set to 0 to use hardware font, -1 to use 
                         vector.  Note that the only hardware font 
                         supported is PostScript.
       /TEX_SEQUENCES -- return the available TeX sequences
       /HELP          -- print out info on use of the function
                         and exit.
 OUTPUTS:
       new            -- IDL string corresponding to old.             out
 COMMON BLOCKS:
 SIDE EFFECTS:
 NOTES:
       - Use the procedure SHOWTEX to get a list of the available TeX
         control sequences.  
       - The only hardware font for which translation is available is
         PostScript. 
       - The only device for which hardware font'
         translation is available is PostScript.'
       - The FONT keyword overrides the font selected'
         by !p.font'
 EXAMPLE:
       out = TeXtoIDL('\Gamma^2 + 5N_{ed}')
       The string out may be used in XYOUTS or other IDL text
       display routines.  It will be an uppercase Gamma, with an
       exponent of 2, then a plus sign, then an N with the subscript
       ed.
 MODIFICATION HISTORY:
       $Id: textoidl.pro,v 1.8 2004/07/19 16:48:04 schlegel Exp $
       $Log: textoidl.pro,v $
       Revision 1.8  2004/07/19 16:48:04  schlegel
       Replace calls to the obsolete function RSTRPOS() with STRPOS(/REVERSE_SEARCH).

       Revision 1.7  2000/11/20 02:27:24  dfink
       Added \AA option for Anstroms

       Revision 1.6  2000/07/12 14:31:33  hogg
       fixed another ()/[] bug.

       Revision 1.5  2000/06/15 18:21:23  hogg
       fixed tiny () -> [] bugs

       Revision 1.4  2000/06/03 17:12:42  dfink
       Fink's new textoidl - all procedures in one file; avoid name conflict

       Revision 1.4  1996/06/14 20:00:27  mcraig
       Updated Copyright info.

       Revision 1.3  1996/05/09 00:22:17  mcraig
       Added error handling, cleaned up documentation.

       Revision 1.2  1996/02/08 18:52:50  mcraig
       Added ability to use hardware fonts for PostScript device.

       Revision 1.1  1996/01/31 18:47:37  mcraig
       Initial revision

 RELEASE:
       $Name: v5_1_3 $

 COPYRIGHT:
  Copyright (C) 1996 The Regents of the University of California, All
  Rights Reserved.  Written by Matthew W. Craig.
  See the file COPYRIGHT for restrictions on distrubting this code.
  This code comes with absolutely NO warranty; see DISCLAIMER for details.

(See pro/TeXtoIDL/textoidl.pro)


TEXTOIDL_MATCHDELIM

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       TEXTOIDL_MATCHDELIM
 PURPOSE:
        Match open/close delimiters in a string.
 CATEGORY:
        text/strings
 CALLING SEQUENCE:
        position = textoidl_matchdelim( strn, [openpos])
 INPUTS:
        strn        -- a string containing an open                 in
                       delimiter (e.g. '{') in which you 
                       want to find the matching closing  
                       delimiter (e.g. '}')
 KEYWORD PARAMETERS:
        OPEN_DELIM  -- A single character containing the opening   in
                       delimiter (e.g. '(').  Default is '{'
        CLOSE_DELIM -- A single character containing the closing   in
                       delimiter (e.g. ')').  Default is '}'
 OUTPUTS:
        position -- returns the position in strn of the            out
                    closing delimiter, -1 if no closing found.
        openpos  -- Set to a named variable to receive the         out
                    position of the first opening delimiter.
                    Optional.
 COMMON BLOCKS:
 SIDE EFFECTS:
 NOTES:
        - Any pair of (nonidentical) characters can be used as
          delimiters. 
 EXAMPLE:
        textoidl_matchdelim('{one{two}}three') returns 9, the character just
        before 'three'.  
 MODIFICATION HISTORY:
       $Id: textoidl.pro,v 1.8 2004/07/19 16:48:04 schlegel Exp $
       $Log: textoidl.pro,v $
       Revision 1.8  2004/07/19 16:48:04  schlegel
       Replace calls to the obsolete function RSTRPOS() with STRPOS(/REVERSE_SEARCH).

       Revision 1.7  2000/11/20 02:27:24  dfink
       Added \AA option for Anstroms

       Revision 1.6  2000/07/12 14:31:33  hogg
       fixed another ()/[] bug.

       Revision 1.5  2000/06/15 18:21:23  hogg
       fixed tiny () -> [] bugs

       Revision 1.4  2000/06/03 17:12:42  dfink
       Fink's new textoidl - all procedures in one file; avoid name conflict

       Revision 1.3  1996/06/14 20:00:27  mcraig
       Updated Copyright info.

       Revision 1.2  1996/05/09 00:22:17  mcraig
       Removed restriction that open delim must be first char.  Added argument
       to allow for return of position of open delim.

       Revision 1.1  1996/01/31 18:41:06  mcraig
       Initial revision

 RELEASE:
       $Name: v5_1_3 $

 COPYRIGHT:
  Copyright (C) 1996 The Regents of the University of California, All
  Rights Reserved.  Written by Matthew W. Craig.
  See the file COPYRIGHT for restrictions on distrubting this code.
  This code comes with absolutely NO warranty; see DISCLAIMER for details.

(See pro/TeXtoIDL/textoidl.pro)


TEXTOIDL_NEXTTOK

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       TEXTOIDL_NEXTTOK
 PURPOSE:
       Find the next occurance of any of a set of characters in a
       string and return the character which occurs next.
 CATEGORY:
       text/strings
 CALLING SEQUENCE:
       tok = textoidl_nexttok( strn, tokens )
 INPUTS:
       strn   -- string to be searched for sub/superscripts    in
       tokens -- string containing characters to be found.     in
 KEYWORD PARAMETERS:
       POSITION -- Set to a named variable to get position     out
                   of next token, or -1 if none found.
       /HELP    -- Print useful message and exit.
 OUTPUTS:
       tok    -- Contains the character among tokens which     out
                 occurs next in strn, or null '' if none found.
 COMMON BLOCKS:
 SIDE EFFECTS:
 NOTES:
 EXAMPLE:
       textoidl_nexttok( 'x^2 + N_j^3', '^_', position=pos ) returns '^' and sets
       pos to 1.
 MODIFICATION HISTORY:
       $Id: textoidl.pro,v 1.8 2004/07/19 16:48:04 schlegel Exp $
       $Log: textoidl.pro,v $
       Revision 1.8  2004/07/19 16:48:04  schlegel
       Replace calls to the obsolete function RSTRPOS() with STRPOS(/REVERSE_SEARCH).

       Revision 1.7  2000/11/20 02:27:24  dfink
       Added \AA option for Anstroms

       Revision 1.6  2000/07/12 14:31:33  hogg
       fixed another ()/[] bug.

       Revision 1.5  2000/06/15 18:21:23  hogg
       fixed tiny () -> [] bugs

       Revision 1.4  2000/06/03 17:12:42  dfink
       Fink's new textoidl - all procedures in one file; avoid name conflict

       Revision 1.3  1996/06/14 20:00:27  mcraig
       Updated Copyright info.

       Revision 1.2  1996/05/09 00:22:17  mcraig
       Generalized so that the next occurence of any of a set of characters will
       be returned.

       Revision 1.1  1996/01/31 18:41:06  mcraig
       Initial revision

 RELEASE:
       $Name: v5_1_3 $

 COPYRIGHT:
  Copyright (C) 1996 The Regents of the University of California, All
  Rights Reserved.  Written by Matthew W. Craig.
  See the file COPYRIGHT for restrictions on distrubting this code.
  This code comes with absolutely NO warranty; see DISCLAIMER for details.

(See pro/TeXtoIDL/textoidl.pro)


TEXTOIDL_STRCNT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       TEXTOIDL_STRCNT
 PURPOSE:
       Count number of occurrences of a substring in a string.
 CATEGORY:
       text/strings
 CALLING SEQUENCE:
       num = textoidl_strcnt(strn, substring, [pos])
 INPUTS:
       string    -- The string in which to count occurences.     in
       substring -- The substring to count occurrences of.       in
       pos       -- the position at which to begin the search.   [in]
                    If not supplied, start at beginning of
                    string.
 KEYWORD PARAMETERS:
       /HELP     -- Print useful message and return.
 OUTPUTS:
       num       -- Number of occurances of substring in string. out
 COMMON BLOCKS:
 SIDE EFFECTS:
 NOTES:
       Overlapping occurances are not counted separately.  For
       example, counting occurances of 'bb' in 'blah bbb' returns one
       occurance. 
 EXAMPLE:
 MODIFICATION HISTORY:
       $Id: textoidl.pro,v 1.8 2004/07/19 16:48:04 schlegel Exp $
       $Log: textoidl.pro,v $
       Revision 1.8  2004/07/19 16:48:04  schlegel
       Replace calls to the obsolete function RSTRPOS() with STRPOS(/REVERSE_SEARCH).

       Revision 1.7  2000/11/20 02:27:24  dfink
       Added \AA option for Anstroms

       Revision 1.6  2000/07/12 14:31:33  hogg
       fixed another ()/[] bug.

       Revision 1.5  2000/06/15 18:21:23  hogg
       fixed tiny () -> [] bugs

       Revision 1.4  2000/06/03 17:12:42  dfink
       Fink's new textoidl - all procedures in one file; avoid name conflict

       Revision 1.3  1996/06/14 20:00:27  mcraig
       Updated Copyright info.

       Revision 1.2  1996/05/09 00:22:17  mcraig
       Added fast processing using BYTE arrays if we are counting occurences of
       a single character.  Added error handling.

       Revision 1.1  1996/01/31 18:47:37  mcraig
       Initial revision

 RELEASE:
       $Name: v5_1_3 $

 COPYRIGHT:
  Copyright (C) 1996 The Regents of the University of California, All
  Rights Reserved.  Written by Matthew W. Craig.
  See the file COPYRIGHT for restrictions on distrubting this code.
  This code comes with absolutely NO warranty; see DISCLAIMER for details.

(See pro/TeXtoIDL/textoidl.pro)


TEXTOIDL_STRTOK

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       TEXTOIDL_STRTOK
 PURPOSE:
       Retrieve portion of string up to token.
 CATEGORY:
       text/strings
 CALLING SEQUENCE:
       new = textoidl_strtok( old, token )
 INPUTS:
       old   -- String to be split.  Contains text after    in, out
                token on output.
       token -- Token to use in splitting old.              in
 KEYWORD PARAMETERS:
       /TRIM -- set to remove leading blanks from old 
                before returning.
       /HELP -- print useful message and exit.
 OUTPUTS:
       new   -- portion of string up to token.              out
       old   -- portion of old after token.                 out, in
 COMMON BLOCKS:
 SIDE EFFECTS:
       Input parameter old is modified.
 NOTES:
       Token may be one or more characters.
       If token is not found, returns old and sets old to ''.
 EXAMPLE:
       If old is 'foo44 bar', then textoidl_strtok( old, '44' ) would return
       'foo', and upon return, old will be left with ' bar'.  If /TRIM
       were set, old would be 'bar' on return.

       If old='xyz', then new=textoidl_strtok(old,'a') would return with
       new='xyz' and old=''.
 THANKS:
       To D. Linder who wrote GETTOK, part of the goddard library,
       upon which this is based.
 MODIFICATION HISTORY:
       $Id: textoidl.pro,v 1.8 2004/07/19 16:48:04 schlegel Exp $
       $Log: textoidl.pro,v $
       Revision 1.8  2004/07/19 16:48:04  schlegel
       Replace calls to the obsolete function RSTRPOS() with STRPOS(/REVERSE_SEARCH).

       Revision 1.7  2000/11/20 02:27:24  dfink
       Added \AA option for Anstroms

       Revision 1.6  2000/07/12 14:31:33  hogg
       fixed another ()/[] bug.

       Revision 1.5  2000/06/15 18:21:23  hogg
       fixed tiny () -> [] bugs

       Revision 1.4  2000/06/03 17:12:42  dfink
       Fink's new textoidl - all procedures in one file; avoid name conflict

       Revision 1.3  1996/06/14 20:00:27  mcraig
       Updated Copyright info.

       Revision 1.2  1996/05/09 00:22:17  mcraig
       Added built in help.

       Revision 1.1  1996/01/31 18:47:37  mcraig
       Initial revision

 RELEASE:
       $Name: v5_1_3 $

 COPYRIGHT:
  Copyright (C) 1996 The Regents of the University of California, All
  Rights Reserved.  Written by Matthew W. Craig.
  See the file COPYRIGHT for restrictions on distrubting this code.
  This code comes with absolutely NO warranty; see DISCLAIMER for details.

(See pro/TeXtoIDL/textoidl.pro)


TEXTOIDL_STRTRANS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       TEXTOIDL_STRTRANS
 PURPOSE:
       Translate all occurences of one substring to another.
 CATEGORY:
       text/strings
 CALLING SEQUENCE:
       new = textoidl_strtrans(oldstr,from,to,ned)
 INPUTS:
       oldstr -- string on which to operate.              in
                 May be an array.
       from   -- substrings to be translated. May be      in
                 an array.
       to     -- what strings in from should be           in
                 translated to. May be an array.
 KEYWORD PARAMETERS:
       /HELP  -- Set this to print useful message and 
                 exit.
 OUTPUTS:
       new    -- Translated string. Array if oldstr is    out          
                 an array.
       ned    -- number of substitutions performed in     out
                 oldstr.  Array if oldstr is an array.
 COMMON BLOCKS:
 SIDE EFFECTS:
 NOTES:
       - Any of old, from, and to can be arrays.  
       - from and to must have the same number of elements.
 EXAMPLE:
       inp='Many*bad!chars+in_here'
       from=['*','!','+','_']
       to  =[' ',' ',' ',' ']
       out = textoidl_strtrans(inp,from,to,ned)
       Will produce out='Many bad chars in here', and set ned to 4.
 MODIFICATION HISTORY:
       $Id: textoidl.pro,v 1.8 2004/07/19 16:48:04 schlegel Exp $
       $Log: textoidl.pro,v $
       Revision 1.8  2004/07/19 16:48:04  schlegel
       Replace calls to the obsolete function RSTRPOS() with STRPOS(/REVERSE_SEARCH).

       Revision 1.7  2000/11/20 02:27:24  dfink
       Added \AA option for Anstroms

       Revision 1.7  2000/11/19 18:25:00  dfink / Jonathan Swift
       Added \AA option for Anstroms

       Revision 1.6  2000/07/12 14:31:33  hogg
       fixed another ()/[] bug.

       Revision 1.5  2000/06/15 18:21:23  hogg
       fixed tiny () -> [] bugs

       Revision 1.4  2000/06/03 17:12:42  dfink
       Fink's new textoidl - all procedures in one file; avoid name conflict

       Revision 1.3  1996/06/14 20:00:27  mcraig
       Updated Copyright info.

       Revision 1.2  1996/05/09 00:22:17  mcraig
       Sped up significantly by using str_sep to handle the translation.  No longer
       relies on routines fromother user libraries.

       Revision 1.1  1996/01/31 18:47:37  mcraig
       Initial revision

 RELEASE:
       $Name: v5_1_3 $

 COPYRIGHT:
  Copyright (C) 1996 The Regents of the University of California, All
  Rights Reserved.  Written by Matthew W. Craig.
  See the file COPYRIGHT for restrictions on distrubting this code.
  This code comes with absolutely NO warranty; see DISCLAIMER for details.

(See pro/TeXtoIDL/textoidl.pro)


TEXTOIDL_SUB_SUP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       TEXTOIDL_SUB_SUP
 PURPOSE:
       Return the proper IDL font positioning command for TeX
       sub/superscripts. 
 CATEGORY:
       TeXtoIDL
 CALLING SEQUENCE:
       fnt = textoidl_sub_sup( strn )
 INPUTS:
       strn      -- Either '^' or '_', the TeX super/subscript       in
                    characters
 KEYWORD PARAMETERS:
       /FORCE_UD -- Set this to use !U/!D instead of !E/!I for
                    sub/superscripts .
       /HELP     -- Set to print useful message and exit.
 OUTPUTS:
       fnt       -- Either '!U' or !E' for superscripts,             out
                    or '!D' or '!I' for subscripts.
 COMMON BLOCKS:
 SIDE EFFECTS:
 NOTES:
       Used only by textoidl_trans_sub_super.  Should be kept in same
       file. 
 EXAMPLE:
 MODIFICATION HISTORY:
       $Id: textoidl.pro,v 1.8 2004/07/19 16:48:04 schlegel Exp $
       $Log: textoidl.pro,v $
       Revision 1.8  2004/07/19 16:48:04  schlegel
       Replace calls to the obsolete function RSTRPOS() with STRPOS(/REVERSE_SEARCH).

       Revision 1.7  2000/11/20 02:27:24  dfink
       Added \AA option for Anstroms

       Revision 1.6  2000/07/12 14:31:33  hogg
       fixed another ()/[] bug.

       Revision 1.5  2000/06/15 18:21:23  hogg
       fixed tiny () -> [] bugs

       Revision 1.4  2000/06/03 17:12:42  dfink
       Fink's new textoidl - all procedures in one file; avoid name conflict

       Revision 1.4  1996/06/14 20:00:27  mcraig
       Updated Copyright info.

       Revision 1.3  1996/05/09 00:22:17  mcraig
       Changed some function calls to reflect changes in those functions, moved
       some code out of the main loop that didn't need to be there, added
       documentation.

       Revision 1.1  1996/01/31 18:47:37  mcraig
       Initial revision

 RELEASE:
       $Name: v5_1_3 $
 COPYRIGHT:
  Copyright (C) 1996 The Regents of the University of California, All
  Rights Reserved.  Written by Matthew W. Craig.
  See the file COPYRIGHT for restrictions on distrubting this code.
  This code comes with absolutely NO warranty; see DISCLAIMER for details.

(See pro/TeXtoIDL/textoidl.pro)


TEXTOIDL_TABLE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       TEXTOIDL_TABLE
 PURPOSE:
       Returns a translation table from TeX to IDL.
 CATEGORY:
       text/strings
 CALLING SEQUENCE:
       table = textoidl_table()
 INPUTS:
       None
 KEYWORD PARAMETERS:
       /POSTSCRIPT -- If set, return postscript translation
                      table rather than vector fonts table.
                      Default is translations for vector
                      fonts.
       /HELP       -- Print help and exit.
 OUTPUTS:
       table -- a 2D text array.  table(0,*) contains          out
                the words to be translated away, table(1,*)
                contains the words to translate them to.   
 COMMON BLOCKS:
 SIDE EFFECTS:
 NOTES:
       To find out what TeX sequences are available, look at
       table(0,*).
 EXAMPLE:
 MODIFICATION HISTORY:
       $Id: textoidl.pro,v 1.8 2004/07/19 16:48:04 schlegel Exp $
       $Log: textoidl.pro,v $
       Revision 1.8  2004/07/19 16:48:04  schlegel
       Replace calls to the obsolete function RSTRPOS() with STRPOS(/REVERSE_SEARCH).

       Revision 1.7  2000/11/20 02:27:24  dfink
       Added \AA option for Anstroms

       Revision 1.6  2000/07/12 14:31:33  hogg
       fixed another ()/[] bug.

       Revision 1.5  2000/06/15 18:21:23  hogg
       fixed tiny () -> [] bugs

       Revision 1.4  2000/06/03 17:12:42  dfink
       Fink's new textoidl - all procedures in one file; avoid name conflict

       Revision 1.7  1996/07/22 23:56:08  mcraig
       Added \vartheta.

       Revision 1.6  1996/07/12 21:31:42  mcraig
       Fixed \varphi in vector font, added \circ.

       Revision 1.5  1996/06/14 20:00:27  mcraig
       Updated Copyright info.

       Revision 1.4  1996/05/09 00:22:17  mcraig
       Added command to return to previous font after switching to Greek or
       symbol font.

       Revision 1.3  1996/02/08 19:49:35  mcraig
       Removed control sequence \perp because the postscript code for it is '^'.

       Revision 1.2  1996/02/08 18:53:38  mcraig
       Added translations for PostScript fonts, and added several new TeX
       control sequences.

       Revision 1.1  1996/01/31 18:47:37  mcraig
       Initial revision

 RELEASE:
       $Name: v5_1_3 $

 COPYRIGHT:
  Copyright (C) 1996 The Regents of the University of California, All
  Rights Reserved.  Written by Matthew W. Craig.
  See the file COPYRIGHT for restrictions on distrubting this code.
  This code comes with absolutely NO warranty; see DISCLAIMER for details.

(See pro/TeXtoIDL/textoidl.pro)


TEXTOIDL_TRANS_SUB_SUPER

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       TEXTOIDL_TRANS_SUB_SUPER
 PURPOSE:
       Translate TeX sub/superscripts to IDL sub/superscripts.
 CATEGORY:
       text/strings
 CALLING SEQUENCE:
       new = textoidl_trans_sub_super( old )
 INPUTS:
       old       -- string to be translated from TeX to IDL.   in
 KEYWORD PARAMETERS:
       /RECURSED -- set if this function is being called 
                    recursively.                  
       /HELP     -- Set to print useful message and exit.
 OUTPUTS:
       new       -- string old converted from TeX to IDL       out
 COMMON BLOCKS:
 SIDE EFFECTS:
 NOTES:
       - For best results, when both a sub and superscript are used,
         place the shorter of the two first (e.g. 'N^{a}_{bbbb}' is
         better than 'N_{bbbb}^{a}').
       - Single character sub/super scripts do not need to be
         protected by braces.
       - Sub/superscripts may be nested (e.g. 'N^{N_1^N}').
 EXAMPLE:
       out = textoidl_trans_sub_super( 'N^2_{big}' )
       Then out='N!U2!N!Dbig!N' which looks like it should on the
       display. 
 LIBRARY FUNCTIONS CALLED:
       textoidl_strtok      -- Text/string (mcraig)
       textoidl_sub_sup -- contained in this file
 MODIFICATION HISTORY:
       $Id: textoidl.pro,v 1.8 2004/07/19 16:48:04 schlegel Exp $
       $Log: textoidl.pro,v $
       Revision 1.8  2004/07/19 16:48:04  schlegel
       Replace calls to the obsolete function RSTRPOS() with STRPOS(/REVERSE_SEARCH).

       Revision 1.7  2000/11/20 02:27:24  dfink
       Added \AA option for Anstroms

       Revision 1.6  2000/07/12 14:31:33  hogg
       fixed another ()/[] bug.

       Revision 1.5  2000/06/15 18:21:23  hogg
       fixed tiny () -> [] bugs

       Revision 1.4  2000/06/03 17:12:42  dfink
       Fink's new textoidl - all procedures in one file; avoid name conflict

       Revision 1.4  1996/06/14 20:00:27  mcraig
       Updated Copyright info.

       Revision 1.3  1996/05/09 00:22:17  mcraig
       Changed some function calls to reflect changes in those functions, moved
       some code out of the main loop that didn't need to be there, added
       documentation.

       Revision 1.2  1996/02/08 18:54:20  mcraig
       Changed default sub/superscript size to be !D/!U rather than !I/!E to
       improve readability of plat annotations.

       Revision 1.1  1996/01/31 18:47:37  mcraig
       Initial revision

 RELEASE:
       $Name: v5_1_3 $

 COPYRIGHT:
  Copyright (C) 1996 The Regents of the University of California, All
  Rights Reserved.  Written by Matthew W. Craig.
  See the file COPYRIGHT for restrictions on distrubting this code.
  This code comes with absolutely NO warranty; see DISCLAIMER for details.

(See pro/TeXtoIDL/textoidl.pro)


TMASS_ASCII2FITS

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

 PURPOSE:
   Convert 2MASS ascii files to FITS tables

 CALLING SEQUENCE:
   tmass_ascii2fits, infile, outfile

 INPUTS:
   infile  - input file name
   outfile - output file name

 KEYWORDS:
   
 OUTPUTS:
   file named <outfile>

 RESTRICTIONS:
   
 EXAMPLES:
   
 COMMENTS:
   Recognizes gzip compression automatically. 

   I'm not keeping all the fields - just the useful ones. 
   Might want to keep everything in the future. 

 REVISION HISTORY:
   2003-Jun-26  Written by Douglas Finkbeiner, Princeton

(See pro/2mass/tmass_ascii2fits.pro)


TMASS_CONE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       tmass_cone
+------------------------------------------------------------------------  
 PURPOSE:
       Determine RA,dec regions to read and call tmass_readzone
+------------------------------------------------------------------------  
 INPUTS:
   fitspath  - catalogue path
   racen     - RA of region center (J2000)    [degrees]
   deccen    - dec of region center (J2000)   [degrees]
   rad       - radius of region               [degrees]

+------------------------------------------------------------------------  
 OUTPUTS:
   result    - data structure defined by FITS file
+------------------------------------------------------------------------  
 COMMENTS:    
   calls tmass_readzone
+------------------------------------------------------------------------  
 REVISION HISTORY
   2003-Jul-14 
   Written  2000 Apr 15 by D. P. Finkbeiner
   2002-Nov-25  Split from tmass_read.pro
                  and modified to work with TMASS-B1.0 - DPF
+------------------------------------------------------------------------  

(See pro/2mass/tmass_cone.pro)


TMASS_DECSLICE

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

 PURPOSE:
   rewrite 2MASS data in 0.1 deg declination slices for fast seeks

 CALLING SEQUENCE:
   
 INPUTS:
   inpath  - path of input files
   outpath - path of output files

 COMMENTS:
   called by tmass_ingest

 REVISION HISTORY:
   2003-July-12  Written by Douglas Finkbeiner, Princeton
   2005-June-25  Fix bug that corrupts .acc file if zero stars in any
           RA step.  - DPF

(See pro/2mass/tmass_decslice.pro)


TMASS_FITS_FILES

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

 PURPOSE:
   Convert 2MASS gzipped ASCII files to decsliced FITS tables

 CALLING SEQUENCE:
   tmass_fits_files

 INPUTS:
   <hardwired paths>

 OPTIONAL INPUTS:
   
 KEYWORDS:
   
 OUTPUTS:
   
 OPTIONAL OUTPUTS:
   
 RESTRICTIONS:
   
 EXAMPLES:
   
 COMMENTS:
   The first step, tmass_reformat_psc, can be run on several boxes
    in parallel. 

 REVISION HISTORY:
   2003-Jul-24  Written by Douglas Finkbeiner, Princeton

(See pro/2mass/tmass_fits_files.pro)


TMASS_READ

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

 PURPOSE:
       Read 2MASS stars near a given RA, dec

 INPUTS:
   racen     - RA of region center (J2000)    [degrees]
   deccen    - dec of region center (J2000)   [degrees]
   rad       - radius of region               [degrees]


 OUTPUTS:
   result    - data structure defined by FITS file

 COMMENTS:    
   Determines RA,dec regions to read and calls tmass_readzone

 REVISION HISTORY
   2003-Jul-14   Written by D. P. Finkbeiner
   2005-Aug-18   Return 0 if no objects are within radius - DPF

(See pro/2mass/tmass_read.pro)


TMASS_READZONE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       tmass_readzone
+------------------------------------------------------------------------  
 PURPOSE:
       Read 2MASS FITS files given RA range out of one deczone.
+------------------------------------------------------------------------  
 INPUTS:
   fitspath  - path to catalogue files (.fits and .acc)
   zone      - zone number (float, 1/10 degrees)
   ra0,ra1   - ra limits [deg]
   prefix    - filename prefix: '2mass' for 2MASS

+------------------------------------------------------------------------  
 OUTPUTS:
   result    - 2mass data structure defined by the FITS files

+------------------------------------------------------------------------  
 COMMENTS:
   uses point_lun to skip to requested part of file.  Very fast. 

   Requests are padded by 1/10 the interpolation grid spacing.  This
     padding is trimmed unless that would yield a null result. 

   Warning - this routine interpolates file index positions
             and works only if the star distribution is approximately
             uniform within each interpolation grid patch (which it is).  
+------------------------------------------------------------------------
 MODIFICATION HISTORY:
  2003-Jul-14 Taken from usno_read by D. Finkbeiner, Princeton

(See pro/2mass/tmass_readzone.pro)


TMASS_REFORMAT_PSC

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

 PURPOSE:
   reformat 2MASS PSC from ASCII to FITS files

 CALLING SEQUENCE:
   tmass_reformat_psc, inpath, outpath

 INPUTS:
   inpath  - path to the gzipped psc files downloaded from IPAC
   outpath - path to temp dir to write FITS files, one per ASCII file.

 COMMENTS:
   convert the gzipped ASCII files to FITS files. 
   "tmass_" prepended to tag names for merge with SDSS data. 

   Data Revision 5: April 13, 2003: R. Stiening,
    Modified for ftp version: April 30, 2003: R. Cutri

 REVISION HISTORY:
   2003-Jul-17  Written by D. Finkbeiner & D. Schlegel, Princeton

(See pro/2mass/tmass_reformat_psc.pro)


TMASS_STRUC

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

 PURPOSE:
   Define data structure for FITS copy of 2MASS data

 CALLING SEQUENCE:
   struc = tmass_struc(N)

 INPUTS:
   N     - number of elements in structure array (default 1)

 OUTPUTS:
   struc - 2MASS data structure

 COMMENTS:
   Used by tmass_ascii2fits.  We use DEC instead of the 2MASS
   name of DECL for declination.

 REVISION HISTORY:
   2003-Jun-26  Written by Douglas Finkbeiner, Princeton

(See pro/2mass/tmass_struc.pro)


TNMIN

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

 AUTHOR:
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov
   UPDATED VERSIONs can be found on my WEB PAGE:
      http://cow.physics.wisc.edu/~craigm/idl/idl.html

 PURPOSE:
   Performs function minimization (Truncated-Newton Method)

 MAJOR TOPICS:
   Optimization and Minimization

 CALLING SEQUENCE:
   parms = TNMIN(MYFUNCT, X, FUNCTARGS=fcnargs, NFEV=nfev,
                 MAXITER=maxiter, ERRMSG=errmsg, NPRINT=nprint,
                 QUIET=quiet, XTOL=xtol, STATUS=status,
                 FGUESS=fguess, PARINFO=parinfo, BESTMIN=bestmin,
                 ITERPROC=iterproc, ITERARGS=iterargs, niter=niter)

 DESCRIPTION:

  TNMIN uses the Truncated-Newton method to minimize an arbitrary IDL
  function with respect to a given set of free parameters.  The
  user-supplied function must compute the gradient with respect to
  each parameter.  TNMIN is based on TN.F (TNBC) by Stephen Nash.

  If you want to solve a least-squares problem, to perform *curve*
  *fitting*, then you will probably want to use the routines MPFIT,
  MPFITFUN and MPFITEXPR.  Those routines are specifically optimized
  for the least-squares problem.  TNMIN is suitable for constrained
  and unconstrained optimization problems with a medium number of
  variables.  Function *maximization* can be performed using the
  MAXIMIZE keyword.

  TNMIN is similar to MPFIT in that it allows parameters to be fixed,
  simple bounding limits to be placed on parameter values, and
  parameters to be tied to other parameters.  See PARINFO below for
  discussion and examples.

 USER FUNCTION

  The user must define an IDL function which returns the desired
  value as a single scalar.  The IDL function must accept a list of
  numerical parameters, P.  Additionally, keyword parameters may be
  used to pass more data or information to the user function, via the
  FUNCTARGS keyword.

  The user function should be declared in the following way:

     FUNCTION MYFUNCT, p, dp [, keywords permitted ]
       ; Parameter values are passed in "p"
       f  = ....   ; Compute function value
       dp = ....   ; Compute partial derivatives (optional)
       return, f
     END

  The function *must* accept at least one argument, the parameter
  list P.  The vector P is implicitly assumed to be a one-dimensional
  array.  Users may pass additional information to the function by
  composing and _EXTRA structure and passing it in the FUNCTARGS
  keyword.

  User functions may also indicate a fatal error condition using the
  ERROR_CODE common block variable, as described below under the
  TNMIN_ERROR common block definition (by setting ERROR_CODE to a
  number between -15 and -1).

  ANALYTIC vs. NUMERICAL DERIVATIVES

  By default, the user must compute gradient components analytically
  using AUTODERIVATIVE=0.  As explained below, numerical derivatives
  can also be calculated using AUTODERIVATIVE=1.

  For analytic derivatives, the user should call TNMIN using the
  default keyword value AUTODERIVATIVE=0.  [ This is different
  behavior from MPFIT, where AUTODERIVATIVE=1 is the default. ] The
  IDL user routine should compute the gradient of the function as a
  one-dimensional array of values, one for each of the parameters.
  They are passed back to TNMIN via "dp" as shown above.

  The derivatives with respect to fixed parameters are ignored; zero
  is an appropriate value to insert for those derivatives.  Upon
  input to the user function, DP is set to a vector with the same
  length as P, with a value of 1 for a parameter which is free, and a
  value of zero for a parameter which is fixed (and hence no
  derivative needs to be calculated).  This input vector may be
  overwritten as needed.

  For numerical derivatives, a finite differencing approximation is
  used to estimate the gradient values.  Users can activate this
  feature by passing the keyword AUTODERIVATIVE=1.  Fine control over
  this behavior can be achieved using the STEP, RELSTEP and TNSIDE
  fields of the PARINFO structure.

  When finite differencing is used for computing derivatives (ie,
  when AUTODERIVATIVE=1), the parameter DP is not passed.  Therefore
  functions can use N_PARAMS() to indicate whether they must compute
  the derivatives or not.  However there is no penalty (other than
  computation time) for computing the gradient values and users may
  switch between AUTODERIVATIVE=0 or =1 in order to test both
  scenarios.

 CONSTRAINING PARAMETER VALUES WITH THE PARINFO KEYWORD

  The behavior of TNMIN can be modified with respect to each
  parameter to be optimized.  A parameter value can be fixed; simple
  boundary constraints can be imposed; limitations on the parameter
  changes can be imposed; properties of the automatic derivative can
  be modified; and parameters can be tied to one another.

  These properties are governed by the PARINFO structure, which is
  passed as a keyword parameter to TNMIN.

  PARINFO should be an array of structures, one for each parameter.
  Each parameter is associated with one element of the array, in
  numerical order.  The structure can have the following entries
  (none are required):

     .VALUE - the starting parameter value (but see the START_PARAMS
              parameter for more information).

     .FIXED - a boolean value, whether the parameter is to be held
              fixed or not.  Fixed parameters are not varied by
              TNMIN, but are passed on to MYFUNCT for evaluation.

     .LIMITED - a two-element boolean array.  If the first/second
                element is set, then the parameter is bounded on the
                lower/upper side.  A parameter can be bounded on both
                sides.  Both LIMITED and LIMITS must be given
                together.

     .LIMITS - a two-element float or double array.  Gives the
               parameter limits on the lower and upper sides,
               respectively.  Zero, one or two of these values can be
               set, depending on the values of LIMITED.  Both LIMITED
               and LIMITS must be given together.

     .PARNAME - a string, giving the name of the parameter.  The
                fitting code of TNMIN does not use this tag in any
                way.

     .STEP - the step size to be used in calculating the numerical
             derivatives.  If set to zero, then the step size is
             computed automatically.  Ignored when AUTODERIVATIVE=0.

     .MPSIDE - the sidedness of the finite difference when computing
               numerical derivatives.  This field can take four
               values:

                  0 - one-sided derivative computed automatically
                  1 - one-sided derivative (f(x+h) - f(x)  )/h
                 -1 - one-sided derivative (f(x)   - f(x-h))/h
                  2 - two-sided derivative (f(x+h) - f(x-h))/(2*h)

              Where H is the STEP parameter described above.  The
              "automatic" one-sided derivative method will chose a
              direction for the finite difference which does not
              violate any constraints.  The other methods do not
              perform this check.  The two-sided method is in
              principle more precise, but requires twice as many
              function evaluations.  Default: 0.

     .TIED - a string expression which "ties" the parameter to other
             free or fixed parameters.  Any expression involving
             constants and the parameter array P are permitted.
             Example: if parameter 2 is always to be twice parameter
             1 then use the following: parinfo(2).tied = '2 * P(1)'.
             Since they are totally constrained, tied parameters are
             considered to be fixed; no errors are computed for them.
             [ NOTE: the PARNAME can't be used in expressions. ]

  Future modifications to the PARINFO structure, if any, will involve
  adding structure tags beginning with the two letters "MP" or "TN".
  Therefore programmers are urged to avoid using tags starting with
  these two combinations of letters; otherwise they are free to
  include their own fields within the PARINFO structure, and they
  will be ignored.

  PARINFO Example:
  parinfo = replicate({value:0.D, fixed:0, limited:[0,0], $
                       limits:[0.D,0]}, 5)
  parinfo(0).fixed = 1
  parinfo(4).limited(0) = 1
  parinfo(4).limits(0)  = 50.D
  parinfo(*).value = [5.7D, 2.2, 500., 1.5, 2000.]

  A total of 5 parameters, with starting values of 5.7,
  2.2, 500, 1.5, and 2000 are given.  The first parameter
  is fixed at a value of 5.7, and the last parameter is
  constrained to be above 50.


 INPUTS:

   MYFUNCT - a string variable containing the name of the function to
             be minimized (see USER FUNCTION above).  The IDL routine
             should return the value of the function and optionally
             its gradients.

   X - An array of starting values for each of the parameters of the
       model.

       This parameter is optional if the PARINFO keyword is used.
       See above.  The PARINFO keyword provides a mechanism to fix or
       constrain individual parameters.  If both X and PARINFO are
       passed, then the starting *value* is taken from X, but the
       *constraints* are taken from PARINFO.


 RETURNS:

   Returns the array of best-fit parameters.


 KEYWORD PARAMETERS:

   AUTODERIVATIVE - If this is set, derivatives of the function will
                    be computed automatically via a finite
                    differencing procedure.  If not set, then MYFUNCT
                    must provide the (analytical) derivatives.
                    Default: 0 (analytical derivatives required)

   BESTMIN - upon return, the best minimum function value that TNMIN
             could find.

   EPSABS - a nonnegative real variable.  Termination occurs when the
            absolute error between consecutive iterates is at most
            EPSABS.  Note that using EPSREL is normally preferable
            over EPSABS, except in cases where ABS(F) is much larger
            than 1 at the optimal point.  A value of zero indicates
            the absolute error test is not applied.  If EPSABS is
            specified, then both EPSREL and EPSABS tests are applied;
            if either succeeds then termination occurs.
            Default: 0 (i.e., only EPSREL is applied).

   EPSREL - a nonnegative input variable. Termination occurs when the
            relative error between two consecutive iterates is at
            most EPSREL.  Therefore, EPSREL measures the relative
            error desired in the function.  An additional, more
            lenient, stopping condition can be applied by specifying
            the EPSABS keyword.
            Default: 100 * Machine Precision

   ERRMSG - a string error or warning message is returned.

   FGUESS - provides the routine a guess to the minimum value.
            Default: 0

   FUNCTARGS - A structure which contains the parameters to be passed
               to the user-supplied function specified by MYFUNCT via
               the _EXTRA mechanism.  This is the way you can pass
               additional data to your user-supplied function without
               using common blocks.

               Consider the following example:
                if FUNCTARGS = { XVAL:[1.D,2,3], YVAL:[1.D,4,9]}
                then the user supplied function should be declared
                like this:
                FUNCTION MYFUNCT, P, XVAL=x, YVAL=y

               By default, no extra parameters are passed to the
               user-supplied function.

   ITERARGS - The keyword arguments to be passed to ITERPROC via the
              _EXTRA mechanism.  This should be a structure, and is
              similar in operation to FUNCTARGS.
              Default: no arguments are passed.

   ITERDERIV - Intended to print function gradient information.  If
               set, then the ITERDERIV keyword is set in each call to
               ITERPROC.  In the default ITERPROC, parameter values
               and gradient information are both printed when this
               keyword is set.

   ITERPROC - The name of a procedure to be called upon each NPRINT
              iteration of the TNMIN routine.  It should be declared
              in the following way:

              PRO ITERPROC, MYFUNCT, p, iter, fnorm, FUNCTARGS=fcnargs, $
                PARINFO=parinfo, QUIET=quiet, _EXTRA=extra
                ; perform custom iteration update
              END

              ITERPROC must accept the _EXTRA keyword, in case of
              future changes to the calling procedure.

              MYFUNCT is the user-supplied function to be minimized,
              P is the current set of model parameters, ITER is the
              iteration number, and FUNCTARGS are the arguments to be
              passed to MYFUNCT.  FNORM is should be the function
              value.  QUIET is set when no textual output should be
              printed.  See below for documentation of PARINFO.

              In implementation, ITERPROC can perform updates to the
              terminal or graphical user interface, to provide
              feedback while the fit proceeds.  If the fit is to be
              stopped for any reason, then ITERPROC should set the
              common block variable ERROR_CODE to negative value
              between -15 and -1 (see TNMIN_ERROR common block
              below).  In principle, ITERPROC should probably not
              modify the parameter values, because it may interfere
              with the algorithm's stability.  In practice it is
              allowed.

              Default: an internal routine is used to print the
                       parameter values.

   MAXITER - The maximum number of iterations to perform.  If the
             number is exceeded, then the STATUS value is set to 5
             and TNMIN returns.
             Default: 200 iterations

   MAXIMIZE - If set, the function is maximized instead of
              minimized.

   MAXNFEV - The maximum number of function evaluations to perform.
             If the number is exceeded, then the STATUS value is set
             to -17 and TNMIN returns.  A value of zero indicates no
             maximum.
             Default: 0 (no maximum)

   NFEV - upon return, the number of MYFUNCT function evaluations
          performed.

   NITER - upon return, number of iterations completed.

   NPRINT - The frequency with which ITERPROC is called.  A value of
            1 indicates that ITERPROC is called with every iteration,
            while 2 indicates every other iteration, etc.
            Default value: 1

   PARINFO - Provides a mechanism for more sophisticated constraints
             to be placed on parameter values.  When PARINFO is not
             passed, then it is assumed that all parameters are free
             and unconstrained.  Values in PARINFO are never modified
             during a call to TNMIN.

             See description above for the structure of PARINFO.

             Default value:  all parameters are free and unconstrained.

   QUIET - set this keyword when no textual output should be printed
           by TNMIN

   STATUS - an integer status code is returned.  All values greater
            than zero can represent success (however STATUS EQ 5 may
            indicate failure to converge).  Gaps in the numbering
            system below are to maintain compatibility with MPFIT.
            Upon return, STATUS can have one of the following values:

        -18  a fatal internal error occurred during optimization.

        -17  the maximum number of function evaluations has been
             reached without convergence.

        -16  a parameter or function value has become infinite or an
             undefined number.  This is usually a consequence of
             numerical overflow in the user's function, which must be
             avoided.

        -15 to -1
             these are error codes that either MYFUNCT or ITERPROC
             may return to terminate the fitting process (see
             description of MPFIT_ERROR common below).  If either
             MYFUNCT or ITERPROC set ERROR_CODE to a negative number,
             then that number is returned in STATUS.  Values from -15
             to -1 are reserved for the user functions and will not
             clash with MPFIT.

	   0  improper input parameters.

	   1  convergence was reached.

          2-4 (RESERVED)

	   5  the maximum number of iterations has been reached

          6-8 (RESERVED)


 EXAMPLE:

   FUNCTION F, X, DF, _EXTRA=extra  ;; *** MUST ACCEPT KEYWORDS
     F  = (X(0)-1)^2 + (X(1)+7)^2
     DF = [ 2D * (X(0)-1), 2D * (X(1)+7) ] ; Gradient
     RETURN, F
   END

   P = TNMIN('F', [0D, 0D], BESTMIN=F0)
   Minimizes the function F(x0,x1) = (x0-1)^2 + (x1+7)^2.


 COMMON BLOCKS:

   COMMON TNMIN_ERROR, ERROR_CODE

     User routines may stop the fitting process at any time by
     setting an error condition.  This condition may be set in either
     the user's model computation routine (MYFUNCT), or in the
     iteration procedure (ITERPROC).

     To stop the fitting, the above common block must be declared,
     and ERROR_CODE must be set to a negative number.  After the user
     procedure or function returns, TNMIN checks the value of this
     common block variable and exits immediately if the error
     condition has been set.  By default the value of ERROR_CODE is
     zero, indicating a successful function/procedure call.


 REFERENCES:

   TRUNCATED-NEWTON METHOD, TN.F
      Stephen G. Nash, Operations Research and Applied Statistics
      Department
      http://www.netlib.org/opt/tn

   Nash, S. G. 1984, "Newton-Type Minimization via the Lanczos
      Method," SIAM J. Numerical Analysis, 21, p. 770-778


 MODIFICATION HISTORY:
   Derived from TN.F by Stephen Nash with many changes and additions,
      to conform to MPFIT paradigm, 19 Jan 1999, CM
   Changed web address to COW, 25 Sep 1999, CM
   Alphabetized documented keyword parameters, 02 Oct 1999, CM
   Changed to ERROR_CODE for error condition, 28 Jan 2000, CM
   Continued and fairly major improvements (CM, 08 Jan 2001):
      - calling of user procedure is now concentrated in TNMIN_CALL,
        and arguments are reduced by storing a large number of them
        in common blocks;
      - finite differencing is done within TNMIN_CALL; added
        AUTODERIVATIVE=1 so that finite differencing can be enabled,
        both one and two sided;
      - a new procedure to parse PARINFO fields, borrowed from MPFIT;
        brought PARINFO keywords up to date with MPFIT;
      - go through and check for float vs. double discrepancies;
      - add explicit MAXIMIZE keyword, and support in TNMIN_CALL and
        TNMIN_DEFITER to print the correct values in that case;
        TNMIN_DEFITER now prints function gradient values if
        requested;
      - convert to common-based system of MPFIT for storing machine
        constants; revert TNMIN_ENORM to simple sum of squares, at
        least for now;
      - remove limit on number of function evaluations, at least for
        now, and until I can understand what happens when we do
        numerical derivatives.
   Further changes: more float vs double; disable TNMINSTEP for now;
     experimented with convergence test in case of function
     maximization, 11 Jan 2001, CM
   TNMINSTEP is parsed but not enabled, 13 Mar 2001
   Major code cleanups; internal docs; reduced commons, CM, 08 Apr
     2001
   Continued code cleanups; documentation; the STATUS keyword
     actually means something, CM, 10 Apr 2001
   Added reference to Nash paper, CM, 08 Feb 2002
   Fixed 16-bit loop indices, D. Schelgel, 22 Apr 2003
   Changed parens to square brackets because of conflicts with
     limits function.  K. Tolbert, 23 Feb 2005

 TODO
  - scale derivatives semi-automatically;
  - ability to scale and offset parameters;

  $Id: tnmin.pro,v 1.3 2006/02/07 22:38:32 schlegel Exp $

(See pro/mpfit/tnmin.pro)


TRACESET2PIX

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

 PURPOSE:
   Use a traceset to find the pixel numbers corresponding to a certain postion

 CALLING SEQUENCE:
   pixpos = traceset2pix(tset, lambda, [nicoeff=nicoeff] )

 INPUTS:
   tset       - Structure containing trace set
   lambda     - Wavelengths at which to find X pixel position

 OPTIONAL KEYWORDS:
   nicoeff    - Number of coefficients to use in inversion; default to using
                2 more coefficients than for the forward trace set
                (e.g., TSET.NCOEFF+2)
   silent     - suppress messages to stdout

 OUTPUTS:
   pixpos     - Pixel positions corresponding to LAMBDA as
                an [Nlambda,Ntrace] array

 OPTIONAL OUTPUTS:

 COMMENTS:

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:
   djs_laxisgen()
   fchebyshev()
   flegendre()
   fpoly()
   traceset2xy
   xy2traceset

 REVISION HISTORY:
   09-Nov-1999  Written by David Schlegel, Ringberg.
   01-Dec-2000  added silent keyword - D. Finkbeiner
   10-Jul-2001  added polynomial option

(See pro/trace/traceset2pix.pro)


TRACESET2XY

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

 PURPOSE:
   Convert from a trace set to an array of x,y positions

 CALLING SEQUENCE:
   traceset2xy, tset, xpos, ypos

 INPUTS:
   tset       - Structure containing trace set

 OPTIONAL KEYWORDS:
   xpos       - Input positions to evaluate YPOS; if not specified (or 0),
                then generate an [NX,NTRACE] array of each pixel position

 OUTPUTS:
   xpos       - X positions corresponding to YPOS
   ypos       - Y centers as an [nx,nTrace] array

 OPTIONAL OUTPUTS:

 COMMENTS:

 EXAMPLES:

 PROCEDURES CALLED:
   djs_laxisgen()
   flegendre()
   fpoly()

 REVISION HISTORY:
   19-May-1999  Written by David Schlegel, Princeton.
   01-Dec-2000  Handle scalar xpos correctly - D. Finkbeiner
   10-Jul-2001  Added fpoly- S.Burles

(See pro/trace/traceset2xy.pro)


TRACESET_TRIM

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

 PURPOSE:
   Trim a trace set to a selected number of traces

 CALLING SEQUENCE:
   newset = traceset_trim(tset, [ indx ] )

 INPUTS:
   tset       - Structure containing trace set

 OPTIONAL KEYWORDS:
   indx       - Indices (0-indexed) of trace numbers to select; if not set,
                then simply return the input structure

 OUTPUTS:
   newset     - Trimmed trace set

 OPTIONAL OUTPUTS:

 COMMENTS:
   This function returns the input structure (which cannot be an array)
   with exactly the same structure except for the tag name COEFF.
   That particular value is trimmed to the values COEFF[*,INDX].
   In our "trace set" notation, this returns a sub-set of the traces.

 EXAMPLES:

 PROCEDURES CALLED:

 REVISION HISTORY:
   14-Jan-2004  Written by David Schlegel, Princeton.

(See pro/trace/traceset_trim.pro)


TRACE_CRUDE

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

 PURPOSE:
   Create a crude trace set given one position (eg, a center) in each trace.

 CALLING SEQUENCE:
   xset = trace_crude( fimage, [ invvar, xstart=, ystart=, radius=, yset=, $
    nave=, nmed=, thresh=, maxerr=, maxshifte=, maxshift0=, xerr=, /double ] )

 INPUTS:
   fimage     - Image

 OPTIONAL INPUTS:
   invvar     - Inverse variance (weight) image
   xstart     - Initial guesses for X centers (one for each trace).
                If not set, then this code searches for all peaks at YSTART.
   ystart     - Y positions corresponding to "xstart" (expected as integers).
                There are three options for this parameter:
                (1) One element of YSTART for each value of XSTART,
                (2) A scalar value that is used for every XSTART, or
                (3) Not set, in which case the center row is used.
   radius     - Radius for centroiding; default to 3.0
   nmed       - Median filtering size down columns before performing trace;
                default to 1
   nave       - Averaging size down columns before performing trace;
                default to 5
   thresh     - Threshold for initial peak finding; if not set, then use
                1.0 times the median of the row(s) used for the initial peaks.
   maxerr     - Maximum error in centroid allowed for valid recentering;
                default to 0.2
   maxshifte  - Maximum shift in centroid allowed for valid recentering;
                default to 0.1
   maxshift0  - Maximum shift in centroid allowed for initial row;
                default to 0.5
   double     - If set, then return values are double-precision; values are
                already double-precision if FIMAGE or XSTART already are

 OUTPUTS:
   xset       - X centers for all traces

 OPTIONAL OUTPUTS:
   yset       - Y centers for all traces
   xerr       - Errors for XSET

 COMMENTS:

 EXAMPLES:

 BUGS:
   This linked C code is always single-precision, even if /DOUBLE is set.

 PROCEDURES CALLED:
   djs_laxisgen()
   splog

   Dynamic link to trace_crude.c

 REVISION HISTORY:
   14-May-1999  Written by David Schlegel, Princeton.
   12-Jul-1999  Added optional output YSET (DJS).
   06-Aug-1999  Added optional outpust XERR (DJS).

(See pro/trace/trace_crude.pro)


TRACE_FWEIGHT

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

 PURPOSE:
   Recenter a trace using flux-weighting centers.

 CALLING SEQUENCE:
   xnew = trace_fweight( fimage, xcen, ycen, [radius=radius, xerr=xerr, 
    invvar=invvar] )

 INPUTS:
   fimage     - Image
   xcen       - Initial guesses for X centers
   ycen       - Y positions corresponding to "xcen" (expected as integers)

 OPTIONAL KEYWORDS:
   radius     - Radius for centroiding; default to 3.0
   invvar     - Inverse variance of image used only in computing errors XERR.
                If not set, then INVVAR=1 is used.

 OUTPUTS:
   xnew       - New X centers

 OPTIONAL OUTPUTS:
   xerr       - Formal errors for XNEW; set equal to 999.0 if there are any
                masked pixels in a centroiding region (e.g., if INVVAR=0)

 COMMENTS:

 EXAMPLES:

 PROCEDURES CALLED:
   Dynamic link to trace_fweight.c

 REVISION HISTORY:
   24-Mar-1999  Written by David Schlegel, Princeton.

(See pro/trace/trace_fweight.pro)


TRACE_GWEIGHT

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

 PURPOSE:
   Recenter a trace using gaussian-weighted centers.

 CALLING SEQUENCE:
   xnew = trace_fweight( fimage, xcen, ycen, [sigma=sigma, xerr=xerr, 
    invvar=invvar] )

 INPUTS:
   fimage     - Image
   xcen       - Initial guesses for X centers
   ycen       - Y positions corresponding to "xcen" (expected as integers)

 OPTIONAL KEYWORDS:
   radius     - Sigma in pixels; default to 1.0
   invvar     - Inverse variance of image used only in computing errors XERR.
                If not set, then INVVAR=1 is used.

 OUTPUTS:
   xnew       - New X centers

 OPTIONAL OUTPUTS:
   xerr       - Formal errors for XNEW; set equal to 999.0 if there are any
                masked pixels in a centroiding region (e.g., if INVVAR=0)

 COMMENTS:

 EXAMPLES:

 REVISION HISTORY:
   17-Jan-2000  Written by Scott Burles, Chicago

(See pro/trace/trace_gweight.pro)


TYCHO_EPOCH

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

 PURPOSE:
   Apply proper motion corrections to an epoch other than 2000
   for the Tycho-2 catalog.

 CALLING SEQUENCE:
   tycho_epoch, epoch, tycdat

 INPUTS:
   epoch:       New epoch
   tycdat:      Tycho-2 data structure

 OUTPUTS:
   tycdat:      (Modified)

 COMMENTS:
   The fields RAMDEG,DEMDEG are assumed to be the epoch 2000 positions
   in degrees.  These positions are moved according to proper motions
   given by PMRA,PMDE, which should be in milliarcsec/yr.

 BUGS:
   I have not handled the case where proper motion will move stars
   over the poles, i.e. to DEC > 90 deg. ???

 PROCEDURES CALLED:

 REVISION HISTORY:
   Written D. Schlegel, 31 December 2002, Princeton

(See pro/astrom/tycho_epoch.pro)


TYCHO_READ

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

 PURPOSE:
   Read the Tycho catalog (and generate IDL save sets)

 CALLING SEQUENCE:
   bigdat = tycho_read( [ racen=, deccen=, radius=, node=, incl=, hwidth=, $
    epoch=, columns= ] )

 OPTIONAL INPUTS:
   racen:       Central RA for selecting a region of stars [J2000 deg]
   deccen:      Central DEC for selecting a region of stars [J2000 deg]
   radius:      Radius for selecting a region of stars [deg]
   node:        Node of great circle for selecting a stripe of stars [deg]
   incl:        Inclination of great circle for selecting a stripe [deg]
   hwidth:      Half-width of great circle for selecting a stripe [deg]
   epoch:       If set, then apply proper motion correction from epoch 2000.
                to that set by EPOCH.  Note that equinox is always J2000.
   columns:     Select only these columns from the data files.
                Must include 'ramdeg' and 'demdeg' if a circular or
                great circle region is selected.
                Must also include 'pmra' and 'pmde' if EPOCH is specified.

 OUTPUTS:
   bigdat:      Returned structure containing data

 COMMENTS:
   To trim to objects within a circle, RACEN, DECCEN and RADIUS must
   all be set.

   To trim to objects along a great circle, NODE, INCL and HWIDTH must
   all be set.

   The equinox of the returned data is always J2000, even if the epoch
   has been chosen to be different.

   Note that 104,189 of the stars (4.3%) do not have a mean position,
   and RAMDEG,DEMDEG are set to exactly zero.  These stars still have
   an observed position in the RADEG,DEDEG fields, which are typically
   from epoch ~1991.  The expected proper motion from that epoch to
   2000 is approximately 0.08 arcsec for stars in this catalog, or
   about 0.01 arcsec/yr.

 BUGS:

 DATA FILES:
   The following data files can be copied from:
     http://adc.gsfc.nasa.gov/adc-cgi/cat.pl?/catalogs/1/1259/
   and should be put in a directory pointed to by the environment
   variable $TYCHO2_DIR:
     $TYCHO2_DIR/index.dat.gz
     $TYCHO2_DIR/tyc2_*.dat.gz
   These files may be either left compressed, or uncompressed.
   This code looks for either.

 INTERNAL SUPPORT ROUTINES:
   tyc_convert()
   tyc_rdindex
   tyc_append_list
   tyc_readascii()
   tyc_readfits()

 PROCEDURES CALLED:
   djs_diff_angle()
   djs_filepath()
   hip_epoch
   mrdfits()
   mwrfits
   radec_to_munu
   splog
   tycho_epoch

 REVISION HISTORY:
   Written D. Schlegel, 31 December 2002, Princeton

(See pro/astrom/tycho_read.pro)


UCAC_READ()

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

 PURPOSE:
   Read the UCAC catalog

 CALLING SEQUENCE:
   outdat = ucac_read( [ racen=, deccen=, radius=, node=, incl=, hwidth=, $
    decrange= ] )

 INPUTS:

 OPTIONAL INPUTS:
   racen:       Central RA for selecting a region of stars [J2000 deg]
   deccen:      Central DEC for selecting a region of stars [J2000 deg]
   radius:      Radius for selecting a region of stars [deg]
   node:        Node of great circle for selecting a stripe of stars [deg]
   incl:        Inclination of great circle for selecting a stripe [deg]
   hwidth:      Half-width of great circle for selecting a stripe [deg]
   decrange   - Declination range for data; default to [-90,90] degrees

 OUTPUT:
   outdat     - Structure with UCAC data in its raw catalog format;
                return 0 if no stars found

 OPTIONAL OUTPUTS:

 COMMENTS:
   Either RACEN, DECCEN, RADIUS must be set, or NODE, INCL, HWIDTH.
   If all keywords are set, the the catalog is trimmed with both sets
   of conditions.

 EXAMPLES:
   a=ucac_read(racen=180.,deccen=0.,radius=0.1)

 BUGS:

 PROCEDURES CALLED:
   cirrange
   djs_diff_angle()
   radec_to_munu
   ucac_readindex()
   ucac_readzone()

 REVISION HISTORY:
   16-Aug-2005  Written by D. Schlegel (LBL)

(See pro/astrom/ucac_read.pro)


UCAC_READINDEX()

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

 PURPOSE:
   Return the indices for seeking within the raw UCAC data files.

 CALLING SEQUENCE:
   uindex = ucac_readindex()

 INPUTS:

 OPTIONAL INPUTS:

 OUTPUT:
   uindex     - Structure with raw UCAC data indices

 OPTIONAL OUTPUTS:

 COMMENTS:

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:
   readfmt

 REVISION HISTORY:
   27-May-2003  Written by David Schlegel, Princeton.

(See pro/astrom/ucac_readindex.pro)


UCAC_READZONE()

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

 PURPOSE:
   Read the raw UCAC data files for a specific declination zone within
   a given RA range.

 CALLING SEQUENCE:
   outdat = ucac_readzone(zone, ra_min, ra_max)

 INPUTS:
   zone       - UCAC zone number (corresponding to a particular declination)
   ra_min     - Minimum RA [deg]
   ra_max     - Maximum RA [deg]

 OPTIONAL INPUTS:

 OUTPUT:
   outdat     - Structure with UCAC data in its raw catalog format;
                return 0 if no stars found

 OPTIONAL OUTPUTS:

 COMMENTS:
   Quantities are de-coded to meaningful units, e.g. converting RA to degrees.

 EXAMPLES:

 BUGS:
   The values of TWOMASS_PH,TWOMASS_CC do not appear to make any
   sense relative to the UCAC documentation.

 PROCEDURES CALLED:
   ucac_readindex()

 REVISION HISTORY:
   27-May-2003  Written by David Schlegel, Princeton.

(See pro/astrom/ucac_readzone.pro)


UNDEFINE

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

 PURPOSE:
       The purpose of this program is to delete or undefine
       an IDL program variable from within an IDL program or
       at the IDL command line. It is a more powerful DELVAR.

 AUTHOR:
       FANNING SOFTWARE CONSULTING
       David Fanning, Ph.D.
       2642 Bradbury Court
       Fort Collins, CO 80521 USA
       Phone: 970-221-0438
       E-mail: davidf@dfanning.com
       Coyote's Guide to IDL Programming: http://www.dfanning.com

 CATEGORY:
       Utilities.

 CALLING SEQUENCE:
       UNDEFINE, variable

 REQUIRED INPUTS:
       variable: The variable to be deleted.

 SIDE EFFECTS:
       The variable no longer exists.

 EXAMPLE:
       To delete the variable "info", type:

        IDL> Undefine, info

 MODIFICATION HISTORY:
       Written by David Fanning, 8 June 97, from an original program
       given to me by Andrew Cool, DSTO, Adelaide, Australia.

(See pro/misc/undefine.pro)


USNOB10_EXTRACT

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

 PURPOSE:
   Extract information from USNO-B1.0 binary data files

 CALLING SEQUENCE:
   a = usnob10_extract(data)
   
 INPUTS:
   data    - ulong array [20, Nstar] read from binary file

 OUTPUTS:
   a       - IDL data structure with positions, proper motions, and 
                up to five magnitudes. 
   
 COMMENTS:
   See http://ftp.nofs.navy.mil/data/fchpix/usnob_format.html
     for descriptions of the fields

 REVISION HISTORY:
   2002-Nov-26   Written by Douglas Finkbeiner, Princeton

(See pro/astrom/usnob10_extract.pro)


USNO_CONE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       usno_cone
+------------------------------------------------------------------------  
 PURPOSE:
       Determine RA,dec regions to read and call usno_readzone
+------------------------------------------------------------------------  
 INPUTS:
   catpath   - catalogue path
   racen     - RA of region center (J2000)    [degrees]
   deccen    - dec of region center (J2000)   [degrees]
   rad       - radius of region               [degrees]

 OPTIONAL INPUTS:
   cattype   - Either 'USNO-A' or 'USNO-B'

+------------------------------------------------------------------------  
 OUTPUTS:
   result    - float(3,N) array of results.  
                 data[0,*] = RA (in .01 arcsec)
                 data[1,*] = (dec+90) (in .01 arcsec)
                 data[2,*] = magnitudes packed in 32-bit int (see below)
+------------------------------------------------------------------------  
 COMMENTS:    
   calls usno_readzone
+------------------------------------------------------------------------  
 REVISION HISTORY
   Written  2000 Apr 15 by D. P. Finkbeiner
   2002-Nov-25  Split from usno_read.pro
                  and modified to work with USNO-B1.0 - DPF
+------------------------------------------------------------------------  

(See pro/astrom/usno_cone.pro)


USNO_READ

[Previous Routine] [Next Routine] [List of Routines]
+------------------------------------------------------------------------  
 NAME:
       usno_read
+------------------------------------------------------------------------  
 PURPOSE:
       Read star list from the USNO-A2.0 catalogue
+------------------------------------------------------------------------  
 INPUTS:
   racen     - RA of region center (J2000)    (degrees) (may be array)
   deccen    - dec of region center (J2000)   (degrees) (may be array)
   rad       - radius of region               (degrees) (may be array)
+------------------------------------------------------------------------  
 OUTPUTS:
   racat,    - (RA,dec) of stars in region (J2000)  (degrees)
     deccat 
   magb      - B magnitude of stars
   magr      - R magnitude
+------------------------------------------------------------------------  
 COMMENTS:    
   Reads US Naval Observatory catalogue v. A2.0 (50,000,000 stars)
     and returns all stars within radius "rad" of (racen,deccen)

   Coords returned are RA,dec J2000 at the epoch of the plates.
   Beware of high proper motion stars.  Typical astrometric error is
   0.25", but can be much worse.  Local errors should be about .15"
 
   For information on the USNO-A2.0 see http://www.usno.navy.mil
+------------------------------------------------------------------------  
 BUGS:
   - Outputs described in header all wrong.
+------------------------------------------------------------------------  
 REVISION HISTORY
   Loosely based on starlist.pro by Doug Finkbeiner and John
   Moustakas, 1999 mar 26

   Written  2000 Apr 15 by D. P. Finkbeiner
   Modified 2000 Apr 18 to use dot product in final trim (DPF)
   Modified 2001 Jul 17 R & B mags were reversed !  (DPF)

+------------------------------------------------------------------------  

(See pro/astrom/usno_read.pro)


USNO_READGC()

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

 PURPOSE:
   Read the UCAC data files for a great circle on the sky.

 CALLING SEQUENCE:
   outdat = usno_readgc(node=node, incl=incl, hwidth=, [ decrange= ])

 INPUTS:
   node       - Node of great circle [degrees]
   incl       - Inclination of great circle [degrees]
   hwidth     - Half-width of great circle for selecting a stripe [deg]

 OPTIONAL INPUTS:
   decrange   - Declination range for data; default to [-90,90] degrees

 OUTPUT:
   outdat     - Structure with UCAC data in its raw catalog format;
                return 0 if no stars found

 OPTIONAL OUTPUTS:

 COMMENTS:

 EXAMPLES:
   a=usno_readgc(node=95.,incl=40.,hwidth=2.5)
   a=usno_readgc(node=95.,incl=10.,hwidth=1.0)

 BUGS:

 PROCEDURES CALLED:
   radec_to_munu
   usno_readindex()
   usno_readzone()

 REVISION HISTORY:
   28-May-2003  Written by D. Schlegel and N. Padmanabhan, Princeton.

(See pro/astrom/usno_readgc.pro)


USNO_READZONE

[Previous Routine] [Next Routine] [List of Routines]
+------------------------------------------------------------------------  
 NAME:
       usno_readzone
+------------------------------------------------------------------------  
 PURPOSE:
       Read given RA range out of one deczone. (USNO-A or B)
+------------------------------------------------------------------------  
 INPUTS:
   catpath   - path to catalogue files (.cat and .acc)
   zone      - zone number (float, 1/10 degrees)
   ra0,ra1   - ra limits [deg]
   rec_len   - record length for each object [bytes] (read as ulongs)
   prefix    - filename prefix: 'zone' for USNOA, 'b' for USNOB

 KEYWORDS:
   swap_if... - USNOA is written little endian, B is big endian(!)
+------------------------------------------------------------------------  
 OUTPUTS:
   data      - float(rec_len/4,N) array of results.  
                 data[0,*] = RA (in .01 arcsec)
                 data[1,*] = (dec+90) (in .01 arcsec)
       USNO-A:
                 data[2,*] = magnitudes packed in 32-bit int
       USNO-B:   
                 data[2:19,*] = all kinds of stuff
+------------------------------------------------------------------------  
 COMMENTS:
   uses point_lun to skip to requested part of file.  Very fast. 

   Requests are padded by 1/10 the interpolation grid spacing.  This
     padding is trimmed unless that would yield a null result. 

   Warning - this routine interpolates file index positions
             and works only if the star distribution is approximately
             uniform (which it is).  
+------------------------------------------------------------------------
 MODIFICATION HISTORY:
  2002-Nov-25 Taken from usno_read by D. Finkbeiner, Princeton
               Also works for USNO-B1.0 now. 

(See pro/astrom/usno_readzone.pro)


UV2LL

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

  PURPOSE: To convert from unit vectors to longitude/latitude

  CALLING SEQUENCE:
    lon_lat = uv2ll(uv)

  INPUT:
    (n,3) unit vector array

  OUTPUT:
    (n,2) longitude/latitude array

  SUBROUTINES CALLED:
    None

  REVISION HISTORY

  SPR 10476  Add Documentation  J.M. Gales  01/21/93

(See pro/astrom/uv2ll.pro)


VMID

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   vmid
 PURPOSE:
   Return vector within a given polygon
 CALLING SEQUENCE:
   vec=vmid(polygon)
 INPUTS:
   polygon - spherical polygon specification
 OPTIONAL INPUTS:
   /allcaps - don't check whether use_caps is set, just assume all
              caps are used
 OUTPUTS:
   vec - [3] location of vector inside
 OPTIONAL INPUT/OUTPUTS:
 COMMENTS:
 EXAMPLES:
 BUGS:
 PROCEDURES CALLED:
 REVISION HISTORY:
   16-Sep-2002  Written by Mike Blanton, NYU

(See pro/mangle/vmid.pro)


VMIDC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   vmidc
 PURPOSE:
   Return vector at barycenter of polygon edges (not necessarily inside!)
 CALLING SEQUENCE:
   vec=vmidc(polygon)
 INPUTS:
   polygon - spherical polygon specification
 OPTIONAL INPUTS:
   /allcaps - don't check whether use_caps is set, just assume all
              caps are used
 OUTPUTS:
   vec - [3] location of barycenter vector
 REVISION HISTORY:
   16-Sep-2002  Written by Mike Blanton, NYU

(See pro/mangle/vmidc.pro)


WCS_COORD2PIX

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

 PURPOSE:
   Transform from a world coordinate system (WCS) to (x,y) pixel numbers.
   This function returns the ZERO-INDEXED pixel position.

   If the FRACTIONAL flag is set, then a fractional pixel position is
   returned.

 CALLING SEQUENCE:
   wcs_coord2pix, lonvec, latvec, hdr, xpix, ypix, [ /fractional ]

 INPUTS:
   lonvec:     Galactic longitude [degrees]
   latvec:     Galactic latitude [degrees]
   hdr:        FITS header data

 OPTIONAL INPUTS:
   fractional: Set this to return fractional rather than integer
               pixel numbers

 OUTPUTS:
   xpix:       X pixel position in range [0,naxis1-1]
   ypix:       Y pixel position in range [0,naxis2-1]

 COMMENTS:
   This conversion routine is based upon the FITS standard of Griesen &
   Calabretta (1996).  Equation numbers refer to that paper.

   At present, only zenithal equal area (ZEA) projections are supported.

   A special case is included for the Lambert projection as defined by
   Schlegel, Finkbeiner & Davis (1998).  Galactic latitude runs clockwise
   from X-axis for NGP, counterclockwise for SGP.
   (CRPIX1, CRPIX2) define the 1-indexed central pixel location of
   the pole.  For example, if CRPIX1=512, then the pole is exactly in
   the middle of 1-indexed pixel number 512; if CRPIX1=512.5, then
   the pole falls between pixel numbers 512 and 513.

 PROCEDURES CALLED:
   djs_angpos()
   sxpar()

 REVISION HISTORY:
   Written by D. Schlegel, 30 May 1996, Durham
   18-Mar-1999  Use of TEMPORARY function to improve memory use
                (D. Finkbeiner).
   30-Mar-1999  Re-written as a general forward conversion for world
                coordinate systems (WCS), though most not yet implemented
                (DJS, DPF).

(See pro/dust/wcs_coord2pix.pro)


WCS_GETVAL

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

 PURPOSE:
   Read value(s) from NGP+SGP polar projections.

 CALLING SEQUENCE:
   value = wcs_getval(files, lonvec, latvec, [ path=path, $
    /interp, /noloop, /verbose ] )

 INPUTS:
   files:      File name(s); if Lambert or ZEA projection, one can pass
               two file names where the first is used for northern points
               and the second for southern points
   lonvec:     Longitude(s) [degrees]
   latvec:     Latitude(s) [degrees]

 OPTIONAL KEYWORDS:
   path:       File name path; default to ''
   interp:     Set this flag to return a linearly interpolated value
               from the 4 nearest pixels
   noloop:     Set this flag to read all values at once without a FOR loop.
               This is a faster option for reading a large number of values,
               but requires reading an entire FITS image into memory.
               (Actually, the smallest possible sub-image is read.)
   verbose:    Set this flag for verbose output, printing pixel coordinates
               and map values.  Setting NOLOOP disables this option.

 OUTPUTS:
   value:      Value(s) from maps

 PROCEDURES CALLED:
   fxread
   headfits()
   sxpar()
   wcs_coord2pix

 REVISION HISTORY:
   31-Mar-1999  Modified from lambert_getval() - D. Schlegel, Princeton

(See pro/dust/wcs_getval.pro)


WEIGHTED_QUANTILE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   weighted_quantile
 PURPOSE:
   given a set of values and weights, returns weighted quantile(s)
 CALLING SEQUENCE:
   quantile= weighted_quantile(values,weights,quant=0.25)
 REVISION HISTORY
   2002-07-ish  written - Blanton

(See pro/math/weighted_quantile.pro)


WHERE_ARRAY

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

 PURPOSE:
 	Return the indices of those elements in vector B which
       exist in vector A.  Basically a WHERE(B IN A)
       where B and A are 1 dimensional arrays.

 CATEGORY:
       Array

 CALLING SEQUENCE:
       result = WHERE_ARRAY(A,B)

 INPUTS:
       A       vector that might contains elements of vector B
       B       vector that we would like to know which of its
               elements exist in A

 OPTIONAL INPUTS:

 KEYWORD PARAMETERS:
       iA_in_B         return instead the indices of A that are in
                       (exist) in B

 OUTPUTS:
       Index into B of elements found in vector A.  If no
       matches are found -1 is returned.  If the function is called
       with incorrect arguments, a warning is displayed, and -2 is
       returned (see SIDE EFFECTS for more info)

 OPTIONAL OUTPUTS:

 COMMON BLOCKS:
               None

 SIDE EFFECTS:
       If the function is called incorrectly, a message is displayed
       to the screen, and the !ERR_STRING is set to the warning
       message.  No error code is set, because the program returns
       -2 already

 RESTRICTIONS:
       This should be used with only Vectors.  Matrices other then
       vectors will result in -2 being returned.  Also, A and B must
       be defined, and must not be strings!

 PROCEDURE:

 EXAMPLE:
       IDL> A=[2,1,3,5,3,8,2,5]
       IDL> B=[3,4,2,8,7,8]
       IDL> result = where_array(a,b)
       IDL> print,result
                  0           0           2           2           3           5
 SEE ALSO:
       where

 MODIFICATION HISTORY:
       Written by:     Dan Carr at RSI (command line version) 2/6/94
                       Stephen Strebel         3/6/94
                               made into a function, but really DAN did all
                               the thinking on this one!
                       Stephen Strebel         6/6/94
                               Changed method, because died with Strings (etc)
                               Used ideas from Dave Landers.  Fast TOO!
                       Strebel 30/7/94
                               fixed checking structure check
                       Smith, JD 9/1/98
                       	Minor Tweak to case of no overlapping members

(See pro/misc/where_array.pro)


WHERE_POLYGONS_OVERLAP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   where_polygons_overlap
 PURPOSE:
   Check which polygons overlap a given polygon
 CALLING SEQUENCE:
   where_polygons_overlap, origpoly, matchpoly, matches, nmatches, $
    [ areamatch= ]
 INPUTS:
   origpoly  - single polygon to check against
   matchpoly - [N] array of polygons to check against origpoly
 OPTIONAL INPUTS:
 OUTPUTS:
   matches - [M<=N] indices of matching polygons (-1 if none)
   nmatches - number of matching polygons
 OPTIONAL INPUT/OUTPUTS:
   areamatch - Overlapping area (Sr)
 COMMENTS:
 EXAMPLES:
 BUGS:
 PROCEDURES CALLED:
 REVISION HISTORY:
   25-Sep-2003  Written by Mike Blanton, NYU

(See pro/mangle/where_polygons_overlap.pro)


WHICH

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

 PURPOSE: 
       To search for any file in the IDL !path that contains the
       user-supplied IDL routine (procedure or function) name.  Also
       returns compilation status of each routine (in IDL lingo,
       whether or not the routine is "resolved".)

 CALLING SEQUENCE:
       WHICH, file

 INPUTS:
       FILE - file name to search for.  The suffix .pro will be
              appended if not included.

 KEYWORD PARAMETERS:
       None.

 OUTPUTS:
       None.

 COMMON BLOCKS:
       None.

 RESTRICTIONS: 
       The IDL !path is searched for file names that are simply the
       module (in IDL documentation, "module" and "routine" are used
       interchangeably) name with a ".pro" suffix appended to them.
       A module stored inside a file whose name is different than the
       module name (followed by a ".pro") will not be found UNLESS
       that module happens to be the currently-resolved module!
       E.g., if the module "pro test_proc" lives in a file named
       "dumb_name.pro", then it will not be found:

       IDL> which, 'test_proc'
       Module TEST_PROC Not Compiled.
       % WHICH: test_proc.pro not found on IDL !path.

       unless it happens to be resolved:

       IDL> .run dumb_name
       % Compiled module: TEST_PROC.
       IDL> which, 'test_proc'
       Currently-Compiled Module TEST_PROC in File:
       /hvc/robishaw/dumb_name.pro

       However, this is terrible programming style and sooner or
       later, if you hide generically-named modules in
       inappropriately-named files, bad things will (deservedly)
       happen to you.

       The routine further assumes that a file named "dumb_name.pro"
       actually contains a module named "dumb_name"!  If it doesn't,
       then you are a bad programmer and should seek professional
       counseling.
 
 PROCEDURES CALLED:
       STRSPLIT(), WHICH_FIND_ROUTINE()

 EXAMPLES:
       You haven't yet resolved (compiled) the routine (module)
       DEFROI.  Let's look for it anyway:

         IDL> which, 'defroi
         Module DEFROI Not Compiled.

         Other Files Containing Module DEFROI in IDL !path:
         /usr/local/rsi/idl/lib/defroi.pro

       For some reason you have two modules with the same name.
       (This can occur in libraries of IDL routines such as the
       Goddard IDL Astronomy User's Library; an updated version of a
       routine is stored in a special directory while the old version
       is stored in its original directory.) Let's see which version
       of the module ADSTRING we are currently using:

         IDL> which, 'adstring.pro'
         Currently-Compiled Module ADSTRING in File:
         /hvc/robishaw/idl/goddard/pro/v5.4+/adstring.pro

         Other Files Containing Module ADSTRING in IDL !path:
         /hvc/robishaw/idl/goddard/pro/astro/adstring.pro

 NOTES:
       First, all currently-compiled procedures and functions are searched.
       Then the remainder of the IDL !path is searched.

 MODIFICATION HISTORY:
   30 May 2003  Written by Tim Robishaw, Berkeley
   17 Feb 2004  Fixed oddity where user tries to call a function as
                if it were a procedure, thus listing the module in both
                the Compiled Functions and Compiled Procedures list.

(See pro/misc/which.pro)


WINDOW_IMAGE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   window_image
 PURPOSE:
   Given a set of mangle polygons, create a pixelized image of the 
   window defined by the polygons. 
 CALLING SEQUENCE:
   image=window_image(polygons [, nx=, ny=, /random])
 INPUTS:
   polygons - list of polygons
 OPTIONAL INPUTS:
   nx - number of ra pixels
   ny - number of dec pixels
   /random - fill image by assigning random points
 OUTPUTS:
 OPTIONAL INPUT/OUTPUTS:
 COMMENTS:
 EXAMPLES:
 BUGS:
 PROCEDURES CALLED:
 REVISION HISTORY:
   30-Nov-2002  Written by MRB (NYU)

(See pro/mangle/window_image.pro)


WRITE_FITS_POLYGONS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   write_fits_polygons
 PURPOSE:
   Write a "polygon" format fits file from the IDL format
 CALLING SEQUENCE:
   write_fits_polygons, outfile, polygons [, hdr= ]
 INPUTS:
   outfile - output file name
   polygons - arrays of structures (eg those made by construct_field_polygon) 
 OPTIONAL INPUTS:
   hdr - put this hdr in 
 COMMENTS:
   The main point of this is to replace caps.x and caps.cm with 
   xcaps and cmcaps columns
 REVISION HISTORY:
   03-Dec-2002  Written by MRB (NYU)

(See pro/mangle/write_fits_polygons.pro)


WRITE_MANGLE_POLYGONS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   write_mangle_polygons
 PURPOSE:
   Create a "polygon" format ascii file that mangle will understand
 CALLING SEQUENCE:
   write_mangle_polygons, outfile, polygons [, id, weight, str, unit=]
 INPUTS:
   outfile - output file name
   polygons - arrays of structures (eg those made by construct_field_polygon) 
 OPTIONAL INPUTS:
   id - array of id's for polygons (should be unique)
   weight - arrays of weights for each polygon
   str - area of each polygon?
   unit - if present, use this unit instead of opening another
 OUTPUTS:
 OPTIONAL INPUT/OUTPUTS:
 COMMENTS:
   The format is lossy --- it only outputs "used" caps, and it throws 
   away auxiliary information about each polygon.
 EXAMPLES:
 BUGS:
 PROCEDURES CALLED:
 REVISION HISTORY:
   07-Nov-2002  Written by MRB (NYU)

(See pro/mangle/write_mangle_polygons.pro)


WSEX

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

 PURPOSE:
       Write out arbitrary SExtractor format catalogs.

 INPUTS:
       A SExtractor-format catalog

 OUTPUTS:
       Prints out a catalog file for the given structure

 COMMON BLOCKS:
       None.

 RESTRICTIONS:
       None.

 PROCEDURE:
       Use syntax
       wset,catalog,outfile='catalog.cat'

 COMMENTS:
       To do -- 
       . better error checking, e.g. for existing output filename,
       etc. 

 PROCEDURES USED:
       VALID_NUM

 MODIFICATION HISTORY:
       L. Moustakas '04feb11 - created

(See pro/misc/wsex.pro)


XY2TRACESET

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

 PURPOSE:
   Convert from an array of x,y positions to a trace set

 CALLING SEQUENCE:
   xy2traceset, xpos, ypos, tset, [ invvar=, func=func, ncoeff=ncoeff, $
    xmin=xmin, xmax=xmax, maxiter=maxiter, inputfunc=inputfunc, $
    inmask=inmask, outmask=outmask, yfit=yfit, inputans=inputans, $
    double=double, silent=silent, _EXTRA=EXTRA ]

 INPUTS:
   xpos       - X positions corresponding to YPOS as an [nx,Ntrace] array
   ypos       - Y centers as an [nx,ntrace] array

 OPTIONAL KEYWORDS:
   invvar     - Inverse variance for weighted fits.
   func       - Function for trace set; options are:
                'poly'
                'legendre'
                'chebyshev'
                'chebyshev_split'
                Default to 'legendre'
   ncoeff     - Number of coefficients in fit; default to 3
   xmin       - Explicitly set XMIN for trace set rather than using minimum
                in XPOS
   xmax       - Explicitly set XMAX for trace set rather than using maximum
                in XPOS
   maxiter    - Maximum number of rejection iterations; set to 0 for no
                rejection; default to 10.
   inmask     - Mask set to 1 for good points and 0 for rejected points;
                same dimensions as XPOS, YPOS.  Points rejected by INMASK
                are always rejected from the fits (the rejection is "sticky"),
                and will also be marked as rejected in OUTMASK.
   inputans   - ???
   inputfunc  - An array which matches the size of ypos, which is multiplied
                  to the normal function before SVD decomposition
   double     - If set, then the traceset will contain all double-precision
                values, which will occur anyway if XPOS, YPOS or INVVAR
                are double-precision
   silent     - Set to suppress print and splog outputs
   EXTRA      - Keywords passed to either the function FUNC, or DJS_REJECT().
                Note that keywords like MAXREJ relate to each individual trace.

 OUTPUTS:
   tset       - Structure containing trace set

 OPTIONAL OUTPUTS:
   outmask    - Mask set to 1 for good points and 0 for rejected points;
                same dimensions as XPOS, YPOS.
   yfit       - Fit values at each XPOS.

 COMMENTS:
   The fits are done to one trace at a time, where each trace is treated
   completely independently.

   Note that both MAXDEV and MAXSIG can be set for applying both rejection
   schemes at once.

   Additional keywords can be passed to the fitting functions with _EXTRA.
   By not setting any of these rejection keywords, no rejection is performed.

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:
   djs_reject()
   fchebyshev()
   fchebyshev_split()
   flegendre()
   fpoly()
   func_fit()

 REVISION HISTORY:
   19-May-1999  Written by David Schlegel, Princeton.
   04-Aug-1999  Added chebyshev option (DJS).
   02-Sep-2000  Modify to use rejection schemes in DJS_REJECT() (DJS).
   07-Dec-2000  Added /silent keyword (DPF)
   10-Jul-2001  Add polynomial option

(See pro/trace/xy2traceset.pro)


XYZ_TO_ANGLES

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
  xyz_to_angles
 PURPOSE:
  Convert Cartesian coordinates (x,y,z) to spherical coordinates
  (r,phi,theta).  The returned angles are 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.
  Note that RA=phi and DEC=90-theta.
 BUGS:
  - May have divide by zero issues. But why would anyone run this
    with r=0??
 REVISION HISTORY:
  2005-09-10  tweaked - Hogg (NYU)

(See pro/coord/xyz_to_angles.pro)


YANNY_DIFF

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

 PURPOSE:
   Compare two Yanny files, optionally copying values from one to another.

 CALLING SEQUENCE:
   yanny_diff, filename1, filename2, [ outfile, $
    cardnames=, stnames=, /verbose, count=, errcode= ]

 INPUTS:
   filename1  - Yanny parameter file from which copy cards
   filename2  - Yanny parameter file to which copy cards

 OPTIONAL INPUTS:
   outfile    - If specified, then write the modified 2nd file to this file.
   stnames    - The Yanny structure names to compare between the two
                input files; if not set, then compare all structures that
                exist in the 2nd file.  These names are case-insensitive.
   cardnames  - The tag names in any structure to compare; if not set,
                then compare all tags that exist in the 2nd file.
                Note that if this is set to 'FOO', then that tag is
                compared (if it exists) between all specified structures.
                These names are case-insensitive.
   verbose    - If set, then explicitly print each change that is made;
                if not set, then simply print the number of changes made.

 OUTPUT:

 OPTIONAL OUTPUTS:
   count      - The total number of elements that differ.
   errcode    - Return 0 upon successful completion, non-zero otherwise.
                A code of -1 means that there were errors reading the
                input files.  A code of +1 means that the number of
                rows or elements in the input structures did not agree.
                In the latter case, changes are still made to any other
                structure elements where the numbers do agree.

 COMMENTS:

 EXAMPLES:
   Simply compare two opECalib files, printing any differences:
     IDL> yanny_diff,'opECalib-50000.par','opECalib-51430.par',/verbose

   Compare the same two files, but copy values for the structure
   ecalib.fullwelldn2 from the 1st file to the 2nd, creating a 3rd file:
     IDL> yanny_diff,'opECalib-50000.par','opECalib-51430.par', $
     IDL>  'opECalib-new.par', stnames='ecalib', cardnames='fullwelldn2'

 BUGS:

 PROCEDURES CALLED:
   splog
   yanny_free
   yanny_read
   yanny_write

 REVISION HISTORY:
   26-Feb-2002  Written by David Schlegel, Princeton.

(See pro/yanny/yanny_diff.pro)


YANNY_FREE

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

 PURPOSE:
   Free memory allocated from reading a Yanny parameter file

 CALLING SEQUENCE:
   yanny_free, pdata

 INPUTS:
   pdata      - Array of pointers to all strucutures read by YANNY_READ.

 OPTIONAL INPUTS:

 OUTPUT:

 OPTIONAL OUTPUTS:

 COMMENTS:

 EXAMPLES:

 BUGS:

 PROCEDURES CALLED:

 REVISION HISTORY:
   15-Nov-1999  Written by David Schlegel, Princeton.

(See pro/yanny/yanny_free.pro)


YANNY_PAR

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

 PURPOSE:
   Obtain the value of a parameter in the header of a Yanny file.

 CALLING SEQUENCE:
   result = yanny_par( hdr, keyname, [count=, indx= ] )

 INPUTS:
   hdr        - Header lines in Yanny file, which are usually keyword pairs.
   keyname    - Keyword name of which to find its corresponding value.
                If this is an array, then this routine is called recursively
                and the results appended together.

 OPTIONAL INPUTS:

 OUTPUT:
   result     - Value of parameter in header as either a string or an
                array of strings; return '' if parameter not found

 OPTIONAL OUTPUTS:
   count      - Return the number of parameters found.  There may be more
                returned values than INDX, if there are several values on
                the same line.
   indx       - Index of the lines that match (0-indexed); -1 for no match.

 COMMENTS:
   This routine is meant to be analogous to the Goddard function SXPAR()
   for reading from FITS headers.

 EXAMPLES:

 BUGS:
   Wildcards are not supported for KEYNAME.

 PROCEDURES CALLED:

 INTERNAL SUPPORT ROUTINES:

 REVISION HISTORY:
   02-Nov-1999  Written by David Schlegel, Princeton.

(See pro/yanny/yanny_par.pro)


YANNY_READ

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

 PURPOSE:
   Read a Yanny parameter file into an IDL structure.

 CALLING SEQUENCE:
   yanny_read, filename, [ pdata, hdr=, enums=, structs=, $
    /anonymous, stnames=, /quick, errcode= ]

 INPUTS:
   filename   - Input file name for Yanny parameter file

 OPTIONAL INPUTS:

 OUTPUT:

 OPTIONAL OUTPUTS:
   pdata      - Array of pointers to all structures read.  The i-th data
                structure is then referenced with "*pdata[i]".  If you want
                to pass a single structure (eg, FOOBAR), then pass
                ptr_new(FOOBAR).
   hdr        - Header lines in Yanny file, which are usually keyword pairs.
   enums      - All "typedef enum" structures.
   structs    - All "typedef struct" structures, which define the form
                for all the PDATA structures.
   anonymous  - If set, then all returned structures are anonymous; set this
                keyword to avoid possible conflicts between named structures
                that are actually different.
   stnames    - Names of structures.  If /ANONYMOUS is not set, then this
                will be equivalent to the IDL name of each structure in PDATA,
                i.e. tag_names(PDATA[0],/structure_name) for the 1st one.
                This keyword is useful for when /ANONYMOUS must be set to
                deal with structures with the same name but different defns.
   quick      - This keyword is only for backwards compatability, and
                has no effect.
   errcode    - Returns as non-zero if there was an error reading the file.

 COMMENTS:
   If the file name suffix is '.gz' or '.Z', the uncompress the file
   while reading.  The gunzip command is spawned for '.gz' files, and
   'uncompress' is spawned for '.Z' files.

   Return 0's if the file does not exist.

   Read and write variables that are denoted INT in the Yanny file
   as IDL-type LONG, and LONG as IDL-type LONG64.  This is because
   Yanny files assume type INT is a 4-byte integer, whereas in IDL
   that type is only 2-byte.

   I special-case the replacement of {{}} with "", since it seems
   that some bonehead used the former to denote blank strings in
   the idReport files.  Otherwise, any curly-brackets are always ignored
   (as they should be).

 EXAMPLES:

 BUGS:
   The reading could probably be sped up by setting a format string for
   each structure to use in the read.

   Not set up yet to deal with multi-dimensional arrays, but neither
   is the fTCL-based reader.

 PROCEDURES CALLED:
   fileandpath()
   hogg_strsplit
   hogg_unquoted_regex()
   mrd_struct
   numlines

 INTERNAL SUPPORT ROUTINES:
   yanny_strip_commas()
   yanny_add_comment
   yanny_getwords()
   yanny_add_pointer
   yanny_readstring
   yanny_nextline()

 REVISION HISTORY:
   05-Sep-1999  Written by David Schlegel, Princeton.
   18-Jun-2001  Fixed bug to allow semi-colons within double quotes
                C. Tremonti (added yanny_inquotes, modifed yanny_strip_commas,
                yanny_nextline)
   11-Oct-2002  Major changes by D. Schlegel and D. Hogg to get rid
                of the 2048-char line limit, dramatically speed up the
                code when reading large files by pre-allocating the memory,
                and use regular-expression matching for speed, robustness,
                and clarity.

(See pro/yanny/yanny_read.pro)


YANNY_READONE

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

 PURPOSE:
   Read one structure from a Yanny parameter file into an IDL structure.

 CALLING SEQUENCE:
   data = yanny_readone( filename, [ selectname, hdr=, enums=, structs=, $
    /anonymous, stnames=, /quick, errcode= ] )

 INPUTS:
   filename   - Input file name for Yanny parameter file

 OPTIONAL INPUTS:
   selectname - Name of structure to select.  If not specified, then
                the first structure is returned.

 OUTPUT:
   data       - Selected structure, or 0 if not found.

 OPTIONAL OUTPUTS:
   hdr        - Header lines in Yanny file, which are usually keyword pairs.
   enums      - All "typedef enum" structures.
   structs    - All "typedef struct" structures, which define the form
                for all the PDATA structures.
   anonymous  - If set, then all returned structures are anonymous; set this
                keyword to avoid possible conflicts between named structures
                that are actually different.
   stnames    - Names of structures.  If /ANONYMOUS is not set, then this
                will be equivalent to the IDL name of each structure in PDATA,
                i.e. tag_names(PDATA[0],/structure_name) for the 1st one.
                This keyword is useful for when /ANONYMOUS must be set to
                deal with structures with the same name but different defns.
                Note that this will contain all of the structure names, even
                though this routine only returns that data from one of them.
   quick      - This keyword is only for backwards compatability, and
                has no effect.
   errcode    - Returns as non-zero if there was an error reading the file.

 COMMENTS:
   This is a simple wrapper for YANNY_READ.

 EXAMPLES:
   Select the IDCOMMENT structure from the Yanny file idReport-52522.par.
   Set the /ANONYMOUS flag to prevent conflicts with any other structures
   of the same name.
     IDL> data = yanny_readone('idReport-52522.par', 'IDCOMMENT', /anon)

 BUGS:

 PROCEDURES CALLED:
   yanny_free
   yanny_read

 REVISION HISTORY:
   05-Oct-2002  Written by David Schlegel, Princeton.

(See pro/yanny/yanny_readone.pro)


YANNY_WRITE

[Previous Routine] [List of Routines]
 NAME:
   yanny_write

 PURPOSE:
   Write a Yanny parameter file from an IDL structure.

 CALLING SEQUENCE:
   yanny_write, filename, [ pdata, hdr=, enums=, structs=, stnames=, $
    /align, formatcodes=, fdigit=, ddigit= ]

 INPUTS:
   filename   - Output file name for Yanny parameter file

 OPTIONAL INPUTS:
   pdata      - Array of pointers to all structures write.  The i-th data
                structure is then referenced with "*pdata[i]"
   hdr        - Header lines in Yanny file, which are usually keyword pairs.
   enums      - All "typedef enum" structures.
   structs    - All "typedef struct" structures, which define the form
                for all the PDATA structures.
   stnames    - Structure names, overriding the IDL structure names.
                Typically, you will want to use this if a structure was
                read using the /ANONYMOUS keyword.
   align      - If set, then align columns in the output file
   formatcodes- Passed to STRUCT_PRINT() if /ALIGN is also set.
   fdigit     - Passed to STRUCT_PRINT() if /ALIGN is also set.
   ddigit     - Passed to STRUCT_PRINT() if /ALIGN is also set.

 OUTPUT:

 OPTIONAL OUTPUTS:

 COMMENTS:
   Read and write variables that are denoted INT in the Yanny file
   as IDL-type LONG, and LONG as IDL-type LONG64.  This is because
   Yanny files assume type INT is a 4-byte integer, whereas in IDL
   that type is only 2-byte.

 EXAMPLES:
   Read a Yanny parameter file, then re-write as a different file with:
     yanny_read, 'testin.par', pdata, comments=comments
     yanny_write, 'testout.par', pdata, comments=comments

 BUGS:
   There is no testing that STRUCTS is consistent with PDATA when that
   keyword is explicitly passed to define the header of the file rather
   than auto-generating it from PDATA itself.

   If FORMATCODES is set, then it is possible to write invalid Yanny files.
   For example, if a format code of 'a5' is set for strings that are longer,
   then any terminating quotations beyond the 5th character will be lost.
   If a format code is too small for a numeric value, then a set of asterisks
   will be written.

 PROCEDURES CALLED:

 REVISION HISTORY:
   05-Sep-1999  Written by David Schlegel, Princeton.

(See pro/yanny/yanny_write.pro)