This page was created by the IDL library routine
mk_html_help
. For more information on
this routine, refer to the IDL Online Help Navigator
or type:
? mk_html_help
at the IDL command line prompt.
Last modified: Wed Jan 19 14:51:52 2005.
NAME: ABSCAL PURPOSE: Apply the FITS BZERO and BSCALE keyword values to a data array CALLING SEQUENCE: RESULT = ABSCAL( Value, Header, /DEBUG) INPUTS: VALUE - Any scalar, vector, or array (usually an integer type giving a relative intensity). HEADER - A FITS header array containing the absolute calibration keyword BSCALE, and optionally BZERO and BUNIT. OUTPUT: RESULT = BSCALE*VALUE + BZERO, where the BSCALE and BZERO scalars are taken from the FITS header. If the absolute calibration keywords do not exist, then RESULT = VALUE, and !ERR = -1. OPTIONAL INPUT KEYWORD: DEBUG - If DEBUG is set, then ABSCAL will print the calibration units given by the BUNIT keyword. REVISION HISTORY: Written W. Landsman, STX Corporation January 1987 Use DEBUG keyword instead of !DEBUG September 1995 Converted to IDL V5.0 W. Landsman September 1997
(See abscal.pro)
NAME: AD2XY PURPOSE: Compute X and Y from RA and DEC and a FITS astrometry structure EXPLANATION: A tangent (gnomonic) projection is computed directly; other projections are computed using WCSXY2SPH. AD2XY is meant to be used internal to other procedures. For interactive purposes, use ADXY. CALLING SEQUENCE: AD2XY, a ,d, astr, x, y INPUTS: A - R.A. in DEGREES, scalar or vector D - Dec. in DEGREES, scalar or vector ASTR - astrometry structure, output from EXTAST procedure containing: .CD - 2 x 2 array containing the astrometry parameters CD1_1 CD1_2 in DEGREES/PIXEL CD2_1 CD2_2 .CDELT - 2 element vector giving increment at reference point in DEGREES/PIXEL .CRPIX - 2 element vector giving X and Y coordinates of reference pixel (def = NAXIS/2) .CRVAL - 2 element vector giving R.A. and DEC of reference pixel in DEGREES .CTYPE - 2 element vector giving projection types OUTPUTS: X - row position in pixels, scalar or vector Y - column position in pixels, scalar or vector REVISION HISTORY: Converted to IDL by B. Boothman, SASC Tech, 4/21/86 Use astrometry structure, W. Landsman Jan. 1994 Do computation correctly in degrees W. Landsman Dec. 1994 Only pass 2 CRVAL values to WCSSPH2XY W. Landsman June 1995 Don't subscript CTYPE W. Landsman August 1995 Converted to IDL V5.0 W. Landsman September 1997
(See ad2xy.pro)
NAME: ADSTRING PURPOSE: Return RA and Dec as character string in sexigesimal format. EXPLANATION: RA and Dec may be entered as either a 2 element vector or as 2 scalars. One can also specify the precision of the declination in digits after the decimal point. CALLING SEQUENCE result = ADSTRING( ra_dec ) or result = ADSTRING( ra,dec,[ precision ] ) INPUTS: RA_DEC - 2 element vector giving the Right Ascension and declination in decimal degrees. or RA - Right ascension in decimal degrees, numeric scalar DEC - Declination in decimal degrees, numeric scalar OPTIONAL INPUT: PRECISION - Integer scalar (0-4) giving the number of digits after the decimal of DEClination. The RA is automatically 1 digit more. This parameter may either be the third parameter after RA,DEC or the second parameter after [RA,DEC]. It is not available for just DEC. If no PRECISION parameter is passed, a precision of 1 for both RA and DEC is returned to maintain compatibility with past ADSTRING functions. Values of precision larger than 4 will be truncated to 4. If PRECISION is 3 or 4, then RA and Dec should be input as double precision. OUTPUT: RESULT - Character string containing HR,MIN,SEC,DEC,MIN,SEC formatted as ( 2I3,F5.(p+1),2I3,F4.p ) where p is the PRECISION parameter. If only a single scalar is supplied it is converted to a sexigesimal string (2I3,F5.1). EXAMPLE: (1) Display CRVAL coordinates in a FITS header, H IDL> crval = sxpar(h,'CRVAL*') ;Extract 2 element CRVAL vector (degs) IDL> print, adstring(crval) ;Print CRVAL vector sexigesimal format (2) print,adstring(30.42,-1.23,1) ==> ' 02 01 40.80 -01 13 48.0' print,adstring(30.42,+0.23) ==> ' 02 01 40.8 +00 13 48.0' print,adstring(+0.23) ==> '+00 13 48.0' PROCEDURES CALLED: RADEC, SIXTY() REVISION HISTORY: Written W. Landsman June 1988 Addition of variable precision and DEC seconds precision fix. ver. Aug. 1990 [E. Deutsch] Output formatting spiffed up October 1991 [W. Landsman] Remove ZPARCHECK call, accept 1 element vector April 1992 [W. Landsman] Call ROUND() instead of NINT() February 1996 [W. Landsman] Check roundoff past 60s October 1997 [W. Landsman] Work for Precision =4 November 1997 [W. Landsman] Converted to IDL V5.0 W. Landsman 24-Nov-1997
(See adstring.pro)
NAME: ADXY PURPOSE: Use a FITS header to convert celestial (RA,Dec) to pixel coordinates EXPLANATION: Use an image header to compute X and Y positions, given the RA and Dec in decimal degrees. CALLING SEQUENCE: ADXY, HDR ;Prompt for Ra and DEC ADXY, hdr, a, d, x, y, [ /PRINT ] INPUTS: HDR - FITS Image header containing astrometry parameters OPTIONAL INPUTS: A - Right ascension in decimal DEGREES, scalar or vector D - Declination in decimal DEGREES, scalar or vector If A and D are not supplied, user will be prompted to supply them in either decimal degrees or HR,MIN,SEC,DEG,MN,SC format. OPTIONAL OUTPUT: X - row position in pixels, same number of elements as A and D Y - column position in pixels OPTIONAL KEYWORD INPUT: PRINT - If this keyword is set and non-zero, then results are displayed at the terminal. OPERATIONAL NOTES: If less than 5 parameters are supplied, or if the /PRINT keyword is set, then then the X and Y positions are displayed at the terminal. If the procedure is to be used repeatedly with the same header, then it would be faster to use AD2XY. PROCEDURES CALLED: AD2XY, ADSTRING(), EXTAST, GETOPT() REVISION HISTORY: W. Landsman HSTX January, 1988 Use astrometry structure W. Landsman January, 1994 Changed default ADSTRING format W. Landsman September, 1995 Converted to IDL V5.0 W. Landsman September 1997
(See adxy.pro)
NAME: AFhread PURPOSE: Subroutine of WFPCREAD to read a GEIS header from an HST STSDAS image. EXPLANATION: This procedure reads a GEIS header from an HST image. It then looks if a .SHH file is present for FOC images to calculate better astrometry by getting the current PSANGLV3 from this file. Called by WFPCREAD.PRO CALLING SEQUENCE: AFhread, HdrFile, hdr INPUTS: HdrFile - scalar string giving name of STSDAS header for an FOC image OUTPUTS: hdr - string array, FITS header for the FOC image. The position angle of the V3 axis of HST (PSANGLV3) is added, if it could be found in the .SHH file REVISION HISTORY: Written Eric W. Deutsch (U. of Washington) June, 1994 Documentation update W. Landsman (HSTX) July, 1994 Converted to IDL V5.0 W. Landsman September 1997
(See afhread.pro)
NAME: AIRTOVAC PURPOSE: Convert air wavelengths to vacuum wavelengths EXPLANATION: Wavelengths are corrected for the index of refraction of air under standard conditions. Wavelength values below 2000 A will not be altered. Uses the IAU standard for conversion given in Morton (1991 Ap.J. Suppl. 77, 119) CALLING SEQUENCE: AIRTOVAC, WAVE INPUT/OUTPUT: WAVE - Wavelength in Angstroms, scalar or vector WAVE should be input as air wavelength(s), it will be returned as vacuum wavelength(s). WAVE is always converted to double precision upon return. EXAMPLE: If the air wavelength is W = 6056.125 (a Krypton line), then AIRTOVAC, W yields an vacuum wavelength of W = 6057.8019 METHOD: See Morton (Ap. J. Suppl. 77, 119) for the formula used REVISION HISTORY Written W. Landsman November 1991 Converted to IDL V5.0 W. Landsman September 1997
(See airtovac.pro)
NAME: AITOFF PURPOSE: Convert Right Ascension, Declination to X,Y using an AITOFF projection. EXPLANATION: This procedure can be used to create an all-sky map in Galactic coordinates with an equal-area Aitoff projection. Output map coordinates are zero longitude centered. CALLING SEQUENCE: AITOFF, L, B, X, Y INPUTS: L - longitude - scalar or vector, in degrees B - latitude - same number of elements as L, in degrees OUTPUTS: X - X coordinate, same number of elements as L. X is normalized to be between -180 and 180 Y - Y coordinate, same number of elements as L. Y is normalized to be between -90 and 90. NOTES: See AIPS memo No. 46, page 4, for details of the algorithm. This version of AITOFF assumes the projection is centered at b=0 degrees. REVISION HISTORY: Written W.B. Landsman STX December 1989 Modified for Unix: J. Bloch LANL SST-9 5/16/91 1.1 Converted to IDL V5.0 W. Landsman September 1997
(See aitoff.pro)
NAME: AITOFF_GRID PURPOSE: Produce an overlay of latitude and longitude lines over a plot or image EXPLANATION: The grid is plotted on the current graphics device. AITOFF_GRID assumes that the ouput plot coordinates span the x-range of -180 to 180 and the y-range goes from -90 to 90. CALLING SEQUENCE: AITOFF_GRID[,DLONG,DLAT,[LINESTYLE=N,/LABELS] INPUTS: DLONG = Optional input longitude line spacing in degrees. If left out, defaults to 30. DLAT = Optional input lattitude line spacing in degrees. If left out, defaults to 30. KEYWORDS: LINESTYLE = Optional input integer specifying the linestyle to use for drawing the grid lines. LABELS = Optional keyword specifying that the lattitude and longitude lines on the prime meridian and the equator should be labeled in degrees. If LABELS is given a value of 2, i.e. LABELS=2, then the longitude labels will be in hours and minutes instead of degrees. OUTPUTS: Draws grid lines on current graphics device. CATAGORY: SST-9 Graphics routine. AUTHOR AND MODIFICATIONS: J. Bloch 1.2 6/2/91 Converted to IDL V5.0 W. Landsman September 1997
(See aitoff_grid.pro)
NAME: APER PURPOSE: Compute concentric aperture photometry (adapted from DAOPHOT) EXPLANATION: APER can compute photometry in several user-specified aperture radii. A separate sky value is computed for each source using specified inner and outer sky radii. CALLING SEQUENCE: APER, image, xc, yc, [ mags, errap, sky, skyerr, phpadu, apr, skyrad, badpix, PRINT = , /SILENT, /FLUX, SETSKYVAL = ] INPUTS: IMAGE - input image array XC - vector of x coordinates. YC - vector of y coordinates OPTIONAL INPUTS: PHPADU - Photons per Analog Digital Units, numeric scalar. Converts the data numbers in IMAGE to photon units. (APER assumes Poisson statistics.) APR - Vector of up to 12 REAL photometry aperture radii. SKYRAD - Two element vector giving the inner and outer radii to be used for the sky annulus BADPIX - Two element vector giving the minimum and maximum value of a good pix (Default [-32765,32767]) OPTIONAL KEYWORD INPUTS: PRINT - if set and non-zero then APER will also write its results to a file APER.PRT. One can specify the output file name by setting PRINT = 'filename'. SILENT - If supplied and non-zero then no output is displayed to the terminal. FLUX - If set, output fluxes instead of magnitudes. SETSKYVAL - Use this keyword to force the sky to a specified value rather than have APER compute a sky value. SETSKYVAL can either be a scalar specifying the sky value to use for all sources, or a 3 element vector specifying the sky value, the sigma of the sky value, and the number of elements used to compute a sky value. The 3 element form of SETSKYVAL is needed for accurate error budgeting. OUTPUTS: MAGS - NAPER by NSTAR array giving the magnitude for each star in each aperture. (NAPER is the number of apertures, and NSTAR is the number of stars). A flux of 1 digital unit is assigned a zero point magnitude of 25. ERRAP - NAPER by NSTAR array giving error in magnitude for each star. If a magnitude could not be deter- mined then ERRAP = 9.99. SKY - NSTAR element vector giving sky value for each star SKYERR - NSTAR element vector giving error in sky values PROCEDURES USED: DATATYPE(), GETOPT, MMM, STRN(), STRNUMBER() REVISON HISTORY: Adapted to IDL from DAOPHOT June, 1989 B. Pfarr, STX Adapted for IDL Version 2, J. Isensee, July, 1990 Code, documentation spiffed up W. Landsman August 1991 TEXTOUT may be a string W. Landsman September 1995 FLUX keyword added J. E. Hollis, February, 1996 SETSKYVAL keyword, increase maxsky W. Landsman, May 1997 Work for more than 32767 stars W. Landsman, August 1997 Converted to IDL V5.0 W. Landsman September 1997
(See aper.pro)
NAME: ARCBAR PURPOSE: Draw an arc bar on an image showing the astronomical plate scale CALLING SEQUENCE: ARCBAR, hdr, arclen,[ COLOR= , /DATA, LABEL= , /NORMAL, POSITION =, /SECONDS, SIZE=, THICK= ] INPUTS: hdr - image FITS header with astrometry, string array arclen - numeric scalar giving length of bar in arcminutes (default) or arcseconds (if /SECONDS is set) OPTIONAL KEYWORD INPUTS: COLOR - integer scalar specifying the color to draw the arcbar (using PLOTS), default = !P.COLOR DATA - if set and non-zero, then the POSITION keyword is given in data units LABEL - string giving user defined label for bar. Default label is size of bar in arcminutes NORMAL - if this keyword is set and non-zero, then POSITION is given in normalized units POSITION - 2 element vector giving the (X,Y) position in device units (or normalized units if /NORMAL is set, or data units if /DATA is set) at which to place the scale bar. If not supplied, then the user will be prompted to place the cursor at the desired position SIZE - scalar specifying character size of label, default = 1.0 THICK - Character thickness of the label, default = !P.THICK EXAMPLE: Place a 3' arc minute scale bar, at position 300,200 of the current image window, (which is associated with a FITS header, HDR) IDL> arcbar, HDR, 3, pos = [300,200] RESTRICTIONS: When using using a device with scalable pixels (e.g. postscript) the data coordinate system must be established before calling ARCBAR. If data coordinates are not set, then ARCBAR assumes that the displayed image size is given by the NAXIS1 keyword in the FITS header. PROCEDURE CALLS: AD2XY, EXTAST, GSSSADXY REVISON HISTORY: written by L. Taylor (STX) from ARCBOX (Boothman) modified for Version 2 IDL, B. Pfarr, STX, 4/91 New ASTROMETRY structures W.Landsman, HSTX, Jan 94 Recognize a GSSS header W. Landsman June 94 Added /NORMAL keyword W. Landsman Feb. 96 Use NAXIS1 for postscript if data coords not set, W. Landsman Aug 96 Fixed typo for postscript W. Landsman Oct. 96 Account for zeropoint offset in postscript W. Landsman Apr 97 Converted to IDL V5.0 W. Landsman September 1997 Added /DATA, /SECONDS keywords W. Landsman July 1998
(See arcbar.pro)
NAME: ARROWS PURPOSE: To display "weathervane" directional arrows on an astronomical image EXPLANATION: Overlays a graphic showing orientation of North and East. CALLING SEQUENCE: ARROWS,h, [ xcen, ycen, ARROWLEN= , CHARSIZE= COLOR= , /DATA FONT=, /NORMAL, /NOTVERTEX, THICK= ] INPUTS: h - FITS or STSDAS header array, must include astrometry OPTIONAL INPUTS: xcen,ycen - numeric scalars, specifying the center position of arrows. Position in device units unless the /NORMALIZED keyword is specified. If not supplied, then ARROWS will prompt for xcen and ycen OPTIONAL KEYWORD INPUTS: arrowlen - length of arrows in terms of normal Y size of vector-drawn character, default = 3.5, floating point scalar charsize - character size, default = 2.0, floating point scalar color - color that the arrows and NE letters should be. Default value is !P.COLOR Data - if this keyword is set and nonzero, the input center (xcen, ycen) is understood to be in data coordinates font - IDL vector font number (1-20) to use to display NE letters. For example, set font=13 to use complex italic font. NotVertex - Normally (historically) the specified xcen,ycen indicated the position of the vertex of the figure. If this keyword is set, the xcen,ycen coordinates refer to a sort of 'center of mass' of the figure. This allows the figure to always appear with the area irregardless of the rotation angle. Normal - if this keyword is set and nonzero, the input center (xcen,ycen) is taken to be in normalized coordinates. The default is device coordinates. thick - line thickness, default = 1.0, floating point scalar OUTPUTS: none EXAMPLE: Draw a weathervane at (400,100) on the currently active window, showing the orientation of the image associated with a FITS header, hdr IDL> arrows, hdr, 400, 100 METHOD: Uses EXTAST to EXTract ASTrometry from the FITS header. The directions of North and East are computed and the procedure ONE_ARROW called to create the "weathervane". PROCEDURES USED: EXTAST - Extract astrometry structure from FITS header ONE_ARROW - Draw a labeled arrow ZPARCHECK REVISON HISTORY: written by B. Boothman 2/5/86 Recoded with new procedures ONE_ARROW, ONE_RAY. R.S.Hill,HSTX,5/20/92 Added separate determination for N and E arrow to properly display arrows irregardless of handedness or other peculiarities and added /NotVertex keyword to improve positioning of figure. E.Deutsch 1/10/93 Added /DATA and /NORMAL keywords W. Landsman July 1993 Recognize GSSS header W. Landsman June 1993 Added /FONT keyword W. Landsman April 1995 Modified to work correctly for COLOR=0 J.Wm.Parker, HITC 1995 May 25 Work correctly for negative CDELT values W. Landsman Feb. 1996 Converted to IDL V5.0 W. Landsman September 1997
(See arrows.pro)
NAME: ASTDISP PURPOSE: Print astronomical and pixel coordinates in a standard format EXPLANATION: This procedure (ASTrometry DISPlay) prints the astronomical and pixel coordinates in a standard format. X,Y must be supplied. RA,DEC may also be supplied, and a data number (DN) may also be supplied. With use of the Coords= keyword, a string containing the formatted data can be returned in addition or instead (with /silent) of printing. CALLING SEQUENCE: ASTDISP, x, y, [Ra, Dec, DN, COORD = , /SILENT ] INPUT: X - The X pixel coordinate(s), scalar or vector Y - The Y pixel coordinate(s), scalar or vector OPTIONAL INPUTS: RA - Right Ascention in *degrees*, scalar or vector DEC - DEClination in *degrees*, scalar or vector (if RA is supplied, DEC must also be supplied) DN - Data Number or Flux values Each of the inputs X,Y, RA, DEC, DN should have the same number of elements OPTIONAL INPUT KEYWORDS: SILENT Prevents printing. Only useful when used with Coords= OUTPUT: Printed positions in both degrees and sexigesimal format All passed variables remain unchanged OPTIONAL KEYWORD OUTPUT: COORDS Returns the formatted coordinates in a string PROCEDURES CALLED: ADSTRING - used to format the RA and Dec HISTORY: 10-AUG-90 Version 1 written by Eric W. Deutsch 20-AUG-91 Converted to standard header. Vectorized Code. E. Deutsch 20-NOV-92 Added Coords= and /silent. E.Deutsch Converted to IDL V5.0 W. Landsman September 1997
(See astdisp.pro)
NAME: ASTRMFIX PURPOSE: Calculate a rough HST WFPC or FOC astrometry solution EXPLANATION: This program will calculate a rough HST WFPC or FOC astrometry solution using the keyword PSANGLEV3 which gives the angle of the V3 axis of HST. Called by WFPCREAD. CALLING SEQUENCE: AstrmFix, hdr, chip INPUT - OUTPUT: hdr - FITS header (string array) from either WFPC or FOC. Header will be updated with rough astrometry INPUT: chip - Scalar (typically 0-3) giving the WFPC chip to read. HISTORY: ??-???-???? Written by Eric W. Deutsch 22-OCT-1992 Changed all calculations to double precision. (E. Deutsch) 22-OCT-1992 Updated PC Pixel size of 0.04389 from WFPC IDT OV/SV manual(EWD) 22-OCT-1992 Updated WF Pixel size of 0.1016 from WFPC IDT OV/SV manual(EWD) 11-JAN-1993 Added warning message and changed CD001001... to CD1_1... (EWD) Converted to IDL V5.0 W. Landsman September 1997
(See astrmfix.pro)
NAME: ASTRO PURPOSE: Interactive utility to compute precession or coordinate conversions. CALLING SEQUENCE: ASTRO, [ selection, EQUINOX = ] OPTIONAL INPUT: SELECTION - Scalar Integer (0-6) giving the the particular astronomical utility to be used. (0) Precession, (1) RA, Dec to Galactic coordinates, (2) Galactic to RA,Dec (3) RA,Dec to Ecliptic, (4) Ecliptic to RA, Dec, (5) Ecliptic to Galactic, (6) Galactic to Ecliptic. Program will prompt for SELECTION if this parameter is omitted. OPTIONAL KEYWORD INPUT: EQUINOX - numeric scalar specifying the equinox to use when converting between celestial and other coordinates. If not supplied, then the RA and Dec will be assumed to be in EQUINOX 1950. This keyword is ignored by the precession utility. For example, to convert from RA and DEC (2000) to galactic coordinates: IDL> astro, 1, E=2000 METHOD: ASTRO uses PRECESS to compute precession, and EULER to compute coordinate conversions. The procedure GET_COORDS is used to read the coordinates, and ADSTRING to format the RA,Dec output. NOTES: ASTRO temporarily sets !QUIET to suppress compilation messages and keep a pretty screen display. PROCEDURES USED: Procedures: GET_COORDS, EULER Function: ADSTRING REVISION HISTORY Written, W. Landsman November 1987 Code cleaned up W. Landsman October 1991 Added Equinox keyword, call to GET_COORDS, W. Landsman April, 1992 Allow floating point equinox input J. Parker/W. Landsman July 1996 Converted to IDL V5.0 W. Landsman September 1997
(See astro.pro)
NAME: ASTROLIB PURPOSE: Add the non-standard system variables used by the IDL Astronomy Library EXPLANATION: Also defines the environment variable or VMS logical ASTRO_DATA pointing to the directory containing data files associated with the IDL Astronomy library (system dependent). CALLING SEQUENCE: ASTROLIB INPUTS: None. OUTPUTS: None. METHOD: The non-standard system variables !PRIV, !DEBUG, !TEXTUNIT, and !TEXTOUT are added using DEFSYSV. REVISION HISTORY: Written, Wayne Landsman, July 1986. Use DEFSYSV instead of ADDSYSVAR December 1990 Converted to IDL V5.0 W. Landsman September 1997
(See astrolib.pro)
NAME: AVG PURPOSE: Return the average value of an array, or 1 dimension of an array EXPLANATION: Calculate the average value of an array, or calculate the average value over one dimension of an array as a function of all the other dimensions. CALLING SEQUENCE: RESULT = AVG( ARRAY, [ DIMENSION ] ) INPUTS: ARRAY = Input array. May be any type except string. OPTIONAL INPUT PARAMETERS: DIMENSION = Optional dimension to do average over, scalar OUTPUTS: The average value of the array when called with one parameter. If DIMENSION is passed, then the result is an array with all the dimensions of the input array except for the dimension specified, each element of which is the average of the corresponding vector in the input array. For example, if A is an array with dimensions of (3,4,5), then the command B = AVG(A,1) is equivalent to B = FLTARR(3,5) FOR J = 0,4 DO BEGIN FOR I = 0,2 DO BEGIN B(I,J) = TOTAL( A(I,*,J) ) / 4. ENDFOR ENDFOR RESTRICTIONS: Dimension specified must be valid for the array passed; otherwise the input array is returned as the output array. PROCEDURE: AVG(ARRAY) = TOTAL(ARRAY)/N_ELEMENTS(ARRAY) when called with one parameter. MODIFICATION HISTORY: William Thompson Applied Research Corporation July, 1986 8201 Corporate Drive Landover, MD 20785 Converted to Version 2 July, 1990 Replace SUM call with TOTAL W. Landsman May, 1992 Converted to IDL V5.0 W. Landsman September 1997
(See avg.pro)
NAME: A_b PURPOSE: Compute B band interstellar extinction according to the RC2. EXPLANATION: The predicted B band extinction is computed as a function of Galactic position using the 21 parameter function given by deVaucouleurs in the 2nd Reference Catalog of Galaxies (RC2). Note that this formula is no longer used in the RC3 and that reddenings are instead obtained from the Burstein-Heiles 21 cm maps. CALLING SEQUENCE: result = A_b( l2, b2) INPUT PARAMETERS l2 = galactic longitude (degrees), scalar or vector b2 = galactic latitude (degrees), scalar or vector OUTPUT PARAMETERS RESULT - Interstellar extinction Ab in magnitudes, same number of elements as input l2 and b2 parameters NOTES: The controversial aspect of the deVaucouleurs reddening curve is that it predicts an extinction of about 0.2 at the poles The parameters used here differ from the ones printed in the RC2 but are the ones actually used for entries in the catalog (see Rowan-Robinson 1985) REVISION HISTORY Written by R. Cornett and W. Landsman, STX October 1987 Vectorized code W. Landsman STX December 1992 Converted to IDL V5.0 W. Landsman September 1997
(See a_b.pro)
NAME: BARYVEL PURPOSE: Calculates heliocentric and barycentric velocity components of Earth. EXPLANATION: BARYVEL takes into account the Earth-Moon motion, and is useful for radial velocity work to an accuracy of ~1 m/s. CALLING SEQUENCE: BARYVEL, dje, deq, dvelh, dvelb INPUTS: DJE - (scalar) julian ephemeris date. DEQ - (scalar) epoch of mean equinox of dvelh and dvelb. If deq=0 then deq is assumed to be equal to dje. OUTPUTS: DVELH: (vector(3)) heliocentric velocity component. in km/s DVELB: (vector(3)) barycentric velocity component. in km/s The 3-vectors DVELH and DVELB are given in a right-handed coordinate system with the +X axis toward the Vernal Equinox, and +Z axis toward the celestial pole. PROCEDURE CALLED: Function PREMAT() -- computes precession matrix NOTES: Algorithm taken from FORTRAN program of Stumpff (1980, A&A Suppl, 41,1) Stumpf claimed an accuracy of 42 cm/s for the velocity. A comparison with the JPL FORTRAN planetary ephemeris program PLEPH found agreement to within about 65 cm/s between 1986 and 1994 EXAMPLE: Compute the radial velocity of the Earth toward Altair on 15-Feb-1994 IDL> jdcnv, 1994, 2, 15, 0, jd ;==> JD = 2449398.5 IDL> baryvel, jd, 2000, vh, vb ==> vh = [-17.07809, -22.80063, -9.885281] ;Heliocentric km/s ==> vb = [-17.08083, -22.80471, -9.886582] ;Barycentric km/s IDL> ra = ten(19,50,46.77)*15/!RADEG ;RA in radians IDL> dec = ten(08,52,3.5)/!RADEG ;Dec in radians IDL> v = vb(0)*cos(dec)*cos(ra) + $ ;Project velocity toward star vb(1)*cos(dec)*sin(ra) + vb(2)*sin(dec) REVISION HISTORY: Jeff Valenti, U.C. Berkeley Translated BARVEL.FOR to IDL. W. Landsman, Cleaned up program sent by Chris McCarthy (SfSU) June 1994 Converted to IDL V5.0 W. Landsman September 1997
(See baryvel.pro)
NAME: BLINK PURPOSE: To allow the user to alternatively examine two or more windows within a single window. CALLING SEQUENCE: BLINK, Wndw [, T] INPUTS: Wndw A vector containing the indices of the windows to blink. T The time to wait, in seconds, between blinks. This is optional and set to 1 if not present. OUTPUTS: None. PROCEDURE: The images contained in the windows given are written to a pixmap. The contents of the the windows are copied to a display window, in order, until a key is struck. EXAMPLE: Blink windows 0 and 2 with a wait time of 3 seconds IDL> blink, [0,2], 3 MODIFICATION HISTORY: Written by Michael R. Greason, STX, 2 May 1990. Allow different size windows Wayne Landsman August, 1991 Converted to IDL V5.0 W. Landsman September 1997
(See blink.pro)
NAME: BOOST_ARRAY PURPOSE: Append one array onto a destination array EXPLANATION: Add array APPEND to array DESTINATION, allowing the dimensions of DESTINATION to adjust to accomodate it. If both input arrays have the same number of dimensions, then the output array will have one additional dimension. Otherwise, the last dimension of DESTINATION will be incremented by one. CATEGOBY: Utility CALLING SEQUENCE: BOOST_ARRAY, DESTINATION, APPEND INPUT: DESTINATION = Array to be expanded. APPEND = Array to append to DESTINATION. OUTPUTS: DESTINATION = Expanded output array. RESTRICTIONS: DESTINATION and APPEND have to be either both of type string or both of numerical types. APPEND cannot have more dimensions than DESTINATION. MODIFICATION HISTOBY: Written Aug'88 (DMZ, ARC) Modified Sep'89 to handle byte arrays (DMZ) Modifed to version 2, Paul Hick (ARC), Feb 1991 Removed restriction to 2D arrays, William Thompson (ARC), Feb 1992. Converted to IDL V5.0 W. Landsman September 1997
(See boost_array.pro)
NAME: BOXAVE PURPOSE: Box-average a 1 or 2 dimensional array. EXPLANATION: This procedure differs from the intrinsic REBIN function in the following two ways: (1) the box size parameter is specified rather than the output array size (2) for INTEGER arrays, BOXAVE computes intermediate steps using REAL*4 arithmetic. This is considerably slower than REBIN but avoids integer truncation CALLING SEQUENCE: result = BOXAVE( Array, Xsize,[ Ysize ] ) INPUTS: ARRAY - Two dimensional input Array to be box-averaged. Array may be one or 2 dimensions and of any type except character. OPTIONAL INPUTS: XSIZE - Size of box in the X direction, over which the array is to be averaged. If omitted, program will prompt for this parameter. YSIZE - For 2 dimensional arrays, the box size in the Y direction. If omitted, then the box size in the X and Y directions are assumed to be equal OUTPUT: RESULT - Output array after box averaging. If the input array has dimensions XDIM by YDIM, then RESULT has dimensions XDIM/NBOX by YDIM/NBOX. The type of RESULT is the same as the input array. However, the averaging is always computed using REAL arithmetic, so that the calculation should be exact. If the box size did not exactly divide the input array, then then not all of the input array will be boxaveraged. PROCEDURE: BOXAVE boxaverages all points simultaneously using vector subscripting NOTES: If im_int is a 512 x 512 integer array, then the two statements IDL> im = fix(round(rebin(float(im_int), 128, 128))) IDL> im = boxave( im_int,4) give equivalent results. The use of REBIN is faster, but BOXAVE is is less demanding on virtual memory, since one does not need to make a floating point copy of the entire array. REVISION HISTORY: Written, W. Landsman, October 1986 Call REBIN for REAL*4 and REAL*8 input arrays, W. Landsman Jan, 1992 Removed /NOZERO in output array definition W. Landsman 1995 Fixed occasional integer overflow problem W. Landsman Sep. 1995 Converted to IDL V5.0 W. Landsman September 1997
(See boxave.pro)
NAME: BPRECESS PURPOSE: Precess positions from J2000.0 (FK5) to B1950.0 (FK4) EXPLANATION: Calculates the mean place of a star at B1950.0 on the FK4 system from the mean place at J2000.0 on the FK5 system. CALLING SEQUENCE: bprecess, ra, dec, ra_1950, dec_1950, [ MU_RADEC = , PARALLAX = RAD_VEL =, EPOCH = ] INPUTS: RA,DEC - Input J2000 right ascension and declination in *degrees*. Scalar or N element vector OUTPUTS: RA_1950, DEC_1950 - The corresponding B1950 right ascension and declination in *degrees*. Same number of elements as RA,DEC but always double precision. OPTIONAL INPUT-OUTPUT KEYWORDS MU_RADEC - 2xN element double precision vector containing the proper motion in seconds of arc per tropical *century* in right ascension and declination. PARALLAX - N_element vector giving stellar parallax (seconds of arc) RAD_VEL - N_element vector giving radial velocity in km/s The values of MU_RADEC, PARALLAX, and RADVEL will all be modified upon output to contain the values of these quantities in the B1950 system. The parallax and radial velocity will have a very minor influence on the B1950 position. EPOCH - scalar giving epoch of original observations, default 2000.0d This keyword value is only used if the MU_RADEC keyword is not set. NOTES: The algorithm is taken from the Explanatory Supplement to the Astronomical Almanac 1992, page 186. Also see Aoki et al (1983), A&A, 128,263 BPRECESS distinguishes between the following two cases: (1) The proper motion is known and non-zero (2) the proper motion is unknown or known to be exactly zero (i.e. extragalactic radio sources). In this case, the reverse of the algorithm in Appendix 2 of Aoki et al. (1983) is used to ensure that the output proper motion is exactly zero. Better precision can be achieved in this case by inputting the EPOCH of the original observations. The error in using the IDL procedure PRECESS for converting between B1950 and J1950 can be up to 1.5", mainly in right ascension. If better accuracy than this is needed then BPRECESS should be used. An unsystematic comparison of BPRECESS with the IPAC precession routine available at ned.ipac.caltech.edu always gives differences less than 0.1". EXAMPLE: The SAO2000 catalogue gives the J2000 position and proper motion for the star HD 119288. Find the B1950 position. RA(2000) = 13h 42m 12.740s Dec(2000) = 8d 23' 17.69'' Mu(RA) = -.0257 s/yr Mu(Dec) = -.090 ''/yr IDL> mu_radec = 100D* [ -15D*.0257, -0.090 ] IDL> ra = ten(13, 42, 12.740)*15.D IDL> dec = ten(8, 23, 17.69) IDL> bprecess, ra, dec, ra1950, dec1950, mu_radec = mu_radec IDL> print, adstring(ra1950, dec1950,2) ===> 13h 39m 44.526s +08d 38' 28.63" REVISION HISTORY: Written, W. Landsman October, 1992 Vectorized, W. Landsman February, 1994 Treat case where proper motion not known or exactly zero November 1994 Handling of arrays larger than 32767 Lars L. Christensen, march, 1995 Converted to IDL V5.0 W. Landsman September 1997
(See bprecess.pro)
NAME: BREAK_PATH() PURPOSE: Breaks up a path string into its component directories. CALLING SEQUENCE: Result = BREAK_PATH( PATHS [ /NoCurrent]) INPUTS: PATHS = A string containing one or more directory paths. The individual paths are separated by commas, although in UNIX, colons can also be used. In other words, PATHS has the same format as !PATH, except that commas can be used as a separator regardless of operating system. A leading $ can be used in any path to signal that what follows is an environmental variable, but the $ is not necessary. (In VMS the $ can either be part of the path, or can signal logical names for compatibility with Unix.) Environmental variables can themselves contain multiple paths. OUTPUT: The result of the function is a string array of directories. Unless the NOCURRENT keyword is set, the first element of the array is always the null string, representing the current directory. All the other directories will end in the correct separator character for the current operating system. OPTIONAL INPUT KEYWORD: NOCURRENT = If set, then the current directory (represented by the null string) will not automatically be prepended to the output. PROCEDURE CALLS: Functions: DATATYPE(), STR_SEP(), TRIM() REVISION HISTORY: Version 1, William Thompson, GSFC, 6 May 1993. Added IDL for Windows compatibility. Version 2, William Thompson, GSFC, 16 May 1995 Added keyword NOCURRENT Version 3, William Thompson, GSFC, 29 August 1995 Modified to use OS_FAMILY Version 4, Zarro, GSFC, 4 August 1997 Added trim to input Converted to IDL V5.0 W. Landsman 25-Nov-1997
(See break_path.pro)
NAME: BSORT PURPOSE: Function to sort data into ascending order, like a simple bubble sort. EXPLANATION: Original subscript order is maintained when values are equal (FIFO). (This differs from the IDL SORT routine alone, which may rearrange order for equal values) CALLING SEQUENCE: result = bsort( array, [ asort, /INFO, /REVERSE ] ) INPUT: Array - array to be sorted OUTPUT: result - sort subscripts are returned as function value OPTIONAL OUTPUT: Asort - sorted array OPTIONAL KEYWORD INPUTS: /REVERSE - if this keyword is set, and non-zero, then data is sorted in descending order instead of ascending order. /INFO = optional keyword to cause brief message about # equal values. HISTORY written by F. Varosi Oct.90: uses WHERE to find equal clumps, instead of looping with IF ( EQ ). compatible with string arrays, test for degenerate array 20-MAY-1991 JKF/ACC via T AKE- return indexes if the array to be sorted has all equal values. Aug - 91 Added REVERSE keyword W. Landsman Always return type LONG W. Landsman August 1994 Converted to IDL V5.0 W. Landsman September 1997
(See bsort.pro)
NAME: CCM_UNRED PURPOSE: Deredden a flux vector according to the parameterization of Cardelli, Clayton, and Mathis (1989 ApJ. 345, 245), including the update for the near-UV given by O'Donnell (1994, ApJ, 422, 158). Parameterization is valid from the IR to the far-UV (3.5 microns to 0.1 microns). CALLING SEQUENCE: CCM_UNRED, wave, flux, ebv, funred, [ R_V = ] or CCM_UNRED, wave, flux, ebv, [ R_V = ] INPUT: WAVE - wavelength vector (Angstroms) FLUX - calibrated flux vector, same number of elements as WAVE If only 3 parameters are supplied, then this vector will updated on output to contain the dereddened flux. EBV - color excess E(B-V), scalar. If a negative EBV is supplied, then fluxes will be reddened rather than deredenned. OUTPUT: FUNRED - unreddened flux vector, same units and number of elements as FLUX OPTIONAL INPUT KEYWORD R_V - scalar specifying the ratio of total selective extinction R(V) = A(V) / E(B - V). If not specified, then R_V = 3.1 Extreme values of R(V) range from 2.75 to 5.3 EXAMPLE: Determine how a flat spectrum (in wavelength) between 1200 A and 3200 A is altered by a reddening of E(B-V) = 0.1. Assume an "average" reddening for the diffuse interstellar medium (R(V) = 3.1) IDL> w = 1200 + findgen(40)*50 ;Create a wavelength vector IDL> f = w*0 + 1 ;Create a "flat" flux vector IDL> ccm_unred, w, f, -0.1, fnew ;Redden (negative E(B-V)) flux vector IDL> plot,w,fnew NOTES: (1) The CCM curve shows good agreement with the Savage & Mathis (1979) ultraviolet curve shortward of 1400 A, but is probably preferable between 1200 and 1400 A. (2) Many sightlines with peculiar ultraviolet interstellar extinction can be represented with a CCM curve, if the proper value of R(V) is supplied. (3) Curve is extrapolated between 912 and 1000 A as suggested by Longo et al. (1989, ApJ, 339,474) (4) Use the 4 parameter calling sequence if you wish to save the original flux vector. REVISION HISTORY: Written W. Landsman Hughes/STX January, 1992 Extrapolate curve for wavelengths between 900 and 1000 A Dec. 1993 Use updated coefficients for near-UV from O'Donnell Feb 1994 Allow 3 parameter calling sequence April 1998 Converted to IDLV5.0 April 1998
(See ccm_unred.pro)
NAME: CHECK_FITS PURPOSE: Check that keywords in a FITS header array match the associated data EXPLANATION: Given a FITS array IM, and a associated FITS or STSDAS header HDR, this procedure will check that (1) HDR is a string array, and IM is defined and numeric (2) The NAXISi values in HDR are appropriate to the dimensions of IM (3) The BITPIX value in HDR is appropriate to the datatype of IM If HDR contains a DATATYPE keyword (as in STSDAS files), then this is also checked against the datatype of of IM If the UPDATE keyword is present, then FITS header will be modified, if necessary, to force agreement with the image array CALLING SEQUENCE: check_FITS, im, hdr, [ dimen, idltype, /UPDATE, /NOTYPE, /SDAS, /SILENT] INPUT PARAMETERS: IM - FITS or STSDAS array, (e.g. as read by SXREAD or READFITS ) HDR - FITS or STSDAS header (string array) associated with IM OPTIONAL OUTPUTS: dimen - vector containing actual array dimensions idltype- data type of the FITS array as specified in the IDL SIZE function (1 for BYTE, 2 for INTEGER*2, 3 for INTEGER*4, etc.) OPTIONAL KEYWORD INPUTS: /NOTYPE - If this keyword is set, then only agreement of the array dimensions with the FITS header are checked, and not the data type. /UPDATE - If this keyword is set then the BITPIX, NAXIS and DATATYPE FITS keywords will be updated to agree with the array /SDAS - If this keyword is set then the header is assumed to be from an SDAS (.hhh) file. CHECK_FITS will then ensure that (1) a DATATYPE keyword is included in the header and (2) BITPIX is always written with positive values. /FITS - If this keyword is present then CHECK_FITS assumes that it is dealing with a FITS header and not an SDAS header, see notes below. /SILENT - If keyword is set and nonzero, the informational messages will not be printed SYSTEM VARIBLE: If there is a fatal problem with the FITS array or header then !ERR is set to -1. ( If the UPDATE keyword was supplied, and the header could be fixed, then !ERR = 0.) PROCEDURE: Program checks the NAXIS1 and NAXIS2 parameters in the header to see if they match the image array dimensions. NOTES: An important distinction between an STSDAS header and a FITS header is that the BITPIX value in an STSDAS header is always positive, e.g. BITPIX=32 for REAL*4 data. Users should use either the /SDAS or the /FITS keyword if it is important whether the STSDAS or FITS convention for REAL*4 data is used. Otherwise, CHECK_FITS assumes that if a DATATYPE keyword is present then it is dealing with an STSDAS header. MODIFICATION HISTORY: Written, December 1991 W. Landsman Hughes/STX to replace CHKIMHD No error returned if NAXIS=0 and IM is a scalar W. Landsman Feb 93 Fixed bug for REAL*8 STSDAS data W. Landsman July 93 Make sure NAXIS agrees with NAXISi W. Landsman October 93 Converted to IDL V5.0 W. Landsman September 1997
(See check_fits.pro)
NAME : CHECK_TAPE_DRV PURPOSE : Associates tape drive numbers with device files. *Unix only* EXPLANATION : This is an internal routine to the CDS/SERTS Unix tape handling utilities. It converts tape drive numbers to actual device names, and checks to make sure that the device file is open. **Unix only** CALLING SEQUENCE: : CHECK_TAPE_DRV, UNIT, LOGICAL_DRIVE, DRIVE, LUN INPUTS UNIT = Tape unit number. Tape drives are selected via the UNIX environment variables "MT1", "MT2", etc. The desired tape drive is thus specified by numbers, as in VMS. Must be from 0 to 9. OUTPUTS : LOGICAL_DRIVE = Name of environment variable pointing to tape drive device file, e.g. "MT0". DRIVE = Name of device file, e.g. '/dev/nrst0'. LUN = Logical unit number used for reads and writes. COMMON : CHCK_TAPE_DRVS contains array TAPE_LUN, containing logical unit numbers for each tape device, and TAPE_OPEN, which tells whether each device is open or not. RESTRICTIONS: The environment variable "MTn", where n corresponds to the variable UNIT, must be defined. E.g., setenv MT0 /dev/nrst0 Requires IDL v3.0 or later. SIDE EFFECTS: If the device file is not yet open, then the tape is rewound, and a file unit is opened to it. Category : Utilities, I/O, Tape. Prev. Hist. : William Thompson, Apr 1991. Written : William Thompson, GSFC, April 1991. Modified : Version 1, William Thompson, GSFC, 21 December 1993. Added keyword /NOSTDIO to OPEN statement. Incorporated into CDS library. Version 2, William Thompson, GSFC, 22 December 1993. Added spawn to "mt rewind". Version 3, W. Landsman GSFC 10-Apr-1996 Open for Readonly, if Update access is unavailable Version : Version 3, 10-Apr-1996. Converted to IDL V5.0 W. Landsman September 1997
(See check_tape_drv.pro)
NAME: CIRRANGE PURPOSE: To force an angle into the range 0 <= ang < 360. CALLING SEQUENCE: CIRRANGE, ang, [/RADIAN] INPUTS/OUTPUT: ang - The angle to modify, in degrees. This parameter is changed by this procedure. Can be a scalar or vector. The type of ANG is always converted to double precision on output. OPTIONAL INPUT KEYWORDS: RADIANS - If present and non-zero, the angle is specified in radians rather than degrees. It is forced into the range 0 <= ang < 2 PI. PROCEDURE: The angle is transformed between -360 and 360 using the MOD operator. Negative values (if any) are then transformed between 0 and 360 MODIFICATION HISTORY: Written by Michael R. Greason, Hughes STX, 10 February 1994. Get rid of WHILE loop, W. Landsman, Hughex STX, May 1996 Converted to IDL V5.0 W. Landsman September 1997
(See cirrange.pro)
NAME: CLEANPLOT PURPOSE: Reset all system variables (!P,!X,!Y,!Z) to their default values EXPLANATION: Reset all system variables (!P,!X,!Y,!Z) which are set by the user and which affect plotting to their default values. CALLING SEQUENCE: Cleanplot INPUTS: None OUTPUTS: None SIDE EFFECTS: The system variables that concern plotting are reset to their default values. A message is output for each variable changed. The CRANGE, S, WINDOW, and REGION fields of the !X, !Y, and !Z system variables are not checked since these are set by the graphics device and not by the user. PROCEDURE: This does NOT reset the plotting device. This does not change any system variables that don't control plotting. RESTRICTIONS: If user default values for !P, !X, !Y and !Z are different from the defaults adopted below, user should change P_old etc accordingly MODIFICATION HISTORY: Written IDL Version 2.3.0 W. Landsman & K. Venkatakrishna May '92 Handle new system variables in V3.0.0 W. Landsman Dec 92 Assume user has at least V3.0.0 W. Landsman August 95 V5.0 has 60 instead of 30 TICKV values W. Landsman Sep. 97 Change !D.N_COLORS to !D.TABLE_SIZE for 24 bit displays W. Landsman April 1998
(See cleanplot.pro)
NAME: CNTRD PURPOSE: Compute the centroid coordinates of a stellar object using the algorithm in the DAOPHOT FIND subroutine. CALLING SEQUENCE: CNTRD, img, x, y, xcen, ycen, [ fwhm , /SILENT, /DEBUG] INPUTS: IMG - Two dimensional image array X,Y - Scalar or vector integers giving approximate stellar center OPTIONAL INPUT: FWHM - floating scalar; Centroid is computed using a box of half width equal to 1.5 sigma = 0.637* FWHM. CNTRD will prompt for FWHM if not supplied OUTPUTS: XCEN - the computed X centroid position, same number of points as X YCEN - computed Y centroid position, same number of points as Y Values for XCEN and YCEN will not be computed if the computed centroid falls outside of the box, or if the computed derivatives are non-decreasing. If the centroid cannot be computed, then a message is displayed and XCEN and YCEN are set to -1. OPTIONAL OUTPUT KEYWORDS: SILENT - Normally CNTRD prints an error message if it is unable to compute the centroid. Set /SILENT to suppress this. DEBUG - If this keyword is set, then CNTRD will display the subarray it is using to compute the centroid. PROCEDURE: Maximum pixel within distance from input pixel X, Y determined from FHWM is found and used as the center of a square, within which the centroid is computed as the value (XCEN,YCEN) at which the derivatives of the partial sums of the input image over (y,x) with respect to (x,y) = 0. MODIFICATION HISTORY: Written 2/25/86, by J. K. Hill, S.A.S.C., following algorithm used by P. Stetson in DAOPHOT. Allowed input vectors G. Hennessy April, 1992 Fixed to prevent wrong answer if floating pt. X & Y supplied W. Landsman March, 1993 Convert byte, integer subimages to float W. Landsman May 1995 Converted to IDL V5.0 W. Landsman September 1997
(See cntrd.pro)
NAME: COMPARE_STRUCT PURPOSE: Compare all matching tag names and return differences EXPLANATION: Compare all matching Tags names (except for "except_Tags") between two structure arrays (may be different struct.defs.), and return a structured List of fields found different. CATEGORY: Structures CALLING SEQUENCE: diff_List = compare_struct( struct_A, struct_B ) INPUTS: struct_A, struct_B : the two structure arrays to compare. Struct_Name : for internal recursion use only. KeyWords: EXCEPT = string array of Tag names to ignore (NOT to compare). /BRIEF = number of differences found for each matching field of two structures is printed. /FULL = option to print even if zero differences found. /RECUR_A = option to search for Tag names in sub-structures of struct_A, and then call compare_struct recursively for those nested sub-structures. /RECUR_B = search for sub-structures of struct_B, and then call compare_struct recursively for those nested sub-structures. Note: compare_struct is automatically called recursively for those nested sub-structures in both struct_A and struct_B (otherwise cannot take difference) OUTPUT: Returns a structure array describing differences found, which can be examined using print,diff_List or help,/st,diff_List. PROCEDURE: Match Tag names and then use where function on tags. MODIFICATION HISTORY: written 1990 Frank Varosi STX @ NASA/GSFC (using copy_struct) modif Aug.90 by F.V. to check and compare same # of elements only. Converted to IDL V5.0 W. Landsman September 1997
(See compare_struct.pro)
NAME: CONCAT_DIR PURPOSE: To concatenate directory and file names for current OS. EXPLANATION: The given file name is appended to the given directory name with the format appropriate to the current operating system. CALLING SEQUENCE: result = concat_dir( directory, file) INPUTS: directory - the directory path (string) file - the basic file name and extension (string) can be an array of filenames. OUTPUTS: The function returns the concatenated string. If the file input is a string array then the output will be a string array also. EXAMPLES: IDL> pixfile = concat_dir('$DIR_GIS_MODEL','pixels.dat') IDL> file = ['f1.dat','f2.dat','f3.dat'] IDL> dir = '$DIR_NIS_CAL' IDL> f = concat_dir(dir,file) RESTRICTIONS: Assumes Unix type format if os is not VMS or windows. The version of CONCAT_DIR available at http://sohowww.nascom.nasa.gov/solarsoft/gen/idl/system/concat_dir.pro includes additional VMS-specific keywords. CATEGORY Utilities, Strings REVISION HISTORY: Prev Hist. : Yohkoh routine by M. Morrison Written : CDS version by C D Pike, RAL, 19/3/93 Version : Version 1 19/3/93 Documentation modified Nov-94 W. Landsman Add V4.0 support for Windows W. Landsman Aug 95 Converted to IDL V5.0 W. Landsman September 1997
(See concat_dir.pro)
NAME: CONS_DEC PURPOSE: Obtain the X and Y coordinates of a line of constant declination EXPLANATION: Returns a set of Y pixels values, given an image with tangent projection astrometry, and either (1) A set of X pixel values, and a scalar declination value, or (2) A set of declination values, and a scalar X value Form (1) can be used to find the (X,Y) values of a line of constant declination. Form (2) can be used to find the Y positions of a set declinations, along a line of constant X. CALLING SEQUENCE: Y = CONS_DEC( DEC, X, CD, ASTR, ALPHA) INPUTS: DEC - Declination value(s) in DEGREES (-!PI/2 < DEC < !PI/2). If X is a vector, then DEC must be a scalar. X - Specified X pixel value(s) for line of constant declination If DEC is a vector, then X must be a scalar. ASTR - Astrometry structure, as extracted from a FITS header by the procedure EXTAST OUTPUT: Y - Computed set of Y pixel values. The number of Y values is the same as either DEC or X, whichever is greater. OPTIONAL OUTPUT: ALPHA - the right ascensions (DEGREES) associated with the (X,Y) points RESTRICTIONS: Implemented only for the TANgent and SIN projections NOTES: The algorithm (and notation) is based on AIPS Memo 27 by Eric Greisen, with modifications for a coordinate description (CD) matrix as described in Appendix B of Greisen & Calabretta (1996, A&A, in press). These documents are available from http://fits.cv.nrao.edu/documents/ wcs/wcs.html REVISION HISTORY: Written, Wayne Landsman STX Co. April 1988 Use new astrometry structure, W. Landsman HSTX Jan. 1994 Use CD matrix, add SIN projection W. Landsman HSTX April, 1996 Converted to IDL V5.0 W. Landsman September 1997
(See cons_dec.pro)
NAME: CONS_RA PURPOSE: Obtain the X and Y coordinates of a line of constant right ascension EXPLANATION: Return a set of X pixel values given an image with astrometry, and either (1) a set of Y pixel values, and a scalar right ascension, or (2) a set of right ascension values, and a scalar Y value. In usage (1), CONS_RA can be used to determine the (X,Y) values of a line of constant right ascension. In usage (2), CONS_RA can used to determine the X positions of specified RA values, along a line of constant Y. CALLING SEQUENCE: X = CONS_RA( RA, Y, ASTR) INPUTS: RA - Right Ascension value in DEGREES (0 < RA < 2*PI). If Y is a vector, then RA must be a scalar Y - Specified Y pixel value(s) for line of constant right ascension If RA is a vector, then Y must be a scalar ASTR - Astrometry structure as extracted from a FITS header by the procedure EXTAST OUTPUTS X - Computed set of X pixel values. The number of elements of X is the maximum of the number of elements of RA and Y. RESTRICTIONS: Program will have difficulty converging for declination values near 90. For tangent projection only. REVISION HISTORY: Written, Wayne Landsman STX Co. April, 1988 Algorithm adapted from AIPS memo No. 27 by Eric Griessen New astrometry structure Converted to IDL V5.0 W. Landsman September 1997
(See cons_ra.pro)
NAME: CONVOLVE PURPOSE: Convolution of an image with a Point Spread Function (PSF) EXPLANATION: The default is to compute the convolution using a product of Fourier transforms (for speed). CALLING SEQUENCE: imconv = convolve( image1, psf, FT_PSF = psf_FT ) or: correl = convolve( image1, image2, /CORREL ) or: correl = convolve( image, /AUTO ) INPUTS: image = 2-D array (matrix) to be convolved with psf psf = the Point Spread Function, (size < or = to size of image). OPTIONAL INPUT KEYWORDS: FT_PSF = passes out/in the Fourier transform of the PSF, (so that it can be re-used the next time function is called). FT_IMAGE = passes out/in the Fourier transform of image. /CORRELATE uses the conjugate of the Fourier transform of PSF, to compute the cross-correlation of image and PSF, (equivalent to IDL function convol() with NO rotation of PSF) /AUTO_CORR computes the auto-correlation function of image using FFT. /NO_FT overrides the use of FFT, using IDL function convol() instead. (then PSF is rotated by 180 degrees to give same result) METHOD: When using FFT, PSF is centered & expanded to size of image. HISTORY: written, Frank Varosi, NASA/GSFC 1992. Converted to IDL V5.0 W. Landsman September 1997
(See convolve.pro)
NAME: CONV_STSDAS PURPOSE: Convert internal format of an STSDAS image to host machine architecture EXPLANATION: Converts the internal format of an STSDAS image (.hhh and .hhd file) to the host machine architecture. Useful for copying STSDAS files between different machines. If the host is not a VMS machine, then by default CONV_STSDAS assumes the image originated on VMS. If the host is VMS, then CONV_STSDAS assumes that the image originated on an IEEE machine (e.g. SparcStation). CALLING SEQUENCE: CONV_STSDAS, sdas_name, [ /FROM_IEEE] INPUTS: sdas_name - scalar string giving name of the STSDAS image CONV_STSDAS assumes a default header extension of .hhh -- otherwise the header extension should be included in sdas_name. The internal format of the file will be modified by CONV_STSDAS. OPTIONAL KEYWORD INPUT: /FROM_IEEE - On little endian machines (OSF, windows) this keyword indicates that the STSDAS file originated on an IEEE machine (e.g SparcStation) rather than a VMS machine EXAMPLE: Suppose files test.hhd and test.hhh have been copied with FTP from a Vax to a Sparcstation. Convert these files to the SparcStation internal format. IDL> conv_stsdas, 'test' METHOD: CONV_STSDAS reads each group image and parameter block and uses IEEE_TO_HOST or CONV_VAX_UNIX to convert the internal format. The converted images and parameter blocks are written back to the orginal file. PROCEDURE CALLS sxopen, fdecomp, datatype(), sxgpar(), ieee_to_host, conv_vax_unix() NOTES: (1) When copying STSDAS files to VMS, be sure the .hhh file is formatted as fixed block 80 byte. (2) CONV_STSDAS has no way of knowing if a file really came from a different machine architecture. If it is applied to a file that already has the correct internal format, then CONV_STSDAS will "convert" this file and corrupt the internal format. (3) Note that CONV_STSDAS currently does not support conversion *from* a little-endian machine (OSF, windows) REVISION HISTORY: Written W. Landsman January, 1993 Don't require .hhh extension April, 1993 Increase speed by calling SXGINFO May, 1993 Converted to IDL V5.0 W. Landsman September 1997
(See conv_stsdas.pro)
NAME: CONV_UNIX_VAX PURPOSE: To convert Unix IDL data types to Vax IDL data types. EXPLANATION: CONV_UNIX_VAX assumes the Unix IDL data type is IEEE standard in either big-endian or little-endian format. CALLING SEQUENCE: CONV_UNIX_VAX, variable, [ SOURCE_ARCH = ] PARAMETERS: variable - The data variable to be converted. This may be a scalar or an array. Valid datatypes are integer, longword, floating point, and double precision. The result of the conversion is passed back in the original variable. OPTIONAL INPUT KEYWORD: SOURCE_ARCH = name (string) of source architecture if using this function on a VAX, otherwise !VERSION.ARCH is used to determine the conversion. **If run on a VAX, the default is to assume the source to be a little-endian machine with IEEE floating point (e.g. MIPSEL or Alpha***). RESTRICTIONS: Requires that data be from IEEE standard Unix machines (e.g. SUN, MIPSEL, or Alpha). EXAMPLE: Read a 100 by 100 matrix of floating point numbers from a data file created on a Sun. Then convert the matrix values into VAX format. IDL> openr,1,'vax_float.dat IDL> data = fltarr(100,100) IDL> forrd,1,data IDL> CONV_UNIX_VAX,data,SOURCE_ARCH='sparc' MODIFICATION HISTORY: Version 1 By John Hoegy 13-Jun-88 04-May-90 - WTT: Created CONV_UNIX_VAX from VAX2SUN, reversing floating point procedure. Modified P. Keegstra September 1994 Implemented MIPSEL and ALPHA architecture, distinguishing VMS and OSF Modified P. Keegstra February 1995 Added 386 PC based architectures If since V5.1 then VMS is always little endian June 1998 Convert to IDL V5.0 W. Landsman June 1998
(See conv_unix_vax.pro)
NAME: CONV_VAX_UNIX PURPOSE: To convert VAX IDL data types to UNIX (Sun,MIPS,etc.) IDL data types. EXPLANTION: Generally used on non-Vax machines to parse data created on Vaxes. The architecture is obtained from IDL sys.var. !VERSION.ARCH. CALLING SEQUENCE: var_unix = conv_vax_unix( var_vax, [TARGET_ARCH = ] ) INPUT PARAMETER: var_vax - The data variable to be converted. This may be a scalar or an array. All IDL datatypes are valid (including structures). The result of the conversion is returned by the function. OPTIONAL INPUT KEYWORD: TARGET_ARCH = name (string) of desired target architecture (e.g. 'sparc' or 'mipsel'). If not supplied, then !VERSION.ARCH is used to determine the target architecture. Note that CONV_VAX_UNIX will leave variables unchanged on a VMS machine, unless the TARGET_ARCH keyword is set. EXAMPLE: Read a 100 by 100 matrix of floating point numbers from a data file created on a VAX. Then convert the matrix values into Sun format. IDL> openr,1,'vax_float.dat' IDL> data = fltarr(100,100) IDL> readu,1,data IDL> data = conv_vax_unix( data ) NOTE: Prior to IDL V5.1, the architecture "alpha" was ambiguous, since VMS alpha IDL used VAX D-float while OSF/1 alpha IDL uses little-endian IEEE. The program uses !VERSION.OS to do the right thing when converting to a representation appropriate for the current platform. To convert to a representation appropriate for an OSF/1 alpha on a VAX or (pre V5.1) VMS alpha, please specify the "mipsel" (or "i386") architecture. MODIFICATION HISTORY: Written F. Varosi August 1990 Modified P. Keegstra April 1992 Implemented MIPSEL architecture Modified P. Keegstra July 1994 Implemented ALPHA architecture, distinguishing VMS and OSF Modified P. Keegstra February 1995 Added 386 PC based architectures Modified P. Keegstra March 1995 Added note, restored and fixed old specifiers for 386 PC based architectures Modified W. Landsman for VAX problems in V4.0 August 1995 Work for double complex variables August 1995 Remove informational messages under VMS August 1997 Since V5.1, IDL VMS uses little endian IEEE June 1998 Convert to IDL V5.0 June 1998
(See conv_vax_unix.pro)
NAME: COPY_STRUCT PURPOSE: Copy all fields with matching tag names from one structure to another EXPLANATION Fields with matching tag names are copied from one structure array to another structure array of different type. This allows copying of tag values when equating the structures of different types is not allowed, or when not all tags are to be copied. Can also recursively copy from/to structures nested within structures. Note that the number of elements in the output structure array is automatically adjusted to equal the length of input structure array. If this not desired then use pro copy_struct_inx which allows specifying via subscripts which elements are copied where in the arrays. CALLING SEQUENCE: copy_struct, struct_From, struct_To, NT_copied copy_struct, struct_From, struct_To, EXCEPT=["image","misc"] copy_struct, struct_From, struct_To, /RECUR_TANDEM INPUTS: struct_From = structure array to copy from. struct_To = structure array to copy values to. KEYWORDS: EXCEPT_TAGS = string array of tag names to ignore (to NOT copy). Used at all levels of recursion. SELECT_TAGS = tag names to copy (takes priority over EXCEPT). This keyword is not passed to recursive calls in order to avoid the confusion of not copying tags in sub-structures. /RECUR_FROM = search for sub-structures in struct_From, and then call copy_struct recursively for those nested structures. /RECUR_TO = search for sub-structures of struct_To, and then call copy_struct recursively for those nested structures. /RECUR_TANDEM = call copy_struct recursively for the sub-structures with matching Tag names in struct_From and struct_To (for use when Tag names match but sub-structure types differ). OUTPUTS: struct_To = structure array to which new tag values are copied. NT_copied = incremented by total # of tags copied (optional) INTERNAL: Recur_Level = # of times copy_struct calls itself. This argument is for internal recursive execution only. The user call is 1, subsequent recursive calls increment it, and the counter is decremented before returning. The counter is used just to find out if argument checking should be performed, and to set NT_copied = 0 first call. EXTERNAL CALLS: pro match (when keyword SELECT_TAGS is specified) PROCEDURE: Match Tag names and then use corresponding Tag numbers. HISTORY: written 1989 Frank Varosi STX @ NASA/GSFC mod Jul.90 by F.V. added option to copy sub-structures RECURSIVELY. mod Aug.90 by F.V. adjust # elements in TO (output) to equal # elements in FROM (input) & count # of fields copied. mod Jan.91 by F.V. added Recur_Level as internal argument so that argument checking done just once, to avoid confusion. Checked against Except_Tags in RECUR_FROM option. mod Oct.91 by F.V. added option SELECT_TAGS= selected field names. mod Aug.95 by W. Landsman to fix match of a single selected tag. mod Mar.97 by F.V. do not pass the SELECT_TAGS keyword in recursion. Converted to IDL V5.0 W. Landsman September 1997
(See copy_struct.pro)
NAME: COPY_STRUCT_INX PURPOSE: Copy matching tags & specified indices from one structure to another EXPLANATION: Copy all fields with matching tag names (except for "except_Tags") from one structure array to another structure array of different type. This allows copying of tag values when equating the structures of different types is not allowed, or when not all tags are to be copied. Can also recursively copy from/to structures nested within structures. This procedure is same as copy_struct with option to specify indices (subscripts) of which array elements to copy from/to. CALLING SEQUENCE: copy_struct_inx, struct_From, struct_To, NT_copied, INDEX_FROM=subf copy_struct_inx, struct_From, struct_To, INDEX_FROM=subf, INDEX_TO=subto INPUTS: struct_From = structure array to copy from. struct_To = structure array to copy values to. KEYWORDS: INDEX_FROM = indices (subscripts) of which elements of array to copy. (default is all elements of input structure array) INDEX_TO = indices (subscripts) of which elements to copy to. (default is all elements of output structure array) EXCEPT_TAGS = string array of Tag names to ignore (to NOT copy). Used at all levels of recursion. SELECT_TAGS = Tag names to copy (takes priority over EXCEPT). This keyword is not passed to recursive calls in order to avoid the confusion of not copying tags in sub-structures. /RECUR_FROM = search for sub-structures in struct_From, and then call copy_struct recursively for those nested structures. /RECUR_TO = search for sub-structures of struct_To, and then call copy_struct recursively for those nested structures. /RECUR_TANDEM = call copy_struct recursively for the sub-structures with matching Tag names in struct_From and struct_To (for use when Tag names match but sub-structure types differ). OUTPUTS: struct_To = structure array to which new tag values are copied. NT_copied = incremented by total # of tags copied (optional) INTERNAL: Recur_Level = # of times copy_struct_inx calls itself. This argument is for internal recursive execution only. The user call is 1, subsequent recursive calls increment it, and the counter is decremented before returning. The counter is used just to find out if argument checking should be performed, and to set NT_copied = 0 first call. EXTERNAL CALLS: pro match (when keyword SELECT_TAGS is specified) PROCEDURE: Match Tag names and then use corresponding Tag numbers, apply the sub-indices during = and recursion. HISTORY: adapted from copy_struct: 1991 Frank Varosi STX @ NASA/GSFC mod Aug.95 by F.V. to fix match of a single selected tag. mod Mar.97 by F.V. do not pass the SELECT_TAGS keyword in recursion, and check validity of INDEX_FROM and INDEX_TO in more detail. Converted to IDL V5.0 W. Landsman September 1997
(See copy_struct_inx.pro)
NAME: CORREL_IMAGES PURPOSE: Compute the 2-D cross-correlation function of two images EXPLANATION: Computes the 2-D cross-correlation function of two images for a range of (x,y) shifting by pixels of one image relative to the other. CALLING SEQUENCE: Result = CORREL_IMAGES( image_A, image_B, [XSHIFT=, YSHIFT=, XOFFSET_B=, YOFFSET_B=, REDUCTION=, MAGNIFICATION=, /NUMPIX, /MONITOR ) INPUTS: image_A, image_B = the two images of interest. OPTIONAL INPUT KEYWORDS: XSHIFT = the + & - shift to be applied in X direction, default=7. YSHIFT = the Y direction + & - shifting, default=7. XOFFSET_B = initial X pixel offset of image_B relative to image_A. YOFFSET_B = Y pixel offset, defaults are (0,0). REDUCTION = optional reduction factor causes computation of Low resolution correlation of bin averaged images, thus faster. Can be used to get approximate optimal (x,y) offset of images, and then called for successive lower reductions in conjunction with CorrMat_Analyze until REDUCTION=1, getting offset up to single pixel. MAGNIFICATION = option causes computation of high resolution correlation of magnified images, thus much slower. Shifting distance is automatically = 2 + Magnification, and optimal pixel offset should be known and specified. Optimal offset can then be found to fractional pixels using CorrMat_Analyze( correl_images( ) ). /NUMPIX - if set, causes the number of pixels for each correlation to be saved in a second image, concatenated to the correlation image, so Result is fltarr( Nx, Ny, 2 ). /MONITOR causes the progress of computation to be briefly printed. OUTPUTS: Result is the cross-correlation function, given as a matrix. PROCEDURE: Loop over all possible (x,y) shifts, compute overlap and correlation for each shift. Correlation set to zero when there is no overlap. MODIFICATION HISTORY: Written, July,1991, Frank Varosi, STX @ NASA/GSFC Use ROUND instead of NINT, June 1995, Wayne Landsman HSTX Avoid divide by zero errors, W. Landsman HSTX April 1996 Remove use of !DEBUG W. Landsman June 1997 Subtract mean of entire image before computing correlation, not just mean of overlap region H. Ebeling/W. Landsman June 1998
(See correl_images.pro)
NAME: CORREL_OPTIMIZE PURPOSE: Find the optimal (x,y) pixel offset of image_B relative to image_A EXPLANATION" Optimal offset is computed by means of maximizing the correlation function of the two images. CALLING SEQUENCE: CORREL_OPTIMIZE, image_A, image_B, xoffset_optimum, yoffset_optimum [ XOFF_INIT=, YOFF_INIT=, MAGNIFICATION=, /PRINT, /NUMPIX, /MONITOR, PLATEAU_THRESH= ] INPUTS: image_A, image_B = the two images of interest. OPTIONAL INPUT KEYWORDS: XOFF_INIT = initial X pixel offset of image_B relative to image_A, YOFF_INIT = Y pixel offset, (default offsets are 0 and 0). MAGNIFICATION = option to determine offsets up to fractional pixels, (example: MAG=2 means 1/2 pixel accuracy, default=1). /NUMPIX: sqrt( sqrt( # pixels )) used as correlation weighting factor. /MONITOR causes the progress of computation to be briefly printed. /PRINT causes the results of analysis to be printed. PLATEAU_THRESH = threshold used for detecting plateaus in the cross-correlation matrix near maximum, (default=0.01), used only if MAGNIFICATION > 1. Decrease this value for high signal-to-noise data OUTPUTS: xoffset_optimum = optimal X pixel offset of image_B relative to image_A. yoffset_optimum = optimal Y pixel offset. CALLS: function correl_images( image_A, image_B ) pro corrmat_analyze PROCEDURE: The combination of function correl_images( image_A, image_B ) and corrmat_analyze of the result is used to obtain the (x,y) offset yielding maximal correlation. The combination is first executed at large REDUCTION factors to speed up computation, then zooming in recursively on the optimal (x,y) offset by factors of 2. Finally, the MAGNIFICATION option (if specified) is executed to determine the (x,y) offset up to fractional pixels. MODIFICATION HISTORY: Written, July,1991, Frank Varosi, STX @ NASA/GSFC Added PLATEAU_THRESH keyword June 1997, Wayne Landsman STX Converted to IDL V5.0 W. Landsman September 1997
(See correl_optimize.pro)
NAME: CORRMAT_ANALYZE PURPOSE: Find the optimal (x,y) offset to maximize correlation of 2 images EXPLANATION: Analyzes the 2-D cross-correlation function of two images and finds the optimal(x,y) pixel offsets. Intended for use with function CORREL_IMAGES. CALLING SEQUENCE: corrmat_analyze, correl_mat, xoffset_optimum, yoffset_optimum, max_corr, edge, plateau, [XOFF_INIT=, YOFF_INIT=, REDUCTION=, MAGNIFICATION=, PLATEAU_THRESH=, /PRINT] INPUTS: correl_mat = the cross-correlation matrix of 2 images. (as computed by function CORREL_IMAGES( imA, imB ) ). NOTE: If correl_mat(*,*,1) is the number of pixels for each correlation, (the case when /NUMPIX was specified in call to CORREL_IMAGES) then sqrt( sqrt( # pixels )) is used as correlation weighting factor. OPTIONAL INPUT KEYWORDS: XOFF_INIT = initial X pixel offset of image_B relative to image_A. YOFF_INIT = Y pixel offset, (both as specified to correl_images). REDUCTION = reduction factor used in call to CORREL_IMAGES. MAGNIFICATION = magnification factor used in call to CORREL_IMAGES, this allows determination of offsets up to fractions of a pixel. PLATEAU_THRESH = threshold used for detecting plateaus in the cross-correlation matrix near maximum, (default=0.01), used only if MAGNIFICATION > 1 /PRINT causes the result of analysis to be printed. OUTPUTS: xoffset_optimum = optimal X pixel offset of image_B relative to image_A. yoffset_optimum = optimal Y pixel offset. max_corr = the maximal correlation corresponding to optimal offset. edge = 1 if maximum is at edge of correlation domain, otherwise=0. plateau = 1 if maximum is in a plateua of correlation function, else=0. PROCEDURE: Find point of maximum cross-correlation and calc. corresponding offsets. If MAGNIFICATION > 1: the correl_mat is checked for plateau near maximum, and if found, the center of plateau is taken as point of maximum cross-correlation. MODIFICATION HISTORY: Written, July-1991, Frank Varosi, STX @ NASA/GSFC Use ROUND instead of NINT, June 1995 Wayne Landsman HSTX Remove use of non-standard !DEBUG system variable W.L. HSTX Converted to IDL V5.0 W. Landsman September 1997
(See corrmat_analyze.pro)
NAME: CREATE_STRUCT PURPOSE: Create an IDL structure from a list of tag names and dimensions EXPLANATION: Dynamically create an IDL structure variable from list of tag names and data types of arbitrary dimensions. Useful when the type of structure needed is not known until run time. Unlike the intrinsic function CREATE_STRUCT(), this procedure does not require the user to know the number of tags before run time. (Note there is no name conflict since the intrinsic CREATE_STRUCT is a function, and this file contains a procedure.) CALLING SEQUENCE: CREATE_STRUCT, STRUCT, strname, tagnames, tag_descript, [ DIMEN = , /CHATTER, /NODELETE ] INPUTS: STRNAME - name to be associated with structure (string) Must be unique for each structure created. Set STRNAME = '' to create an anonymous structure TAGNAMES - tag names for structure elements (string or string array) TAG_DESCRIPT - String descriptor for the structure, containing the tag type and dimensions. For example, 'A(2),F(3),I', would be the descriptor for a structure with 3 tags, strarr(2), fltarr(3) and Integer scalar, respectively. Allowed types are 'A' for strings, 'B' or 'L' for unsigned byte integers, 'I' for integers, 'J' for longword integers, 'F' or 'E' for floating point, 'D' for double precision 'C' for complex, and 'M' for double complex Uninterpretable characters in a format field are ignored. For vectors, the tag description can also be specified by a repeat count. For example, '16E,2J' would specify a structure with two tags, fltarr(16), and lonarr(2) OPTIONAL KEYWORD INPUTS: DIMEN - number of dimensions of structure array (default is 1) CHATTER - If /CHATTER is set, then CREATE_STRUCT will display the dimensions of the structure to be created, and prompt the user whether to continue. Default is no prompt. NODELETE - If /NODELETE is set, then the temporary file created CREATE_STRUCT will not be deleted upon exiting. See below OUTPUTS: STRUCT - IDL structure, created according to specifications EXAMPLES: IDL> create_struct, new, 'name',['tag1','tag2','tag3'], 'D(2),F,A(1)' will create a structure variable new, with structure name NAME To see the structure of new: IDL> help,new,/struc ** Structure NAME, 3 tags, 20 length: TAG1 DOUBLE Array(2) TAG2 FLOAT 0.0 TAG3 STRING Array(1) PROCEDURE: Generates a temporary procedure file using input information with the desired structure data types and dimensions hard-coded. This file is then executed with CALL_PROCEDURE. NOTES: If CREATE_STRUCT cannot write a temporary .pro file in the current directory, then it will write the temporary file in the getenv('HOME') directory. At present, can fail if a tag_name cannot be used as a proper structure component definition, e.g., '0.10' will not work, but a typical string like 'RA' or 'DEC' will. A partial workaround checks for characters '\' and '/' and '.' and converts them to '_'. in a tag_name. Note that 'L' now specifies a LOGICAL (byte) data type and not a a LONG data type for consistency with FITS binary tables RESTRICTIONS: The name of the structure must be unique, for each structure created. Otherwise, the new variable will have the same structure as the previous definition (because the temporary procedure will not be recompiled). ** No error message will be generated *** SUBROUTINES CALLED: FDECOMP, GETTOK(), REPCHR() MODIFICATION HISTORY: Version 1.0 RAS January 1992 Modified 26 Feb 1992 for Rosat IDL Library (GAR) Modified Jun 1992 to accept arrays for tag elements -- KLV, Hughes STX Accept anonymous structures W. Landsman HSTX Sep. 92 Accept 'E' and 'J' format specifications W. Landsman Jan 93 'L' format now stands for logical and not long array Accept repeat format for vectors W. Landsman Feb 93 Accept complex and double complex (for V4.0) W. Landsman Jul 95 Work for long structure definitions W. Landsman Aug 97 Converted to IDL V5.0 W. Landsman September 1997 Write temporary file in HOME directory if necessary W. Landsman Jul 98
(See create_struct.pro)
NAME: CR_REJECT PURPOSE: General, iterative cosmic ray rejection using two or more input images. EXPLANATION: Similar to the STSDAS task crrej. Uses a noise model input by the user, rather than determining noise empirically from the images themselves. The image returned has the combined exposure time of all the input images, unless the bias flag is set, in which case the mean is returned. This image is computed by summation (or taking mean) regardless of loop and initialization options (see below). CALLING SEQUENCE: cr_reject, input_cube, rd_noise_dn, dark_dn, gain, mult_noise, $ combined_image, combined_npix, combined_noise MODIFIED ARGUMENT: input_cube - Cube in which each plane is an input image. On output, contains individual cleaned-up images. INPUT ARGUMENTS: rd_noise_dn - Read noise per pixel. Units of DN. If negative, then the user supplies an error cube via the keyword noise_cube. In the latter case, mult_noise still applies, since it is basically a fudge. dark_dn - Dark rate in DN per pixel per s. This can be a scalar, or it can be a dark image divided by the exposure time. gain - Electrons per DN. mult_noise - Coefficient for multiplicative noise term -- helps account for differing PSFs or subpixel image shifts. INPUT KEYWORDS: exptime - If the images have different exposure times, pass them in a vector. You can leave this off for frames with the same exposure time, but dark counts won't be treated correctly. verbose - If set, lots of output. nsig - Rejection limit in units of pixel-to-pixel noise (sigma) on each input image. Can be specified as an array, in which case the dimension gives the maximum number of iterations to run. (Default = [8, 6, 4] dilation - With dfactor, provides functionality similar to the expansion of the CR with pfactor and radius in STSDAS crrej. Dilate gives the size of the border to be tested around each initially detected CR pixel. E.g., dilate=1 searches a 9 X 9 area centered on the original pixel. If dfactor is set, the default is 1. dfactor - See dilation. This parameter is equivalent to pfactor in STSDAS crrej. The current threshold for rejection is multiplied by this factor when doing the search with the dilated mask. If dilation is set, the default for this parameter is 0.5. bias - Set if combining biases (divides through by number of images at end, since exposure time is 0). tracking_set - Subscripts of pixels, in terms of one component image, to be followed through the computation. verbose - Set to get messages. noskyadjust - Sky not to be subtracted before rejection tests. Default is to do the subtraction. The sky is added back in at the end so bias can be subtracted later if need be. xmedsky - Flag. If set, the sky is computed as a 1-d array which is a column-by-column median. This is intended for STIS slitless spectra. If sky adjustment is disabled, this keyword has no effect. The following keywords control how the current guess at a CR-free "check image" is recomputed on each iteration: median_loop - If set, the check image for each iteration is the pixel-by-pixel median. THE MEAN IS RETURNED in combined_image even is you set this option. (Default is mean_loop.) minimum_loop - If set, the check image for each iteration is the pixel-by-pixel minimum. THE MEAN IS RETURNED in combined_image even is you set this option. (Default is mean_loop.) mean_loop - If set, the check image for each iteration is the pixel-by-pixel mean. (Same as the default.) noclearmask - By default, the mask of CR flags is reset before every iteration, and a pixel that has been rejected has a chance to get back in the game if the average migrates toward its value. If this keyword is set, then any rejected pixel stays rejected in subsequent iterations. Note that what stsdas.hst_calib.wfpc.crrej does is the same as the default. For this procedure, the default was NOT to clear the flags, until 20 Oct. 1997. restore_sky - Flag. If set, the routine adds the sky back into the datacube before returning. skyvals - Sky value array. For an image cube with N planes, this array is fltarr(N) if the sky is a scalar per image plane, and fltarr(XDIM, N), is the XMEDSKY is set. null_value - Value to be used for output pixels to which no input pixels contribute. Default=0 The following keywords allow the initial guess at a CR-free "check image" to be of a different kind from the iterative guesses: init_med - If set, the initial check image is the pixel-by-pixel median. (Default is minimum.) init_mean - If set, the initial check image is the pixel-by-pixel mean. (Default is minimum.) init_min - If set, the initial check image is the pixel-by-pixel minimum. (Same as the default.) OUTPUT ARGUMENTS:: combined_image - Mean image with CRs removed. combined_npix - Byte (or integer) image of same dimensions as combined_image, with each element containing the number of non-CR stacked pixels that went into the result. combined_noise - Noise in combined image according to noise model or supplied noise cube. OUTPUT KEYWORD: mask_cube - CR masks for each input image. 1 means good pixel; 0 means CR pixel. INPUT/OUTPUT KEYWORD: noise_cube - Estimated noise in each pixel of input_cube as returned (if rd_noise_dn ge 0), or input noise per pixel of image_cube (if rd_noise_dn lt 0). COMMON BLOCKS: none SIDE EFFECTS: none METHOD: COMPARISON WITH STSDAS Cr_reject emulates the crrej routine in stsdas.hst_calib.wfpc. The two routines have been verified to give identical results under the following conditions: no sky adjustment no dilation of CRs initialization of trial image with minimum taking mean for each trial image after first (no choice in crrej) Dilation introduces a difference between crrej and this routine around the very edge of the image, because the IDL mask manipulation routines don't handle the edge the same way as crrej does. Away from the edge, crrej and cr_reject are the same with respect to dilation. The main difference between crrej and cr_reject is in the sky computation. Cr_reject does a DAOPHOT I sky computation on a subset of pixels grabbed from the image, whereas crrej searches for a histogram mode. REMARKS ON USAGE The default is that the initial guess at a CR-free image is the pixel-by-pixel minimum of all the input images. The pixels cut from each component image are the ones more than nsig(0) sigma from this minimum image. The next iteration is based on the mean of the cleaned-up component images, and the cut is taken at nsig(1) sigma. The next iteration is also based on the mean with the cut taken at nsig(2) sigma. The user can specify an arbitrary sequence of sigma cuts, e.g., nsig=[6,2] or nsig=[10,9,8,7]. The user can also specify that the initial guess is the median (/init_med) rather than the minimum, or even the mean. The iterated cleaned_up images after the first guess can be computed as the mean or the median (/mean_loop or /median_loop). The minimum_loop option is also specified, but this is a trivial case, and you wouldn't want to use it except perhaps for testing. The routine takes into account exposure time if you want it to, i.e., if the pieces of the CR-split aren't exactly the same. For bias frames (exposure time 0), set /bias to return the mean rather than the total of the cleaned-up component images. The crrej pfactor and radius to propagate the detected CRs outward from their initial locations have been implemented in slightly different form using the IDL DILATE function. It is possible to end up with output pixels to which no valid input pixels contribute. These end up with the value NULL_VALUE, and the corresponding pixels of combined_npix are also returned as 0. This result can occur when the pixel is very noisy across the whole image stack, i.e., if all the values are, at any step of the process, far from the stack average at that position even after rejecting the real outliers. Because pixels are flagged symmetrically N sigma above and below the current combined image (see code), all the pixels at a given position can end up getting flagged. (At least, that's how I think it happens.) MODIFICATION HISTORY: 5 Mar. 1997 - Written. R. S. Hill 14 Mar. 1997 - Changed to masking approach to keep better statistics and return CR-affected pixels to user. Option to track subset of pixels added. Dilation of initially detected CRs added. Other small changes. RSH 17 Mar. 1997 - Arglist and treatment of exposure times fiddled to mesh better with stis_cr. RSH 25 Mar. 1997 - Fixed bug if dilation finds nothing. RSH 4 Apr. 1997 - Changed name to cr_reject. RSH 15 Apr. 1997 - Restyled with emacs, nothing else done. RSH 18 Jun. 1997 - Input noise cube allowed. RSH 19 Jun. 1997 - Multiplicative noise deleted from final error. RSH 20 Jun. 1997 - Fixed error in using input noise cube. RSH 12 July 1997 - Sky adjustment option. RSH 27 Aug. 1997 - Dilation kernel made round, not square, and floating-point radius allowed. RSH 16 Sep. 1997 - Clearmask added. Intermediate as well as final mean is exptime weighted. RSH 17 Sep. 1997 - Redundant zeroes around dilation kernel trimmed. RSH 1 Oct. 1997 - Bugfix in preceding. RSH 21 Oct. 1997 - Clearmask changed to noclearmask. Bug in robust array division fixed (misplaced parens). Sky as a function of X (option). RSH 30 Jan. 1998 - Restore_sky keyword added. RSH 5 Feb. 1998 - Quick help corrected and updated. RSH 6 Feb. 1998 - Fixed bug in execution sequence for tracking_set option. RSH 18 Mar. 1998 - Eliminated confusing maxiter spec. Added null_value keyword. RSH 28 Jun 1998 - Converted to IDL V5.0 W. Landsman
(See cr_reject.pro)
NAME: CSPLINE PURPOSE: Function to evaluate a natural cubic spline at specified data points EXPLANATION: Combines the Numerical Recipes functions SPL_INIT and SPL_INTERP CALLING SEQUENCE: result = cspline( x, y, t, [ DERIV = ]) INPUTS: x - vector of spline node positions y - vector of node values t - x-positions at which to evaluate the spline, scalar or vector INPUT-OUTPUT KEYWORD: DERIV - values of the second derivatives of the interpolating function at the node points. This is an intermediate step in the computation of the natural spline that requires only the X and Y vectors. If repeated interpolation is to be applied to the same (X,Y) pair, then some computation time can be saved by supplying the DERIV keyword on each call. On the first call DERIV will be computed and returned on output. OUTPUT: the values for positions t are returned as the function value If any of the input variables are double precision, then the output will also be double precision; otherwise the output is floating point. EXAMPLE: The following uses the example vectors from the SPL_INTERP documentation IDL> x = (findgen(21)/20.0)*2.0*!PI ;X vector IDL> y = sin(x) ;Y vector IDL> t = (findgen(11)/11.0)*!PI ;Values at which to interpolate IDL> plot,x,y,psym=1 ;Plot original grid IDL> oplot, t,cspline(x,y,t),psym=2 ;Overplot interpolated values METHOD: The "Numerical Recipes" implementation of the natural cubic spline is used, by calling the intrinsic IDL functions SPL_INIT and SPL_INTERP. HISTORY: version 1 D. Lindler May, 1989 version 2 W. Landsman April, 1997 Rewrite using the intrinsic SPL_INIT & SPL_INTERP functions Converted to IDL V5.0 W. Landsman September 1997
(See cspline.pro)
NAME: CT2LST PURPOSE: To convert from Local Civil Time to Local Mean Sidereal Time. CALLING SEQUENCE: CT2LST, Lst, Lng, Tz, Time, [Day, Mon, Year] or CT2LST, Lst, Lng, Tz, JD INPUTS: Lng The longitude in degrees of the place for which the local sidereal time is desired, scalar. The Greenwich mean sidereal time (GMST) can be found by setting Lng = 0. Tz The time zone of the site in hours. Use this to easily account for Daylight Savings time (e.g. 4=EDT, 5 = EST/CDT), scalar Time or JD - If more than four parameters are specified, then this is the time of day of the specified date in decimal hours. If the exactly four parameters are specified, then this is the Julian date of time in question, scalar or vector OPTIONAL INPUTS: Day - The day of the month (1-31) Mon - The month, in numerical format (1-12) Year - The year (e.g. 1987) OUTPUTS: Lst The Local Sideral Time for the date/time specified in hours. RESTRICTIONS: If specified, the date should be in numerical form. The year should appear as yyyy. PROCEDURE: The Julian date of the day and time is question is used to determine the number of days to have passed since 0 Jan 2000. This is used in conjunction with the GST of that date to extrapolate to the current GST; this is then used to get the LST. See Astronomical Algorithms by Jean Meeus, p. 83 for the constants used. EXAMPLE: Find the Greenwich mean sidereal time (GMST) on 1987 April 10, 19h21m UT For GMST, we set lng=0, and for UT we set Tz = 0 IDL> CT2LST, lst, 0, 0,ten(19,21), 10, 4, 1987 ==> lst = 8.5825249 hours (= 8h 34m 57.0896s) PROCEDURES USED: jdcnv - Convert from year, month, day, hour to julian date MODIFICATION HISTORY: Adapted from the FORTRAN program GETSD by Michael R. Greason, STX, 27 October 1988. Use IAU 1984 constants Wayne Landsman, HSTX, April 1995, results differ by about 0.1 seconds Converted to IDL V5.0 W. Landsman September 1997
(See ct2lst.pro)
NAME: CURS PURPOSE: Selects an X windows cursor shape CALLING SEQUENCE: curs ;Interactively select a cursor shape. curs, sel ;Make the given CURSOR_STANDARD value the cursor shape. OPTIONAL INPUT: sel - Either an integer giving the CURSOR_STANDARD value (usually an even value between 0 and 152) indicating the cursor shape, or a string from the following menu a -- Up arrow b -- Left-angled arrow c -- Right-angled arrow d -- Crosshair e -- Finger pointing left f -- Finger pointing right g -- Narrow crosshair h -- Cycle through all possible standard cursor shapes OUTPUTS: None. RESTRICTIONS: Uses the CURSOR_STANDARD keyword of the DEVICE procedure. Although this keyword is available under Macintosh and Windows IDL, the values used by this procedure are specific to the X windows device. PROCEDURE: If the user supplies a valid cursor shape value, it is set. Otherwise, an interactive command loop is entered; it will continue until a valid value is given. MODIFICATION HISTORY: Converted to VAX 3100 workstations / IDL V2. M. Greason, STX, May 1990. Avoid bad cursor parameter values W. Landsman February, 1991 Don't change value of input param W. Landsman August 1995 Converted to IDL V5.0 W. Landsman September 1997
(See curs.pro)
NAME: CURVAL PURPOSE: Cursor controlled display of image intensities and astronomical coords EXPLANATION CURVAL displays different information depending whether the user supplied an image array, and/or a FITS header array CALLING SEQUENCE(S): curval ;Display x,y and byte intensity (inten) curval, im ;Display x,y,inten, and also pixel value (from image array) curval, hdr, [ im, OFFSET = , ZOOM =, FILEIMAGE =] OPTIONAL INPUTS: Hdr = FITS Header array Im = Array containing values that are displayed. Any type. OPTIONAL KEYWORD INPUTS: OFFSET - 2 element vector giving the location of the image pixel (0,0) on the window display. OFFSET can be positive (e.g if the image is centered in a larger window) or negative (e.g. if the only the central region of an image much larger than the window is being displayed. Default value is [0,0], or no offset. ZOOM - Scalar specifying the magnification of the window with respect to the image variable. Use, for example, if image has been REBINed before display. FILENAME = name of file to where CURVAL data can be saved. Data will only be saved if left or center mouse button are pressed. OUTPUTS: None. SIDE EFFECTS: X and Y values, etc., of the pixel under the cursor are constantly displayed. Pressing left or center mouse button prints a line of output, and starts a new line. Pressing right mouse button exits the procedure. If the keyword FILENAME is defined, the date and time, and a heading will be printed in the file before the data. PROCEDURES CALLED: EXTAST, GSSSXYAD, RADEC, SXPAR(), UNZOOM_XY, XY2AD REVISION HISTORY: Written, K. Rhode, STX May 1990 Added keyword FILENAME D. Alexander June 1991 Don't write to Journal file W. Landsman March 1993 Use astrometry structure W. Landsman Feb 1994 Modified for Mac IDL I. Freedman April 1994 Allow for zoomed or offset image W. Landsman Mar 1996 Proper rounding of zoomed pixel values W. Landsman/R. Hurt Dec. 1997 Converted to IDL V5.0 W. Landsman 10-Dec-1997
(See curval.pro)
NAME: DAOERF PURPOSE: Calulates the intensity, and derivatives, of a 2-d Gaussian PSF EXPLANATION: Corrects for the finite size of a pixel by integrating the Gaussian over the size of the pixel. Used in the IDL-DAOPHOT sequence. CALLING SEQUENCE: DAOERF, XIN, YIN, A, F, [ PDER ] INPUTS: XIN - input scalar, vector or array, giving X coordinate values YIN - input scalar, vector or array, giving Y coordinate values, must have same number of elements as XIN. A - 5 element parameter array describing the Gaussian A(0) - peak intensity A(1) - X position of peak intensity (centroid) A(2) - Y position of peak intensity (centroid) A(3) - X sigma of the gaussian (=FWHM/2.345) A(4) - Y sigma of gaussian OUTPUTS: F - array containing value of the function at each (XIN,YIN) The number of output elements in F and PDER is identical with the number of elements in X and Y OPTIONAL OUTPUTS: PDER - 2 dimensional array of size (NPTS,5) giving the analytic derivative at each value of F with respect to each parameter A. REVISION HISTORY: Written: W. Landsman October, 1987 Converted to IDL V5.0 W. Landsman September 1997
(See daoerf.pro)
NAME: DAO_VALUE PURPOSE: Returns the value of a DAOPHOT point-spread function at a set of points. EXPLANATION: The value of the point-spread function is the sum of a two-dimensional integral under a bivariate Gaussian function, and a value obtained by interpolation in a look-up table. DAO_VALUE will optionally compute the derivatives wrt X and Y CALLING SEQUENCE: Result = DAO_VALUE( xx, yy, gauss, psf, [ dvdx, dvdy ] ) INPUTS: XX,YY - the real coordinates of the desired point relative to the centroid of the point-spread function. GAUSS - 5 element vector describing the bivariate Gaussian GAUSS(0)- the peak height of the best-fitting Gaussian profile. GAUSS(1,2) - x and y offsets from the centroid of the point-spread function to the center of the best-fitting Gaussian. GAUSS(3,4) - the x and y sigmas of the best-fitting Gaussian. PSF - a NPSF by NPSF array containing the look-up table. OUTPUTS: RESULT - the computed value of the point-spread function at a position XX, YY relative to its centroid (which coincides with the center of the central pixel of the look-up table). OPTIONAL OUTPUTS: DVDX,DVDY - the first derivatives of the composite point-spread function with respect to x and y. NOTES although the arguments XX,YY of the function DAO_VALUE are relative to the centroid of the PSF, the function RINTER which DAO_VALUE calls requires coordinates relative to the corner of the array (see code). PROCEDURES CALLED: DAOERF, RINTER() REVISON HISTORY: Adapted to IDL by B. Pfarr, STX, 11/17/87 from 1986 STSDAS version of DAOPHOT Converted to IDL V5.0 W. Landsman September 1997
(See dao_value.pro)
NAME: DATATYPE() PURPOSE: Returns the data type of a variable. EXPLANATION: This routine returns the data type of a variable in a format specified by the optional flag parameter. CALLING SEQUENCE : Result = DATATYPE( VAR [, FLAG ] ) INPUTS: VAR = Variable to examine. OPTIONAL INPUT PARAMETERS: FLAG = Output format flag as explained below. The default is 0. OUTPUT PARAMETRS: The result of the function is the either a string or integer giving the data type of VAR. Depending on the value of FLAG, the result will be one of the values from the following table: FLAG = 0 FLAG = 1 FLAG = 2 FLAG = 3 UND Undefined 0 UND BYT Byte 1 BYT INT Integer 2 INT LON Long 3 LON FLO Float 4 FLT DOU Double 5 DBL COM Complex 6 COMPLEX STR String 7 STR STC Structure 8 STC DCO DComplex 9 DCOMPLEX PTR Pointer 10 POINTER OBJ Object 11 OBJECT OPTIONAL INPUT KEYWORD: HELP = If set, then a short explanation is printed out. RESTRICTIONS: FLAG, if passed, must be an integer between 0 and 3. Copyright (C) 1985, Johns Hopkins University/Applied Physics Laboratory This software may be used, copied, or redistributed as long as it is not sold and this copyright notice is reproduced on each copy made. This routine is provided as is without any express or implied warranties whatsoever. Other limitations apply as described in the file disclaimer.txt. REVISION HISTORY: R. Sterner, JHU/APL, 24 October 1985. R. Sterner, 18 Mar, 1993 --- Added /DESCRIPTOR. R. Sterner, 1995 Jul 24 --- Added DCOMPLEX for data type 9. D. Zarro, 1997 Jul 19 --- Added PTR and OBJ for data type 10 and 11. Converted to IDL V5.0 W. Landsman September 1997
(See datatype.pro)
NAME: DATE PURPOSE: Convert day-of-year to a DD-MMM-YYYY string CALLING SEQUENCE: D_String = DATE(Year, day ) INPUTS: Year - Integer scalar specifying the year. If the year contains only two digits, then it is assumed to indicate the number of years after 1900. Day - Integer scalar giving number of days after Jan 0 of the specified year. Can be larger than 366 OUTPUTS: D_String - String giving date in format '13-MAR-1986' RESTRICTIONS: Will not work for years before 100 AD EXAMPLE: IDL> print, date(1997,279) '6-Oct-1997' MODIFICATION HISTORY: D.M. fecit 24 October,1983 Work for years outside of the 19th century W. Landsman September 1997 Converted to IDL V5.0 W. Landsman September 1997
(See date.pro)
NAME: DATE_CONV PURPOSE: Procedure to perform conversion of dates to a choice of three formats EXPLANATION: The three possible output date formats are format 1: real*8 scalar encoded as: (year-1900)*1000 + day + hour/24. + min/24./60 + sec/24./60/60 where day is the day of year (1 to 366) format 2: Vector encoded as: date(0) = year (eg. 1987 or just 87) date(1) = day of year (1 to 366) date(2) = hour date(3) = minute date(4) = second format 3: string (ascii text) encoded as DD-MON-YEAR HH:MM:SS.SS (eg. 14-JUL-1987 15:25:44.23) format 4: three element vector giving spacecraft time words from ST telemetry packet. CALLING SEQUENCE results = DATE_CONV( DATE, TYPE ) INPUTS: DATE - input date in one of the three possible formats. TYPE - type of output format desired. If not supplied then format 3 (real*8 scalar) is used. valid values: 'REAL' - format 1 'VECTOR' - format 2 'STRING' - format 3 TYPE can be abbreviated to the single character strings 'R', 'V', and 'S'. Nobody wants to convert TO spacecraft time (I hope!) OUTPUTS: The converted date is returned as the function value. HISTORY: version 1 D. Lindler July, 1987 adapted for IDL version 2 J. Isensee May, 1990 Converted to IDL V5.0 W. Landsman September 1997
(See date_conv.pro)
NAME: DAYCNV PURPOSE: Converts Julian dates to Gregorian calendar dates CALLING SEQUENCE: DAYCNV, XJD, YR, MN, DAY, HR INPUTS: XJD = Julian date, positive double precision scalar or vector OUTPUTS: YR = Year (Integer) MN = Month (Integer) DAY = Day (Integer) HR = Hours and fractional hours (Real). If XJD is a vector, then YR,MN,DAY and HR will be vectors of the same length. EXAMPLE: IDL> DAYCNV, 2440000.D, yr, mn, day, hr yields yr = 1968, mn =5, day = 23, hr =12. WARNING: Be sure that the Julian date is specified as double precision to maintain accuracy at the fractional hour level. METHOD: Uses the algorithm of Fliegel and Van Falndern (1968) as reported in the "Explanatory Supplement to the Astronomical Almanac" (1992), p. 604 Works for all Gregorian calendar dates with XJD > 0, i.e., dates after -4713 November 23. REVISION HISTORY: Converted to IDL from Yeoman's Comet Ephemeris Generator, B. Pfarr, STX, 6/16/88 Converted to IDL V5.0 W. Landsman September 1997
(See daycnv.pro)
NAME: DBBUILD PURPOSE: Build a database by appending new values for every item. EXPLANATION: The database must be opened for update (with DBOPEN) before calling DBBUILD. CALLING SEQUENCE: DBBUILD, [ v1, v2, v3, v4......v30, /NOINDEX, /SILENT, STATUS = ] INPUTS: v1,v2....v30 - vectors containing values for all items in the database. V1 contains values for the first item, V2 for the second, etc. The number of vectors supplied must equal the number of items (excluding entry number) in the database. The number of elements in each vector should be the same. A multiple valued item should be dimensioned NVALUE by NENTRY, where NVALUE is the number of values, and NENTRY is the number of entries. OPTIONAL INPUT KEYWORDS: NOINDEX - If this keyword is supplied and non-zero then DBBUILD will *not* create an indexed file. Useful to save time if DBBUILD is to be called several times and the indexed file need only be created on the last call SILENT - If the keyword SILENT is set and non-zero, then DBBUILD will not print a message when the index files are generated OPTIONAL OUTPUT KEYWORD: STATUS - Returns a status code denoting whether the operation was successful (1) or unsuccessful (0). Useful when DBBUILD is called from within other applications. EXAMPLE: Suppose a database named STARS contains the four items NAME,RA,DEC, and FLUX. Assume that one already has the four vectors containing the values, and that the database definition (.DBD) file already exists. IDL> !PRIV=2 ;Writing to database requires !PRIV=2 IDL> dbcreate,'stars',1,1 ;Create database (.DBF) & index (.DBX) file IDL> dbopen,'stars',1 ;Open database for update IDL> dbbuild,name,ra,dec,flux ;Write 4 vectors into the database NOTES: Do not call DBCREATE before DBBUILD if you want to append entries to an existing database DBBUILD checks that each value vector matches the idl type given in the database definition (.DBD) file, and that character strings are the proper length. REVISION HISTORY: Written W. Landsman March, 1989 Added /NOINDEX keyword W. Landsman November, 1992 User no longer need supply all items W. Landsman December, 1992 Added STATUS keyword, William Thompson, GSFC, 1 April 1994 Added /SILENT keyword, William Thompson, GSFC, October 1995 Allow up to 30 items, fix problem if first item was multiple value W. Landsman GSFC, July 1996 Faster build of external databases on big endian machines W. Landsman GSFC, November 1997 Converted to IDL V5.0 W. Landsman 24-Nov-1997
(See dbbuild.pro)
NAME: DBCIRCLE PURPOSE: Find sources in a database within specified radius of specified center EXPLANATION: Database must include items named 'RA' and 'DEC' and must have previously been opened with DBOPEN CALLING SEQUENCE: list = DBCIRCLE( ra_cen, dec_cen, [radius, dis, sublist, /SILENT] ) INPUTS: RA_CEN - Right ascension of the search center in decimal HOURS, scalar DEC_CEN - Declination of the search center in decimal DEGREES, scalar RA_CEN and DEC_CEN should be in the same equinox as the currently opened catalog. OPTIONAL INPUT: RADIUS - Radius of the search field in arc minutes, scalar. DBCIRCLE prompts for RADIUS if not supplied. SUBLIST - Vector giving entry numbers in currently opened database to be searched. Default is to search all entries OUTPUTS: LIST - Vector giving entry numbers in the currently opened catalog which have positions within the specified search circle LIST is set to -1 if no sources fall within the search circle !ERR is set to the number sources found. OPTIONAL OUTPUT DIS - The distance in arcminutes of each entry specified by LIST to the search center (given by RA_CEN and DEC_CEN) OPTIONAL KEYWORD INPUT: SILENT - If this keyword is set, then DBCIRCLE will not print the number of entries found at the terminal TO_J2000 - If this keyword is set, then the entered coordinates are assumed to be in equinox B1950, and will be converted to J2000 before searching the database TO_B1950 - If this keyword is set, then the entered coordinates are assumed to be in equinox J2000, and will be converted to B1950 before searching the database NOTE: The user must determine on his own whether the database is in B1950 or J2000 coordinates. METHOD: A DBFIND search is first performed on a square area of given radius. The list is the restricted to a circular area by using GCIRC to compute the distance of each object to the field center. EXAMPLE: Find all SAO stars within 40' of the nucleus of M33 (at 1h 31m 1.67s 30d 24' 15'') IDL> dbopen,'sao' IDL> list = dbcircle( ten(1,31,1.67), ten(30,24,15), 40) REVISION HISTORY: Written W. Landsman STX January 1990 Fixed search when crossing 0h July 1990 Spiffed up code a bit October, 1991 Converted to IDL V5.0 W. Landsman September 1997
(See dbcircle.pro)
NAME: DBCLOSE PURPOSE: procedure to close a data base file CALLING SEQUENCE: dbclose INPUTS: None OUTPUTS None SIDE EFFECTS: the data base files currently opened are closed PROCEDURE CALLS: DB_INFO(), HOST_TO_IEEE HISTORY: version 2 D. Lindler Oct. 1987 For IDL version 2 August 1990 William Thompson, GSFC/CDS (ARC), 30 May 1994 Added support for external (IEEE) data format Converted to IDL V5.0 W. Landsman September 1997
(See dbclose.pro)
NAME: DBCOMPARE PURPOSE: Display two entries in an IDL database side by side in a column format CALLING SEQUENCE: dbcompare, list1, list2, [items, TEXTOUT= , /DIFF] INPUTS: list - list of entry numbers to be printed, vector or scalar if list = -1, then all entries will be printed. An error message is returned if any entry number is larger than the number of entries in the database OPTIONAL INPUT-OUTPUT: items - items to be printed, specified in any of the following ways: form 1 scalar string giving item(s) as list of names separated by commas form 2 string array giving list of item names form 3 string of form '$filename' giving name of text file containing items (one item per line) form 4 integer scalar giving single item number or integer vector list of item numbers form 5 Null string specifying interactive selection. This is the default if 'items' is not supplied form 6 '*' select all items, printout will be in table format. If items was undefined or a null string on input, then on output it will contain the items interactively selected. OPTIONAL INPUT KEYWORDS: DIFF - If this keyword is set and non-zero, then only the items in the database that differ will be printed TEXTOUT - Integer (1-7) Used to determine output device. See TEXTOPEN for more info. SYSTEM VARIABLES: Output device controlled by non-standard system variable !TEXTOUT, if TEXTOUT keyword is not used. EXAMPLE: Display entries 3624 and 3625 in column form showing only the items that differ. IDL> dbcompare,3624,3625,/diff HISTORY: Written, W. Landsman July 1996 Converted to IDL V5.0 W. Landsman September 1997
(See dbcompare.pro)
NAME DBCOMPRESS PURPOSE: Compress a .dbf database file after a call to DBDELETE EXPLANATION: The procedure DBDELETE will remove specified entries from a database but it will not free the unused space. DBCOMPRESS will compress the .dbf file so that it only contains valid entries. CALLING SEQUENCE: DBCOMPRESS, dbname INPUT PARAMETERS: dbname - Name of the database to be compressed, scalar string NOTES: (1) Will not compress the index (.dbx) file. The size of the .dbx file is controlled by the MaxEntries value in the database definition (.dbd) file (2) The updated .dbf file is written in the current directory. This may need to be moved into the ZDBASE directory. PROCEDURE CALLS: DBOPEN, DB_INFO(), FIND_WITH_DEF() REVISION HISTORY: Written, W. Landsman Raytheon STX May 1998 Converted to IDL V5.0 June 1998
(See dbcompress.pro)
NAME: DBCREATE PURPOSE: Create a new data base (.dbf), index (.dbx) or description (.dbh) file EXPLANATION: A database definition (.dbd) file must already exist. The default directory must be a ZDBASE: directory. CALLING SEQUENCE: dbcreate, name,[ newindex, newdb, maxitems] [,/EXTERNAL] INPUTS: name- name of the data base (with no qualifier), scalar string. The description will be read from the file "NAME".dbd OPTIONAL INPUTS: newindex - if non-zero then a new index file is created, otherwise it is assumed that changes do not affect the index file. (default=0) newdb - if non-zero then a new data base file (.dbf) will be created. Otherwise changes are assumed not to affect the file's present format. maxitems - maximum number of items in data base. If not supplied then the number of items is limited to 200. OUTPUTS: NONE. OPTIONAL INPUT KEYWORD: external - If set, then the database is written with an external data representation. This allows the database files to be used on any computer platform, e.g. through NFS mounts, but some overhead is added to reading the files. The default is to write the data in the native format of the computer being used. This keyword is only paid attention to if NEWDB or NEWINDEX are nonzero. Otherwise, the database is opened to find out if it uses external representation or not. Extreme caution should be used if this keyword is used with only NEWINDEX set to a nonzero value. This mode is allowed so that databases written on machines which already use the external data representation format, e.g. Sun workstations, to be marked external so that other machines can read them. PROCEDURE CALLS: GETTOK(), FIND_WITH_DEF(), ZPARCHECK RESTRICTIONS: If newdb=0 is not specified, the changes to the .dbd file can not alter the length of the records in the data base file. and may not alter positions of current fields in the file. permissible changes are: 1) utilization of spares to create a item or field 2) change in field name(s) 3) respecification of index items 4) changes in default print formats 5) change in data base title 6) changes in pointer specification to other data data bases !priv must be 2 or greater to execute this routine. SIDE EFFECTS: data base description file ZDBASE:name.dbh is created and optionally ZDBASE:name.dbf (data file) and ZDBASE.dbx (index file) if it is a new data base. REVISION HISTORY: D. Lindler, GSFC/HRS, October 1987 Modified: Version 1, William Thompson, GSFC, 29 March 1994 Version 2, William Thompson, GSFC/CDS (ARC), 28 May 1994 Added EXTERNAL keyword. Version 4, William Thompson, GSFC, 3 November 1994 Modified to allow ZDBASE to be a path string. 8/14/95 JKF/ACC - allow EXTERNAL data for newindex OR newdb modes. Make sure all databases closed before starting W. Landsman June 1997 Converted to IDL V5.0 W. Landsman September 1997
(See dbcreate.pro)
NAME: DBDELETE PURPOSE Deletes specified entries from data base CALLING SEQUENCE: DBDELETE, list, [ name, /DEBUG ] INPUTS: list - list of entries to be deleted, scalar or vector name - optional name of data base, scalar string. If not specified then the data base file must be previously opened for update by DBOPEN. OPERATIONAL NOTES: !PRIV must be at least 3 to execute. SIDE EFFECTS: The data base file (ZDBASE:name.DBF) is modified by removing the specified entries and reordering the remaining entry numbers accordingly (ie. if you delete entry 100, it will be replaced by entry 101 and the database will contain 1 less entry. EXAMPLE: Delete entries in a database STARS where RA=DEC = 0.0 IDL> !PRIV= 3 ;Set privileges IDL> dbopen,'STARS',1 ;Open for update IDL> list = dbfind('ra=0.0,dec=0.0') ;Obtain LIST vector IDL> dbdelete, list ;Delete specified entries from db NOTES: The procedure is rather slow because the entire database is re- created with the specified entries deleted. OPTIONAL KEYWORD INPUT: DEBUG - if this keyword is set and non-zero, then additional diagnostics will be printed as each entry is deleted. COMMON BLOCKS: DBCOM PROCEDURE CALLS: DBINDEX, DB_INFO(), DBOPEN, DBPUT, ZPARCHECK HISTORY Version 2 D. Lindler July, 1989 Updated documentation W. Landsman December 1992 William Thompson, GSFC, 28 February 1995 Fixed bug when external representation used. Fixed for case where second parameter supplied W. Landsman April 1996 Use keyword DEBUG rather than !DEBUG W. Landsman May 1997 Converted to IDL V5.0 W. Landsman September 1997
(See dbdelete.pro)
NAME: DBEDIT PURPOSE: Interactively edit specified fields in a database. EXPLANATION: The value of each field is displayed, and the user has the option of changing or keeping the value. Widgets will be used if they are available. CALLING SEQUENCE: dbedit, list, [ items ] INPUTS: list - scalar or vector of database entry numbers. Set list = 0 to interactively add a new entry to a database. Set list = -1 to edit all entries. OPTIONAL INPUTS: items - list of items to be edited. If omitted, all fields can be edited. COMMON BLOCKS: DB_COM -- contains information about the opened database. DBW_C -- contains information intrinsic to this program. SIDE EFFECTS: Will update the database files. RESTRICTIIONS: Database must be opened for update prior to running this program. User must be running DBEDIT from an account that has write privileges to the databases. If one is editing an indexed item, then after all edits are complete, DBINDEX will be called to reindex the entire item. This may be time consuming. Cannot be used to edit items with multiple values EXAMPLE: Suppose one had new parallaxes for all stars fainter than 5th magnitude in the Yale Bright Star Catalog and wanted to update the PRLAX and PRLAX_CODE fields with these new numbers IDL> !priv=2 IDL> dbopen, 'yale_bs', 1 ;Open catalog for update IDL> list = dbfind( 'v>5') ;Find fainter than 5th magnitude IDL> dbedit, list, 'prlax, prlax_code' ;Manual entry of new values PROCEDURE: (1) Use the cursor and point to the value you want to edit. (2) Type the new field value over the old field value. (3) When you are done changing all of the field values for each entry save the entry to the databases by pressing 'SAVE ENTRY TO DATABASES'. Here all of the values will be checked to see if they are the correct data type. If a field value is not of the correct data type, it will not be saved. Use the buttons "PREV ENTRY" and "NEXT ENTRY" to move between entry numbers. You must save each entry before going on to another entry in order for your changes to be saved. Pressing "RESET THIS ENTRY" will remove any unsaved changes to the current entry. REVISION HISTORY: Adapted from Landsman's DBEDIT added widgets, Melissa Marsh, HSTX, August 1993 do not need to press return after entering each entry, fixed layout problem on SUN, Melissa Marsh, HSTX, January 1994 Only updates the fields which are changed. Joel Offenberg, HSTX, Mar 94 Corrected test for changed fields Wayne Landsman HSTX, Mar 94 Removed a couple of redundant statements W. Landsman HSTX Jan 96 Converted to IDL V5.0 W. Landsman September 1997
(See dbedit.pro)
NAME: DBEDIT_BASIC PURPOSE: Subroutine of DBEDIT_BASIC to edit a database on a dumb terminal. EXPLANATION: Interactively edit specified fields in a database. The value of each field is displayed, and the user has the option of changing or keeping the value. CALLING SEQUENCE: dbedit_basic, list, [ items ] INPUTS: list - scalar or vector of database entry numbers. Set LIST=0 to interactively add a new entry to a database. OPTIONAL INPUTS items - list of items to be edited. If not supplied, then the value of every field will be displayed. NOTES: (1) Database must be opened for update (dbopen,,1) before calling DBEDIT_BASIC. User must have write privileges on the database files. (2) User gets a second chance to look at edited values, before they are actually written to the database PROMPTS: The item values for each entry to be edited are first displayed User is the asked "EDIT VALUES IN THIS ENTRY (Y(es), N(o), or Q(uit))? If user answers 'Y' or hits RETURN, then each item is displayed with its current value, which the user can update. If user answered 'N' then DBEDIT_BASIC skips to the next entry. If user answers 'Q' then DBEDIT will exit, saving all previous changes. EXAMPLE: Suppose V magnitudes (V_MAG) in a database STARS with unknown values were assigned a value of 99.9. Once the true values become known, the database can be edited IDL> !PRIV=2 & dbopen,'STARS',1 ;Open database for update IDL> list = dbfind('V_MAG=99.9') ;Get list of bad V_MAG values IDL> dbedit,list,'V_MAG' ;Interactively insert good V_MAG values REVISION HISTORY: Written W. Landsman STX April, 1989 Rename DBEDIT_BASIC from DBEDIT July, 1993 Converted to IDL V5.0 W. Landsman September 1997
(See dbedit_basic.pro)
NAME: DBEXT PURPOSE: Extract values of up to 12 items from an IDL database EXPLANATION: Procedure to extract values of up to 12 items from data base file, and place into IDL variables CALLING SEQUENCE: dbext,list,items,v1,[v2,v3,v4,v5,v6,v7,v8,v9,v10,v11,v12] INPUTS: list - list of entry numbers to be printed, vector or scalar If list = -1, then all entries will be extracted. list may be converted to a vector by DBEXT items - standard item list specification. See DBPRINT for the 6 different ways that items may be specified. OUTPUTS: v1...v12 - the vectors of values for up to 12 items. EXAMPLE: Extract all RA and DEC values from the currently opened database, and place into the IDL vectors, IDLRA and IDLDEC. IDL> DBEXT,-1,'RA,DEC',idlra,idldec HISTORY version 2 D. Lindler NOV. 1987 check for INDEXED items W. Landsman Feb. 1989 Converted to IDL V5.0 W. Landsman September 1997
(See dbext.pro)
NAME: DBEXT_DBF PURPOSE: Subroutine of DBEXT to extract values of up to 15 items from a database EXPLANATION: This is a subroutine of DBEXT, which is the routine a user should normally use. CALLING SEQUENCE: dbext_dbf,list,dbno,sbyte,nbytes,idltype,nval,v1,[ v2,v3,v4,v5,v6,v7, v8,v9,v10,v11,v12, ITEM_DBNO = ] INPUTS: list - list of entry numbers to extract desired items. It is the entry numbers in the primary data base unless dbno is greater than or equal to -1. In that case it is the entry number in the specified data base. dbno - number of the opened db file if set to -1 then all data bases are included sbyte - starting byte in the entry. If single data base then it must be the starting byte for that data base only and not the concatenation of db records nbytes - number of bytes in the entry idltype - idl data type of each item to be extracted nval - number of values per entry of each item to be extracted OUTPUTS: v1...v12 - the vectors of values for up to 12 items OPTIONAL INPUT KEYWORD: item_dbno - A vector of the individual database numbers for each item. Simplifies the code for linked databases PROCEDURE CALLS: DB_INFO(), DB_ITEM_INFO(), DBRD, DBXVAL(), IS_IEEE_BIG(), IEEE_TO_HOST HISTORY version 1 D. Lindler Nov. 1987 Extract multiple valued entries W. Landsman May 1989 William Thompson, GSFC/CDS (ARC), 1 June 1994 Added support for external (IEEE) representation. Work with multiple element string items W. Landsman August 1995 Increase speed for external databases on IEEE machines WBL August 1996 IEEE conversion implemented on blocks of entries using BIG Added keyword ITEM_DBNO R. Schwartz, GSFC/SDAC, August 1996 Return a vector even if only 1 value W. Thompson October 1996 Change variable name of BYTESWAP to BSWAP W. Thompson Mar 1997 Use /OVERWRITE with reform W. Landsman May 1997 Converted to IDL V5.0 W. Landsman September 1997
(See dbext_dbf.pro)
NAME: DBEXT_IND PURPOSE: routine to read a indexed item values from index file CALLING SEQUENCE: dbext_ind,list,item,dbno,values INPUTS: list - list of entry numbers to extract values for (if it is a scalar, values for all entries are extracted) item - item to extract dbno - number of the opened data base OUTPUT: values - vector of values returned as function value HISTORY: version 1 D. Lindler Feb 88 Faster processing of string values W. Landsman April, 1992 William Thompson, GSFC/CDS (ARC), 30 May 1994 Added support for external (IEEE) data format Converted to IDL V5.0 W. Landsman September 1997
(See dbext_ind.pro)
NAME: DBFIND() PURPOSE: Search data base for entries with specified characteristics EXPLANATION: Function to search data base for entries with specified search characteristics. CALLING SEQUENCE: result = dbfind(spar,[ listin, /SILENT, /FULLSTRING, ERRMSG= ]) INPUTS: spar - search_parameters (string)...each search parameter is of the form: option 1) min_val < item_name < max_val option 2) item_name = value option 3) item_name = [value_1, value_10] Note: option 3 is also the slowest. option 4) item_name > value option 5) item_name < value option 6) item_name = value(tolerance) ;eg. temp=25.0(5.2) option 7) item_name ;must be non-zero Multiple search parameters are separated by a comma. eg. 'cam_no=2,14is interpreted as greater than or equal. RA and DEC keyfields are stored as floating point numbers in the data base may be entered as HH:MM:SEC and DEG:MIN:SEC. Where: HH:MM:SEC equals HH + MM/60.0 + SEC/3600. DEG:MIN:SEC equals DEG + MIN/60.0 + SEC/3600. For example: 40:34:10.5 < dec < 43:25:19 , 8:22:1.0 < ra < 8:23:23.0 Specially encoded date/time in the data base may be entered by YY/DAY:hr:min:sec which is interpreted as YY*1000+DAY+hr/24.0+min/24.0/60.+sec/24.0/3600. For example 85/201:10:35:30 (See dbfind.pro)
DBFIND_ENTRY
[Previous Routine] [Next Routine] [List of Routines]NAME: DBFIND_ENTRY PURPOSE: Subroutine of DBFIND to perform an entry number search EXPLANATION: This is a subroutine of dbfind and is not a standalone procedure It performs a entry number search. CALLING SEQUENCE: dbfind_entry, type, svals, nentries, values INPUTS: type - type of search (output from dbfparse) svals - search values (output from dbfparse) values - array of values to search OUTPUT: good - indices of good values !err is set to number of good values REVISION HISTORY: D. Lindler July,1987 Fixed test for final entry number W. Landsman Sept. 95 Converted to IDL V5.0 W. Landsman September 1997(See dbfind_entry.pro)
DBFIND_SORT
[Previous Routine] [Next Routine] [List of Routines]NAME: DBFIND_SORT PURPOSE: Subroutine of DBFIND to perform a search using sorted values EXPLANATION: This is a subroutine of dbfind and is not a standalone procedure It is used to limit the search using sorted values CALLING SEQUENCE: dbfind_sort, it, type, svals, list INPUT: it - item number, scalar type - type of search (output from dbfparse) svals - search values (output from dbfparse) INPUT/OUTPUT: list - found entries !err is set to number of good values !ERR = -2 for an invalid search INPUT KEYWORD: FULLSTRING - By default, one has a match if a search string is included in any part of a database value (substring match). But if /FULLSTRING is set, then all characters in the database value must match the search string (excluding leading and trailing blanks). Both types of string searches are case insensitive. REVISION HISTORY: D. Lindler July,1987 William Thompson, GSFC/CDS (ARC), 30 May 1994 Added support for external (IEEE) data format William Thompson, GSFC, 14 March 1995 Added keyword FULLSTRING Converted to IDL V5.0 W. Landsman September 1997(See dbfind_sort.pro)
DBFPARSE
[Previous Routine] [Next Routine] [List of Routines]NAME: DBFPARSE PURPOSE Parse the search string supplied to DBFIND. Not a standalone routine CALLING SEQUENCE: DBFPARSE, [ spar, items, stype, values ] INPUTS: spar - search parameter specification, scalar string OUTPUTS: items - list of items to search on stype - search type, numeric scalar 0 item=values(j,0) -1 item>values(j,0) -2 item(See dbfparse.pro)
DBGET
[Previous Routine] [Next Routine] [List of Routines]NAME: DBGET PURPOSE: Find entry numbers which contain specified values of a given item. EXPLANATION: DBGET() is useful as an alternative to DBFIND() when the desired search values are not easily expressed as a string. CALLING SEQUENCE: list = dbget( item, values, [ listin ], /SILENT, /FULLSTRING ) INPUTS: item - Item name or number values - scalar or vector containing item values to search for. OPTIONAL INPUTS: listin - list of entries to be searched. If not supplied, or set to -1, then all entries are searched OUTPUT: list - vector giving the entry number of entries containing desired item values. The number of elements in LIST may be different from that of VALUE, since a value might be located zero, once, or many times in the database. Use the function DBMATCH if a one to one correspondence is desired between VALUES and LIST. OPTIONAL INPUT KEYWORDS: SILENT - If this keyword is supplied, then DBGET will not display the number of entries found FULLSTRING - By default, one has a match if a search string is included in any part of a database value (substring match). But if /FULLSTRING is set, then all characters in the database value must match the search string (excluding leading and trailing blanks). Both types of string searches are case insensitive. RESTRICTIONS: When linked databases are opened together, DBGET can only be used to search on items in the primary database. EXAMPLE: Get info on selected HD stars in Bright Star catalogue IDL> dbopen, 'YALE_BS' IDL> hdno = [1141,2363,3574,4128,6192,6314,6668] ;Desired HD numbers IDL> list = dbget( 'HD', hdno ) ;Get corresponding entry numbers SYSTEM VARIABLES: !ERR is set to the number of entries found REVISION HISTORY: Written, W. Landsman STX February, 1989 William Thompson, GSFC, 14 March 1995 Added keyword FULLSTRING Converted to IDL V5.0 W. Landsman September 1997(See dbget.pro)
DBHELP
[Previous Routine] [Next Routine] [List of Routines]NAME: DBHELP PURPOSE: List available databases or items in the currently open database EXPLANATION: Procedure to either list available databases (if no database is currently open) or the items in the currently open database. CALLING SEQUENCE: dbhelp, [ flag , TEXTOUT = ] INPUT: flag - (optional) if set to nonzero then item or database descriptions are also printed default=0 If flag is a string, then it is interpreted as the name of a data base (if no data base is opened) or a name of an item in the opened data base. In this case, help is displayed only for the particular item or database OUTPUTS: None OPTIONAL INPUT KEYWORDS: textout Used to determine output device. If not present, the value of !TEXTOUT system variable is used (see TEXTOPEN ) textout=1 Terminal with /MORE textout=2 Terminal without /MORE textout=3.PRT textout=4 LASER PRINTER textout=5 USER MUST OPEN FILE; METHOD: If no data base is opened then a list of data bases are printed, otherwise the items in the open data base are printed. If a string is supplied for flag and a data base is opened flag is assumed to be an item name. The information for that item is printed along with contents in a optional file zdbase:dbname_itemname.hlp if a string is supplied for flag and no data base is opened, then string is assumed to be the name of a data base file. only information for that file is printed along with an optional file zdbase:dbname.hlp. HISTORY Version 2 D. Lindler Nov 1987 (new db format) Faster printing of title desc. W. Landsman May 1989 Keyword textout added, J. Isensee, July, 1990 Modified to work on Unix, D. Neill, ACC, Feb 1991. William Thompson, GSFC/CDS (ARC), 1 June 1994 Added support for external (IEEE) representation. William Thompson, GSFC, 3 November 1994 Modified to allow ZDBASE to be a path string. Remove duplicate database names Wayne Landsman December 1994 8/17/95 jkf/acc - force lowercase filenames for .hlp files. Converted to IDL V5.0 W. Landsman September 1997 (See dbhelp.pro)
DBINDEX
[Previous Routine] [Next Routine] [List of Routines]NAME: DBINDEX PURPOSE: Procedure to create index file for data base CALLING SEQUENCE: dbindex, [ items ] OPTIONAL INPUT: items - names or numbers of items to be index -- if not supplied, then all indexed fields will be processed. OUTPUT: Index file.dbx is created on disk location ZDBASE: OPERATIONAL NOTES: (1) Data base must have been previously opened for update by DBOPEN (2) Only 15 items can be indexed at one time. If the database has more than 15 items, then two separate calls to DBINDEX are needed. PROCEDURES CALLED: DBINDEX_BLK, DB_INFO(), DB_ITEM, DB_ITEM_INFO(), IEEE_TO_HOST, IS_IEEE_BIG() HISTORY: version 2 D. Lindler Nov 1987 (new db format) W. Landsman added optional items parameter Feb 1989 M. Greason converted to IDL version 2. June 1990. William Thompson, GSFC/CDS (ARC), 30 May 1994 Added support for external (IEEE) data format Test if machine is bigendian W. Landsman May, 1996 Change variable name of BYTESWAP to BSWAP W. Thompson Mar, 1997 Increased number of fields to 15 W. Landsman June, 1997 Converted to IDL V5.0 W. Landsman September 1997 (See dbindex.pro)
DBINDEX_BLK
[Previous Routine] [Next Routine] [List of Routines]NAME: DBINDEX_BLK PURPOSE: Subroutine of DBINDEX to create associated variable of correct datatype EXPLANATION: DBINDEX_BLK will offset into the file by a specified amount in preparation for writing to the file. CALLING SEQUENCE: res = dbindex_blk(unit, nb, bsz, ofb, dtype) INPUTS: unit The unit number assigned to the file. nb The number of blocks to offset into the file. bsz The size of each block, in bytes, to offset into the file. ofb The offset into the block, in bytes. dtype The IDL datatype as defined in the SIZE function OUTPUTS: res The returned variable. This is an associated variable. RESTRICTIONS: The file must have been previously opened. MODIFICATION HISTORY: Written by Michael R. Greason, STX, 14 June 1990. Converted to IDL V5.0 W. Landsman September 1997(See dbindex_blk.pro)
DBMATCH