Документ взят из кэша поисковой машины. Адрес
оригинального документа
: http://www.arcetri.astro.it/CC/Manuals/astron.html
Дата изменения: Fri Jan 18 18:20:11 2013 Дата индексирования: Sun Feb 3 16:12:05 2013 Кодировка: Поисковые слова: http www.mccme.ru |
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: Fri Jan 18 15:20:10 2013.
NAME: AD2XY PURPOSE: Compute X and Y from native coordinates and a FITS astrometry structure EXPLANATION: If a WCS projection (Calabretta & Greisen 2002, A&A, 395, 1077) is present, then the procedure WCSXY2SPH is used to compute native coordinates. If distortion is present then this is corrected. In all cases, the inverse of the CD matrix is applied and offset from the reference pixel to obtain X and Y. AD2XY is generally meant to be used internal to other procedures. For interactive purposes, use ADXY. CALLING SEQUENCE: AD2XY, a ,d, astr, x, y INPUTS: A - R.A. or longitude in DEGREES, scalar or vector D - Dec. or longitude in DEGREES, scalar or vector ASTR - astrometry structure, output from EXTAST procedure containing: .CD - 2 x 2 array containing the astrometry parameters CD1_1 CD1_2 in DEGREES/PIXEL CD2_1 CD2_2 .CDELT - 2 element vector giving increment at reference point in DEGREES/PIXEL .CRPIX - 2 element vector giving X and Y coordinates of reference pixel (def = NAXIS/2) in FITS convention (first pixel is 1,1) .CRVAL - 2 element vector giving coordinates of the reference pixel in DEGREES .CTYPE - 2 element vector giving projection types .LONGPOLE - scalar longitude of north pole (default = 180) .PV2 - Vector of additional parameter (e.g. PV2_1, PV2_2) needed in some projections .DISTORT - Optional substructure specifying distortion parameters OUTPUTS: X - row position in pixels, scalar or vector Y - column position in pixels, scalar or vector X,Y will be in the standard IDL convention (first pixel is 0), and *not* the FITS convention (first pixel is 1) NOTES: AD2XY tests for presence of WCS coordinates by the presence of a dash in the 5th character position in the value of CTYPE (e.g 'DEC--SIN'). PROCEDURES USED: TAG_EXIST(), WCSSPH2XY REVISION HISTORY: Converted to IDL by B. Boothman, SASC Tech, 4/21/86 Use astrometry structure, W. Landsman Jan. 1994 Do computation correctly in degrees W. Landsman Dec. 1994 Only pass 2 CRVAL values to WCSSPH2XY W. Landsman June 1995 Don't subscript CTYPE W. Landsman August 1995 Understand reversed X,Y (X-Dec, Y-RA) axes, W. Landsman October 1998 Consistent conversion between CROTA and CD matrix W. Landsman October 2000 No special case for tangent projection W. Landsman June 2003 Work for non-WCS coordinate transformations W. Landsman Oct 2004 Use CRVAL reference point for non-WCS transformation W.L. March 2007 Use post V6.0 notation W.L. July 2009
(See astrolib/pro/ad2xy.pro)
NAME: ADSTRING PURPOSE: Return RA and Dec as character string(s) in sexagesimal format. EXPLANATION: RA and Dec may be entered as either a 2 element vector or as two separate vectors (or scalars). One can also specify the precision of the declination in digits after the decimal point. CALLING SEQUENCE result = ADSTRING( ra_dec, precision, /TRUNCATE ) or result = ADSTRING( ra,dec,[ precision, /TRUNCATE ] ) or result = ADSTRING( 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 or vector DEC - Declination in decimal degrees, numeric scalar or vector If only parameter is supplied then it must be either a scalar (which is converted to sexagesimal) or a two element [RA, Dec] vector. OPTIONAL INPUT: PRECISION - Integer scalar (0-4) giving the number of digits after the decimal of DEClination. The RA is automatically 1 digit more. This parameter may either be the third parameter after RA,DEC or the second parameter after [RA,DEC]. If only DEC is supplied then precision must be supplied as a keyword parameter. If no PRECISION parameter or keyword is passed, a precision of 1 for both RA and DEC is returned to maintain compatibility with past ADSTRING versions. Values of precision larger than 4 will be truncated to 4. If PRECISION is 3 or 4, then RA and Dec should be input as double precision. OPTIONAL INPUT KEYWORD: /TRUNCATE - if set, then the last displayed digit in the output is truncated in precision rather than rounded. This option is useful if ADSTRING() is used to form an official IAU name (see http://vizier.u-strasbg.fr/Dic/iau-spec.htx) with coordinate specification. The IAU name will typically be be created by applying STRCOMPRESS/REMOVE) after the ADSTRING() call, e.g. strcompress( adstring(ra,dec,0,/truncate), /remove) ;IAU format PRECISION = Alternate method of supplying the precision parameter, OUTPUT: RESULT - Character string(s) containing HR,MIN,SEC,DEC,MIN,SEC formatted as ( 2I3,F5.(p+1),2I3,F4.p ) where p is the PRECISION parameter. If only a single scalar is supplied it is converted to a sexagesimal 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 sexagesimal format (2) print,adstring(30.42,-1.23,1) ==> ' 02 01 40.80 -01 13 48.0' print,adstring(30.42,+0.23) ==> ' 02 01 40.8 +00 13 48.0' print,adstring(+0.23) ==> '+00 13 48.0' (3) The first two calls in (2) can be combined in a single call using vector input print,adstring([30.42,30.42],[-1.23,0.23], 1) PROCEDURES CALLED: 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] Major rewrite to allow vector inputs W. Landsman February 2000 Fix possible error in seconds display when Precision=0 P. Broos/W. Landsman April 2002 Added /TRUNCATE keyword, put leading zeros in seconds display P. Broos/W. Landsman September 2002 Fix declination zero values under vector processing W.Landsman Feb 2004 Fix possible problem in leading zero display W. Landsman June 2004 Assume since V5.4, omit fstring() call W. Landsman April 2006 Fix significant bug when round a declination with -199.99 W. L. Sep 2012
(See astrolib/pro/adstring.pro)
NAME: ADXY PURPOSE: Use a FITS header to convert astronomical to pixel coordinates EXPLANATION: Use an image header to compute X and Y positions, given the RA and Dec (or longitude, latitude) in decimal degrees. CALLING SEQUENCE: ADXY, HDR ;Prompt for Ra and DEC ADXY, hdr, a, d, x, y, [ /PRINT, ALT= ] INPUTS: HDR - FITS Image header containing astrometry parameters OPTIONAL INPUTS: A - Right ascension in decimal DEGREES, scalar or vector D - Declination in decimal DEGREES, scalar or vector If A and D are not supplied, user will be prompted to supply them in either decimal degrees or HR,MIN,SEC,DEG,MN,SC format. OPTIONAL OUTPUT: X - row position in pixels, same number of elements as A and D Y - column position in pixels X and Y will be in standard IDL convention (first pixel is 0) and not the FITS convention (first pixel is 1). As in FITS an integral value corresponds to the center of a pixel. OPTIONAL KEYWORD INPUT: /PRINT - If this keyword is set and non-zero, then results are displayed at the terminal. ALT - single character 'A' through 'Z' or ' ' specifying an alternate astrometry system present in the FITS header. The default is to use the primary astrometry or ALT = ' '. If /ALT is set, then this is equivalent to ALT = 'A'. See Section 3.3 of Greisen & Calabretta (2002, A&A, 395, 1061) for information about alternate astrometry keywords. OPERATIONAL NOTES: If less than 5 parameters are supplied, or if the /PRINT keyword is set, then the X and Y positions are displayed at the terminal. If the procedure is to be used repeatedly with the same header, then it would be faster to use AD2XY. PROCEDURES CALLED: AD2XY, ADSTRING(), EXTAST, GETOPT(), TEN() REVISION HISTORY: W. Landsman HSTX January, 1988 Use astrometry structure W. Landsman January, 1994 Changed default ADSTRING format W. Landsman September, 1995 Check if latitude/longitude reversed in CTYPE keyword W. L. Feb. 2004 Added ALT keyword W. Landsman September 2004 Work for non-spherical coordinate transformation W. Landsman May 2005 More informative error message if astrometry missing W.L. Feb 2008 Cosmetic updates W.L. July 2011
(See astrolib/pro/adxy.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 relation of Ciddor (1996). CALLING SEQUENCE: AIRTOVAC, WAVE_AIR, [ WAVE_VAC] INPUT/OUTPUT: WAVE_AIR - Wavelength in Angstroms, scalar or vector If this is the only parameter supplied, it will be updated on output to contain double precision vacuum wavelength(s). OPTIONAL OUTPUT: WAVE_VAC - Vacuum wavelength in Angstroms, same number of elements as WAVE_AIR, double precision EXAMPLE: If the air wavelength is W = 6056.125 (a Krypton line), then AIRTOVAC, W yields an vacuum wavelength of W = 6057.8019 METHOD: Formula from Ciddor 1996, Applied Optics 62, 958 NOTES: Take care within 1 A of 2000 A. Wavelengths below 2000 A *in air* are not altered. REVISION HISTORY Written W. Landsman November 1991 Use Ciddor (1996) formula for better accuracy in the infrared Added optional output vector, W Landsman Mar 2011 Iterate for better precision W.L./D. Schlegel Mar 2011
(See astrolib/pro/airtovac.pro)
NAME: AITOFF PURPOSE: Convert longitude, latitude to X,Y using an AITOFF projection. EXPLANATION: This procedure can be used to create an all-sky map in Galactic coordinates with an equal-area Aitoff projection. Output map coordinates are zero longitude centered. CALLING SEQUENCE: AITOFF, L, B, X, Y INPUTS: L - longitude - scalar or vector, in degrees B - latitude - same number of elements as L, in degrees OUTPUTS: X - X coordinate, same number of elements as L. X is normalized to be between -180 and 180 Y - Y coordinate, same number of elements as L. Y is normalized to be between -90 and 90. NOTES: See AIPS memo No. 46, page 4, for details of the algorithm. This version of AITOFF assumes the projection is centered at b=0 degrees. REVISION HISTORY: Written W.B. Landsman STX December 1989 Modified for Unix: J. Bloch LANL SST-9 5/16/91 1.1 Converted to IDL V5.0 W. Landsman September 1997
(See astrolib/pro/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, LABEL=, /NEW, CHARTHICK=, CHARSIZE=, FONT=, _EXTRA=] OPTIONAL INPUTS: DLONG = Optional input longitude line spacing in degrees. If left out, defaults to 30. DLAT = Optional input latitude line spacing in degrees. If left out, defaults to 30. OPTIONAL INPUT KEYWORDS: LABEL = Optional keyword specifying that the latitude and longitude lines on the prime meridian and the equator should be labeled in degrees. If LABELS is given a value of 2, i.e. LABELS=2, then the longitude labels will be in hours instead of degrees. CHARSIZE = If /LABEL is set, then CHARSIZE specifies the size of the label characters (passed to XYOUTS) CHARTHICK = If /LABEL is set, then CHARTHICK specifies the thickness of the label characters (passed to XYOUTS) FONT = scalar font graphics keyword (-1,0 or 1) for text /NEW = If this keyword is set, then AITOFF_GRID will create a new plot grid, rather than overlay an existing plot. Any valid keyword to OPLOT such as COLOR, LINESTYLE, THICK can be passed to AITOFF_GRID (though the _EXTRA facility) to to specify the color, style, or thickness of the grid lines. OUTPUTS: Draws grid lines on current graphics device. EXAMPLE: Create a labeled Aitoff grid of the Galaxy, and overlay stars at specified Galactic longitudes, glong and latitudes, glat IDL> aitoff_grid,/label,/new ;Create labeled grid IDL> aitoff, glong, glat, x,y ;Convert to X,Y coordinates IDL> plots,x,y,psym=2 ;Overlay "star" positions PROCEDURES USED: AITOFF NOTES: If labeling in hours (LABEL=2) then the longitude spacing should be a multiple of 15 degrees AUTHOR AND MODIFICATIONS: J. Bloch 1.2 6/2/91 Converted to IDL V5.0 W. Landsman September 1997 Create default plotting coords, if needed W. Landsman August 2000 Added _EXTRA, CHARTHICK, CHARSIZE keywords W. Landsman March 2001 Several tweaks, plot only hours not minutes W. Landsman January 2002 Allow FONT keyword to be passed to XYOUTS. T. Robishaw Apr. 2006
(See astrolib/pro/aitoff_grid.pro)
NAME: ALTAZ2HADEC PURPOSE: Convert Horizon (Alt-Az) coordinates to Hour Angle and Declination. EXPLANATION:: Can deal with the NCP singularity. Intended mainly to be used by program hor2eq.pro CALLING SEQUENCE: ALTAZ2HADEC, alt, az, lat, ha, dec INPUTS alt - the local apparent altitude, in DEGREES, scalar or vector az - the local apparent azimuth, in DEGREES, scalar or vector, measured EAST of NORTH!!! If you have measured azimuth west-of-south (like the book MEEUS does), convert it to east of north via: az = (az + 180) mod 360 lat - the local geodetic latitude, in DEGREES, scalar or vector. OUTPUTS ha - the local apparent hour angle, in DEGREES. The hour angle is the time that right ascension of 0 hours crosses the local meridian. It is unambiguously defined. dec - the local apparent declination, in DEGREES. EXAMPLE: Arcturus is observed at an apparent altitude of 59d,05m,10s and an azimuth (measured east of north) of 133d,18m,29s while at the latitude of +43.07833 degrees. What are the local hour angle and declination of this object? IDL> altaz2hadec, ten(59,05,10), ten(133,18,29), 43.07833, ha, dec ===> Hour angle ha = 336.683 degrees Declination, dec = 19.1824 degrees The widely available XEPHEM code gets: Hour Angle = 336.683 Declination = 19.1824 REVISION HISTORY: Written Chris O'Dell Univ. of Wisconsin-Madison May 2002
(See astrolib/pro/altaz2hadec.pro)
NAME: AL_LEGEND PURPOSE: Create an annotation legend for a plot. EXPLANATION: This procedure was originally named LEGEND, but a distinct LEGEND() function was introduced into IDL V8.0. Therefore, the original LEGEND procedure in the Astronomy Library is renamed to AL_LEGEND. This procedure makes a legend for a plot. The legend can contain a mixture of symbols, linestyles, Hershey characters (vectorfont), and filled polygons (usersym). A test procedure, al_legendtest.pro, shows legend's capabilities. Placement of the legend is controlled with keywords like /right, /top, and /center or by using a position keyword for exact placement (position=[x,y]) or via mouse (/position). CALLING SEQUENCE: AL_LEGEND [,items][,keyword options] EXAMPLES: The call: al_legend,['Plus sign','Asterisk','Period'],psym=[1,2,3] produces: ----------------- | | | + Plus sign | | * Asterisk | | . Period | | | ----------------- Each symbol is drawn with a cgPlots command, so they look OK. Other examples are given in optional output keywords. lines = indgen(6) ; for line styles items = 'linestyle '+strtrim(lines,2) ; annotations al_legend,items,linestyle=lines ; vertical legend---upper left items = ['Plus sign','Asterisk','Period'] sym = [1,2,3] al_legend,items,psym=sym ; ditto except using symbols al_legend,items,psym=sym,/horizontal ; horizontal format al_legend,items,psym=sym,box=0 ; sans border al_legend,items,psym=sym,delimiter='=' ; embed '=' betw psym & text al_legend,items,psym=sym,margin=2 ; 2-character margin al_legend,items,psym=sym,position=[x,y] ; upper left in data coords al_legend,items,psym=sym,pos=[x,y],/norm ; upper left in normal coords al_legend,items,psym=sym,pos=[x,y],/device ; upper left in device coords al_legend,items,psym=sym,/position ; interactive position al_legend,items,psym=sym,/right ; at upper right al_legend,items,psym=sym,/bottom ; at lower left al_legenditems,psym=sym,/center ; approximately near center al_legend,items,psym=sym,number=2 ; plot two symbols, not one Plot 3 filled colored squares al_legend,items,/fill,psym=[8,8,8],colors=['red','green','blue'] Another example of the use of AL_LEGEND can be found at http://www.idlcoyote.com/cg_tips/al_legend.php INPUTS: items = text for the items in the legend, a string array. For example, items = ['diamond','asterisk','square']. You can omit items if you don't want any text labels. OPTIONAL INPUT KEYWORDS: linestyle = array of linestyle numbers If linestyle[i] < 0, then omit ith symbol or line to allow a multi-line entry. If linestyle = -99 then text will be left-justified. psym = array of plot symbol numbers or names. If psym[i] is negative, then a line connects pts for ith item. If psym[i] = 8, then the procedure USERSYM is called with vertices defined in the keyword usersym. If psym[i] = 88, then use the previously defined user symbol. If 11 <= psym[i] <= 46 then David Fanning's function CGSYMCAT() will be used for additional symbols. Note that PSYM=10 (histogram plot mode) is not allowed since it cannot be used with the cgPlots command. vectorfont = vector-drawn characters for the sym/line column, e.g., ['!9B!3','!9C!3','!9D!3'] produces an open square, a checkmark, and a partial derivative, which might have accompanying items ['BOX','CHECK','PARTIAL DERIVATIVE']. There is no check that !p.font is set properly, e.g., -1 for X and 0 for PostScript. This can produce an error, e.g., use !20 with PostScript and !p.font=0, but allows use of Hershey *AND* PostScript fonts together. N. B.: Choose any of linestyle, psym, and/or vectorfont. If none is present, only the text is output. If more than one is present, all need the same number of elements, and normal plot behaviour occurs. By default, if psym is positive, you get one point so there is no connecting line. If vectorfont[i] = '', then cgPlots is called to make a symbol or a line, but if vectorfont[i] is a non-null string, then cgText is called. /help = flag to print header /horizontal = flag to make the legend horizontal /vertical = flag to make the legend vertical (D=vertical) background_color - color name or number to fill the legend box. Automatically sets /clear. (D = -1) box = flag to include/omit box around the legend (D=include) outline_color = color of box outline (D = !P.color) bthick = thickness of the legend box (D = !P.thick) charsize = just like !p.charsize for plot labels charthick = just like !p.charthick for plot labels clear = flag to clear the box area before drawing the legend colors = array of colors names or numbers for plot symbols/lines See cgCOLOR for list of color names. Default is 'Opposite' If you are using index colors (0-255), then supply color as a byte, integer or string, but not as a long, which will be interpreted as a decomposed color. See http://www.idlcoyote.com/cg_tips/legcolor.php delimiter = embedded character(s) between symbol and text (D=none) font = scalar font graphics keyword (-1,0 or 1) for text linsize = Scale factor for line length (0-1), default = 1 Set to 0 to give a dot, 0.5 give half default line length margin = margin around text measured in characters and lines number = number of plot symbols to plot or length of line (D=1) spacing = line spacing (D=bit more than character height) position = data coordinates of the /top (D) /left (D) of the legend pspacing = psym spacing (D=3 characters) (when number of symbols is greater than 1) textcolors = array of color names or numbers for text. See cgCOLOR for a list of color names. Default is 'Opposite' of background thick = array of line thickness numbers (D = !P.thick), if used, then linestyle must also be specified normal = use normal coordinates for position, not data device = use device coordinates for position, not data /window - if set then send legend to a resizeable graphics window usersym = 2-D array of vertices, cf. usersym in IDL manual. (/USERSYM =square, default is to use existing USERSYM definition) /fill = flag to fill the usersym /left_legend = flag to place legend snug against left side of plot window (D) /right_legend = flag to place legend snug against right side of plot window. If /right,pos=[x,y], then x is position of RHS and text runs right-to-left. /top_legend = flag to place legend snug against top of plot window (D) /bottom = flag to place legend snug against bottom of plot window /top,pos=[x,y] and /bottom,pos=[x,y] produce same positions. If LINESTYLE, PSYM, VECTORFONT, SYMSIZE, THICK, COLORS, or TEXTCOLORS are supplied as scalars, then the scalar value is set for every line or symbol in the legend. Outputs: legend to current plot device OPTIONAL OUTPUT KEYWORDS: corners = 4-element array, like !p.position, of the normalized coords for the box (even if box=0): [llx,lly,urx,ury]. Useful for multi-column or multi-line legends, for example, to make a 2-column legend, you might do the following: c1_items = ['diamond','asterisk','square'] c1_psym = [4,2,6] c2_items = ['solid','dashed','dotted'] c2_line = [0,2,1] al_legend,c1_items,psym=c1_psym,corners=c1,box=0 al_legend,c2_items,line=c2_line,corners=c2,box=0,pos=[c1[2],c1[3]] c = [c1[0]c2[2],c1[3]>c2[3]] cgplots,[c[0],c[0],c[2],c[2],c[0]],[c[1],c[3],c[3],c[1],c[1]],/norm Useful also to place the legend. Here's an automatic way to place the legend in the lower right corner. The difficulty is that the legend's width is unknown until it is plotted. In this example, the legend is plotted twice: the first time in the upper left, the second time in the lower right. al_legend,['1','22','333','4444'],linestyle=indgen(4),corners=corners ; BOGUS LEGEND---FIRST TIME TO REPORT CORNERS xydims = [corners[2]-corners[0],corners[3]-corners[1]] ; SAVE WIDTH AND HEIGHT chdim=[!d.x_ch_size/float(!d.x_size),!d.y_ch_size/float(!d.y_size)] ; DIMENSIONS OF ONE CHARACTER IN NORMALIZED COORDS pos = [!x.window[1]-chdim[0]-xydims[0] $ ,!y.window[0]+chdim[1]+xydims[1]] ; CALCULATE POSITION FOR LOWER RIGHT cgplot,findgen(10) ; SIMPLE PLOT; YOU DO WHATEVER YOU WANT HERE. al_legend,['1','22','333','4444'],linestyle=indgen(4),pos=pos ; REDO THE LEGEND IN LOWER RIGHT CORNER You can modify the pos calculation to place the legend where you want. For example to place it in the upper right: pos = [!x.window[1]-chdim[0]-xydims[0],!y.window[1]-xydims[1]] Common blocks: none Procedure: If keyword help is set, call doc_library to print header. See notes in the code. Much of the code deals with placement of the legend. The main problem with placement is not being able to sense the length of a string before it is output. Some crude approximations are used for centering. Restrictions: Here are some things that aren't implemented. - An orientation keyword would allow lines at angles in the legend. - An array of usersyms would be nice---simple change. - An order option to interchange symbols and text might be nice. - Somebody might like double boxes, e.g., with box = 2. - Another feature might be a continuous bar with ticks and text. - There are no guards to avoid writing outside the plot area. - There is no provision for multi-line text, e.g., '1st line!c2nd line' Sensing !c would be easy, but !c isn't implemented for PostScript. A better way might be to simply output the 2nd line as another item but without any accompanying symbol or linestyle. A flag to omit the symbol and linestyle is linestyle[i] = -1. - There is no ability to make a title line containing any of titles for the legend, for the symbols, or for the text. Side Effects: Modification history: write, 24-25 Aug 92, F K Knight (knight@ll.mit.edu) allow omission of items or omission of both psym and linestyle, add corners keyword to facilitate multi-column legends, improve place- ment of symbols and text, add guards for unequal size, 26 Aug 92, FKK add linestyle(i)=-1 to suppress a single symbol/line, 27 Aug 92, FKK add keyword vectorfont to allow characters in the sym/line column, 28 Aug 92, FKK add /top, /bottom, /left, /right keywords for automatic placement at the four corners of the plot window. The /right keyword forces right-to-left printing of menu. 18 Jun 93, FKK change default position to data coords and add normal, data, and device keywords, 17 Jan 94, FKK add /center keyword for positioning, but it is not precise because text string lengths cannot be known in advance, 17 Jan 94, FKK add interactive positioning with /position keyword, 17 Jan 94, FKK allow a legend with just text, no plotting symbols. This helps in simply describing a plot or writing assumptions done, 4 Feb 94, FKK added thick, symsize, and clear keyword Feb 96, W. Landsman HSTX David Seed, HR Wallingford, d.seed@hrwallingford.co.uk allow scalar specification of keywords, Mar 96, W. Landsman HSTX added charthick keyword, June 96, W. Landsman HSTX Made keyword names left,right,top,bottom,center longer, Aug 16, 2000, Kim Tolbert Added ability to have regular text lines in addition to plot legend lines in legend. If linestyle is -99 that item is left-justified. Previously, only option for no sym/line was linestyle=-1, but then text was lined up after sym/line column. 10 Oct 2000, Kim Tolbert Make default value of thick = !P.thick W. Landsman Jan. 2001 Don't overwrite existing USERSYM definition W. Landsman Mar. 2002 Added outline_color BT 24 MAY 2004 Pass font keyword to cgText commands. M. Fitzgerald, Sep. 2005 Default spacing, pspacing should be relative to charsize. M. Perrin, July 2007 Don't modify position keyword A. Kimball/ W. Landsman Jul 2007 Small update to Jul 2007 for /NORMAL coords. W. Landsman Aug 2007 Use SYMCAT() plotting symbols for 11<=PSYM<=46 W. Landsman Nov 2009 Make a sharper box edge T. Robishaw/W.Landsman July 2010 Added BTHICK keyword W. Landsman October 2010 Added BACKGROUND_COLOR keyword W. Landsman February 2011 Incorporate Coyote graphics W. Landsman February 2011 Added LINSIZE keyword W.L./V.Gonzalez May 2011 Fixed a small problem with Convert_Coord when the Window keyword is set. David Fanning, May 2011. Fixed problem when /clear and /Window are set J. Bailin/WL May 2011 CGQUERY was called instead of CGCONTROL W.L. June 2011 Fixed typo preventing BTHICK keyword from working W.L. Dec 2011 Remove call to SYMCAT() W.L. Dec 2011 Changed the way the WINDOW keyword adds commands to cgWindow, and now default to BACKGROUND for background color. 1 Feb 2012 David Fanning Allow 1 element SYMSIZE for vector input, WL Apr 2012. Allow to specify symbols by cgSYMCAT() name WL Aug 2012 Fixed bug when linsize, /right called simultaneously, Dec 2012, K.Stewart
(See astrolib/pro/al_legend.pro)
NAME: AL_LEGENDTEST PURPOSE: Demo program to show capabilities of the al_legend procedure. CALLING SEQUENCE: al_legendtest INPUTS: none OPTIONAL INPUTS: none KEYWORDS: none OUTPUTS: legends of note COMMON BLOCKS: none SIDE EFFECTS: Sets !20 font to symbol if PostScript and !p.font=0. RESTRICTIONS: With the vectorfont test, you'll get different results for PostScript depending on the value of !p.font. MODIFICATION HISTORY: write, 27 Aug 92, F.K.Knight (knight@ll.mit.edu) add test of /left,/right,/top,/bottom keywords, 21 June 93, FKK update based on recent changes to legend, 7 Feb 94, FKK Fix ambiguous CHAR keyword W. Landsman Sep 2007 Use Coyote graphics routines W. Landsman Jan 2011
(See astrolib/pro/al_legendtest.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, /NAN, /EXACT, /FLUX, PRINT = , /SILENT, /MEANBACK, MINSKY=, SETSKYVAL = ] INPUTS: IMAGE - input image array XC - vector of x coordinates. YC - vector of y coordinates OPTIONAL INPUTS: PHPADU - Photons per Analog Digital Units, numeric scalar. Converts the data numbers in IMAGE to photon units. (APER assumes Poisson statistics.) APR - Vector of up to 12 REAL photometry aperture radii. SKYRAD - Two element vector giving the inner and outer radii to be used for the sky annulus. Ignored if the SETSKYVAL keyword is set. BADPIX - Two element vector giving the minimum and maximum value of a good pixel. If badpix is not supplied or if BADPIX[0] is equal to BADPIX[1] then it is assumed that there are no bad pixels. Note that fluxes will not be computed for any star with a bad pixel within the aperture area, but that bad pixels will be simply ignored for the sky computation. The BADPIX parameter is ignored if the /NAN keyword is set. OPTIONAL KEYWORD INPUTS: CLIPSIG - if /MEANBACK is set, then this is the number of sigma at which to clip the background. Default=3 CONVERGE_NUM: if /MEANBACK is set then if the proportion of rejected pixels is less than this fraction, the iterations stop. Default=0.02, i.e., iteration stops if fewer than 2% of pixels excluded. /EXACT - By default, APER counts subpixels, but uses a polygon approximation for the intersection of a circular aperture with a square pixel (and normalizes the total area of the sum of the pixels to exactly match the circular area). If the /EXACT keyword, then the intersection of the circular aperture with a square pixel is computed exactly. The /EXACT keyword is much slower and is only needed when small (~2 pixels) apertures are used with very undersampled data. /FLUX - By default, APER uses a magnitude system where a magnitude of 25 corresponds to 1 flux unit. If set, then APER will keep results in flux units instead of magnitudes. MAXITER if /MEANBACK is set then this is the ceiling on number of clipping iterations of the background. Default=5 /MEANBACK - if set, then the background is computed using the 3 sigma clipped mean (using meanclip.pro) rather than using the mode computed with mmm.pro. This keyword is useful for the Poisson count regime or where contamination is known to be minimal. MINSKY - Integer giving mininum number of sky values to be used with MMM APER will not compute a flux if fewer valid sky elements are within the sky annulus. Default = 20. /NAN - If set then APER will check for NAN values in the image. /NAN takes precedence over the BADPIX parameter. Note that fluxes will not be computed for any star with a NAN pixel within the aperture area, but that NAN pixels will be simply ignored for the sky computation. PRINT - if set and non-zero then APER will also write its results to a file aper.prt. One can specify the output file name by setting PRINT = 'filename'. READNOISE - Scalar giving the read noise (or minimum noise for any pixel. This value is passed to the procedure mmm.pro when computing the sky, and is only need for images where the noise is low, and pixel values are quantized. /SILENT - If supplied and non-zero then no output is displayed to the terminal. SETSKYVAL - Use this keyword to force the sky to a specified value rather than have APER compute a sky value. SETSKYVAL can either be a scalar specifying the sky value to use for all sources, or a 3 element vector specifying the sky value, the sigma of the sky value, and the number of elements used to compute a sky value. The 3 element form of SETSKYVAL is needed for accurate error budgeting. OUTPUTS: MAGS - NAPER by NSTAR array giving the magnitude for each star in each aperture. (NAPER is the number of apertures, and NSTAR is the number of stars). If the /FLUX keyword is not set, then a flux of 1 digital unit is assigned a zero point magnitude of 25. ERRAP - NAPER by NSTAR array giving error for each star. If a magnitude could not be determined then ERRAP = 9.99 (if in magnitudes) or ERRAP = !VALUES.F_NAN (if /FLUX is set). SKY - NSTAR element vector giving sky value for each star in flux units SKYERR - NSTAR element vector giving error in sky values EXAMPLE: Determine the flux and error for photometry radii of 3 and 5 pixels surrounding the position 234.2,344.3 on an image array, im. Compute the partial pixel area exactly. Assume that the flux units are in Poisson counts, so that PHPADU = 1, and the sky value is already known to be 1.3, and that the range [-32767,80000] for bad low and bad high pixels IDL> aper, im, 234.2, 344.3, flux, eflux, sky,skyerr, 1, [3,5], -1, $ [-32767,80000],/exact, /flux, setsky = 1.3 PROCEDURES USED: GETOPT, MMM, PIXWT(), STRN(), STRNUMBER() NOTES: Reasons that a valid magnitude cannot be computed include the following: (1) Star position is too close (within 0.5 pixels) to edge of the frame (2) Less than 20 valid pixels available for computing sky (3) Modal value of sky could not be computed by the procedure MMM (4) *Any* pixel within the aperture radius is a "bad" pixel (5) The total computed flux is negative. In this case the negative flux and error are returned. For the case where the source is fainter than the background, APER will return negative fluxes if /FLUX is set, but will otherwise give invalid data (since negative fluxes can't be converted to magnitudes) APER was modified in June 2000 in two ways: (1) the /EXACT keyword was added (2) the approximation of the intersection of a circular aperture with square pixels was improved (i.e. when /EXACT is not used) REVISON HISTORY: Adapted to IDL from DAOPHOT June, 1989 B. Pfarr, STX FLUX keyword added J. E. Hollis, February, 1996 SETSKYVAL keyword, increase maxsky W. Landsman, May 1997 Work for more than 32767 stars W. Landsman, August 1997 Don't abort for insufficient sky pixels W. Landsman May 2000 Added /EXACT keyword W. Landsman June 2000 Allow SETSKYVAL = 0 W. Landsman December 2000 Set BADPIX[0] = BADPIX[1] to ignore bad pixels W. L. January 2001 Fix chk_badpixel problem introduced Jan 01 C. Ishida/W.L. February 2001 Set bad fluxes and error to NAN if /FLUX is set W. Landsman Oct. 2001 Remove restrictions on maximum sky radius W. Landsman July 2003 Added /NAN keyword W. Landsman November 2004 Set badflux=0 if neither /NAN nor badpix is set M. Perrin December 2004 Added READNOISE keyword W. Landsman January 2005 Added MEANBACK keyword W. Landsman October 2005 Correct typo when /EXACT and multiple apertures used. W.L. Dec 2005 Remove VMS-specific code W.L. Sep 2006 Add additional keywords if /MEANBACK is set W.L Nov 2006 Allow negative fluxes if /FLUX is set W.L. Mar 2008 Previous update would crash if first star was out of range W.L. Mar 2008 Fix floating equality test for bad magnitudes W.L./J.van Eyken Jul 2009 Added MINSKY keyword W.L. Dec 2011
(See astrolib/pro/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=, FONT= ] 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 - name or integer scalar specifying the color to draw the arcbar See cgColor for a list of available color names /DATA - if set and non-zero, then the POSITION keyword is given in data units LABEL - string giving user defined label for bar. Default label is size of bar in arcminutes /NORMAL - if this keyword is set and non-zero, then POSITION is given in normalized units POSITION - 2 element vector giving the (X,Y) position in device units (or normalized units if /NORMAL is set, or data units if /DATA is set) at which to place the scale bar. If not supplied, then the user will be prompted to place the cursor at the desired position /SECONDS - if set, then arlen is specified in arcseconds rather than arcminutes SIZE - scalar specifying character size of label, default = 1.0 THICK - Character thickness of the label, default = !P.THICK FONT - scalar font graphics keyword (-1,0 or 1) for text EXAMPLE: Place a 3' arc minute scale bar, at position 300,200 of the current image window, (which is associated with a FITS header, HDR) IDL> arcbar, HDR, 3, pos = [300,200] RESTRICTIONS: When using using a device with scalable pixels (e.g. postscript) the data coordinate system must be established before calling ARCBAR. If data coordinates are not set, then ARCBAR assumes that the displayed image size is given by the NAXIS1 keyword in the FITS header. PROCEDURE CALLS: AD2XY, EXTAST, GSSSADXY, SXPAR(), cgPlot, cgText 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 Added /DATA, /SECONDS keywords W. Landsman July 1998 Use device-independent label offset W. Landsman August 2001 Allow font keyword to be passed. T. Robishaw Apr. 2006 Remove obsolete TVCURSOR command W. Landsman Jul 2007 Use Coyote Graphics W. Landsman February 2011
(See astrolib/pro/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 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 name or number for the arrows and NE letters. See cgCOLOR() for a list of color names. Data - if this keyword is set and nonzero, the input center (xcen, ycen) is understood to be in data coordinates font - IDL vector font number (1-20) to use to display NE letters. For example, set font=13 to use complex italic font. NotVertex - Normally (historically) the specified xcen,ycen indicated the position of the vertex of the figure. If this keyword is set, the xcen,ycen coordinates refer to a sort of 'center of mass' of the figure. This allows the figure to always appear with the area irregardless of the rotation angle. Normal - if this keyword is set and nonzero, the input center (xcen,ycen) is taken to be in normalized coordinates. The default is device coordinates. thick - line thickness, default = 2.0, floating point scalar OUTPUTS: none EXAMPLE: Draw a weathervane at (400,100) on the currently active window, showing the orientation of the image associated with a FITS header, hdr IDL> arrows, hdr, 400, 100 METHOD: Uses EXTAST to EXTract ASTrometry from the FITS header. The directions of North and East are computed and the procedure ONE_ARROW called to create the "weathervane". PROCEDURES USED: GETROT - Computes rotation from the FITS header ONE_ARROW - Draw a labeled arrow ZPARCHECK REVISON HISTORY: written by B. Boothman 2/5/86 Recoded with new procedures ONE_ARROW, ONE_RAY. R.S.Hill,HSTX,5/20/92 Added separate determination for N and E arrow to properly display arrows irregardless of handedness or other peculiarities and added /NotVertex keyword to improve positioning of figure. E.Deutsch 1/10/93 Added /DATA and /NORMAL keywords W. Landsman July 1993 Recognize GSSS header W. Landsman June 1993 Added /FONT keyword W. Landsman April 1995 Modified to work correctly for COLOR=0 J.Wm.Parker, HITC 1995 May 25 Work correctly for negative CDELT values W. Landsman Feb. 1996 Use GETROT to compute rotation W. Landsman June 2003 Restored /NotVertex keyword which was not working after June 2003 change W. Landsman January 2004
(See astrolib/pro/arrows.pro)
NAME: ASINH PURPOSE: Return the inverse hyperbolic sine of the argument EXPLANATION: The inverse hyperbolic sine is used for the calculation of asinh magnitudes, see Lupton et al. (1999, AJ, 118, 1406) CALLING SEQUENCE result = asinh( x) INPUTS: X - hyperbolic sine, numeric scalar or vector or multidimensional array (not complex) OUTPUT: result - inverse hyperbolic sine, same number of elements as X double precision if X is double, otherwise floating pt. METHOD: Expression given in Numerical Recipes, Press et al. (1992), eq. 5.6.7 Note that asinh(-x) = -asinh(x) and that asinh(0) = 0. and that if y = asinh(x) then x = sinh(y). REVISION HISTORY: Written W. Landsman February, 2001 Work for multi-dimensional arrays W. Landsman August 2002 Simplify coding, and work for scalars again W. Landsman October 2003
(See astrolib/pro/asinh.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 Ascension 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 sexagesimal 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 astrolib/pro/astdisp.pro)
NAME: ASTRO PURPOSE: Interactive utility for precession and coordinate conversion. CALLING SEQUENCE: ASTRO, [ selection, EQUINOX =, /FK4] OPTIONAL INPUT: SELECTION - Scalar Integer (0-6) giving the the particular astronomical utility to be used. (0) Precession, (1) RA, Dec (2000) to Galactic coordinates, (2) Galactic to RA,Dec (2000) (3) RA,Dec (2000) to Ecliptic, (4) Ecliptic to RA, Dec, (5) Ecliptic to Galactic, (6) Galactic to Ecliptic. Program will prompt for SELECTION if this parameter is omitted. OPTIONAL KEYWORD INPUT: EQUINOX - numeric scalar specifying the equinox to use when converting between celestial and other coordinates. If not supplied, then the RA and Dec will be assumed to be in EQUINOX J2000. This keyword is ignored by the precession utility. For example, to convert from RA and DEC (J1975) to Galactic coordinates: IDL> astro, 1, E=1975 /FK4 - If this keyword is set and nonzero, then calculations are done in the FK4 system. For example, to convert from RA and Dec (B1975) to Galactic coordinates IDL> astro,1, E=1975,/FK4 METHOD: ASTRO uses PRECESS to compute precession, and EULER to compute coordinate conversions. The procedure GET_COORDS is used to read the coordinates, and ADSTRING to format the RA,Dec output. NOTES: (1) ASTRO temporarily sets !QUIET to suppress compilation messages and keep a pretty screen display. (2) ASTRO was changed in December 1998 to use J2000 as the default equinox, **and may be incompatible with earlier calls.*** (3) A nice online page for coordinate conversions is available at http://heasarc.gsfc.nasa.gov/cgi-bin/Tools/convcoord/convcoord.pl PROCEDURES USED: Procedures: GET_COORDS, EULER Function: ADSTRING REVISION HISTORY Written, W. Landsman November 1987 Code cleaned up W. Landsman October 1991 Added Equinox keyword, call to GET_COORDS, W. Landsman April, 1992 Allow floating point equinox input J. Parker/W. Landsman July 1996 Make FK5 the default, add FK4 keyword
(See astrolib/pro/astro.pro)
NAME: ASTROLIB PURPOSE: Add the non-standard system variables used by the IDL Astronomy Library EXPLANATION: Also defines the environment variable ASTRO_DATA pointing to the directory containing data files associated with the IDL Astronomy library (system dependent -- user must edit the third line in the program below). CALLING SEQUENCE: ASTROLIB INPUTS: None. OUTPUTS: None. METHOD: The non-standard system variables !PRIV, !TEXTUNIT, and !TEXTOUT are added using DEFSYSV. REVISION HISTORY: Written, Wayne Landsman, July 1986. Use DEFSYSV instead of ADDSYSVAR December 1990 Test for system variable existence before definition July 2001 Assume since V55, remove VMS support W. Landsman Sep 2006 Remove !Debug, comment out ASTRO_DATA definition WL Jan 2009
(See astrolib/pro/astrolib.pro)
NAME: AUTOHIST PURPOSE: Draw a histogram using automatic bin-sizing. EXPLANATION AUTOHIST chooses a number of bins (initially, SQRT(2*N). If this leads to a histogram in which > 1/5 of the central 50% of the bins are empty, it decreases the number of bins and tries again. The minimum # bins is 5. The max=199. Called by HISTOGAUSS and HALFAGAUSS. CALLING SEQUENCE: AUTOHIST, Sample, XLines, Ylines, XCenters, YCenters, [/NOPLOT, ] ...Plotting Keywords INPUT: Sample = the vector to be histogrammed OUTPUT: XLINES = vector of x coordinates of the points that trace the rectangular histogram bins YLINES = vector of y coordinates. To draw the histogram plot YLINES vs XLINES XCENTERS = the x values of the bin centers YCENTERS = the corresponding y values OPTIONAL INPUT KEYWORDS: /NOPLOT If set, nothing is drawn Any plotting keywords (e.g. XTITLE) may be supplied to AUTOHIST through the _EXTRA facility. REVISION HISTORY: Written, H. Freudenreich, STX, 1/91 1998 March 17 - Changed shading of histogram. RSH, RSTX V5.0 update, _EXTRA keywords W. Landsman April 2002 Added NOCLIP keyword for POLYFILL call C. Paxson/W. Landsman July 2003 Use Coyote graphics W. Landsman Feb 2011
(See astrolib/pro/autohist.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. In 2009, a DIMENSION keyword was added to the IDL MEAN() function, giving it the same capability as AVG(). Thus, the use of AVG() is now **deprecated** in favor of the MEAN() function. CALLING SEQUENCE: RESULT = AVG( ARRAY, [ DIMENSION, /NAN, /DOUBLE ] ) INPUTS: ARRAY = Input array. May be any type except string. OPTIONAL INPUT PARAMETERS: DIMENSION = Optional dimension to do average over, integer scalar OPTIONAL KEYWORD INPUT: /NAN - Set this keyword to cause the routine to check for occurrences of the IEEE floating-point value NaN in the input data. Elements with the value NaN are treated as missing data. /DOUBLE - By default, if the input Array is double-precision, complex, or double complex, the result is of the same type; 64 bit integers are also returned as double. Otherwise the result the result is floating-point. Use of the /DOUBLE keyword forces a double precision output. Note that internal computations are always done in double precision. OUTPUTS: The average value of the array when called with one parameter. If DIMENSION is passed, then the result is an array with all the dimensions of the input array except for the dimension specified, each element of which is the average of the corresponding vector in the input array. For example, if A is an array with dimensions of (3,4,5), then the command B = AVG(A,1) is equivalent to B = FLTARR(3,5) FOR J = 0,4 DO BEGIN FOR I = 0,2 DO BEGIN B[I,J] = TOTAL( A[I,*,J] ) / 4. ENDFOR ENDFOR RESTRICTIONS: Dimension specified must be valid for the array passed; otherwise the input array is returned as the output array. PROCEDURE: AVG(ARRAY) = TOTAL(ARRAY, /DOUBLE)/N_ELEMENTS(ARRAY) when called with one parameter. MODIFICATION HISTORY: William Thompson Applied Research Corporation July, 1986 8201 Corporate Drive Landover, MD 20785 Converted to Version 2 July, 1990 Replace SUM call with TOTAL W. Landsman May, 1992 Converted to IDL V5.0 W. Landsman September 1997 Added /NAN keyword W. Landsman July 2000 Accept a scalar input value W. Landsman/jimm@berkeley November 2000 Internal calculations always in double precision W. Landsman March 2002 Return NAN if all values in array are NAN W. Landsman April 2002 Fixed coding bug if all values in array are NAN W. Landsman Jan 2004
(See astrolib/pro/avg.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, [ JPL = ] INPUTS: DJE - (scalar) Julian ephemeris date. DEQ - (scalar) epoch of mean equinox of dvelh and dvelb. If deq=0 then deq is assumed to be equal to dje. OUTPUTS: DVELH: (vector(3)) heliocentric velocity component. in km/s DVELB: (vector(3)) barycentric velocity component. in km/s The 3-vectors DVELH and DVELB are given in a right-handed coordinate system with the +X axis toward the Vernal Equinox, and +Z axis toward the celestial pole. OPTIONAL KEYWORD SET: JPL - if /JPL set, then BARYVEL will call the procedure JPLEPHINTERP to compute the Earth velocity using the full JPL ephemeris. The JPL ephemeris FITS file JPLEPH.405 must exist in either the current directory, or in the directory specified by the environment variable ASTRO_DATA. Alternatively, the JPL keyword can be set to the full path and name of the ephemeris file. A copy of the JPL ephemeris FITS file is available in http://idlastro.gsfc.nasa.gov/ftp/data/ PROCEDURES CALLED: Function PREMAT() -- computes precession matrix JPLEPHREAD, JPLEPHINTERP, TDB2TDT - if /JPL keyword is set NOTES: Algorithm taken from FORTRAN program of Stumpff (1980, A&A Suppl, 41,1) Stumpf claimed an accuracy of 42 cm/s for the velocity. A comparison with the JPL FORTRAN planetary ephemeris program PLEPH found agreement to within about 65 cm/s between 1986 and 1994 If /JPL is set (using JPLEPH.405 ephemeris file) then velocities are given in the ICRS system; otherwise in the FK4 system. EXAMPLE: Compute the radial velocity of the Earth toward Altair on 15-Feb-1994 using both the original Stumpf algorithm and the JPL ephemeris IDL> jdcnv, 1994, 2, 15, 0, jd ;==> JD = 2449398.5 IDL> baryvel, jd, 2000, vh, vb ;Original algorithm ==> vh = [-17.07243, -22.81121, -9.889315] ;Heliocentric km/s ==> vb = [-17.08083, -22.80471, -9.886582] ;Barycentric km/s IDL> baryvel, jd, 2000, vh, vb, /jpl ;JPL ephemeris ==> vh = [-17.07236, -22.81126, -9.889419] ;Heliocentric km/s ==> vb = [-17.08083, -22.80484, -9.886409] ;Barycentric km/s IDL> ra = ten(19,50,46.77)*15/!RADEG ;RA in radians IDL> dec = ten(08,52,3.5)/!RADEG ;Dec in radians IDL> v = vb[0]*cos(dec)*cos(ra) + $ ;Project velocity toward star vb[1]*cos(dec)*sin(ra) + vb[2]*sin(dec) REVISION HISTORY: Jeff Valenti, U.C. Berkeley Translated BARVEL.FOR to IDL. W. Landsman, Cleaned up program sent by Chris McCarthy (SfSU) June 1994 Converted to IDL V5.0 W. Landsman September 1997 Added /JPL keyword W. Landsman July 2001 Documentation update W. Landsman Dec 2005
(See astrolib/pro/baryvel.pro)
NAME: BIWEIGHT_MEAN PURPOSE: Calculate the center and dispersion (like mean and sigma) of a distribution using bisquare weighting. CALLING SEQUENCE: Mean = BIWEIGHT_MEAN( Vector, [ Sigma, Weights ] ) INPUTS: Vector = Distribution in vector form OUTPUT: Mean - The location of the center. OPTIONAL OUTPUT ARGUMENTS: Sigma = An outlier-resistant measure of the dispersion about the center, analogous to the standard deviation. Weights = The weights applied to the data in the last iteration, floating point vector NOTES: Since a sample mean scaled by sigma/sqrt(N), has a Student's T distribution, the half-width of the 95% confidence interval for the sample mean can be determined as follows: ABS( T_CVF( .975, .7*(N-1) )*SIGMA/SQRT(N) ) where N = number of points, and 0.975 = 1 - (1 - 0.95)/2. PROCEDURES USED: ROBUST_SIGMA() REVISION HISTORY Written, H. Freudenreich, STX, 12/89 Modified 2/94, H.T.F.: use a biweighted standard deviation rather than median absolute deviation. Modified 2/94, H.T.F.: use the fractional change in SIGMA as the convergence criterion rather than the change in center/SIGMA. Modified May 2002 Use MEDIAN(/EVEN) Modified October 2002, Faster computation of weights Corrected documentation on 95% confidence interval of mean P.Broos/W. Landsman July 2003
(See astrolib/pro/biweight_mean.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 astrolib/pro/blink.pro)
NAME: BLKSHIFT AUTHOR: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 craigm@lheamail.gsfc.nasa.gov PURPOSE: Shift a block of data to a new position in a file (possibly overlapping) CALLING SEQUENCE: BLKSHIFT, UNIT, POS, [ DELTA, TO=TO, /NOZERO, ERRMSG=ERRMSG, BUFFERSIZE=BUFFERSIZE ] DESCRIPTION: BLKSHIFT moves a block of data forward or backward, to a new position in a data file. The old and new positions of the block can overlap safely. The new position can be specified with either the DELTA parameter, which gives the number of bytes to move forward (positive delta) or backward (negative delta); or the TO keyword, which give the new absolute starting position of the block. The block can be moved beyond the current end of file point, in which case the intervening gap is filled with zeros (optionally). The gap left at the old position of the block is also optionally zero-filled. If a set of data up to the end of the file is being moved forward (thus making the file smaller) then the file is truncated at the new end.using TRUNCATE_LUN. INPUTS: UNIT - a logical unit number, opened for reading and writing. POS - POS[0] is the position of the block in the file, in bytes, before moving. POS[1], if present, is the size of the block in bytes. If POS[1] is not given, then the block is from POS[0] to the end of the file. DELTA - the (optional) offset in bytes between the old and new positions, from the start of the block. Positive values indicate moving the data forward (toward the end of file), and negative values indicate moving the data backward (toward the beginning of the file). One of DELTA and TO must be specified; DELTA overrides the TO keyword. Attempts to move the block beyond the end of the file will succeed. A block can never be moved beyond the beginning of the file; it will be moved to the beginning instead. KEYWORD PARAMETERS: TO - the absolute file offset in bytes for the new start of the block. One of DELTA and TO must be specified; DELTA overrides the TO keyword. /NOZERO - if set, then newly created gaps will not be explicitly zeroed. Note that in same systems (e.g. MacOS) the gaps will always be zeroed whether or not /NOZERO is set. ERRMSG - If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. BLKSHIFT, UNIT, POS, DElTA, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... BUFFERSIZE - the maximum buffer size for transfers, in bytes. Larger values of this keyword impose larger memory requirements on the application; smaller values will lead to more transfer operations. Default: 32768 (bytes) MODIFICATION HISTORY: Written, CM, Apr 2000 Documented and re-written, CM, 20 Jul 2000 Renamed from FXSHIFT to BLKSHIFT, CM, 21 Jul 2000 Documentation, CM, 12 Dec 2002 Truncate if moving data block forward from the end of file using TRUNCATE_LUN W. Landsman Feb. 2005 Assume since V5.5, remove VMS support W. Landsman Sep 2006 Assume since V5.6, TRUNCATE_LUN available W. Landsman Sep 2006 MacOS can point beyond EOF W. Landsman Aug 2009
(See astrolib/pro/blkshift.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 accommodate it. If both input arrays have the same number of dimensions, then the output array will have one additional dimension. Otherwise, the last dimension of DESTINATION will be incremented by one. CATEGORY: Utility CALLING SEQUENCE: BOOST_ARRAY, DESTINATION, APPEND INPUT: DESTINATION = Array to be expanded. APPEND = Array to append to DESTINATION. OUTPUTS: DESTINATION = Expanded output array. RESTRICTIONS: DESTINATION and APPEND have to be either both of type string or both of numerical types. APPEND cannot have more dimensions than DESTINATION. MODIFICATION HISTOBY: Written Aug'88 (DMZ, ARC) Modified Sep'89 to handle byte arrays (DMZ) Modifed to version 2, Paul Hick (ARC), Feb 1991 Removed restriction to 2D arrays, William Thompson (ARC), Feb 1992. Converted to IDL V5.0 W. Landsman September 1997
(See astrolib/pro/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 follow 2 ways: (1) the box size parameter is specified rather than the output array size (2) for INTEGER arrays, BOXAVE computes intermediate steps using REAL*4 (or REAL*8 for 64bit integers) 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 Allow unsigned data types W. Landsman Jan. 2000 Assume since V5.4, Allow 64bit integers W. Landsman Apr 2006
(See astrolib/pro/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 12", mainly in right ascension. If better accuracy than this is needed then BPRECESS should be used. An unsystematic comparison of BPRECESS with the IPAC precession routine (http://nedwww.ipac.caltech.edu/forms/calculator.html) always gives differences less than 0.15". EXAMPLE: The SAO2000 catalogue gives the J2000 position and proper motion for the star HD 119288. Find the B1950 position. RA(2000) = 13h 42m 12.740s Dec(2000) = 8d 23' 17.69'' Mu(RA) = -.0257 s/yr Mu(Dec) = -.090 ''/yr IDL> mu_radec = 100D* [ -15D*.0257, -0.090 ] IDL> ra = ten(13, 42, 12.740)*15.D IDL> dec = ten(8, 23, 17.69) IDL> bprecess, ra, dec, ra1950, dec1950, mu_radec = mu_radec IDL> print, adstring(ra1950, dec1950,2) ===> 13h 39m 44.526s +08d 38' 28.63" REVISION HISTORY: Written, W. Landsman October, 1992 Vectorized, W. Landsman February, 1994 Treat case where proper motion not known or exactly zero November 1994 Handling of arrays larger than 32767 Lars L. Christensen, march, 1995 Fixed bug where A term not initialized for vector input W. Landsman February 2000 Use V6.0 notation W. Landsman Mar 2011
(See astrolib/pro/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. Environmental variables can themselves contain multiple paths. OUTPUT: The result of the function is a string array of directories. Unless the NOCURRENT keyword is set, the first element of the array is always the null string, representing the current directory. All the other directories will end in the correct separator character for the current operating system. OPTIONAL INPUT KEYWORD: /NOCURRENT = If set, then the current directory (represented by the null string) will not automatically be prepended to the output. PROCEDURE CALLS: None. REVISION HISTORY: Version 1, William Thompson, GSFC, 6 May 1993. Added IDL for Windows compatibility. Version 2, William Thompson, GSFC, 16 May 1995 Added keyword NOCURRENT Version 3, William Thompson, GSFC, 29 August 1995 Modified to use OS_FAMILY Version 4, Zarro, GSFC, 4 August 1997 Added trim to input Fix directory character on Macintosh system A. Ferro February 2000 Use STRSPLIT instead of STR_SEP() W. Landsman July 2002 Remove VMS support W. Landsman September 2006
(See astrolib/pro/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) A faster algorithm (radix sort) for numeric data is available at http://idldatapoint.com/2012/04/19/an-lsd-radix-sort-algorithm-in-idl/ 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 astrolib/pro/bsort.pro)
NAME: CALZ_UNRED PURPOSE: Deredden a galaxy spectrum using the Calzetti et al. (2000) recipe EXPLANATION: Calzetti et al. (2000, ApJ 533, 682) developed a recipe for dereddening the spectra of galaxies where massive stars dominate the radiation output, valid between 0.12 to 2.2 microns. (CALZ_UNRED extrapolates between 0.12 and 0.0912 microns.) CALLING SEQUENCE: CALZ_UNRED, wave, flux, ebv, [ funred, R_V = ] INPUT: WAVE - wavelength vector (Angstroms) FLUX - calibrated flux vector, same number of elements as WAVE If only 3 parameters are supplied, then this vector will updated on output to contain the dereddened flux. EBV - color excess E(B-V), scalar. If a negative EBV is supplied, then fluxes will be reddened rather than deredenned. Note that the supplied color excess should be that derived for the stellar continuum, EBV(stars), which is related to the reddening derived from the gas, EBV(gas), via the Balmer decrement by EBV(stars) = 0.44*EBV(gas) OUTPUT: FUNRED - unreddened flux vector, same units and number of elements as FLUX. FUNRED values will be zeroed outside valid domain Calz_unred (0.0912 - 2.2 microns). OPTIONAL INPUT KEYWORD: R_V - Ratio of total to selective extinction, default = 4.05. Calzetti et al. (2000) estimate R_V = 4.05 +/- 0.80 from optical -IR observations of 4 starbursts. EXAMPLE: Estimate how a flat galaxy spectrum (in wavelength) between 1200 A and 3200 A is altered by a reddening of E(B-V) = 0.1. IDL> w = 1200 + findgen(40)*50 ;Create a wavelength vector IDL> f = w*0 + 1 ;Create a "flat" flux vector IDL> calz_unred, w, f, -0.1, fnew ;Redden (negative E(B-V)) flux vector IDL> plot,w,fnew NOTES: Use the 4 parameter calling sequence if you wish to save the original flux vector. PROCEDURE CALLS: POLY() REVISION HISTORY: Written W. Landsman Raytheon ITSS December, 2000
(See astrolib/pro/calz_unred.pro)
NAME: CCM_UNRED PURPOSE: Deredden a flux vector using the CCM 1989 parameterization EXPLANATION: The reddening curve is that of Cardelli, Clayton, and Mathis (1989 ApJ. 345, 245), including the update for the near-UV given by O'Donnell (1994, ApJ, 422, 158). Parameterization is valid from the IR to the far-UV (3.5 microns to 0.1 microns). Users might wish to consider using the alternate procedure FM_UNRED which uses the extinction curve of Fitzpatrick (1999). CALLING SEQUENCE: CCM_UNRED, wave, flux, ebv, funred, [ R_V = ] or CCM_UNRED, wave, flux, ebv, [ R_V = ] INPUT: WAVE - wavelength vector (Angstroms) FLUX - calibrated flux vector, same number of elements as WAVE If only 3 parameters are supplied, then this vector will updated on output to contain the dereddened flux. EBV - color excess E(B-V), scalar. If a negative EBV is supplied, then fluxes will be reddened rather than deredenned. OUTPUT: FUNRED - unreddened flux vector, same units and number of elements as FLUX OPTIONAL INPUT KEYWORD R_V - scalar specifying the ratio of total selective extinction R(V) = A(V) / E(B - V). If not specified, then R_V = 3.1 Extreme values of R(V) range from 2.75 to 5.3 EXAMPLE: Determine how a flat spectrum (in wavelength) between 1200 A and 3200 A is altered by a reddening of E(B-V) = 0.1. Assume an "average" reddening for the diffuse interstellar medium (R(V) = 3.1) IDL> w = 1200 + findgen(40)*50 ;Create a wavelength vector IDL> f = w*0 + 1 ;Create a "flat" flux vector IDL> ccm_unred, w, f, -0.1, fnew ;Redden (negative E(B-V)) flux vector IDL> plot,w,fnew NOTES: (1) The CCM curve shows good agreement with the Savage & Mathis (1979) ultraviolet curve shortward of 1400 A, but is probably preferable between 1200 and 1400 A. (2) Many sightlines with peculiar ultraviolet interstellar extinction can be represented with a CCM curve, if the proper value of R(V) is supplied. (3) Curve is extrapolated between 912 and 1000 A as suggested by Longo et al. (1989, ApJ, 339,474) (4) Use the 4 parameter calling sequence if you wish to save the original flux vector. (5) Valencic et al. (2004, ApJ, 616, 912) revise the ultraviolet CCM curve (3.3 -- 8.0 um-1). But since their revised curve does not connect smoothly with longer and shorter wavelengths, it is not included here. REVISION HISTORY: Written W. Landsman Hughes/STX January, 1992 Extrapolate curve for wavelengths between 900 and 1000 A Dec. 1993 Use updated coefficients for near-UV from O'Donnell Feb 1994 Allow 3 parameter calling sequence April 1998 Converted to IDLV5.0 April 1998
(See astrolib/pro/ccm_unred.pro)
NAME: CHECKSUM32 PURPOSE: To compute the 32bit checksum of an array (ones-complement arithmetic) EXPLANATION: The 32bit checksum is adopted in the FITS Checksum convention http://heasarc.gsfc.nasa.gov/docs/heasarc/fits/checksum.html CALLING SEQUENCE: CHECKSUM32, array, checksum, [/FROM_IEEE, /NoSAVE] INPUTS: array - any numeric idl array. If the number of bytes in the array is not a multiple of four then it is padded with zeros internally (the array is returned unchanged). Convert a string array (e.g. a FITS header) to bytes prior to calling CHECKSUM32. OUTPUTS: checksum - unsigned long scalar, giving sum of array elements using ones-complement arithmetic OPTIONAL INPUT KEYWORD: /FROM_IEEE - If this keyword is set, then the input is assumed to be in big endian format (e.g. an untranslated FITS array). This keyword only has an effect on little endian machines (e.g. Linux boxes). /NoSAVE - if set, then the input array is not saved upon exiting. Use the /NoSave keyword to save time if the input array is not needed in further computations. METHOD: Uses TOTAL() to sum the array into a double precision variable. The overflow bits beyond 2^32 are then shifted back to the least significant bits. Due to the limited precision of a DOUBLE variable, the summing is done in chunks determined by MACHAR(). Adapted from FORTRAN code in heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/general/checksum/node30.html Could probably be done in a cleverer way (similar to the C implementation) but then the array-oriented TOTAL() function could not be used. RESTRICTIONS: (1) Not valid for object or pointer data types EXAMPLE: Find the 32 bit checksum of the array x = findgen(35) IDL> checksum32, x, s ===> s = 2920022024 FUNCTION CALLED: HOST_TO_IEEE, IS_IEEE_BIG(), N_BYTES() MODIFICATION HISTORY: Written W. Landsman June 2001 Work correctly on little endian machines, added /FROM_IEEE and /NoSave W. Landsman November 2002 Pad with zeros when array size not a multiple of 4 W.Landsman Aug 2003 Always copy to new array, somewhat slower but more robust algorithm especially for Linux boxes W. Landsman Sep. 2004 Sep. 2004 update not implemented correctly (sigh) W. Landsman Dec 2004 No need to byteswap 4 byte datatypes on little endian W. L. May 2009 Use /INTEGER keyword to TOTAL() function W.L. June 2009
(See astrolib/pro/checksum32.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 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 the /UPDATE keyword is present, then the FITS header will be modified, if necessary, to force agreement with the image array CALLING SEQUENCE: check_FITS, im, hdr, [ dimen, idltype, /UPDATE, /NOTYPE, /SILENT ERRMSG = ]' INPUT PARAMETERS: IM - FITS array, e.g. as read by READFITS HDR - FITS 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 NAXISi FITS keywords will be updated to agree with the array /FITS, /SDAS - these are obsolete keywords that now do nothing /SILENT - If keyword is set and nonzero, the informational messages will not be printed OPTIONAL KEYWORD OUTPUT: ERRMSG = If this keyword is present, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. PROCEDURE: Program checks the NAXIS and NAXISi keywords in the header to see if they match the image array dimensions, and checks whether the BITPIX keyword agrees with the array type. PROCEDURE CALLS: FXADDPAR, FXPAR(), SXDELPAR 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 Allow unsigned data types W. Landsman December 1999 Allow BZERO = 0 for unsigned data types W. Landsman January 2000 Added ERRMSG keyword, W. Landsman February 2000 Use FXADDPAR to put NAXISi in proper order W. Landsman August 2000 Improper FXADDPAR call for DATATYPE keyword W. Landsman December 2000 Remove explicit setting of obsolete !err W. Landsman February 2004 Remove SDAS support W. Landsman November 2006 Fix dimension errors introduced Nov 2006 Work again for null arrays W. Landsman/E. Hivon May 2007 Use V6.0 notation W.L. Feb. 2011
(See astrolib/pro/check_fits.pro)
NAME: CIC PURPOSE: Interpolate an irregularly sampled field using Cloud in Cell method EXPLANATION: This function interpolates an irregularly sampled field to a regular grid using Cloud In Cell (nearest grid point gets weight 1-dngp, point on other side gets weight dngp, where dngp is the distance to the nearest grid point in units of the cell size). CATEGORY: Mathematical functions, Interpolation CALLING SEQUENCE: Result = CIC, VALUE, POSX, NX[, POSY, NY, POSZ, NZ, AVERAGE = average, WRAPAROUND = wraparound, ISOLATED = isolated, NO_MESSAGE = no_message] INPUTS: VALUE: Array of sample weights (field values). For e.g. a temperature field this would be the temperature and the keyword AVERAGE should be set. For e.g. a density field this could be either the particle mass (AVERAGE should not be set) or the density (AVERAGE should be set). POSX: Array of X coordinates of field samples, unit indices: [0,NX>. NX: Desired number of grid points in X-direction. OPTIONAL INPUTS: POSY: Array of Y coordinates of field samples, unit indices: [0,NY>. NY: Desired number of grid points in Y-direction. POSZ: Array of Z coordinates of field samples, unit indices: [0,NZ>. NZ: Desired number of grid points in Z-direction. KEYWORD PARAMETERS: AVERAGE: Set this keyword if the nodes contain field samples (e.g. a temperature field). The value at each grid point will then be the weighted average of all the samples allocated to it. If this keyword is not set, the value at each grid point will be the weighted sum of all the nodes allocated to it (e.g. for a density field from a distribution of particles). (D=0). WRAPAROUND: Set this keyword if you want the first grid point to contain samples of both sides of the volume (see below). ISOLATED: Set this keyword if the data is isolated, i.e. not periodic. In that case total `mass' is not conserved. This keyword cannot be used in combination with the keyword WRAPAROUND. NO_MESSAGE: Suppress informational messages. Example of default allocation of nearest grid points: n0=4, *=gridpoint. 0 1 2 3 Index of gridpoints * * * * Grid points |---|---|---|---| Range allocated to gridpoints ([0.0,1.0> --> 0, etc.) 0 1 2 3 4 posx Example of ngp allocation for WRAPAROUND: n0=4, *=gridpoint. 0 1 2 3 Index of gridpoints * * * * Grid points |---|---|---|---|-- Range allocated to gridpoints ([0.5,1.5> --> 1, etc.) 0 1 2 3 4=0 posx OUTPUTS: Prints that a CIC interpolation is being performed of x samples to y grid points, unless NO_MESSAGE is set. RESTRICTIONS: Field data is assumed to be periodic with the sampled volume the basic cell, unless ISOLATED is set. All input arrays must have the same dimensions. Postition coordinates should be in `index units' of the desired grid: POSX=[0,NX>, etc. Keywords ISOLATED and WRAPAROUND cannot both be set. PROCEDURE: Nearest grid point is determined for each sample. CIC weights are computed for each sample. Samples are interpolated to the grid. Grid point values are computed (sum or average of samples). NOTES: Use tsc.pro for a higher-order interpolation scheme, ngp.pro for a lower order interpolation scheme. A standard reference for these interpolation methods is: R.W. Hockney and J.W. Eastwood, Computer Simulations Using Particles (New York: McGraw-Hill, 1981). EXAMPLE: nx=20 ny=10 posx=randomu(s,1000) posy=randomu(s,1000) value=posx^2+posy^2 field=cic(value,posx*nx,nx,posy*ny,ny,/average) surface,field,/lego MODIFICATION HISTORY: Written by Joop Schaye, Feb 1999. Avoid integer overflow for large dimensions P.Riley/W.Landsman Dec. 1999
(See astrolib/pro/cic.pro)
NAME: CIRRANGE PURPOSE: To force an angle into the range 0 <= ang < 360. CALLING SEQUENCE: CIRRANGE, ang, [/RADIANS] 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, Hughes STX, May 1996 Converted to IDL V5.0 W. Landsman September 1997
(See astrolib/pro/cirrange.pro)
NAME: CLEANPLOT PURPOSE: Reset all plotting 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, [ /Silent, /ShowOnly] INPUTS: None OPTIONAL KEYWORD INPUT: /SHOWONLY - If set, then CLEANPLOT will display the plotting system variables with nondefault values, but it will not reset them. /SILENT - If set, then CLEANPLOT will not display a message giving the the system variables tags being reset. One cannot set both /SILENT and /SHOWONLY 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 !P.CLIP and 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 Added silent keyword to supress output & modified X_old to handle the new !X and !Y tags in IDL 5.4 S. Penton July 2000 Test for visual depth if > V5.1 W. Landsman July 2000 Macs can report a visual depth of 32 W. Landsman March 2001 Call device,get_visual_depth only for device which allow it W. Landsman June 2001 Default !P.color is 16777215 for 16 bit systems W. Landsman/M. Hadfield November 2001 Added ShowOnly keyword W. Landsman April 2002 Use V6.0 notation W. Landsman April 2011
(See astrolib/pro/cleanplot.pro)
NAME: CNTRD PURPOSE: Compute the centroid of a star using a derivative search EXPLANATION: CNTRD uses an early DAOPHOT "FIND" centroid algorithm by locating the position where the X and Y derivatives go to zero. This is usually a more "robust" determination than a "center of mass" or fitting a 2d Gaussian if the wings in one direction are affected by the presence of a neighboring star. CALLING SEQUENCE: CNTRD, img, x, y, xcen, ycen, [ fwhm , /KEEPCENTER, /SILENT, /DEBUG EXTENDBOX = ] INPUTS: IMG - Two dimensional image array X,Y - Scalar or vector integers giving approximate integer 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, floating point 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. EXTENDBOX = {non-negative positive integer}. CNTRD searches a box with a half width equal to 1.5 sigma = 0.637* FWHM to find the maximum pixel. To search a larger area, set EXTENDBOX to the number of pixels to enlarge the half-width of the box. Default is 0; prior to June 2004, the default was EXTENDBOX= 3 /KeepCenter = By default, CNTRD finds the maximum pixel in a box centered on the input X,Y coordinates, and then extracts a new box about this maximum pixel. Set the /KeepCenter keyword to skip then step of finding the maximum pixel, and instead use a box centered on the input X,Y coordinates. 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. In order to minimize contamination from neighboring stars stars, a weighting factor W is defined as unity in center, 0.5 at end, and linear in between RESTRICTIONS: (1) Does not recognize (bad) pixels. Use the procedure GCNTRD.PRO in this situation. (2) DAOPHOT now uses a newer algorithm (implemented in GCNTRD.PRO) in which centroids are determined by fitting 1-d Gaussians to the marginal distributions in the X and Y directions. (3) The default behavior of CNTRD changed in June 2004 (from EXTENDBOX=3 to EXTENDBOX = 0). (4) Stone (1989, AJ, 97, 1227) concludes that the derivative search algorithm in CNTRD is not as effective (though faster) as a Gaussian fit (used in GCNTRD.PRO). 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 Better checking of edge of frame David Hogg October 2000 Avoid integer wraparound for unsigned arrays W.Landsman January 2001 Handle case where more than 1 pixel has maximum value W.L. July 2002 Added /KEEPCENTER, EXTENDBOX (with default = 0) keywords WL June 2004 Some errrors were returning X,Y = NaN rather than -1,-1 WL Aug 2010
(See astrolib/pro/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 have different struct.definitions), and return a structured List of fields found different. The Exelis contrib library has a faster but less powerful procedure struct_equal.pro, see http://www.exelisvis.com/Default.aspx?tabid=1540&id=1175 CALLING SEQUENCE: diff_List = compare_struct( struct_A, struct_B [ EXCEPT=, /BRIEF, /FULL, /NaN, /RECUR_A, /RECUR_B ) INPUTS: struct_A, struct_B : the two structure arrays to compare. Struct_Name : for internal recursion use only. OPTIONAL INPUT 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. /NaN = if set, then tag values are considered equal if they are both set to NaN /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. The tags are TAG_NUM_A - the tag number in structure A TAG_NUM_B - the tag number in structure B FIELD - the tag name NDIFF - number of differences (always 1 for a scalar tag). PROCEDURE: Match Tag names and then use where function on tags. EXAMPLE: Find the tags in the !X system variable which are changed after a simple plot. IDL> x = !X ;Save original values IDL> plot, indgen(25) ;Make a simple plot IDL> help,/str,compare_struct(x,!X) ;See how structure has changed and one will see that the tags !X.crange and !X.S are changed by the plot. 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. Added /NaN keyword W. Landsman March 2004 Don't test string for NaN values W. Landsman March 2008
(See astrolib/pro/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> RESTRICTIONS: The version of CONCAT_DIR available at http://sohowww.nascom.nasa.gov/solarsoft/gen/idl/system/concat_dir.pro includes (mostly) 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 Changed loops to long integer W. Landsman December 1998 Added Mac support, translate Windows environment variables, & treat case where dirname ends in '/' W. Landsman Feb. 2000 Assume since V5.5, remove VMS support W. Landsman Sep. 2006
(See astrolib/pro/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 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, 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, SIN and CAR 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 Paper II of Greisen & Calabretta (2002, A&A, 395, 1077). These documents are available from http://www.cv.nrao.edu/fits/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 Fix case where DEC is scalar, X is vector W. Landsman RITSS Feb. 2000 Fix possible sign error introduced Jan. 2000 W. Landsman May 2000 Work for the CARee' projection W. Landsman May 2003
(See astrolib/pro/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 longitude), 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, [ DEC] ) INPUTS: RA - Right Ascension value in DEGREES (0 < RA < 360.). 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. OPTIONAL OUTPUT: DEC - Computed set of declinations (in DEGREES) for X,Y, coordinates 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 Paper II of Calabretta & Greisen (2002, A&A, 395, 1077). These documents are available from http://www.cv.nrao.edu/fits/documents/wcs/wcs.html RESTRICTIONS: Implemented only for the TANgent, SIN and CARtesian projections REVISION HISTORY: Written, Wayne Landsman STX Co. April, 1988 Algorithm adapted from AIPS memo No. 27 by Eric Greisen New astrometry structure Converted to IDL V5.0 W. Landsman September 1997 Added SIN projection W. Landsman January 2000 Fix possible sign error introduced Jan. 2000 W. Landsman May 2000 Work for the CARee' projection W. Landsman May 2003 For TAN projection ensure angles between -90 and 90 W. Landsman Jan 2008
(See astrolib/pro/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). The image is padded with zeros so that a large PSF does not overlap one edge of the image with the opposite edge of the image. This routine is now partially obsolete due to the introduction of the intrinsic CONVOL_FFT() function in IDL 8.1 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). The PSF *must* be symmetric about the point FLOOR((n_elements-1)/2), where n_elements is the number of elements in each dimension. For Gaussian PSFs, the maximum of the PSF must occur in this pixel (otherwise the convolution will shift everything in the 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) /NO_PAD - if set, then do not pad the image to avoid edge effects. This will improve memory and speed of the computation at the expense of edge effects. This was the default method prior to October 2009 METHOD: When using FFT, PSF is centered & expanded to size of image. HISTORY: written, Frank Varosi, NASA/GSFC 1992. Appropriate precision type for result depending on input image Markus Hundertmark February 2006 Fix the bug causing the recomputation of FFT(psf) and/or FFT(image) Sergey Koposov December 2006 Fix the centering bug Kyle Penner October 2009 Add /No_PAD keyword for better speed and memory usage when edge effects are not important. W. Landsman March 2010 Add warning when kernel type does not match integer array W. Landsman Feb 2012
(See astrolib/pro/convolve.pro)
NAME: COPY_STRUCT PURPOSE: Copy all fields with matching tag names from one structure to another EXPLANATION: COPY_STRUCT is similar to the intrinisc STRUCT_ASSIGN procedure but has optional keywords to exclude or specify specific tags. 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 mod May 01 by D. Schlegel use long integers
(See astrolib/pro/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 Use long integers W. Landsman May 2001
(See astrolib/pro/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 Always REBIN() using floating pt arithmetic W. Landsman Nov 2007
(See astrolib/pro/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 astrolib/pro/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 astrolib/pro/corrmat_analyze.pro)
NAME: COSMO_PARAM PURPOSE: Derive full set of cosmological density parameters from a partial set EXPLANATION: This procedure is called by LUMDIST and GALAGE to allow the user a choice in defining any two of four cosmological density parameters. Given any two of the four input parameters -- (1) the normalized matter density Omega_m (2) the normalized cosmological constant, Omega_lambda (3) the normalized curvature term, Omega_k and (4) the deceleration parameter q0 -- this program will derive the remaining two. Here "normalized" means divided by the closure density so that Omega_m + Omega_lambda + Omega_k = 1. For a more precise definition see Carroll, Press, & Turner (1992, ArAA, 30, 499). If less than two parameters are defined, this procedure sets default values of Omega_k=0 (flat space), Omega_lambda = 0.7, Omega_m = 0.3 and q0 = -0.55 CALLING SEQUENCE: COSMO_PARAM, Omega_m, Omega_lambda, Omega_k, q0 INPUT-OUTPUTS: Omega_M - normalized matter energy density, non-negative numeric scalar Omega_Lambda - Normalized cosmological constant, numeric scalar Omega_k - normalized curvature parameter, numeric scalar. This is zero for a flat universe q0 - Deceleration parameter, numeric scalar = -R*(R'')/(R')^2 = 0.5*Omega_m - Omega_lambda NOTES: If more than two parameters are defined upon input (overspecification), then the first two defined parameters in the ordered list Omega_m, Omega_lambda, Omega_k, q0 are used to define the cosmology. EXAMPLE: Suppose one has Omega_m = 0.3, and Omega_k = 0.5 then to determine Omega_lambda and q0 IDL> cosmo_param, 0.3, omega_lambda, 0.5, q0 which will return omega_lambda = 0.2 and q0 = -2.45 REVISION HISTORY: W. Landsman Raytheon ITSS April 2000 Better Error checking W. Landsman/D. Syphers October 2010
(See astrolib/pro/cosmo_param.pro)
NAME: CO_ABERRATION PURPOSE: Calculate changes to Ra and Dec due to the effect of annual aberration EXPLANATION: as described in Meeus, Chap 23. CALLING SEQUENCE: co_aberration, jd, ra, dec, d_ra, d_dec, [EPS = ] INPUTS jd : Julian Date [scalar or vector] ra, dec : Arrays (or scalars) of the ra and dec's in degrees Note: if jd is a vector, then ra and dec must either be scalars, or vectors of the same length. OUTPUTS d_ra, d_dec: the corrections to ra and dec due to aberration in arcseconds. (These values can be added to the true RA and dec to get the apparent position). Note that d_ra is *not* multiplied by cos(dec), so that apparent_ra = ra + d_ra/3600. OPTIONAL INPUT KEYWORD: eps : set this to the true obliquity of the ecliptic (in radians), or it will be set for you if you don't know it (in that case, set it to an empty variable). EXAMPLE: Compute the change in RA and Dec of Theta Persei (RA = 2h46m,11.331s, Dec = 49d20',54.54") due to aberration on 2028 Nov 13.19 TD IDL> jdcnv,2028,11,13,.19*24,jd ;Get Julian date IDL> co_aberration,jd,ten(2,46,11.331)*15,ten(49,20,54.54),d_ra,d_dec ==> d_ra = 30.045" (=2.003s) d_dec = 6.697" NOTES: These formula are from Meeus, Chapters 23. Accuracy is much better than 1 arcsecond. The maximum deviation due to annual aberration is 20.49" and occurs when the Earth velocity is perpendicular to the direction of the star. REVISION HISTORY: Written, June 2002, Chris O'Dell, U. of Wisconsin Fix error with vector input W. Landsman June 2009 June 2009 update fixed case where JD was scalar but RA,Dec were vectors, but broke the case when both JD and RA,Dec were vectors Aug 2012 W. Landsman
(See astrolib/pro/co_aberration.pro)
NAME: CO_NUTATE PURPOSE: Calculate changes in RA and Dec due to nutation of the Earth's rotation EXPLANATION: Calculates necessary changes to ra and dec due to the nutation of the Earth's rotation axis, as described in Meeus, Chap 23. Uses formulae from Astronomical Almanac, 1984, and does the calculations in equatorial rectangular coordinates to avoid singularities at the celestial poles. CALLING SEQUENCE: CO_NUTATE, jd, ra, dec, d_ra, d_dec, [EPS=, D_PSI =, D_EPS = ] INPUTS JD: Julian Date [scalar or vector] RA, DEC : Arrays (or scalars) of the ra and dec's of interest Note: if jd is a vector, ra and dec MUST be vectors of the same length. OUTPUTS: d_ra, d_dec: the corrections to ra and dec due to nutation (must then be added to ra and dec to get corrected values). OPTIONAL OUTPUT KEYWORDS: EPS: set this to a named variable that will contain the obliquity of the ecliptic. D_PSI: set this to a named variable that will contain the nutation in the longitude of the ecliptic D_EPS: set this to a named variable that will contain the nutation in the obliquity of the ecliptic EXAMPLE: (1) Example 23a in Meeus: On 2028 Nov 13.19 TD the mean position of Theta Persei is 2h 46m 11.331s 49d 20' 54.54". Determine the shift in position due to the Earth's nutation. IDL> jd = JULDAY(11,13,2028,.19*24) ;Get Julian date IDL> CO_NUTATE, jd,ten(2,46,11.331)*15.,ten(49,20,54.54),d_ra,d_dec ====> d_ra = 15.843" d_dec = 6.217" PROCEDURES USED: NUTATE REVISION HISTORY: Written Chris O'Dell, 2002 Vector call to NUTATE W. Landsman June 2002
(See astrolib/pro/co_nutate.pro)
NAME: CO_REFRACT() PURPOSE: Calculate correction to altitude due to atmospheric refraction. DESCRIPTION: CO_REFRACT can calculate both apparent altitude from observed altitude and vice-versa. CALLING SEQUENCE: new_alt = CO_REFRACT(old_alt, [ ALTITUDE= , PRESSURE= , $ TEMPERATURE= , /TO_OBSERVED , EPSILON= ]) INPUT: old_alt - Observed (apparent) altitude, in DEGREES. (apparent if keyword /TO_OBSERVED set). May be scalar or vector. OUTPUT: Function returns apparent (observed) altitude, in DEGREES. (observed if keyword /TO_OBSERVED set). Will be of same type as input altitude(s). OPTIONAL KEYWORD INPUTS: ALTITUDE : The height of the observing location, in meters. This is only used to determine an approximate temperature and pressure, if these are not specified separately. [default=0, i.e. sea level] PRESSURE : The pressure at the observing location, in millibars. TEMPERATURE: The temperature at the observing location, in Kelvin. EPSILON: When keyword /TO_OBSERVED has been set, this is the accuracy to obtain via the iteration, in arcseconds [default = 0.25 arcseconds]. /TO_OBSERVED: Set this keyword to go from Apparent->Observed altitude, using the iterative technique. Note, if altitude is set, but temperature or pressure are not, the program will make an intelligent guess for the temperature and pressure. DESCRIPTION: Because the index of refraction of air is not precisely 1.0, the atmosphere bends all incoming light, making a star or other celestial object appear at a slightly different altitude (or elevation) than it really is. It is important to understand the following definitions: Observed Altitude: The altitude that a star is SEEN to BE, with a telescope. This is where it appears in the sky. This is always GREATER than the apparent altitude. Apparent Altitude: The altitude that a star would be at, if *there were no atmosphere* (sometimes called "true" altitude). This is usually calculated from an object's celestial coordinates. Apparent altitude is always LOWER than the observed altitude. Thus, for example, the Sun's apparent altitude when you see it right on the horizon is actually -34 arcminutes. This program uses couple simple formulae to estimate the effect for most optical and radio wavelengths. Typically, you know your observed altitude (from an observation), and want the apparent altitude. To go the other way, this program uses an iterative approach. EXAMPLE: The lower limb of the Sun is observed to have altitude of 0d 30'. Calculate the the true (=apparent) altitude of the Sun's lower limb using mean conditions of air pressure and temperature IDL> print, co_refract(0.5) ===> 0.025degrees (1.55') WAVELENGTH DEPENDENCE: This correction is 0 at zenith, about 1 arcminute at 45 degrees, and 34 arcminutes at the horizon FOR OPTICAL WAVELENGTHS. The correction is NON-NEGLIGIBLE at all wavelengths, but is not very easily calculable. These formulae assume a wavelength of 550 nm, and will be accurate to about 4 arcseconds for all visible wavelengths, for elevations of 10 degrees and higher. Amazingly, they are also ACCURATE FOR RADIO FREQUENCIES LESS THAN ~ 100 GHz. It is important to understand that these formulae really can't do better than about 30 arcseconds of accuracy very close to the horizon, as variable atmospheric effects become very important. REFERENCES: 1. Meeus, Astronomical Algorithms, Chapter 15. 2. Explanatory Supplement to the Astronomical Almanac, 1992. 3. Methods of Experimental Physics, Vol 12 Part B, Astrophysics, Radio Telescopes, Chapter 2.5, "Refraction Effects in the Neutral Atmosphere", by R.K. Crane. DEPENDENCIES: CO_REFRACT_FORWARD (contained in this file and automatically compiled). AUTHOR: Chris O'Dell Univ. of Wisconsin-Madison Observational Cosmology Laboratory Email: odell@cmb.physics.wisc.edu REVISION HISTORY: version 1 (May 31, 2002) Update iteration formula, W. Landsman June 2002 Corrected slight bug associated with scalar vs. vector temperature and pressure inputs. 6/10/2002 Fixed problem with vector input when /TO_OBSERVED set W. Landsman Dec 2005 Allow arrays with more than 32767 elements W.Landsman/C.Dickinson Feb 2010
(See astrolib/pro/co_refract.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) Any strings that are not valid IDL tag names (e.g. 'a\2') will be converted by IDL_VALIDNAME to a valid tagname by replacing with underscores as necessary (e.g. 'a_2') 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, 'K' for 64bit 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 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 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. 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: 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 Write temporary file in HOME directory if necessary W. Landsman Jul 98 Use OPENR,/DELETE for OS-independent file removal W. Landsman Jan 99 Use STRSPLIT() instead of GETTOK() W. Landsman July 2002 Assume since V5.3 W. Landsman Feb 2004 Added RESOLVE_ROUTINE to ensure recompilation W. Landsman Sep. 2004 Delete temporary with FILE_DELETE W. Landsman Sep 2006 Assume since V5.5, delete VMS reference W.Landsman Sep 2006 Added 'K' format for 64 bit integers, IDL_VALIDNAME check on tags W. Landsman Feb 2007 Use vector form of IDL_VALIDNAME() if V6.4 or later W.L. Dec 2007 Suppress compilation mesage of temporary file A. Conley/W.L. May 2009 Remove FDECOMP, some cleaner coding W.L. July 2009 Do not limit string length to 1000 chars P. Broos, Feb 2011
(See astrolib/pro/create_struct.pro)
NAME: CR_REJECT PURPOSE: General, iterative cosmic ray rejection using two or more input images. EXPLANATION: 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. If the noise model is used (rd_noise_dn, dark_dn, gain), then input_cube must be in units of DN. If an input noise cube is supplied (rd_noise_dn <0), then the units of input_cube and noise_cube merely need to be consistent. This array is used as a buffer and its contents are not guaranteed on output (although for now, weighting=0 with /restore_sky should give you back your input unaltered). INPUT ARGUMENTS: rd_noise_dn - Read noise per pixel. Units are 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 to be followed through the computation. noskyadjust - Sky not to be subtracted before rejection tests. Default is to do the subtraction. 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. input_mask - Mask cube input by the user. Should be byte data because it's boolean. 1 means use the pixel, and 0 means reject the pixel - these rejections are in addition to those done by the CR rejection algorithm as such. 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 if 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 if 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 input_cube before returning. Works only if weighting=0. null_value - Value to be used for output pixels to which no input pixels contribute. Default=0 weighting - Selects weighting scheme in final image combination: 0 (default) - Poissonian weighting - co-add detected DN from non-CR pixels. (Pixel-by- pixel scaling up to total exposure time, for pixels in stack where some rejected.) Equivalent to exptime weighting of rates. 1 or more - Sky and read noise weighting of rates. Computed as weighted average of DN rates, with total exp time multiplied back in afterward. In all cases, the image is returned as a sum in DN with the total exposure time of the image stack, and with total sky added back in. 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. (Not permitted if input_cube has fewer than 3 planes; 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 KEYWORDS: mask_cube - CR masks for each input image. 1 means good pixel; 0 means CR pixel. 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. 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). skybox - X0, X1, Y0, Y1 bounds of image section used to compute sky. If supplied by user, this region is used. If not supplied, the image bounds are returned. This parameter might be used (for instance) if the imaging area doesn't include the whole chip. 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 (except for some pixels along the edge of the image) 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 15 May 1998 - Input_mask keyword. RSH 27 May 1998 - Initialization of minimum image corrected. NRC, RSH 9 June 1998 - Input mask cube processing corrected. RSH 21 Sep. 1998 - Weighting keyword added. RSH 7 Oct. 1998 - Fixed bug in input_mask processing (introduced in preceding update). Input_mask passed to skyadj_cube. RSH 5 Mar. 1999 - Force init_min for 2 planes. RSH 1 Oct. 1999 - Make sure weighting=1 not given with noise cube. RSH 1 Dec. 1999 - Corrections to doc; restore_sky needs weighting=0. RSH 17 Mar. 2000 - SKYBOX added. RSH
(See astrolib/pro/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, must be monotonic increasing or decreasing 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> cgplot,x,y,psym=1 ;Plot original grid IDL> cgplot, /over, 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 Work for monotonic decreasing X vector W. Landsman February 1999
(See astrolib/pro/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, dummy, JD INPUTS: Lng - The longitude in degrees (east of Greenwich) 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, positive East of the Greenwich meridian (ahead of GMT). Use this parameter to easily account for Daylight Savings time (e.g. -4=EDT, -5 = EST/CDT), scalar This parameter is not needed (and ignored) if Julian date is supplied. ***Note that the sign of TZ was changed in July 2008 to match the standard definition.*** 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 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),integer scalar or vector Mon - The month, in numerical format (1-12), integer scalar or vector Year - The 4 digit year (e.g. 2008), integer scalar or vector OUTPUTS: Lst The Local Sidereal 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. 84 (Eq. 11-4) for the constants used. EXAMPLE: Find the Greenwich mean sidereal time (GMST) on 2008 Jul 30 at 15:53 pm in Baltimore, Maryland (longitude=-76.72 degrees). The timezone is EDT or tz=-4 IDL> CT2LST, lst, -76.72, -4,ten(15,53), 30, 07, 2008 ==> lst = 11.356505 hours (= 11h 21m 23.418s) The Web site http://tycho.usno.navy.mil/sidereal.html contains more info on sidereal time, as well as an interactive calculator. 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 Longitudes measured *east* of Greenwich W. Landsman December 1998 Time zone now measure positive East of Greenwich W. Landsman July 2008 Remove debugging print statement W. Landsman April 2009
(See astrolib/pro/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 The full list of available cursor values is given in /usr/include/X11/cursorfont.h OUTPUTS: None. RESTRICTIONS: Uses the CURSOR_STANDARD keyword of the DEVICE procedure. Although this keyword is available in 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 Use SIZE(/TNAME) instead of DATATYPE() W. Landsman October 2001
(See astrolib/pro/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 Note that in the usual truecolor mode, the byte intensity returned by CURVAL does not correspond to the byte scaled image value but rather returns the maximum value in each color gun. 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=, FILENAME=, ALT=] OPTIONAL INPUTS: Hdr = FITS Header array Im = Array containing values that are displayed. Any type. OPTIONAL KEYWORD INPUTS: ALT - single character 'A' through 'Z' or ' ' specifying an alternate astrometry system present in the FITS header. The default is to use the primary astrometry or ALT = ' '. If /ALT is set, then this is equivalent to ALT = 'A'. See Section 3.3 of Greisen & Calabretta (2002, A&A, 395, 1061) for information about alternate astrometry keywords. 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: ADSTRING(), 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 Remove unneeded calls to obsolete !ERR W. Landsman December 2000 Replace remaining !ERR calls with !MOUSE.BUTTON W. Landsman Jan 2001 Allow for non-celestial (e.g. Galactic) coordinates W. Landsman Apr 2003 Work if RA/Dec reversed in CTYPE keyword W. Landsman Feb. 2004 Always call UNZOOM_XY for MOUSSE compatibility W. Landsman Sep. 2004 Added ALT keyword W. Landsman October 2004 Always test if offset/zoom supplied W. Landsman Feb 2008
(See astrolib/pro/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 astrolib/pro/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 astrolib/pro/dao_value.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 astrolib/pro/date.pro)
NAME: DATE_CONV PURPOSE: Procedure to perform conversion of dates to one of three possible formats. EXPLANATION: The following date formats are allowed format 1: real*8 scalar encoded as: year*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. 2005) 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-2005 15:25:44.23) OR YYYY-MM-DD HH:MM:SS.SS (ISO standard) (eg. 1987-07-14 15:25:44.23 or 1987-07-14T15:25:44.23) format 4: three element vector giving spacecraft time words from a Hubble Space Telescope (HST) telemetry packet. Based on total number of secs since midnight, JAN. 1, 1979 format 5: Julian day. As this is also a scalar, like format 1, the distinction between the two on input is made based on their value. Numbers > 2300000 are interpreted as Julian days. CALLING SEQUENCE results = DATE_CONV( DATE, TYPE ) INPUTS: DATE - input date in one of the possible formats. Must be scalar. 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 'FITS' - YYYY-MM-DDTHH:MM:SS.SS' 'JULIAN' - Julian date 'MODIFIED' - Modified Julian date (JD-2400000.5) TYPE can be abbreviated to the single character strings 'R', 'V', 'S', 'F', 'J', and 'M'. Nobody wants to convert TO spacecraft time (I hope!) OUTPUTS: The converted date is returned as the function value. EXAMPLES: IDL> print,date_conv('2006-03-13 19:58:00.00'),f='(f15.5)' 2006072.83194 IDL> print,date_conv( 2006072.8319444d,'F') 2006-03-13T19:58:00.00 IDL> print,date_conv( 2006072.8319444d,'V') 2006.00 72.0000 19.0000 57.0000 59.9962 IDL> print,date_conv( 2006072.8319444d,'J'), f='(f15.5)' 2453808.33194 HISTORY: version 1 D. Lindler July, 1987 adapted for IDL version 2 J. Isensee May, 1990 Made year 2000 compliant; allow ISO format input jls/acc Oct 1998 DJL/ACC Jan 1998, Modified to work with dates such as 6-JAN-1996 where day of month has only one digit. DJL, Nov. 2000, Added input/output format YYYY-MM-DDTHH:MM:SS.SS Replace spaces with '0' in output FITS format W.Landsman April 2006 Added Julian date capabilities on input and output. M.Perrin, July 2007 Removed spurious /WARN keyword to MESSAGE W.L. Feb 2012
(See astrolib/pro/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 Flandern (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 astrolib/pro/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. This version for IDL V6.1 or later. CALLING SEQUENCE: DBBUILD, [ v1, v2, v3, v4......v50, /NOINDEX, /SILENT, STATUS = ] INPUTS: v1,v2....v50 - 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. PROCEDURE CALLS: DBCLOSE, DBINDEX, DBXPUT, DBWRT, IS_IEEE_BIG() 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 Use SIZE(/TNAME) for error mesage display W.Landsman July 2001 Fix message display error introduced July 2001 W. Landsman Oct. 2001 Make sure error message appears even if !QUIET is set W.L November 2006 Major rewrite to use SCOPE_VARFETCH, accept 50 input items W. Landsman November 2006 Fix warning if parameters have different # of elements W.L. May 2010 Fix warning if scalar parameter supplied W.L. June 2010 Fix for when first parameter is multi-dimensioned W.L. July 2010 Check data type of first parameter W.L. Jan 2012
(See astrolib/pro/dbbuild.pro)
NAME: DBCIRCLE PURPOSE: Find sources in a database within specified radius of specified center EXPLANATION: Database must include items named 'RA' (in hours) and 'DEC' (in degrees) and must have previously been opened with DBOPEN CALLING SEQUENCE: list = DBCIRCLE( ra_cen, dec_cen, [radius, dis, sublist, /SILENT, /GALACTIC, TO_B1950, /TO_J2000, COUNT= ] ) 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 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: /GALACTIC - if set, then the first two parameters are interpreted as Galactic coordinates in degrees, and is converted internally to J2000 celestial to search the database. /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. OPTIONAL KEYWORD OUTPUT: COUNT - - Integer scalar giving the number of valid matches 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. RESTRICTIONS; The database must have items 'RA' (in hours) and 'DEC' (in degrees). Alternatively, the database could have items RA_OBJ and DEC_OBJ (both in degrees) EXAMPLE: Find all Hipparcos stars within 40' of the nucleus of M33 (at J2000 1h 33m 50.9s 30d 39' 36.7'') IDL> dbopen,'hipparcos' IDL> list = dbcircle( ten(1,33,50.9), ten(3,39,36.7), 40) PROCEDURE CALLS: BPRECESS, DBFIND(), DBEXT, DB_INFO(), GCIRC, GLACTC, JPRECESS REVISION HISTORY: Written W. Landsman STX January 1990 Fixed search when crossing 0h July 1990 Spiffed up code a bit October, 1991 Leave DIS vector unchanged if no entries found W. Landsman July 1999 Use maximum declination, rather than declination at field center to correct RA for latitude effect W. Landsman September 1999 Added COUNT, GALACTIC keywords W. Landsman December 2008 Fix problem when RA range exceeds 24h W. Landsman April 2009 Work as advertised for RA_OBJ field W. Landsman June 2010 Fix occasional problem when crossing 0h E. Donoso/W.Landsman Jan 2013
(See astrolib/pro/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 astrolib/pro/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: list1 - Integer scalar giving first entry number to be compared. list2 - Integer scalar giving second entry number to be compared. OPTIONAL INPUT-OUTPUT: items - items to be compared, if not supplied then all items will be compared. The items can be 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) 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 (= default) 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 - Scalar 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 PROCEDURES USED: DB_INFO(), DB_ITEM, DB_ITEM_INFO(), DBRD, DBXVAL() TEXTOPEN, TEXTCLOSE HISTORY: Written, W. Landsman July 1996 Fix documentation, add Syntax display W. Landsman November 1998 Replace DATATYPE() with size(/TNAME) W. Landsman November 2001 Assume since V5.5, remove VMS call W. Landsman September 2006 Fix problem with multiple values when /DIFF set W. Landsman April 2007
(See astrolib/pro/dbcompare.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 in the current directory or in a ZDBASE directory. The new .dbf, .dbx and/or .dbh files will be written to the same directory. So if the .dbd file is in a ZDBASE directory, then the user must have write privilege to that directory This version allows record length to be larger than 32767 bytes CALLING SEQUENCE: dbcreate, name,[ newindex, newdb, maxitems] [,/EXTERNAL, MAXENTRY=] INPUTS: name- name of the data base (with no qualifier), scalar string. The description will be read from the file "NAME".dbd Maximum length of name is 19 characters. 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 KEYWORDS: 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. MAXENTRY - positive integer giving the maximum number of entries in the database (needed to adjust the size of the index file). This keyword can be used to supercede the #maxentries line in the .dbd file (the larger of the two numbers will be used). 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 Added new unsigned and 64 bit integer datatypes W. Landsman July 2001 Make sure to use lowercase filenames on Unix W. Landsman May 2006 Added MAXENTRY keyword W. Landsman July 2006 Assume since V5.5, remove obsolete keywords to OPEN W. Landsman Sep2006 No longer required to be a ZDBASE directory W. Landsman Feb 2008 Fix Feb 2008 bug when files are in current dir W. L. May 2008 Fix May 2008 bug when files are not in current dir (sigh) W. L. May 2008 Warn if database length exceeds 32767 bytes W.L. Dec 2009 Remove spurious warning that database name is too long W.L. April 2010 Support entry lengths larger than 32767 bytes W.L. Oct. 2010 Better testing for valid print formats W.L. Nov 2010 Fix problem where descriptions of different items could overlap E.Shaya/W.L. Oct. 2012
(See astrolib/pro/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 Don't call DBINDEX if no indexed items W. Landsman May 2006 Use TRUNCATE_LUN if V5.6 or later W. Landsman Sep 2006 Fix problem when deleting last entry W. Landsman Mar 2007 Assume since V5.6 so TRUNCATE_LUN is available W. Landsman
(See astrolib/pro/dbdelete.pro)
NAME: DBEDIT PURPOSE: Interactively edit specified fields in an IDL 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. KEYWORDS: BYTENUM = If set, treat byte variables as numbers instead of characters. 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 Replace DATAYPE() with size(/TNAME) W. Landsman November 2001 Work for entry numbers > 32767 W. Landsman December 2001 Added /BYTENUM William Thompson 13-Mar-2006 Use DIALOG_MESSAGE for error messages W. Landsman April 2006 Assume since V5.5, remove VMS support W. Landsman Sep 2006
(See astrolib/pro/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 Change DATATYPE() to size(/TNAME) W. Landsman November 2001
(See astrolib/pro/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 Avoid EXECUTE() call for V6.1 or later W. Landsman December 2006 Assume since V6.1 W. Landsman June 2009
(See astrolib/pro/dbext.pro)
NAME: DBEXT_DBF PURPOSE: Subroutine of DBEXT to extract values of up to 18 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,v13,v14,v15,v16,v17,v18 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...v18 - the vectors of values for up to 18 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 Increase maximum number of items to 18 W. Landsman November 1999 2 May 2003, W. Thompson, Use DBXVAL with BSWAP instead of IEEE_TO_HOST. Avoid EXECUTE() for V6.1 or later W. Landsman Jan 2007 Assume since V6.1 W. Landsman June 2009 Change arrays to LONG to support entries >32767 bytes WL Oct 2010
(See astrolib/pro/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 Allow multiple valued (nonstring) index items W. Landsman November 2000 Use 64bit integer index for large databases W. Landsman February 2001 Fix sublisting of multiple valued index items W. Landsman March 2001 Check whether any supplied entries are valid W. Landsman Jan 2009
(See astrolib/pro/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=, Count = ]) 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 CCYY/DAY:hr:min:sec which is interpreted as CCYY*1000+DAY+hr/24.0+min/24.0/60.+sec/24.0/3600. If a two digit year is supplied and YY GE 40 then it is understood to refer to year 1900 +YY; if YY LT 40 then it is understood to refer to year 2000 +YY For example 1985/201:10:35:30 32767 bytes W.L. Oct. 2010
(See astrolib/pro/dbfind.pro)
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, [COUNT = ] 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 OPTIONAL OUTPUT KEYWORD: Count - integer scalar giving the number of valid matches SIDE EFFECTS" The obsolete system variable !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 Added COUNT keyword, deprecate !ERR W. Landsman March 2000 Better checking of out of range values W. Landsman February 2002
(See astrolib/pro/dbfind_entry.pro)
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, [/FULLSTRING, COUNT = ] INPUT: it - item number, scalar type - type of search (output from dbfparse) svals - search values (output from dbfparse) INPUT/OUTPUT: list - found entries OPTIONAL 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. OPTIONAL OUTPUT KEYWORD Count - Integer scalar giving the number of matches found SYSTEM VARIABLES: The obsolete system variable !err is set to number of good values !ERR = -2 for an invalid search PROCEDURES CALLED: DB_INFO(), DB_ITEM_INFO(), DBSEARCH() 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 Minimize use of obsolete !ERR variable W. Landsman February 2000 Added COUNT keyword, deprecate !ERR W. Landsman March 2000 Use 64 bit integers V5.2 or later Include new IDL unsigned & 64 bit integer datatypes W.Landsman July 2001 Make sure returned list vector is LONG W. Landsman August 2001 Work on string items W. Landsman November 2009 Don't use VALUE_LOCATE on a single value W. Landsman November 2009 Use VALUE_LOCATE even for equal values W. Landsman December 2009 Fix bug allowing negative FIRST values, William Thompson, 10 May 2010
(See astrolib/pro/dbfind_sort.pro)
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 astrolib/pro/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 set, 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. OPTIONAL OUTPUT KEYWORD: COUNT - Integer scalar giving the number of valid matches 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: The obsolete system variable !ERR is set to 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 Added COUNT keyword, deprecate !ERR W. Landsman March 2000 Fix bug introduced March 2000 W. Landsman November 2000 Fix possible bug when sublist supplied W. Landsman August 2008(See astrolib/pro/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=, /SORT ] 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=0 Nowhere textout=1 if a TTY then TERMINAL using /more option otherwise standard (Unit=-1) output textout=2 if a TTY then TERMINAL without /more option otherwise standard (Unit=-1) output textout=3.prt textout=4 laser.tmp textout=5 user must open file textout=7 same as 3 but text is appended to .prt file if it already exists. textout = filename (default extension of .prt) /SORT - If set and non-zero, then the help items will be displayed sorted alphabetically. If more than one database is open, then this keyword does nothing. 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. PROCEDURES USED: DB_INFO(),DB_ITEM_INFO(),FIND_WITH_DEF(), TEXTOPEN, TEXTCLOSE, UNIQ() IDL VERSION: V5.3 or later (uses vectorized FDECOMP) 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. Added /SORT keyword J. Sandoval/W. Landsman October 1998 V5.3 version use vectorized FDECOMP W. Landsman February 2001 Recognize 64 bit, unsigned integer datatypes W. Landsman September 2001 Fix display of number of bytes with /SORT W. Landsman February 2002 Assume since V5.2 W. Landsman February 2002 Assume since V5.5 W. Landsman (See astrolib/pro/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 18 items can be indexed at one time. If the database has more than 18 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 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 Increase number of items to 18 W. Landsman November 1999 Allow multiple valued (nonstring) index items W. Landsman November 2000 Use 64 bit integers for V5.2 or later W. Landsman February 2001 Do not use EXECUTE() for V6.1 or later, improve efficiency W. Landsman December 2006 Automatically enlarge .dbx file if needed, fix major bug in last update W. Landsman Dec 2006 Assume since V6.1 W. Landsman June 2009 Allow sorted string items W. Landsman October 2009 (See astrolib/pro/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. V5.2 or later 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 Use 64 bit integer for very large databases W. Landsman February 2001 Added new unsigned & 64bit integer datatypes W. Landsman July 2001(See astrolib/pro/dbindex_blk.pro)
DBMATCH
[Previous Routine] [Next Routine] [List of Routines]NAME: DBMATCH PURPOSE: Find the entry number in a database for each element of item values EXPLANATION: DBMATCH() is especially useful for finding a one-to-one correspondence between entries in different databases, and thus to create the vector needed for database pointers. CALLING SEQUENCE: list = DBMATCH( item, values, [ listin, /FULLSTRING ] ) INPUTS: ITEM - Item name or number, scalar 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 of entry numbers with the same number of elements as VALUES. Contains a value of 0 wherever the corresponding item value was not found. OPTIONAL INPUT: /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. NOTES: DBMATCH is meant to be used for items which do not have duplicate values in a database (e.g. catalog numbers). If more than one entry is found for a particular item value, then only the first one is stored in LIST. When linked databases are opened together, DBMATCH can only be used to search on items in the primary database. EXAMPLE: Make a vector which points from entries in the Yale Bright Star catalog to those in the Hipparcos catalog, using the HD number IDL> dbopen, 'yale_bs' ;Open the Yale Bright star catalog IDL> dbext, -1, 'HD', hd ;Get the HD numbers IDL> dbopen, 'hipparcos' ;Open the Hipparcos catalog IDL> list = dbmatch( 'HD', HD) ;Get entries in Hipparcos catalog ;corresponding to each HD number. PROCEDURE CALLS: DB_ITEM, DB_ITEM_INFO(), DBEXT, DBFIND_SORT() REVISION HISTORY: Written, W. Landsman STX February, 1990 Fixed error when list in parameter used May, 1992 Faster algorithm with sorted item when listin parameter supplied Added keyword FULLSTRING,check for empty database, William Thompson, GSFC, 15 March 1995 Work for more than 32767 values, added CATCH W. Landsman July 1997 Change some loop variables to type LONG, W. Landsman July 1999 Remove loop for substring searches (faster) W. landsman August 1999 Replace DATATYPE() with size(/TNAME) W. Landsman November 2001 Fixed typo when search on sorted items W. Landsman February 2002 Fixed bug from Nov 2001 where /FULLSTRING was always set. W.L Feb 2007(See astrolib/pro/dbmatch.pro)
DBOPEN
[Previous Routine] [Next Routine] [List of Routines]NAME: DBOPEN PURPOSE: Routine to open an IDL database CALLING SEQUENCE: dbopen, name, update INPUTS: name - (Optional) name or names of the data base files to open. It has one of the following forms: 'name' -open single data base file 'name1,name2,...,nameN' - open N files which are connected via pointers. 'name,*' -Open the data base with all data bases connected via pointers '' -Interactively allow selection of the data base files. If not supplied then '' is assumed. name may optionally be a string array with one name per element. update - (Optional) Integer flag specifing openning for update. 0 - Open for read only 1 - Open for update 2 - Open index file for update only !PRIV must be 2 or greater to open a file for update. If a file is opened for update only a single data base can be specified. OUTPUTS: none INPUT-OUTPUT KEYWORD: UNAVAIL - If present, a "database doesn't exit" flag is returned through it. 0 = the database exists and was opened (if no other errors arose). 1 = the database doesn't exist. Also if present, the error message for non-existent databases is suppressed. The action, however, remains the same. SIDE EFFECTS: The .DBF and .dbx files are opened using unit numbers obtained by GET_LUN. Descriptions of the files are placed in the common block DB_COM. PROCEDURES CALLED: DBCLOSE, DB_INFO(), SELECT_W, ZPARCHECK HISTORY: For IDL Version 2 W. Landsman May 1990 -- Will require further modfication once SCREEN_SELECT is working Modified to work under Unix, D. Neill, ACC, Feb 1991. UNAVAIL keyword added. M. Greason, Hughes STX, Feb 1993. 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. 8/29/95 JKF/ACC - forces lowercase for input database names. W. Landsman, Use CATCH to catch errors July, 1997 W. Landsman Use vector call to FDECOMP, STRSPLIT() Sep 2006 W. Landsman Remove obsolete keywords to OPEN Sep 2006 Replace SCREEN_SELECT with SELECT_W, remove IEEE_TO_HOST WL Jan 2009 Fix typos in BYTEORDER introduced Jan 2009 G. Scandariato/W.L.Feb. 2009 Support new DB format which allows entry lengths > 32767 bytes W.L. October 2010 William Thompson, fixed bug opening multiple databases Dec 2010 Fix problem with external databases WL Sep 2011(See astrolib/pro/dbopen.pro)
DBPRINT
[Previous Routine] [Next Routine] [List of Routines]NAME: DBPRINT PURPOSE: Procedure to print specified items from a list of database entries CALLING SEQUENCE: dbprint, list, [items, FORMS= , TEXTOUT= , /AdjustFormat, /NoHeader] 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: /ADJUSTFORMAT - If set, then the format length for string items will be adjusted to the maximum length for the entries to be printed. This option will slow down DBPRINT because it requires the string items be extracted and their maximum length determined prior to any printing. However, it enables the display of string items without any truncation or wasted space. FORMS - The number of printed lines per page. If forms is not present, output assumed to be in PORTRAIT form, and a heading and 47 lines are printed on each page, with a page eject between each page. For LANDSCAPE form with headings on each page, and a page eject between pages, set forms = 34. For a heading only on the first page, and no page eject, set forms = 0. This is the default for output to the terminal. TEXTOUT - Integer (0-7) or string used to determine output device (see TEXTOPEN for more info). If not present, the !TEXTOUT system variable is used. textout=0 Nowhere textout=1 if a TTY then TERMINAL using /more option otherwise standard (Unit=-1) output textout=2 if a TTY then TERMINAL without /more option otherwise standard (Unit=-1) output textout=3 dbprint.prt (file) textout=4 laser.tmp textout=5 user must open file textout=7 same as 3 but text is appended to.prt textout = filename (default extension of .prt) /NOHEADER - If this keyword is set, then the column headers will not be printed EXAMPLE: The following example shows how a multiple valued item DATAMAX can be printed as separate columns. In the WFPC2 target database, DATAMAX is an item with 4 values, one for each of the 4 chips IDL> dbopen,'wflog' IDL> dbprint,list,'entry,datamax(0),datamax(1),datamax(2),datamax(3)' SYSTEM VARIABLES: Output device controlled by non-standard system varaible !TEXTOUT, if TEXTOUT keyword is not used. NOTES: Users may want to adjust the default lines_per_page value given at the beginning of the program for their own particular printer. PROCEDURE CALLS: db_info(), db_item_info(), dbtitle(), dbxval(), textopen, textclose zparcheck HISTORY: version 2 D. Lindler Nov. 1987 (new db format) Test if user pressed 'Q' in response to /MORE W. Landsman Sep 1991 Apply STRTRIM to free form (table) output W. Landsman Dec 1992 Test for string value of TEXTOUT W. Landsman Feb 1994 William Thompson, GSFC, 3 November 1994 Modified to allow ZDBASE to be a path string. W. Landsman, GSFC, July, 1997, Use CATCH to catch errors Removed STRTRIM in table format output to handle byte values April 1999 Fixed occasional problem when /NOHEADER is supplied Sep. 1999 Only byteswap when necessary for improved performance Feb. 2000 Change loop index for table listing to type LONG W. Landsman Aug 2000 Entry vector can be any integer type W. Landsman Aug. 2001 Replace DATATYPE() with size(/TNAME) W. Landsman Nov. 2001 No page eject for TEXTOUT =5 W. Landsman Nov. 2001 No initial page eject W. Landsman Jan. 2002 Added AdjustFormat keyword W. Landsman Sep. 2002 Assume since V5.3 (STRJOIN) W. Landsman Feb. 2004 Fix display on GUI terminals W. Landsman March 2006 Remove VMS statements W. Landsman Sep 2006 Remove EXECUTE statement W. Landsman Jan 2007 Fix display of multi element items W. Landsman Aug 2010 Fix problem with linked databases W. Landsman Dec 2011 (See astrolib/pro/dbprint.pro)
DBPUT
[Previous Routine] [Next Routine] [List of Routines]NAME: DBPUT PURPOSE: Procedure to place a new value for a specified item into a data base file entry. CALLING SEQUENCE: dbput, item, val, entry INPUTS: item - item name or number val - item value(s) INPUT/OUTPUT: entry - entry (byte array) or scalar entry number. if entry is a scalar entry number then the data base file will be updated. Otherwise the change will be only made to the entry array which must be written latter using DBWRT. OPERATIONAL NOTES: If entry is a scalar entry number or the input file name is supplied, the entry in the data base will be updated instead of a supplied entry variable. In this case, !priv must be greater than 1. EXAMPLE: IDL> dbput,'WAVELEN',1215.6,entry PROCEDURES USED: DB_ITEM, DBRD, DBXPUT, DBWRT HISTORY: version 2 D. Lindler Feb 1988 (new db formats) modified to convert blanks into zeros correctly D. Neill Jan 1991 Converted to IDL V5.0 W. Landsman September 1997 V5.2 version support unsigned, 64bit integers W. Landsman Sep. 2001(See astrolib/pro/dbput.pro)
DBRD
[Previous Routine] [Next Routine] [List of Routines]NAME: DBRD PURPOSE: procedure to read an entry from a data base file or from linked multiple databases. CALLING SEQUENCE: dbrd, enum, entry, [available, dbno, /NoConvert] INPUTS: enum - entry number to read, integer scalar OUTPUT: entry - byte array containing the entry OPTIONAL OUTPUT: available - byte array with length equal to number of data bases opened. available(i) eq 1 if an entry (pointed to) is available. It always equals 1 for the first data base, otherwise it is an error condition. OPTIONAL INPUT: dbno - specification of the data base number to return. If supplied, only the record for the requested data base number is returned in entry. Normally this input should not be supplied. dbno is numbered for 0 to n-1 and gives the number of the data base opened. The data bases are numbered in the order supplied to dbopen. If dbno is supplied then the entry number refers to that data base and not the primary or first data base. If set to -1, then it means all data bases opened (same as not supplying it) OPTIONAL INPUT KEYWORD: noconvert - if set then don't convert external to host format. Assumes that calling program will take care of this requirement. OPERATIONAL NOTES: If multiple data base files are opened, the records are concatenated with each other HISTORY version 2 D. Lindler Nov. 1987 William Thompson, GSFC/CDS (ARC), 1 June 1994 Added support for external (IEEE) representation. Version 3, Richard Schwartz, GSFC/SDAC, 23-Aug-1996 Add noconvert keyword Converted to IDL V5.0 W. Landsman September 1997 Version 4, 2 May 2003, W. Thompson Use BSWAP keyword to DBXVAL instead of calling IEEE_TO_HOST.(See astrolib/pro/dbrd.pro)
DBSEARCH
[Previous Routine] [Next Routine] [List of Routines]NAME: DBSEARCH PURPOSE: Subroutine of DBFIND() to search a vector for specified values CALLING SEQUENCE: dbsearch, type, svals, values, good, [ /FULLSTRING, COUNT = ] INPUT: 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 OPTIONAL 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. OPTIONAL OUTPUT KEYWORD: COUNT - Integer scalar giving the number of valid matches SIDE EFFECTS: The obsolete system variable !ERR is set to number of good values REVISION HISTORY: D. Lindler July,1987 Added COUNT keyword, deprecate !ERR W. Landsman March 2000 Some speed improvements W.L. August 2008 Add compound operators, slightly faster WL November 2009(See astrolib/pro/dbsearch.pro)
DBSORT
[Previous Routine] [Next Routine] [List of Routines]NAME: DBSORT PURPOSE: Routine to sort list of entries in data base CALLING SEQUENCE: result = dbsort( list, items , [ REVERSE = ]) INPUTS: list - list of entry numbers to sort -1 to sort all entries items - list of items to sort (up to 9 items) OUTPUT: result - numeric vector giving input list sorted by items OPTIONAL KEYWORD INPUT: REVERSE - scalar or vector with the same number of elements as the the number of items to sort. If the corresponding element of REVERSE is non-zero then that item is sorted in descending rather than ascending order. EXAMPLE: Sort an astronomical catalog with RA as primary sort, and declination as secondary sort (used when RA values are equal) IDL> NEWLIST = DBSORT( -1, 'RA,DEC' ) If for some reason, one wanted the DEC sorted in descending order, but the RA in ascending order IDL> NEWLIST = DBSORT( -1, 'RA,DEC', REV = [ 0, 1 ] ) METHOD: The list is sorted such that each item is sorted into asscending order starting with the last item. COMMON BLOCKS: DBCOM PROCEDURES USED: ZPARCHECK, BSORT, DBEXT, DB_ITEM HISTORY VERSION 1 D. Lindler Oct. 86 Added REVERSE keyword W. Landsman August, 1991 Avoid use of EXECUTE() for V6.1 or later W. Landsman Dec 2006 Assume since V6.1 W. Landsman June 2009 Add TEMPORARY call W. Lnadsman July 2009(See astrolib/pro/dbsort.pro)
DBTARGET
[Previous Routine] [Next Routine] [List of Routines]NAME: DBTARGET PURPOSE: Find sources in a database within specified radius of specified target EXPLANATION: Uses QuerySimbad to translate target name to RA and Dec, and then uses DBCIRCLE() to find any entries within specified radius. Database must include items named 'RA' (in hours) and 'DEC' (in degrees) and must have previously been opened with DBOPEN CALLING SEQUENCE: list = DBTARGET(target, [radius, sublist, /SILENT, DIS= ,/TO_B1950 ] ) INPUTS: TARGET - A scalar string giving an astronomical target name, which will be translated into J2000 celestial coordinates by QuerySimbad OPTIONAL INPUT: RADIUS - Radius of the search field in arc minutes, scalar. Default is 5 arc minutes 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 specified by the target. OPTIONAL KEYWORD INPUT: /SILENT - If this keyword is set, then DBTARGET will not print the number of entries found at the terminal /TO_B1950 - If this keyword is set, then the SIMBAD J2000 coordinates are converted to B1950 before searching the database NOTE: The user must determine on his own whether the database is in B1950 or J2000 coordinates. RESTRICTIONS; The database must have items 'RA' (in hours) and 'DEC' (in degrees). Alternatively, the database could have items RA_OBJ and DEC_OBJ (both in degrees) EXAMPLE: (1) Use the HST_CATALOG database to find all HST observations within 5' (the default) of M33 IDL> dbopen,'hst_catalog' IDL> list = dbtarget('M33') (2) As above but restrict targets within 2' of the nucleus using the WFPC2 camara IDL> dbopen,'hst_catalog' IDL> sublist = dbfind('config=WFPC2') IDL> list = dbtarget('M33',2,sublist) PROCEDURE CALLS: QuerySimbad, DBCIRCLE() REVISION HISTORY: Written W. Landsman SSAI September 2002 Propagate /SILENT keyword to QuerySimbad W. Landsman Oct 2009 Make sure a database is open W.L. Oct 2010(See astrolib/pro/dbtarget.pro)
DBTITLE
[Previous Routine] [Next Routine] [List of Routines]NAME: DBTITLE PURPOSE: function to create title line for routine dbprint CALLING SEQUENCE: result = dbtitle( c, f ) INPUTS: c = string array of titles for each item f = field length of each item OUTPUT: header string returned as function value OPERATIONAL NOTES: this is a subroutine of DBPRINT. HISTORY: version 1 D. Lindler Sept 86 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/dbtitle.pro)
DBUPDATE
[Previous Routine] [Next Routine] [List of Routines]NAME: DBUPDATE PURPOSE: Update columns of data in a database -- inverse of DBEXT EXPLANATION: Database must be open for update before calling DBUPDATE CALLING SEQUENCE: dbupdate, list, items, v1, [ v2, v3, v4......v14 ] INPUTS: list - entries in database to be updated, scalar or vector If list=-1 then all entries will be updated items -standard list of items that will be updated. v1,v2....v14 - vectors containing values for specified items. The number of vectors supplied must equal the number of items specified. The number of elements in each vector should be the same. OPTIONAL KEYWORD INPUT: /NOINDEX - If set, then DBUPDATE will not update the index file. This keyword is useful to save if additional updates will occur, and the index file need only be updated on the last call. EXAMPLES: A database STAR contains RA and DEC in radians, convert to degrees IDL> !PRIV=2 & dbopen,'STAR',1 ;Open database for update IDL> dbext,-1,'RA,DEC',ra,dec ;Extract RA and DEC, all entries IDL> ra = ra*!RADEG & dec=dec*!RADEG ;Convert to degrees IDL> dbupdate,-1,'RA,DEC',ra,dec ;Update database with new values NOTES: It is quicker to update several items simultaneously rather than use repeated calls to DBUPDATE. It is possible to update multiple valued items. In this case, the input vector should be of dimension (NVAL,NLIST) where NVAL is the number of values per item, and NLIST is the number of entries to be updated. This vector will be temporarily transposed by DBUPDATE but will be restored before DBUPDATE exits. REVISION HISTORY Written W. Landsman STX March, 1989 Work for multiple valued items May, 1991 String arrays no longer need to be fixed length December 1992 Transpose multiple array items back on output December 1993 Faster update of external databases on big endian machines November 1997 Converted to IDL V5.0 W. Landsman 24-Nov-1997 Added /NOINDEX keyword W. Landsman July 2001(See astrolib/pro/dbupdate.pro)
DBVAL
[Previous Routine] [Next Routine] [List of Routines]NAME: DBVAL PURPOSE: procedure to extract value(s) of the specified item from a data base file entry. CALLING SEQUENCE: result = dbval( entry, item ) INPUTS: entry - byte array containing the entry, or a scalar entry number item - name (string) or number (integer) of the item OUTPUT: the value(s) will be returned as the function value EXAMPLE: Extract a flux vector from entry 28 of the database FARUV ==> flux = dbval(28,'FLUX') HISTORY: version 2 D. Lindler Nov, 1987 (new db format) Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/dbval.pro)
DBWRT
[Previous Routine] [Next Routine] [List of Routines]NAME: DBWRT PURPOSE: procedure to update or add a new entry to a data base CALLING SEQUENCE: dbwrt, entry, [ index, append, /NoConvert ] INPUTS: entry - entry record to be updated or added if first item (entry number=0) OPTIONAL INPUTS: index - optional integer flag, if set to non zero then index file is updated. (default=0, do not update index file) (Updating the index file is time-consuming, and should normally be done after all changes have been made. append - optional integer flag, if set to non-zero the record is appended as a new entry, regardless of what the entry number in the record is. The entry number will be reset to the next entry number in the file. OUTPUTS: data base file is updated. If index is non-zero then the index file is updated. OPTIONAL INPUT KEYWORD: NoConvert - If set then don't convert to host format with an external database. Useful when the calling program decides that conversion isn't needed (i.e. on a big-endian machine), or takes care of the conversion itself. OPERATIONAL NOTES: !PRIV must be greater than 1 to execute HISTORY: version 2 D. Lindler Feb. 1988 (new db format) converted to IDL Version 2. M. Greason, STX, June 1990. William Thompson, GSFC/CDS (ARC), 28 May 1994 Added support for external (IEEE) representation. Faster handling of byte swapping W. L. August 2010(See astrolib/pro/dbwrt.pro)
DBXPUT
[Previous Routine] [Next Routine] [List of Routines]NAME: DBXPUT PURPOSE: routine to replace value of an item in a data base entry CALLING SEQUENCE: dbxput, val, entry, idltype, sbyte, nbytes INPUT: val - value(s) to be placed into entry, string values might be truncated to fit number of allowed bytes in item entry - entry or entries to be updated idltype - idl data type for item (1-7) sbyte - starting byte in record nbytes - total number of bytes in value added OUTPUT: entry - (updated) OPERATIONAL NOTES: This routine assumes that the calling procedure or user knows what he or she is doing. String items are truncated or padded to the fixed size specified by the database but otherwise no validity checks are made. HISTORY: version 1, D. Lindler Aug, 1986 converted to IDL Version 2. M. Greason, STX, June 1990. Work with multiple element string items W. Landsman August 1995 Really work with multiple element string items R. Bergman/W. Landsman July 1996 Work with multiple entries, R. Schwartz, GSFC/SDAC August 1996 Use /overwrite with REFORM() W. Landsman May 1997 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/dbxput.pro)
DBXVAL
[Previous Routine] [Next Routine] [List of Routines]NAME: DBXVAL PURPOSE: Quickly return a value of the specified item number EXPLANATION: Procedure to quickly return a value of the specified item number from the entry. CALLING SEQUENCE: result = dbxval( entry, idltype, nvalues, sbyte, nbytes ) INPUTS entry - entry or entries from data base (bytarr) idltype - idl data type (obtained with db_item_info) nvalues - number of values to return (obtained with db_item) sbyte - starting byte in the entry (obtained with db_item) nbytes - number of bytes (needed only for string type) (obtained with db_item) OUTPUTS: function value is value of the specified item in entry KEYWORDS: bswap - If set, then IEEE_TO_HOST is called. RESTRICTIONS: To increase speed the routine assumes that entry and item are valid and that the data base is already opened using dbopen. REVISION HISTORY: version 0 D. Lindler Nov. 1987 (for new db format) Version 1, William Thompson, GSFC, 28 March 1994. Incorporated into CDS library. Version 2, Richard Schwartz, GSFC/SDAC, 23 August 1996 Allowed Entry to have 2 dimensions Version 2.1, 22 Feb 1997, JK Feggans, avoid reform for strings arrays. Version 2.2 Use overwrite with REFORM(), W. Landsman, May 1997 Converted to IDL V5.0 W. Landsman September 1997 Work for multiple-valued strings W. Landsman October 2000 Add new 64bit & unsigned integer datatypes W.Landsman July 2001 Version 3, 2-May-2003, JK Feggans/Sigma, W.T. Thompson Added BSWAP keyword to avoid floating errors on some platforms.(See astrolib/pro/dbxval.pro)
DB_ENT2EXT
[Previous Routine] [Next Routine] [List of Routines]NAME: DB_ENT2EXT PURPOSE: Convert a database entry to external (IEEE) data format EXPLANATION: Converts a database entry to external (IEEE) data format prior to writing it. Called from DBWRT. CALLING SEQUENCE: DB_ENT2EXT, ENTRY INPUTS: ENTRY = Byte array containing a single record to be written to the database file. OUTPUTS: ENTRY = The converted array is returned in place of the input array. COMMON BLOCKS: DB_COM HISTORY: Version 1, William Thompson, GSFC/CDS (ARC), 1 June 1994 Version 2, William Thompson, GSFC/CDS (ARC), 15 September 1995 Fixed bug where only the first element in a multidimensional array was converted. Version 2.1 W. Landsman August 2010 Fix for multidimensional strings Version 2.2 W. Landsman Sep 2011 Work with new DB format(See astrolib/pro/db_ent2ext.pro)
DB_ENT2HOST
[Previous Routine] [Next Routine] [List of Routines]NAME: DB_ENT2HOST PURPOSE: Converts a database entry from external data format to host format. EXPLANATION: All items are extracted from the entry, and then converted to host format, and placed back into the entry. Called from DBRD and DBEXT_DBF. CALLING SEQUENCE: DB_ENT2HOST, ENTRY, DBNO INPUTS: ENTRY = Byte array containing a single record read from the database file. DBNO = Number of the opened database file. OUTPUTS: ENTRY = The converted array is returned in place of the input array. COMMON BLOCKS: DB_COM HISTORY: Version 1, William Thompson, GSFC/CDS (ARC), 1 June 1994 Version 2, William Thompson, GSFC/CDS (ARC), 15 September 1995 Fixed bug where only the first element in a multidimensional array was converted. Version 3, Richard Schwartz, GSFC/SDAC, 23 August 1996 Allow 2 dimensional byte arrays for entries to facilitate multiple entry processing. Pass IDLTYPE onto IEEE_TO_HOST Version 4, 2 May 2003, W. Thompson Use BSWAP keyword to DBXVAL instead of calling IEEE_TO_HOST. Version 4.1 W. Landsman August 2010 Fix for multidimensional strings Version 4.2 W. Landsman Sep 2011 Work with new DB format(See astrolib/pro/db_ent2host.pro)
DB_INFO
[Previous Routine] [Next Routine] [List of Routines]NAME: DB_INFO PURPOSE: Function to obtain information on opened data base file(s) CALLING SEQUENCES: 1) result = db_info(request) 2) result = db_info(request,dbname) INPUTS (calling sequence 1): request - string specifying requested value(s) value of request value returned in result 'open' Flag set to 1 if data base(s) are opened 'number' Number of data base files opened 'items' Total number of items (all db's opened) 'update' update flag (1 if opened for update) 'unit_dbf' Unit number of the .dbf files 'unit_dbx' Unit number of the .dbx files 'entries' Number of entries in the db's 'length' Record lengths for the db's 'external' True if the db's are in external format INPUTS (calling sequence 2): request - string specifying requested value(s) value of request value returned in result 'name' Name of the data base 'number' Sequential number of the db 'items' Number of items for this db 'item1' Position of item1 for this db in item list for all db's 'item2' Position of last item for this db. 'pointer' Number of the item which points to this db. 0 for first or primary db. -1 if link file pointers. 'length' Record length for this db. 'title' Title of the data base 'unit_dbf' Unit number of the .dbf file 'unit_dbx' Unit number of the .dbx file 'entries' Number of entries in the db 'seqnum' Last sequence number used 'alloc' Allocated space (# entries) 'update' 1 if data base opened for update 'external' True if data base in external format 'newdb' True if new (post Oct 2010) format that allows entries > 32767 bytes dbname - data base name or number OUTPUTS: Requested value(s) are returned as the function value. HISTORY: version 1 D. Lindler Oct. 1987 changed type from 1 to 7 for IDLV2, J. Isensee, Nov., 1990 William Thompson, GSFC/CDS (ARC), 30 May 1994 Added EXTERNAL request type. Support new DB format, add NEWDB request type W. Landsman Oct 2010(See astrolib/pro/db_info.pro)
DB_ITEM
[Previous Routine] [Next Routine] [List of Routines]NAME: DB_ITEM PURPOSE: Returns the item numbers and other info. for an item name. EXPLANATION: Procedure to return the item numbers and other information of a specified item name CALLING SEQUENCE: db_item, items, itnum, ivalnum, idltype, sbyte, numvals, nbytes INPUTS: items - item name or number 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 Upon return items will contain selected items in form 1 form 6 '*' select all items OUTPUTS: itnum - item number ivalnum - value(s) number from multiple valued item idltype - data type(s) (1=string,2=byte,4=i*4,...) sbyte - starting byte(s) in entry numvals - number of data values for item(s) It is the full length of a vector item unless a subscript was supplied nbytes - number of bytes for each value All outputs are vectors even if a single item is requested OPTIONAL INPUT KEYWORDS: ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' DB_ITEM, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... PROCEDURE CALLS: DB_INFO, GETTOK, SELECT_W REVISION HISTORY: Written: D. Lindler, GSFC/HRS, October 1987 Version 2, William Thompson, GSFC, 17-Mar-1997 Added keyword ERRMSG Use STRSPLIT instead of GETTOK to parse form 1, W. Landsman July 2002 Assume since V5.4 use FILE_EXPAND_PATH() instead of SPEC_DIR() W. Landsman April 2006 Support new DB format allowing entry lengths > 32767 bytes WL Oct 2010 Ignore blank lines in .items file WL February 2011(See astrolib/pro/db_item.pro)
DB_ITEM_INFO
[Previous Routine] [Next Routine] [List of Routines]NAME: DB_ITEM_INFO PURPOSE: routine to return information on selected item(s) in the opened data bases. CALLING SEQUENCE: result = db_item_info( request, itnums) INPUTS: request - string giving the requested information. 'name' - item names 'idltype' - IDL data type (integers) see documentation of intrinsic SIZE funtion 'nvalues' - vector item length (1 for scalar) 'sbyte' - starting byte in .dbf record (use bytepos to get starting byte in record returned by dbrd) 'nbytes' - bytes per data value 'index' - index types 'description' - description of the item 'pflag' - pointer item flags 'pointer' - data bases the items point to 'format' - print formats 'flen' - print field length 'headers' - print headers 'bytepos' - starting byte in dbrd record for the items 'dbnumber' - number of the opened data base 'pnumber' - number of db it points to (if the db is opened) 'itemnumber' - item number in the file itnums -(optional) Item numbers. If not supplied info on all items are returned. OUTPUT: Requested information is returned as a vector. Its type depends on the item requested. HISTORY: version 1 D. Lindler Nov. 1987 Converted to IDL V5.0 W. Landsman September 1997 Support new DB format which allows > 32767 bytes W.L. Oct 2010(See astrolib/pro/db_item_info.pro)
DB_OR
[Previous Routine] [Next Routine] [List of Routines]NAME: DB_OR PURPOSE: Combine two vectors of entry numbers, removing duplicate values. EXPLANATION: DB_OR can also be used to remove duplicate values from any longword vector CALLING SEQUENCE: LIST = DB_OR( LIST1 ) ;Remove duplicate values from LIST1 or LIST = DB_OR( LIST1, LIST2 ) ;Concatenate LIST1 and LIST2, remove dups INPUTS: LIST1, LIST2 - Vectors containing entry numbers, must be non-negative integers or longwords. OUTPUT: LIST - Vector containing entry numbers in either LIST1 or LIST2 METHOD DB_OR returns where the histogram of the entry vectors is non-zero PROCEDURE CALLS ZPARCHECK - checks parameters REVISION HISTORY: Written, W. Landsman February, 1989 Check for degenerate values W.L. February, 1993 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/db_or.pro)
DB_TITLES
[Previous Routine] [Next Routine] [List of Routines]NAME: DB_TITLES PURPOSE: Print database name and title. Called by DBHELP CALLING SEQUENCE: db_titles, fnames, titles INPUT: fnames - string array of data base names SIDE EFFECT: Database name is printed along with the description in the .dbh file HISTORY: version 2 W. Landsman May, 1989 modified to work under 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. Converted to IDL V5.0 W. Landsman September 1997 Assume since V5.5, W. Landsman September 2006(See astrolib/pro/db_titles.pro)
DELVARX
[Previous Routine] [Next Routine] [List of Routines]NAME: DELVARX PURPOSE: Delete up to 10 variables for memory management (can call from routines) EXPLANATION: Like intrinsic DELVAR function, but can be used from any calling level Modified in January 2012 to always free memory associated with pointers/objects and remove the use of EXECUTE() Also look at CALLING SEQUENCE: DELVARX, p0, [p1, p2......p9] INPUTS: p0, p1...p9 - variables to delete OBSOLETE KEYWORD: /FREE_MEM - formerly freed memory associated with pointers and objects. Since this is now the DELVARX default this keyword does nothing. METHOD: Uses HEAP_FREE and PTR_NEW(/NO_COPY) to delete variables and free memory REVISION HISTORY: Copied from the Solar library, written by slf, 25-Feb-1993 Added to Astronomy Library, September 1995 Modified, 26-Mar-2003, Zarro (EER/GSFC) 26-Mar-2003 - added FREE_MEM to free pointer/objects Modified, 28-Jan-2012, E. Rykoff (SLAC), W. Landsman - replace EXECUTE calls with SCOPE_VARFETCH.(See astrolib/pro/delvarx.pro)
DEREDD
[Previous Routine] [Next Routine] [List of Routines]NAME: DEREDD PURPOSE: Deredden stellar Stromgren parameters given for a value of E(b-y) EXPLANATION: See the procedure UVBYBETA for more info. CALLING SEQUENCE: deredd, eby, by, m1, c1, ub, by0, m0, c0, ub0, /UPDATE INPUTS: Eby - color index E(b-y),scalar (E(b-y) = 0.73*E(B-V) ) by - b-y color (observed) m1 - Stromgren line blanketing parameter (observed) c1 - Stromgren Balmer discontinuity parameter (observed) ub - u-b color (observed) These input values are unaltered unless the /UPDATE keyword is set OUTPUTS: by0 - b-y color (dereddened) m0 - Line blanketing index (dereddened) c0 - Balmer discontinuity parameter (dereddened) ub0 - u-b color (dereddened) OPTIONAL INPUT KEYWORDS: /UPDATE - If set, then input parameters are updated with the dereddened values (and output parameters are not used). REVISION HISTORY: Adapted from FORTRAN routine DEREDD by T.T. Moon W. Landsman STX Co. April, 1988 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/deredd.pro)
DETABIFY
[Previous Routine] [Next Routine] [List of Routines]NAME: DETABIFY PURPOSE: Replaces tabs in character strings with appropriate number of spaces EXPLANATION: The number of space characters inserted is calculated to space out to the next effective tab stop, each of which is eight characters apart. CALLING SEQUENCE: Result = DETABIFY( CHAR_STR ) INPUT PARAMETERS: CHAR_STR = Character string variable (or array) to remove tabs from. OUTPUT: Result of function is CHAR_STR with tabs replaced by spaces. RESTRICTIONS: CHAR_STR must be a character string variable. MODIFICATION HISTORY: William Thompson, Feb. 1992. Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/detabify.pro)
DIST_CIRCLE
[Previous Routine] [Next Routine] [List of Routines]NAME: DIST_CIRCLE PURPOSE: Form a square array where each value is its distance to a given center. EXPLANATION: Returns a square array in which the value of each element is its distance to a specified center. Useful for circular aperture photometry. CALLING SEQUENCE: DIST_CIRCLE, IM, N, [ XCEN, YCEN, /DOUBLE ] INPUTS: N = either a scalar specifying the size of the N x N square output array, or a 2 element vector specifying the size of the N x M rectangular output array. OPTIONAL INPUTS: XCEN,YCEN = Scalars designating the X,Y pixel center. These need not be integers, and need not be located within the output image. If not supplied then the center of the output image is used (XCEN = YCEN = (N-1)/2.). OUTPUTS: IM - N by N (or M x N) floating array in which the value of each pixel is equal to its distance to XCEN,YCEN OPTIONAL INPUT KEYWORD: /DOUBLE - If this keyword is set and nonzero, the output array will be of type DOUBLE rather than floating point. EXAMPLE: Total the flux in a circular aperture within 3' of a specified RA and DEC on an 512 x 512 image IM, with a header H. IDL> adxy, H, RA, DEC, x, y ;Convert RA and DEC to X,Y IDL> getrot, H, rot, cdelt ;CDELT gives plate scale deg/pixel IDL> cdelt = cdelt*3600. ;Convert to arc sec/pixel IDL> dist_circle, circle, 512, x, y ;Create a distance circle image IDL> circle = circle*abs(cdelt[0]) ;Distances now given in arcseconds IDL> good = where(circle LT 180) ;Within 3 arc minutes IDL> print,total( IM[good] ) ;Total pixel values within 3' RESTRICTIONS: The speed of DIST_CIRCLE decreases and the the demands on virtual increase as the square of the output dimensions. Users should dimension the output array as small as possible, and re-use the array rather than re-calling DIST_CIRCLE MODIFICATION HISTORY: Adapted from DIST W. Landsman March 1991 Allow a rectangular output array W. Landsman June 1994 Converted to IDL V5.0 W. Landsman September 1997 Add /DOUBLE keyword, make XCEN,YCEN optional W. Landsman Jun 1998(See astrolib/pro/dist_circle.pro)
DIST_ELLIPSE
[Previous Routine] [Next Routine] [List of Routines]NAME: DIST_ELLIPSE PURPOSE: Create a mask array useful for elliptical aperture photemetry EXPLANATION: Form an array in which the value of each element is equal to the semi-major axis of the ellipse of specified center, axial ratio, and position angle, which passes through that element. Useful for elliptical aperture photometry. CALLING SEQUENCE: DIST_ELLIPSE, IM, N, XC, YC, RATIO, POS_ANG, /DOUBLE INPUTS: N = either a scalar specifying the size of the N x N square output array, or a 2 element vector specifying the size of the M x N rectangular output array. XC,YC - Scalars giving the position of the ellipse center. This does not necessarily have to be within the image RATIO - Scalar giving the ratio of the major to minor axis. This should be greater than 1 for postion angle to have its standard meaning. OPTIONAL INPUTS: POS_ANG - Position angle of the major axis, measured counter-clockwise from the Y axis. For an image in standard orientation (North up, East left) this is the astronomical position angle. OPTIONAL INPUT KEYWORD: /DOUBLE - If this keyword is set and nonzero, the output array will be of type DOUBLE rather than floating point. OUTPUT: IM - REAL*4 elliptical mask array, of size M x N. THe value of each pixel is equal to the semi-major axis of the ellipse of center XC,YC, axial ratio RATIO, and position angle POS_ANG, which passes through the pixel. EXAMPLE: Total the flux in a elliptical aperture with a major axis of 3', an axial ratio of 2.3, and a position angle of 25 degrees centered on a specified RA and DEC. The image array, IM is 200 x 200, and has an associated FITS header H. ADXY, H, ra, dec, x, y ;Get X and Y corresponding to RA and Dec GETROT, H, rot, cdelt ;CDELT gives plate scale degrees/pixel cdelt = abs( cdelt)*3600. ;CDELT now in arc seconds/pixel DIST_ELLIPSE, ell, 200, x, y, 2.3, 25 ;Create a elliptical image mask ell = ell*cdelt(0) ;Distances now given in arcseconds good = where( ell lt 180 ) ;Within 3 arc minutes print,total( im(good) ) ;Total pixel values within 3' RESTRICTIONS: The speed of DIST_ELLIPSE decreases and the the demands on virtual increase as the square of the output dimensions. Users should dimension the output array as small as possible, and re-use the array rather than re-calling DIST_ELLIPSE REVISION HISTORY: Written W. Landsman April, 1991 Somewhat faster algorithm August, 1992 Allow rectangular output array June, 1994 Converted to IDL V5.0 W. Landsman September 1997 Added /DOUBLE keyword W. Landsman July 2000(See astrolib/pro/dist_ellipse.pro)
ECI2GEO
[Previous Routine] [Next Routine] [List of Routines]NAME: ECI2GEO PURPOSE: Convert Earth-centered inertial coordinates to geographic spherical coords EXPLANATION: Converts from ECI (Earth-Centered Inertial) (X,Y,Z) rectangular coordinates to geographic spherical coordinates (latitude, longitude, altitude). JD time is also needed as input. ECI coordinates are in km from Earth center. Geographic coordinates are in degrees/degrees/km Geographic coordinates assume the Earth is a perfect sphere, with radius equal to its equatorial radius. CALLING SEQUENCE: gcoord=eci2geo(ECI_XYZ,JDtime) INPUT: ECI_XYZ : the ECI [X,Y,Z] coordinates (in km), can be an array [3,n] of n such coordinates. JDtime: the Julian Day time, double precision. Can be a 1-D array of n such times. KEYWORD INPUTS: None OUTPUT: a 3-element array of geographic [latitude,longitude,altitude], or an array [3,n] of n such coordinates, double precision COMMON BLOCKS: None PROCEDURES USED: CT2LST - Convert Local Civil Time to Local Mean Sidereal Time EXAMPLE: IDL> gcoord=eci2geo([6378.137+600,0,0], 2452343.38982663D) IDL> print,gcoord 0.0000000 232.27096 600.00000 (The above is the geographic direction of the vernal point on 2002/03/09 21:21:21.021, in geographic coordinates. The chosen altitude was 600 km.) gcoord can be further transformed into geodetic coordinates (using geo2geodetic.pro) or into geomagnetic coordinates (using geo2mag.pro) MODIFICATION HISTORY: Written by Pascal Saint-Hilaire (Saint-Hilaire@astro.phys.ethz.ch) on 2001/05/13 Modified on 2002/05/13, PSH : vectorization + use of JD times(See astrolib/pro/eci2geo.pro)
EQ2HOR
[Previous Routine] [Next Routine] [List of Routines]NAME: EQ2HOR PURPOSE: Convert celestial (ra-dec) coords to local horizon coords (alt-az). CALLING SEQUENCE: eq2hor, ra, dec, jd, alt, az, [ha, LAT= , LON= , /WS, OBSNAME= , $ /B1950 , PRECESS_= 0, NUTATE_= 0, REFRACT_= 0, $ ABERRATION_= 0, ALTITUDE= , /VERBOSE, _EXTRA= ] DESCRIPTION: This code calculates horizon (alt,az) coordinates from equatorial (ra,dec) coords. It is typically accurate to about 1 arcsecond or better (I have checked the output against the publicly available XEPHEM software). It performs precession, nutation, aberration, and refraction corrections. The perhaps best thing about it is that it can take arrays as inputs, in all variables and keywords EXCEPT Lat, lon, and Altitude (the code assumes these aren't changing), and uses vector arithmetic in every calculation except when calculating the precession matrices. INPUT VARIABLES: RA : Right Ascension of object (J2000) in degrees (FK5); scalar or vector. Dec : Declination of object (J2000) in degrees (FK5), scalar or vector. JD : Julian Date [scalar or vector] Note: if RA and DEC are arrays, then alt and az will also be arrays. If RA and DEC are arrays, JD may be a scalar OR an array of the same dimensionality. OPTIONAL INPUT KEYWORDS: lat : north geodetic latitude of location in degrees lon : EAST longitude of location in degrees (Specify west longitude with a negative sign.) /WS : Set this to get the azimuth measured westward from south (not East of North). obsname: Set this to a valid observatory name to be used by the astrolib OBSERVATORY procedure, which will return the latitude and longitude to be used by this program. /B1950 : Set this if your ra and dec are specified in B1950, FK4 coordinates (instead of J2000, FK5) precess_ : Set this to 1 to force precession [default], 0 for no precession correction nutate_ : Set this to 1 to force nutation [default], 0 for no nutation. aberration_ : Set this to 1 to force aberration correction [default], 0 for no correction. refract_ : Set to 1 to force refraction correction [default], 0 for no correction. altitude: The altitude of the observing location, in meters. [default=0]. verbose: Set this for verbose output. The default is verbose=0. _extra: This is for setting TEMPERATURE or PRESSURE explicitly, which are used by CO_REFRACT to calculate the refraction effect of the atmosphere. If you don't set these, the program will make an intelligent guess as to what they are (taking into account your altitude). See CO_REFRACT for more details. OUTPUT VARIABLES: (all double precision) alt : altitude (in degrees) az : azimuth angle (in degrees, measured EAST from NORTH, but see keyword WS above.) ha : hour angle (in degrees) (optional) DEPENDENCIES: NUTATE, PRECESS, OBSERVATORY, SUNPOS, ADSTRING() CO_NUTATE, CO_ABERRATION, CO_REFRACT, ALTAZ2HADEC, SETDEFAULTVALUE BASIC STEPS Apply refraction correction to find apparent Alt. Calculate Local Mean Sidereal Time Calculate Local Apparent Sidereal Time Do Spherical Trig to find apparent hour angle, declination. Calculate Right Ascension from hour angle and local sidereal time. Nutation Correction to Ra-Dec Aberration correction to Ra-Dec Precess Ra-Dec to current equinox. CORRECTIONS I DO NOT MAKE: * Deflection of Light by the sun due to GR. (typically milliarcseconds, can be arseconds within one degree of the sun) * The Effect of Annual Parallax (typically < 1 arcsecond) * and more (see below) TO DO * Better Refraction Correction. Need to put in wavelength dependence, and integrate through the atmosphere. * Topocentric Parallax Correction (will take into account elevation of the observatory) * Proper Motion (but this will require crazy lookup tables or something). * Difference between UTC and UT1 in determining LAST -- is this important? * Effect of Annual Parallax (is this the same as topocentric Parallax?) * Polar Motion * Better connection to Julian Date Calculator. EXAMPLE Find the position of the open cluster NGC 2264 at the Effelsburg Radio Telescope in Germany, on June 11, 2023, at local time 22:00 (METDST). The inputs will then be: Julian Date = 2460107.250 Latitude = 50d 31m 36s Longitude = 06h 51m 18s Altitude = 369 meters RA (J2000) = 06h 40m 58.2s Dec(J2000) = 09d 53m 44.0s IDL> eq2hor, ten(6,40,58.2)*15., ten(9,53,44), 2460107.250d, alt, az, $ lat=ten(50,31,36), lon=ten(6,51,18), altitude=369.0, /verb, $ pres=980.0, temp=283.0 The program produces this output (because the VERBOSE keyword was set) Latitude = +50 31 36.0 Longitude = +06 51 18.0 Julian Date = 2460107.250000 Ra, Dec: 06 40 58.2 +09 53 44.0 (J2000) Ra, Dec: 06 42 15.7 +09 52 19.2 (J2023.4422) Ra, Dec: 06 42 13.8 +09 52 26.9 (fully corrected) LMST = +11 46 42.0 LAST = +11 46 41.4 Hour Angle = +05 04 27.6 (hh:mm:ss) Az, El = 17 42 25.6 +16 25 10.3 (Apparent Coords) Az, El = 17 42 25.6 +16 28 22.8 (Observer Coords) Compare this with the result from XEPHEM: Az, El = 17h 42m 25.6s +16d 28m 21s This 1.8 arcsecond discrepancy in elevation arises primarily from slight differences in the way I calculate the refraction correction from XEPHEM, and is pretty typical. AUTHOR: Chris O'Dell Univ. of Wisconsin-Madison Observational Cosmology Laboratory Email: odell@cmb.physics.wisc.edu Revision History: August 2012 Use Strict_Extra to flag spurious keywords W. Landsman(See astrolib/pro/eq2hor.pro)
EQPOLE
[Previous Routine] [Next Routine] [List of Routines]NAME: EQPOLE PURPOSE: Convert RA and Dec to X,Y using an equal-area polar projection. EXPLANATION: The output X and Y coordinates are scaled to be between -90 and +90 to go from equator to pole to equator. Output map points can be centered on the north pole or south pole. CALLING SEQUENCE: EQPOLE, L, B, X, Y, [ /SOUTHPOLE ] INPUTS: L - longitude - scalar or vector, in degrees B - latitude - same number of elements as RA, in degrees OUTPUTS: X - X coordinate, same number of elements as RA. X is normalized to be between -90 and 90. Y - Y coordinate, same number of elements as DEC. Y is normalized to be between -90 and 90. KEYWORDS: /SOUTHPOLE - Keyword to indicate that the plot is to be centered on the south pole instead of the north pole. REVISION HISTORY: J. Bloch LANL, SST-9 1.1 5/16/91 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/eqpole.pro)
EQPOLE_GRID
[Previous Routine] [Next Routine] [List of Routines]NAME: EQPOLE_GRID PURPOSE: Produce an equal area polar projection grid overlay EXPLANATION: Grid is written on the current graphics device using the equal area polar projection. EQPOLE_GRID assumes that the output plot coordinates span the x and y ranges of -90 to 90 for a region that covers the equator to the chosen pole. The grid is assumed to go from the equator to the chosen pole. CALLING SEQUENCE: EQPOLE_GRID[,DLONG,DLAT,[/SOUTHPOLE, LABEL = , /NEW, _EXTRA=] 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. INPUT KEYWORDS: /SOUTHPOLE = Optional flag indicating that the output plot is to be centered on the south rather than the north pole. LABEL = Optional flag for creating labels on the output grid on the prime meridian and the equator for lattitude and longitude lines. If set =2, then the longitude lines are labeled in hours and minutes. CHARSIZE = If /LABEL is set, then CHARSIZE specifies the size of the label characters (passed to XYOUTS) CHARTHICK = If /LABEL is set, then CHARTHICK specifies the thickness of the label characters (passed to XYOUTS) /NEW = If this keyword is set, then EQPOLE_GRID will create a new plot, rather than overlay an existing plot. Any valid keyword to OPLOT such as COLOR, LINESTYLE, THICK can be passed to AITOFF_GRID (though the _EXTRA facility) to to specify the color, style, or thickness of the grid lines. OUTPUTS: Draws grid lines on current graphics device. EXAMPLE: Create a labeled equal area projection grid of the Galaxy, centered on the South pole, and overlay stars at specified Galactic longitudes, glong and latitudes, glat IDL> eqpole_grid,/label,/new,/south ;Create labeled grid IDL> eqpole, glong, glat, x,y ;Convert to X,Y coordinates IDL> plots,x,y,psym=2 ;Overplot "star" positions. COPYRIGHT NOTICE: Copyright 1992, The Regents of the University of California. This software was produced under U.S. Government contract (W-7405-ENG-36) by Los Alamos National Laboratory, which is operated by the University of California for the U.S. Department of Energy. The U.S. Government is licensed to use, reproduce, and distribute this software. Neither the Government nor the University makes any warranty, express or implied, or assumes any liability or responsibility for the use of this software. AUTHOR AND MODIFICATIONS: J. Bloch 1.4 10/28/92 Converted to IDL V5.0 W. Landsman September 1997 Create default plotting coords, if needed W. Landsman August 2000 Added _EXTRA, CHARTHICK, CHARSIZE keywords W. Landsman March 2001(See astrolib/pro/eqpole_grid.pro)
EULER
[Previous Routine] [Next Routine] [List of Routines]NAME: EULER PURPOSE: Transform between Galactic, celestial, and ecliptic coordinates. EXPLANATION: Use the procedure ASTRO to use this routine interactively CALLING SEQUENCE: EULER, AI, BI, AO, BO, [ SELECT, /FK4, /RADIAN, SELECT = ] INPUTS: AI - Input Longitude, scalar or vector. In DEGREES unless /RADIAN is set. If only two parameters are supplied, then AI and BI will be modified to contain the output longitude and latitude. BI - Input Latitude in DEGREES OPTIONAL INPUT: SELECT - Integer (1-6) specifying type of coordinate transformation. SELECT From To | SELECT From To 1 RA-Dec (2000) Galactic | 4 Ecliptic RA-Dec 2 Galactic RA-DEC | 5 Ecliptic Galactic 3 RA-Dec Ecliptic | 6 Galactic Ecliptic If not supplied as a parameter or keyword, then EULER will prompt for the value of SELECT Celestial coordinates (RA, Dec) should be given in equinox J2000 unless the /FK4 keyword is set. OUTPUTS: AO - Output Longitude in DEGREES, always double precision BO - Output Latitude in DEGREES, always double precision OPTIONAL INPUT KEYWORD: /FK4 - If this keyword is set and non-zero, then input and output celestial and ecliptic coordinates should be given in equinox B1950. /RADIAN - if set, then all input and output angles are in radians rather than degrees. SELECT - The coordinate conversion integer (1-6) may alternatively be specified as a keyword EXAMPLE: Find the Galactic coordinates of Cyg X-1 (ra=299.590315, dec=35.201604) IDL> ra = 299.590315d IDL> dec = 35.201604d IDL> euler,ra,dec,glong,glat,1 & print,glong,glat 71.334990, 3.0668335 REVISION HISTORY: Written W. Landsman, February 1987 Adapted from Fortran by Daryl Yentis NRL Made J2000 the default, added /FK4 keyword W. Landsman December 1998 Add option to specify SELECT as a keyword W. Landsman March 2003 Use less virtual memory for large input arrays W. Landsman June 2008 Added /RADIAN input keyword W. Landsman Sep 2008(See astrolib/pro/euler.pro)
EXPAND_TILDE()
[Previous Routine] [Next Routine] [List of Routines]NAME: EXPAND_TILDE() PURPOSE: Expand tilde in UNIX directory names CALLING SEQUENCE: IDL> output=expand_tilde(input) INPUTS: INPUT = input file or directory name, scalar string OUTPUT: Returns expanded filename, scalar string EXAMPLES: output=expand_tilde('~zarro/test.doc') ---> output='/usr/users/zarro' NOTES: This version of EXPAND_TILDE differs from the version in the Solar Library in that it does not call the functions EXIST and IDL_RELEASE. However, it should work identically. PROCEDURE CALLS: None. REVISION HISTORY: Version 1, 17-Feb-1997, D M Zarro. Written Transfered from Solar Library W. Landsman Sep. 1997 Made more robust D. Zarro/W. Landsman Sep. 2000 Made even more robust (since things like ~zarro weren't being expanded) Zarro (EITI/GSFC, Mar 2001)(See astrolib/pro/expand_tilde.pro)
EXTAST
[Previous Routine] [Next Routine] [List of Routines]NAME: EXTAST PURPOSE: Extract ASTrometry parameters from a FITS image header. EXPLANATION: Extract World Coordinate System information ( http://fits.gsfc.nasa.gov/fits_wcs.html ) from a FITS header and place it into an IDL structure. CALLING SEQUENCE: EXTAST, hdr, [ astr, noparams, ALT= ] INPUT: HDR - variable containing the FITS header (string array) OUTPUTS: ASTR - Anonymous structure containing astrometry info from the FITS header ASTR always contains the following tags (even though some projections do not require all the parameters) .NAXIS - 2 element array giving image size .CD - 2 x 2 array containing the astrometry parameters CD1_1 CD1_2 in DEGREES/PIXEL CD2_1 CD2_2 .CDELT - 2 element double vector giving physical increment at the reference pixel .CRPIX - 2 element double vector giving X and Y coordinates of reference pixel (def = NAXIS/2) in FITS convention (first pixel is 1,1) .CRVAL - 2 element double precision vector giving R.A. and DEC of reference pixel in DEGREES .CTYPE - 2 element string vector giving projection types, default ['RA---TAN','DEC--TAN'] .LONGPOLE - scalar giving native longitude of the celestial pole (default = 180 for zenithal projections) .LATPOLE - scalar giving native latitude of the celestial pole default=0) .PV2 - Vector of projection parameter associated with latitude axis PV2 will have up to 21 elements for the ZPN projection, up to 3 for the SIN projection and no more than 2 for any other projection .DISTORT - optional substructure specifying any distortion parameters currently implemented only for "SIP" (Spitzer Imaging Polynomial) distortion parameters NOPARAMS - Scalar indicating the results of EXTAST -1 = Failure - Header missing astrometry parameters 1 = Success - Header contains CROTA + CDELT (AIPS-type) astrometry 2 = Success - Header contains CDn_m astrometry, rec. 3 = Success - Header contains PCn_m + CDELT astrometry. 4 = Success - Header contains ST Guide Star Survey astrometry (see gsssextast.pro ) OPTIONAL INPUT/OUTPUT KEYWORDS: ALT - single character 'A' through 'Z' or ' ' specifying an alternate astrometry system present in the FITS header. The default is to use the primary astrometry or ALT = ' '. If /ALT is set, then this is equivalent to ALT = 'A'. See Section 3.3 of Greisen & Calabretta (2002, A&A, 395, 1061) for information about alternate astrometry keywords. If not set on input, then ALT is set to ' ' on output. PROCEDURE: EXTAST checks for astrometry parameters in the following order: (1) the CD matrix PC1_1,PC1_2...plus CDELT*, CRPIX and CRVAL (2) the CD matrix CD1_1,CD1_2... plus CRPIX and CRVAL. (3) CROTA2 (or CROTA1) and CDELT plus CRPIX and CRVAL. All three forms are valid FITS according to the paper "Representations of World Coordinates in FITS by Greisen and Calabretta (2002, A&A, 395, 1061 http://fits.gsfc.nasa.gov/fits_wcs.html ) although form (1) is preferred. NOTES: 1. An anonymous structure is created to avoid structure definition conflicts. This is needed because some projection systems require additional dimensions (i.e. spherical cube projections require a specification of the cube face). 2, Some FITS headers (e.g.from HST/ACS) include SIP forward distortion coefficients but do not include the reverse coefficients. Currently, EXTAST only gives a warning that the reverse coefficients (RA,Dec to X,Y) are not present. EXTAST should actually compute the inverse coefficients, but this is not yet implemented.. PROCEDURES CALLED: GSSSEXTAST, ZPARCHECK REVISION HISTORY Written by B. Boothman 4/15/86 Accept CD001001 keywords 1-3-88 Accept CD1_1, CD2_1... keywords W. Landsman Nov. 92 Recognize GSSS FITS header W. Landsman June 94 Get correct sign, when converting CDELT* to CD matrix for right-handed coordinate system W. Landsman November 1998 Consistent conversion between CROTA and CD matrix October 2000 CTYPE = 'PIXEL' means no astrometry params W. Landsman January 2001 Don't choke if only 1 CTYPE value given W. Landsman August 2001 Recognize PC00n00m keywords again (sigh...) W. Landsman December 2001 Recognize GSSS in ctype also D. Finkbeiner Jan 2002 Introduce ALT keyword W. Landsman June 2003 Fix error introduced June 2003 where free-format values would be truncated if more than 20 characters. W. Landsman Aug 2003 Further fix to free-format values -- slash need not be present Sep 2003 Default value of LATPOLE is 90.0 W. Landsman February 2004 Allow for distortion substructure, currently implemented only for SIP (Spitzer Imaging Polynomial) W. Landsman February 2004 Correct LONGPOLE computation if CTYPE = ['*DEC','*RA'] W. L. Feb. 2004 Assume since V5.3 (vector STRMID) W. Landsman Feb 2004 Yet another fix to free-format values W. Landsman April 2004 Introduce PV2 tag to replace PROJP1, PROJP2.. etc. W. Landsman May 2004 Convert NCP projection to generalized SIN W. Landsman Aug 2004 Add NAXIS tag to output structure W. Landsman Jan 2007 .CRPIX tag now Double instead of Float W. Landsman Apr 2007 If duplicate keywords use the *last* value W. Landsman Aug 2008 Fix typo for AZP projection, nonzero longpole N. Cunningham Feb 2009 Give warning if reverse SIP coefficient not present W. Landsman Nov 2011 Allow obsolete CD matrix representations W. Landsman May 2012(See astrolib/pro/extast.pro)
EXTGRP
[Previous Routine] [Next Routine] [List of Routines]NAME: EXTGRP PURPOSE: Extract the group parameter information out of SXREAD output EXPLANATION: This procedure extracts the group parameter information out of a header and parameter variable obtained from SXREAD. This allows astrometry, photometry and other parameters to be easily SXPARed by conventional methods and allows the image and header to be saved in a SIMPLE format. CALLING SEQUENCE: ExtGrp, hdr, par INPUT: HDR - The header which is to be converted (input and output) PAR - The Parameter string returned from a call to SXREAD OUTPUT: HDR - The converted header, string array OTHER PROCEDURES CALLED: SXPAR(), SXADDPAR, SXGPAR(), STRN() HISTORY: 25-JUN-90 Version 1 written 13-JUL-92 Header finally added to this ancient procedure, code spiffed up a bit. Now 3 times faster. Added PTYPE comment inclusion. E. Deutsch Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/extgrp.pro)
EXTRAP
[Previous Routine] [Next Routine] [List of Routines]NAME: EXTRAP PURPOSE: This procedure fills in the ends of a one-dimensional array from interior portions using polynomial extrapolation. CATEGORY: Image processing CALLING SEQUENCE: EXTRAP, Deg, X, Y, Y2 INPUT POSITIONAL PARAMETERS: Deg: Degree of polynomial X: Independent variable Y: Dependent variable KEYWORD PARAMETERS: LIMS: 3-element array giving range of X to be used to fit polynomial and starting point where extrapolation is to be substituted; if not given, you click on a plot; order of elements is [xmin, xmax, xstart]; if LIMS is specified, then program is silent OUTPUT POSITIONAL PARAMETERS: Y2: Dependent variable with extrapolated portion filled in SIDE EFFECTS: May pop a window for selecting range. MODIFICATION HISTORY: Written by RSH, RITSS, 14 Aug 98 Spiffed up for library. RSH, 6 Oct 98(See astrolib/pro/skyadj_cube.pro)
FDECOMP
[Previous Routine] [Next Routine] [List of Routines]NAME: FDECOMP PURPOSE: Routine to decompose file name(s) for any operating system. CALLING SEQUENCE: FDECOMP, filename, disk, dir, name, qual, [OSFamily = ] INPUT: filename - string file name(s), scalar or vector OUTPUTS: All the output parameters will have the same number of elements as input filename disk - disk name, always '' on a Unix machine, scalar or vector string dir - directory name, scalar or vector string name - file name, scalar or vector string qual - qualifier, set equal to the characters beyond the last "." OPTIONAL INPUT KEYWORD: OSFamily - scalar string specifying the operating system, must be either 'Windows' or 'unix'. If not supplied, then !VERSION.OS_FAMILY is used to determine the OS. EXAMPLES: Consider the following file names unix: file = '/itt/idl71/avg.pro' Windows: file = 'd:\itt\idl71\avg.pro' then IDL> FDECOMP, file, disk, dir, name, qual will return the following Disk Dir Name Qual Unix: '' '/itt/idl71/' 'avg' 'pro' Windows: 'd:' \itt\idl71\ 'avg' 'pro' NOTES: (1) The period is removed between the name and qualifier (2) Unlike the intrinsic FILE_BASENAME() and FILE_DIRNAME() functions, one can use FDECOMP to decompose a Windows file name on a Unix machine or a Unix filename on a Windows machine. ROUTINES CALLED: None. HISTORY version 1 D. Lindler Oct 1986 Include VMS DECNET machine name in disk W. Landsman HSTX Feb. 94 Converted to Mac IDL, I. Freedman HSTX March 1994 Major rewrite to accept vector filenames V5.3 W. Landsman June 2000 Fix cases where disk name not always present W. Landsman Sep. 2000 Make sure version defined for Windows W. Landsman April 2004 Include final delimiter in directory under Windows as advertised W. Landsman May 2006 Remove VMS support, W. Landsman September 2006 Remove MacOS branch (same as Unix) W. Landsman August 2009(See astrolib/pro/fdecomp.pro)
FILTER_IMAGE
[Previous Routine] [Next Routine] [List of Routines]NAME: FILTER_IMAGE PURPOSE: Identical to MEDIAN or SMOOTH but handle edges and allow iterations. EXPLANATION: Computes the average and/or median of pixels in moving box, replacing center pixel with the computed average and/or median, (using the IDL SMOOTH() or MEDIAN() functions). The main reason for using this function is the options to also process the pixels at edges and corners of image, and, to apply iterative smoothing simulating convolution with Gaussian, and/or to convolve image with a Gaussian kernel. Users might also look at the function ESTIMATOR_FILTER() introduced in IDL 7.1. CALLING SEQUENCE: Result = filter_image( image, SMOOTH=width, MEDIAN = width, /ALL_PIXELS /ITERATE, FWHM =, /NO_FT_CONVOL) INPUT: image = 2-D array (matrix) OPTIONAL INPUT KEYWORDS: SMOOTH = scalar (odd) integer specifying the width of a square box for moving average, in # pixels. /SMOOTH means use box width = 3 pixels for smoothing. MEDIAN = scalar (usually odd) integer specifying the width of square moving box for median filter, in # pixels. /MEDIAN means use box width = 3 pixels for median filter. /ALL_PIXELS causes the edges of image to be filtered as well. This is accomplished by reflecting pixels adjacent to edges outward (similar to the /EDGE_WRAP keyword in CONVOL). Note that this is a different algorithm from the /EDGE_TRUNCATE keyword to SMOOTH or CONVOL, which duplicates the nearest pixel. /ITERATE means apply smooth(image,3) iteratively for a count of (box_width-1)/2 times (=radius), when box_width >= 5. This is equivalent to convolution with a Gaussian PSF of FWHM = 2 * sqrt( radius ) as radius gets large. Note that /ALL_PIXELS is automatically applied, giving better results in the iteration limit. (also, MEDIAN keyword is ignored when /ITER is specified). FWHM_GAUSSIAN = Full-width half-max of Gaussian to convolve with image. FWHM can be a single number (circular beam), or 2 numbers giving axes of elliptical beam. /NO_FT_CONVOL causes the convolution to be computed directly, with intrinsic IDL CONVOL function. The default is to use FFT when factors of size are all LE 13. Note that external function convolve.pro handles both cases) OPTIONAL INPUT/OUTPUT KEYWORD: PSF = Array containing the PSF used during the convolution. This keyword is only active if the FWHM_GAUSSIAN keyword is also specified. If PSF is undefined on input, then upon output it contains the Gaussian convolution specified by the FWHM_GAUSSIAN keyword. If the PSF array is defined on input then it is used as the convolution kernel, the value of the FWHM_GAUSSIAN keyword is ignored. Typically, on a first call set PSF to an undefined variable, which can be reused for subsequent calls to prevent recalculation of the Gaussian PSF. RESULT: Function returns the smoothed, median filtered, or convolved image. If both SMOOTH and MEDIAN are specified, median filter is applied first. If only SMOOTH is applied, then output is of same type as input. If either MEDIAN or FWHM_GAUSSIAN is supplied than the output is at least floating (double if the input image is double). EXAMPLES: To apply 3x3 moving median filter and then 3x3 moving average, both applied to all pixels: Result = filter_image( image, /SMOOTH, /MEDIAN, /ALL ) To iteratively apply 3x3 moving average filter for 4 = (9-1)/2 times, thus approximating convolution with Gaussian of FWHM = 2*sqrt(4) = 4 : Result = filter_image( image, SMOOTH=9, /ITER ) To convolve all pixels with Gaussian of FWHM = 3.7 x 5.2 pixels: Result = filter_image( image, FWHM=[3.7,5.2], /ALL ) EXTERNAL CALLS: function psf_gaussian function convolve pro factor function prime ;all these called only if FWHM is specified PROCEDURE: If both /ALL_PIXELS (or /ITERATE) keywords are set then create a larger image by reflecting the edges outward, then call the IDL MEDIAN() or SMOOTH() function on the larger image, and just return the central part (the original size image). NAN values are recognized during calls to MEDIAN() or SMOOTH(), but not for convolution with a Gaussian (FWHM keyword supplied). HISTORY: Written, 1991, Frank Varosi, NASA/GSFC. FV, 1992, added /ITERATE option. FV, 1993, added FWHM_GAUSSIAN= option. Use /EVEN call to median, recognize NAN values in SMOOTH W. Landsman June 2001 Added PSF keyword, Bjorn Heijligers/WL, September 2001 Keep same output data type if /ALL_PIXELS supplied A. Steffl Mar 2011(See astrolib/pro/filter_image.pro)
FIND
[Previous Routine] [Next Routine] [List of Routines]NAME: FIND PURPOSE: Find positive brightness perturbations (i.e stars) in an image EXPLANATION: Also returns centroids and shape parameters (roundness & sharpness). Adapted from 1991 version of DAOPHOT, but does not allow for bad pixels and uses a slightly different centroid algorithm. Modified in March 2008 to use marginal Gaussian fits to find centroids CALLING SEQUENCE: FIND, image, [ x, y, flux, sharp, round, hmin, fwhm, roundlim, sharplim PRINT= , /SILENT, /MONITOR] INPUTS: image - 2 dimensional image array (integer or real) for which one wishes to identify the stars present OPTIONAL INPUTS: FIND will prompt for these parameters if not supplied hmin - Threshold intensity for a point source - should generally be 3 or 4 sigma above background RMS fwhm - FWHM (in pixels) to be used in the convolve filter sharplim - 2 element vector giving low and high cutoff for the sharpness statistic (Default: [0.2,1.0] ). Change this default only if the stars have significantly larger or or smaller concentration than a Gaussian roundlim - 2 element vector giving low and high cutoff for the roundness statistic (Default: [-1.0,1.0] ). Change this default only if the stars are significantly elongated. OPTIONAL INPUT KEYWORDS: /MONITOR - Normally, FIND will display the results for each star only if no output variables are supplied. Set /MONITOR to always see the result of each individual star. /SILENT - set /SILENT keyword to suppress all output display PRINT - if set and non-zero then FIND will also write its results to a file find.prt. Also one can specify a different output file name by setting PRINT = 'filename'. OPTIONAL OUTPUTS: x - vector containing x position of all stars identified by FIND y- vector containing y position of all stars identified by FIND flux - vector containing flux of identified stars as determined by a Gaussian fit. Fluxes are NOT converted to magnitudes. sharp - vector containing sharpness statistic for identified stars round - vector containing roundness statistic for identified stars NOTES: (1) The sharpness statistic compares the central pixel to the mean of the surrounding pixels. If this difference is greater than the originally estimated height of the Gaussian or less than 0.2 the height of the Gaussian (for the default values of SHARPLIM) then the star will be rejected. (2) More recent versions of FIND in DAOPHOT allow the possibility of ignoring bad pixels. Unfortunately, to implement this in IDL would preclude the vectorization made possible with the CONVOL function and would run extremely slowly. (3) Modified in March 2008 to use marginal Gaussian distributions to compute centroid. (Formerly, find.pro determined centroids by locating where derivatives went to zero -- see cntrd.pro for this algorithm. This was the method used in very old (~1984) versions of DAOPHOT. ) As discussed in more detail in the comments to the code, the centroid computation here is the same as in IRAF DAOFIND but differs slightly from the current DAOPHOT. PROCEDURE CALLS: GETOPT() REVISION HISTORY: Written W. Landsman, STX February, 1987 ROUND now an internal function in V3.1 W. Landsman July 1993 Change variable name DERIV to DERIVAT W. Landsman Feb. 1996 Use /PRINT keyword instead of TEXTOUT W. Landsman May 1996 Changed loop indices to type LONG W. Landsman Aug. 1997 Replace DATATYPE() with size(/TNAME) W. Landsman Nov. 2001 Fix problem when PRINT= filename W. Landsman October 2002 Fix problems with >32767 stars D. Schlegel/W. Landsman Sep. 2004 Fix error message when no stars found S. Carey/W. Landsman Sep 2007 Rewrite centroid computation to use marginal Gaussians W. Landsman Mar 2008 Added Monitor keyword, /SILENT now suppresses all output W. Landsman Nov 2008 Work when threshold is negative (difference images) W. Landsman May 2010(See astrolib/pro/find.pro)
FINDPRO
[Previous Routine] [Next Routine] [List of Routines]NAME: FINDPRO PURPOSE: Find all locations of a procedure in the IDL !PATH EXPLANATION: FINDPRO searces for the procedure name (as a .pro or a .sav file) in all IDL libraries or directories given in the !PATH system variable. This differs from the intrinsic FILE_WHICH() function which only finds the first occurence of the procedure name. CALLING SEQUENCE: FINDPRO, [ Proc_Name, /NoPrint, DirList = , ProList = ] OPTIONAL INPUT: Proc_Name - Character string giving the name of the IDL procedure or function. Do not include the ".pro" extension. If Proc_Name is omitted, the program will prompt for PROC_NAME. "*" wildcards are permitted. OPTIONAL KEYWORD INPUT: /NoPrint - if set, then the file's path is not printed on the screen and absolutely no error messages are printed on the screen. If not set, then - since the MESSAGE routine is used - error messages will be printed but the printing of informational messages depends on the value of the !Quiet variable. OPTIONAL KEYWORD OUTPUTS: DirList - The directories in which the file is located are returned in the keyword as a string array. If the procedure is an intrinsic IDL procedure, then the value of DirList = ['INTRINSIC']. If the procedure is not found, the value of DirList = ['']. ProList - The list (full pathnames) of procedures found. Useful if you are looking for the name of a procedure using wildcards. The order of the names in DirList and ProList is identical to the order in which the procedure name appears in the !PATH PROCEDURE: The system variable !PATH is parsed using EXPAND_PATH into individual directories. FILE_SEARCH() is used to search the directories for the procedure name. If not found in !PATH, then the name is compared with the list of intrinsic IDL procedures given by the ROUTINE_INFO() function. EXAMPLE: (1) Find the procedure CURVEFIT. Assume for this example that the user also has a copy of the curvefit.pro procedure in her home directory on a Unix machine. IDL> findpro, 'curvefit', DIRLIST=DirList Procedure curvefit.pro found in directory /home/user/. Procedure curvefit.pro found in directory /software/IDL/idl82/lib/ IDL> help, DirList DIRLIST STRING = Array(2) IDL> help, DirList[0], DirList[1]STRING = '/home/user' STRING = '/software/IDL/idl82/lib/' (2) Find all procedures in one's !path containing the characters "zoom" IDL> findpro,'*zoom*' RESTRICTIONS: User will be unable to find a path for a native IDL function or procedure, or for a FORTRAN or C routine added with CALL_EXTERNAL. Remember that Unix is case sensitive, and most procedures will be in lower case. PROCEDURES USED: FDECOMP -- Decompose file name REVISION HISTORY: Based on code extracted from the GETPRO procedure, J. Parker 1994 Use the intrinsic EXPAND_PATH function W. Landsman Nov. 1994 Use ROUTINE_NAMES() to check for intrinsic procs W. Landsman Jul 95 Added Macintosh, WINDOWS compatibility W. Landsman Sep. 95 Removed spurious first element in PROLIST W. Landsman March 1997 Don't include duplicate directories in !PATH WL May 1997 Use ROUTINE_INFO instead of undocumented ROUTINE_NAMES W.L. October 1998 Also check for save sets W. Landsman October 1999 Force lower case check for VMS W. Landsman January 2000 Only return .pro or .sav files in PROLIST W. Landsman January 2002 Force lower case check for .pro and .sav D. Swain September 2002 Use FILE_SEARCH() if V5.5 or later W. Landsman June 2006 Assume since V55, remove VMS support W. Landsman Sep. 2006 Assume since V6.0, use file_basename() W.Landsman Feb 2009 Specify whether an intrinsic function or procedure W.L. Jan 2013 (See astrolib/pro/findpro.pro)
FIND_ALL_DIR()
[Previous Routine] [Next Routine] [List of Routines]NAME: FIND_ALL_DIR() PURPOSE: Finds all directories under a specified directory. EXPLANATION: This routine finds all the directories in a directory tree when the root of the tree is specified. This provides the same functionality as having a directory with a plus in front of it in the environment variable IDL_PATH. CALLING SEQUENCE: Result = FIND_ALL_DIR( PATH ) PATHS = FIND_ALL_DIR('+mypath', /PATH_FORMAT) PATHS = FIND_ALL_DIR('+mypath1:+mypath2') INPUTS: PATH = The path specification for the top directory in the tree. Optionally this may begin with the '+' character but the action is the same unless the PLUS_REQUIRED keyword is set. One can also path a series of directories separated by the correct character ("," for VMS, ":" for Unix) OUTPUTS: The result of the function is a list of directories starting from the top directory passed and working downward from there. Normally, this will be a string array with one directory per array element, but if the PATH_FORMAT keyword is set, then a single string will be returned, in the correct format to be incorporated into !PATH. OPTIONAL INPUT KEYWORDS: PATH_FORMAT = If set, then a single string is returned, in the format of !PATH. PLUS_REQUIRED = If set, then a leading plus sign is required in order to expand out a directory tree. This is especially useful if the input is a series of directories, where some components should be expanded, but others shouldn't. RESET = Often FIND_ALL_DIR is used with logical names. It can be rather slow to search through these subdirectories. The /RESET keyword can be used to redefine an environment variable so that subsequent calls don't need to look for the subdirectories. To use /RESET, the PATH parameter must contain the name of a *single* environment variable. For example setenv,'FITS_DATA=+/datadisk/fits' dir = find_all_dir('FITS_DATA',/reset,/plus) The /RESET keyword is usually combined with /PLUS_REQUIRED. PROCEDURE CALLS: DEF_DIRLIST, FIND_WITH_DEF(), BREAK_PATH() RESTRICTIONS: PATH must point to a directory that actually exists. REVISION HISTORY: Version 11, Zarro (SM&A/GSFC), 23-March-00 Removed all calls to IS_DIR Version 12, William Thompson, GSFC, 02-Feb-2001 In Windows, use built-in expand_path if able. Version 13, William Thompson, GSFC, 23-Apr-2002 Follow logical links in Unix (Suggested by Pascal Saint-Hilaire) Version 14, Zarro (EER/GSFC), 26-Oct-2002 Saved/restored current directory to protect against often mysterious directory changes caused by spawning FIND in Unix Version 15, William Thompson, GSFC, 9-Feb-2004 Resolve environment variables in Windows. Version : Version 16 W. Landsman GSFC Sep 2006 Remove VMS support(See astrolib/pro/find_all_dir.pro)
FIND_WITH_DEF()
[Previous Routine] [Next Routine] [List of Routines]NAME: FIND_WITH_DEF() PURPOSE: Searches for files with a default path and extension. EXPLANATION: Finds files using default paths and extensions, Using this routine together with environment variables allows an OS-independent approach to finding files. CALLING SEQUENCE: Result = FIND_WITH_DEF( FILENAME, PATHS [, EXTENSIONS ] ) INPUTS: FILENAME = Name of file to be searched for. It may either be a complete filename, or the path or extension could be left off, in which case the routine will attempt to find the file using the default paths and extensions. PATHS = One or more default paths to use in the search in case FILENAME does not contain a path itself. 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. The current directory is always searched first, unless the keyword NOCURRENT is set. A leading $ can be used in any path to signal that what follows is an environmental variable, but the $ is not necessary. Environmental variables can themselves contain multiple paths. OPTIONAL INPUTS: EXTENSIONS = Scalar string giving one or more extensions to append to end of filename if the filename does not contain one (e.g. ".dat"). The period is optional. Multiple extensions can be separated by commas or colons. OUTPUTS: The result of the function is the name of the file if successful, or the null string if unsuccessful. OPTIONAL INPUT KEYWORDS: NOCURRENT = If set, then the current directory is not searched. RESET = The FIND_WITH_DEF routine supports paths which are preceeded with the plus sign to signal that all subdirectories should also be searched. Often this is used with logical names. It can be rather slow to search through these subdirectories. The /RESET keyword can be used to redefine an environment variable so that subsequent calls don't need to look for the subdirectories. To use /RESET, the PATHS parameter must contain the name of a *single* environment variable. For example setenv,'FITS_DATA=+/datadisk/fits' file = find_with_def('test.fits','FITS_DATA',/reset) EXAMPLE: FILENAME = '' READ, 'File to open: ', FILENAME FILE = FIND_WITH_DEF( FILENAME, 'SERTS_DATA', '.fix' ) IF FILE NE '' THEN ... PROCEDURE CALLS: BREAK_PATH(), FIND_ALL_DIR(), STR_SEP() REVISION HISTORY: Version 1, William Thompson, GSFC, 3 May 1993. Removed trailing / and : characters. Fixed bugs Allow for commas within values of logical names. Added keyword NOCURRENT. Changed to call BREAK_PATH Version 2, William Thompson, GSFC, 3 November 1994 Made EXTENSIONS optional. Version 3, William Thompson, GSFC, 30 April 1996 Call FIND_ALL_DIR to resolve any plus signs. Version 4, S.V. Haugan, UiO, 5 June 1996 Using OPENR,..,ERROR=ERROR to avoid an IDL 3.6 internal nesting error. Version 5, R.A. Schwartz, GSFC, 11 July 1996 Use SPEC_DIR to interpret PATH under VMS Version 6, William Thompson, GSFC, 5 August 1996 Took out call to SPEC_DIR (i.e., reverted to version 4). The use of SPEC_DIR was required to support logical names defined via SETLOG,/CONFINE. However, it conflicted with the ability to use logical names with multiple values. Removing the /CONFINE made it unnecessary to call SPEC_DIR in this routine. Version 7, William Thompson, GSFC, 6 August 1996 Added keyword RESET Converted to IDL V5.0 W. Landsman October 1997 Use STRTRIM instead of TRIM, W. Landsman November 1998 Use STRSPLIT instead of STR_SEP W. Landsman July 2002(See astrolib/pro/find_with_def.pro)
FITEXY
[Previous Routine] [Next Routine] [List of Routines]NAME: FITEXY PURPOSE: Best straight-line fit to data with errors in both coordinates EXPLANATION: Linear Least-squares approximation in one-dimension (y = a + b*x), when both x and y data have errors CALLING EXAMPLE: FITEXY, x, y, A, B, X_SIG= , Y_SIG= , [sigma_A_B, chi_sq, q, TOL=] INPUTS: x = array of values for independent variable. y = array of data values assumed to be linearly dependent on x. REQUIRED INPUT KEYWORDS: X_SIGMA = scalar or array specifying the standard deviation of x data. Y_SIGMA = scalar or array specifying the standard deviation of y data. OPTIONAL INPUT KEYWORD: TOLERANCE = desired accuracy of minimum & zero location, default=1.e-3. OUTPUTS: A_intercept = constant parameter result of linear fit, B_slope = slope parameter, so that: ( A_intercept + B_slope * x ) approximates the y data. OPTIONAL OUTPUT: sigma_A_B = two element array giving standard deviation of A_intercept and B_slope parameters, respectively. The standard deviations are not meaningful if (i) the fit is poor (see parameter q), or (ii) b is so large that the data are consistent with a vertical (infinite b) line. If the data are consistent with *all* values of b, then sigma_A_B = [1e33,e33] chi_sq = resulting minimum Chi-Square of Linear fit, scalar q - chi-sq probability, scalar (0-1) giving the probability that a correct model would give a value equal or larger than the observed chi squared. A small value of q indicates a poor fit, perhaps because the errors are underestimated. As discussed by Tremaine et al. (2002, ApJ, 574, 740) an underestimate of the errors (e.g. due to an intrinsic dispersion) can lead to a bias in the derived slope, and it may be worth enlarging the error bars to get a reduced chi_sq ~ 1 COMMON: common fitexy, communicates the data for computation of chi-square. PROCEDURE CALLS: CHISQ_FITEXY() ;Included in this file MINF_BRACKET, MINF_PARABOLIC, ZBRENT ;In IDL Astronomy Library MOMENT(), CHISQR_PDF() ;In standard IDL distribution PROCEDURE: From "Numerical Recipes" column by Press and Teukolsky: in "Computer in Physics", May, 1992 Vol.6 No.3 Also see the 2nd edition of the book "Numerical Recipes" by Press et al. In order to avoid problems with data sets where X and Y are of very different order of magnitude the data are normalized before the fitting process is started. The following normalization is used: xx = (x - xm) / xs and sigx = x_sigma / xs where xm = MEAN(x) and xs = STDDEV(x) yy = (y - ym) / ys and sigy = y_sigma / ys where ym = MEAN(y) and ys = STDDEV(y) MODIFICATION HISTORY: Written, Frank Varosi NASA/GSFC September 1992. Now returns q rather than 1-q W. Landsman December 1992 Use CHISQR_PDF, MOMENT instead of STDEV,CHI_SQR1 W. Landsman April 1998 Fixed typo for initial guess of slope, this error was nearly always insignificant W. Landsman March 2000 Normalize X,Y before calculation (from F. Holland) W. Landsman Nov 2006(See astrolib/pro/fitexy.pro)
FITSDIR
[Previous Routine] [Next Routine] [List of Routines]NAME: FITSDIR PURPOSE: Display selected FITS keywords from the headers of FITS files. EXPLANATION: The values of either user-specified or default FITS keywords are displayed in either the primary header and/or the first extension header. Unless the /NOSIZE keyword is set, the data size is also displayed. The default keywords are as follows (with keywords in 2nd row used if those in the first row not found, and the 3rd row if neither the keywords in the first or second rows found:) DATE-OBS TELESCOP OBJECT EXPTIME TDATEOBS TELNAME TARGNAME INTEG ;First Alternative DATE OBSERVAT EXPOSURE ;Second Alternative INSTRUME EXPTIM ;Third Alternative FITSDIR will also recognize gzip compressed files (must have a .gz or FTZ extension). CALLING SEQUENCE: FITSDIR , [ directory, TEXTOUT =, EXTEN=, KEYWORDS=, /NOSIZE, /NoTELESCOPE ALT1_KEYWORDS= ,ALT2_KEYWORDS = ,ALT3_KEYWORDS = OPTIONAL INPUT PARAMETERS: DIRECTORY - Scalar string giving file name, disk or directory to be searched. Wildcard file names are allowed. Examples of valid names include 'iraf/*.fits' (Unix), d:\myfiles\f*.fits', (Windows) or 'Macintosh HD:Files:*c0f.fits' (Macintosh). OPTIONAL KEYWORD INPUT PARAMETER KEYWORDS - FITS keywords to display, as either a vector of strings or as a comma delimited scalar string, e.g.'testname,dewar,filter' If not supplied, then the default keywords are 'DATE-OBS', 'TELESCOP','OBJECT','EXPTIME' ALT1_KEYWORDS - A list (either a vector of strings or a comma delimited strings of alternative keywords to use if the default KEYWORDS cannot be found. By default, 'TDATEOBS', is the alternative to DATE-OBS, 'TELNAME' for 'TELESCOP','TARGNAME' for 'OBJECT', and 'INTEG' for EXPTIME ALT2_KEYWORDS - A list (either a vector of strings or a comma delimited strings of alternative keywords to use if neither KEYWORDS nor ALT1_KEYWORDS can be found. ALT3_KEYWORDS - A list (either a vector of strings or a comma delimited strings of alternative keywords to use if neither KEYWORDS nor ALT1_KEYWORDS nor ALT2_KEYWORDS can be found. /NOSIZE - if set then information about the image size is not displayed TEXTOUT - Controls output device as described in TEXTOPEN procedure textout=1 TERMINAL using /more option textout=2 TERMINAL without /more option textout=3.prt textout=4 laser.tmp textout=5 user must open file textout=7 Append to existing .prt file textout = filename (default extension of .prt) EXTEN - Specifies an extension number (/EXTEN works for first extension) which is checked for the desired keywords. /NOTELESCOPE - If set, then if the default keywords are used, then the TELESCOPE (or TELNAME, OBSERVAT, INSTRUME) keywords are omitted to give more room for display other keywords. The /NOTELESCOP keyword has no effect if the default keywords are not used. OUTPUT PARAMETERS: None. EXAMPLES: (1) Print info on all'*.fits' files in the current directory using default keywords. Include information from the extension header IDL> fitsdir,/exten (2) Write a driver program to display selected keywords in HST/ACS drizzled (*drz) images pro acsdir keywords = 'date-obs,targname,detector,filter1,filter2,exptime' fitsdir,'*drz.fits',key=keywords,/exten return & end (3) Write info on all *.fits files in the Unix directory /usr2/smith, to a file 'smith.txt' using the default keywords, but don't display the value of the TELESCOPE keyword IDL> fitsdir ,'/usr2/smith/*.fits',t='smith.txt', /NoTel PROCEDURE: FILE_SEARCH() is used to find the specified FITS files. The header of each file is read, and the selected keywords are extracted. The formatting is adjusted so that no value is truncated on display. SYSTEM VARIABLES: TEXTOPEN (called by FITSDIR) will automatically define the following non-standard system variables if they are not previously defined: DEFSYSV,'!TEXTOUT',1 DEFSYSV,'!TEXTUNIT',0 PROCEDURES USED: FDECOMP, FXMOVE, MRD_HREAD, REMCHAR TEXTOPEN, TEXTCLOSE MODIFICATION HISTORY: Written, W. Landsman, HSTX February, 1993 Search alternate keyword names W.Landsman October 1998 Avoid integer truncation for NAXISi >32767 W. Landsman July 2000 Don't leave open unit W. Landsman July 2000 Added EXTEN keyword, work with compressed files, additional alternate keywords W. Landsman December 2000 Don't assume floating pt. exposure time W. Landsman September 2001 Major rewrite, KEYWORD & ALT*_KEYWORDS keywords, no truncation, /NOSIZE keyword W. Landsman, SSAI August 2002 Assume V5.3 or later W. Landsman November 2002 Fix case where no keywords supplied W. Landsman January 2003 NAXIS* values must be integers W. Landsman SSAI June 2003 Trim spaces off of input KEYWORD values W. Landsman March 2004 Treat .FTZ extension as gzip compressed W. Landsman September 2004 Assume since V5.5, file_search() available W. Landsman Aug 2006 Don't assume all images compressed or uncompressed W. L. Apr 2010 Use V6.0 notation W.L. Feb 2011 (See astrolib/pro/fitsdir.pro)
FITSRGB_TO_TIFF
[Previous Routine] [Next Routine] [List of Routines]NAME: FITSRGB_to_TIFF PURPOSE: Combine separate red, green, and blue FITS images into TIFF format EXPLANATION: The output TIFF (class R) file can have colors interleaved either by pixel or image. The colour mix is also adjustable. CALLING SEQUENCE: FITSRGB_to_TIFF, path, rgb_files, tiff_name [,/BY_PIXEL, /PREVIEW, RED= , GREEN =, BLUE =] INPUTS: path = file system directory path to the RGB files required. rgb_files = string array with three components - the red FITS file filename, the blue FITS file filename and the green FITS file filename OUTPUTS: tiff_name = string containing name of tiff file to be produced OPTIONAL OUTPUT: Header = String array containing the header from the FITS file. OPTIONAL INPUT KEYWORDS: BY_PIXEL = This causes TIFF file RGB to be interleaved by pixel rather than the default of by image. PREVIEW = Allows a 24 bit image to be displayed on the screen to check the colour mix. RED = Real number containing the fractional mix of red GREEN = Real number containing the fractional mix of green BLUE = Real number containing the fractional mix of blue EXAMPLE: Read three FITS files, 'red.fits', 'blue.fits' and 'green.fits' from the directory '/data/images/space' and output a TIFF file named 'colour.tiff' IDL> FITSRGB_to_TIFF, '/data/images/space', ['red.fits', $ 'blue.fits', 'green.fits'], 'colour.tiff' Read three FITS files, 'red.fits', 'blue.fits' and 'green.fits' from the current directory and output a TIFF file named '/images/out.tiff' In this case, the red image is twice as strong as the green and the blue is a third more intense. A preview on screen is also wanted. IDL> FITSRGB_to_TIFF, '.', ['red.fits', $ 'blue.fits', 'green.fits'], '/images/out.tiff', $ /PREVIEW, RED=0.5, GREEN=1.0, BLUE=0.666 RESTRICTIONS: (1) Limited to the ability of the routine READFITS NOTES: None PROCEDURES USED: Functions: READFITS, CONCAT_DIR Procedures: WRITE_TIFF MODIFICATION HISTORY: 16th January 1995 - Written by Carl Shaw, Queen's University Belfast 27 Jan 1995 - W. Landsman, Add CONCAT_DIR for VMS, Windows compatibility Converted to IDL V5.0 W. Landsman September 1997 Use WRITE_TIFF instead of obsolete TIFF_WRITE W. Landsman December 1998 Cosmetic changes W. Landsman February 2000(See astrolib/pro/fitsrgb_to_tiff.pro)
FITS_ADD_CHECKSUM
[Previous Routine] [Next Routine] [List of Routines]NAME: FITS_ADD_CHECKSUM PURPOSE: Add or update the CHECKSUM and DATASUM keywords in a FITS header EXPLANATION: Follows the 23 May 2002 version of the FITS checksum proposal at http://heasarc.gsfc.nasa.gov/docs/heasarc/fits/checksum.html CALLING SEQUENCE: FITS_ADD_CHECKSUM, Hdr, [ Data, /No_TIMESTAMP, /FROM_IEEE ] INPUT-OUTPUT: Hdr - FITS header (string array), it will be updated with new (or modfied) CHECKSUM and DATASUM keywords OPTIONAL INPUT: Data - data array associated with the FITS header. If not supplied, or set to a scalar, then the program checks whether there is a DATASUM keyword already in the FITS header containing the 32bit checksum for the data. if there is no such keyword then there assumed to be no data array associated with the FITS header. OPTIONAL INPUT KEYWORDS: /FROM_IEEE - If this keyword is set, then the input is assumed to be in big endian format (e.g. an untranslated FITS array). This keyword only has an effect on little endian machines (e.g. a Linux box). /No_TIMESTAMP - If set, then a time stamp is not included in the comment field of the CHECKSUM and DATASUM keywords. Unless the /No_TIMESTAMP keyword is set, repeated calls to FITS_ADD_CHECKSUM with the same header and data will yield different values of CHECKSUM (as the date stamp always changes). However, use of the date stamp is recommended in the checksum proposal. PROCEDURES USED: CHECKSUM32, FITS_ASCII_ENCODE(), GET_DATE, SXADDPAR, SXPAR() REVISION HISTORY: W. Landsman SSAI December 2002 Fix problem with images with a multiple of 2880 bytes. W.L. May 2008 Avoid conversion error when DATASUM is an empty string W.L. June 2008 Don't update DATASUM if not already present and no data array supplied W.L. July 2008 Make sure input header array has 80 chars/line W.L. Aug 2009(See astrolib/pro/fits_add_checksum.pro)
FITS_ASCII_ENCODE()
[Previous Routine] [Next Routine] [List of Routines]NAME: FITS_ASCII_ENCODE() PURPOSE: Encode an unsigned longword as an ASCII string to insert in a FITS header EXPLANATION: Follows the 23 May 2002 version of the FITS checksum proposal at http://heasarc.gsfc.nasa.gov/docs/heasarc/fits/checksum.html CALLING SEQUENCE: result = FITS_ASCII_ENCODE( sum32) INPUTS: sum32 - 32bit *unsigned longword* (e.g. as returned by CHECKSUM32) RESULT: A 16 character scalar string suitable for the CHECKSUM keyword EXAMPLE: A FITS header/data unit has a checksum of 868229149. Encode the complement of this value (3426738146) into an ASCII string IDL> print,FITS_ASCII_ENCODE(3426738146U) ===> "hcHjjc9ghcEghc9g" METHOD: The 32bit value is interpreted as a sequence of 4 unsigned 8 bit integers, and divided by 4. Add an offset of 48b (ASCII '0'). Remove non-alphanumeric ASCII characters (byte values 58-64 and 91-96) by simultaneously incrementing and decrementing the values in pairs. Cyclicly shift the string one place to the right. REVISION HISTORY: Written W. Landsman SSAI December 2002(See astrolib/pro/fits_ascii_encode.pro)
FITS_CD_FIX
[Previous Routine] [Next Routine] [List of Routines]NAME: FITS_CD_FIX PURPOSE: Update obsolete representations of the CD matrix in a FITS header EXPLANATION: According the paper, "Representations of Celestial Coordinates in FITS" by Calabretta & Greisen (2002, A&A, 395, 1077, available at http://fits.gsfc.nasa.gov/fits_wcs.html) the rotation of an image from standard coordinates is represented by a coordinate description (CD) matrix. The standard representation of the CD matrix are PCn_m keywords, but CDn_m keywords (which include the scale factors) are also allowed. However, earliers drafts of the standard allowed the keywords forms CD00n00m and PC00n00m. This procedure will convert FITS CD matrix keywords containing zeros into the standard forms CDn_m and PCn_m containing only underscores. CALLING SEQUENCE: FITS_CD_FIX, Hdr INPUT-OUTPUT: HDR - FITS header, 80 x N string array. If the header does not contain 'CD00n00m' or 'PC00n00m' keywords then it is left unmodified. Otherwise, the keywords containing integers are replaced with those containing underscores. OPTIONAL KEYWORD INPUT /REVERSE - this keyword does nothing, but is kept for compatibility with earlier versions. PROCEDURES USED: SXADDPAR, SXDELPAR, SXPAR() REVISION HISTORY: Written W. Landsman Feb 1990 Major rewrite Feb 1994 Converted to IDL V5.0 W. Landsman September 1997 Use double precision formatting of CD matrix W. Landsman April 2000 Major rewrite to convert only to forms recognized by the Greisen & Calabretta standard W. Landsman July 2003(See astrolib/pro/fits_cd_fix.pro)
FITS_CLOSE
[Previous Routine] [Next Routine] [List of Routines]NAME: FITS_CLOSE *PURPOSE: Close a FITS data file *CATEGORY: INPUT/OUTPUT *CALLING SEQUENCE: FITS_CLOSE,fcb *INPUTS: FCB: FITS control block returned by FITS_OPEN. *KEYWORD PARAMETERS: /NO_ABORT: Set to return to calling program instead of a RETALL when an I/O error is encountered. If set, the routine will return a non-null string (containing the error message) in the keyword MESSAGE. If /NO_ABORT not set, then FITS_CLOSE will print the message and issue a RETALL MESSAGE = value: Output error message *EXAMPLES: Open a FITS file, read some data, and close it with FITS_CLOSE FITS_OPEN,'infile',fcb FITS_READ,fcb,data FITS_READ,fcb,moredata FITS_CLOSE,fcb *HISTORY: Written by: D. Lindler August, 1995 Converted to IDL V5.0 W. Landsman September 1997 Do nothing if fcb an invalid structure D. Schlegel/W. Landsman Oct. 2000 Return Message='' for to signal normal operation W. Landsman Nov. 2000(See astrolib/pro/fits_close.pro)
FITS_HELP
[Previous Routine] [Next Routine] [List of Routines]NAME: FITS_HELP PURPOSE: To print a summary of the primary data units and extensions in a FITS file. ; CALLING SEQUENCE: FITS_HELP,filename_or_fcb INPUTS: FILENAME_OR_FCB - name of the fits file or the FITS Control Block (FCB) structure returned by FITS_OPEN. The file name is allowed to be gzip compressed (with a .gz extension) OUTPUTS: A summary of the FITS file is printed. For each extension, the values of the XTENSION, EXTNAME EXTVER EXTLEVEL BITPIX GCOUNT, PCOUNT NAXIS and NAXIS* keywords are displayed. EXAMPLES: FITS_HELP,'myfile.fits' FITS_OPEN,'anotherfile.fits',fcb FITS_HELP,fcb PROCEDURES USED: FITS_OPEN, FITS_CLOSE HISTORY: Written by: D. Lindler August, 1995 Converted to IDL V5.0 W. Landsman September 1997 Don't truncate EXTNAME values at 10 chars W. Landsman Feb. 2005 Use V6.0 notation W. Landsman Jan 2012(See astrolib/pro/fits_help.pro)
FITS_INFO
[Previous Routine] [Next Routine] [List of Routines]NAME: FITS_INFO PURPOSE: Provide information about the contents of a FITS file EXPLANATION: Information includes number of header records and size of data array. Applies to primary header and all extensions. Information can be printed at the terminal and/or stored in a common block This routine is mostly obsolete, and better results can be usually be performed with FITS_HELP (for display) or FITS_OPEN (to read FITS information into a structure) CALLING SEQUENCE: FITS_INFO, Filename, [ /SILENT , TEXTOUT = , N_ext =, EXTNAME= ] INPUT: Filename - Scalar string giving the name of the FITS file(s) Can include wildcards such as '*.fits', or regular expressions allowed by the FILE_SEARCH() function. One can also search gzip compressed FITS files, but their extension must end in .gz or .ftz. OPTIONAL INPUT KEYWORDS: /SILENT - If set, then the display of the file description on the terminal will be suppressed TEXTOUT - specifies output device. textout=1 TERMINAL using /more option textout=2 TERMINAL without /more option textout=3.prt textout=4 laser.tmp textout=5 user must open file, see TEXTOPEN textout=7 append to existing file textout = filename (default extension of .prt) If TEXTOUT is not supplied, then !TEXTOUT is used OPTIONAL OUTPUT KEYWORDS: The following keyowrds are for use when only one file is processed N_ext - Returns an integer scalar giving the number of extensions in the FITS file extname - returns a list containing the EXTNAME keywords for each extension. COMMON BLOCKS DESCRIPTOR = File descriptor string of the form N_hdrrec Naxis IDL_type Naxis1 Naxis2 ... Naxisn [N_hdrrec table_type Naxis IDL_type Naxis1 ... Naxisn] (repeated for each extension) For example, the following descriptor 167 2 4 3839 4 55 BINTABLE 2 1 89 5 indicates that the primary header containing 167 lines, and the primary (2D) floating point image (IDL type 4) is of size 3839 x 4. The first extension header contains 55 lines, and the byte (IDL type 1) table array is of size 89 x 5. The DESCRIPTOR is *only* computed if /SILENT is set. EXAMPLE: Display info about all FITS files of the form '*.fit' in the current directory IDL> fits_info, '*.fit' Any time a *.fit file is found which is *not* in FITS format, an error message is displayed at the terminal and the program continues PROCEDURES USED: GETTOK(), MRD_SKIP, STRN(), SXPAR(), TEXTOPEN, TEXTCLOSE SYSTEM VARIABLES: The non-standard system variables !TEXTOUT and !TEXTUNIT will be created by FITS_INFO if they are not previously defined. DEFSYSV,'!TEXTOUT',1 DEFSYSV,'!TEXTUNIT',0 See TEXTOPEN.PRO for more info MODIFICATION HISTORY: Written, K. Venkatakrishna, Hughes STX, May 1992 Added N_ext keyword, and table_name info, G. Reichert Work on *very* large FITS files October 92 More checks to recognize corrupted FITS files February, 1993 Proper check for END keyword December 1994 Correctly size variable length binary tables WBL December 1994 EXTNAME keyword can be anywhere in extension header WBL January 1998 Correctly skip past extensions with no data WBL April 1998 Converted to IDL V5.0, W. Landsman, April 1998 No need for !TEXTOUT if /SILENT D.Finkbeiner February 2002 Define !TEXTOUT if needed. R. Sterner, 2002 Aug 27 Work on gzip compressed files for V5.3 or later W. Landsman 2003 Jan Improve speed by only reading first 36 lines of header Count headers with more than 32767 lines W. Landsman Feb. 2003 Assume since V5.3 (OPENR,/COMPRESS) W. Landsman Feb 2004 EXTNAME keyword can be anywhere in extension header again WBL/S. Bansal Dec 2004 Read more than 200 extensions WBL March 2005 Work for FITS files with SIMPLE=F WBL July 2005 Assume since V5.4, fstat.compress available WBL April 2006 Added EXTNAME as an IDL keyword to return values. M. Perrin Dec 2007 make Ndata a long64 to deal with large files. E. Hivon Mar 2008 For GDL compatibility, first check if file is compressed before using OPENR,/COMPRESS B. Roukema/WL Apr 2010 Increased nmax (max number of extensions) from 400 to 2000 Sept 2012 Correctly fills EXTNAME when SILENT is set EH Jan 2013 (See astrolib/pro/fits_info.pro)
FITS_OPEN
[Previous Routine] [Next Routine] [List of Routines]NAME: FITS_OPEN PURPOSE: Opens a FITS (Flexible Image Transport System) data file. EXPLANATION: Used by FITS_READ and FITS_WRITE CALLING SEQUENCE: FITS_OPEN, filename, fcb INPUTS: filename : name of the FITS file to open, scalar string FITS_OPEN can also open gzip compressed (.gz) file *for reading only*, although there is a performance penalty FPACK ( http://heasarc.gsfc.nasa.gov/fitsio/fpack/ ) compressed FITS files can be read provided that the FPACK software is installed. *OUTPUTS: fcb : (FITS Control Block) a IDL structure containing information concerning the file. It is an input to FITS_READ, FITS_WRITE FITS_CLOSE and MODFITS. INPUT KEYWORD PARAMETERS: /APPEND: Set to append to an existing file. /FPACK - Signal that the file is compressed with the FPACK software. http://heasarc.gsfc.nasa.gov/fitsio/fpack/ ) By default, FITS_OPEN assumes that if the file name extension ends in .fz that it is fpack compressed. The FPACK software must be installed on the system /HPRINT - print headers with routine HPRINT as they are read. (useful for debugging a strange file) /NO_ABORT: Set to quietly return to calling program when an I/O error is encountered, and return a non-null string (containing the error message) in the keyword MESSAGE. If /NO_ABORT not set, then FITS_OPEN will display the error message and return to the calling program. /UPDATE Set this keyword to open an existing file for update /WRITE: Set this keyword to open a new file for writing. OUTPUT KEYWORD PARAMETERS: MESSAGE = value: Output error message. If the FITS file was opened successfully, then message = ''. NOTES: The output FCB should be passed to the other FITS routines (FITS_OPEN, FITS_READ, FITS_HELP, and FITS_WRITE). It has the following structure when FITS_OPEN is called without /WRITE or /APPEND keywords set. FCB.FILENAME - name of the input file .UNIT - unit number the file is opened to .FCOMPRESS - 1 if unit is a FPACK compressed file opened with a pipe to SPAWN .NEXTEND - number of extensions in the file. .XTENSION - string array giving the extension type for each extension. .EXTNAME - string array giving the extension name for each extension. (null string if not defined the extension) .EXTVER - vector of extension version numbers (0 if not defined) .EXTLEVEL - vector of extension levels (0 if not defined) .GCOUNT - vector with the number of groups in each extension. .PCOUNT - vector with parameter count for each group .BITPIX - BITPIX for each extension with values 8 byte data 16 short word integers 32 long word integers -32 IEEE floating point -64 IEEE double precision floating point .NAXIS - number of axes for each extension. (0 for null data units) .AXIS - 2-D array where axis(*,N) gives the size of each axes for extension N .START_HEADER - vector giving the starting byte in the file where each extension header begins .START_DATA - vector giving the starting byte in the file where the data for each extension begins .HMAIN - keyword parameters (less standard required FITS keywords) for the primary data unit. .OPEN_FOR_WRITE - flag (0= open for read, 1=open for write, 2=open for update) .LAST_EXTENSION - last extension number read. .RANDOM_GROUPS - 1 if the PDU is random groups format, 0 otherwise .NBYTES - total number of (uncompressed) bytes in the FITS file When FITS open is called with the /WRITE or /APPEND option, FCB contains: FCB.FILENAME - name of the input file .UNIT - unit number the file is opened to .NEXTEND - number of extensions in the file. .OPEN_FOR_WRITE - flag (1=open for write, 2=open for append 3=open for update) EXAMPLES: Open a FITS file for reading: FITS_OPEN,'myfile.fits',fcb Open a new FITS file for output: FITS_OPEN,'newfile.fits',fcb,/write PROCEDURES USED: GET_PIPE_FILESIZE (for Fcompress'ed files) HPRINT, SXDELPAR, SXPAR() HISTORY: Written by: D. Lindler August, 1995 July, 1996 NICMOS Modified to allow open for overwrite to allow primary header to be modified DJL Oct. 15, 1996 corrected to properly extend AXIS when more than 100 extensions present Converted to IDL V5.0 W. Landsman September 1997 Use Message = '' rather than !ERR =1 as preferred signal of normal operation W. Landsman November 2000 Lindler, Dec, 2001, Modified to use 64 bit words for storing byte positions within the file to allow support for very large files Work with gzip compressed files W. Landsman January 2003 Fix gzip compress for V5.4 and earlier W.Landsman/M.Fitzgerald Dec 2003 Assume since V5.3 (STRSPLIT, OPENR,/COMPRESS) W. Landsman Feb 2004 Treat FTZ extension as gzip compressed W. Landsman Sep 2004 Assume since V5.4 fstat.compress available W. Landsman Apr 2006 FCB.Filename now expands any wildcards W. Landsman July 2006 Make ndata 64bit for very large files B. Garwood/W. Landsman Sep 2006 Open with /SWAP_IF_LITTLE_ENDIAN, remove obsolete keywords to OPEN W. Landsman Sep 2006 Warn that one cannot open a compressed file for update W.L. April 2007 Use post-V6.0 notation W.L. October 2010 Support FPACK compressed files, new .FCOMPRESS tag to FCB structure W.L. December 2010 Read gzip'ed files even if gzip is not installed W.L. October 2012(See astrolib/pro/fits_open.pro)
FITS_READ
[Previous Routine] [Next Routine] [List of Routines]NAME: FITS_READ PURPOSE: To read a FITS file. CALLING SEQUENCE: FITS_READ, filename_or_fcb, data [,header, group_par] INPUTS: FILENAME_OR_FCB - this parameter can be the FITS Control Block (FCB) returned by FITS_OPEN or the file name of the FITS file. If a file name is supplied, FITS_READ will open the file with FITS_OPEN and close the file with FITS_CLOSE before exiting. When multiple extensions are to be read from the file, it is more efficient for the user to call FITS_OPEN and leave the file open until all extensions are read. FPACK ( http://heasarc.gsfc.nasa.gov/fitsio/fpack/ ) compressed FITS files can be read provided that the FPACK software is installed. OUTPUTS: DATA - data array. If /NOSCALE is specified, BSCALE and BZERO (if present in the header) will not be used to scale the data. If Keywords FIRST and LAST are used to read a portion of the data or the heap portion of an extension, no scaling is done and data is returned as a 1-D vector. The user can use the IDL function REFORM to convert the data to the correct dimensions if desired. If /DATA_ONLY is specified, no scaling is done. HEADER - FITS Header. The STScI inheritance convention is recognized http://fits.gsfc.nasa.gov/registry/inherit/fits_inheritance.txt If an extension is read, and the INHERIT keyword exists with a value of T, and the /NO_PDU keyword keyword is not supplied, then the primary data unit header and the extension header will be combined. The header will have the form:BEGIN MAIN HEADER -------------------------------- BEGIN EXTENSION HEADER --------------------------- 1. (Default=0, the first group) OUTPUT KEYWORD PARAMETERS: ENUM - Output extension number that was read. MESSAGE = value: Output error message NOTES: Determination or which extension to read. case 1: EXTEN_NO specified. EXTEN_NO will give the number of the extension to read. The primary data unit is refered to as extension 0. If EXTEN_NO is specified, XTENSION, EXTNAME, EXTVER, and EXTLEVEL parameters are ignored. case 2: if EXTEN_NO is not specified, the first extension with the specified XTENSION, EXTNAME, EXTVER, and EXTLEVEL will be read. If any of the 4 parameters are not specified, they will not be used in the search. Setting EXTLEVEL=0, EXTVER=0, EXTNAME='', or XTENSION='' is the same as not supplying them. case 3: if none of the keyword parameters, EXTEN_NO, XTENSION, EXTNAME, EXTVER, or EXTLEVEL are supplied. FITS_READ will read the next extension in the file. If the primary data unit (PDU), extension 0, is null, the first call to FITS_READ will read the first extension of the file. The only way to read a null PDU is to use EXTEN_NO = 0. If FIRST and LAST are specified, the data is returned without applying any scale factors (BSCALE and BZERO) and the data is returned in a 1-D vector. This will allow you to read any portion of a multiple dimension data set. Once returned, the IDL function REFORM can be used to place the correct dimensions on the data. IMPLICIT IMAGES: FITS_READ will construct an implicit image for cases where NAXIS=0 and the NPIX1, NPIX2, and PIXVALUE keywords are present. The output image will be: image = replicate(PIXVALUE,NPIX1,NPIX2) FPACK compressed files are always closed and reopened when exiting FITS_READ so that the pointer is set to the beginning of the file. (Since FPACK files are opened with a bidirectional pipe rather than OPEN, one cannot use POINT_LUN to move to a specified position in the file.) EXAMPLES: Read the primary data unit of a FITS file, if it is null read the first extension: FITS_READ, 'myfile.fits', data, header Read the first two extensions of a FITS file and the extension with EXTNAME = 'FLUX' and EXTVER = 4 FITS_OPEN, 'myfile.fits', fcb FITS_READ, fcb,data1, header2, exten_no = 1 FITS_READ, fcb,data1, header2, exten_no = 2 FITS_READ, fcb,data3, header3, extname='flux', extver=4 FITS_CLOSE, fcb Read the sixth image in a data cube for the fourth extension. FITS_OPEN, 'myfile.fits', fcb image_number = 6 ns = fcb.axis(0,4) nl = fcb.axis(1,4) i1 = (ns*nl)*(image_number-1) i2 = i2 + ns*nl-1 FITS_READ,fcb,image,header,first=i1,last=i2 image = reform(image,ns,nl,/overwrite) FITS_CLOSE PROCEDURES USED: FITS_CLOSE, FITS_OPEN SXADDPAR, SXDELPAR, SXPAR() WARNINGS: In Sep 2006, FITS_OPEN was modified to open FITS files using the /SWAP_IF_LITTLE_ENDIAN keyword to OPEN, so that subsequent routines (FITS_READ, FITS_WRITE) did not require any byte swapping. An error may result if an pre-Sep 2006 version of FITS_OPEN is used with a post Sep 2006 version of FITS_READ, FITS_WRITE or MODFITS. HISTORY: Written by: D. Lindler, August 1995 Avoid use of !ERR W. Landsman August 1999 Read unsigned datatypes, added /no_unsigned W. Landsman December 1999 Don't call FITS_CLOSE unless fcb is defined W. Landsman January 2000 Set BZERO = 0 for unsigned integer data W. Landsman January 2000 Only call IEEE_TO_HOST if needed W. Landsman February 2000 Ensure EXTEND keyword in primary header W. Landsman April 2001 Don't erase ERROR message when closing file W. Landsman April 2002 Assume at least V5.1 remove NANValue keyword W. Landsman November 2002 Work with compress files (read file size from fcb), requires updated (Jan 2003) version of FITS_OPEN W. Landsman Jan 2003 Do not modify BSCALE/BZERO for unsigned integers W. Landsman April 2006 Asuume FITS_OPEN has opened the file with /SWAP_IF_LITTLE_ENDIAN W. Landsman September 2006 Fix problem with /DATA_ONLY keyword M.Buie/W.Landsman October 2006 Only append primary header if INHERIT=T W. Landsman April 2007 Make ndata 64bit for very large files E. Hivon/W. Landsman May 2007 Added /PDU keyword to always append primary header W. Landsman June 2007 Use PRODUCT to compute # of data points W. Landsman May 2009 Make sure FIRST is long64 when computing position W.L. October 2009 Read FPACK compressed files, W.L. December 2010 Don't assume FCB has a FCOMPRESS tag W.L./Satori UeNO September 2012 (See astrolib/pro/fits_read.pro)
FITS_TEST_CHECKSUM()
[Previous Routine] [Next Routine] [List of Routines]NAME: FITS_TEST_CHECKSUM() PURPOSE: Verify the values of the CHECKSUM and DATASUM keywords in a FITS header EXPLANATION: Follows the 2007 version of the FITS checksum proposal at http://fits.gsfc.nasa.gov/registry/checksum.html CALLING SEQUENCE: result = FITS_TEST_CHECKSUM(HDR, [ DATA, ERRMSG=, /FROM_IEEE ]) INPUTS: HDR - FITS header (vector string) OPTIONAL DATA: DATA - data array associated with the FITS header. If not supplied, or set to a scalar, then there is assumed to be no data array associated with the FITS header. RESULT: An integer -1, 0 or 1 indicating the following conditions: 1 - CHECKSUM (and DATASUM) keywords are present with correct values 0 - CHECKSUM keyword is not present -1 - CHECKSUM or DATASUM keyword does not have the correct value indicating possible data corruption. OPTIONAL INPUT KEYWORD: /FROM_IEEE - If this keyword is set, then the input is assumed to be in big endian format (e.g. an untranslated FITS array). This keyword only has an effect on little endian machines (e.g. a Linux box). OPTIONAL OUTPUT KEYWORD: ERRMSG - will contain a scalar string giving the error condition. If RESULT = 1 then ERRMSG will be an empty string. If this output keyword is not supplied, then the error message will be printed at the terminal. NOTES: The header and data must be *exactly* as originally written in the FITS file. By default, some FITS readers may alter keyword values (e.g. BSCALE) or append information (e.g. HISTORY or an inherited primary header) and this will alter the checksum value. PROCEDURES USED: CHECKSUM32, FITS_ASCII_ENCODE(), SXPAR() EXAMPLE: Verify the CHECKSUM keywords in the primary header/data unit of a FITS file 'test.fits' FITS_READ,'test.fits',data,hdr,/no_PDU,/NoSCALE print,FITS_TEST_CHECKSUM(hdr,data) Note the use of the /No_PDU and /NoSCALE keywords to avoid any alteration of the FITS header REVISION HISTORY: W. Landsman SSAI December 2002 Return quietly if CHECKSUM keywords not found W. Landsman May 2003 Add /NOSAVE to CHECKSUM32 calls when possible W. Landsman Sep 2004(See astrolib/pro/fits_test_checksum.pro)
FITS_WRITE
[Previous Routine] [Next Routine] [List of Routines]NAME: FITS_WRITE PURPOSE: To write a FITS primary data unit or extension. EXPLANATION: ***NOTE** This version of FITS_READ must be used with a post Sep 2006 version of FITS_OPEN. CALLING SEQUENCE: FITS_WRITE, filename_or_fcb, data, [header_in] INPUTS: FILENAME_OR_FCB: name of the output data file or the FITS control block returned by FITS_OPEN (called with the /WRITE or /APPEND) parameters. OPTIONAL INPUTS: DATA: data array to write. If not supplied or set to a scalar, a null image is written. HEADER_IN: FITS header keyword. If not supplied, a minimal basic header will be created. Required FITS keywords, SIMPLE, BITPIX, XTENSION, NAXIS, ... are added by FITS_WRITE and do not need to be supplied with the header. If supplied, their values will be updated as necessary to reflect DATA. INPUT KEYWORD PARAMETERS: XTENSION: type of extension to write (Default="IMAGE"). If not supplied, it will be taken from HEADER_IN. If not in either place, the default is "IMAGE". This parameter is ignored when writing the primary data unit. Note that binary and and ASCII table extensions already have a properly formatted header (e.g. with TTYPE* keywords) and byte array data. EXTNAME: EXTNAME for the extension. If not supplied, it will be taken from HEADER_IN. If not supplied and not in HEADER_IN, no EXTNAME will be written into the output extension. EXTVER: EXTVER for the extension. If not supplied, it will be taken from HEADER_IN. If not supplied and not in HEADER_IN, no EXTVER will be written into the output extension. EXTLEVEL: EXTLEVEL for the extension. If not supplied, it will be taken from HEADER_IN. If not supplied and not in HEADER_IN, no EXTLEVEL will be written into the output extension. /NO_ABORT: Set to return to calling program instead of a RETALL when an I/O error is encountered. If set, the routine will return a non-null string (containing the error message) in the keyword MESSAGE. If /NO_ABORT not set, then FITS_WRITE will print the message and issue a RETALL /NO_DATA: Set if you only want FITS_WRITE to write a header. The header supplied will be written without modification and the user is expected to write the data using WRITEU to unit FCB.UNIT. When FITS_WRITE is called with /NO_DATA, the user is responsible for the validity of the header, and must write the correct amount and format of the data. When FITS_WRITE is used in this fashion, it will pad the data from a previously written extension to 2880 blocks before writting the header. OUTPUT KEYWORD PARAMETERS: MESSAGE: value of the error message for use with /NO_ABORT HEADER: actual output header written to the FITS file. NOTES: If the first call to FITS_WRITE is an extension, FITS_WRITE will automatically write a null image as the primary data unit. Keywords and history in the input header will be properly separated into the primary data unit and extension portions when constructing the output header (See FITS_READ for information on the internal Header format which separates the extension and PDU header portions). EXAMPLES: Write an IDL variable to a FITS file with the minimal required header. FITS_WRITE,'newfile.fits',ARRAY Write the same array as an image extension, with a null Primary data unit. FITS_WRITE,'newfile.fits',ARRAY,xtension='IMAGE' Write 4 additional image extensions to the same file. FITS_OPEN,'newfile.fits',fcb FITS_WRITE,fcb,data1,extname='FLUX',extver=1 FITS_WRITE,fcb,err1,extname'ERR',extver=1 FITS_WRITE,fcb,data2,extname='FLUX',extver=2 FITS_WRITE,fcb,err2,extname='ERR',extver=2 FITS_CLOSE,FCB WARNING: FITS_WRITE currently does not completely update the file control block. When mixing FITS_READ and FITS_WRITE commands it is safer to use file names, rather than passing the file control block. PROCEDURES USED: FITS_OPEN, SXADDPAR, SXDELPAR, SXPAR() HISTORY: Written by: D. Lindler August, 1995 Work for variable length extensions W. Landsman August 1997 Converted to IDL V5.0 W. Landsman September 1997 PCOUNT and GCOUNT added for IMAGE extensions J. Graham October 1999 Write unsigned data types W. Landsman December 1999 Pad data area with zeros not blanks W. McCann/W. Landsman October 2000 Return Message='' to signal normal operation W. Landsman Nov. 2000 Ensure that required extension table keywords are in proper order W.V. Dixon/W. Landsman March 2001 Assume since V5.1, remove NaNValue keyword W. Landsman Nov. 2002 Removed obsolete !ERR system variable W. Landsman Feb 2004 Check that byte array supplied with table extension W. Landsman Mar 2004 Make number of bytes 64bit to avoid possible overflow W.L Apr 2006 Asuume FITS_OPEN has opened the file with /SWAP_IF_LITTLE_ENDIAN W. Landsman September 2006 Removes BZERO and BSCALE for floating point output, D. Lindler, Sep 2008(See astrolib/pro/fits_write.pro)
FLEGENDRE
[Previous Routine] [Next Routine] [List of Routines]NAME: FLEGENDRE PURPOSE: Compute the first M terms in a Legendre polynomial expansion. EXPLANATION: Meant to be used as a supplied function to SVDFIT. This procedure became partially obsolete in IDL V5.0 with the introduction of the /LEGENDRE keyword to SVDFIT and the associated SVDLEG function. However, note that, unlike SVDLEG, FLEGENDRE works on vector values of X. CALLING SEQUENCE: result = FLEGENDRE( X, M) INPUTS: X - the value of the independent variable, scalar or vector M - number of term of the Legendre expansion to compute, integer scalar OUTPUTS: result - (N,M) array, where N is the number of elements in X and M is the order. Contains the value of each Legendre term for each value of X EXAMPLE: (1) If x = 2.88 and M = 3 then IDL> print, flegendre(x,3) ==> [1.00, 2.88, 11.9416] This result can be checked by explicitly computing the first 3 Legendre terms, 1.0, x, 0.5*( 3*x^2 -1) (2) Find the coefficients to an M term Legendre polynomial that gives the best least-squares fit to a dataset (x,y) IDL> coeff = SVDFIT( x,y,M,func='flegendre') The coefficients can then be supplied to the function POLYLEG to compute the best YFIT values for any X. METHOD: The recurrence relation for the Legendre polynomials is used to compute each term. Compare with the function FLEG in "Numerical Recipes" by Press et al. (1992), p. 674 REVISION HISTORY: Written Wayne Landsman Hughes STX April 1995 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/flegendre.pro)
FLUX2MAG
[Previous Routine] [Next Routine] [List of Routines]NAME: FLUX2MAG PURPOSE: Convert from flux (ergs/s/cm^2/A) to magnitudes. EXPLANATION: Use MAG2FLUX() for the opposite direction. CALLING SEQUENCE: mag = flux2mag( flux, [ zero_pt, ABwave= ] ) INPUTS: flux - scalar or vector flux vector, in erg cm-2 s-1 A-1 OPTIONAL INPUT: zero_pt - scalar giving the zero point level of the magnitude. If not supplied then zero_pt = 21.1 (Code et al 1976) Ignored if the ABwave keyword is supplied OPTIONAL KEYWORD INPUT: ABwave - wavelength scalar or vector in Angstroms. If supplied, then FLUX2MAG() returns Oke AB magnitudes (Oke & Gunn 1983, ApJ, 266, 713). OUTPUT: mag - magnitude vector. If the ABwave keyword is set then mag is given by the expression ABMAG = -2.5*alog10(f) - 5*alog10(ABwave) - 2.406 Otherwise, mag is given by the expression mag = -2.5*alog10(flux) - zero_pt EXAMPLE: Suppose one is given wavelength and flux vectors, w (in Angstroms) and f (in erg cm-2 s-1 A-1). Plot the spectrum in AB magnitudes IDL> plot, w, flux2mag(f,ABwave = w), /nozero REVISION HISTORY: Written J. Hill STX Co. 1988 Converted to IDL V5.0 W. Landsman September 1997 Added ABwave keyword W. Landsman September 1998(See astrolib/pro/flux2mag.pro)
FM_UNRED
[Previous Routine] [Next Routine] [List of Routines]NAME: FM_UNRED PURPOSE: Deredden a flux vector using the Fitzpatrick (1999) parameterization EXPLANATION: The R-dependent Galactic extinction curve is that of Fitzpatrick & Massa (Fitzpatrick, 1999, PASP, 111, 63; astro-ph/9809387 ). Parameterization is valid from the IR to the far-UV (3.5 microns to 0.1 microns). UV extinction curve is extrapolated down to 912 Angstroms. CALLING SEQUENCE: FM_UNRED, wave, flux, ebv, [ funred, R_V = , /LMC2, /AVGLMC, ExtCurve= gamma =, x0=, c1=, c2=, c3=, c4= ] 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 dereddened. OUTPUT: FUNRED - unreddened flux vector, same units and number of elements as FLUX OPTIONAL INPUT KEYWORDS R_V - scalar specifying the ratio of total to selective extinction R(V) = A(V) / E(B - V). If not specified, then R = 3.1 Extreme values of R(V) range from 2.3 to 5.3 /AVGLMC - if set, then the default fit parameters c1,c2,c3,c4,gamma,x0 are set to the average values determined for reddening in the general Large Magellanic Cloud (LMC) field by Misselt et al. (1999, ApJ, 515, 128) /LMC2 - if set, then the fit parameters are set to the values determined for the LMC2 field (including 30 Dor) by Misselt et al. Note that neither /AVGLMC or /LMC2 will alter the default value of R_V which is poorly known for the LMC. The following five input keyword parameters allow the user to customize the adopted extinction curve. For example, see Clayton et al. (2003, ApJ, 588, 871) for examples of these parameters in different interstellar environments. x0 - Centroid of 2200 A bump in microns (default = 4.596) gamma - Width of 2200 A bump in microns (default =0.99) c3 - Strength of the 2200 A bump (default = 3.23) c4 - FUV curvature (default = 0.41) c2 - Slope of the linear UV extinction component (default = -0.824 + 4.717/R) c1 - Intercept of the linear UV extinction component (default = 2.030 - 3.007*c2 OPTIONAL OUTPUT KEYWORD: ExtCurve - Returns the E(wave-V)/E(B-V) extinction curve, interpolated onto the input wavelength vector 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> fm_unred, w, f, -0.1, fnew ;Redden (negative E(B-V)) flux vector IDL> plot,w,fnew NOTES: (1) The following comparisons between the FM curve and that of Cardelli, Clayton, & Mathis (1989), (see ccm_unred.pro): (a) - In the UV, the FM and CCM curves are similar for R < 4.0, but diverge for larger R (b) - In the optical region, the FM more closely matches the monochromatic extinction, especially near the R band. (2) Many sightlines with peculiar ultraviolet interstellar extinction can be represented with the FM curve, if the proper value of R(V) is supplied. (3) Use the 4 parameter calling sequence if you wish to save the original flux vector. PROCEDURE CALLS: CSPLINE(), POLY() REVISION HISTORY: Written W. Landsman Raytheon STX October, 1998 Based on FMRCurve by E. Fitzpatrick (Villanova) Added /LMC2 and /AVGLMC keywords, W. Landsman August 2000 Added ExtCurve keyword, J. Wm. Parker August 2000 Assume since V5.4 use COMPLEMENT to WHERE W. Landsman April 2006(See astrolib/pro/fm_unred.pro)
FORPRINT
[Previous Routine] [Next Routine] [List of Routines]NAME: FORPRINT PURPOSE: Print a set of vectors by looping over each index value. EXPLANATION: If W and F are equal length vectors, then the statement IDL> forprint, w, f is equivalent to IDL> for i = 0L, N_elements(w)-1 do print,w[i],f[i] CALLING SEQUENCE: forprint, v1,[ v2, v3, v4,....v18, FORMAT = , TEXTOUT = ,STARTLINE =, SUBSET=, NUMLINE =, /SILENT, COMMENT= ] INPUTS: V1,V2,...V18 - Arbitary IDL vectors. If the vectors are not of equal length then the number of rows printed will be equal to the length of the smallest vector. Up to 18 vectors can be supplied. OPTIONAL KEYWORD INPUTS: TEXTOUT - Controls print output device, defaults to !TEXTOUT textout=1 TERMINAL using /more option if available textout=2 TERMINAL without /more option textout=3 file 'forprint.prt' textout=4 file 'laser.tmp' textout=5 user must open file textout = filename (default extension of .prt) textout=7 Append to.prt file if it exists COMMENT - String scalar or vector to write to the first line of output file if TEXTOUT > 2. By default, FORPRINT will write a time stamp on the first line. Use /NOCOMMENT if you don't want FORPRINT to write anything in the output file. If COMMENT is a vector then one line will be written for each element. FORMAT - Scalar format string as in the PRINT procedure. The use of outer parenthesis is optional. Ex. - format="(F10.3,I7)" This program will automatically remove a leading "$" from incoming format statements. Ex. - "$(I4)" would become "(I4)". If omitted, then IDL default formats are used. /NOCOMMENT - Set this keyword if you don't want any comment line line written as the first line in a harcopy output file. /SILENT - Normally, with a hardcopy output (TEXTOUT > 2), FORPRINT will print an informational message. If the SILENT keyword is set and non-zero, then this message is suppressed. SUBSET - Index vector specifying elements to print. No error checking is done to make sure the indicies are valid. The statement IDL> forprint,x,y,z,subset=s is equivalent to IDL> for i=0,n-1 do print, x[s[i]], y[s[i]], z[s[i]] STARTLINE - Integer scalar specifying the first line in the arrays to print. Default is STARTLINE = 1, i.e. start at the beginning of the arrays. (If a SUBSET keyword is supplied then STARTLINE refers to first element in the subscript vector.) /STDOUT - If set, the force standard output unit (=-1) if not writing to a file. This allows the FORPINT output to be captured in a journal file. Only needed for non-GUI terminals WIDTH - Line width for wrapping, passed onto OPENW when using hardcopy. OUTPUTS: None SYSTEM VARIABLES: If keyword TEXTOUT is not used, the default is the nonstandard keyword !TEXTOUT. If you want to use FORPRINT to write more than once to the same file then set TEXTOUT=5, and open and close the file yourself (see documentation of TEXTOPEN for more info). The non-standard system variables !TEXTOUT and !TEXTUNIT are automatically added if not present to start with. EXAMPLE: Suppose W,F, and E are the wavelength, flux, and epsilon vectors for a spectrum. Print these values to a file 'output.dat' in a nice format. IDL> fmt = '(F10.3,1PE12.2,I7)' IDL> forprint, F = fmt, w, f, e, TEXT = 'output.dat' RESTRICTIONS: Uses the EXECUTE() function and so is not compatible with the IDL virtual machine. PROCEDURES CALLED: TEXTOPEN, TEXTCLOSE REVISION HISTORY: Written W. Landsman April, 1989 Keywords textout and format added, J. Isensee, July, 1990 Made use of parenthesis in FORMAT optional W. Landsman May 1992 Added STARTLINE keyword W. Landsman November 1992 Set up so can handle 18 input vectors. J. Isensee, HSTX Corp. July 1993 Handle string value of TEXTOUT W. Landsman, HSTX September 1993 Added NUMLINE keyword W. Landsman, HSTX February 1996 Added SILENT keyword W. Landsman, RSTX, April 1998 Much faster printing to a file W. Landsman, RITSS, August, 2001 Use SIZE(/TNAME) instead of DATATYPE() W. Landsman SSAI October 2001 Fix skipping of first line bug introduced Aug 2001 W. Landsman Nov2001 Added /NOCOMMENT keyword, the SILENT keyword now controls only the display of informational messages. W. Landsman June 2002 Skip PRINTF if IDL in demo mode W. Landsman October 2004 Assume since V5.4 use BREAK instead of GOTO W. Landsman April 2006 Add SUBSET keyword, warning if different size vectors passed. P.Broos,W.Landsman. Aug 2006 Change keyword_set() to N_elements W. Landsman Oct 2006 Added /STDOUT keyword W. Landsman Oct 2006 Fix error message for undefined variable W. Landsman April 2007 Added WIDTH keyword J. Bailin Nov 2010 Allow multiple (vector) comment lines W. Landsman April 2011 Define !TEXTOUT and !TEXTUNIT if needed. W. Landsman October 2012 (See astrolib/pro/forprint.pro)
FREBIN
[Previous Routine] [Next Routine] [List of Routines]NAME: FREBIN PURPOSE: Shrink or expand the size of an array an arbitary amount using interpolation EXPLANATION: FREBIN is an alternative to CONGRID or REBIN. Like CONGRID it allows expansion or contraction by an arbitary amount. ( REBIN requires integral factors of the original image size.) Like REBIN it conserves flux by ensuring that each input pixel is equally represented in the output array. CALLING SEQUENCE: result = FREBIN( image, nsout, nlout, [ /TOTAL] ) INPUTS: image - input image, 1-d or 2-d numeric array nsout - number of samples in the output image, numeric scalar OPTIONAL INPUT: nlout - number of lines in the output image, numeric scalar If not supplied, then set equal to 1 OPTIONAL KEYWORD INPUTS: /total - if set, the output pixels will be the sum of pixels within the appropriate box of the input image. Otherwise they will be the average. Use of the /TOTAL keyword conserves surface flux. OUTPUTS: The resized image is returned as the function result. If the input image is of type DOUBLE or FLOAT then the resized image is of the same type. If the input image is BYTE, INTEGER or LONG then the output image is usually of type FLOAT. The one exception is expansion by integral amount (pixel duplication), when the output image is the same type as the input image. EXAMPLE: Suppose one has an 800 x 800 image array, im, that must be expanded to a size 850 x 900 while conserving surface flux: IDL> im1 = frebin(im,850,900,/total) im1 will be a 850 x 900 array, and total(im1) = total(im) NOTES: If the input image sizes are a multiple of the output image sizes then FREBIN is equivalent to the IDL REBIN function for compression, and simple pixel duplication on expansion. If the number of output pixels are not integers, the output image size will be truncated to an integer. The platescale, however, will reflect the non-integer number of pixels. For example, if you want to bin a 100 x 100 integer image such that each output pixel is 3.1 input pixels in each direction use: n = 100/3.1 ; 32.2581 image_out = frebin(image,n,n) The output image will be 32 x 32 and a small portion at the trailing edges of the input image will be ignored. PROCEDURE CALLS: None. HISTORY: Adapted from May 1998 STIS version, written D. Lindler, ACC Added /NOZERO, use INTERPOLATE instead of CONGRID, June 98 W. Landsman Fixed for nsout non-integral but a multiple of image size Aug 98 D.Lindler DJL, Oct 20, 1998, Modified to work for floating point image sizes when expanding the image. Improve speed by addressing arrays in memory order W.Landsman Dec/Jan 2001(See astrolib/pro/frebin.pro)
FTAB_DELROW
[Previous Routine] [Next Routine] [List of Routines]NAME: FTAB_DELROW PURPOSE: Delete rows of data from a FITS ASCII or binary table extension CALLING SEQUENCE: ftab_delrow, filename, rows, EXTEN_NO =, NEWFILE = ] INPUTS-OUPUTS filename - scalar string giving name of the FITS file containing an ASCII or binary table extension. rows - scalar or vector, specifying the row numbers to delete First row has index 0. If a vector, it will be sorted and duplicates will be removed OPTIONAL KEYWORD INPUTS: EXTEN_NO - scalar integer specifying which extension number to process Default is to process the first extension NEWFILE - scalar string specifying the name of the new output FITS file FTAB_DELROW will prompt for this parameter if not supplied EXAMPLE: Compress the first extension of a FITS file 'test.fits' to include only non-negative values in the 'FLUX' column ftab_ext,'test.fits','flux',flux ;Obtain original flux vector bad = where(flux lt 0) ;Find negative fluxes ftab_delrow,'test.fits',bad,new='test1.fits' ;Delete specified rows RESTRICTIONS: Does not work for variable length binary tables PROCEDURES USED: FITS_CLOSE, FITS_OPEN, FITS_READ, FITS_WRITE, FTDELROW, TBDELROW REVISION HISTORY: Written W. Landsman STX Co. August, 1997 Converted to IDL V5.0 W. Landsman September 1997 Use COPY_LUN if V5.6 or later W. Landsman February 2003 Assume since V5.6, COPY_LUN available W. Landsman Sep 2006(See astrolib/pro/ftab_delrow.pro)
FTAB_EXT
[Previous Routine] [Next Routine] [List of Routines]NAME: FTAB_EXT PURPOSE: Routine to extract columns from a FITS (binary or ASCII) table. CALLING SEQUENCE: FTAB_EXT, name_or_fcb, columns, v1, [v2,..,v9, ROWS=, EXTEN_NO= ] INPUTS: name_or_fcb - either a scalar string giving the name of a FITS file containing a (binary or ASCII) table, or an IDL structure containing as file control block (FCB) returned by FITS_OPEN If FTAB_EXT is to be called repeatedly on the same file, then it is quicker to first open the file with FITS_OPEN, and then pass the FCB structure to FTAB_EXT columns - table columns to extract. Can be either (1) String with names separated by commas (2) Scalar or vector of column numbers OUTPUTS: v1,...,v30 - values for the columns. Up to 30 columns can be extracted OPTIONAL INPUT KEYWORDS: ROWS - scalar or vector giving row number(s) to extract Row numbers start at 0. If not supplied or set to -1 then values for all rows are returned EXTEN_NO - Extension number to process. If not set, then data is extracted from the first extension in the file (EXTEN_NO=1) EXAMPLES: Read wavelength and flux vectors from the first extension of a FITS file, 'spec.fit'. Using FTAB_HELP,'spec.fit' we find that this information is in columns named 'WAVELENGTH' and 'FLUX' (in columns 1 and 2). To read the data IDL> ftab_ext,'spec.fit','wavelength,flux',w,f or IDL> ftab_ext,'spec.fit',[1,2],w,f PROCEDURES CALLED: FITS_READ, FITS_CLOSE, FTINFO, FTGET(), TBINFO, TBGET() HISTORY: version 1 W. Landsman August 1997 Converted to IDL V5.0 W. Landsman September 1997 Improve speed processing binary tables W. Landsman March 2000 Use new FTINFO calling sequence W. Landsman May 2000 Don't call fits_close if fcb supplied W. Landsman May 2001 Use STRSPLIT to parse column string W. Landsman July 2002 Cleanup pointers in TBINFO structure W. Landsman November 2003 Avoid EXECUTE() if V6.1 or later W. Landsamn December 2006 Assume since V6.1 W. Landsman June 2009 Read up to 30 columns W.L. Aug 2009(See astrolib/pro/ftab_ext.pro)
FTAB_HELP
[Previous Routine] [Next Routine] [List of Routines]NAME: FTAB_HELP PURPOSE: Describe the columns of a FITS binary or ASCII table extension(s). CALLING SEQUENCE: FTAB_HELP, filename, [ EXTEN_No = , TEXTOUT= ] or FTAB_HELP, fcb, [EXTEN_No=, TEXTOUT= ] INPUTS: filename - scalar string giving name of the FITS file. fcb - FITS control block returned by a previous call to FITS_OPEN OPTIONAL KEYWORD INPUTS: EXTEN_NO - integer scalar or vector specifying which FITS extensions to display. Default is to display all FITS extension. TEXTOUT - scalar number (0-7) or string (file name) determining output device (see TEXTOPEN). Default is TEXTOUT=1, output to the user's terminal EXAMPLE: Describe the columns in the second and fourth extensions of a FITS file spec.fits and write the results to a file 'spec24.lis' IDL> ftab_help,'spec.fits',exten=[2,4],t='spec24.lis' SYSTEM VARIABLES: Uses the non-standard system variables !TEXTOUT and !TEXTUNIT which must be defined (e.g. with ASTROLIB) before compilation NOTES: The behavior of FTAB_HELP was changed in August 2005 to display all extensions by default, rather than just the first extension PROCEDURES USED: FITS_READ, FITS_CLOSE, FITS_OPEN, FTHELP, TBHELP, TEXTOPEN, TEXTCLOSE HISTORY: version 1 W. Landsman August 1997 Corrected documentation W. Landsman September 1997 Don't call fits_close if fcb supplied W. Landsman May 2001 Default now is to display all extensions, EXTEN keyword can now be a vector W. Landsman Aug 2005(See astrolib/pro/ftab_help.pro)
FTAB_PRINT
[Previous Routine] [Next Routine] [List of Routines]NAME: FTAB_PRINT PURPOSE: Print the contents of a FITS (binary or ASCII) table extension. EXPLANATION: User can specify which rows or columns to print CALLING SEQUENCE: FTAB_PRINT, filename, columns, rows, [ TEXTOUT=, FMT=, EXTEN_NO= NUM_HEADER_LINES ] INPUTS: filename - scalar string giving name of a FITS file containing a binary or ASCII table columns - string giving column names, or vector giving column numbers (beginning with 1). If a string supplied then column names should be separated by comma's. if not supplied, then all columns are printed. If set to '*' then all columns are printed in table format (1 row per line, binary tables only). rows - (optional) vector of row numbers to print (beginning with 0). If not supplied or set to scalar, -1, then all rows are printed. OPTIONAL KEYWORD INPUT: EXTEN_NO - Extension number to read. If not set, then the first extension is printed (EXTEN_NO=1) FMT = Format string for print display (binary tables only). If not supplied, then any formats in the TDISP keyword fields will be used, otherwise IDL default formats. For ASCII tables, the format used is always as stored in the FITS table. NUM_HEADER_LINES - Number of lines to display the column headers (default = 1). By setting NUM_HEADER_LINES to an integer larger than 1, one can avoid truncation of the headers. In addition, setting NUM_HEADER_LINES will display commented lines indicating a FORMAT for reading the data, and a suggested call to readfmt.pro. Works for binary tables only NVAL_PER_LINE - The maximum number of values displayed from a multivalued column when printing in table format. Default = 6 TEXTOUT - scalar number (0-7) or string (file name) determining output device (see TEXTOPEN). Default is TEXTOUT=1, output to the user's terminal EXAMPLE: (1) Print all rows of the first 5 columns of the first extension of the file 'wfpc.fits' IDL> ftab_print,'vizier.fits',indgen(5)+1 (2) Print all columns of the first row to a file 'vizier.dat' in 'table' format IDL> ftab_print,'vizier.fits',t='vizier.dat','*',0 SYSTEM VARIABLES: Uses the non-standard system variables !TEXTOUT and !TEXTUNIT which must be defined (e.g. with ASTROLIB) prior to compilation. PROCEDURES USED: FITS_CLOSE, FITS_OPEN, FITS_READ, FTPRINT, TBPRINT HISTORY: version 1 W. Landsman August 1997 Check whether data exists W. Landsman Feb 2007 Check whether extension exists W. Landsman Mar 2010 Added NUM_HEADER_LINES, NVAL_PER_LINE keywords for binary tables W. Landsman Apr 2010(See astrolib/pro/ftab_print.pro)
FTADDCOL
[Previous Routine] [Next Routine] [List of Routines]NAME: FTADDCOL PURPOSE: Routine to add a field to a FITS ASCII table CALLING SEQUENCE: ftaddcol, h, tab, name, idltype, [ tform, tunit, tscal, tzero, tnull ] INPUTS: h - FITS table header. It will be updated as appropriate tab - FITS table array. Number of columns will be increased if neccessary. name - field name, scalar string idltype - idl data type (as returned by SIZE function) for field, For string data (type=7) use minus the string length. OPTIONAL INPUTS: tform - format specification 'qww.dd' where q = A, I, E, or D tunit - string giving physical units for the column. tscal - scale factor tzero - zero point for field tnull - null value for field Use '' as the value of tform,tunit,tscal,tzero,tnull if you want the default or no specification of them in the table header. OUTPUTS: h,tab - updated to allow new column of data PROCEDURES USED: FTINFO, FTSIZE, GETTOK(), SXADDPAR HISTORY: version 1 D. Lindler July, 1987 Converted to IDL V5.0 W. Landsman September 1997 Updated call to new FTINFO W. Landsman April 2000(See astrolib/pro/ftaddcol.pro)
FTCREATE
[Previous Routine] [Next Routine] [List of Routines]NAME: FTCREATE PURPOSE: Create a new (blank) FITS ASCII table and header with specified size. CALLING SEQUENCE: ftcreate, maxcols, maxrows, h, tab INPUTS: maxcols - number of character columns allocated, integer scalar maxrows - maximum number of rows allocated, integer scalar OUTPUTS: h - minimal FITS Table extension header, string array OPTIONAL OUTPUT: tab - empty table, byte array HISTORY: version 1 D. Lindler July. 87 Converted to IDL V5.0 W. Landsman September 1997 Make table creation optional, allow 1 row table, add comments to required FITS keywords W. Landsman October 2001(See astrolib/pro/ftcreate.pro)
FTDELCOL
[Previous Routine] [Next Routine] [List of Routines]NAME: FTDELCOL PURPOSE: Delete a column of data from a FITS table CALLING SEQUENCE: ftdelcol, h, tab, name INPUTS-OUPUTS h,tab - FITS table header and data array. H and TAB will be updated with the specified column deleted INPUTS: name - Either (1) a string giving the name of the column to delete or (2) a scalar giving the column number to delete EXAMPLE: Suppose it has been determined that the F7.2 format used for a field FLUX in a FITS table is insufficient. The old column must first be deleted before a new column can be written with a new format. flux = FTGET(h,tab,'FLUX') ;Save the existing values FTDELCOL,h,tab,'FLUX' ;Delete the existing column FTADDCOL,h,tab,'FLUX',8,'F9.2' ;Create a new column with larger format FTPUT,h,tab,'FLUX',0,flux ;Put back the original values REVISION HISTORY: Written W. Landsman STX Co. August, 1988 Adapted for IDL Version 2, J. Isensee, July, 1990 Converted to IDL V5.0 W. Landsman September 1997 Updated call to new FTINFO W. Landsman May 2000(See astrolib/pro/ftdelcol.pro)
FTDELROW
[Previous Routine] [Next Routine] [List of Routines]NAME: FTDELROW PURPOSE: Delete a row of data from a FITS table CALLING SEQUENCE: ftdelrow, h, tab, rows INPUTS-OUPUTS h,tab - FITS table header and data array. H and TAB will be updated on output with the specified row(s) deleted. rows - scalar or vector, specifying the row numbers to delete This vector will be sorted and duplicates removed by FTDELROW EXAMPLE: Compress a table to include only non-negative flux values flux = FTGET(h,tab,'FLUX') ;Obtain original flux vector bad = where(flux lt 0) ;Find negative fluxes FTDELROW,h,tab,bad ;Delete rows with negative fluxes PROCEDURE: Specified rows are deleted from the data array, TAB. The NAXIS2 keyword in the header is updated. PROCEDURES USED: sxaddpar REVISION HISTORY: Written W. Landsman STX Co. August, 1988 Checked for IDL Version 2, J. Isensee, July, 1990 Converted to IDL V5.0 W. Landsman September 1997 Assume since V5.4, use BREAK instead of GOTO W. Landsman April 2006(See astrolib/pro/ftdelrow.pro)
FTGET
[Previous Routine] [Next Routine] [List of Routines]NAME: FTGET PURPOSE: Function to return value(s) from specified column in a FITS ASCII table CALLING SEQUENCE values = FTGET( h, tab, field, [ rows, nulls ] ) or values = FTGET( ft_str, tab, field. [rows, nulls] INPUTS: h - FITS ASCII extension header (e.g. as returned by FITS_READ) or ft_str - FITS table structure extracted from FITS header by FTINFO Use of the IDL structure will improve processing speed tab - FITS ASCII table array (e.g. as returned by FITS_READ) field - field name or number OPTIONAL INPUTS: rows - scalar or vector giving row number(s) Row numbers start at 0. If not supplied or set to -1 then values for all rows are returned OUTPUTS: the values for the row are returned as the function value. Null values are set to 0 or blanks for strings. OPTIONAL OUTPUT: nulls - null value flag of same length as the returned data. It is set to 1 at null value positions and 0 elsewhere. If supplied then the optional input, rows, must also be supplied. EXAMPLE: Read the columns labeled 'WAVELENGTH' and 'FLUX' from the second (ASCII table) extension of a FITS file 'spectra.fit' IDL> fits_read,'spectra.fit',tab,htab,exten=2 ;Read 2nd extension IDL> w = ftget( htab, tab,'wavelength') ;Wavelength vector IDL> f = ftget( htab, tab,'flux') ;Flux vector Slightly more efficient would be to first call FTINFO IDL> ftinfo, htab, ft_str ;Extract structure IDL> w = ftget(ft_str, tab,'wavelength') ;Wavelength vector IDL> f = ftget(ft_str, tab,'flux') ;Flux vector NOTES: (1) Use the higher-level procedure FTAB_EXT to extract vectors directly from the FITS file. (2) Use FTAB_HELP or FTHELP to determine the columns in a particular ASCII table. HISTORY: coded by D. Lindler July, 1987 Always check for null values W. Landsman August 1990 More informative error message W. Landsman Feb. 1996 Converted to IDL V5.0 W. Landsman September 1997 Allow structure rather than FITS header W. Landsman May 2000 No case sensitivity in TTYPE name W. Landsman February 2002(See astrolib/pro/ftget.pro)
FTHELP
[Previous Routine] [Next Routine] [List of Routines]NAME: FTHELP PURPOSE: Routine to print a description of a FITS ASCII table extension CALLING SEQUENCE: FTHELP, H, [ TEXTOUT = ] INPUTS: H - FITS header for ASCII table extension, string array OPTIONAL INPUT KEYWORD TEXTOUT - scalar number (0-7) or string (file name) determining output device (see TEXTOPEN). Default is TEXTOUT=1, output to the user's terminal NOTES: FTHELP checks that the keyword XTENSION equals 'TABLE' in the FITS header. SYSTEM VARIABLES: Uses the non-standard system variables !TEXTOUT and !TEXTUNIT which must be defined (e.g. with ASTROLIB) prior to compilation. PROCEDURES USED: REMCHAR, SXPAR(), TEXTOPEN, TEXTCLOSE, ZPARCHECK HISTORY: version 1 W. Landsman Jan. 1988 Add TEXTOUT option, cleaner format W. Landsman September 1991 TTYPE value can be longer than 8 chars, W. Landsman August 1995 Remove calls to !ERR, some vectorization W. Landsman February 2000 Slightly more compact display W. Landsman August 2005(See astrolib/pro/fthelp.pro)
FTHMOD
[Previous Routine] [Next Routine] [List of Routines]NAME: FTHMOD PURPOSE: Procedure to modify header information for a specified field in a FITS table. CALLING SEQUENCE: fthmod, h, field, parameter, value INPUT: h - FITS header for the table field - field name or number parameter - string name of the parameter to modify. Choices include: TTYPE - field name TUNIT - physical units for field (eg. 'ANGSTROMS') TNULL - null value (string) for field, (eg. '***') TFORM - format specification for the field TSCAL - scale factor TZERO - zero offset User should be aware that the validity of the change is not checked. Unless you really know what you are doing, this routine should only be used to change field names, units, or another user specified parameter. value - new value for the parameter. Refer to the FITS table standards documentation for valid values. EXAMPLE: Change the units for a field name "FLUX" to "Janskys" in a FITS table header,h IDL> FTHMOD, h, 'FLUX', 'TUNIT','Janskys' METHOD: The header keywordis modified with the new value. HISTORY: version 1, D. Lindler July 1987 Converted to IDL V5.0 W. Landsman September 1997 Major rewrite to use new FTINFO call W. Landsman May 2000 (See astrolib/pro/fthmod.pro)
FTINFO
[Previous Routine] [Next Routine] [List of Routines]NAME: FTINFO PURPOSE: Return an informational structure from a FITS ASCII table header. CALLING SEQUENCE: ftinfo,h,ft_str, [Count = ] INPUTS: h - FITS ASCII table header, string array OUTPUTS: ft_str - IDL structure with extracted info from the FITS ASCII table header. Tags include .tbcol - starting column position in bytes .width - width of the field in bytes .idltype - idltype of field. 7 - string, 4- real*4, 3-integer, 5-real*8 .tunit - string unit numbers .tscal - scale factor .tzero - zero point for field .tnull - null value for the field .tform - format for the field .ttype - field name OPTIONAL OUTPUT KEYWORD: Count - Integer scalar giving number of fields in the table PROCEDURES USED: GETTOK(), SXPAR() NOTES: This procedure underwent a major revision in May 2000, and **THE NEW CALLING SEQUENCE IS INCOMPATIBLE WITH THE OLD ONE ** HISTORY: D. Lindler July, 1987 Converted to IDL V5.0 W. Landsman September 1997 Major rewrite, return structure W. Landsman April 2000(See astrolib/pro/ftinfo.pro)
FTKEEPROW
[Previous Routine] [Next Routine] [List of Routines]NAME: FTKEEPROW PURPOSE: Subscripts (and reorders) a FITS table. A companion piece to FTDELROW. CALLING SEQUENCE: ftkeeprow, h, tab, subs INPUT PARAMETERS: h = FITS table header array tab = FITS table data array subs = subscript array of FITS table rows. Works like any other IDL subscript array (0 based, of course). OUTPUT PARAMETERS: h and tab are modified MODIFICATION HISTORY: Written by R. S. Hill, ST Sys. Corp., 2 May 1991. Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/ftkeeprow.pro)
FTPRINT
[Previous Routine] [Next Routine] [List of Routines]NAME: FTPRINT PURPOSE: Procedure to print specified columns and rows of a FITS table CALLING SEQUENCE: FTPRINT, h, tab, columns, [ rows, TEXTOUT = ] INPUTS: h - Fits header for table, string array tab - table array columns - string giving column names, or vector giving column numbers (beginning with 1). If string supplied then column names should be separated by comma's. rows - (optional) vector of row numbers to print. If not supplied or set to scalar, -1, then all rows are printed. OUTPUTS: None OPTIONAL INPUT KEYWORDS: TEXTOUT controls the output device; see the procedure TEXTOPEN SYSTEM VARIABLES: Uses nonstandard system variables !TEXTOUT and !TEXTOPEN These will be defined (using ASTROLIB) if not already present. Set !TEXTOUT = 3 to direct output to a disk file. The system variable is overriden by the value of the keyword TEXTOUT EXAMPLES: ftprint,h,tab,'STAR ID,RA,DEC' ;print id,ra,dec for all stars ftprint,h,tab,[2,3,4],indgen(100) ;print columns 2-4 for ;first 100 stars ftprint,h,tab,text="stars.dat" ;Convert entire FITS table to ;an ASCII file named STARS.DAT PROCEDURES USED: FTSIZE, FTINFO, TEXTOPEN, TEXTCLOSE RESTRICTIONS: (1) Program does not check whether output length exceeds output device capacity (e.g. 80 or 132). (2) Column heading may be truncated to fit in space defined by the FORMAT specified for the column (3) Program does not check for null values HISTORY: version 1 D. Lindler Feb. 1987 Accept undefined values of rows, columns W. Landsman August 1997 New FTINFO calling sequence W. Landsman May 2000 Parse scalar string with STRSPLIT W. Landsman July 2002 Fix format display of row number W. Landsman March 2003 Fix format display of row number again W. Landsman May 2003(See astrolib/pro/ftprint.pro)
FTPUT
[Previous Routine] [Next Routine] [List of Routines]NAME: FTPUT PURPOSE: Procedure to add or update a field in an FITS ASCII table CALLING SEQUENCE: FTPUT, htab, tab, field, row, values, [ nulls ] INPUTS: htab - FITS ASCII table header string array tab - FITS ASCII table array (e.g. as read by READFITS) field - string field name or integer field number row - either a non-negative integer scalar giving starting row to update, or a non-negative integer vector specifying rows to update. FTPUT will append a new row to a table if the value of 'row' exceeds the number of rows in the tab array values - value(s) to add or update. If row is a vector then values must contain the same number of elements. OPTIONAL INPUT: nulls - null value flag of same length as values. It should be set to 1 at null value positions and 0 elsewhere. OUTPUTS: htab,tab will be updated as specified. EXAMPLE: One has a NAME and RA and Dec vectors for 500 stars with formats A6, F9.5 and F9.5 respectively. Write this information to an ASCII table named 'star.fits'. IDL> FTCREATE,24,500,h,tab ;Create table header and (empty) data IDL> FTADDCOL,h,tab,'RA',8,'F9.5','DEGREES' ;Explicity define the IDL> FTADDCOL,h,tab,'DEC',8,'F9.5','DEGREES' ;RA and Dec columns IDL> FTPUT,h,tab,'RA',0,ra ;Insert RA vector into table IDL> FTPUT,h,tab,'DEC',0,dec ;Insert DEC vector into table IDL> FTPUT, h,tab, 'NAME',0,name ;Insert NAME vector with default IDL> WRITEFITS,'stars.fits',tab,h ;Write to a file Note that (1) explicit formatting has been supplied for the (numeric) RA and Dec vectors, but was not needed for the NAME vector, (2) A width of 24 was supplied in FTCREATE based on the expected formats (6+9+9), though the FT* will adjust this value as necessary, and (3) WRITEFITS will create a minimal primary header NOTES: (1) If the specified field is not already in the table, then FTPUT will create a new column for that field using default formatting. However, FTADDCOL should be called prior to FTPUT for explicit formatting. PROCEDURES CALLED FTADDCOL, FTINFO, FTSIZE, SXADDPAR, SXPAR() HISTORY: version 1 D. Lindler July, 1987 Allow E format W. Landsman March 1992 Write in F format if E format will overflow April 1994 Update documentation W. Landsman January 1996 Allow 1 element vector W. Landsman March 1996 Adjust string length to maximum of input string array June 1997 Work for more than 32767 elements August 1997 Converted to IDL V5.0 W. Landsman September 1997 Updated call to the new FTINFO W. Landsman May 2000 Fix case where header does not have any columns yet W.Landsman Sep 2002 Assume since V5.2, omit fstring() call W. Landsman April 2006(See astrolib/pro/ftput.pro)
FTSIZE
[Previous Routine] [Next Routine] [List of Routines]NAME: FTSIZE PURPOSE: Procedure to return the size of a FITS ASCII table. CALLING SEQUENCE: ftsize,h,tab,ncols,rows,tfields,ncols_all,nrows_all, [ERRMSG = ] INPUTS: h - FITS ASCII table header, string array tab - FITS table array, 2-d byte array OUTPUTS: ncols - number of characters per row in table nrows - number of rows in table tfields - number of fields per row ncols_all - number of characters/row allocated (size of tab) nrows_all - number of rows allocated OPTIONAL OUTPUT KEYWORD: ERRMSG = If this keyword is present, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. HISTORY D. Lindler July, 1987 Fix for 1-row table, W. Landsman HSTX, June 1994 Converted to IDL V5.0 W. Landsman September 1997 Added ERRMSG keyword W. Landsman May 2000(See astrolib/pro/ftsize.pro)
FTSORT
[Previous Routine] [Next Routine] [List of Routines]NAME: FTSORT PURPOSE: Sort a FITS ASCII table according to a specified field CALLING SEQUENCE: FTSORT,h,tab,[field, REVERSE = ] ;Sort original table header and array or FTSORT,h,tab,hnew,tabnew,[field, REVERSE =] ;Create new sorted header INPUTS: H - FITS header (string array) TAB - FITS table (byte array) associated with H. If less than 4 parameters are supplied, then H and TAB will be updated to contain the sorted table OPTIONAL INPUTS: FIELD - Field name(s) or number(s) used to sort the entire table. If FIELD is a vector then the first element is used for the primary sort, the second element is used for the secondary sort, and so forth. (A secondary sort only takes effect when values in the primary sort field are equal.) Character fields are sorted using the ASCII collating sequence. If omitted, the user will be prompted for the field name. OPTIONAL OUTPUTS: HNEW,TABNEW - Header and table containing the sorted tables EXAMPLE: Sort a FITS ASCII table by the 'DECLINATION' field in descending order Assume that the table header htab, and array, tab, have already been read (e.g. with READFITS or FITS_READ): IDL> FTSORT, htab, tab,'DECLINATION',/REVERSE OPTIONAL INPUT KEYWORD: REVERSE - If set then the table is sorted in reverse order (maximum to minimum. If FIELD is a vector, then REVERSE can also be a vector. For example, REVERSE = [1,0] indicates that the primary sort should be in descending order, and the secondary sort should be in ascending order. EXAMPLE: SIDE EFFECTS: A HISTORY record is added to the table header. REVISION HISTORY: Written W. Landsman June, 1988 Converted to IDL V5.0 W. Landsman September 1997 New FTINFO calling sequence, added REVERSE keyword, allow secondary sorts W. Landsman May 2000(See astrolib/pro/ftsort.pro)
FXADDPAR
[Previous Routine] [Next Routine] [List of Routines]NAME: FXADDPAR Purpose : Add or modify a parameter in a FITS header array. Explanation : This version of FXADDPAR will write string values longer than 68 characters using the FITS continuation convention described at http://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/ofwg_recomm/r13.html Use : FXADDPAR, HEADER, NAME, VALUE, COMMENT Inputs : HEADER = String array containing FITS header. The maximum string length must be equal to 80. If not defined, then FXADDPAR will create an empty FITS header array. NAME = Name of parameter. If NAME is already in the header the value and possibly comment fields are modified. Otherwise a new record is added to the header. If NAME is equal to either "COMMENT" or "HISTORY" then the value will be added to the record without replacement. In this case the comment parameter is ignored. VALUE = Value for parameter. The value expression must be of the correct type, e.g. integer, floating or string. String values of 'T' or 'F' are considered logical values unless the /NOLOGICAL keyword is set. If the value is a string and is "long" (more than 69 characters), then it may be continued over more than one line using the OGIP CONTINUE standard. Opt. Inputs : COMMENT = String field. The '/' is added by this routine. Added starting in position 31. If not supplied, or set equal to '' (the null string), then any previous comment field in the header for that keyword is retained (when found). Outputs : HEADER = Updated header array. Opt. Outputs: None. Keywords : BEFORE = Keyword string name. The parameter will be placed before the location of this keyword. For example, if BEFORE='HISTORY' then the parameter will be placed before the first history location. This applies only when adding a new keyword; keywords already in the header are kept in the same position. AFTER = Same as BEFORE, but the parameter will be placed after the location of this keyword. This keyword takes precedence over BEFORE. FORMAT = Specifies FORTRAN-like format for parameter, e.g. "F7.3". A scalar string should be used. For complex numbers the format should be defined so that it can be applied separately to the real and imaginary parts. If not supplied, then the IDL default formatting is used, except that double precision is given a format of G19.12. /NOCONTINUE = By default, FXADDPAR will break strings longer than 68 characters into multiple lines using the continuation convention. If this keyword is set, then the line will instead be truncated to 68 characters. This was the default behaviour of FXADDPAR prior to December 1999. /NOLOGICAL = If set, then the values 'T' and 'F' are not interpreted as logical values, and are simply added without interpretation. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL, e.g. ERRMSG = '' FXADDPAR, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : DETABIFY(), FXPAR(), FXPARPOS() Common : None. Restrictions: Warning -- Parameters and names are not checked against valid FITS parameter names, values and types. The required FITS keywords SIMPLE (or XTENSION), BITPIX, NAXIS, NAXIS1, NAXIS2, etc., must be entered in order. The actual values of these keywords are not checked for legality and consistency, however. Side effects: All HISTORY records are inserted in order at the end of the header. All COMMENT records are also inserted in order at the end of the header, but before the HISTORY records. The BEFORE and AFTER keywords can override this. All records with no keyword (blank) are inserted in order at the end of the header, but before the COMMENT and HISTORY records. The BEFORE and AFTER keywords can override this. All other records are inserted before any of the HISTORY, COMMENT, or "blank" records. The BEFORE and AFTER keywords can override this. String values longer than 68 characters will be split into multiple lines using the OGIP CONTINUE convention, unless the /NOCONTINUE keyword is set. For a description of the CONTINUE convention see http://fits.gsfc.nasa.gov/registry/continue_keyword.html Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Jan 1992, from SXADDPAR by D. Lindler and J. Isensee. Differences include: * LOCATION parameter replaced with keywords BEFORE and AFTER. * Support for COMMENT and "blank" FITS keywords. * Better support for standard FITS formatting of string and complex values. * Built-in knowledge of the proper position of required keywords in FITS (although not necessarily SDAS/Geis) primary headers, and in TABLE and BINTABLE extension headers. William Thompson, May 1992, fixed bug when extending length of header, and new record is COMMENT, HISTORY, or blank. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 5 September 1997 Fixed bug replacing strings that contain "/" character--it interpreted the following characters as a comment. Version 3, Craig Markwardt, GSFC, December 1997 Allow long values to extend over multiple lines Version 4, D. Lindler, March 2000, modified to use capital E instead of a lower case e for exponential format. Version 4.1 W. Landsman April 2000, make user-supplied format uppercase Version 4.2 W. Landsman July 2002, positioning of EXTEND keyword Version 5, 23-April-2007, William Thompson, GSFC Version 6, 02-Aug-2007, WTT, bug fix for OGIP long lines Version 6.1, 10-Feb-2009, W. Landsman, increase default format precision Version 6.2 30-Sep-2009, W. Landsman, added /NOLOGICAL keyword Version : Version 6.2, 30-Sep-2009(See astrolib/pro/fxaddpar.pro)
FXBADDCOL
[Previous Routine] [Next Routine] [List of Routines]NAME: FXBADDCOL PURPOSE : Adds a column to a binary table extension. EXPLANATION : Modify a basic FITS binary table extension (BINTABLE) header array to define a column. USE : FXBADDCOL, INDEX, HEADER, ARRAY [, TTYPE [, COMMENT ]] INPUTS : HEADER = String array containing FITS extension header. ARRAY = IDL variable used to determine the data size and type associated with the column. If the column is defined as containing variable length arrays, then ARRAY must be of the maximum size to be stored in the column. Opt. Inputs : TTYPE = Column label. COMMENT = Comment for TTYPE Outputs : INDEX = Index (1-999) of the created column. HEADER = The header is modified to reflect the added column. Opt. Outputs: None. Keywords : VARIABLE= If set, then the column is defined to contain pointers to variable length arrays in the heap area. DCOMPLEX= If set, and ARRAY is complex, with the first dimension being two (real and imaginary parts), then the column is defined as double-precision complex (type "M"). This keyword is only needed prior to IDL Version 4.0, when the double double complex datatype was unavailable in IDL BIT = If passed, and ARRAY is of type byte, then the column is defined as containg bit mask arrays (type "X"), with the value of BIT being equal to the number of mask bits. LOGICAL = If set, and array is of type byte, then the column is defined as containing logical arrays (type "L"). NO_TDIM = If set, then the TDIMn keyword is not written out to the header. No TDIMn keywords are written for columns containing variable length arrays. TUNIT = If passed, then corresponding keyword is added to header. TSCAL = Same. TZERO = Same. TNULL = Same. TDISP = Same. TDMIN = Same. TDMAX = Same. TDESC = Same. TCUNI = Same. TROTA = Same. TRPIX = Same. TRVAL = Same. TDELT = Same. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBADDCOL, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : FXADDPAR, FXPAR Common : None. Restrictions: Warning: No checking is done of any of the parameters defining the values of optional FITS keywords. FXBHMAKE must first be called to initialize the header. If ARRAY is of type character, then it must be of the maximum length expected for this column. If a character string array, then the largest string in the array is used to determine the maximum length. The DCOMPLEX keyword is ignored if ARRAY is not double-precision. ARRAY must also have a first dimension of two representing the real and imaginary parts. The BIT and LOGICAL keywords are ignored if ARRAY is not of type byte. BIT takes precedence over LOGICAL. Side effects: If the data array is multidimensional, then a TDIM keyword is added to the header, unless either NO_TDIM or VARIABLE is set. No TDIMn keywords are written out for bit arrays (format 'X'), since the dimensions would refer to bits, not bytes. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Jan 1992. W. Thompson, Feb 1992, changed from function to procedure. W. Thompson, Feb 1992, modified to support variable length arrays. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 31 May 1994 Added ERRMSG keyword. Version 3, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 4, William Thompson, GSFC, 30 December 1994 Added keyword TCUNI. Version 5, Wayne Landsman, GSFC, 12 Aug 1997 Recognize double complex IDL datatype Version 6, Wayne Landsman, GSFC. C. Yamauchi (ISAS) 23 Feb 2006 Support 64bit integers Version 7, C. Markwardt, GSFC, Allow unsigned integers, which have special TSCAL/TZERO values. Feb 2009 Version 8, P.Broos (PSU), Wayne Landsman (GSFC) Mar 2010 Do *not* force TTYPE* keyword to uppercase Version : Version 8, Mar 2010(See astrolib/pro/fxbaddcol.pro)
FXBCLOSE
[Previous Routine] [Next Routine] [List of Routines]NAME: FXBCLOSE Purpose : Close a FITS binary table extension opened for read. Explanation : Closes a FITS binary table extension that had been opened for read by FXBOPEN. Use : FXBCLOSE, UNIT Inputs : UNIT = Logical unit number of the file. Opt. Inputs : None. Outputs : None. Opt. Outputs: None. Keywords : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBCLOSE, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : None. Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The file must have been opened with FXBOPEN. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Feb. 1992. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 June 1994 Added ERRMSG keyword. Version 3, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version : Version 3, 23 June 1994 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/fxbclose.pro)
FXBCOLNUM()
[Previous Routine] [Next Routine] [List of Routines]NAME: FXBCOLNUM() Purpose : Returns a binary table column number. Explanation : Given a column specified either by number or name, this routine will return the appropriate column number. Use : Result = FXBCOLNUM( UNIT, COL ) Inputs : UNIT = Logical unit number corresponding to the file containing the binary table. COL = Column in the binary table, given either as a character string containing a column label (TTYPE), or as a numerical column index starting from column one. Opt. Inputs : None. Outputs : The result of the function is the number of the column specified, or zero if no column is found (when passed by name). Opt. Outputs: None. Keywords : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' Result = FXBCOLNUM( ERRMSG=ERRMSG, ... ) IF ERRMSG NE '' THEN ... Calls : None. Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The binary table file must have been opened with FXBOPEN. If COL is passed as a number, rather than as a name, then it must be consistent with the number of columns in the table. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : None. Written : William Thompson, GSFC, 2 July 1993. Modified : Version 1, William Thompson, GSFC, 2 July 1993. Version 2, William Thompson, GSFC, 29 October 1993. Added error message for not finding column by name. Version 3, William Thompson, GSFC, 21 June 1994 Added ERRMSG keyword. Version 4, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version : Version 4, 23 June 1994 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/fxbcolnum.pro)
FXBCREATE
[Previous Routine] [Next Routine] [List of Routines]NAME: FXBCREATE Purpose : Open a new binary table at the end of a FITS file. Explanation : Write a binary table extension header to the end of a disk FITS file, and leave it open to receive the data. The FITS file is opened, and the pointer is positioned just after the last 2880 byte record. Then the binary header is appended. Calls to FXBWRITE will append the binary data to this file, and then FXBFINISH will close the file. Use : FXBCREATE, UNIT, FILENAME, HEADER Inputs : FILENAME = Name of FITS file to be opened. HEADER = String array containing the FITS binary table extension header. Opt. Inputs : None. Outputs : UNIT = Logical unit number of the opened file. EXTENSION= Extension number of newly created extension. Opt. Outputs: None. Keywords : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBCREATE, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : FXADDPAR, FXBFINDLUN, FXBPARSE, FXFINDEND Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The primary FITS data unit must already be written to a file. The binary table extension header must already be defined (FXBHMAKE), and must match the data that will be written to the file. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Jan 1992, based on WRITEFITS by J. Woffard and W. Landsman. W. Thompson, Feb 1992, changed from function to procedure. W. Thompson, Feb 1992, removed all references to temporary files. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 July 1993. Fixed bug with variable length arrays. Version 3, William Thompson, GSFC, 21 June 1994 Added ERRMSG keyword. Version 4, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 5, Antony Bird, Southampton, 25 June 1997 Modified to allow very long tables Version : Version 5, 25 June 1997 Converted to IDL V5.0 W. Landsman September 1997 Added EXTENSION parameter, C. Markwardt 1999 Jul 15 More efficient zeroing of file, C. Markwardt, 26 Feb 2001 Recompute header size if updating THEAP keyword B. Roukema April 2010(See astrolib/pro/fxbcreate.pro)
FXBDIMEN()
[Previous Routine] [Next Routine] [List of Routines]NAME: FXBDIMEN() PURPOSE: Returns the dimensions for a column in a FITS binary table. Explanation : This procedure returns the dimensions associated with a column in a binary table opened for read with the command FXBOPEN. Use : Result = FXBDIMEN(UNIT,COL) Inputs : UNIT = Logical unit number returned by FXBOPEN routine. Must be a scalar integer. COL = Column in the binary table to read data from, either as a character string containing a column label (TTYPE), or as a numerical column index starting from column one. Opt. Inputs : None. Outputs : The result of the function is an array containing the dimensions for the specified column in the FITS binary table that UNIT points to. Opt. Outputs: None. Keywords : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' Result = FXBDIMEN( ERRMSG=ERRMSG, ... ) IF ERRMSG NE '' THEN ... Calls : FXBCOLNUM, FXBFINDLUN Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: None. Side effects: The dimensions will be returned whether or not the table is still open or not. If UNIT does not point to a binary table, then 0 is returned. If UNIT is an undefined variable, then 0 is returned. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : None. Written : William Thompson, GSFC, 4 March 1994. Modified : Version 1, William Thompson, GSFC, 4 March 1994. Version 2, William Thompson, GSFC, 21 June 1994 Added ERRMSG keyword. Version 3, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version : Version 3, 23 June 1994 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/fxbdimen.pro)
FXBFIND
[Previous Routine] [Next Routine] [List of Routines]NAME: FXBFIND Purpose : Find column keywords in a FITS binary table header. Explanation : Finds the value of a column keyword for all the columns in the binary table for which it is set. For example, FXBFIND, UNIT, 'TTYPE', COLUMNS, VALUES, N_FOUND Would find all instances of the keywords TTYPE1, TTYPE2, etc. The array COLUMNS would contain the column numbers for which a TTYPEn keyword was found, and VALUES would contain the values. N_FOUND would contain the total number of instances found. Use : FXBFIND, [UNIT or HEADER], KEYWORD, COLUMNS, VALUES, N_FOUND [, DEFAULT ] Inputs : Either UNIT or HEADER must be passed. UNIT = Logical unit number of file opened by FXBOPEN. HEADER = FITS binary table header. KEYWORD = Prefix to a series of FITS binary table column keywords. The keywords to be searched for are formed by combining this prefix with the numbers 1 through the value of TFIELDS in the header. Opt. Inputs : DEFAULT = Default value to use for any column keywords that aren't found. If passed, then COLUMNS and VALUES will contain entries for every column. Otherwise, COLUMNS and VALUES only contain entries for columns where values were found. Outputs : COLUMNS = Array containing the column numbers for which values of the requested keyword series were found. VALUES = Array containing the found values. N_FOUND = Number of values found. The value of this parameter is unaffected by whether or not DEFAULT is passed. Opt. Outputs: None. Output Keywords : COMMENTS = Comments associated with each keyword, if any Calls : FXBFINDLUN, FXPAR Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: If UNIT is passed, then the file must have been opened with FXBOPEN. If HEADER is passed, then it must be a legal FITS binary table header. The type of DEFAULT must be consistent with the values of the requested keywords, i.e. both most be either of string or numerical type. The KEYWORD prefix must not have more than five characters to leave room for the three digits allowed for the column numbers. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Feb. 1992. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Vectorized implementation improves performance, CM 18 Nov 1999 Added COMMENTS keyword CM Nov 2003 Remove use of obsolete !ERR system variable W. Landsman April 2010 Fix error introduced April 2010 W. Landsman Version : Version 3, April 2010.(See astrolib/pro/fxbfind.pro)
FXBFINDLUN()
[Previous Routine] [Next Routine] [List of Routines]NAME: FXBFINDLUN() Purpose : Find logical unit number UNIT in FXBINTABLE common block. Explanation : Finds the proper index to use for getting information about the logical unit number UNIT in the arrays stored in the FXBINTABLE common block. Called from FXBCREATE and FXBOPEN. Use : Result = FXBFINDLUN( UNIT ) Inputs : UNIT = Logical unit number. Opt. Inputs : None. Outputs : The result of the function is an index into the FXBINTABLE common block. Opt. Outputs: None. Keywords : None. Calls : None. Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: None. Side effects: If UNIT is not found in the common block, then it is added to the common block. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Feb. 1992. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 July 1993. Added DHEAP variable to fix bug with variable length arrays. Version 3, Michael Schubnell, University of Michigan, 22 May 1996 Change N_DIMS from short to long integer. Version : Version 3, 22 May 1996 Converted to IDL V5.0 W. Landsman September 1997 Make NAXIS1, NAXIS2, HEAP, DHEAP, BYTOFF 64-bit integers to deal with large files, E. Hivon Mar 2008(See astrolib/pro/fxbfindlun.pro)
FXBFINISH
[Previous Routine] [Next Routine] [List of Routines]NAME: FXBFINISH Purpose : Close a FITS binary table extension file opened for write. Explanation : Closes a FITS binary table extension file that had been opened for write by FXBCREATE. Use : FXBFINISH, UNIT Inputs : UNIT = Logical unit number of the file. Opt. Inputs : None. Outputs : None. Opt. Outputs: None. Keywords : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBFINISH, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : None. Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The file must have been opened with FXBCREATE, and written with FXBWRITE. Side effects: Any bytes needed to pad the file out to an integral multiple of 2880 bytes are written out to the file. Then, the file is closed. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Jan 1992. W. Thompson, Feb 1992, modified to support variable length arrays. W. Thompson, Feb 1992, removed all references to temporary files. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 July 1993. Fixed bug with variable length arrays. Version 3, William Thompson, GSFC, 31 May 1994 Added ERRMSG keyword. Version 4, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version : Version 4, 23 June 1994 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/fxbfinish.pro)
FXBGROW
[Previous Routine] [Next Routine] [List of Routines]NAME: FXBGROW PURPOSE : Increase the number of rows in a binary table. EXPLANATION : Call FXBGROW to increase the size of an already-existing FITS binary table. The number of rows increases to NROWS; however the table cannot shrink by this operation. This procedure is useful when a table with an unknown number of rows must be created. The caller would then call FXBCREATE to construct a table of some base size, and follow with calls to FXBGROW to lengthen the table as needed. The extension being enlarged need not be the last extension in the file. If subsequent extensions exist in the file, they will be shifted properly. CALLING SEQUENCE : FXBGROW, UNIT, HEADER, NROWS[, ERRMSG= , NOZERO= , BUFFERSIZE= ] INPUT PARAMETERS : UNIT = Logical unit number of an already-opened file. HEADER = String array containing the FITS binary table extension header. The header is modified in place. NROWS = New number of rows, always more than the previous number. OPTIONAL INPUT KEYWORDS: NOZERO = when set, FXBGROW will not zero-pad the new data if it doesn't have to. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBGROW, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... BUFFERSIZE = Size in bytes for intermediate data transfers (default 32768) Calls : FXADDPAR, FXHREAD, BLKSHIFT Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The file must be open with write permission. The binary table extension in question must already by written to the file (using FXBCREATE). A table can never shrink via this operation. SIDE EFFECTS: The FITS file will grow in size, and heap areas are preserved by moving them to the end of the file. The header is modified to reflect the new number of rows. CATEGORY : Data Handling, I/O, FITS, Generic. Initially written, C. Markwardt, GSFC, Nov 1998 Added ability to enlarge arbitrary extensions and tables with variable sized rows, not just the last extension in a file, CM, April 2000 Fix bug in the zeroing of the output file, C. Markwardt, April 2005(See astrolib/pro/fxbgrow.pro)
FXBHEADER()
[Previous Routine] [Next Routine] [List of Routines]NAME: FXBHEADER() PURPOSE: Returns the header of an open FITS binary table. EXPLANATION: This procedure returns the FITS extension header of a FITS binary table opened for read with the command FXBOPEN. Use : Result = FXBHEADER(UNIT) Inputs : UNIT = Logical unit number returned by FXBOPEN routine. Must be a scalar integer. Opt. Inputs : None. Outputs : The result of the function is a string array containing the header for the FITS binary table that UNIT points to. Opt. Outputs: None. Keywords : None. Calls : FXBFINDLUN Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: None. Side effects: The string array returned always has as many elements as the largest header read by FXBOPEN. Any extra elements beyond the true header are blank or null strings. The header will be returned whether or not the table is still open or not. If UNIT does not point to a binary table, then a string array of nulls is returned. If UNIT is an undefined variable, then the null string is returned. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : None. Written : William Thompson, GSFC, 1 July 1993. Modified : Version 1, William Thompson, GSFC, 1 July 1993. Version : Version 1, 1 July 1993. Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/fxbheader.pro)
FXBHELP
[Previous Routine] [Next Routine] [List of Routines]NAME: FXBHELP Purpose : Prints short description of columns in a FITS binary table. Explanation : Prints a short description of the columns in a FITS binary table to the terminal screen. Use : FXBHELP, UNIT Inputs : UNIT = Logical unit number of file opened by FXBOPEN. Opt. Inputs : None. Outputs : None. Opt. Outputs: None. Keywords : None. Calls : FXBFIND, FXBFINDLUN, FXPAR Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The file must have been opened with FXBOPEN. Side effects: Certain fields may be truncated in the display. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Feb. 1992, from TBHELP by W. Landsman. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 12 May 1993. Modified to not write to a logical unit number assigned to the terminal. This makes it compatible with IDL for Windows. Version 3, Wayne Landsman GSFC April 2010 Remove use of obsolete !ERR system variable Version : Version 3, April 2010.(See astrolib/pro/fxbhelp.pro)
FXBHMAKE
[Previous Routine] [Next Routine] [List of Routines]NAME: FXBHMAKE Purpose : Create basic FITS binary table extension (BINTABLE) header. Explanation : Creates a basic header array with all the required keywords, but with none of the table columns defined. This defines a basic structure which can then be added to or modified by other routines. Use : FXBHMAKE, HEADER, NROWS [, EXTNAME [, COMMENT ]] Inputs : NROWS = Number of rows in the binary table. Opt. Inputs : EXTNAME = If passed, then the EXTNAME record is added with this value. COMMENT = Comment to go along with EXTNAME. Outputs : HEADER = String array containing FITS extension header. Opt. Outputs: None. Keywords : INITIALIZE = If set, then the header is completely initialized, and any previous entries are lost. DATE = If set, then the DATE keyword is added to the header. EXTVER = Extension version number (integer). EXTLEVEL = Extension level number (integer). ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBHMAKE, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : GET_DATE, FXADDPAR, FXHCLEAN Common : None. Restrictions: Warning: No checking is done of any of the parameters. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Jan 1992. William Thompson, Sep 1992, added EXTVER and EXTLEVEL keywords. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 June 1994 Added ERRMSG keyword. Version 3, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version : Version 3, 23 June 1994 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/fxbhmake.pro)
FXBINTABLE
[Previous Routine] [Next Routine] [List of Routines]NAME: FXBINTABLE Purpose : Common block FXBINTABLE used by "FXB" routines. Explanation : This is not an IDL routine as such, but contains the definition of the common block FXBINTABLE for inclusion into other routines. By defining the common block in one place, the problem of conflicting definitions is avoided. This file is included into routines that need this common block with the single line (left justified) @fxbintable FXBINTABLE contains the following arrays: LUN = An array of logical unit numbers of currently (or previously) opened binary table files. STATE = Array containing the state of the FITS files associated with the logical unit numbers, where 0=closed, 1=open for read, and 2=open for write. HEAD = FITS binary table headers. MHEADER = Array containing the positions of the first data byte of the header for each file referenced by array LUN. NHEADER = Array containing the positions of the first data byte after the header for each file referenced by array LUN. NAXIS1 = Values of NAXIS1 from the binary table headers. NAXIS2 = Values of NAXIS2 from the binary table headers. TFIELDS = Values of TFIELDS from the binary table headers. HEAP = The start of the first byte of the heap area for variable length arrays. DHEAP = The start of the first byte of the next variable length array, if writing. BYTOFF = Byte offset from the beginning of the row for each column in the binary table headers. TTYPE = Values of TTYPE for each column in the binary table headers. FORMAT = Character code formats of the various columns. IDLTYPE = IDL type code for each column in the binary table headers. N_ELEM = Number of elements for each column in the binary table headers. TSCAL = Scale factors for the individual columns. TZERO = Zero offsets for the individual columns. MAXVAL = For variable length arrays, contains the maximum number of elements for each column in the binary table headers. N_DIMS = Number of dimensions, and array of dimensions for each column of type string in the binary table headers. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Feb 1992. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 July 1993. Added DHEAP variable to fix bug with variable length arrays. Version : Version 2, 21 July 1993.(See astrolib/pro/fxbintable.pro)
FXBISOPEN()
[Previous Routine] [Next Routine] [List of Routines]NAME: FXBISOPEN() PURPOSE: Returns true if UNIT points to an open FITS binary table. Explanation : This procedure checks to see if the logical unit number given by the variable UNIT corresponds to a FITS binary table opened for read with the command FXBOPEN, and which has not yet been closed with FXBCLOSE. Use : Result = FXBISOPEN(UNIT) If FXBISOPEN(UNIT) THEN ... Inputs : UNIT = Logical unit number returned by FXBOPEN routine. Must be a scalar integer. Opt. Inputs : None. Outputs : The result of the function is either True (1) or False (0), depending on whether UNIT points to an open binary table or not. Opt. Outputs: None. Keywords : None. Calls : FXBFINDLUN Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: None. Side effects: If UNIT is an undefined variable, then False (0) is returned. If UNIT points to a FITS binary table file that is opened for write, then False (0) is returned. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : None. Written : William Thompson, GSFC, 1 July 1993. Modified : Version 1, William Thompson, GSFC, 1 July 1993. Version : Version 1, 1 July 1993. Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/fxbisopen.pro)
FXBOPEN
[Previous Routine] [Next Routine] [List of Routines]NAME: FXBOPEN Purpose : Open binary table extension in a disk FITS file for reading or updating Explanation : Opens a binary table extension in a disk FITS file for reading. The columns are then read using FXBREAD, and the file is closed when done with FXBCLOSE. Use : FXBOPEN, UNIT, FILENAME, EXTENSION [, HEADER ] Inputs : FILENAME = Name of FITS file to be opened. Optional extension *number* may be specified, in either of the following formats (using the FTOOLS convention): FILENAME[EXT] or FILENAME+EXT, where EXT is 1 or higher. Such an extension specification takes priority over EXTENSION. EXTENSION = Either the number of the FITS extension, starting with the first extension after the primary data unit being one; or a character string containing the value of EXTNAME to search for. Opt. Inputs : None. Outputs : UNIT = Logical unit number of the opened file. Opt. Outputs: HEADER = String array containing the FITS binary table extension header. Keywords : NO_TDIM = If set, then any TDIMn keywords found in the header are ignored. ACCESS = A scalar string describing access privileges as one of READ ('R') or UPDATE ('RW'). DEFAULT: 'R' REOPEN = If set, UNIT must be an already-opened file unit. FXBOPEN will treat the file as a FITS file. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBOPEN, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : FXBFINDLUN, FXBPARSE, FXHREAD, FXPAR Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The file must be a valid FITS file. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Feb 1992, based on READFITS by J. Woffard and W. Landsman. W. Thompson, Feb 1992, changed from function to procedure. W. Thompson, June 1992, fixed up error handling. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 27 May 1994 Added ERRMSG keyword. Version 3, William Thompson, GSFC, 21 June 1994 Extended ERRMSG to call to FXBPARSE Version 4, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 4, 23 June 1994 Added ACCESS, REOPEN keywords, and FXFILTER package, CM 1999 Feb 03 Added FILENAME[EXT] and FILENAME+EXT extension parsing, CM 1999 Jun 28 Some general tidying, CM 1999 Nov 18 Allow for possible 64bit integer number of bytes W. Landsman Nov 2007 Make Ndata a 64bit integer to deal with larger files, E. Hivon, Mar 2008(See astrolib/pro/fxbopen.pro)
FXBPARSE
[Previous Routine] [Next Routine] [List of Routines]NAME: FXBPARSE Purpose : Parse the binary table extension header. Explanation : Parses the binary table extension header, and store the information about the format of the binary table in the FXBINTABLE common block--called from FXBCREATE and FXBOPEN. Use : FXBPARSE, ILUN, UNIT, HEADER Inputs : ILUN = Index into the arrays in the FXBINTABLE common block. HEADER = FITS binary table extension header. Opt. Inputs : None. Outputs : None. Opt. Outputs: None. Keywords : NO_TDIM = If set, then any TDIMn keywords found in the header are ignored. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBPARSE, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : FXBFIND, FXBTDIM, FXBTFORM, FXPAR Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: None. Side effects: Any TDIMn keywords found for bit arrays (format 'X') are ignored, since the dimensions would refer to bits, not bytes. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Feb. 1992. William Thompson, Jan. 1993, modified for renamed FXBTFORM and FXBTDIM. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 June 1994 Added ERRMSG keyword. Version 3, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 4, Michael Schubnell, University of Michigan, 22 May 1996 Change N_DIMS from short to long integer. Version 5, W. Landsman, GSFC, 12 Aug 1997 Use double complex datatype, if needed Version 6, W. Landsman GSFC 30 Aug 1997 Optimized FXPAR; call FXBFIND for speed, CM 1999 Nov 18 Modify DHEAP(ILUN) when opening table now, CM 2000 Feb 22 Default the TZERO/TSCAL tables to double instead of single precision floating point, CM 2003 Nov 23 Make NAXIS1 and NAXIS2 64-bit integers to deal with large files, E. Hivon Mar 2008 Remove use of Obsolete !ERR system variable Version Version 8 April 2010(See astrolib/pro/fxbparse.pro)
FXBREAD
[Previous Routine] [Next Routine] [List of Routines]NAME: FXBREAD Purpose : Read a data array from a disk FITS binary table file. Explanation : Each call to FXBREAD will read the data from one column and one row from the FITS data file, which should already have been opened by FXBOPEN. One needs to call this routine for every column and every row in the binary table. FXBCLOSE will then close the FITS data file. Use : FXBREAD, UNIT, DATA, COL [, ROW ] Inputs : UNIT = Logical unit number corresponding to the file containing the binary table. COL = Column in the binary table to read data from, either as a character string containing a column label (TTYPE), or as a numerical column index starting from column one. Opt. Inputs : ROW = Either row number in the binary table to read data from, starting from row one, or a two element array containing a range of row numbers to read. If not passed, then the entire column is read in. Row must be passed for variable length arrays. Outputs : DATA = IDL data array to be read from the file. Opt. Outputs: None. Keywords : NOSCALE = If set, then the output data will not be scaled using the optional TSCAL and TZERO keywords in the FITS header. Default is to scale. NOIEEE = If set, then the output data is not byte-swapped to machine order. NOIEEE implies NOSCALE. Default is to perform the byte-swap. VIRTUAL = If set, and COL is passed as a name rather than a number, then if the program can't find a column with that name, it will then look for a keyword with that name in the header. Such a keyword would then act as a "virtual column", with the same value for every row. DIMENSIONS = Vector array containing the dimensions to be used to read in the data. Bypasses any dimensioning information stored in the header. Ignored for bit arrays. If the data type is double-precision complex, then an extra dimension of 2 is prepended to the dimensions passed by the user. NANVALUE= Value signalling data dropout. All points corresponding to IEEE NaN (not-a-number) are converted to this number. Ignored unless DATA is of type float, double-precision or complex. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBREAD, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : FXPAR, WHERE_NEGZERO, WHERENAN Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The binary table file must have been opened with FXBOPEN. The data must be consistent with the column definition in the binary table header. The row number must be consistent with the number of rows stored in the binary table header. The number of elements implied by the dimensions keyword must not exceed the number of elements stored in the file. Side effects: If the DIMENSIONS keyword is used, then the number of data points read in may be less than the number of points stored in the table. If there are no elements to read in (the number of elements is zero), then the program sets !ERR to -1, and DATA is unmodified. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Jan 1992. W. Thompson, Feb 1992, modified to support variable length arrays. W. Thompson, Jun 1992, modified way that row ranges are read in. No longer works reiteratively. W. Thompson, Jun 1992, fixed bug where NANVALUE would be modified by TSCAL and TZERO keywords. W. Thompson, Jun 1992, fixed bug when reading character strings. Treats dimensions better when reading multiple rows. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 30 June 1993. Added overwrite keyword to REFORM call to speed up. Version 3, William Thompson, GSFC, 21 July 1993. Fixed bug with variable length arrays. Version 4, William Thompson, GSFC, 29 October 1993. Added error message for not finding column by name. Version 5, William Thompson, GSFC, 31 May 1994 Added ERRMSG keyword. Version 6, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 7, William Thompson, GSFC, 29 December 1994 Fixed bug where single element dimensions were lost. Version 8, William Thompson, GSFC, 20 March 1995 Fixed bug introduced in version 7. Version 9, Wayne Landsman, GSFC, 3 July 1996 Fixed bug involving use of virtual keyword. Version 10, William Thompson, GSFC, 31-Jan-1997 Added call to WHERE_NEGZERO. Version 11, Wayne Landsman, GSFC, 12 Aug, 1997 Use IDL dcomplex datatype if needed Version 12, Wayne Landmsan, GSFC, 20 Feb, 1998 Remove call to WHERE_NEGZERO (now part of IEEE_TO_HOST) Version 13, 18 Nov 1999, CM, Add NOIEEE keyword Version 14, 21 Aug 2000, William Thompson, GSFC Catch I/O errors Version 15, W. Landsman GSFC 10 Dec 2009 Fix Dimension keyword, remove IEEE_TO_HOST Version : Version 15, 10 Dec 2009(See astrolib/pro/fxbread.pro)
FXBREADM
[Previous Routine] [Next Routine] [List of Routines]NAME: FXBREADM PURPOSE: Read multiple columns/rows from a disk FITS binary table file. EXPLANATION : A call to FXBREADM will read data from multiple rows and multiple columns in a single procedure call. Up to forty-nine columns may be read in a single pass; the number of rows is limited essentially by available memory. The file should have already been opened with FXBOPEN. FXBREADM optimizes reading multiple columns by first reading a large chunk of data from the FITS file directly, and then slicing the data into columns within memory. FXBREADM can read variable-length arrays (see below). The number of columns is limited to 49 if data are passed by positional argument. However, this limitation can be overcome by having FXBREADM return the data in an array of pointers. The user should set the PASS_METHOD keyword to 'POINTER', and an array of pointers to the data will be returned in the POINTERS keyword. The user is responsible for freeing the pointers; however, FXBREADM will reuse any pointers passed into the procedure, and hence any pointed-to data will be destroyed. FXBREADM can also read variable-length columns from FITS binary tables. Since such data is not of a fixed size, it is returned as a structure. The structure has the following elements: VARICOL: ;; Flag: variable length column (= 1) N_ELEMENTS: ;; Total number of elements returned TYPE: ;; IDL data type code (integer) N_ROWS: ;; Number of rows read from table (integer) INDICES: ;; Indices of each row's data (integer array) DATA: ;; Raw data elements (variable type array) In order to gain access to the Ith row's data, one should examine DATA(INDICES(I):INDICES(I+1)-1), which is similar in construct to the REVERSE_INDICES keyword of the HISTOGRAM function. CALLING SEQUENCE: FXBREADM, UNIT, COL, DATA1, [ DATA2, ... DATA48, ROW=, BUFFERSIZE = ] /NOIEEE, /NOSCALE, /VIRTUAL, NANVALUE=, PASS_METHOD = POINTERS=, ERRMSG = , WARNMSG = , STATUS = , /DEFAULT_FLOAT] INPUT PARAMETERS : UNIT = Logical unit number corresponding to the file containing the binary table. COL = An array of columns in the binary table to read data from, either as character strings containing column labels (TTYPE), or as numerical column indices starting from column one. Outputs : DATA1, DATA2...DATA48 = A named variable to accept the data values, one for each column. The columns are stored in order of the list in COL. If the read operation fails for a particular column, then the corresponding output Dn variable is not altered. See the STATUS keyword. Ignored if PASS_METHOD is 'POINTER'. OPTIONAL INPUT KEYWORDS: ROW = Either row number in the binary table to read data from, starting from row one, or a two element array containing a range of row numbers to read. If not passed, then the entire column is read in. /DEFAULT_FLOAT = If set, then scaling with TSCAL/TZERO is done with floating point rather than double precision. /NOIEEE = If set, then then IEEE floating point data will not be converted to the host floating point format (and this by definition implies NOSCALE). The user is responsible for their own floating point conversion. /NOSCALE = If set, then the output data will not be scaled using the optional TSCAL and TZERO keywords in the FITS header. Default is to scale. VIRTUAL = If set, and COL is passed as a name rather than a number, then if the program can't find a column with that name, it will then look for a keyword with that name in the header. Such a keyword would then act as a "virtual column", with the same value for every row. DIMENSIONS = FXBREADM ignores this keyword. It is here for compatibility only. NANVALUE= Value signalling data dropout. All points corresponding to IEEE NaN (not-a-number) are converted to this number. Ignored unless DATA is of type float, double-precision or complex. PASS_METHOD = A scalar string indicating method of passing data from FXBREADM. Either 'ARGUMENT' (indicating pass by positional argument), or 'POINTER' (indicating passing an array of pointers by the POINTERS keyword). Default: 'ARGUMENT' POINTERS = If PASS_METHOD is 'POINTER' then an array of IDL pointers is returned in this keyword, one for each requested column. Any pointers passed into FXBREADM will have their pointed-to data destroyed. Ultimately the user is responsible for deallocating pointers. BUFFERSIZE = Raw data are transferred from the file in chunks to conserve memory. This is the size in bytes of each chunk. If a value of zero is given, then all of the data are transferred in one pass. Default is 32768 (32 kB). OPTIONAL OUTPUT KEYWORDS: ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBREAD, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... WARNMSG = Messages which are considered to be non-fatal "warnings" are returned in this output string. Note that if some but not all columns are unreadable, this is considered to be non-fatal. STATUS = An output array containing the status for each column read, 1 meaning success and 0 meaning failure. Calls : IEEE_TO_HOST, FXPAR(), WHERENAN() Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The binary table file must have been opened with FXBOPEN. The data must be consistent with the column definition in the binary table header. The row number must be consistent with the number of rows stored in the binary table header. Generaly speaking, FXBREADM will be faster than iterative calls to FXBREAD when (a) a large number of columns is to be read or (b) the size in bytes of each cell is small, so that the overhead of the FOR loop in FXBREAD becomes significant. SIDE EFFECTS: If there are no elements to read in (the number of elements is zero), then the program sets !ERR to -1, and DATA is unmodified. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : C. Markwardt, based in concept on FXBREAD version 12 from IDLASTRO, but with significant and major changes to accomodate the multiple row/column technique. Mostly the parameter checking and general data flow remain. C. Markwardt, updated to read variable length arrays, and to pass columns by handle or pointer. 20 Jun 2001 C. Markwardt, try to conserve memory when creating the arrays 13 Oct 2001 Handle case of GE 50 columns, C. Markwardt, 18 Apr 2002 Handle case where TSCAL/TZERO changes type of column, C. Markwardt, 23 Feb 2003 Fix bug in handling of FOUND and numeric columns, C. Markwardt 12 May 2003 Removed pre-V5.0 HANDLE options W. Landsman July 2004 Fix bug when HANDLE options were removed, July 2004 Handle special cases of TSCAL/TZERO which emulate unsigned integers, Oct 2003 Add DEFAULT_FLOAT keyword to select float values instead of double for TSCAL'ed, June 2004 Read 64bit integer columns, E. Hivon, Mar 2008 Add support for columns with TNULLn keywords, C. Markwardt, Apr 2010 Add support for files larger than 2 GB, C. Markwardt, 2012-04-17(See astrolib/pro/fxbreadm.pro)
FXBSTATE()
[Previous Routine] [Next Routine] [List of Routines]NAME: FXBSTATE() PURPOSE: Returns the state of a FITS binary table. Explanation : This procedure returns the state of a FITS binary table that was either opened for read with the command FXBOPEN, or for write with the command FXBCREATE. Use : Result = FXBSTATE(UNIT) Inputs : UNIT = Logical unit number returned by FXBOPEN routine. Must be a scalar integer. Opt. Inputs : None. Outputs : The result of the function is the state of the FITS binary table that UNIT points to. This can be one of three values: 0 = Closed 1 = Open for read 2 = Open for write Opt. Outputs: None. Keywords : None. Calls : FXBFINDLUN Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: None. Side effects: If UNIT is an undefined variable, then 0 (closed) is returned. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : None. Written : William Thompson, GSFC, 1 July 1993. Modified : Version 1, William Thompson, GSFC, 1 July 1993. Version : Version 1, 1 July 1993. Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/fxbstate.pro)
FXBTDIM()
[Previous Routine] [Next Routine] [List of Routines]NAME: FXBTDIM() Purpose : Parse TDIM-like kwywords. Explanation : Parses the value of a TDIM-like keyword (e.g. TDIMnnn, TDESC, etc.) to return the separate elements contained within. Use : Result = FXBTDIM( TDIM_KEYWORD ) Inputs : TDIM_KEYWORD = The value of a TDIM-like keyword. Must be a character string of the form "(value1,value2,...)". If the parentheses characters are missing, then the string is simply returned as is, without any further processing. Opt. Inputs : None. Outputs : The result of the function is a character string array containing the values contained within the keyword parameter. If a numerical result is desired, then simply call, e.g. Result = FIX( FXBTDIM( TDIM_KEYWORD )) Opt. Outputs: None. Keywords : None. Calls : GETTOK Common : None. Restrictions: The input parameter must have the proper format. The separate values must not contain the comma character. TDIM_KEYWORD must not be an array. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Jan. 1992. William Thompson, Jan. 1993, renamed to be compatible with DOS limitations. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version : Version 1, 12 April 1993. Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/fxbtdim.pro)
FXBTFORM
[Previous Routine] [Next Routine] [List of Routines]NAME: FXBTFORM PURPOSE : Returns information about FITS binary table columns. EXPLANATION : Procedure to return information about the format of the various columns in a FITS binary table. Use : FXBTFORM,HEADER,TBCOL,IDLTYPE,FORMAT,NUMVAL,MAXVAL Inputs : HEADER = Fits binary table header. Opt. Inputs : None. Outputs : TBCOL = Array of starting column positions in bytes. IDLTYPE = IDL data types of columns. FORMAT = Character code defining the data types of the columns. NUMVAL = Number of elements of the data arrays in the columns. MAXVAL = Maximum number of elements for columns containing variable length arrays, or zero otherwise. Opt. Outputs: None. Keywords : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBTFORM, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : FXPAR Common : None. Restrictions: None. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Feb. 1992, from TBINFO by D. Lindler. W. Thompson, Jan. 1993, renamed to be compatible with DOS limitations. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 June 1994 Added ERRMSG keyword. Version 3, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 4, William Thompson, GSFC, 9 April 1997 Modified so that variable length arrays can be read, even if the maximum array size is not in the header. Version 5 Wayne Landsman, GSFC, August 1997 Recognize double complex array type if since IDL version 4.0 Version 6 Optimized FXPAR call, CM 1999 Nov 18 Version 7: Wayne Landsman, GSFC Feb 2006 Added support for 64bit integer K format Version: Version 8: Wayne Landsman GSFC Apr 2010 Remove use of obsolete !ERR variable(See astrolib/pro/fxbtform.pro)
FXBWRITE
[Previous Routine] [Next Routine] [List of Routines]NAME: FXBWRITE Purpose : Write a binary data array to a disk FITS binary table file. Explanation : Each call to FXBWRITE will write to the data file, which should already have been created and opened by FXBCREATE. One needs to call this routine for every column and every row in the binary table. FXBFINISH will then close the file. Use : FXBWRITE, UNIT, DATA, COL, ROW Inputs : UNIT = Logical unit number corresponding to the file containing the binary table. DATA = IDL data array to be written to the file. COL = Column in the binary table to place data in, starting from column one. ROW = Row in the binary table to place data in, starting from row one. Opt. Inputs : None. Outputs : None. Opt. Outputs: None. Keywords : BIT = Number of bits in bit mask arrays (type "X"). Only used if the column is of variable size. NANVALUE= Value signalling data dropout. All points corresponding to this value are set to be IEEE NaN (not-a-number). Ignored unless DATA is of type float, double-precision or complex. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBWRITE, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : HOST_TO_IEEE Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The binary table file must have been opened with FXBCREATE. The data must be consistent with the column definition in the binary table header. The row number must be consistent with the number of rows stored in the binary table header. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Jan 1992, based on WRITEFITS by J. Woffard and W. Landsman. W. Thompson, Feb 1992, modified to support variable length arrays. W. Thompson, Feb 1992, removed all references to temporary files. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 July 1993. Fixed bug with variable length arrays. Version 3, William Thompson, GSFC, 31 May 1994 Added ERRMSG keyword. Version 4, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 5, Wayne Landsman, GSFC, 12 Aug 1997 Recognize IDL double complex data type Version : Version 5, 12 August 1997 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/fxbwrite.pro)
FXBWRITM
[Previous Routine] [Next Routine] [List of Routines]NAME: FXBWRITM PURPOSE: Write multiple columns/rows to a disk FITS binary table file. EXPLANATION : A call to FXBWRITM will write multiple rows and multiple columns to a binary table in a single procedure call. Up to fifty columns may be read in a single pass. The file should have already been opened with FXBOPEN (with write access) or FXBCREATE. FXBWRITM optimizes writing multiple columns by first writing a large chunk of data to the FITS file all at once. FXBWRITM cannot write variable-length arrays; use FXBWRITE instead. The number of columns is limited to 50 if data are passed by positional argument. However, this limitation can be overcome by passing pointers to FXBWRITM. The user should set the PASS_METHOD keyword to 'POINTER' as appropriate, and an array of pointers to the data in the POINTERS keyword. The user is responsible for freeing the pointers. CALLING SEQUENCE: FXBWRITM, UNIT, COL, D0, D1, D2, ..., [ ROW= , PASS_METHOD, NANVALUE= POINTERS=, BUFFERSIZE= ] INPUT PARAMETERS: UNIT = Logical unit number corresponding to the file containing the binary table. D0,..D49= An IDL data array to be written to the file, one for each column. These parameters will be igonred if data is passed through the POINTERS keyword. COL = Column in the binary table to place data in. May be either a list of column numbers where the first column is one, or a string list of column names. OPTIONAL INPUT KEYWORDS: ROW = Either row number in the binary table to write data to, starting from row one, or a two element array containing a range of row numbers to write. If not passed, then the entire column is written. NANVALUE= Value signalling data dropout. All points corresponding to this value are set to be IEEE NaN (not-a-number). Ignored unless DATA is of type float, double-precision or complex. NOSCALE = If set, then TSCAL/TZERO values are ignored, and data is written exactly as supplied. PASS_METHOD = A scalar string indicating method of passing data to FXBWRITM. One of 'ARGUMENT' (indicating pass by positional argument), or'POINTER' (indicating passing an array of pointers by the POINTERS keyword). Default: 'ARGUMENT' POINTERS = If PASS_METHOD is 'POINTER' then the user must pass an array of IDL pointers to this keyword, one for each column. Ultimately the user is responsible for deallocating pointers. BUFFERSIZE = Data are transferred in chunks to conserve memory. This is the size in bytes of each chunk. If a value of zero is given, then all of the data are transferred in one pass. Default is 32768 (32 kB). OPTIONAL OUTPUT KEYWORDS: ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBWRITE, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... WARNMSG = Messages which are considered to be non-fatal "warnings" are returned in this output string. STATUS = An output array containing the status for each read, 1 meaning success and 0 meaning failure. PROCEDURE CALLS: None. EXAMPLE: Write a binary table 'sample.fits' giving 43 X,Y positions and a 21 x 21 PSF at each position: (1) First, create sample values x = findgen(43) & y = findgen(43)+1 & psf = randomn(seed,21,21,43) (2) Create primary header, write it to disk, and make extension header fxhmake,header,/initialize,/extend,/date fxwrite,'sample.fits',header fxbhmake,header,43,'TESTEXT','Test binary table extension' (3) Fill extension header with desired column names fxbaddcol,1,header,x[0],'X' ;Use first element in each array fxbaddcol,2,header,y[0],'Y' ;to determine column properties fxbaddcol,3,header,psf[*,*,0],'PSF' (4) Write extension header to FITS file fxbcreate,unit,'sample.fits',header (5) Use FXBWRITM to write all data to the extension in a single call fxbwritm,unit,['X','Y','PSF'], x, y, psf fxbfinish,unit ;Close the file COMMON BLOCKS: Uses common block FXBINTABLE--see "fxbintable.pro" for more information. RESTRICTIONS: The binary table file must have been opened with FXBCREATE or FXBOPEN (with write access). The data must be consistent with the column definition in the binary table header. The row number must be consistent with the number of rows stored in the binary table header. A PASS_METHOD of POINTER does not use the EXECUTE() statement and can be used with the IDL Virtual Machine. However, the EXECUTE() statement is used when the PASS_METHOD is by arguments. CATEGORY: Data Handling, I/O, FITS, Generic. PREVIOUS HISTORY: C. Markwardt, based on FXBWRITE and FXBREADM (ver 1), Jan 1999 WRITTEN: Craig Markwardt, GSFC, January 1999. MODIFIED: Version 1, Craig Markwardt, GSFC 18 January 1999. Documented this routine, 18 January 1999. C. Markwardt, added ability to pass by handle or pointer. Some bug fixes, 20 July 2001 W. Landsman/B.Schulz Allow more than 50 arguments when using pointers W. Landsman Remove pre-V5.0 HANDLE options July 2004 W. Landsman Remove EXECUTE() call with POINTERS May 2005 C. Markwardt Allow the output table to have TSCAL/TZERO keyword values; if that is the case, then the passed values will be quantized to match those scale factors before being written. Sep 2007 E. Hivon: write 64bit integer and double precison columns, Mar 2008 C. Markwardt Allow unsigned integers, which have special TSCAL/TZERO values. Feb 2009 C. Markwardt Add support for files larger than 2 GB, 2012-04-17(See astrolib/pro/fxbwritm.pro)
FXFINDEND
[Previous Routine] [Next Routine] [List of Routines]NAME: FXFINDEND Purpose : Find the end of a FITS file. Explanation : This routine finds the end of the last logical record in a FITS file, which may be different from that of the physical end of the file. Each FITS header is read in and parsed, and the file pointer is moved to where the next FITS extension header would be if there is one, or to the end of the file if not. Use : FXFINDEND, UNIT [, EXTENSION] Inputs : UNIT = Logical unit number for the opened file. Opt. Inputs : None. Outputs : None. Opt. Outputs: EXTENSION = The extension number that a new extension would have if placed at the end of the file. Keywords : None. Calls : FXHREAD, FXPAR Common : None. Restrictions: The file must have been opened for block I/O. There must not be any FITS "special records" at the end of the file. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Feb. 1992. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version : Version 1, 12 April 1993. Converted to IDL V5.0 W. Landsman September 1997 Added EXTENSION parameter, CM 1999 Nov 18 Allow for possible 64bit integer number of bytes W. Landsman Nov 2007 make Ndata a long64 to deal with large files. E. Hivon Mar 2008(See astrolib/pro/fxfindend.pro)
FXHCLEAN
[Previous Routine] [Next Routine] [List of Routines]NAME: FXHCLEAN Purpose : Removes required keywords from FITS header. Explanation : Removes any keywords relevant to array structure from a FITS header, preparatory to recreating it with the proper values. Use : FXHCLEAN, HEADER Inputs : HEADER = FITS header to be cleaned. Opt. Inputs : None. Outputs : HEADER = The cleaned FITS header is returned in place of the input array. Opt. Outputs: None. Keywords : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXHCLEAN, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : SXDELPAR, FXPAR Common : None. Restrictions: HEADER must be a string array containing a properly formatted FITS header. Side effects: Warning: when cleaning a binary table extension header, not all of the keywords pertaining to columns in the table may be removed. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Jan 1992. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 31 May 1994 Added ERRMSG keyword. Version 3, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 4, William Thompson, GSFC, 30 December 1994 Added TCUNIn to list of column keywords to be removed. Version : Version 4, 30 December 1994 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/fxhclean.pro)
FXHMAKE
[Previous Routine] [Next Routine] [List of Routines]NAME: FXHMAKE Purpose : Create a basic FITS header array. Explanation : Creates a basic header array with all the required keywords. This defines a basic structure which can then be added to or modified by other routines. Use : FXHMAKE, HEADER [, DATA ] Inputs : None required. Opt. Inputs : DATA = IDL data array to be written to file. It must be in the primary data unit unless the XTENSION keyword is supplied. This array is used to determine the values of the BITPIX and NAXIS, etc. keywords. If not passed, then BITPIX is set to eight, NAXIS is set to zero, and no NAXISnnn keywords are included in this preliminary header. Outputs : HEADER = String array containing FITS header. Opt. Outputs: None. Keywords : INITIALIZE = If set, then the header is completely initialized, and any previous entries are lost. EXTEND = If set, then the keyword EXTEND is inserted into the file, with the value of "T" (true). DATE = If set, then the DATE keyword is added to the header. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXHMAKE, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... XTENSION - If set, then the header is appropriate for an image extension, rather than the primary data unit. Calls : GET_DATE, FXADDPAR, FXHCLEAN Common : None. Restrictions: Groups are not currently supported. Side effects: BITPIX, NAXIS, etc. are defined such that complex arrays are stored as floating point, with an extra first dimension of two elements (real and imaginary parts). Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Jan 1992, from SXHMAKE by D. Lindler and M. Greason. Differences include: * Use of FITS standard (negative BITPIX) to signal floating point numbers instead of (SDAS/Geis) DATATYPE keyword. * Storage of complex numbers as pairs of real numbers. * Support for EXTEND keyword, and for cases where there is no primary data array. * Insertion of DATE record made optional. Only required FITS keywords are inserted automatically. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 June 1994 Added ERRMSG keyword. Version 3, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 4, Wayne Landsman, GSFC, 12 August 1997 Recognize double complex data type Converted to IDL V5.0 W. Landsman September 1997 Version 6, William Thompson, GSFC, 22 September 2004 Recognize unsigned integer types. Version 6.1, C. Markwardt, GSFC, 19 Jun 2005 Add the XTENSION keyword, which writes an XTENSION keyword instead of SIMPLE. Version : Version 6.1, 19 June 2005(See astrolib/pro/fxhmake.pro)
FXHMODIFY
[Previous Routine] [Next Routine] [List of Routines]NAME: FXHMODIFY PURPOSE : Modify a FITS header in a file on disk. Explanation : Opens a FITS file, and adds or modifies a parameter in the FITS header. Can be used for either the main header, or for an extension header. The modification is performed directly on the disk file. Use : FXHMODIFY, FILENAME, NAME, VALUE, COMMENT Inputs : FILENAME = String containing the name of the file to be read. NAME = Name of parameter, scalar string If NAME is already in the header the value and possibly comment fields are modified. Otherwise a new record is added to the header. If NAME is equal to either "COMMENT" or "HISTORY" then the value will be added to the record without replacement. In this case the comment parameter is ignored. VALUE = Value for parameter. The value expression must be of the correct type, e.g. integer, floating or string. String values of 'T' or 'F' are considered logical values. Opt. Inputs : COMMENT = String field. The '/' is added by this routine. Added starting in position 31. If not supplied, or set equal to '' (the null string), then any previous comment field in the header for that keyword is retained (when found). Outputs : None. Opt. Outputs: None. Keywords : EXTENSION = Either the number of the FITS extension, starting with the first extension after the primary data unit being one; or a character string containing the value of EXTNAME to search for. If not passed, then the primary FITS header is modified. BEFORE = Keyword string name. The parameter will be placed before the location of this keyword. For example, if BEFORE='HISTORY' then the parameter will be placed before the first history location. This applies only when adding a new keyword; keywords already in the header are kept in the same position. AFTER = Same as BEFORE, but the parameter will be placed after the location of this keyword. This keyword takes precedence over BEFORE. FORMAT = Specifies FORTRAN-like format for parameter, e.g. "F7.3". A scalar string should be used. For complex numbers the format should be defined so that it can be applied separately to the real and imaginary parts. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXHMODIFY, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : FXHREAD, FXPAR, FXADDPAR, BLKSHIFT Restrictions: This routine can not be used to modify any of the keywords that control the structure of the FITS file, e.g. BITPIX, NAXIS, PCOUNT, etc. Doing so could corrupt the readability of the FITS file. Example: Modify the name 'OBJECT' keyword in the primary FITS header of a FITS file 'spec98.ccd' to contain the value 'test domeflat' IDL> fxhmodify, 'spec98.ccd', 'OBJECT', 'test domeflat' Side effects: If adding a record to the FITS header would increase the number of 2880 byte records stored on disk, then the file is enlarged before modification, unless the NOGROW keyword is passed. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : None. Written : William Thompson, GSFC, 3 March 1994. Modified : Version 1, William Thompson, GSFC, 3 March 1994. Version 2, William Thompson, GSFC, 31 May 1994 Added ERRMSG keyword. Version 3, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 3.1 Wayne Landsman GSFC 17 March 2006 Fix problem in BLKSHIFT call if primary header extended Version 3.2 W. Landsman 14 November 204 Allow for need for 64bit number of bytes ; Version : Version 3.2, 14 Nov 2007(See astrolib/pro/fxhmodify.pro)
FXHREAD
[Previous Routine] [Next Routine] [List of Routines]NAME: FXHREAD Purpose : Reads a FITS header from an opened disk file. Explanation : Reads a FITS header from an opened disk file. Use : FXHREAD, UNIT, HEADER [, STATUS ] Inputs : UNIT = Logical unit number. Opt. Inputs : Outputs : HEADER = String array containing the FITS header. Opt. Outputs: STATUS = Condition code giving the status of the read. Normally, this is zero, but is set to !ERR if an error occurs, or if the first byte of the header is zero (ASCII null). Keywords : None. Calls : None. Common : None. Restrictions: The file must already be positioned at the start of the header. It must be a proper FITS file. Side effects: The file ends by being positioned at the end of the FITS header, unless an error occurs. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Feb 1992, from READFITS by J. Woffard and W. Landsman. W. Thompson, Aug 1992, added test for SIMPLE keyword. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version : Version 1, 12 April 1993. Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/fxhread.pro)
FXMOVE
[Previous Routine] [Next Routine] [List of Routines]NAME: FXMOVE PURPOSE: Skip to a specified extension number or name in a FITS file CALLING SEQUENCE: STATUS=FXMOVE(UNIT, EXT, /Silent) STATUS=FXMOVE(UNIT, EXTNAME, /Silent, EXT_NO=, ERRMSG= ) INPUT PARAMETERS: UNIT = An open unit descriptor for a FITS data stream. EXTEN = Number of extensions to skip. or Scalar string giving extension name (in the EXTNAME keyword) OPTIONAL INPUT PARAMETER: /SILENT - If set, then any messages about invalid characters in the FITS file are suppressed. OPTIONAL OUTPUT PARAMETER: ERRMSG = If this keyword is present, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. EXT_NO - Extension number, scalar integer, useful if the user supplied an extension name in the EXTEN parameter RETURNS: 0 if successful. -1 if an error is encountered. COMMON BLOCKS: None. SIDE EFFECTS: Repositions the file pointer. PROCEDURE: Each FITS header is read in and parsed, and the file pointer is moved to where the next FITS extension header until the desired extension is reached. PROCEDURE CALLS: FXPAR(), MRD_HREAD, MRD_SKIP MODIFICATION HISTORY: Extracted from FXPOSIT 8-March-2000 by T. McGlynn Added /SILENT keyword 14-Dec-2000 by W. Landsman Save time by not reading the full header W. Landsman Feb. 2003 Allow extension name to be specified, added EXT_NO, ERRMSG keywords W. Landsman December 2006 Make search for EXTNAME case-independent W.Landsman March 2007 Avoid round-off error for very large extensions N. Piskunov Dec 2007 Assume since V6.1 (/INTEGER keyword available to PRODUCT() ) Dec 2007 Capture error message from MRD_HREAD (must be used with post-June 2009 version of MRD-HREAD) W. Landsman July 2009(See astrolib/pro/fxmove.pro)
FXPAR()
[Previous Routine] [Next Routine] [List of Routines]NAME: FXPAR() PURPOSE: Obtain the value of a parameter in a FITS header. EXPLANATION: The first 8 chacters of each element of HDR are searched for a match to NAME. If the keyword is one of those allowed to take multiple values ("HISTORY", "COMMENT", or " " (blank)), then the value is taken as the next 72 characters. Otherwise, it is assumed that the next character is "=", and the value (and optional comment) is then parsed from the last 71 characters. An error occurs if there is no parameter with the given name. If the value is too long for one line, it may be continued on to the the next input card, using the CONTINUE Long String Keyword convention. For more info, http://fits.gsfc.nasa.gov/registry/continue_keyword.html Complex numbers are recognized as two numbers separated by one or more space characters. If a numeric value has no decimal point (or E or D) it is returned as type LONG. If it contains more than 8 numerals, or contains the character 'D', then it is returned as type DOUBLE. Otherwise it is returned as type FLOAT. If an integer is too large to be stored as type LONG, then it is returned as DOUBLE. CALLING SEQUENCE: Result = FXPAR( HDR, NAME [, ABORT, COUNT=, COMMENT=, /NOCONTINUE ] ) Result = FXPAR(HEADER,'DATE') ;Finds the value of DATE Result = FXPAR(HEADER,'NAXIS*') ;Returns array dimensions as ;vector REQUIRED INPUTS: HDR = FITS header string array (e.g. as returned by FXREAD). Each element should have a length of 80 characters NAME = String name of the parameter to return. If NAME is of the form 'keyword*' then an array is returned containing values of keywordN where N is an integer. The value of keywordN will be placed in RESULT(N-1). The data type of RESULT will be the type of the first valid match of keywordN found, unless DATATYPE is given. OPTIONAL INPUT: ABORT = String specifying that FXPAR should do a RETALL if a parameter is not found. ABORT should contain a string to be printed if the keyword parameter is not found. If not supplied, FXPAR will return with a negative !err if a keyword is not found. DATATYPE = A scalar value, indicating the type of vector data. All keywords will be cast to this type. Default: based on first keyword. Example: DATATYPE=0.0D (cast data to double precision) START = A best-guess starting position of the sought-after keyword in the header. If specified, then FXPAR first searches for scalar keywords in the header in the index range bounded by START-PRECHECK and START+POSTCHECK. This can speed up keyword searches in large headers. If the keyword is not found, then FXPAR searches the entire header. If not specified then the entire header is searched. Searches of the form 'keyword*' also search the entire header and ignore START. Upon return START is changed to be the position of the newly found keyword. Thus the best way to search for a series of keywords is to search for them in the order they appear in the header like this: START = 0L P1 = FXPAR('P1', START=START) P2 = FXPAR('P2', START=START) PRECHECK = If START is specified, then PRECHECK is the number of keywords preceding START to be searched. Default: 5 POSTCHECK = If START is specified, then POSTCHECK is the number of keywords after START to be searched. Default: 20 OUTPUT: The returned value of the function is the value(s) associated with the requested keyword in the header array. If the parameter is complex, double precision, floating point, long or string, then the result is of that type. Apostrophes are stripped from strings. If the parameter is logical, 1 is returned for T, and 0 is returned for F. If NAME was of form 'keyword*' then a vector of values are returned. OPTIONAL INPUT KEYWORDS: /NOCONTINUE = If set, then continuation lines will not be read, even if present in the header OPTIONAL OUTPUT KEYWORD: COUNT = Optional keyword to return a value equal to the number of parameters found by FXPAR. COMMENTS= Array of comments associated with the returned values. PROCEDURE CALLS: GETTOK(), VALID_NUM SIDE EFFECTS: The system variable !err is set to -1 if parameter not found, 0 for a scalar value returned. If a vector is returned it is set to the number of keyword matches found. If a keyword occurs more than once in a header, a warning is given, and the first occurence is used. However, if the keyword is "HISTORY", "COMMENT", or " " (blank), then multiple values are returned. NOTES: The functions SXPAR() and FXPAR() are nearly identical, although FXPAR() has slightly more sophisticated parsing. There is no particular reason for having two nearly identical procedures, but both are too widely used to drop either one. REVISION HISTORY: Version 1, William Thompson, GSFC, 12 April 1993. Adapted from SXPAR Version 2, William Thompson, GSFC, 14 October 1994 Modified to use VALID_NUM instead of STRNUMBER. Inserted additional call to VALID_NUM to trap cases where character strings did not contain quotation marks. Version 3, William Thompson, GSFC, 22 December 1994 Fixed bug with blank keywords, following suggestion by Wayne Landsman. Version 4, Mons Morrison, LMSAL, 9-Jan-98 Made non-trailing ' for string tag just be a warning (not a fatal error). It was needed because "sxaddpar" had an error which did not write tags properly for long strings (over 68 characters) Version 5, Wayne Landsman GSFC, 29 May 1998 Fixed potential problem with overflow of LONG values Version 6, Craig Markwardt, GSFC, 28 Jan 1998, Added CONTINUE parsing Version 7, Craig Markwardt, GSFC, 18 Nov 1999, Added START, PRE/POSTCHECK keywords for better performance Version 8, Craig Markwardt, GSFC, 08 Oct 2003, Added DATATYPE keyword to cast vector keywords type Version 9, Paul Hick, 22 Oct 2003, Corrected bug (NHEADER-1) Version 10, W. Landsman, GSFC 2 May 2012 Keywords of form "name_0" could confuse vector extractions(See astrolib/pro/fxpar.pro)
FXPARPOS()
[Previous Routine] [Next Routine] [List of Routines]NAME: FXPARPOS() Purpose : Finds position to insert record into FITS header. Explanation : Finds the position to insert a record into a FITS header. Called from FXADDPAR. Use : Result = FXPARPOS(KEYWRD, IEND [, BEFORE=BEFORE ] [, AFTER=AFTER ]) Inputs : KEYWRD = Array of eight-character keywords in header. IEND = Position of END keyword. Opt. Inputs : None. Outputs : Result of function is position to insert record. Opt. Outputs: None. Keywords : BEFORE = Keyword string name. The parameter will be placed before the location of this keyword. For example, if BEFORE='HISTORY' then the parameter will be placed before the first history location. This applies only when adding a new keyword; keywords already in the header are kept in the same position. AFTER = Same as BEFORE, but the parameter will be placed after the location of this keyword. This keyword takes precedence over BEFORE. If neither BEFORE or AFTER keywords are passed, then IEND is returned. Calls : None. Common : None. Restrictions: KEYWRD and IEND must be consistent with the relevant FITS header. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Jan 1992. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version : Version 1, 12 April 1993. Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/fxparpos.pro)
FXPOSIT
[Previous Routine] [Next Routine] [List of Routines]NAME: FXPOSIT PURPOSE: Return the unit number of a FITS file positioned at specified extension EXPLANATION: The FITS file will be ready to be read at the beginning of the specified extension. Either an extension number or extension name can be specified. Called by headfits.pro, mrdfits.pro Modified in March 2009 to set the /SWAP_IF_LITTLE_ENDIAN keyword when opening a file, and **may not be compatible with earlier versions** CALLING SEQUENCE: unit=FXPOSIT(FILE, EXT_NO_OR_NAME, /READONLY, COMPRESS=program, UNIXPIPE=, ERRMSG= , EXTNUM= , UNIT=, /SILENT /FPACK, /NO_FPACK INPUT PARAMETERS: FILE = FITS file name, scalar string. If an empty string is supplied then the user will be prompted for the file name. The user will also be prompted if a wild card is supplied, and more than one file matches the wildcard. EXT_NO_OR_NAME = Either the extension to be moved to (scalar nonnegative integer) or the name of the extension to read (scalar string) RETURNS: Unit number of file or -1 if an error is detected. OPTIONAL INPUT KEYWORD PARAMETER: COMPRESS - If this keyword is set and non-zero, then then treat the file as compressed. If 1 assume a gzipped file. and use IDLs internal decompression facility. For Unix compressed or bzip2 compressed files spawn off a process to decompress and use its output as the FITS stream. If the keyword is not 1, then use its value as a string giving the command needed for decompression. /FPACK - Signal that the file is compressed with the FPACK software. http://heasarc.gsfc.nasa.gov/fitsio/fpack/ ) By default, (FXPOSIT will assume that if the file name extension ends in .fz that it is fpack compressed.) The FPACK software must be installed on the system /NO_FPACK - The unit will only be used to read the FITS header. In that case FPACK compressed files need not be uncompressed. LUNIT - Integer giving the file unit number. Use this keyword if you want to override the default use of GET_LUN to obtain a unit number. /READONLY - If this keyword is set and non-zero, then OPENR rather than OPENU will be used to open the FITS file. Note that compressed files are always set to /READONLY /SILENT If set, then suppress any messages about invalid characters in the FITS file. OPTIONAL OUTPUT KEYWORDS: EXTNUM - Nonnegative integer give the extension number actually read Useful only if the extension was specified by name. ERRMSG = If this keyword is present, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. UNIXPIPE - If set to 1, then the FITS file was opened with a UNIX pipe rather than with the OPENR command. This is only required when reading a FPACK, bzip or Unix compressed file. Note that automatic byteswapping cannnot be set for a Unix pipe, since the SWAP_IF_LITTLE_ENDIAN keyword is only available for the OPEN command, and it is the responsibilty of the calling routine to perform the byteswapping. SIDE EFFECTS: Opens and returns a file unit. PROCEDURE: Open the appropriate file, or spawn a command and intercept the output. Call FXMOVE to get to the appropriate extension. PROCEDURE CALLS: FXMOVE() MODIFICATION HISTORY: Derived from William Thompson's FXFINDEND routine. Modified by T.McGlynn, 5-October-1994. Modified by T.McGlynn, 25-Feb-1995 to handle compressed files. Pipes cannot be accessed using FXHREAD so MRD_HREAD was written. W. Landsman 23-Apr-1997 Force the /bin/sh shell when uncompressing T. McGlynn 03-June-1999 Use /noshell option to get rid of processes left by spawn. Use findfile to retain ability to use wildcards W. Landsman 03-Aug-1999 Use EXPAND_TILDE under Unix to find file T. McGlynn 04-Apr-2000 Put reading code into FXMOVE, additional support for compression from D.Palmer. W. Landsman/D.Zarro 04-Jul-2000 Added test for !VERSION.OS EQ 'Win32' (WinNT) W. Landsman 12-Dec-2000 Added /SILENT keyword W. Landsman April 2002 Use FILE_SEARCH for V5.5 or later W. Landsman Feb 2004 Assume since V5.3 (OPENR,/COMPRESS available) W. Landsman,W. Thompson, 2-Mar-2004, Add support for BZIP2 W. Landsman Don't leave open file if an error occurs W. Landsman Sep 2004 Treat FTZ extension as gzip compressed W. Landsman Feb 2006 Removed leading spaces (prior to V5.5) W. Landsman Nov 2006 Allow specification of extension name Added EXTNUM, ERRMSG keywords W. Landsman/N.Piskunov Dec 2007 Added LUNIT keyword W. Landsman Mar 2009 OPEN with /SWAP_IF_LITTLE_ENDIAN Added UNIXPIPE output keyword N. Rich May 2009 Check if filename is an empty string W. Landsman May 2009 Support FPACK compressed files Added /FPACK, /HEADERONLY keywords W.Landsman July 2009 Deprecated /HEADERONLY add /NO_FPACK W.Landsman July 2011 Check for SIMPLE in first 8 chars Use gunzip to decompress Unix. Z file since compress utility often not installed anymore) W. Landsman October 2012 Add .fz extension if /FPACK set(See astrolib/pro/fxposit.pro)
FXREAD
[Previous Routine] [Next Routine] [List of Routines]NAME: FXREAD Purpose : Read basic FITS files. Explanation : Read an image array from a disk FITS file. Optionally allows the user to read in only a subarray and/or every Nth pixel. Use : FXREAD, FILENAME, DATA [, HEADER [, I1, I2 [, J1, J2 ]] [, STEP]] Inputs : FILENAME = String containing the name of the file to be read. Opt. Inputs : I1,I2 = Data range to read in the first dimension. If passed, then HEADER must also be passed. If not passed, or set to -1,-1, then the entire range is read. J1,J2 = Data range to read in the second dimension. If passed, then HEADER and I1,J2 must also be passed. If not passed, or set to -1,-1, then the entire range is read. STEP = Step size to use in reading the data. If passed, then HEADER must also be passed. Default value is 1. Ignored if less than 1. Outputs : DATA = Data array to be read from the file. Opt. Outputs: HEADER = String array containing the header for the FITS file. Keywords : /COMPRESS - If this keyword is set and non-zero, then then treat the file as gzip compressed. By default FXREAD assumes the file is gzip compressed if it ends in ".gz" NANVALUE = Value signalling data dropout. All points corresponding to IEEE NaN (not-a-number) are set to this value. Ignored unless DATA is of type float or double-precision. EXTENSION = FITS extension. It can be a scalar integer, indicating the extension number (extension number 0 is the primary HDU). It can also be a scalar string, indicating the extension name (EXTNAME keyword). Default: 0 (primary HDU) PROMPT = If set, then the optional parameters are prompted for at the keyboard. AVERAGE = If set, then the array size is reduced by averaging pixels together rather than by subselecting pixels. Ignored unless STEP is nontrivial. Note: this is much slower. YSTEP = If passed, then STEP is the step size in the 1st dimension, and YSTEP is the step size in the 2nd dimension. Otherwise, STEP applies to both directions. NOSCALE = If set, then the output data will not be scaled using the optional BSCALE and BZERO keywords in the FITS header. Default is to scale, if and only if BSCALE and BZERO are present and nontrivial. NOUPDATE = If set, then the optional BSCALE and BZERO keywords in the optional HEADER array will not be changed. The default is to reset these keywords to BSCALE=1, BZERO=0. Ignored if NOSCALE is set. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXREAD, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... NODATA = If set, then the array is not read in, but the primary header is read. Calls : GET_DATE, IEEE_TO_HOST, FXADDPAR, FXHREAD, FXPAR, WHERENAN Common : None. Restrictions: Groups are not supported. The optional parameters I1, I2, and STEP only work with one or two-dimensional arrays. J1 and J2 only work with two-dimensional arrays. Use of the AVERAGE keyword is not compatible with arrays with missing pixels. Side effects: If the keywords BSCALE and BZERO are present in the FITS header, and have non-trivial values, then the returned array DATA is formed by the equation DATA = BSCALE*original + BZERO However, this behavior can overridden by using the /NOSCALE keyword. If the data is scaled, then the optional HEADER array is changed so that BSCALE=1 and BZERO=0. This is so that these scaling parameters are not applied to the data a second time by another routine. Also, history records are added storing the original values of these constants. Note that only the returned array is modified--the header in the FITS file itself is untouched. If the /NOUPDATE keyword is set, however, then the BSCALE and BZERO keywords are not changed. It is then the user's responsibility to ensure that these parameters are not reapplied to the data. In particular, these keywords should not be present in any header when writing another FITS file, unless the user wants their values to be applied when the file is read back in. Otherwise, FITS readers will read in the wrong values for the data array. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, May 1992, based in part on READFITS by W. Landsman, and STSUB by M. Greason and K. Venkatakrishna. W. Thompson, Jun 1992, added code to interpret BSCALE and BZERO records, and added NOSCALE and NOUPDATE keywords. W. Thompson, Aug 1992, changed to call FXHREAD, and to add history records for BZERO, BSCALE. Minimium IDL Version: V5.3 (uses COMPRESS keyword to OPEN) Written : William Thompson, GSFC, May 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 17 November 1993. Corrected bug with AVERAGE keyword on non-IEEE compatible machines. Corrected bug with subsampling on VAX machines. Version 3, William Thompson, GSFC, 31 May 1994 Added ERRMSG keyword. Version 4, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 5, Zarro (SAC/GSFC), 14 Feb 1997 Added I/O error checking Version 6, 20-May-1998, David Schlegel/W. Thompson Allow a single pixel to be read in. Change the signal to read in the entire array to be -1 Version 7 C. Markwardt 22 Sep 2003 If the image is empty (NAXIS EQ 0), or NODATA is set, then return only the header. Version 8 W. Landsman 29 June 2004 Added COMPRESS keyword, check for .gz extension Version 9, William Thompson, 19-Aug-2004 Make sure COMPRESS is treated as a scalar Version 10, Craig Markwardt, 01 Mar 2004 Add EXTENSION keyword and ability to read different extensions than the primary one. Version 11, W. Landsamn September 2006 Assume since V5.5, remove VMS support Version 11.1, W. Landsamn November 2007 Allow for possibility number of bytes requires 64 bit integer Version 12, William Thompson, 18-Jun-2010, update BLANK value.(See astrolib/pro/fxread.pro)
FXWRITE
[Previous Routine] [Next Routine] [List of Routines]NAME: FXWRITE Purpose : Write a disk FITS file. Explanation : Creates or appends to a disk FITS file and writes a FITS header, and optionally an image data array. Use : FXWRITE, FILENAME, HEADER [, DATA ] Inputs : FILENAME = String containing the name of the file to be written. HEADER = String array containing the header for the FITS file. Opt. Inputs : DATA = IDL data array to be written to the file. If not passed, then it is assumed that extensions will be added to the file. Outputs : None. Opt. Outputs: None. Keywords : NANVALUE = Value signalling data dropout. All points corresponding to this value are set to be IEEE NaN (not-a-number). Ignored unless DATA is of type float, double-precision or complex. NOUPDATE = If set, then the optional BSCALE and BZERO keywords in the HEADER array will not be changed. The default is to reset these keywords to BSCALE=1, BZERO=0. APPEND = If set, then an existing file will be appended to. Appending to a non-existent file will create it. If a primary HDU already exists then it will be modified to have EXTEND = T. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXWRITE, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : CHECK_FITS, GET_DATE, HOST_TO_IEEE, FXADDPAR, FXPAR Common : None. Restrictions: If DATA is passed, then HEADER must be consistent with it. If no data array is being written to the file, then HEADER must also be consistent with that. The routine FXHMAKE can be used to create a FITS header. If found, then the optional keywords BSCALE and BZERO in the HEADER array is changed so that BSCALE=1 and BZERO=0. This is so that these scaling parameters are not applied to the data a second time by another routine. Also, history records are added storing the original values of these constants. (Other values of BZERO are used for unsigned integers.) If the /NOUPDATE keyword is set, however, then the BSCALE and BZERO keywords are not changed. The user should then be aware that FITS readers will apply these numbers to the data, even if the data is already converted to floating point form. Groups are not supported. Side effects: HEADER may be modified. One way it may be modified is describe above under NOUPDATE. The first header card may also be modified to conform to the FITS standard if it does not already agree (i.e. use of either the SIMPLE or XTENSION keyword depending on whether the image is the primary HDU or not). Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Jan 1992, from WRITEFITS by J. Woffard and W. Landsman. Differences include: * Made DATA array optional, and HEADER array mandatory. * Changed order of HEADER and DATA parameters. * No attempt made to fix HEADER array. W. Thompson, May 1992, changed open statement to force 2880 byte fixed length records (VMS). The software here does not depend on this file configuration, but other FITS readers might. W. Thompson, Aug 1992, added code to reset BSCALE and BZERO records, and added the NOUPDATE keyword. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 31 May 1994 Added ERRMSG keyword. Version 3, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 4, William Thompson, GSFC, 12 August 1999 Catch error if unable to open file. Version 4.1 Wayne Landsman, GSFC, 02 May 2000 Remove !ERR in call to CHECK_FITS, Use ARG_PRESENT() Version 5, William Thompson, GSFC, 22 September 2004 Recognize unsigned integer types Version 5.1 W. Landsman 14 November 204 Allow for need for 64bit number of bytes Version 6, Craig Markwardt, GSFC, 30 May 2005 Ability to append to existing files Version : Version 6, 30 May 2005(See astrolib/pro/fxwrite.pro)
F_FORMAT
[Previous Routine] [Next Routine] [List of Routines]NAME: F_FORMAT PURPOSE: Choose a nice floating format for displaying an array of REAL data. EXPLANATION: Called by TVLIST, IMLIST. CALLING SEQUENCE: fmt = F_FORMAT( minval, maxval, factor, [ length ] ) INPUTS: MINVAL - REAL scalar giving the minimum value of an array of numbers for which one desires a nice format. MAXVAL - REAL scalar giving maximum value in array of numbers OPTIONAL INPUT: LENGTH - length of the output F format (default = 5) must be an integer scalar > 2 OUTPUT: FMT - an F or I format string, e.g. 'F5.1' FACTOR - factor of 10 by which to multiply array of numbers to achieve a pretty display using format FMT. EXAMPLE: Find a nice format to print an array of numbers with a minimum of 5.2e-3 and a maximum of 4.2e-2. IDL> fmt = F_FORMAT( 5.2e-3, 4.2e-2, factor ) yields fmt = '(F5.2)' and factor = .01, i.e. the array can be displayed with a F5.2 format after multiplication by 100. REVISION HISTORY: Written W. Landsman December 1988 Deal with factors < 1. August 1991 Deal with factors < 1. *and* a large range October 1992 Now returns In format rather than Fn.0 February, 1994 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/f_format.pro)
GALAGE
[Previous Routine] [Next Routine] [List of Routines]NAME: GALAGE PURPOSE: Determine the age of a galaxy given its redshift and a formation redshift. CALLING SEQUENCE: age = galage(z, [zform, H0 =, k=, lambda0 =, Omega_m= , q0 =, /SILENT])' INPUTS: z - positive numeric vector or scalar of measured redshifts zform - redshift of galaxy formation (> z), numeric positive scalar To determine the age of the universe at a given redshift, set zform to a large number (e.g. ~1000). OPTIONAL KEYWORD INPUTS: H0 - Hubble constant in km/s/Mpc, positive scalar, default is 70 /SILENT - If set, then the adopted cosmological parameters are not displayed at the terminal. No more than two of the following four parameters should be specified. None of them need be specified -- the adopted defaults are given. k - curvature constant, normalized to the closure density. Default is 0, (indicating a flat universe) Omega_m - Matter density, normalized to the closure density, default is 0.3. Must be non-negative Lambda0 - Cosmological constant, normalized to the closure density, default is 0.7 q0 - Deceleration parameter, numeric scalar = -R*(R'')/(R')^2, default is -0.55 OUTPUTS: age - age of galaxy in years, will have the same number of elements as the input Z vector EXAMPLE: (1) Determine the age of a galaxy observed at z = 1.5 in a cosmology with Omega_matter = 0.3 and Lambda = 0.0. Assume the formation redshift was at z = 25, and use the default Hubble constant (=70 km/s/Mpc) IDL> print,galage(1.5,25,Omega_m=0.3, Lambda = 0) ===> 3.35 Gyr (2) Plot the age of a galaxy in Gyr out to a redshift of z = 5, assuming the default cosmology (omega_m=0.3, lambda=0.7), and zform = 100 IDL> z = findgen(50)/10. IDL> plot,z,galage(z,100)/1e9,xtit='z',ytit = 'Age (Gyr)' PROCEDURE: For a given formation time zform and a measured z, integrate dt/dz from zform to z. Analytic formula of dt/dz in Gardner, PASP 110:291-305, 1998 March (eq. 7) COMMENTS: (1) Integrates using the IDL Astronomy Library procedure QSIMP. (The intrinsic IDL QSIMP() function is not called because of its ridiculous restriction that only scalar arguments can be passed to the integrating function.) The function 'dtdz' is defined at the beginning of the routine (so it can compile first). (2) Should probably be fixed to use a different integrator from QSIMP when computing age from an "infinite" redshift of formation. But using a large value of zform seems to work adequately. (3) An alternative set of IDL procedures for computing cosmological parameters is available at http://cerebus.as.arizona.edu/~ioannis/research/red/ PROCEDURES CALLED: COSMO_PARAM, QSIMP HISTORY: STIS version by P. Plait (ACC) June 1999 IDL Astro Version W. Landsman (Raytheon ITSS) April 2000 Avoid integer overflow for more than 32767 redshifts July 2001(See astrolib/pro/galage.pro)
GAL_FLAT
[Previous Routine] [Next Routine] [List of Routines]NAME: GAL_FLAT PURPOSE: Transforms the image of a galaxy so that the galaxy appears face-on EXPLANATION: Either a nearest-neighbor approximations or a bilinear interpolation may be used. CALLING SEQUENCE: RESULT = GAL_FLAT( image, ang, inc, [, cen, /INTERP ] ) INPUTS: IMAGE - Image to be transformed ANG - Angle of major axis, counterclockwise from Y-axis, degrees For an image in standard orientation (North up, East left) this is the Position Angle INC - Angle of inclination of galaxy, degrees OPTIONAL INPUTS: CEN - Two element vector giving the X and Y position of galaxy center If not supplied, then the galaxy center is assumed to coincide with the image center INPUT KEYWORDS: INTERP - If present, and non-zero, then bilinear interpolation will be performed. Otherwise a nearest neighbor approximation is used. OUTPUTS: RESULT - the transformed image, same dimensions and type as IMAGE METHOD: A set of 4 equal spaced control points are corrected for inclination using the procedure POLYWARP. These control points are used by POLY_2D to correct the whole image. REVISION HISTORY: Written by R. S. Hill, SASC Technologies Inc., 4 December 1985 Code cleaned up a bit W. Landsman December 1992 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/gal_flat.pro)
GAL_UVW
[Previous Routine] [Next Routine] [List of Routines]NAME: GAL_UVW PURPOSE: Calculate the Galactic space velocity (U,V,W) of star EXPLANATION: Calculates the Galactic space velocity U, V, W of star given its (1) coordinates, (2) proper motion, (3) distance (or parallax), and (4) radial velocity. CALLING SEQUENCE: GAL_UVW, U, V, W, [/LSR, RA=, DEC=, PMRA= ,PMDEC=, VRAD= , DISTANCE= PLX= ] OUTPUT PARAMETERS: U - Velocity (km/s) positive toward the Galactic *anti*center V - Velocity (km/s) positive in the direction of Galactic rotation W - Velocity (km/s) positive toward the North Galactic Pole REQUIRED INPUT KEYWORDS: User must supply a position, proper motion,radial velocity and distance (or parallax). Either scalars or vectors can be supplied. (1) Position: RA - Right Ascension in *Degrees* Dec - Declination in *Degrees* (2) Proper Motion PMRA = Proper motion in RA in arc units (typically milli-arcseconds/yr) If given mu_alpha --proper motion in seconds of time/year - then this is equal to 15*mu_alpha*cos(dec) PMDEC = Proper motion in Declination (typically mas/yr) (3) Radial Velocity VRAD = radial velocity in km/s (4) Distance or Parallax DISTANCE - distance in parsecs or PLX - parallax with same distance units as proper motion measurements typically milliarcseconds (mas) OPTIONAL INPUT KEYWORD: /LSR - If this keyword is set, then the output velocities will be corrected for the solar motion (U,V,W)_Sun = (-8.5, 13.38, 6.49) (Coskunoglu et al. 2011 MNRAS) to the local standard of rest. Note that the value of the solar motion through the LSR remains poorly determined. EXAMPLE: (1) Compute the U,V,W coordinates for the halo star HD 6755. Use values from Hipparcos catalog, and correct to the LSR ra = ten(1,9,42.3)*15. & dec = ten(61,32,49.5) pmra = 628.42 & pmdec = 76.65 ;mas/yr dis = 139 & vrad = -321.4 gal_uvw,u,v,w,ra=ra,dec=dec,pmra=pmra,pmdec=pmdec,vrad=vrad,dis=dis,/lsr ===> u=141.2 v = -491.7 w = 93.9 ;km/s (2) Use the Hipparcos Input and Output Catalog IDL databases (see http://idlastro.gsfc.nasa.gov/ftp/zdbase/) to obtain space velocities for all stars within 10 pc with radial velocities > 10 km/s dbopen,'hipp_new,hic' ;Need Hipparcos output and input catalogs list = dbfind('plx>100,vrad>10') ;Plx > 100 mas, Vrad > 10 km/s dbext,list,'pmra,pmdec,vrad,ra,dec,plx',pmra,pmdec,vrad,ra,dec,plx ra = ra*15. ;Need right ascension in degrees GAL_UVW,u,v,w,ra=ra,dec=dec,pmra=pmra,pmdec=pmdec,vrad=vrad,plx = plx forprint,u,v,w ;Display results METHOD: Follows the general outline of Johnson & Soderblom (1987, AJ, 93,864) except that U is positive outward toward the Galactic *anti*center, and the J2000 transformation matrix to Galactic coordinates is taken from the introduction to the Hipparcos catalog. REVISION HISTORY: Written, W. Landsman December 2000 fix the bug occuring if the input arrays are longer than 32767 and update the Sun velocity Sergey Koposov June 2008 vectorization of the loop -- performance on large arrays is now 10 times higher Sergey Koposov December 2008 More recent value of solar motion WL/SK Jan 2011(See astrolib/pro/gal_uvw.pro)
GAUSSIAN
[Previous Routine] [Next Routine] [List of Routines]NAME: GAUSSIAN PURPOSE: Compute the 1-d Gaussian function and optionally the derivative EXPLANATION: Compute the 1-D Gaussian function and optionally the derivative at an array of points. CALLING SEQUENCE: y = gaussian( xi, parms,[ pderiv ]) INPUTS: xi = array, independent variable of Gaussian function. parms = parameters of Gaussian, 2, 3 or 4 element array: parms[0] = maximum value (factor) of Gaussian, parms[1] = mean value (center) of Gaussian, parms[2] = standard deviation (sigma) of Gaussian. (if parms has only 2 elements then sigma taken from previous call to gaussian(), which is stored in a common block). parms[3] = optional, constant offset added to Gaussian. OUTPUT: y - Function returns array of Gaussian evaluated at xi. Values will be floating pt. (even if xi is double) unless the /DOUBLE keyword is set. OPTIONAL INPUT: /DOUBLE - set this keyword to return double precision for both the function values and (optionally) the partial derivatives. OPTIONAL OUTPUT: pderiv = [N,3] or [N,4] output array of partial derivatives, computed only if parameter is present in call. pderiv[*,i] = partial derivative at all xi absisca values with respect to parms[i], i=0,1,2,[3]. EXAMPLE: Evaulate a Gaussian centered at x=0, with sigma=1, and a peak value of 10 at the points 0.5 and 1.5. Also compute the derivative IDL> f = gaussian( [0.5,1.5], [10,0,1], DERIV ) ==> f= [8.825,3.25]. DERIV will be a 2 x 3 array containing the numerical derivative at the two points with respect to the 3 parameters. COMMON BLOCKS: None HISTORY: Written, Frank Varosi NASA/GSFC 1992. Converted to IDL V5.0 W. Landsman September 1997 Use machar() for machine precision, added /DOUBLE keyword, add optional constant 4th parameter W. Landsman November 2001(See astrolib/pro/gaussian.pro)
GCIRC
[Previous Routine] [Next Routine] [List of Routines]NAME: GCIRC PURPOSE: Computes rigorous great circle arc distances. EXPLANATION: Input position can either be either radians, sexagesimal RA, Dec or degrees. All computations are double precision. CALLING SEQUENCE: GCIRC, U, RA1, DC1, RA2, DC2, DIS INPUTS: U -- integer = 0,1, or 2: Describes units of inputs and output: 0: everything radians 1: RAx in decimal hours, DCx in decimal degrees, DIS in arc seconds 2: RAx and DCx in degrees, DIS in arc seconds RA1 -- Right ascension or longitude of point 1 DC1 -- Declination or latitude of point 1 RA2 -- Right ascension or longitude of point 2 DC2 -- Declination or latitude of point 2 OUTPUTS: DIS -- Angular distance on the sky between points 1 and 2 See U above for units; double precision PROCEDURE: "Haversine formula" see http://en.wikipedia.org/wiki/Great-circle_distance NOTES: (1) If RA1,DC1 are scalars, and RA2,DC2 are vectors, then DIS is a vector giving the distance of each element of RA2,DC2 to RA1,DC1. Similarly, if RA1,DC1 are vectors, and RA2, DC2 are scalars, then DIS is a vector giving the distance of each element of RA1, DC1 to RA2, DC2. If both RA1,DC1 and RA2,DC2 are vectors then DIS is a vector giving the distance of each element of RA1,DC1 to the corresponding element of RA2,DC2. If the input vectors are not the same length, then excess elements of the longer ones will be ignored. (2) The function SPHDIST provides an alternate method of computing a spherical distance. (3) The haversine formula can give rounding errors for antipodal points. PROCEDURE CALLS: None MODIFICATION HISTORY: Written in Fortran by R. Hill -- SASC Technologies -- January 3, 1986 Translated from FORTRAN to IDL, RSH, STX, 2/6/87 Vector arguments allowed W. Landsman April 1989 Prints result if last argument not given. RSH, RSTX, 3 Apr. 1998 Remove ISARRAY(), V5.1 version W. Landsman August 2000 Added option U=2 W. Landsman October 2006 Use double precision for U=0 as advertised R. McMahon/W.L. April 2007 Use havesine formula, which has less roundoff error in the milliarcsecond regime W.L. Mar 2009(See astrolib/pro/gcirc.pro)
GCNTRD
[Previous Routine] [Next Routine] [List of Routines]NAME: GCNTRD PURPOSE: Compute the stellar centroid by Gaussian fits to marginal X,Y, sums EXPLANATION: GCNTRD uses the DAOPHOT "FIND" centroid algorithm by fitting Gaussians to the marginal X,Y distributions. User can specify bad pixels (either by using the MAXGOOD keyword or setting them to NaN) to be ignored in the fit. Pixel values are weighted toward the center to avoid contamination by neighboring stars. CALLING SEQUENCE: GCNTRD, img, x, y, xcen, ycen, [ fwhm , /SILENT, /DEBUG, MAXGOOD = , /KEEPCENTER ] 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. GCNTRD 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 there are too many bad pixels, or if the best-fit Gaussian has a negative height. If the centroid cannot be computed, then a message is displayed (unless /SILENT is set) and XCEN and YCEN are set to -1. OPTIONAL OUTPUT KEYWORDS: MAXGOOD= Only pixels with values less than MAXGOOD are used to in Gaussian fits to determine the centroid. For non-integer data, one can also flag bad pixels using NaN values. /SILENT - Normally GCNTRD prints an error message if it is unable to compute the centroid. Set /SILENT to suppress this. /DEBUG - If this keyword is set, then GCNTRD will display the subarray it is using to compute the centroid. /KeepCenter By default, GCNTRD first convolves a small region around the supplied position with a lowered Gaussian filter, and then finds the maximum pixel in a box centered on the input X,Y coordinates, and then extracts a new box about this maximum pixel. Set the /KeepCenter keyword to skip the convolution and finding the maximum pixel, and instead use a box centered on the input X,Y coordinates. PROCEDURE: Unless /KEEPCENTER is set, a small area around the initial X,Y is convolved with a Gaussian kernel, and the maximum pixel is found. This pixel is used as the center of a square, within which the centroid is computed as the Gaussian least-squares fit to the marginal sums in the X and Y directions. EXAMPLE: Find the centroid of a star in an image im, with approximate center 631, 48. Assume that bad (saturated) pixels have a value of 4096 or or higher, and that the approximate FWHM is 3 pixels. IDL> GCNTRD, IM, 631, 48, XCEN, YCEN, 3, MAXGOOD = 4096 MODIFICATION HISTORY: Written June 2004, W. Landsman following algorithm used by P. Stetson in DAOPHOT2. Modified centroid computation (as in IRAF/DAOFIND) to allow shifts of more than 1 pixel from initial guess. March 2008 First perform Gaussian convolution prior to finding maximum pixel to smooth out noise W. Landsman Jan 2009(See astrolib/pro/gcntrd.pro)
GEO2ECI
[Previous Routine] [Next Routine] [List of Routines]NAME: GEO2ECI PURPOSE: Convert geographic spherical coordinates to Earth-centered inertial coords EXPLANATION: Converts from geographic spherical coordinates [latitude, longitude, altitude] to ECI (Earth-Centered Inertial) [X,Y,Z] rectangular coordinates. JD time is also needed. Geographic coordinates are in degrees/degrees/km Geographic coordinates assume the Earth is a perfect sphere, with radius equal to its equatorial radius. ECI coordinates are in km from Earth center. CALLING SEQUENCE: ECIcoord=geo2eci(gcoord,JDtime) INPUT: gcoord: geographic [latitude,longitude,altitude], or a an array [3,n] of n such coordinates JDtime: Julian Day time, double precision. Can be a 1-D array of n such times. KEYWORD INPUTS: None OUTPUT: a 3-element array of ECI [X,Y,Z] coordinates, or an array [3,n] of n such coordinates, double precision COMMON BLOCKS: None PROCEDURES USED: CT2LST - Convert Local Civil Time to Local Mean Sidereal Time EXAMPLES: IDL> ECIcoord=geo2eci([0,0,0], 2452343.38982663D) IDL> print,ECIcoord -3902.9606 5044.5548 0.0000000 (The above is the ECI coordinates of the intersection of the equator and Greenwich's meridian on 2002/03/09 21:21:21.021) MODIFICATION HISTORY: Written by Pascal Saint-Hilaire (shilaire@astro.phys.ethz.ch) on 2002/05/14(See astrolib/pro/geo2eci.pro)
GEO2GEODETIC
[Previous Routine] [Next Routine] [List of Routines]NAME: GEO2GEODETIC PURPOSE: Convert from geographic/planetographic to geodetic coordinates EXPLANATION: Converts from geographic (latitude, longitude, altitude) to geodetic (latitude, longitude, altitude). In geographic coordinates, the Earth is assumed a perfect sphere with a radius equal to its equatorial radius. The geodetic (or ellipsoidal) coordinate system takes into account the Earth's oblateness. Geographic and geodetic longitudes are identical. Geodetic latitude is the angle between local zenith and the equatorial plane. Geographic and geodetic altitudes are both the closest distance between the satellite and the ground. The PLANET keyword allows a similar transformation for the other planets (planetographic to planetodetic coordinates). The EQUATORIAL_RADIUS and POLAR_RADIUS keywords allow the transformation for any ellipsoid. Latitudes and longitudes are expressed in degrees, altitudes in km. REF: Stephen P. Keeler and Yves Nievergelt, "Computing geodetic coordinates", SIAM Rev. Vol. 40, No. 2, pp. 300-309, June 1998 Planetary constants from "Allen's Astrophysical Quantities", Fourth Ed., (2000) CALLING SEQUENCE: ecoord=geo2geodetic(gcoord,[ PLANET=,EQUATORIAL_RADIUS=, POLAR_RADIUS=]) INPUT: gcoord = a 3-element array of geographic [latitude,longitude,altitude], or an array [3,n] of n such coordinates. OPTIONAL KEYWORD INPUT: PLANET = keyword specifying planet (default is Earth). The planet may be specified either as an integer (1-9) or as one of the (case-independent) strings 'mercury','venus','earth','mars', 'jupiter','saturn','uranus','neptune', or 'pluto' EQUATORIAL_RADIUS : Self-explanatory. In km. If not set, PLANET's value is used. POLAR_RADIUS : Self-explanatory. In km. If not set, PLANET's value is used. OUTPUT: a 3-element array of geodetic/planetodetic [latitude,longitude,altitude], or an array [3,n] of n such coordinates, double precision. COMMON BLOCKS: None RESTRICTIONS: Whereas the conversion from geodetic to geographic coordinates is given by an exact, analytical formula, the conversion from geographic to geodetic isn't. Approximative iterations (as used here) exist, but tend to become less good with increasing eccentricity and altitude. The formula used in this routine should give correct results within six digits for all spatial locations, for an ellipsoid (planet) with an eccentricity similar to or less than Earth's. More accurate results can be obtained via calculus, needing a non-determined amount of iterations. In any case, IDL> PRINT,geodetic2geo(geo2geodetic(gcoord)) - gcoord is a pretty good way to evaluate the accuracy of geo2geodetic.pro. EXAMPLES: Locate the geographic North pole, altitude 0., in geodetic coordinates IDL> geo=[90.d0,0.d0,0.d0] IDL> geod=geo2geodetic(geo); convert to equivalent geodetic coordinates IDL> PRINT,geod 90.000000 0.0000000 21.385000 As above, but for the case of Mars IDL> geod=geo2geodetic(geo,PLANET='Mars') IDL> PRINT,geod 90.000000 0.0000000 18.235500 MODIFICATION HISTORY: Written by Pascal Saint-Hilaire (shilaire@astro.phys.ethz.ch), May 2002 Generalized for all solar system planets by Robert L. Marcialis (umpire@lpl.arizona.edu), May 2002 Modified 2002/05/18, PSH: added keywords EQUATORIAL_RADIUS and POLAR_RADIUS(See astrolib/pro/geo2geodetic.pro)
GEO2MAG()
[Previous Routine] [Next Routine] [List of Routines]NAME: GEO2MAG() PURPOSE: Convert from geographic to geomagnetic coordinates EXPLANATION: Converts from GEOGRAPHIC (latitude,longitude) to GEOMAGNETIC (latitude, longitude). (Altitude remains the same) Latitudes and longitudes are expressed in degrees. CALLING SEQUENCE: mcoord=geo2mag(gcoord) INPUT: gcoord = a 2-element array of geographic [latitude,longitude], or an array [2,n] of n such coordinates. KEYWORD INPUTS: None OUTPUT: a 2-element array of magnetic [latitude,longitude], or an array [2,n] of n such coordinates COMMON BLOCKS: None EXAMPLES: geographic coordinates of magnetic south pole IDL> mcoord=geo2mag([79.3,288.59]) IDL> print,mcoord 89.999992 -173.02325 MODIFICATION HISTORY: Written by Pascal Saint-Hilaire (Saint-Hilaire@astro.phys.ethz.ch), May 2002(See astrolib/pro/geo2mag.pro)
GEODETIC2GEO
[Previous Routine] [Next Routine] [List of Routines]NAME: GEODETIC2GEO PURPOSE: Convert from geodetic (or planetodetic) to geographic coordinates EXPLANATION: Converts from geodetic (latitude, longitude, altitude) to geographic (latitude, longitude, altitude). In geographic coordinates, the Earth is assumed a perfect sphere with a radius equal to its equatorial radius. The geodetic (or ellipsoidal) coordinate system takes into account the Earth's oblateness. Geographic and geodetic longitudes are identical. Geodetic latitude is the angle between local zenith and the equatorial plane. Geographic and geodetic altitudes are both the closest distance between the satellite and the ground. The PLANET keyword allows a similar transformation for the other planets (planetodetic to planetographic coordinates). The EQUATORIAL_RADIUS and POLAR_RADIUS keywords allow the transformation for any ellipsoid. Latitudes and longitudes are expressed in degrees, altitudes in km. REF: Stephen P. Keeler and Yves Nievergelt, "Computing geodetic coordinates", SIAM Rev. Vol. 40, No. 2, pp. 300-309, June 1998 Planetary constants from "Allen's Astrophysical Quantities", Fourth Ed., (2000) CALLING SEQUENCE: gcoord = geodetic2geo(ecoord, [ PLANET= ] ) INPUT: ecoord = a 3-element array of geodetic [latitude,longitude,altitude], or an array [3,n] of n such coordinates. OPTIONAL KEYWORD INPUT: PLANET = keyword specifying planet (default is Earth). The planet may be specified either as an integer (1-9) or as one of the (case-independent) strings 'mercury','venus','earth','mars', 'jupiter','saturn','uranus','neptune', or 'pluto' EQUATORIAL_RADIUS : Self-explanatory. In km. If not set, PLANET's value is used. Numeric scalar POLAR_RADIUS : Self-explanatory. In km. If not set, PLANET's value is used. Numeric scalar OUTPUT: a 3-element array of geographic [latitude,longitude,altitude], or an array [3,n] of n such coordinates, double precision The geographic and geodetic longitudes will be identical. COMMON BLOCKS: None EXAMPLES: IDL> geod=[90,0,0] ; North pole, altitude 0., in geodetic coordinates IDL> geo=geodetic2geo(geod) IDL> PRINT,geo 90.000000 0.0000000 -21.385000 As above, but the equivalent planetographic coordinates for Mars IDL> geod=geodetic2geo(geod,PLANET='Mars'); IDL> PRINT,geod 90.000000 0.0000000 -18.235500 MODIFICATION HISTORY: Written by Pascal Saint-Hilaire (shilaire@astro.phys.ethz.ch), May 2002 Generalized for all solar system planets by Robert L. Marcialis (umpire@lpl.arizona.edu), May 2002 Modified 2002/05/18, PSH: added keywords EQUATORIAL_RADIUS and POLAR_RADIUS(See astrolib/pro/geodetic2geo.pro)
GETOPT
[Previous Routine] [Next Routine] [List of Routines]NAME: GETOPT PURPOSE: Convert a string supplied by the user into a valid scalar or vector EXPLANATION: Distinct elements in the string may be separated by either a comma or a space. The output scalar or vector can be specified to be either integer or floating point. A null string is converted to a zero. CALLING SEQUENCE: option = GETOPT( input, [ type, numopt, COUNT = ]) INPUTS: input - string that was input by user in response to a prompt Arithmetic operations can be included in the string (see examples) OPTIONAL INPUTS: type - Either an "I" (integer) or an "F" (floating point) specifying the datatype of the output vector. Default is floating point numopt - number of values expected by calling procedure If less than NUMOPT values are supplied the output vector will be padded with zeros. OUTPUTS: option - scalar or vector containing the numeric conversion of the fields in the string INPUT. If NUMOPT is not supplied, the number of elements in OPTION will equal the number of distinct fields in INPUT. OPTIONAL INPUT KEYWORD: Count - integer giving the number of values actually returned by GETOPT. If the input is invalid then COUNT is set to -1 NOTES: (1) If an input is invalid, Count is set to -1 and the result is set to 999. (2) GETOPT uses the execute function to interpret the user string. Therefore GETOPT itself cannot be called with the EXECUTE function. (3) GETOPT has a hard limit of 10 tokens in the input string. EXAMPLES: (1) a = getopt( '3.4,5*4 ', 'I' ) yields a = [ 3, 20] (2) a = getopt( '5/2.', 'F', 5) yields a = [2.5,0.,0.,0.,0.] (3) a = getopt( '2*3,5,6') yields a = [6.,5.,6.] REVISON HISTORY: written by B. Pfarr, STX, 5/6/87 change value of !ERR W. Landsman STX, 6/30/88 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/getopt.pro)
GETPRO
[Previous Routine] [Next Routine] [List of Routines]NAME: GETPRO PURPOSE: Search !PATH for a procedure, and copy into user's working directory EXPLANATION: Extract a procedure from an IDL Library or directory given in the !PATH system variable and place it in the current default directory (presumably to be edited by the user). CALLING SEQUENCE: GETPRO, [ proc_name ] ;Find PROC_NAME in !PATH and copy OPTIONAL INPUT: proc_name - Character string giving the name of the IDL procedure or function. Do not give an extension. If omitted, the program will prompt for PROC_NAME. OUTPUTS: None. SIDE EFFECTS: A file with the extension .pro and a name given by PROC_NAME will be created on the user's directory. PROCEDURE: The FILE_WHICH() function is used to locate the procedure in the IDL !PATH. When found, FILE_COPY is used to copy the procedure into the user's current default directory. If not found in !PATH, then the ROUTINE_INFO() function is used to determine if it is an intrinsic IDL procedure. EXAMPLE: Put a copy of the USER library procedure CURVEFIT on the current directory IDL> getpro, 'CURVEFIT' RESTRICTIONS: User will be unable to obain source code for a native IDL function or procedure, or for a FORTRAN or C routine added with CALL_EXTERNAL. User must have write privilege to the current directory PROCEDURE CALLS: ZPARCHECK REVISION HISTORY: Written W. Landsman, STX Corp. June 1990 Now use intrinsic EXPAND_PATH() command W. Landsman November 1994 Use ROUTINE_NAMES() to check for intrinsic procs W. Landsman July 95 Update for Windows/IDL W. Landsman September 95 Check if procedure is in current directory W. Landsman June 1997 Use ROUTINE_INFO instead of undocumented ROUTINE_NAMES W.L. October 1998 Use FILE_WHICH() to locate procedure W. Landsman May 2006 Assume since V5.5, remove VMS support W. Landsman Sep 2006 Assume since V6.0, use file_basename() W.Landsman Feb 2009 Test for .sav file, more robust test for write privilege W.L. Jul 2010(See astrolib/pro/getpro.pro)
GETPSF
[Previous Routine] [Next Routine] [List of Routines]NAME: GETPSF PURPOSE: To generate a point-spread function (PSF) from observed stars. EXPLANATION: The PSF is represented as a 2-dimensional Gaussian (integrated over each pixel) and a lookup table of residuals. The lookup table and Gaussian parameters are output in a FITS image file. The PSF FITS file created by GETPSF can be read with the procedure RDPSF. Adapted from the 1986 STSDAS version of DAOPHOT CALLING SEQUENCE: GETPSF, image, xc, yc, apmag, sky, [ronois, phpadu, gauss, psf, idpsf, psfrad, fitrad, psfname, /DEBUG ] INPUTS: IMAGE - input image array XC - input vector of x coordinates (from FIND), these should be IDL (first pixel is (0,0)) convention. YC - input vector of y coordinates (from FIND) APMAG - vector of magnitudes (from APER), used for initial estimate of gaussian intensity. If APMAG is multidimensional, (more than 1 aperture was used in APER) then the first aperture is used. SKY - vector of sky values (from APER) OPTIONAL INPUTS: The user will be prompted for the following parameters if not supplied. RONOIS - readout noise per pixel, (in electrons, or equivalent photons) PHPADU - photons per analog digital unit, used to scale the data numbers in IMAGE into photon units IDPSF - subscripts of the list of stars created by APER which will be used to define the PSF. Stars whose centroid does not fall within PSFRAD of the edge of the frame, or for which a Gaussian fit requires more than 25 iterations, will be ignored when creating the final PSF. PSFRAD - the scalar radius, in pixels, of the circular area within which the PSF will be defined. This should be slightly larger than the radius of the brightest star that one will be interested in. FITRAD - the scalar radius, in pixels of the circular area used in the least-square star fits. Stetson suggest that FITRAD should approximately equal to the FWHM, slightly less for crowded fields. (FITRAD must be smaller than PSFRAD.) PSFNAME- Name of the FITS file that will contain the table of residuals, and the best-fit Gaussian parameters. This file is subsequently required for use by NSTAR. OPTIONAL OUTPUTS: GAUSS - 5 element vector giving parameters of gaussian fit to the first PSF star GAUSS(0) - height of the gaussian (above sky) GAUSS(1) - the offset (in pixels) of the best fitting gaussian and the original X centroid GAUSS(2) - similiar offset from the Y centroid GAUSS(3) - Gaussian sigma in X GAUSS(4) - Gaussian sigma in Y PSF - 2-d array of PSF residuals after a Gaussian fit. PROCEDURE: GETPSF fits a Gaussian profile to the core of the first PSF star and generates a look-up table of the residuals of the actual image data from the Gaussian fit. If desired, it will then fit this PSF to another star (using PKFIT) to determine its precise centroid, scale the same Gaussian to the new star's core, and add the differences between the actual data and the scaled Gaussian to the table of residuals. (In other words, the Gaussian fit is performed only on the first star.) OPTIONAL KEYWORD INPUT: DEBUG - if this keyword is set and non-zero, then the result of each fitting iteration will be displayed. PROCEDURES CALLED DAOERF, MAKE_2D, MKHDR, RINTER(), PKFIT, STRNUMBER(), STRN(), WRITEFITS REVISON HISTORY: Adapted from the 1986 version of DAOPHOT in STSDAS IDL Version 2 W Landsman November 1988 Use DEBUG keyword instead of !DEBUG W. Landsman May 1996 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/getpsf.pro)
GETROT
[Previous Routine] [Next Routine] [List of Routines]NAME: GETROT PURPOSE: Return the rotation and plate scale of an image from its FITS header EXPLANATION: Derive the counterclockwise rotation angle, and the X and Y scale factors of an image, from a FITS image header. The input parameter may be either a FITS image header or an astrometry structure (as obtained by extast.pro) CALLING SEQUENCE: GETROT, Hdr, [ Rot, CDelt, /SILENT, DEBUG = ] or GETROT, Astr, Rot, CDelt, /SILENT, DEBUG = ] INPUT PARAMETERS: HDR - FITS Image header (string array). Program will extract the astrometry structure or ASTR - ASTROMETRY structure, of the type returned by EXTAST. See the documentation for EXTAST.PRO for details. OPTIONAL OUTPUT PARAMETERS: ROT - Scalar giving the counterclockwise rotation of NORTH in DEGREES from the +Y axis of the image. CDELT- 2 element vector giving the scale factors in DEGREES/PIXEL in the X and Y directions. CDELT[1] is always positive, whereas CDELT[0] is negative for a normal left-handed coordinate system, and positive for a right-handed system. If no output variables are supplied (or /DEBUG is set), then GETROT will display the rotation and plate scale at the terminal. OPTIONAL INPUT KEYWORD ALT - single character 'A' through 'Z' or ' ' specifying an alternate astrometry system present in the FITS header. See extast.pro for more information on the ALT keyword. Ignored if an astrometry structure rather than FITS header is supplied. DEBUG - if DEBUG is set, GETROT will print the rotation for both the X and Y axis when these values are unequal. If DEBUG is set to 2, then the output parameter ROT will contain both X and Y rotations. /SILENT - if set, then do not provide a warning about a right-handed coordinate system PROCEDURE: If the FITS header already contains CDELT (and CD or CROTA) keyword, (as suggested by the Calabretta & Greisen (2002, A&A, 395, 1077) FITS standard) then this is used for the scale factor. If the header contains CD keywords but no CDELT keywords (as in IRAF headers) then the scale factor is derived from the CD matrix. In case of skew (different rotations of the X and Y axes), the rotations are averaged together if they are less than 2 degrees. Otherwise, a warning is given and the X rotation is used. PROCEDURES USED: EXTAST, GSSS_EXTAST REVISION HISTORY: Written W. Landsman STX January 1987 Option to return both rotations added. J. D. Offenberg, STX, Aug 1991 Use new astrometry structure W. Landsman Mar 1994 Recognize a GSSS header W. Landsman June 1994 Correct rotation determination with unequal CDELT values WL October 1998 Consistent conversion between CROTA and CD matrix WL October 2000 Correct CDELT computations for rotations near 90 deg WL November 2002 Preserve sign in the CDELT output WL June 2003 Check if latitude/longitude reversed in CTYPE WL February 2004 Fix problem in latitude check M.Lombardi/W.Landsman Sep 2004 Added ALT keyword W. Landsman May 2005 Account for any rotation of the native system by examining the value of LONGPOLE H. Taylor/W. Landsman Account for case where X,Y rotations differ by 2*!pi WL. Aug 2011(See astrolib/pro/getrot.pro)
GETTOK
[Previous Routine] [Next Routine] [List of Routines]NAME: GETTOK PURPOSE: Retrieve the first part of a (vector) string up to a specified character EXPLANATION: GET TOKen - Retrieve first part of string until the character char is encountered. CALLING SEQUENCE: token = gettok( st, char, [ /EXACT, /NOTRIM ] ) INPUT: char - character separating tokens, scalar string INPUT-OUTPUT: st - string to get token from (on output token is removed unless /NOTRIM is set), scalar or vector OUTPUT: token - extracted string value is returned, same dimensions as st OPTIONAL INPUT KEYWORD: /EXACT - The default behaviour of GETTOK is to remove any leading blanks and (if the token is a blank) convert tabs to blanks. Set the /EXACT keyword to skip these steps and leave the input string unchanged before searching for the character tokens. /NOTRIM - if set, then the input string is left unaltered EXAMPLE: If ST is ['abc=999','x=3.4234'] then gettok(ST,'=') would return ['abc','x'] and ST would be left as ['999','3.4234'] PROCEDURE CALLS: REPCHR() HISTORY version 1 by D. Lindler APR,86 Remove leading blanks W. Landsman (from JKF) Aug. 1991 V5.3 version, accept vector input W. Landsman February 2000 Slightly faster implementation W. Landsman February 2001 Added EXACT keyword W. Landsman March 2004 Assume since V5.4, Use COMPLEMENT keyword to WHERE W. Landsman Apr 2006 Added NOTRIM keyword W. L. March 2011(See astrolib/pro/gettok.pro)
GET_COORDS
[Previous Routine] [Next Routine] [List of Routines]NAME: GET_COORDS PURPOSE: Converts a string with angular coordinates to floating point values. EXPLANATION: Although called by ASTRO.PRO, this is a general purpose routine. The user may input as floating point or sexagesimal. If user inputs calling procedure's job to convert hours to degrees if needed. Since the input string is parsed character-by-character, ANY character that is not a digit, minus sign or decimal point may be used as a delimiter, i.e. acceptable examples of user input are: 1:03:55 -10:15:31 1 3 55.0 -10 15 31 1*3 55 -10abcd15efghij31 1.065278 hello -10.25861 CALLING SEQUENCE: GET_COORDS, Coords, [ PromptString, NumVals, INSTRING =, /QUIET ] OPTIONAL INPUT: PromptString - A string to inform the user what data are to be entered OPTIONAL KEYWORD INPUT: InString - a keyword that, if set, is assumed to already contain the input data string to be parsed. If this keyword is set, then the user is not prompted for any input. /Quiet - if set the program won't printout any error messages, but bad input is still flagged by Coords=[-999,-999]. OUTPUT: Coords - a 2 element floating array containing the coordinates. The vector [-999,-999] is returned if there has been an error. OPTIONAL OUTPUT: NumVals - the number of separate values entered by the user: 2 if the user entered the coordinates as floating point numbers, 6 if the user entered the coordinates as sexagesimal numbers. Some calling procedures might find this information useful (e.g., to to print some output in the same format as the user's input). REVISION HISTORY: Written by Joel Parker, 5 MAR 90 Included InString and Quiet keywords. Cleaned up some of the code and comments. JWmP, 16 Jun 94 ******************************************************************************* Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/get_coords.pro)
GET_DATE
[Previous Routine] [Next Routine] [List of Routines]NAME: GET_DATE PURPOSE: Return the (current) UTC date in CCYY-MM-DD format for FITS headers EXPLANATION: This is the format required by the DATE and DATE-OBS keywords in a FITS header. CALLING SEQUENCE: GET_DATE, FITS_date, [ in_date, /OLD, /TIMETAG ] OPTIONAL INPUTS: in_date - string (scalar or vector) containing dates in IDL systime() format (e.g. 'Tue Sep 25 14:56:14 2001') OUTPUTS: FITS_date = A scalar character string giving the current date. Actual appearance of dte depends on which keywords are supplied. No Keywords supplied - dte is a 10 character string with the format CCYY-MM-DD whererepresents a calendar year, the ordinal number of a calendar month within the calendar year, and the ordinal number of a day within the calendar month. /TIMETAG set - dte is a 19 character string with the format CCYY-MM-DDThh:mm:ss where represents the hour in the day, the minutes, the seconds, and the literal 'T' the ISO 8601 time designator /OLD set - dte is an 8 character string in DD/MM/YY format INPUT KEYWORDS: /TIMETAG - Specify the time to the nearest second in the DATE format /OLD - Return the DATE format formerly (pre-1997) recommended for FITS Note that this format is now deprecated because it uses only a 2 digit representation of the year. EXAMPLE: Add the current date to the DATE keyword in a FITS header,h IDL> GET_DATE,dte IDL> sxaddpar, h, 'DATE', dte, 'Date header was created' NOTES: (1) A discussion of the DATExxx syntax in FITS headers can be found in http://www.cv.nrao.edu/fits/documents/standards/year2000.txt (2) Those who wish to use need further flexibility in their date formats (e.g. to use TAI time) should look at Bill Thompson's time routines in http://sohowww.nascom.nasa.gov/solarsoft/gen/idl/time PROCEDURES USED: DAYCNV - Convert Julian date to Gregorian calendar date REVISION HISTORY: Written W. Landsman March 1991 Major rewrite to write new DATExxx syntax W. Landsman August 1997 Converted to IDL V5.0 W. Landsman September 1997 Work after year 2000 even with /OLD keyword W. Landsman January 2000 Don't need to worry about TIME_DIFF since V5.4 W. Landsman July 2001 Assume since V5.4, remove LOCAL_DIFF keyword W. Landsman April 2006 (See astrolib/pro/get_date.pro)
GET_EQUINOX
[Previous Routine] [Next Routine] [List of Routines]NAME: GET_EQUINOX PURPOSE: Return the equinox value from a FITS header. EXPLANATION: Checks for 4 possibilities: (1) If the EQUINOX keyword is found and has a numeric value, then this value is returned (2) If the EQUINOX keyword has the values 'J2000' or 'B1950', then either 2000. or 1950. is returned. (3) If the EQUINOX keyword is not found, then GET_EQUINOX will return the EPOCH keyword value. This usage of EPOCH is disparaged. (4) If neither EQUINOX no EPOCH is found, then the RADESYS keyword (or the deprecated RADECSYS keyword) is checked. If the value is 'ICRS' or 'FK5' then 2000 is is returned, if it is 'FK4' then 1950 is returned. According Calabretta & Greisen (2002, A&A, 395, 1077) the EQUINOX should be written as a numeric value, as in format (1). However, in older FITS headers, the EQUINOX might have been written using formats (2) or (3). CALLING SEQUENCE: Year = GET_EQUINOX( Hdr, [ Code ] ) INPUTS: Hdr - FITS Header, string array, will be searched for the EQUINOX (or EPOCH) keyword. OUTPUT: Year - Year of equinox in FITS header, numeric scalar OPTIONAL OUTPUT: Code - Result of header search, scalar -1 - EQUINOX, EPOCH or RADECSYS keyword not found in header 0 - EQUINOX found as a numeric value 1 - EPOCH keyword used for equinox (not recommended) 2 - EQUINOX found as 'B1950' 3 - EQUINOX found as 'J2000' 4 - EQUINOX derived from value of RADESYS or RADECSYS keyword 'ICRS', 'FK5' ==> 2000, 'FK4' ==> 1950 OPTIONAL KEYWORD INPUT: ALT - single character 'A' through 'Z' or ' ' specifying which astrometry system to use in the FITS header. The default is to use the primary astrometry or ALT = ''. If /ALT is set, then this is equivalent to ALT = 'A'. See Section 3.3 of Greisen & Calabretta (2002, A&A, 395, 1061) for information about alternate astrometry keywords. PROCEDURES USED: ZPARCHECK, SXPAR() NOTES: Technically, RADESYS = 'ICRS' does not specify any equinox, but can be assumed to be equivalent to J2000 for all but highest-precision work. REVISION HISTORY: Written W. Landsman STX March, 1991 Don't use !ERR W. Landsman February 2000 N = 1 for check of EPOCH keyword, not 0 S. Ott July 2000 Added ALT keyword, recognize RADESYS along with deprecated RADECSYS W. Landsman Sep 2011(See astrolib/pro/get_equinox.pro)
GET_JULDATE
[Previous Routine] [Next Routine] [List of Routines]NAME: GET_JULDATE PURPOSE: Return the current Julian Date EXPLANATION: In V5.4, GET_JULDATE became completely obsolete with the introduction of the /UTC keyword to SYSTIME(). So GET_JULDATE,jd is equivalent to jd = SYSTIME(/JULIAN,/UTC). CALLING SEQUENCE: GET_JULDATE,jd INPUTS: None OUTPUTS: jd = Current Julian Date, double precision scalar EXAMPLE: Return the current hour, day, month and year as integers IDL> GET_JULDATE, JD ;Get current Julian date IDL> DAYCNV, JD, YR, MON, DAY, HOURS ;Convert to hour,day month & year METHOD: A call is made to SYSTIME(/JULIAN,/UTC). REVISION HISTORY: Written Wayne Landsman March, 1991 Converted to IDL V5.0 W. Landsman September 1997 Assume since V5.4 Use /UTC keyword to SYSTIME() W. Landsman April 2006(See astrolib/pro/get_juldate.pro)
GLACTC
[Previous Routine] [Next Routine] [List of Routines]NAME: GLACTC PURPOSE: Convert between celestial and Galactic (or Supergalactic) coordinates. EXPLANATION: Program to convert right ascension (ra) and declination (dec) to Galactic longitude (gl) and latitude (gb) (j=1) or vice versa (j=2). CALLING SEQUENCE: GLACTC, ra, dec, year, gl, gb, j, [ /DEGREE, /FK4, /SuperGalactic ] INPUT PARAMETERS: year equinox of ra and dec, scalar (input) j direction of conversion (input) 1: ra,dec --> gl,gb 2: gl,gb --> ra,dec INPUTS OR OUTPUT PARAMETERS: ( depending on argument J ) ra Right ascension, hours (or degrees if /DEGREES is set), scalar or vector dec Declination, degrees,scalar or vector gl Galactic longitude, degrees, scalar or vector gb Galactic latitude, degrees, scalar or vector All results forced double precision floating. OPTIONAL INPUT KEYWORD PARAMETERS: /DEGREE - If set, then the RA parameter (both input and output) is given in degrees rather than hours. /FK4 - If set, then the celestial (RA, Dec) coordinates are assumed to be input/output in the FK4 system. By default, coordinates are assumed to be in the FK5 system. For B1950 coordinates, set the /FK4 keyword *and* set the year to 1950. /SuperGalactic - If set, the GLACTC returns SuperGalactic coordinates as defined by deVaucouleurs et al. (1976) to account for the local supercluster. The North pole in SuperGalactic coordinates has Galactic coordinates l = 47.47, b = 6.32, and the origin is at Galactic coordinates l = 137.37, b= 0 EXAMPLES: Find the Galactic coordinates of Altair (RA (J2000): 19 50 47 Dec (J2000): 08 52 06) IDL> glactc, ten(19,50,47),ten(8,52,6),2000,gl,gb,1 ==> gl = 47.74, gb = -8.91 PROCEDURE CALLS: BPRECESS, JPRECESS, PRECESS HISTORY: FORTRAN subroutine by T. A. Nagy, 21-MAR-78. Conversion to IDL, R. S. Hill, STX, 19-OCT-87. Modified to handle vector input, E. P. Smith, GSFC, 14-OCT-94 Converted to IDL V5.0 W. Landsman September 1997 Added DEGREE keyword, C. Markwardt, Nov 1999 Major rewrite, default now FK5 coordinates, added /FK4 keyword use external precession routines W. Landsman April 2002 Add /Supergalactic keyword W. Landsman September 2002 Fix major bug when year not 2000 and /FK4 not set W. Landsman July 2003(See astrolib/pro/glactc.pro)
GLACTC_PM
[Previous Routine] [Next Routine] [List of Routines]NAME: GLACTC_PM PURPOSE: Convert between celestial and Galactic (or Supergalactic) proper motion (also converts coordinates). EXPLANATION: Program to convert proper motion in equatorial coordinates (ra,dec) to proper motion in Galactic coordinates (gl, gb) or Supergalacic Coordinates (sgl,sgb) or back to equatorial coordinates (j=2). The proper motion unit is arbitrary, but be sure to set /MUSTAR if units are the projection of the proper motion on the RA, Dec axis. It does precession on the coordinates but does not take care of precession of the proper motions which is usually a very small effect. CALLING SEQUENCE: GLACTC_PM, ra, dec, mu_ra,mu_dec,year, gl, gb, mu_gl, mu_gb, j, [ /DEGREE, /FK4, /SuperGalactic, /mustar ] INPUT PARAMETERS: year equinox of ra and dec, scalar (input) j direction of conversion (input) 1: ra,dec,mu_ra,mu_dec --> gl,gb,mu_gl,mu_gb 2: gl,gb,mu_gl,mu_gb --> ra,dec,mu_ra,mu_dec INPUTS OR OUTPUT PARAMETERS: ( depending on argument J ) ra Right ascension, hours (or degrees if /DEGREES is set), scalar or vector. dec Declination, degrees,scalar or vector mu_ra right ascension proper motion any proper motion unit (angle/time) mu_dec declination proper motion in any proper motion unit (angle/time) gl Galactic longitude, degrees, scalar or vector gb Galactic latitude, degrees, scalar or vector mu_gl galactic longitude proper motion in any time unit mu_gb galactic latitude proper motion in any time unit All results forced double precision floating. OPTIONAL INPUT KEYWORD PARAMETERS: /DEGREE - If set, then the RA parameter (both input and output) is given in degrees rather than hours. /FK4 - If set, then the celestial (RA, Dec) coordinates are assumed to be input/output in the FK4 system. By default, coordinates are assumed to be in the FK5 system. For B1950 coordinates, set the /FK4 keyword *and* set the year to 1950. /SuperGalactic - If set, the GLACTC returns SuperGalactic coordinates as defined by deVaucouleurs et al. (1976) to account for the local supercluster. The North pole in SuperGalactic coordinates has Galactic coordinates l = 47.47, b = 6.32, and the origin is at Galactic coordinates l = 137.37, b= 0 /mustar - if set then input and output of mu_ra and mu_dec are the projections of mu in the ra or dec direction rather than the d(ra)/dt or d(mu)/dt. So mu_ra becomes mu_ra*cos(dec) and mu_gl becomes mu_gl*cos(gb). EXAMPLES: Find the SuperGalactic proper motion of M33 given its equatorial proper motion mu* =(-29.3, 45.2) microas/yr. Where the (*) indicates ra component is actual mu_ra*cos(dec) (Position: RA (J2000): 01 33 50.9, Dec (J2000): 30 39 36.8) IDL> glactc_pm, ten(1,33,50.9),ten(30,39,36.8),-29.3,45.2, 2000,$ sgl,sgb,mu_sgl,mu_sgb,1,/Supergalactic,/mustar ==> SGL = 328.46732 deg, SGB = -0.089896901 deg, mu_sgl = 33.732 muas/yr, mu_gb = 41.996 muas/yr. And for the roundtrip: IDL> glactc_pm, ra,dec,mu_ra,mu_dec,2000,$ IDL> sgl,sgb,mu_sgl,mu_sgb,2,/Supergalactic,/mustar ==> ra=1.5641376 hrs., dec= 30.660277 deg, mu_ra= -29.300000 muas/yr, mu_dec=i 45.200000 muas/yr PROCEDURE CALLS: BPRECESS, JPRECESS, PRECESS HISTORY: Written Ed Shaya, U of MD, Oct 2009. Adapted from GLACTC to make proper motion transformations, Correct occasional sign error in galactic longitude E. Shaya Nov 2011(See astrolib/pro/glactc_pm.pro)
GROUP
[Previous Routine] [Next Routine] [List of Routines]NAME: GROUP PURPOSE: Assign stars with non-overlapping PSF profiles into distinct groups EXPLANATION: Part of the IDL-DAOPHOT sequence CALLING SEQUENCE: GROUP, X, Y, RCRIT, NGROUP INPUTS: X - vector, giving X coordinates of a set of stars. Y - vector, giving Y coordinates of a set of stars. If X and Y are input as integers, then they will be converted to floating point RCRIT - scalar, giving minimum distance between stars of two distinct groups. Stars less than this distance from each other are always in the same group. Stetson suggests setting the critical distance equal to the PSF radius + the Fitting radius. OUTPUTS: NGROUP - integer vector, same number of elements as X and Y, giving a group number for each star position. Group numbering begins with 0. METHOD: Each position is initially given a unique group number. The distance of each star is computed against every other star. Those distances less than RCRIT are assigned the minimum group number of the set. A check is then made to see if any groups have merged together. PROCEDURES USED: REM_DUP() REVISION HISTORY: Written W. Landsman STX April, 1988 Major revision to properly merge groups together W. Landsman Sep 1991 Work for more than 32767 points W. Landsman March 1997 Converted to IDL V5.0 W. Landsman September 1997 Avoid overflow if X and Y are integers W. Landsman Feb. 1999(See astrolib/pro/group.pro)
GSSSADXY
[Previous Routine] [Next Routine] [List of Routines]NAME: GSSSADXY PURPOSE: Converts RA and DEC (J2000) to (X,Y) for an STScI GuideStar image. EXPLANATION: The sky coordinates may be printed and/or returned in variables. CALLING SEQUENCE: GSSSADXY, GSA, Ra,Dec, [ X, Y, /Print ] INPUT: GSA - the GSSS Astrometry structure created by GSSSEXTAST RA - the RA coordinate(s) in *degrees*, scalar or vector DEC - the DEC coordinate(s) in *degrees*, scalar or vector OPTIONAL KEYWORD INPUT: /PRINT - If this keyword is set and non-zero, then coordinates will be displayed at the terminal OUTPUT: X - the corresponding X pixel coordinate(s), double precision Y - the corresponding Y pixel coordinate(s), double precision X and Y will be in IDL convention (first pixel 0,0) EXAMPLE: Given a FITS header, hdr, from the STScI Guidestar Survey, determine the X,Y coordinates of 3C 273 (RA = 12 29 6.7 +02 03 08) IDL> GSSSEXTAST, hdr, gsa ;Extract astrometry structure IDL> GSSSADXY, gsa, ten(12,29,6.7)*15,ten(2,3,8),/print NOTES: For most purpose users can simply use ADXY, which will call GSSSADXY if it is passed a GSSS header. PROCEDURES CALLED: ASTDISP - Print RA, Dec in standard format HISTORY: 10-JUL-90 Version 1 written by Eric W. Deutsch Derived from procedures written by Brian McLean Vectorized code W. Landsman March, 1991 14-AUG-91 Fixed error which caused returned X and Y to be .5 pixels too large. Now X,Y follows same protocol as ADXY. June 1994 - Dropped PRFLAG parameter, added /PRINT W. Landsman (HSTX) Converted to IDL V5.0 W. Landsman September 1997 29-JUN-99 Added support for AMD[X,Y]1[2-3] for DSS images by E. Deutsch Reduce memory requirements for large arrays D. Finkbeiner April 2004(See astrolib/pro/gsssadxy.pro)
GSSSEXTAST
[Previous Routine] [Next Routine] [List of Routines]NAME: GSSSEXTAST PURPOSE: Extract IDL astrometry structure from a ST Guide Star Survey FITS header EXPLANATION: This procedure extracts the astrometry information from a ST Guide Star Survey FITS header and places it in an IDL structure for subsequent use with GSSSxyad and GSSSadxy. CALLING SEQUENCE: GSSSExtast, hdr, astr, noparams INPUT: h - the GSSS FITS header OUTPUT: astr - Structure containing the GSSS Astrometry information .CTYPE = ['RA---GSS','DEC--GSS'] .CRVAL = plate center Ra, Dec (from PLTRAH, PLTRAM etc.) .XLL,.YLL = offsets lower lefthand corner .AMDX, .AMDY = 12 transformation coefficients .XSZ,.YSZ = X and Y pixel size in microns .PLTSCL = plate scale in arc sec/mm .PPO3, .PPO6 - orientation coefficients NOTES: Most users should use EXTAST rather than this procedure. EXTAST will call GSSSEXTAST if supplied with GSSS FITS header. PROCEDURES CALLED: SXPAR() - Extract parameter values from a FITS header HISTORY: 01-JUL-90 Version 1 written by Eric W. Deutsch Code derived from Software by Brian McLean 20-AUG-91 Modified to Double Precision Variables. E. Deutsch June 94 Change astrometry tags to better agree with EXTAST W. Landsman Converted to IDL V5.0 W. Landsman September 1997 29-JUN-99 Added support for AMD[X,Y]1[2-3] for DSS images by E. Deutsch Eliminate use of obsolete !ERR W. Landsman February 2000(See astrolib/pro/gsssextast.pro)
GSSSXYAD
[Previous Routine] [Next Routine] [List of Routines]NAME: GSSSXYAD PURPOSE: Convert (X,Y) coordinates in a STScI Guide Star image to RA and Dec EXPLANATION: The sky coordinates may be printed and/or returned in variables. CALLING SEQUENCE: GSSSxyad, gsa, x, y, ra, dec, [ /PRINT ] INPUT: GSA - The GSSS Astrometry structure extracted from a FITS header by GSSSEXTAST X - The X pixel coordinate(s) of the image, scalar or vector Y - The Y pixel coordinate(s) of the image, scalar or vector OUTPUT: RA - The RA coordinate of the given pixel(s) in *degrees* DEC - The DEC coordinate of the given pixel(s) in *degrees* Both RA and Dec will be returned as double precision OPTIONAL KEYWORD INPUT: /PRINT - If this keyword is set and non-zero, then coordinates will be displayed at the terminal EXAMPLE: Given a FITS header,hdr, from a GSSS image, print the astronomical coordinates of (X,Y) = (200.23, 100.16) at the terminal IDL> GSSSExtast, hdr, gsa ;Extract astrometry structure IDL> GSSSxyad, gsa, 200.23, 100.16, /print NOTES: For most purpose users can simply use XYAD, which will call GSSSXYAD if it is passed a GSSS header. PROCEDURES CALLED: ASTDISP - print RA, Dec in a standard format HISTORY: 01-JUL-90 Version 1 written by Eric W. Deutsch Vectorized Code W. Landsman March, 1991 14-AUG-91 Fixed error which caused returned RA and DEC to be off by -.5 pixels in both X,Y. Now X,Y follows same protocol as ADXY. 20-AUG-91 Modified to use AstDisp procedure. June 94 Added /PRINT keyword instead of PRFLAG W. Landsman June 94 Converted to IDL V5.0 W. Landsman September 1997 29-JUN-99 Added support for AMD[X,Y]1[2-3] for DSS images by E. Deutsch(See astrolib/pro/gsssxyad.pro)
GSSS_STDAST
[Previous Routine] [Next Routine] [List of Routines]NAME: GSSS_STDAST PURPOSE: Insert the closest tangent projection astrometry into an GSSS Image DESCRIPTION: This procedure takes a header with GSSS (ST Guide Star Survey) astrometry and writes a roughly equivalent tangent projection astrometry into the header. One might want to do this if (1) one needs to use software which does not recognize the GSSS astrometric parameters or (2) if the the image to be transformed, since the highly nonlinear GSSS solution does not transform easily. CALLING SEQUENCE: GSSS_STDAST, H, [Xpts, Ypts] INPUT - OUTPUT: H - FITS header (string array) containing GSSS astrometry. GSSS_STDAST will write the roughly equivalent tangent projection astrometry solution into H. OPTIONAL INPUTS: xpts, ypts -- Vectors giving the X and Y positions of the three reference points used to find approximate tangent projection. Default is Xpts = [0.2,0.8,0.5], Ypts = [0.2, 0.4, 0.8] METHOD: The procedures GSSSXYAD is used to exactly determine the RA and Dec at 3 reference points. STARAST is then used to find the tangent projection astrometry that best matches these reference points. NOTES: Images from the STScI server (http://archive.stsci.edu/dss/) contain both a GSSS polynomial plate solution and an approximate WCS tangent projection. The value of the WCSNAME keyword in the FITS header is 'DSS'. If WCSNAME = "DSS' then the more accurate DSS astrometry is extracted by EXTAST This procedure changes the value of WCSNAME to 'DSS_TANGENT' to indicate that the tangent solution should be used. Some early GSSS images (before the 1994 CD-Rom) used keywords CRPIXx rather than CNPIXx. The GSSS astrometry in these images could be corrupted by this procedure as the CRPIXx values will be altered. The tangent is only a approximation of the nonlinear GSSS astrometry, but is generally accurate to about 0.1 pixels on a 1024 x 1024 image. PROCEDURES USED: GSSSEXTAST, GSSSXYAD, STARAST, PUTAST, SXADDHIST, SXDELPAR HISTORY: 13-AUG-91 Version 2 written from MAKEASTGSSS Eric Deutsch (STScI) Delete CDELT* keywords from header W. Landsman May 1994 Remove call to BUILDAST W. Landsman Jan, 1995 Added optional Xpts, Ypts parameters E. Deutsch Oct, 1995 Add WCSNAME W. Landsman Nov 2006(See astrolib/pro/gsss_stdast.pro)
HADEC2ALTAZ
[Previous Routine] [Next Routine] [List of Routines]NAME: HADEC2ALTAZ PURPOSE: Converts Hour Angle and Declination to Horizon (alt-az) coordinates. EXPLANATION: Can deal with NCP/SCP singularity. Intended mainly to be used by program EQ2HOR CALLING SEQUENCE: HADEC2ALTAZ, ha, dec, lat ,alt ,az [ /WS ] INPUTS ha - the local apparent hour angle, in DEGREES, scalar or vector dec - the local apparent declination, in DEGREES, scalar or vector lat - the local latitude, in DEGREES, scalar or vector OUTPUTS alt - the local apparent altitude, in DEGREES. az - the local apparent azimuth, in DEGREES, all results in double precision OPTIONAL KEYWORD INPUT: /WS - Set this keyword for the output azimuth to be measured West from South. The default is to measure azimuth East from North. EXAMPLE: What were the apparent altitude and azimuth of the sun when it transited the local meridian at Pine Bluff Observatory (Lat=+43.07833 degrees) on April 21, 2002? An object transits the local meridian at 0 hour angle. Assume this will happen at roughly 1 PM local time (18:00 UTC). IDL> jdcnv, 2002, 4, 21, 18., jd ; get rough Julian date to determine ;Sun ra, dec. IDL> sunpos, jd, ra, dec IDL> hadec2altaz, 0., dec, 43.078333, alt, az ===> Altitude alt = 58.90 Azimuth az = 180.0 REVISION HISTORY: Written Chris O'Dell Univ. of Wisconsin-Madison May 2002(See astrolib/pro/hadec2altaz.pro)
HASTROM
[Previous Routine] [Next Routine] [List of Routines]NAME: HASTROM PURPOSE: Transformation of an image to align it with a reference image EXPLANATION: A transformation is applied (using POLY_2D) to an image so that its astrometry is identical with that in a reference header. This procedure can be used to align two images. CALLING SEQUENCE: HASTROM, oldim, oldhd, newim, newhd, refhd, [MISSING =, INTERP = ] or HASTROM, oldim, oldhd, refhd, [MISSING =, INTERP ={0,1,2}, NGRID =, CUBIC =, DEGREE = ] INPUTS: OLDIM - Image array to be manipulated. If only 3 parameters are supplied then OLDIM and OLDHD will be modified to contain the output image array and header OLDHD - FITS header array for OLDIM, containing astrometry parameters REFHD - Reference header, containing astrometry parameters. OLDIM will be rotated, shifted, and compressed or expanded until its astrometry matches that in REFHD. OUTPUTS: NEWIM - Image array after transformation has been performed. The dimensions of NEWIM will be identical to the NAXIS1 and NAXIS2 keywords specified in REFHD. Regions on the reference image that do not exist in OLDIM can be assigned a value with the MISSING keyword. NEWHD - Updated FITS image header associated with NEWIM OPTIONAL INPUT KEYWORDS: MISSING - Set this keyword to a scalar value which will be assigned to pixels in the output image which are out of range of the supplied imput image. If not supplied, then linear extrapolation is used. See the IDL manual on POLY_2D. ***NOTE: A bug was introduced into the POLY_2D function in IDL V5.5 (fixed in V6.1) such that the MISSING keyword may not work properly with floating point data*** INTERP - Scalar, one of 0, 1, or 2 determining type of interpolation 0 nearest neighbor, 1 (default) bilinear interpolation, 2 cubic interpolation. CUBIC - a scalar value between -1 and 0 specifying cubic interpolation with the specified value as the cubic interpolation parameter. (see poly_2d for info). Setting CUBIC to a value greater than zero is equivalent to setting CUBIC = -1. NGRID - Integer scalar specifying the number of equally spaced grid points on each axis to use to specify the transformation. The value of NGRID must always be greater than DEGREE + 1. The default is DEGREE + 2 which equals 3 (9 total points) for DEGREE=1 (linear warping). DEGREE - Integer scalar specifying the degree of the transformation. See the routine POLYWARP for more info. Default = 1 (linear transformation) unless polynomial ('SIP') distortion parameters are present in either the input or reference FITS header. In that case, the default degree is equal to the degree of the distortion polynomial. OPTIONAL OUTPUT KEYWORD: ERRMSG - If this keyword is supplied, then any error messages will be returned to the user in this parameter rather than depending on on the MESSAGE routine in IDL. If no errors are encountered then a null string is returned. NOTES: (1) The 3 parameter calling sequence is less demanding on virtual memory. (2) The astrometry in OLDHD will be precessed to match the equinox given in REFHD. (3) If an ST Guidestar image is used for the reference header, then the output header will be converted to standard astrometry. EXAMPLE: Suppose one has an image array, IM, and an associated FITS header H. One desires to warp the image array so that it is aligned with another image with a FITS header, HREF. Both headers contain astrometry info. Set pixel values to 0 where there is no overlap between the input and reference image, and use linear interpolation (default) IDL> hastrom, IM, H, HREF, MISSING = 0 PROCEDURES USED: ad2xy, check_FITS, extast, get_EQUINOX(), gsssextast, hprecess, putast, sxaddpar, sxaddhist, sxpar(), xy2ad, zparcheck REVISION HISTORY: Written W. Landsman, STX Co. Feb, 1989 Updated to CHECK_FITS Dec, 1991 New astrometry keywords Mar, 1994 Recognize GSSS header W. Landsman June, 1994 Added CUBIC keyword W. Landsman March, 1997 Accept INTERP=0, Convert output GSS header to standard astrometry W. Landsman June 1998 Remove calls to obsolete !ERR system variable March 2000 Added ERRMSG output keyword W. Landsman April 2000 Need to re-extract astrometry after precession W. Landsman Nov. 2000 Check for distortion parameters in headers, add more FITS HISTORY information W. Landsman February 2005 Use different coefficient for nearest neighbor to avoid half-pixel shift with POLY_2D W. Landsman Aug 2006 Return ERRMSG if no overlap between images W. Landsman Nov 2007 Use V6.0 notation W. Landsman Jan 2012(See astrolib/pro/hastrom.pro)
HBOXAVE
[Previous Routine] [Next Routine] [List of Routines]NAME: HBOXAVE PURPOSE: Box average an image array and update the FITS header array EXPLANATION: The function BOXAVE() is used. This procedure is recommended for integer images when photometric precision is desired, because it performs intermediate steps using REAL*4 arithmetic. Otherwise, the procedure HREBIN is much faster. CALLING SEQUENCE: HBOXAVE, Oldim, Oldhd, Newim, Hewhd, box or HBOXAVE, Oldim, Oldhd, box INPUTS: Oldim - the original image array Oldhd - the original image FITS header, string array OPTIONAL INPUTS: box - the box size to be used, integer scalar. If omitted, then HBOXAVE will prompt for this parameter. OPTIONAL OUTPUTS: Newim - the image after boxaveraging Newhd - header for newim containing updated astrometry info If output parameters are not supplied, the program will modify the input parameters OLDIM and OLDHD to contain the new array and updated header. OPTIONAL KEYWORD OUTPUT: ERRMSG - If this keyword is supplied, then any error mesasges will be returned to the user in this parameter rather than depending on on the MESSAGE routine in IDL. If no errors are encountered then a null string is returned. PROCEDURE: The parameters BSCALE, NAXIS1, NAXIS2, CRPIX1, and CRPIX2 and the CD (or CDELT) parameters are updated for the new FITS header. EXAMPLE: Compress the image in a FITS file 'image.fits' by a factor of 4 and update the astrometry in the FITS header IDL> im = readfits('image.fits',hdr) ;Read FITS file into IDL arrays IDL> hboxave, im, hdr, 4 ;Boxaverage by 4 IDL> writefits,'image.fits',im,hdr ;Write a new FITS file CALLED PROCEDURES: CHECK_FITS - Check that the FITS header is appropriate to the image BOXAVE() - Performs box averaging of an image SXPAR(), SXADDPAR - Read and write FITS keyword values MODIFICATION HISTORY: Written, Aug. 1986 W. Landsman, STI Corp. IDLV2 changes, sxaddpar format keyword added, J. Isensee, July,1990 Fix 0.5 pixel offset in new CRPIX computation W. Landsman, Dec, 1991 Update BSCALE even if no astrometry present W. Landsman, May 1997 Added ERRMSG keyword, Use double formatting W. Landsman April 2000 Recognize PC matrix astrometry format W. Landsman December 2001 Use V6.0 notation W. Landsman October 2012(See astrolib/pro/hboxave.pro)
HCONGRID
[Previous Routine] [Next Routine] [List of Routines]NAME: HCONGRID PURPOSE: CONGRID an image and update astrometry in a FITS header EXPLANATION: Expand or contract an image using CONGRID and update the associated FITS header array. CALLING SEQUENCE: HCONGRID, oldhd ;Update FITS header only HCONGRID, oldim, oldhd, [ newim, newhd, newx, newy, /HALF_HALF CUBIC = , INTERP=, OUTSIZE=, ERRMSG=, ALT= ] INPUTS: OLDIM - the original image array OLDHD - the original image FITS header, string array OPTIONAL INPUTS: NEWX - size of the new image in the X direction NEWY - size of the new image in the Y direction The OUTSIZE keyword can be used instead of the NEWX, NEWY parameters OPTIONAL OUTPUTS: NEWIM - the image after expansion or contraction with CONGRID NEWHD - header for newim containing updated astrometry info If output parameters are not supplied, the program will modify the input parameters OLDIM and OLDHD to contain the new array and updated header. OPTIONAL KEYWORD INPUTS: ALT - Single character 'A' through 'Z' or ' ' specifying which astrometry system to modify in the FITS header. The default is to use the primary astrometry of ALT = ' '. See Greisen and Calabretta (2002) for information about alternate astrometry keywords. CUBIC - If set and non-zero, then cubic interpolation is used. Valid ranges are -1 <= Cubic < 0. Setting /CUBIC is equivalent to CUBIC = -1 and also equivalent to INTERP = 2. See INTERPOLATE for more info. Setting CUBIC = -0.5 is recommended. ERRMSG - If this keyword is supplied, then any error mesasges will be returned to the user in this parameter rather than depending on on the MESSAGE routine in IDL. If no errors are encountered then a null string is returned. /HALF_HALF - Due to edge effects, the default behaviour of CONGRID is to introduce a slight shift in the image center. Craig Markwardt (http://cow.physics.wisc.edu/~craigm/idl/misc.html) has written a modified version of CONGRID called CMCONGRID that when used with the /HALF_HALF keyword eliminates any shift. The use of the /HALF keyword emulates CMCONGRID and eliminates any shift in the image centroid. INTERP - 0 for nearest neighbor, 1 for bilinear interpolation (default), 2 for cubic (=-1) interpolation. OUTSIZE - Two element integer vector which can be used instead of the NEWX and NEWY parameters to specify the output image dimensions OPTIONAL KEYWORD OUTPUT: ERRMSG - If this keyword is supplied, then any error mesasges will be returned to the user in this parameter rather than depending on on the MESSAGE routine in IDL. If no errors are encountered then a null string is returned. PROCEDURE: Expansion or contraction is done using the CONGRID function, unless HALF_HALF is set. The parameters BSCALE, NAXIS1, NAXIS2, CRPIX1, and CRPIX2 and the CD (or CDELT) parameters are updated for the new header. NOTES: A FITS header can be supplied as the first parameter without having to supply an image array. The astrometry in the FITS header will be updated to be appropriate to the specified image size. If the FITS header contains astrometry from a ST Guide Star image, then the astrometry will be converted to an approximately equivalent tangent projection before applying CONGRID. EXAMPLE: Congrid an 512 x 512 image array IM and FITS header H to size 300 x 300 using cubic interpolation. Use the HALF_HALF keyword to avoid a shift of the image centroid IDL> hcongrid, IM ,H, OUT = [300, 300], CUBIC = -0.5, /HALF The variables IM and H will be modified to the new image size. PROCEDURES CALLED: CHECK_FITS, CONGRID(), EXTAST, GSSS_STDAST, SXADDHIST, SXADDPAR, SXPAR(), ZPARCHECK MODIFICATION HISTORY: Written, Aug. 1986 W. Landsman, STI Corp. Added interp keywords, J. Isensee, July, 1990 Add cubic interpolation W. Landsman HSTX January 1994 Recognize a GSSS FITS header W. Landsman June 1994 Fix case where header but not image supplied W. Landsman May 1995 Remove call to SINCE_VERSION() W. Landsman March 1996 Assume since IDL V3.5, add CUBIC keyword W. Landsman March 1997 Update BSCALE even if no astrometry present W. Landsman May 1997 Converted to IDL V5.0 W. Landsman September 1997 Added HALF_HALF keyword W. Landsman February 2000 Added ERRMSG keyword, use double precision formatting W.L. April 2000 Recognize PC00n00m astrometry format W. Landsman December 2001 Now works when both /INTERP and /HALF are set W. Landsman January 2002 Fix output astrometry for non-equal plate scales for PC matrix or CROTA2 keyword, added ALT keyword. W. Landsman May 2005 Update distortion parameters if present W. Landsman January 2008 Don't update BSCALE/BZERO for unsigned integer W.Landsman Mar 2008 Write CRPIX as Double precision if necessary W. Landsman Oct 2012(See astrolib/pro/hcongrid.pro)
HEADFITS
[Previous Routine] [Next Routine] [List of Routines]NAME: HEADFITS PURPOSE: Read a FITS (primary or extension) header into a string array. EXPLANATION: HEADFITS() supports several types of compressed files including gzip (.gz), Unix compressed (.Z), Bzip2 (.bz2) or FPACK (.fz http://heasarc.gsfc.nasa.gov/fitsio/fpack/ ) CALLING SEQUENCE: Result = HEADFITS(Filename/Fileunit ,[ ERRMSG =, EXTEN= , COMPRESS=, /SILENT ]) INPUTS: Filename = String containing the name of the FITS file to be read. If set to an empty string, then user will be prompted for name. File names ending in '.gz' are assumed to be gzip'ed compressed and under Unix file names ending in '.Z' are assumed to be Unix compressed, and file names ending in .bz2 are assumed to be bzip2 compressed. If this default behaviour is not sufficient then use the COMPRESS keyword. or Fileunit - A scalar integer specifying the unit of an already opened FITS file. The unit will remain open after exiting HEADFITS(). There are two possible reasons for choosing to specify a unit number rather than a file name: (1) For a FITS file with many extensions, one can move to the desired extensions with FXPOSIT() and then use HEADFITS(). This is more efficient that repeatedly starting at the beginning of the file. (2) For reading a FITS file across a Web http: address after opening the unit with the SOCKET procedure. OPTIONAL INPUT KEYWORDS: EXTEN = Either an integer scalar, specifying which FITS extension to read, or a scalar string specifying the extension name (stored in the EXTNAME keyword). For example, to read the header of the first extension set EXTEN = 1. Default is to read the primary FITS header (EXTEN = 0). The EXTEN keyword cannot be used when a unit number is supplied instead of a file name. COMPRESS - If this keyword is set and non-zero, then treat the file as compressed. If 1 assume a gzipped file. Use IDL's internal decompression facilities for gzip files, while for Unix or bzip2 compression spawn off a process to decompress and use its output as the FITS stream. If the keyword is not 1, then use its value as a string giving the command needed for decompression. See FXPOSIT for more info. /SILENT - If set, then suppress any warning messages about invalid characters in the FITS file. OPTIONAL KEYWORD OUTPUT: ERRMSG = If this keyword is present, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. OUTPUTS: Result of function = FITS header, string array EXAMPLE: Print the main FITS header of a file 'test.fits' into a string variable, h IDL> print, headfits( 'test.fits') Print the second extension header of a gzip compressed FITS file 'test.fits.gz'. Use HPRINT for pretty format IDL> hprint, headfits( 'test.fits.gz', ext=2) Read the extension named CALSPEC IDL> hprint,headfits('test.fits.gz',ext='CALSPEC') PROCEDURES CALLED FXPOSIT(), MRD_HREAD The version of fxposit.pro must be post- May 2009. MODIFICATION HISTORY: adapted by Frank Varosi from READFITS by Jim Wofford, January, 24 1989 Keyword EXTEN added, K.Venkatakrishna, May 1992 Make sure first 8 characters are 'SIMPLE' W. Landsman October 1993 Check PCOUNT and GCOUNT W. Landsman December 1994 Major rewrite, work for Unix gzip files, W. Landsman April 1996 Added COMPRESS keyword W. Landsman April 2000 Added ERRMSG keyword W. Landsman July 2000 Added /SILENT keyword W. Landsman December 2000 Option to read a unit number rather than file name W.L October 2001 Test output status of MRD_HREAD call October 2003 W. Landsman Allow extension to be specified by name Dec 2006 W. Landsman No need to uncompress FPACK compressed files May 2009 W. Landsman Use V6.0 notation W.L. Feb. 2011(See astrolib/pro/headfits.pro)
HELIO
[Previous Routine] [Next Routine] [List of Routines]NAME: HELIO PURPOSE: Compute (low-precision) heliocentric coordinates for the planets. EXPLANATION: The mean orbital elements for epoch J2000 are used. These are derived from a 250 yr least squares fit of the DE 200 planetary ephemeris to a Keplerian orbit where each element is allowed to vary linearly with time. For dates between 1800 and 2050, this solution fits the terrestrial planet orbits to ~25" or better, but achieves only ~600" for Saturn. Use PLANET_COORDS (which calls HELIO) to get celestial (RA, Dec) coordinates of the planets CALLING SEQUENCE: HELIO, JD, LIST, HRAD, HLONG, HLAT, [/RADIAN] INPUTS: JD = Julian date, double precision scalar or vector LIST = List of planets array. May be a single number. 1 = merc, 2 = venus, ... 9 = pluto. OUTPUTS: HRAD = array of Heliocentric radii (A.U). HLONG = array of Heliocentric (ecliptic) longitudes (degrees). HLAT = array of Heliocentric latitudes (degrees). These output parameters will be dimensioned Nplanet by Ndate, where Nplanet is the number of elements of list, and Ndate is the number of elements of JD. OPTIONAL INPUT KEYWORD: /RADIAN - If set, then the output longitude and latitude are given in radians. EXAMPLE: (1) Find the current heliocentric positions of all the planets IDL> GET_JULDATE, jd ;Get current Julian date IDL> HELIO,jd,indgen(9)+1,hrad,hlong,hlat ;Get radius, long, and lat (2) Find heliocentric position of Mars on August 23, 2000 IDL> JDCNV, 2000,08,23,0,jd IDL> HELIO,JD,2,HRAD,HLONG,HLAT ===> hrad = 1.6407 AU hlong = 124.3197 hlat = 1.7853 For comparison, the JPL ephemeris gives hrad = 1.6407 AU hlong = 124.2985 hlat = 1.7845 (3) Find the heliocentric positions of Mars and Venus for every day in November 2000 IDL> JDCNV, 2000, 11, 1, 0, jd ;Julian date of November 1, 2000 IDL> helio, jd+indgen(30), [4,2], hrad,hlong,hlat ;Mars=4, Venus=2 hrad, hlong, and hlat will be dimensioned [2,30] first column contains Mars data, second column Venus COMMON BLOCKS: None ROUTINES USED: CIRRANGE - force angle between 0 and 2*!PI NOTES: (1) The calling sequence for this procedure was changed in August 2000 (2) This program is based on the two-body model and thus neglects interactions between the planets. This is why the worst results are for Saturn. Use the procedure JPLEPHINTERp for more accurate positions using the JPL ephemeris. Also see http://ssd.jpl.nasa.gov/cgi-bin/eph for a more accurate ephemeris generator online. (3) The coordinates are given for equinox 2000 and *not* the equinox of the supplied date(s) MODIFICATION HISTORY: R. Sterner. 20 Aug, 1986. Code cleaned up a bit W. Landsman December 1992 Major rewrite, use modern orbital elements, vectorize, more accurate solution to Kepler's equation W. Landsman August 2000 Wasn't working for planet vectors W. Landsman August 2000 Work for more than 32767 positions S. Leach Jan 2009(See astrolib/pro/helio.pro)
HELIO_JD
[Previous Routine] [Next Routine] [List of Routines]NAME: HELIO_JD PURPOSE: Convert geocentric (reduced) Julian date to heliocentric Julian date EXPLANATION: This procedure correct for the extra light travel time between the Earth and the Sun. An online calculator for this quantity is available at http://www.physics.sfasu.edu/astro/javascript/hjd.html Users requiring more precise calculations and documentation should look at the IDL code available at http://astroutils.astronomy.ohio-state.edu/time/ CALLING SEQUENCE: jdhelio = HELIO_JD( date, ra, dec, /B1950, /TIME_DIFF) INPUTS date - reduced Julian date (= JD - 2400000), scalar or vector, MUST be double precision ra,dec - scalars giving right ascension and declination in DEGREES Equinox is J2000 unless the /B1950 keyword is set OUTPUTS: jdhelio - heliocentric reduced Julian date. If /TIME_DIFF is set, then HELIO_JD() instead returns the time difference in seconds between the geocentric and heliocentric Julian date. OPTIONAL INPUT KEYWORDS /B1950 - if set, then input coordinates are assumed to be in equinox B1950 coordinates. /TIME_DIFF - if set, then HELIO_JD() returns the time difference (heliocentric JD - geocentric JD ) in seconds EXAMPLE: What is the heliocentric Julian date of an observation of V402 Cygni (J2000: RA = 20 9 7.8, Dec = 37 09 07) taken June 15, 1973 at 11:40 UT? IDL> juldate, [1973,6,15,11,40], jd ;Get geocentric Julian date IDL> hjd = helio_jd( jd, ten(20,9,7.8)*15., ten(37,9,7) ) ==> hjd = 41848.9881 Wayne Warren (Raytheon ITSS) has compared the results of HELIO_JD with the FORTRAN subroutines in the STARLINK SLALIB library (see http://star-www.rl.ac.uk/). Time Diff (sec) Date RA(2000) Dec(2000) STARLINK IDL 1999-10-29T00:00:00.0 21 08 25. -67 22 00. -59.0 -59.0 1999-10-29T00:00:00.0 02 56 33.4 +00 26 55. 474.1 474.1 1940-12-11T06:55:00.0 07 34 41.9 -00 30 42. 366.3 370.2 1992-02-29T03:15:56.2 12 56 27.4 +42 10 17. 350.8 350.9 2000-03-01T10:26:31.8 14 28 36.7 -20 42 11. 243.7 243.7 2100-02-26T09:18:24.2 08 26 51.7 +85 47 28. 104.0 108.8 PROCEDURES CALLED: bprecess, xyz, zparcheck REVISION HISTORY: Algorithm from the book Astronomical Photometry by Henden, p. 114 Written, W. Landsman STX June, 1989 Make J2000 default equinox, add B1950, /TIME_DIFF keywords, compute variation of the obliquity W. Landsman November 1999(See astrolib/pro/helio_jd.pro)
HELIO_RV
[Previous Routine] [Next Routine] [List of Routines]NAME: HELIO_RV PURPOSE: Return the heliocentric radial velocity of a spectroscopic binary EXPLANATION: This function will return the heliocentric radial velocity of a spectroscopic binary star at a given heliocentric date given its orbit. CALLING SEQUENCE: Result = HELIO_RV ( JD ,T ,Period ,Gamma , K, [,e ,Omega ] ) INPUT: JD - Time of observation T - Time of periastron passage (max. +ve velocity for circular orbits), same time system as JD Period - the period in same units as JD Gamma - systemic velocity K - velocity semi-amplitude in the same units as Gamma. e - eccentricity of the orbit, default is 0. Omega - longitude of periastron in degrees. Must be specified for eccentric orbits. OUTPUT: The predicted heliocentric radial velocity in the same units as Gamma for the date(s) specified by Reduced_HJD. RESTRICTIONS: The user should ensure consistency with all time systems being used (i.e. JD and T should be in the same units and time system). Generally, users should reduce large time values by subtracting a large constant offset, which may improve numerical accuracy. If using the the routines JULDATE and HELIO_JD, the reduced HJD time system must be used throughtout. EXAMPLES: Example 1 What was the heliocentric radial velocity of the primary component of HU Tau at 1730 UT 25 Oct 1994? IDL> juldate ,[94,10,25,17,30],JD ;Get Geocentric julian date IDL> hjd = helio_jd(jd,ten(04,38,16)*15.,ten(20,41,05)) ; Convert to HJD IDL> print, helio_rv(hjd,46487.5303D,2.0563056D,-6.0,59.3) -62.965569 NB. 1. The routines JULDATE and HELIO_JD return a reduced HJD (HJD - 2400000) and so T and P must be specified in the same fashion. 2. The user should be careful to use double precision format to specify T and P to sufficient precision where necessary. Example 2 Plot two cycles of an eccentric orbit, e=0.6, omega=45 for both components of a binary star IDL> phi=findgen(100)/50.0 ; Generates 100 phase points IDL> plot, phi,helio_rv(phi,0,1,0,100,0.6,45),yrange=[-100,150] IDL> oplot, phi,helio_rv(phi,0,1,0,50,0.6,45+180) This illustrates both the use of arrays to perform multiple calculations and generating radial velocities for a given phase by setting T=0 and P=1. Note also that omega has been changed by 180 degrees for the orbit of the second component (the same 'trick' can be used for circular orbits). MODIFICATION HISTORY: Written by: Pierre Maxted CUOBS, October, 1994 Circular orbits handled by setting e=0 and omega=0 to allow binary orbits to be handled using omega and omega+180. Pierre Maxted,Feb 95 BUG - omega was altered by the routine - corrected Feb 95,Pierre Maxted Iteration for E changed to that given by Reidel , Feb 95,Pierre Maxted /SINGLE keyword removed. May 96,Pierre Maxted ; Removed limitation of time system on HJD, C. Markwardt, 2011-04-15 Change convergence test from relative to absolute precision on E Pierre Maxted, Apr 12(See astrolib/pro/helio_rv.pro)
HERMITE
[Previous Routine] [Next Routine] [List of Routines]NAME: HERMITE PURPOSE: To compute Hermite spline interpolation of a tabulated function. EXPLANATION: Hermite interpolation computes the cubic polynomial that agrees with the tabulated function and its derivative at the two nearest tabulated points. It may be preferable to Lagrangian interpolation (QUADTERP) when either (1) the first derivatives are known, or (2) one desires continuity of the first derivative of the interpolated values. HERMITE() will numerically compute the necessary derivatives, if they are not supplied. CALLING SEQUENCE: F = HERMITE( XX, FF, X, [ FDERIV = ]) INPUT PARAMETERS: XX - Vector giving tabulated X values of function to be interpolated Must be either monotonic increasing or decreasing FF - Tabuluated values of function, same number of elements as X X - Scalar or vector giving the X values at which to interpolate OPTIONAL INPUT KEYWORD: FDERIV - function derivative values computed at XX. If not supplied, then HERMITE() will compute the derivatives numerically. The FDERIV keyword is useful either when (1) the derivative values are (somehow) known to better accuracy than can be computed numerically, or (2) when HERMITE() is called repeatedly with the same tabulated function, so that the derivatives need be computed only once. OUTPUT PARAMETER: F - Interpolated values of function, same number of points as X EXAMPLE: Interpolate the function 1/x at x = 0.45 using tabulated values with a spacing of 0.1 IDL> x = findgen(20)*0.1 + 0.1 IDL> y = 1/x IDL> print,hermite(x,y,0.45) This gives 2.2188 compared to the true value 1/0.45 = 2.2222 IDL> yprime = -1/x^2 ;But in this case we know the first derivatives IDL> print,hermite(x,y,0.45,fderiv = yprime) == 2.2219 ;and so can get a more accurate interpolation NOTES: The algorithm here is based on the FORTRAN code discussed by Hill, G. 1982, Publ Dom. Astrophys. Obs., 16, 67. The original FORTRAN source is U.S. Airforce. Surveys in Geophysics No 272. HERMITE() will return an error if one tries to interpolate any values outside of the range of the input table XX PROCEDURES CALLED: None REVISION HISTORY: Written, B. Dorman (GSFC) Oct 1993, revised April 1996 Added FDERIV keyword, W. Landsman (HSTX) April 1996 Test for out of range values W. Landsman (HSTX) May 1996 Converted to IDL V5.0 W. Landsman September 1997 Use VALUE_LOCATE instead of TABINV W. Landsman February 2001(See astrolib/pro/hermite.pro)
HEULER
[Previous Routine] [Next Routine] [List of Routines]NAME: HEULER PURPOSE: Change the coordinate system of a FITS header or astrometry structure EXPLANATION: Converts a FITS header or a astrometry structure containing WCS (world coordinate system) information between celestial, ecliptic, and Galactic coordinates CALLING SEQUENCE: HEULER, hdr, [/GALACTIC, /CELESTIAL, /ECLIPTIC, ALT_IN = , ALT_OUT=] or HEULER, astr, /GALACTIC, /CELESTIAL, /ECLIPTIC INPUT/OUTPUT PARAMETERS: hdr - FITS header (string array) containing WCS information or Astr - Astrometry structure as extracted from a FITS header by extast.pro (See EXTAST for more info). Header or astrometry structure will be modified by the program to contain astrometry in the new coordinates system. REQUIRED INPUT KEYWORDS: One of the following exclusive keywords is *required* /GALACTIC - Convert the header to Galactic coordinates /CELESTIAL - Convert the header to celestial (RA & Dec) coordinates /ECLIPTIC - Convert the header to ecliptic coordinates OPTIONAL INPUT KEYWORDS: The following two keywords apply if the FITS header contains multiple WCS keywords. See Section 3.3 of Greisen & Calabretta (2002, A&A, 395, 1061) for information about alternate astrometry keywords. ALT_IN - single character 'A' through 'Z' or ' ' specifying an alternate astrometry system present in the input FITS header. The default isto use the primary astrometry or ALT = ' '. If /ALT_IN is set, then this is equivalent to ALT_IN = 'A'. ALT_OUT - single character specifying the alternate WCS keywords to write the *output* astrometry. If not specified, then ALT_OUT is set equal to ALT_IN. RESTRICTIONS: Currently assumes that celestial and ecliptic coordinates are in J2000. Use HPRECESS if this is not the case. ST Guide Star (DSS) image headers are first converted to a standard tangent projection, prior to the coordinate conversion METHOD: The algorithm used is described in Section 2.7 of Calabretta & Greisen (2002, A&A, 395, 1077). The CRVAL coordinates are transformed directly using EULER. The new LONPOLE and LATPOLE values are then determined by transforming the pole of the new system to the old, and converted to native coordinates using WCS_ROTATE. EXAMPLE: A FITS header, hdr, has a standard tangent projection WCS information. Add an alternate 'G' Galactic projection. Note that the original WCS information will be left unchanged IDL> heuler, hdr, /Galactic, alt='G' PROCEDURES USED: EULER, EXTAST, GSSS_STDAST, PUTAST, SXADDHIST, WCS_ROTATE REVISION HISTORY: Written W. Landsman June 2003 Use PV2 tag in astrometry structure rather than PROJP1 W. L. May 2004 Use double precision to compute new North pole W.L. Aug 2005(See astrolib/pro/heuler.pro)
HEXTRACT
[Previous Routine] [Next Routine] [List of Routines]NAME: HEXTRACT PURPOSE: Extract a subimage from an array and update astrometry in FITS header EXPLANATION: Extract a subimage from an array and create a new FITS header with updated astrometry for the subarray CALLING SEQUENCE: HEXTRACT, Oldim, Oldhd, [ Newim, Newhd, x0, x1, y0, y1, /SILENT ] or HEXTRACT, Oldim, Oldhd, [x0, x1, y0, y1, /SILENT, ERRMSG = ] INPUTS: Oldim - the original image array Oldhd - the original image header OPTIONAL INPUTS: x0, x1, y0, y1 - respectively, first and last X pixel, and first and last Y pixel to be extracted from the original image, integer scalars. HEXTRACT will convert these values to long integers. If omitted, HEXTRACT will prompt for these parameters OPTIONAL OUTPUTS: Newim - the new subarray extracted from the original image Newhd - header for newim containing updated astrometry info If output parameters are not supplied or set equal to -1, then the HEXTRACT will modify the input parameters OLDIM and OLDHD to contain the subarray and updated header. OPTIONAL INPUT KEYWORD: ALT - Single character 'A' through 'Z' or ' ' specifying which astrometry system to modify in the FITS header. The default is to use the primary astrometry or ALT = ' '. See Greisen and Calabretta (2002) for information about alternate astrometry keywords. /SILENT - If set and non-zero, then a message describing the extraction is not printed at the terminal. This message can also be suppressed by setting !QUIET. OPTIONAL KEYWORD OUTPUT: ERRMSG - If this keyword is supplied, then any error mesasges will be returned to the user in this parameter rather than depending on on the MESSAGE routine in IDL. If no errors are encountered then a null string is returned. PROCEDURE: The FITS header parameters NAXIS1, NAXIS2, CRPIX1, and CRPIX2 are updated for the extracted image. EXAMPLE: Read an image from a FITS file 'IMAGE', extract a 512 x 512 subimage with the same origin, and write to a new FITS file 'IMAGENEW' IDL> im = READFITS( 'IMAGE', hdr ) ;Read FITS files into IDL arrays IDL> hextract, im, h, 0, 511, 0, 511 ;Extract 512 x 512 subimage IDL> writefits, 'IMAGENEW', im ,h ;Write subimage to a FITS file PROCEDURES CALLED CHECK_FITS, STRN(), SXPAR(), SXADDPAR, SXADDHIST MODIFICATION HISTORY: Written, Aug. 1986 W. Landsman, STX Corp. Use astrometry structure, W. Landsman Jan, 1994 Minor fix if bad Y range supplied W. Landsman Feb, 1996 Added /SILENT keyword W. Landsman March, 1997 Added ERRMSG keyword W. Landsman May 2000 Work for dimensions larger than 32767 W.L., M.Symeonidis Mar 2007 Added ALT keyword W.L. April 2007 Use V6.0 notation W.L. October 2012(See astrolib/pro/hextract.pro)
HGREP
[Previous Routine] [Next Routine] [List of Routines]NAME: HGREP PURPOSE: Find a substring in a FITS header (or any other string array) CALLING SEQUENCE: HGREP, header, substring, [/KEEPCASE, /LINENUM ] INPUTS: header - FITS header or other string array substring - scalar string to find in header; if a numeric value is supplied, it will be converted to type string OPTIONAL INPUT KEYWORDS: /KEEPCASE: if set, then look for an exact match of the input substring Default is to ignore case . /LINENUM: if set, prints line number of header in which substring appears OUTPUTS: None, results are printed to screen EXAMPLE: Find every place in a FITS header that the word 'aperture' appears in lower case letters and print the element number of the header array: IDL> hgrep, header, 'aperture', /keepcase, /linenum HISTORY: Written, Wayne Landsman (Raytheon ITSS) August 1998 Adapted from STIS version by Phil Plait/ ACC November 14, 1997 Remove trailing spaces if a non-string is supplied W. Landsman Jun 2002(See astrolib/pro/hgrep.pro)
HISTOGAUSS
[Previous Routine] [Next Routine] [List of Routines]NAME: HISTOGAUSS PURPOSE: Histograms data and overlays it with a Gaussian. Draws the mean, sigma, and number of points on the plot. CALLING SEQUENCE: HISTOGAUSS, Sample, A, [XX, YY, GX, GY, /NOPLOT, /NOFIT, FONT=, CHARSIZE = ] INPUT: SAMPLE = Vector to be histogrammed OUTPUT ARGUMENTS: A = coefficients of the Gaussian fit: Height, mean, sigma A[0]= the height of the Gaussian A[1]= the mean A[2]= the standard deviation A[3]= the half-width of the 95% conf. interval of the standard mean A[4]= 1/(N-1)*total( (y-mean)/sigma)^2 ) = a measure of normality Below: superceded. The formula is not entirely reliable. A[4]= measure of the normality of the distribution. =1.0, perfectly normal. If no more than a few hundred points are input, there are formulae for the 90 and 95% confidence intervals of this quantity: M=ALOG10(N-1) ; N = number of points T90=ABS(.6376-1.1535*M+.1266*M^2) ; = 90% confidence interval IF N LT 50 THEN T95=ABS(-1.9065-2.5465*M+.5652*M^2) $ ELSE T95=ABS( 0.7824-1.1021*M+.1021*M^2) ;95% conf. (From Martinez, J. and Iglewicz, I., 1981, Biometrika, 68, 331-333.) XX = the X coordinates of the histogram bins (CENTER) YY = the Y coordinates of the histogram bins GX = the X coordinates of the Gaussian fit GY = the Y coordinates of the Gaussian fit OPTIONAL INPUT KEYWORDS: /NOPLOT - If set, nothing is drawn /FITIT If set, a Gaussian is actually fitted to the distribution. By default, a Gaussian with the same mean and sigma is drawn; the height is the only free parameter. CHARSIZE Size of the characters in the annotation. Default = 0.82. FONT - scalar font graphics keyword (-1,0 or 1) for text /WINDOW - set to plot to a resizeable graphics window _EXTRA - Any value keywords to the cgPLOT command (e.g. XTITLE) may also be passed to HISTOGAUSS SUBROUTINE CALLS: BIWEIGHT_MEAN, which determines the mean and std. dev. AUTOHIST, which draws the histogram GAUSSFIT() (IDL Library) which does just that REVISION HISTORY: Written, H. Freudenreich, STX, 12/89 More quantities returned in A, 2/94, HF Added NOPLOT keyword and print if Gaussian, 3/94 Stopped printing confidence limits on normality 3/31/94 HF Added CHARSIZE keyword, changed annotation format, 8/94 HF Simplified calculation of Gaussian height, 5/95 HF Convert to V5.0, use T_CVF instead of STUDENT_T, GAUSSFIT instead of FITAGAUSS W. Landsman April 2002 Correct call to T_CVF for calculation of A[3], 95% confidence interval P. Broos/W. Landsman July 2003 Allow FONT keyword to be passed. T. Robishaw Apr. 2006 Use Coyote Graphics for plotting W.L. Mar 2011 Better formatting of text output W.L. May 2012(See astrolib/pro/histogauss.pro)
HOR2EQ
[Previous Routine] [Next Routine] [List of Routines]NAME: HOR2EQ PURPOSE: Converts local horizon coords (alt-az) of something to equatorial (ra-dec). EXPLANATION: This is a nice code to calculate equatorial (ra,dec) coordinates from horizon (alt,az) coords. It is typically accurate to about 1 arcsecond or better (I have checked the output against the publicly available XEPHEM software). It performs precession, nutation, aberration, and refraction corrections. The perhaps best thing about it is that it can take arrays as inputs, in all variables and keywords EXCEPT Lat, lon, and Altitude (the code assumes these aren't changing), and uses vector arithmetic in every calculation except when calculating the precession matrices. CALLING SEQUENCE: HOR2EQ, alt, az, jd, ra, dec, [ha, LAT= , LON= , /WS, OBSNAME= , $ /B1950 , PRECESS_= 0, NUTATE_= 0, REFRACT_= 0, $ ABERRATION_= 0, ALTITUDE= , /VERBOSE, _EXTRA= ] INPUT VARIABLES alt : altitude (in degrees) [scalar or vector] az : azimuth angle (in degrees, measured EAST from NORTH, but see keyword WS below.) [scalar or vector] JD : Julian Date [scalar or vector], double precision Note: if RA and DEC are arrays, then alt and az will also be arrays. If RA and DEC are arrays, JD may be a scalar OR an array of the same dimensionality. OPTIONAL INPUT KEYWORDS: lat : north geodetic latitude of location in degrees lon : EAST longitude of location in degrees (Specify west longitude with a negative sign.) /WS : Set this to get the azimuth measured westward from south (not East of North). obsname : Set this to a valid observatory name to be used by the astrolib OBSERVATORY procedure, which will return the latitude and longitude to be used by this program. /B1950 : Set this if your ra and dec are specified in B1950, FK4 coordinates (instead of J2000, FK5) precess_ : Set this to 1 to force precession [default], 0 for no precession. nutate_ : Set this to 1 to force nutation [default], 0 for no nutation. aberration_ : Set this to 1 to force aberration correction [default], 0 for no correction. refract_ : Set to 1 to force refraction correction [default], 0 for no correction. altitude: The altitude of the observing location, in meters. [default=0]. /verbose: Set this for verbose output. The default is verbose=0. _extra: This is for setting TEMPERATURE or PRESSURE explicitly, which are used by CO_REFRACT to calculate the refraction effect of the atmosphere. If you don't set these, the program will make an intelligent guess as to what they are (taking into account your altitude). See CO_REFRACT for more details. OUTPUT VARIABLES ra : Right Ascension of object (J2000) in degrees (FK5); scalar or vector. dec : Declination of object (J2000) in degrees (FK5), scalar or vector. ha : hour angle (in degrees) (optional) DEPENDENCIES: NUTATE, PRECESS, ADSTRING(), SUNPOS, OBSERVATORY (from the astrolib) CO_NUTATE, CO_ABERRATION, CO_REFRACT, HADEC2ALTAZ BASIC STEPS Precess Ra-Dec to current equinox. Nutation Correction to Ra-Dec Aberration correction to Ra-Dec Calculate Local Mean Sidereal Time Calculate Local Apparent Sidereal Time Calculate Hour Angle Do Spherical Trig to find Apparent Alt-Az Apply refraction correction to find observed Alt. CORRECTIONS I DO NOT MAKE: * Deflection of Light by the sun due to GR. (typically milliarcseconds, can be arcseconds within one degree of the sun) * The Effect of Annual Parallax (typically < 1 arcsecond) * and more (see below) TO DO * Better Refraction Correction. Need to put in wavelength dependence, and integrate through the atmosphere. * Topocentric Parallax Correction (will take into account elevation of the observatory) * Proper Motion (but this will require crazy lookup tables or something). * Difference between UTC and UT1 in determining LAST -- is this important? * Effect of Annual Parallax (is this the same as topocentric Parallax?) * Polar Motion * Better connection to Julian Date Calculator. EXAMPLE: You are at Kitt Peak National Observatory, looking at a star at azimuth angle 264d 55m 06s and elevation 37d 54m 41s (in the visible). Today is Dec 25, 2041 and the local time is 10 PM precisely. What is the ra and dec (J2000) of the star you're looking at? The temperature here is about 0 Celsius, and the pressure is 781 millibars. The Julian date for this time is 2466879.7083333 IDL> hor2eq, ten(37,54,41), ten(264,55,06), 2466879.7083333d, ra, dec, $ /verb, obs='kpno', pres=781.0, temp=273.0 The program produces this output (because the VERBOSE keyword was set): Latitude = +31 57 48.0 Longitude = *** 36 0.0 ; longitude prints weirdly b/c of negative input to ADSTRING!! Julian Date = 2466879.708333 Az, El = 17 39 40.4 +37 54 41.0 (Observer Coords) Az, El = 17 39 40.4 +37 53 39.6 (Apparent Coords) LMST = +03 53 54.1 LAST = +03 53 53.6 Hour Angle = +03 38 30.1 (hh:mm:ss) Ra, Dec: 00 15 23.5 +15 25 1.9 (Apparent Coords) Ra, Dec: 00 15 24.2 +15 25 0.1 (J2041.9841) Ra, Dec: 00 13 14.1 +15 11 0.3 (J2000) The star is therefore Algenib! Compare the derived Ra, Dec with what XEPHEM got: Ra, Dec: 00 13 14.2 +15 11 1.0 (J2000) AUTHOR: Chris O'Dell Univ. of Wisconsin-Madison Observational Cosmology Laboratory Email: odell@cmb.physics.wisc.edu REVISION HISTORY: Made all integers type LONG W. Landsman September 2007 Fixed for case of scalar Julian date but vector positions W L June 2009(See astrolib/pro/hor2eq.pro)
HOST_TO_IEEE
[Previous Routine] [Next Routine] [List of Routines]NAME: HOST_TO_IEEE PURPOSE: Translate an IDL variable from host to IEEE representation EXPLANATION: The variable is converted from the format used by the host architecture into IEEE-754 representation ("big endian" as used, e.g., in FITS data ). Duplicates most of the functionality of the SWAP_ENDIAN_INPLACE procedure with the addition of the IDLTYPE keyword. CALLING SEQUENCE: HOST_TO_IEEE, data, [ IDLTYPE = ] INPUT-OUTPUT PARAMETERS: data - any IDL variable, scalar or vector. It will be modified by HOST_TO_IEEE to convert from host to IEEE representation. Byte and string variables are returned by HOST_TO_IEEE unchanged OPTIONAL KEYWORD INPUTS: IDLTYPE - scalar integer (1-15) specifying the IDL datatype according to the code given by the SIZE function. This keyword will usually be used when supplying a byte array that needs to be interpreted as another data type (e.g. FLOAT). EXAMPLE: Suppose FITARR is a 2880 element byte array to be converted to a FITS record and interpreted a FLOAT data. IDL> host_to_ieee, FITARR, IDLTYPE = 4 METHOD: The BYTEORDER procedure is called with the appropriate keywords MODIFICATION HISTORY: Adapted from CONV_UNIX_VAX, W. Landsman Hughes/STX January, 1992 Version for IDL V5.0 August 1997 Converted to IDL V5.0 W. Landsman September 1997 Added new integer datatypes C. Markwardt/W. Landsman July 2000 Use /SWAP_IF_LITTLE_ENDIAN keyword for 64bit types W. Landsman Feb 2003 Do not use XDR keywords to BYTEORDER for much improved speed W. Landsman April 2006(See astrolib/pro/host_to_ieee.pro)
HPRECESS
[Previous Routine] [Next Routine] [List of Routines]NAME: HPRECESS PURPOSE: Precess the astrometry in a FITS header to a new equinox CALLING SEQUENCE: HPRECESS, HDR, [ yearf ] INPUT-OUTPUT: HDR - FITS Header, must contain the CRVAL astrometry keywords, and either an EPOCH or EQUINOX keyword. HDR will be modified to contain the precessed astrometry OPTIONAL INPUT: YEARF - Scalar, giving the year of the new (Final) equinox. If not supplied, user will be prompted for this value. METHOD: The CRVAL and CD (or CROTA) keywords are extracted from the header and precessed to the new equinox. The EPOCH or EQUINOX keyword in the header is updated. A HISTORY record is added RESTRICTIONS: The FK5 reference frame is assumed for both equinoxes. PROCEDURES USED: EXTAST, GET_EQUINOX(), SXADDPAR, SXADDHIST, PRECESS, PRECESS_CD PUTAST, ZPARCHECK REVISION HISTORY: Written W. Landsman STX July, 1988 CD matrix precessed - February, 1989 Update EQUINOX keyword when CROTA2 present November, 1992 Recognize a GSSS header June, 1994 Additional Noparams value recognize for storing CDs. RSH, 6 Apr 95 Understand reversed X,Y (X-Dec, Y-RA) axes, W. Landsman October 1998 Correct algorithm when CROTA2 is in header W. Landsman April 2006 Correct sign error introduced April 2006, include CDELT values when computing rotation of pole W. Landsman July 2007 Call hprecess/jprecess for 1950<>2000 W. L. Aug 2009(See astrolib/pro/hprecess.pro)
HPRINT
[Previous Routine] [Next Routine] [List of Routines]NAME: HPRINT PURPOSE: Display a FITS header (or other string array) EXPLANATION: On a GUI terminal, the string array is displayed using XDISPSTR. If printing at a non-GUI terminal, the string array is printed 1 line at a time, to make sure that each element of the string array is displayed on a separate line. CALLING SEQUENCE: HPRINT, h, [ firstline ] INPUTS: H - FITS header (or any other string array). OPTIONAL INPUT: FIRSTLINE - scalar integer specifying the first line to begin displaying. The default is FIRSTLINE = 1, i.e. display all the lines. If Firstline is negative, then the first line to be printed is counted backward from the last line. NOTES: When displaying at the terminal, HPRINT has the following differences from the intrinsic PRINT procedure (1) Arrays are printed one line at a time to avoid a space between 80 character lines (2) Lines are trimmed with STRTRIM before being printed to speed up display (3) The /more option is used for output. EXAMPLE: Read the header from a FITS file named 'test.fits' and display it at the terminal beginning with line 50 IDL> h = headfits( 'test.fits') ;Read FITS header IDL> hprint, h, 50 ;Display starting at line 50 To print the last 25 lines of the header IDL> hprint, h, -25 REVISION HISTORY: Written W. Landsman July, 1990 Added test for user quit July, 1991 Added optional FIRSTLINE parameter November, 1992 Modified for when STDOUT is not a TTY W. Landsman September 1995 Converted to IDL V5.0 W. Landsman September 1997 Fixed printing in IDLDE, C. Gehman August, 1998 Skip PRINTF if IDL in demo mode W. Landsman October 2004 Fixed bug on non-terminals, William Thompson, 18-Oct-2004 Assume since V5.4 Use BREAK instead of GOTO W. Landsman Apr 2006 Call XDISPSTR on a GUI terminal W. Landsman Jun 2006(See astrolib/pro/hprint.pro)
HREBIN
[Previous Routine] [Next Routine] [List of Routines]NAME: HREBIN PURPOSE: Expand or contract a FITS image using (F)REBIN and update the header EXPLANATION: If the output size is an exact multiple of the input size then REBIN is used, else FREBIN is used. User can either overwrite the input array, or write to new variables. CALLING SEQUENCE: HREBIN, oldhd ;Special calling sequence to just update header HREBIN, oldim, oldhd, [ newim, newhd, newx, newy, OUTSIZE = ,/SAMPLE, ERRMSG = ] INPUTS: OLDIM - the original image array OLDHD - the original image FITS header, string array OPTIONAL INPUTS: NEWX - size of the new image in the X direction, integer scalar NEWY - size of the new image in the Y direction, integer scalar HREBIN will prompt for NEWX and NEWY if not supplied OPTIONAL OUTPUTS: NEWIM - the image after expansion or contraction with REBIN NEWHD - header for newim containing updated astrometry info If output parameters are not supplied, the program will modify the input parameters OLDIM and OLDHD to contain the new array and updated header. OPTIONAL INPUT KEYWORDS: /SAMPLE - Expansion or contraction is done using REBIN which uses bilinear interpolation when magnifying and boxaveraging when minifying. If the SAMPLE keyword is supplied and non-zero, then nearest neighbor sampling is used in both cases. Keyword has no effect when output size is not a multiple of input size. OUTSIZE - Two element integer vector which can be used instead of the NEWX and NEWY parameters to specify the output image dimensions ALT - Single character 'A' through 'Z' or ' ' specifying which astrometry system to modify in the FITS header. The default is to use the primary astrometry of ALT = ' '. See Greisen and Calabretta (2002) for information about alternate astrometry keywords. OPTIONAL KEYWORD OUTPUT: ERRMSG - If this keyword is supplied, then any error mesasges will be returned to the user in this parameter rather than depending on on the MESSAGE routine in IDL. If no errors are encountered then a null string is returned. PROCEDURE: The parameters BSCALE, NAXIS1, NAXIS2, CRPIX1, and CRPIX2 and the CD (or CDELT) parameters are updated for the new FITS header. EXAMPLE: Compress a 2048 x 2048 image array IM, with FITS header HDR, to a 724 x 724 array. Overwrite the input variables with the compressed image and header. IDL> hrebin, im, hdr, OUT = [724, 724] PROCEDURES USED: CHECK_FITS, EXTAST, FREBIN, GSSS_STDAST, STRN(), SXPAR(), SXADDHIST, SXADDPAR, ZPARCHECK MODIFICATION HISTORY: Written, December 1990 W. Landsman, ST System Corp. Update CD1_1 keywords W. Landsman November 1992 Check for a GSSS header W. Landsman June 1994 Update BSCALE even if no astrometry present W. Landsman May 1997 Converted to IDL V5.0 W. Landsman September 1997 Use FREBIN to accept sizes that are not a integer multiple of the original size W. Landsman August 1998 Correct for "edge" effects when expanding with REBIN W. Landsman Apr. 1999 Fixed initialization of header only call broken in Apr 98 change May. 1999 Remove reference to obsolete !ERR W. Landsman February 2000 Use double precision formatting for CD matrix W. Landsman April 2000 Recognize PC00n00m astrometry format W. Landsman December 2001 Correct astrometry for integral contraction W. Landsman April 2002 Fix output astrometry for non-equal plate scales for PC matrix or CROTA2 keyword, added ALT keyword. W. Landsman May 2005 Update distortion parameters if present W. Landsman August 2007 Don't update BSCALE/BZERO for unsigned integer W.Landsman Mar 2008 Use post-V6.0 notation W. Landsman Nov 2011 Write CRPIX values as double precision if necessay W. Landsman Oct. 2012(See astrolib/pro/hrebin.pro)
HREVERSE
[Previous Routine] [Next Routine] [List of Routines]NAME: HREVERSE PURPOSE: Reverse an image about either dimension and update FITS astrometry EXPLANATION: Reverse an image about either the X or Y axis, and create a new header with updated astrometry for the reversed image. CALLING SEQUENCE: HREVERSE,oldim,oldhd, [ subs, /SILENT ] ;Update input image and header or HREVERSE, oldim, oldhd, newim, newhd, [ subs, /SILENT ] INPUTS: OLDIM - the original image array OLDHD - the original image header OPTIONAL INPUTS: SUBS - Subs equals 1 to reverse the order of the X dimension, 2 to reverse Y order. If omitted, then HREVERSE will prompt for this scalar parameter. OPTIONAL OUTPUTS: NEWIM - the rotated image, with the same dimensions as Oldim NEWHD - header for newim containing updated astrometry info If output parameters are not supplied, the program will modify the input parameters OLDIM and OLDHD to contain the rotated image and updated header. OPTIONAL KEYWORD INPUT: SILENT - if set and non-zero, then informative messages are suppressed. OPTIONAL KEYWORD OUTPUT: ERRMSG - If this keyword is supplied, then any error mesasges will be returned to the user in this parameter rather than depending on on the MESSAGE routine in IDL. If no errors are encountered then a null string is returned. SIDE EFFECTS: A right-handed coordinate system is converted into a left- handed one, and vice-versa. PROCEDURE: The User's Library procedure REVERSE is used to reverse the image. The CD and CRPIX header parameters are updated for the new header. For AIPS type astrometry, the CDELT parameters are also updated. A history record is also added to the header PROCEDURES USED: CHECK_FITS, EXTAST, REVERSE(), STRN(), SXADDPAR MODIFICATION HISTORY: Written, Aug. 1986 W. Landsman, STI Corp. Error modifying CROTA angles corrected 9-23-88 Added format keyword, J. Isensee, July, 1990 Work for ST Guide Star images, W. Landsman HSTX, May 1995 Compute CRPIX1 correctly for X reversal W. Landsman HSTX August 1995 Converted to IDL V5.0 W. Landsman September 1997 Added ERRMSG, Use double precision formatting, W. Landsman April 2000 Recognize PC00n00m astrometry matrix W. Landsman December 2001 Use V6.0 notation W. Landsman October 2012(See astrolib/pro/hreverse.pro)
HROT
[Previous Routine] [Next Routine] [List of Routines]NAME: HROT PURPOSE: Rotate an image and create new FITS header with updated astrometry. EXPLANATION: Cubic, bilinear or nearest neighbor interpolation can be used. CALLING SEQUENCE: HROT, oldim, oldhd, [ newim, newhd, angle, xc, yc, int, MISSING =, INTERP =, CUBIC = , /PIVOT] INPUTS: OLDIM - the original image array OLDHD - the original FITS image header, string array OPTIONAL INPUTS: NEWIM - If NEWIM is set to -1, then the old image and header will be updated ANGLE - Rotation angle, degrees clockwise, scalar XC - X Center of rotation (-1 for center of image) YC - Y Center of rotation (-1 for center of image) INT - 0 for nearest neighbor, 1 for bilinear interpolation 2 for cubic interpolation. OPTIONAL OUTPUTS: NEWIM - the rotated image, with the same dimensions as Oldim NEWHD - header for newim containing updated astrometry info If output parameters are not supplied, the program will modify the input parameters OLDIM and OLDHD to contain the rotated image and updated header. OPTIONAL INPUT KEYWORD: MISSING - Set this keyword to a scalar value which will be assigned to pixels in the output image which do not correspond to existing input images (e.g if one rotates off-center). If not supplied then linear extrapolation is used. ***NOTE: A bug was introduced into the POLY_2D function in IDL V5.5 (fixed in V6.1) such that the MISSING keyword may not work properly with floating point data*** INTERP - scalar set to either 0 (nearest neighbor interpolation), 1 (bilinear interpolation), or 2 (cubic interpolation). The interpolation type can be specified by either the INTERP keyword or the int parameter CUBIC - If set and non-zero then cubic interpolation is used (see ROT), which is equivalent to setting INT = 2. In IDL V5.0 and later, this keyword can also be set to a value between -1 and 0. /PIVOT - Setting this keyword causes the image to pivot around the point XC, YC, so that this point maps into the same point in the output image. If this keyword is set to 0 or omitted, then the point XC, YC in the input image is mapped into the center of the output image. OPTIONAL OUTPUT KEYWORD: ERRMSG - If this keyword is supplied, then any error mesasges will be returned to the user in this parameter rather than depending on on the MESSAGE routine in IDL. If no errors are encountered then a null string is returned. EXAMPLE: Rotate an image non-interactively 30 degrees clockwise. Use bilinear interpolation, and set missing values to 0. IDL> HROT, im_old, h_old, im_new, h_new, 30, -1, -1, 1, MIS = 0 As above but update the input image and header and pivot about (100,120) IDL> HROT, im_old, h_old, -1, -1, 30, 100, 120, 1, MIS = 0, /PIVOT RESTRICTIONS: Unlike the ROT procedure, HROT cannot be used to magnify or or demagnify an image. Use HCONGRID or HREBIN instead. PROCEDURE: The image array is rotated using the ROT procedure. The CD (or CROTA) and CRPIX parameters, if present in the FITS header, are updated for the new rotation. History records are also added to the header PROCEDURES USED: CHECK_FITS, EXTAST, GETOPT(), GETROT, ROT(), STRN(), SXADDPAR MODIFICATION HISTORY: Written, Aug. 1986 W. Landsman, ST Systems Corp. Added MISSING keyword, W. Landsman March, 1991 Added cubic interpolation, use astrometry structure Feb 1994 Removed call to SINCE_VERSION() W. Landsman March 1996 Assume at least V3.5, add CUBIC parameter W. Landsman March 1997 Converted to IDL V5.0 W. Landsman September 1997 Fix for CROTA2 defined and CDELT1 NE CDELT2, W. Landsman November 1998 Fix documentation to specify clockwise rotation W. Landsman Dec. 1999 Added /PIVOT keyword W. Landsman January 2000 Added ERRMSG, Use double precision formatting, W. Landsman April 2000 Consistent conversion between CROTA and CD matrix W. Landsman Oct 2000 Work for both CD001001 and CDELT defined W. Landsman March 2001 Recognize PC matrix astrometry W. Landsman December 2001 Update astrometry correctly when /PIVOT applied W. Landsman March 2002 Update CROTA2 astrometry correctly, approximate GSSS W.L. June 2003 Work with CD1_1, PC1_1 and CROTA keywords W. L. July 2003 Work with angle as a 1 element vector W.L. May 2006(See astrolib/pro/hrot.pro)
HROTATE
[Previous Routine] [Next Routine] [List of Routines]NAME: HROTATE PURPOSE: Apply the IDL ROTATE function and update astrometry in a FITS header EXPLANATION: Apply the intrinsic IDL ROTATE function to an image and update astrometry in the associated FITS header. CALLING SEQUENCE: HROTATE, oldim, oldhd, newim, newhd, direction or HROTATE, oldim, oldhd, direction INPUTS: OLDIM - the original image array OLDHD - the original FITS image header, string array DIRECTION - Scalar integer (0-7) specifying rotation direction, exactly as specified by the IDL ROTATE function. Direction Transpose? Rot. CCW X1 Y1 ---------------------------------------- 0 No None X0 Y0 (no change) 1 No 90 -Y0 X0 2 No 180 -X0 -Y0 3 No 270 Y0 -X0 4 Yes None Y0 X0 5 Yes 90 -X0 Y0 6 Yes 180 -Y0 -X0 7 Yes 270 X0 -Y0 OPTIONAL OUTPUTS: NEWIM - the rotated image, with the same dimensions as Oldim NEWHD - header for newim containing updated astrometry info If output parameters are not supplied, the program will modify the input parameters OLDIM and OLDHD to contain the rotated image and updated header. OPTIONAL KEYWORD OUTPUT: ERRMSG - If this keyword is supplied, then any error mesasges will be returned to the user in this parameter rather than depending on on the MESSAGE routine in IDL. If no errors are encountered then a null string is returned. EXAMPLE: Rotate an image exactly 90 degrees counterclockwise and update the FITS image array and header. IDL> HROT, im, h, im_new, h_new, 1 PROCEDURE: The image array is rotated using the ROTATE function. The CD (or CROTA) and CRPIX parameters, if present in the FITS header, are updated for the new rotation. History records are also added to the header RESTRICTIONS: Does not work Guide Star Survey (GSS) astrometry. Use GSSS_STDAST to first convert PROCEDURES USED: CHECK_FITS(), SXADDPAR, EXTAST MODIFICATION HISTORY: Written, Mar 1997 W. Landsman, Hughes STX Work for non-square images W. Landsman June 1998 Raytheon STX Fix for different plate scales, and CROTA2 defined, November 1998 Added ERRMSG, Use double precision formatting, W. Landsman April 2000 Consistent conversion between CROTA and CD matrix W. Landsman Oct 2000 Correct update when CROTA keyword present W. Landsman June 2003 Update CDELT for AIPS-style astrometry headers M. Perrin/WL Jul 2003 Convert GSS astrometry to WCS W. Landsman November 2004 Work even if no astrometry present, just update NAXIS* WL June 2011(See astrolib/pro/hrotate.pro)
IEEE_TO_HOST
[Previous Routine] [Next Routine] [List of Routines]NAME: IEEE_TO_HOST PURPOSE: Translate an IDL variable from IEEE-754 to host representation EXPLANATION: The variable is translated from IEEE-754 ("big-endian" as used, for example, in FITS data ), into the host machine architecture. Duplicates most of the functionality of the SWAP_ENDIAN_INPLACE procedure introduced in V5.6, with the addition of the IDLTYPE keyword. CALLING SEQUENCE: IEEE_TO_HOST, data, [ IDLTYPE = , ] INPUT-OUTPUT PARAMETERS: data - any IDL variable, scalar or vector. It will be modified by IEEE_TO_HOST to convert from IEEE to host representation. Byte and string variables are returned by IEEE_TO_HOST unchanged OPTIONAL KEYWORD INPUTS: IDLTYPE - scalar integer (1-15) specifying the IDL datatype according to the code given by the SIZE function. This keyword is usually when DATA is a byte array to be interpreted as another datatype (e.g. FLOAT). EXAMPLE: A 2880 byte array (named FITARR) from a FITS record is to be interpreted as floating and converted to the host representaton: IDL> IEEE_TO_HOST, fitarr, IDLTYPE = 4 METHOD: The BYTEORDER procedure is called with the appropriate keyword MODIFICATION HISTORY: Written, W. Landsman Hughes/STX May, 1992 Converted to IDL V5.0 W. Landsman September 1997 Under VMS check for IEEE -0.0 values January 1998 VMS now handle -0.0 values under IDL V5.1 July 1998 Added new integer datatypes C. Markwardt/W. Landsman July 2000 Post-V5.1 version, no VMS negative zero check W. Landsman July 2001 Use size(/type) W. Landsman December 2002 Use /SWAP_IF_LITTLE_ENDIAN keyword for 64bit types W. Landsman Feb 2003 Do not use XDR keywords to BYTEORDER for much improved speed W. Landsman April 2006 Update cosmetic typo for structures W. Landsman October 2006(See astrolib/pro/ieee_to_host.pro)
IMCONTOUR
[Previous Routine] [Next Routine] [List of Routines]NAME: IMCONTOUR PURPOSE: Make a contour plot labeled with astronomical coordinates. EXPLANATION: The type of coordinate display is controlled by the keyword TYPE Set TYPE=0 (default) to measure distances from the center of the image (IMCONTOUR will decide whether the plotting units will be in arc seconds, arc minutes, or degrees depending on image size.) Set /TYPE for standard RA and Dec labeling By using the /NODATA keyword, IMCONTOUR can also be used to simply provide astronomical labeling of a previously displayed image. CALLING SEQUENCE IMCONTOUR, im, hdr,[ /TYPE, /PUTINFO, XDELTA = , YDELTA =, _EXTRA = XMID=, YMID= ] INPUTS: IM - 2-dimensional image array HDR - FITS header associated with IM, string array, must include astrometry keywords. IMCONTOUR will also look for the OBJECT and IMAGE keywords, and print these if found and the PUTINFO keyword is set. OPTIONAL PLOTTING KEYWORDS: /TYPE - the type of astronomical labeling to be displayed. Either set TYPE = 0 (default), distance to center of the image is marked in units of Arc seconds, arc minutes, or degrees TYPE = 1 astronomical labeling with Right ascension and declination. /PUTINFO - If set, then IMCONTOUR will add information about the image to the right of the contour plot. Information includes image name, object, image center, image center, contour levels, and date plot was made XDELTA, YDELTA - Integer scalars giving spacing of labels for TYPE=1. Default is to label every major tick (XDELTA=1) but if crowding occurs, then the user might wish to label every other tick (XDELTA=2) or every third tick (XDELTA=3) XMID, YMID - Scalars giving the X,Y position from which offset distances will be measured when TYPE=0. By default, offset distances are measured from the center of the image. /OVERLAY - If set, then IMCONTOUR is assumed to overlay an image. This requires 1 extra pixel be included on the X and Y axis, to account for edge effects in the image display. Setting OVERLAY provide a better match of the contour and underlying image but is not as aesthetically pleasing because the contours will not extend to the axes. Any keyword accepted by CONTOUR may also be passed through IMCONTOUR since IMCONTOUR uses the _EXTRA facility. IMCONTOUR uses its own defaults for the XTITLE, YTITLE XMINOR, YMINOR, and SUBTITLE keywords but these may be overridden. Note in particular the /NODATA keyword which can be used if imcontour.pro is to only provide labeling. NOTES: (1) The contour plot will have the same dimensional ratio as the input image array (2) To contour a subimage, use HEXTRACT before calling IMCONTOUR (3) Use the /NODATA keyword to simply provide astronomical labeling of a previously displayed image. (4) The IMCONTOUR display currently does not indicate the image rotation in any way, but only specifies coordinates along the edges of the image EXAMPLE: Overlay the contour of an image, im2, with FITS header, h2, on top of the display of a different image, im1. Use RA, Dec labeling, and seven equally spaced contour levels. The use of a program like David Fanning's cgImage http://www.idlcoyote.com/programs/cgimage.pro is suggested to properly overlay plotting and image coordinates. The /Keep_aspect_ratio keyword must be used. IDL> cgimage,im1,/keep_aspect, position = pos IDL> imcontour,im2,h2,nlevels=7,/Noerase,/TYPE,position = pos PROCEDURES USED: CHECK_FITS, EXTAST, GETROT, TICPOS, TICLABEL, TIC_ONE, TICS, XYAD CONS_RA(), CONS_DEC(), ADSTRING() REVISION HISTORY: Written W. Landsman STX May, 1989 Fixed RA,Dec labeling W. Landsman November, 1991 Fix plotting keywords W.Landsman July, 1992 Recognize GSSS headers W. Landsman July, 1994 Removed Channel keyword for V4.0 compatibility June, 1995 Add _EXTRA CONTOUR plotting keywords W. Landsman August, 1995 Add XDELTA, YDELTA keywords W. Landsman November, 1995 Use SYSTIME() instead of !STIME August, 1997 Remove obsolete !ERR system variable W. Landsman May 2000 Added XMID, YMID keywords to specify central position (default is still center of image) W. Landsman March 2002 Recognize Galactic coordinates, fix Levels display when /PUTINFO set W. Landsman May 2003 Correct conversion from seconds of RA to arcmin is 4 not 15. M. Perrin July 2003 Fix integer truncation which appears with tiny images WL July 2004 Changed some keyword_set() to N_elements WL Sep 2006 Work to 1 pixels level when overlaying an image,added /OVERLAY keyword Use FORMAT_AXIS_VALUES() W. Landsman Jan 2008 Make /OVERLAY always optional W. Landsman Feb 2008 Check if RA crosses 0 hours WL Aug 2008 Use Coyote Graphics WL Feb 2011(See astrolib/pro/imcontour.pro)
IMDBASE
[Previous Routine] [Next Routine] [List of Routines]NAME: IMDBASE PURPOSE: Find the sources in an IDL database that are located on a given image. CALLING SEQUENCE: imdbase, hdr, [catalogue, list, ALT=, XPOS= ,YPOS=, XRANGE= ,YRANGE= , SUBLIST =, /SILENT ] INPUTS: hdr - FITS image header containing astrometry, and the NAXIS1, NAXIS2 keywords giving the image size catalogue - string giving name of catalogue in database. If not supplied then the currently open database is used. The database must contain the (preferably indexed) fields RA (in hours) and DEC. Type DBHELP for a list of the names of available catalogues. OPTIONAL OUTPUT PARAMETER: LIST - A longwprd vector containing the entry numbers of sources found within the image. This vector can then be used with other database procedures, e.g. to print specified fields (DBPRINT) or subselect with further criteria (DBFIND) OPTIONAL OUTPUT KEYWORD PARAMETER: XPOS - REAL*4 vector giving X positions of catalogue sources found within the image YPOS - REAL*4 vector giving Y positions of catalogue sources found within the image OPTIONAL INPUT KEYWORD PARAMETERS ALT - single character 'A' through 'Z' or ' ' specifying an alternate astrometry system present in the FITS header. The default is to use the primary astrometry or ALT = ' '. If /ALT is set, then this is equivalent to ALT = 'A'. See Section 3.3 of Greisen & Calabretta (2002, A&A, 395, 1061) for information about alternate astrometry keywords. SILENT - If set, then informational messages are suppressed SUBLIST - vector giving entries in the database to consider in the search. If not supplied, or set equal to -1, then all entries are considered. XRANGE - 2 element vector giving the X range of the image to consider. The default is to search for catalogue sources within the entire image YRANGE - 2 element vector giving the Y range of the image to consider. NOTES: If an output list vector is not supplied, then the found objects are diplayed at the terminal. EXAMPLE: Find all existing IUE observations within the field of the FITS file fuv0435fc.fits. Subselect those taken with the SWP camera H = HEADFITS('fuv0435f.fits') ;Read FITS header IMDBASE,H,'IUE',list ;Find IUE obs. within image list2 = DBFIND('CAM_NO=3',list) ;Subselect on SWP images SIDE EFFECTS: The IDL database is left open upon exiting IMDBASE. NOTES: IMDBASE checks the description of the RA item in the database for the string '1950'. If found, the database RA and Dec are assumed to be in equinox B1950. Otherwise they are assumed to be in ICRS or J2000. SYSTEM VARIABLES: The non-standard system variable !TEXTOUT is required for use with the database procedures. PROCEDURES USED: AD2XY, DBEXT, DB_ITEM, DB_ITEM_INFO(), DBOPEN, DBFIND(), EXTAST, GET_EQUINOX(), GSSSADXY, GSSSXYAD, HPRECESS, SXPAR(), XY2AD REVISION HISTORY: Written W. Landsman September, 1988 Added SUBLIST keyword September, 1991 Updated to use ASTROMETRY structures J.D. Offenberg, HSTX, Jan 1993 Conversion for precession fixed. R.Hill, HSTX, 22-Apr-93 Check RA description for equinox W. Landsman Aug 96 Call HPRECESS if header equinox does not match DB W. Landsman Oct. 1998 Assume Equinox J2000 if not explicitly B1950 W. Landsman Jan. 2005 Added ALT keyword W. Landsman April 2005 Use open database, if no catalogue name given W.L April 2008 Added /SILENT keyword W.L. Mar 2009(See astrolib/pro/imdbase.pro)
IMF
[Previous Routine] [Next Routine] [List of Routines]NAME: IMF PURPOSE: Compute an N-component power-law logarithmic initial mass function EXPLANTION: The function is normalized so that the total mass distribution equals one solar mass. CALLING SEQUENCE: psi = IMF( mass, expon, mass_range ) INPUTS: mass - mass in units of solar masses (scalar or vector) Converted to floating point if necessary expon - power law exponent, usually negative, scalar or vector The number of values in expon equals the number of different power-law components in the IMF A Saltpeter IMF has a scalar value of expon = -1.35 mass_range - vector containing the mass upper and lower limits of the IMF and masses where the IMF exponent changes. The number of values in mass_range should be one more than in expon. The values in mass_range should be monotonically increasing. OUTPUTS psi - mass function, number of stars per unit logarithmic mass interval evaluated for supplied masses NOTES: The mass spectrum f(m) giving the number of stars per unit mass interval is related to psi(m) by m*f(m) = psi(m). The normalization condition is that the integral of psi(m) between the upper and lower mass limit is unity. EXAMPLE: (1) Print the number of stars per unit mass interval at 3 Msun for a Salpeter (expon = -1.35) IMF, with a mass range from 0.1 MSun to 110 Msun. IDL> print, imf(3, -1.35, [0.1, 110] ) / 3 (2) Lequex et al. (1981, A & A 103, 305) describes an IMF with an exponent of -0.6 between 0.007 Msun and 1.8 Msun, and an exponent of -1.7 between 1.8 Msun and 110 Msun. Plot the mass spectrum f(m) IDL> m = [0.01,0.1,indgen(110) + 1 ] ;Make a mass vector IDL> expon = [-0.6, -1.7] ;Exponent Vector IDL> mass_range = [ 0.007, 1.8, 110] ;Mass range IDL> plot,/xlog,/ylog, m, imf(m, expon, mass_range ) / m METHOD IMF first calculates the constants to multiply the power-law components such that the IMF is continuous at the intermediate masses, and that the total mass integral is one solar mass. The IMF is then calculated for the supplied masses. Also see Scalo (1986, Fund. of Cosmic Physics, 11, 1) PROCEDURES CALLED: None REVISION HISTORY: Written W. Landsman August, 1989 Set masses LE mass_u rather than LT mass_u August, 1992 Major rewrite to accept arbitrary power-law components April 1993 Convert EXPON to float if necessary W. Landsman March 1996 Remove call to DATATYPE, V5.3 version W. Landsman August 2000(See astrolib/pro/imf.pro)
IMLIST
[Previous Routine] [Next Routine] [List of Routines]NAME: IMLIST PURPOSE: Display pixel values on an image surrounding a specified X,Y center. EXPLANATION: IMLIST is similar to TVLIST but the center pixel is supplied directly by the user, rather than being read off of the image display CALLING SEQUENCE: IMLIST, Image, Xc, Yc, [ TEXTOUT = , DX = , DY = ,WIDTH = ,DESCRIP = ] INPUTS: Image - Two-dimensional array containing the image Xc - X pixel value at which to center the display, integer scalar Yc - Y pixel value at which to center the display, integer scalar OPTIONAL INPUTS KEYWORDS: TEXTOUT - Scalar number (1-7) or string which determines output device. (see TEXTOPEN) The following dev/file is opened for output. textout=1 TERMINAL using /more option textout=2 TERMINAL without /more option textout=3.prt textout=4 laser.tmp textout=5 user must open file textout=7 same as 3 but text is appended to .prt if file already exists textout = filename (default extension of .prt) DX -Integer scalar giving the number of pixels inthe X direction to be displayed. If omitted then DX = 18 for byte images, and DX = 14 for integer images. IMLIST will display REAL data with more significant figures if more room is available to print. DY - Same as DX, but in Y direction. If omitted, then DY = DX WIDTH - Integer scalar giving the character width of the output device. Default is 80 characters. DESCRIP = Scalar string which will be written as a description over the output pixel values. If DESCRIP is not supplied, and the output device specified by TEXTOUT is not a terminal, then the user will be prompted for a description. OFFSET - 2 element numeric vector giving an offset to apply to the display of the X,Y coordinates of the image (e.g. if the supplied image array is a subarray of a larger image). OUTPUTS: None. PROCEDURE: Corresponding region of image is then displayed at the terminal. If necessary, IMLIST will divide all pixel values in a REAL*4 image by a (displayed) factor of 10 to make a pretty format. SYSTEM VARIABLES: If the keyword TEXTOUT is not supplied, then the non-standard system variable !TEXTOUT will be read. (The procedure ASTROLIB can be used to add the non-standard system variables.) RESTRICTIONS: IMLIST may not be able to correctly format all pixel values if the dynamic range of the values near the center pixel is very large EXAMPLE: Display the pixel values of an image array IM in the vicinity of 254,111 IDL> imlist, IM, 254, 111 PROCEDURES USED TEXTOPEN, F_FORMAT(), TEXTCLOSE REVISION HISTORY: Written, W. Landsman June, 1991 Added DESCRIP keyword W. Landsman December, 1991 Treat LONG image as integer when possible, call TEXTOPEN with /STDOUT keyword, W. Landsman April, 1996 Use SYSTIME() instead of !STIME August 1997 Converted to IDL V5.0 W. Landsman September 1997 Recognize new integer types, added OFFSET keyword W. Landsman Jan. 2000 Replace DATATYPE() with size(/TNAME) W. Landsman Nov. 2001 Handle NAN values in output display W. Landsman June 2004 Use V6.0 notation W. Landsman April 2011 (See astrolib/pro/imlist.pro)
IRAFDIR
[Previous Routine] [Next Routine] [List of Routines]NAME: IRAFDIR PURPOSE: Provide a brief description of the IRAF images on a directory CALLING SEQUENCE: IRAFDIR, [ directory, TEXTOUT = ] OPTIONAL INPUT PARAMETERS: DIRECTORY - Scalar string giving file name, disk or directory to be searched OPTIONAL INPUT KEYWORD: TEXTOUT - specifies output device (see TEXTOPEN) textout=1 TERMINAL using /more option textout=2 TERMINAL without /more option textout=3.prt textout=4 laser.tmp textout=5 user must open file textout=7 Append to existing .prt file textout = 'filename' (default extension of .prt) OUTPUT PARAMETERS: None PROCEDURE: FINDFILE is used to find all '.imh' files in the directory. The object name and image size (NAXIS1, NAXIS2) are extracted from the header. Each header is also searched for the parameters DATE-OBS (or TDATEOBS), TELESCOP (or OBSERVAT), EXPTIME. RESTRICTIONS: (1) Some fields may be truncated since IRAFDIR uses a fixed format output (2) No more than 2 dimension sizes are displayed SYSTEM VARIABLES: If 'textout' keyword is not specified to select an output device, !TEXTOUT will be the default. This non-standard system variable can be added using the procedure ASTROLIB. PROCEDURE CALLS: EXPAND_TILDE(), FDECOMP, REMCHAR, TEXTOPEN, TEXTCLOSE MODIFICATION HISTORY: Written, K. Venkatakrishna, ST Systems Corp, August 1991 Work for IRAF V2.11 format W. Landsman November 1997 Assume since V5.5 use file_search W. Landsman Sep 2006 (See astrolib/pro/irafdir.pro)
IRAFRD
[Previous Routine] [Next Routine] [List of Routines]NAME: IRAFRD PURPOSE: Read an IRAF (.imh) file into IDL image and header arrays. EXPLANATION: The internal IRAF format changed somewhat in IRAF V2.11 to a machine independent format, with longer filename allocations. This version of IRAFRD should be able to read either format. CALLING SEQUENCE: IRAFRD, im, hdr, filename, [/SILENT ] OPTIONAL INPUT: FILENAME - Character string giving the name of the IRAF image header. If omitted, then program will prompt for the file name. IRAFRD always assumes the header file has an extension '.imh'. IRAFRD will automatically locate the ".pix" file containing the data by parsing the contents of the .imh file. (If the parse is unsuccesful, then IRAFRD looks in the same directory as the .imh file.) OUTPUTS: IM - array containing image data HDR - string array containing header. Basic information in the IRAF header is converted to a FITS style header OPTIONAL INPUT KEYWORDS: /SILENT - If this keyword is set and non-zero, then messages displayed while reading the image will be suppressed. RESTRICTIONS: (1) Image size and history sections of the IRAF header are copied into the FITS header HDR. Other information (e.g. astrometry) might not be included unless it is also in the history section (2) IRAFRD ignores the node name when deciphering the name of the IRAF ".pix" file. (3) Certain FITS keywords ( DATATYPE, IRAFNAME) may appear more than once in the output name (4) Does not read the DATE keyword for the new (V2.11) IRAF files NOTES: IRAFRD obtains dimensions and type of image from the IRAF header. PROCEDURES CALLED: FDECOMP, SXADDPAR, SXPAR() MODIFICATION HISTORY: Written W. Landsman, STX January 1989 Converted to IDL Version 2. M. Greason, STX, June 1990 Updated for DecStation compatibility W. Landsman March 1992 Don't leave an open LUN W. Landsman July 1993 Don't overwrite existing OBS-DATE W. Landsman October 1994 Don't bomb on very long FITS headers W. Landsman April 1995 Work on Alpha/OSF and Linux W. Landsman Dec 1995 Remove /VMSIMG keyword, improve efficiency when physical and image dimensions differ W. Landsman April 1996 Don't use FINDFILE (too slow) W. Landsman Oct 1996 Read V2.11 files, remove some parameter checks W. Landsman Nov. 1997 Fixed problem reading V2.11 files with long headers Jan. 1998 Accept names with multiple extensions W. Landsman April 98 Test for big endian machine under V2.11 format W. Landsman Feb. 1999 Don't read past the end of file for V5.4 compatilibity W.L. Jan. 2001 Convert to square brackets W.L May 2001 Assume since V5.4, remove SPEC_DIR() W. L. April 2006(See astrolib/pro/irafrd.pro)
IRAFWRT
[Previous Routine] [Next Routine] [List of Routines]NAME: IRAFWRT PURPOSE: Write IDL data in IRAF (OIF) format (.imh and .pix files). EXPLANATION: Does the reverse of IRAFRD. IRAFWRT writes the "old" IRAF format used prior to v2.11. However, this "old" format is still readable by the current version of IRAF. CALLING SEQUENCE: IRAFWRT, image, hdr, filename, [ PIXDIR = ] INPUTS: image - array containing data hdr - The corresponding FITS header. Use MKHDR to create a minimal FITS header if one does not already exist. filename - Scalar string giving the name of the file to be written Should not include the extension name, which will be supplied by IRAFWRT. OUTPUTS: None OPTIONAL KEYWORD INPUT: PIXDIR - scalar string specifying the directory into which to write the IRAF pixel (.pix) file. The default is to write the pixel file to the same directory as the header (.imh) file SIDE EFFECTS: Image array and FITS header are written to IRAF pixel file 'filename'.pix and header file 'filename'.imh EXAMPLE: Write an empty 50 x 50 array of all zeros to an IRAF file named 'EMPTY' IDL> im = intarr( 50, 50) ;Create empty array IDL> mkhdr, hdr, im ;Create a minimal FITS header IDL> irafwrt, im, hdr, 'empty' ;Write to a IRAF file named 'empty' PROCEDURE: IRAFWRT gets information about the data - image dimensions, size, datatype, maximum and minimum pixel values - and writes it into the binary part of the header. The ASCII part of the header is directly copied after deleting records with certain keywords A pixel file is created, with a header in the first 1024 bytes RESTRICTIONS: (1) The files are not created by IRAFWRT are not identical to those created by the IRAF routine rfits. However, the files created by IRAFWRT appear to be compatible with all the IRAF routines tested so far. (2) IRAFWRT has been tested on a limited number of data types (3) IRAFWRT has only been tested on Unix and VMS systems. PROCEDURES CALLED: FDECOMP, IS_IEEE_BIG(), ISARRAY(), REPCHR(), STRN(), SXDELPAR, SXPAR() MODIFICATION HISTORY: Written K. Venkatakrishna, STX February 1992 VMS compatibility W. Landsman April 1992 Work with headers without DATE-OBS or ORIGIN August 1992 Preserve HISTORY records with other FITS records March 1995 Fix case where a minimal FITS header supplied August 1995 Work under Alpha/OSF and Linux Dec. 1995 Make sureheader has 80 char lines, use IS_IEEE_BIG() May 1997 Don't apply strlowcase to .pix name W. Landsman April 1999 Work with double precision W. Landsman May 1999 Minimize use of obsolete !ERR W. Landsman Feb. 2000 Assume since V5.5, remove VMS support W. Landsman Sep. 2006(See astrolib/pro/irafwrt.pro)
ISMEUV
[Previous Routine] [Next Routine] [List of Routines]NAME: ISMEUV PURPOSE: Compute the continuum interstellar EUV optical depth EXPLANATION: The EUV optical depth is computed from the photoionization of hydrogen and helium. CALLING SEQUENCE: tau = ISMEUV( wave, Hcol, [ HeIcol, HeIIcol, /Fano ] INPUTS: wave - Vector of wavelength values (in Angstroms). Useful range is 40 - 912 A; at shorter wavelengths metal opacity should be considered, at longer wavelengths there is no photoionization. Hcol - Scalar specifying interstellar hydrogen column density in cm-2. Typical values are 1E17 to 1E20. OUTPUT: tau - Vector giving resulting optical depth, same number of elements as wave, non-negative values. To obtain the attenuation of an input spectrum, multiply by exp(-tau). OPTIONAL INPUTS: HeIcol - Scalar specifying neutral helium column density in cm-2. Default is 0.1*Hcol (10% of hydrogen column) HeIIcol - Scalar specifying ionized helium column density in cm-2 Default is 0 (no HeII) OPTIONAL INPUT KEYWORDS: /FANO - If this keyword is set and non-zero, then the 4 strongest auto-ionizing resonances of He I are included. The shape of these resonances is given by a Fano profile - see Rumph, Bowyer, & Vennes 1994, AJ, 107, 2108. If these resonances are included then the input wavelength vector should have a fine (>~0.01 A) grid between 190 A and 210 A, since the resonances are very narrow. EXAMPLE: (1) One has a model EUV spectrum with wavelength, w (in Angstroms) and flux,f . Plot the model flux after attenuation by 1e18 cm-2 of HI, with N(HeI)/N(HI) = N(HeII)/N(HI) = 0.05 IDL> Hcol = 1e18 IDL> plot, w, f*exp(-ismeuv(w, Hcol, .05*Hcol, .05*Hcol)) (2) Plot the cross-section of HeI from 180 A to 220 A for 1e18 cm-2 of HeI, showing the auto-ionizing resonances. This is Figure 1 in Rumph et al. (1994) IDL> w = 180 + findgen(40000)*0.001 ;Need a fine wavelength grid IDL> plot, w, ismeuv(w, 0, 1e18, /Fano) NOTES: (1) The more complete program ismtau.pro at http://hea-www.harvard.edu/PINTofALE/pro/ extends this work to shorter wavelengths and includes metal and molecular hydrogen opacities (2) This program only compute continuum opacities, and for example, the He ionization edges at 504 A and 228 A are blurred by converging line absorptions (Dupuis et al. 1995. ApJ, 455, 574) HISTORY: Written, W. Landsman October, 1994 Adapted from ism.c at anonymous ftp site cea-ftp.cea.berkeley.edu by Pat Jelinsky, Todd Rumph & others. Converted to IDL V5.0 W. Landsman September 1997 Avoid underflow messages, support double prec. W. Landsman October 2003(See astrolib/pro/ismeuv.pro)
IS_IEEE_BIG
[Previous Routine] [Next Routine] [List of Routines]NAME: IS_IEEE_BIG PURPOSE: Determine if the current machine uses IEEE, big-endian numbers. EXPLANATION: (Big endian implies that byteorder XDR conversions are no-ops). CALLING SEQUENCE: flag = is_ieee_big() INPUT PARAMETERS: None RETURNS: 1 if the machine appears to be IEEE-compliant, 0 if not. COMMON BLOCKS: None. SIDE EFFECTS: None RESTRICTIONS: PROCEDURE: The first byte of the two-byte representation of 1 is examined. If it is zero, then the data is stored in big-endian order. MODIFICATION HISTORY: Written 15-April-1996 by T. McGlynn for use in MRDFITS. 13-jul-1997 jkf/acc - added calls to check_math to avoid underflow messages in V5.0 on Win32 (NT). Converted to IDL V5.0 W. Landsman September 1997 Follow RSI and just do a single test W. Landsman April 2003(See astrolib/pro/is_ieee_big.pro)
JDCNV
[Previous Routine] [Next Routine] [List of Routines]NAME: JDCNV PURPOSE: Converts Gregorian dates to Julian days EXPLANATION: For IDL versions V5.1 or greater, this procedure is superceded by JULDAY() function in the standard IDL distribution. Note, however, that prior to V5.1 there wasa bug in JULDAY() that gave answers off by 0.5 days. CALLING SEQUENCE: JDCNV, YR, MN, DAY, HR, JULIAN INPUTS: YR = Year, integer scalar or vector MN = Month integer (1-12) scalar or vector DAY = Day integer 1-31) scalar or vector HR = Hours and fractions of hours of universal time (U.T.), scalar or vector OUTPUTS: JULIAN = Julian date (double precision) EXAMPLE: To find the Julian Date at 1978 January 1, 0h (U.T.) IDL> JDCNV, 1978, 1, 1, 0., JULIAN will give JULIAN = 2443509.5 NOTES: (1) JDCNV will accept vector arguments (2) JULDATE is an alternate procedure to perform the same function REVISON HISTORY: Converted to IDL from Don Yeomans Comet Ephemeris Generator, B. Pfarr, STX, 6/15/88 Converted to IDL V5.0 W. Landsman September 1997 Added checks on valid month, day ranges W. Landsman July 2008(See astrolib/pro/jdcnv.pro)
JPLEPHINTERP
[Previous Routine] [Next Routine] [List of Routines]NAME: JPLEPHINTERP AUTHOR: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 craigm@lheamail.gsfc.nasa.gov UPDATED VERSIONs can be found on my WEB PAGE: http://cow.physics.wisc.edu/~craigm/idl/idl.html PURPOSE: Interpolate position and motion of planetary bodies (JPL Ephemeris) MAJOR TOPICS: Planetary Orbits, Interpolation CALLING SEQUENCE: JPLEPHINTERP, INFO, RAWDATA, T, X, Y, Z, [VX, VY, VZ, /EARTH, /SUN, OBJECTNAME=, CENTER=, TBASE=, POSUNITS=, VELUNITS= ] DESCRIPTION: JPLEPHINTERP interpolates the JPL DE200 or DE405 planetary ephemeris to find the positions and motions of planetary bodies. This routine is the second stage of a two-stage process to interpolate the JPL ephemeris. In this first stage, the file is opened using JPLEPHREAD, and the relevant portions of the table are read and stored into the two variables INFO and RAWDATA. In the second stage, the user actually interpolates the ephemeris for the desired bodies and to the desired ephemeris time using JPLEPHINTERP. The only independent variable which must be specified is T, the ephemeris time. For low to moderate accuracy applications, T is simply the conventional calendar date, expressed in Julian days. See below for high precision applications. Upon output, the position components of the desired body are returned in parameters X, Y and Z, and if requested velocity components are returned in parameters VX, VY and VZ. Coordinates are referred to the ephemeris's coordinate system: FK5 for JPL-DE200 and ICRS for JPL-DE405. By default, the origin of coordinates is the solar system barycenter (SSB), unless another origin is selected using the CENTER keyword. Users must set the VELOCITY keyword to generate body velocities. By default they are not generated. Users can select the desired body by using either the EARTH or SUN keywords, or the OBJECTNAME keyword. By default, positions are returned in units of KM and velocities in units of KM/DAY. However, the output units are selectable by setting the POSUNITS and VELUNITS keywords. High Precision Applications If the required precision is finer than a few hundred meters, the user must be aware that the formal definition of the ephemeris time is the coordinate time of a clock placed at the solar system barycenter (SSB). If the user's time is measured by a clock positioned elsewhere, then various corrections must be applied. Usually, the most significant correction is that from the geocenter to the SSB (see Fairhead & Bretagnon 1990; Fukushima 1995). Not applying this correction creates an error with amplitude ~170 nano-light-seconds ( = 50 m) on the earth's position. (see TDB2TDT) For high precision, the user should also specify the TBASE keyword. TBASE should be considered a fixed epoch with respect to which T is measured; T should be small compared to TBASE. Internally, subtraction of large numbers occurs with TBASE first, so truncation error is minimized by specifying TBASE. Nutations and Librations This routine also provides information about earth nutations and lunar librations, which are stored in the JPL ephemeris tables. The POSUNITS and VELUNITS keywords do not affect these computations. Lunar librations in the form of three Euler angles are returned in X, Y, Z, in units of radians, and their time derivatives are returned in VX, VY, and VZ in units of radians per day. The earth nutation angles psi (nutation in longitude) and epsilon (nutation in obliquity) are returned in X and Y, in units of radians. Their time derivatives are returned in VX and VY respectively. The quantities returned in Z and VZ are undefined. Verification The precision routine has been verified using JPLEPHTEST, which is similar to the original JPL program EPHTEST. For years 1950 to 2050, JPLEPHINTERP reproduces the original JPL ephemeris to within 1 centimeter. Custom Ephemerides It is possible to make custom ephemerides using JPLEPHMAKE, or to augmented an existing ephemeris with additional data. In the former case JPLEPHINTERP should automatically choose the correct object from the table and interpolate it appropriately. For augmented ephemerides, the object can be specified by name, which works as expected, or by number, which has a special behavior. For augmented files only, the new objects begin at number 100. PARAMETERS: INFO - structure returned by JPLEPHREAD. Users should not modify this structure. RAWDATA - raw data array returned by JPLEPHREAD. Users should not modify this data array. T - ephemeris time(s) of interest, relative to TBASE (i.e. the actual interpolation time is (T+TBASE)). May be a scalar or vector. X, Y, Z - upon return, the x-, y- and z-components of the body position are returned in these parameters. For nutations and librations see above. VX, VY, VZ - upon return, the x-, y- and z-components of the body velocity are returned in these parameters, if the VELOCITY keyword is set. For nutations and librations see above. KEYWORD PARAMETERS: EARTH, SUN - set one of these keywords if the desired body is the earth or the sun. One of EARTH, SUN or OBJECTNAME must be specified. OBJECTNAME - a scalar string or integer, specifies the planetary body of interest. May take any one of the following integer or string values. 1 - 'MERCURY' 9 - 'PLUTO' 2 - 'VENUS' 10 - 'MOON' (earth's moon) 3 - 'EARTH' 11 - 'SUN' 4 - 'MARS' 12 - 'SOLARBARY' or 'SSB' (solar system barycenter) 5 - 'JUPITER' 13 - 'EARTHBARY' or 'EMB' (earth-moon barycenter) 6 - 'SATURN' 14 - 'NUTATIONS' (see above) 7 - 'URANUS' 15 - 'LIBRATIONS' (see above) 8 - 'NEPTUNE' For custom ephemerides, the user should specify the object name or number. For augmented ephemerides, the user should specify the name. If the number is specified, then numbers 1-15 have the above meanings, and new objects are numbered starting at 100. CENTER - a scalar string or integer, specifies the origin of coordinates. See OBJECTNAME for allowed values. Default: 12 (Solar system barycenter) VELOCITY - if set, body velocities are generated and returned in VX, VY and VZ. Default: unset (no velocities) POSUNITS - a scalar string specifying the desired units for X, Y, and Z. Allowed values: 'KM' - kilometers (default) 'CM' - centimeters 'AU' - astronomical units 'LT-S' - light seconds If angles are requested, this keyword is ignored and the units are always 'RADIANS'. VELUNITS - a scalar string specifying the desired units for VX, VY and VZ. Allowed values: 'KM/DAY' - kilometers per day (default) 'KM/S' - kilometers per second 'CM/S' - centimeters per second 'LT-S/S' - light seconds per second 'AU/DAY' - astronomical units per day TBASE - a scalar or vector, specifies a fixed epoch against wich T is measured. The ephemeris time will be (T+TBASE). Use this keyword for maximum precision. EXAMPLE: Find position of earth at ephemeris time 2451544.5 JD. Units are in Astronomical Units. JPLEPHREAD, 'JPLEPH.200', pinfo, pdata, [2451544D, 2451545D] JPLEPHINTERP, pinfo, pdata, 2451544.5D, xearth, yearth, zearth, $ /EARTH, posunits='AU' REFERENCES: AXBARY, Arnold Rots. ftp://heasarc.gsfc.nasa.gov/xte/calib_data/clock/bary/ HORIZONS, JPL Web-based ephermis calculator (Ephemeris DE406) http://ssd.jpl.nasa.gov/horizons.html Fairhead, L. & Bretagnon, P. 1990, A&A, 229, 240 Fukushima, T. 1995, A&A, 294, 895 Standish, E.M. 1982, "Orientation of the JPL Ephemerides, DE200/LE200, to the Dynamical Equinox of J2000", Astronomy & Astrophysics, vol. 114, pp. 297-302. Standish, E.M.: 1990, "The Observational Basis for JPL's DE200, the planetary ephemeris of the Astronomical Almanac", Astronomy & Astrophysics, vol. 233, pp. 252-271. SEE ALSO JPLEPHREAD, JPLEPHINTERP, JPLEPHTEST, TDB2TDT, JPLEPHMAKE MODIFICATION HISTORY: Written and Documented, CM, Jun 2001 Corrected bug in name conversion of NUTATIONS and LIBRATIONS, 18 Oct 2001, CM Added code to handle custom-built ephemerides, 04 Mar 2002, CM Fix bug in evaluation of velocity (only appears in highest order polynomial term); JPLEPHTEST verification tests still pass; change is of order < 0.5 cm in position, 22 Nov 2004, CM Perform more validity checking on inputs; and more informative outputs, 09 Oct 2008, CM Allow SSB and EMB as shortcuts for solar system and earth-moon bary center, 15 Oct 2008, CM TBASE now allowed to be a vector or scalar, 01 Jan 2009, CM VELFAC keyword gives scale factor between POSUNITS and VELUNITS, 12 Jan 2009, CM $Id: jplephinterp.pro,v 1.18 2009/01/13 04:53:26 craigm Exp $(See astrolib/pro/jplephinterp.pro)
JPLEPHREAD
[Previous Routine] [Next Routine] [List of Routines]NAME: JPLEPHREAD AUTHOR: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 craigm@lheamail.gsfc.nasa.gov UPDATED VERSIONs can be found on my WEB PAGE: http://cow.physics.wisc.edu/~craigm/idl/idl.html PURPOSE: Open and read JPL DE200 or DE405 Ephemeride FITS File MAJOR TOPICS: Planetary Orbits, Interpolation CALLING SEQUENCE: JPLEPHREAD, FILENAME, INFO, RAWDATA, JDLIMITS, STATUS=, ERRMSG= DESCRIPTION: JPLEPHREAD opens and reads the JPL DE200 or DE405 planetary ephemerides, as available in FITS format. The user must have the IDL Astronomy Library installed to use this routine. This routine is the initialization stage of a two-stage process to interpolate the JPL ephemeris. In this first stage, the file is opened, and the relevant portions of the table are read and stored into the two variables INFO and RAWDATA. In the second stage, the user actually interpolates the ephemeris for the desired bodies and to the desired ephemeris time using JPLEPHINTERP. Users must decide ahead of time the approximate dates of interest, and pass this range in the JDLIMITS parameter. Any date covered by the ephemeris is valid. JPLEPHREAD is able to read files of the following format: DE200 - Chebyshev - FITS format - Note 1 DE405 - Chebyshev - FITS format - Note 1 DE200 - Taylor - FITS format - Note 2 Note 1 - Chebyshev formatted FITS files are available in the AXBARY package by Arnold Rots, found here: ftp://heasarc.gsfc.nasa.gov/xte/calib_data/clock/bary/ or at the Markwardt FTP site: ftp://cow.physics.wisc.edu/pub/craigm/bary/ Note 2 - Taylor-series based ephemerides have been available for years in the FTOOLS / LHEASOFT package produced by NASA's Goddard Space Flight Center. The original file is de200_new.fits, which covers the years 1959-2000, inclusive. A newer file is named de200_1950-2050_v2.fits, and covers the years 1959-2050. See Markwardt FTP site for these files. PARAMETERS: FILENAME - name of ephemeris file (scalar string). INFO - upon completion, information about the ephemeris data is returned in this parameter in the form of a structure. Users must not modify INFO, although several fields are useful and may be accessed read-only: TSTART/TSTOP (start and stop time of data in Julian days); C (speed of light in km/s); DENUM (development ephemeris number [200 or 405]) AU (1 astronomical unit, in units of light-seconds) RAWDATA - upon completion, raw ephemeris data is returned in this parameter. Users are not meant to access this data directly, but rather to pass it to JPLEPHINTERP. JDLIMITS - a two-element vector (optional), describing the desired time range of interest. The vector should have the form [TSTART, TSTOP], where TSTART and TSTOP are the beginning and ending times of the range, expressed in Julian days. Default: entire table is read (note, this can be several megabytes) KEYWORD PARAMETERS: STATUS - upon completion, a value of 1 indicates success, and 0 indicates failure. ERRMSG - upon completion, an error message is returned in this keyword. If there were no errors, then the returned value is the empty string, ''. EXAMPLE: Find position of earth at ephemeris time 2451544.5 JD. Units are in Astronomical Units. JPLEPHREAD, 'JPLEPH.200', pinfo, pdata, [2451544D, 2451545D] JPLEPHINTERP, pinfo, pdata, 2451544.5D, xearth, yearth, zearth, $ /EARTH, posunits='AU' REFERENCES: AXBARY, Arnold Rots. ftp://heasarc.gsfc.nasa.gov/xte/calib_data/clock/bary/ HORIZONS, JPL Web-based ephermis calculator (Ephemeris DE406) http://ssd.jpl.nasa.gov/horizons.html JPL Export Ephemeris FTP Site ftp://ssd.jpl.nasa.gov/pub/eph/planets/ (ephemeris files are available here, however, they must be converted to FITS format using the "bin2eph" utility found in AXBARY) JPL Export Ephemeris CD-ROM - Ordering Information http://www.willbell.com/software/jpl.htm Standish, E.M. 1982, "Orientation of the JPL Ephemerides, DE200/LE200, to the Dynamical Equinox of J2000", Astronomy & Astrophysics, vol. 114, pp. 297-302. Standish, E.M.: 1990, "The Observational Basis for JPL's DE200, the planetary ephemeris of the Astronomical Almanac", Astronomy & Astrophysics, vol. 233, pp. 252-271. SEE ALSO JPLEPHREAD, JPLEPHINTERP, JPLEPHTEST PROCEDURES USED: FXBCLOSE, FXBOPEN, FXPAR(), MODIFICATION HISTORY: Written and Documented, CM, Jun 2001 Use GETTOK() instead of STR_SEP() W. Landsman July 2002 $Id: jplephread.pro,v 1.6 2001/07/01 03:32:02 craigm Exp $(See astrolib/pro/jplephread.pro)
JPLEPHTEST
[Previous Routine] [Next Routine] [List of Routines]NAME: JPLEPHTEST AUTHOR: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 craigm@lheamail.gsfc.nasa.gov UPDATED VERSIONs can be found on my WEB PAGE: http://cow.physics.wisc.edu/~craigm/idl/idl.html PURPOSE: Test JPLEPHTEST with JPL test data set MAJOR TOPICS: Planetary Orbits, Interpolation CALLING SEQUENCE: JPLEPHTEST, EPHFILE, TESTFILE DESCRIPTION: JPLEPHTEST tests the JPLEPHINTERP procedure for precision. In order to function, you must have a JPL ephemeris test data set. The test data set testpo.405 is available in ftp://idlastro.gsfc.nasa.gov/pub/data The procedure opens and reads the test set, which contains precomputed data. Every tenth value is printed on the screen. Any deviations that exceed 1.5d-13 AU = 1.5 cm are reported. The columns are labelled according to the input file, except for the final column, which is the deviation between the input file and the computed value. PARAMETERS: EPHFILE - a scalar string, specifies the name of the ephemeris file, in FITS format. JPLEPHTEST will look in the directory $ASTRO_DATA for the file if it is not in the current directory. TESTFILE - a scalar string, specifies JPL test data set to compare against. JPLEPHTEST will look in the directory $ASTRO_DATA for the file if it is not in the current directory. EXAMPLE: Test JPL DE200 and DE405 ephemerides. Assumes files are in the current directory. JPLEPHTEST, 'JPLEPH.200', 'testpo.200' JPLEPHTEST, 'JPLEPH.405', 'testpo.405' REFERENCES: JPL Export Ephemeris FTP Site ftp://ssd.jpl.nasa.gov/pub/eph/planets/ (see test-data/ for test data sets) HORIZONS, JPL Web-based ephermis calculator (Ephemeris DE406) http://ssd.jpl.nasa.gov/horizons.html SEE ALSO JPLEPHREAD, JPLEPHINTERP, JPLEPHTEST MODIFICATION HISTORY: Written and Documented, CM, Jun 2001 Removed TRANSREAD, improved output, improved docs, CM, 9 Jul 2001 $Id: jplephtest.pro,v 1.4 2001/07/20 13:29:53 craigm Exp $(See astrolib/pro/jplephtest.pro)
JPRECESS
[Previous Routine] [Next Routine] [List of Routines]NAME: JPRECESS PURPOSE: Precess astronomical coordinates from B1950 to J2000 EXPLANATION: Calculate the mean place of a star at J2000.0 on the FK5 system from the mean place at B1950.0 on the FK4 system. Use BPRECESS for the reverse direction J2000 ==> B1950 CALLING SEQUENCE: jprecess, ra, dec, ra_2000, dec_2000, [ MU_RADEC = , PARALLAX = RAD_VEL =, EPOCH = ] INPUTS: RA,DEC - input B1950 right ascension and declination in *degrees*. Scalar or vector OUTPUTS: RA_2000, DEC_2000 - the corresponding J2000 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 J2000 system. Values will also be converted to double precision. The parallax and radial velocity will have a very minor influence on the J2000 position. EPOCH - scalar giving epoch of original observations, default 1950.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 184. Also see Aoki et al (1983), A&A, 128,263 JPRECESS 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 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 J2000 can be up to 12", mainly in right ascension. If better accuracy than this is needed then JPRECESS should be used. EXAMPLE: The SAO catalogue gives the B1950 position and proper motion for the star HD 119288. Find the J2000 position. RA(1950) = 13h 39m 44.526s Dec(1950) = 8d 38' 28.63'' Mu(RA) = -.0259 s/yr Mu(Dec) = -.093 ''/yr IDL> mu_radec = 100D* [ -15D*.0259, -0.093 ] IDL> ra = ten(13,39,44.526)*15.D IDL> dec = ten(8,38,28.63) IDL> jprecess, ra, dec, ra2000, dec2000, mu_radec = mu_radec IDL> print, adstring(ra2000, dec2000,2) ===> 13h 42m 12.740s +08d 23' 17.69" RESTRICTIONS: "When transferring individual observations, as opposed to catalog mean place, the safest method is to tranform the observations back to the epoch of the observation, on the FK4 system (or in the system that was used to to produce the observed mean place), convert to the FK5 system, and transform to the the epoch and equinox of J2000.0" -- from the Explanatory Supplement (1992), p. 180 REVISION HISTORY: Written, W. Landsman September, 1992 Corrected a couple of typos in M matrix October, 1992 Vectorized, W. Landsman February, 1994 Implement Appendix 2 of Aoki et al. (1983) for case where proper motion unknown or exactly zero W. Landsman November, 1994 Converted to IDL V5.0 W. Landsman September 1997 Fixed typo in updating proper motion W. Landsman April 1999 Make sure proper motion is floating point W. Landsman December 2000 Use V6.0 notation W. Landsman Mar 2011(See astrolib/pro/jprecess.pro)
JULDATE
[Previous Routine] [Next Routine] [List of Routines]NAME: JULDATE PURPOSE: Convert from calendar to Reduced Julian Date EXPLANATION: Julian Day Number is a count of days elapsed since Greenwich mean noon on 1 January 4713 B.C. The Julian Date is the Julian day number followed by the fraction of the day elapsed since the preceding noon. This procedure duplicates the functionality of the JULDAY() function in in the standard IDL distribution, but also allows interactive input and gives output as Reduced Julian date (=JD - 2400000.) CALLING SEQUENCE: JULDATE, /PROMPT ;Prompt for calendar Date, print Julian Date or JULDATE, date, jd INPUT: DATE - 3 to 6-element vector containing year,month (1-12),day, and optionally hour, minute, and second all specified as numbers (Universal Time). Year should be supplied with all digits. Years B.C should be entered as negative numbers (and note that Year 0 did not exist). If Hour, minute or seconds are not supplied, they will default to 0. OUTPUT: JD - Reduced Julian date, double precision scalar. To convert to Julian Date, add 2400000. JULDATE will print the value of JD at the terminal if less than 2 parameters are supplied, or if the /PROMPT keyword is set OPTIONAL INPUT KEYWORD: /PROMPT - If this keyword is set and non-zero, then JULDATE will prompt for the calendar date at the terminal. RESTRICTIONS: The procedure HELIO_JD can be used after JULDATE, if a heliocentric Julian date is required. EXAMPLE: A date of 25-DEC-2006 06:25 UT may be expressed as either IDL> juldate, [2006, 12, 25, 6, 25], jd IDL> juldate, [2006, 12, 25.2673611d], jd In either case, one should obtain a Reduced Julian date of JD = 54094.7673611 PROCEDURE USED: GETOPT() REVISION HISTORY Adapted from IUE RDAF (S. Parsons) 8-31-87 Algorithm from Sky and Telescope April 1981 Added /PROMPT keyword, W. Landsman September 1992 Converted to IDL V5.0 W. Landsman September 1997 Make negative years correspond to B.C. (no year 0), work for year 1582 Disallow 2 digit years. W. Landsman March 2000(See astrolib/pro/juldate.pro)
KSONE
[Previous Routine] [Next Routine] [List of Routines]NAME: KSONE PURPOSE: Compute the one-sided Kolmogorov-Smirnov statistic EXPLANATION: Returns the Kolmogorov-Smirnov statistic and associated probability for for an array of data values and a user-supplied cumulative distribution function (CDF) of a single variable. Algorithm from the procedure of the same name in "Numerical Recipes" by Press et al. 2nd edition (1992) CALLING SEQUENCE: ksone, data, func_name, D, prob, [ /PLOT ] INPUT PARAMETERS: data - vector of data values, must contain at least 4 elements for the K-S statistic to be meaningful func_name - scalar string giving the name of the cumulative distribution function. The function must be defined to accept the data vector as its only input (see example), though keywords may be passed via the _EXTRA facility. OUTPUT PARAMETERS: D - floating scalar giving the Kolmogorov-Smirnov statistic. It specified the maximum deviation between the cumulative distribution of the data and the supplied function prob - floating scalar between 0 and 1 giving the significance level of the K-S statistic. Small values of PROB show that the cumulative distribution function of DATA is significantly different from FUNC_NAME. OPTIONAL INPUT KEYWORD: /PLOT - If this keyword is set and non-zero, then KSONE will display a plot of the CDF of the data with the supplied function superposed. The data value where the K-S statistic is computed (i.e. at the maximum difference between the data CDF and the function) is indicated by a vertical line. KSONE accepts the _EXTRA keyword, so that most plot keywords (e.g. TITLE, XTITLE, XSTYLE) can also be passed to KSONE. /WINDOW - If set, the plot to a resizeable graphics window EXAMPLE: Determine if a vector created by the RANDOMN function is really consistent with a Gaussian distribution with unit variance. The CDF of a Gaussian is the error function except that a factor of 2 is included in the error function. So we must create a special function: function gauss_cdf, x return, errorf( x/sqrt(2) ) end IDL> data = randomn(seed, 50) ;create data array to be tested IDL> ksone, abs(data), 'gauss_cdf', D, prob, /PLOT ;Use K-S test A small value of PROB indicates that the cumulative distribution of DATA is significantly different from a Gaussian NOTES: The code for PROB_KS is from the 2nd (1992) edition of Numerical Recipes which includes a more accurate computation of the K-S significance for small values of N than the first edition. Since _EXTRA is used to pass extra parameters both to the user-supplied function, and to the cgPLOT command, the user-supplied function should not accept "cgPLOT" keyword names (e.g. XTITLE). PROCEDURE CALLS procedure PROB_KS - computes significance of K-S distribution TAG_EXIST() REVISION HISTORY: Written W. Landsman August, 1992 Accept _EXTRA keywords W. Landsman September, 1995 Fixed possible bug in plot display showing position maximum difference in histogram M. Fardal/ W. Landsman March, 1997 Documentation updates W. Landsman June 2003 Pass _EXTRA to func_name M. Fitzgerald April, 2005 Work for functions that do not accept keywords W. Landsman July 2009 Use Coyote graphics for plotting Feb 2011(See astrolib/pro/ksone.pro)
KSTWO
[Previous Routine] [Next Routine] [List of Routines]NAME: KSTWO PURPOSE: Return the two-sided Kolmogorov-Smirnov statistic EXPLANATION: Returns the Kolmogorov-Smirnov statistic and associated probability that two arrays of data values are drawn from the same distribution Algorithm taken from procedure of the same name in "Numerical Recipes" by Press et al., 2nd edition (1992), Chapter 14 CALLING SEQUENCE: kstwo, data1, data2, D, prob INPUT PARAMATERS: data1 - vector of data values, at least 4 data values must be included for the K-S statistic to be meaningful data2 - second set of data values, does not need to have the same number of elements as data1 OUTPUT PARAMETERS: D - floating scalar giving the Kolmogorov-Smirnov statistic. It specifies the maximum deviation between the cumulative distribution of the data and the supplied function prob - floating scalar between 0 and 1 giving the significance level of the K-S statistic. Small values of PROB show that the cumulative distribution function of DATA1 is significantly different from DATA2 EXAMPLE: Test whether two vectors created by the RANDOMN function likely came from the same distribution IDL> data1 = randomn(seed,40) ;Create data vectors to be IDL> data2 = randomn(seed,70) ;compared IDL> kstwo, data1, data2, D, prob & print,D,prob PROCEDURE CALLS procedure PROB_KS - computes significance of K-S distribution REVISION HISTORY: Written W. Landsman August, 1992 FP computation of N_eff H. Ebeling/W. Landsman March 1996 Fix for arrays containing equal values J. Ballet/W. Landsman Oct. 2001 Fix index when maximum difference is at array end Renbin Yan Dec 2008 Handle large number when computing N_err D. Schnitzeler/WL Sep 2010(See astrolib/pro/kstwo.pro)
KUIPERONE
[Previous Routine] [Next Routine] [List of Routines]NAME: KUIPERONE PURPOSE: Compute the one-sided Kuiper statistic (invariant Kolmogorov-Smirnov) EXPLANATION: Returns the Kuiper statistic and associated probability for an array of data values and a user-supplied cumulative distribution function (CDF) of a single variable. Algorithm adapted from KSONE in "Numerical Recipes" by Press et al. 2nd edition (1992) Kuiper's test is especially useful for data defined on a circle or to search for periodicity (see Paltani 2004, A&A, 420, 789). CALLING SEQUENCE: kuiperone, data, func_name, D, prob, [ /PLOT ] INPUT PARAMETERS: data - vector of data values, must contain at least 4 elements for the Kuiper statistic to be meaningful func_name - scalar string giving the name of the cumulative distribution function. The function must be defined to accept the data vector as its only input (see example). OUTPUT PARAMETERS: D - floating scalar giving the Kuiper statistic. It specifies the sum of positive and negative deviations between the cumulative distribution of the data and the supplied function prob - floating scalar between 0 and 1 giving the significance level of the Kuiper statistic. Small values of PROB show that the cumulative distribution function of DATA is significantly different from FUNC_NAME. OPTIONAL INPUT KEYWORD: /PLOT - If this keyword is set and non-zero, then KUIPERONE will display a plot of the CDF of the data with the supplied function superposed. The data values where the Kuiper statistic is computed (i.e. at the maximum difference between the data CDF and the function) are indicated by vertical dashed lines. KUIPERONE accepts the _EXTRA keyword, so that most plot keywords (e.g. TITLE, XTITLE, XSTYLE) can also be passed to KUIPERONE. EXAMPLE: Determine if a vector created by the RANDOMN function is really consistent with a Gaussian distribution. The CDF of a Gaussian is the error function except that a factor of 2 is included in the error function. So we must create a special function: function gauss_cdf, x return, errorf( x/sqrt(2) ) end IDL> data = randomn(seed, 50) ;create data array to be tested IDL> kuiperone, data, 'gauss_pdf', D, prob, /PLOT ;Use Kuiper test A small value of PROB indicates that the cumulative distribution of DATA is significantly different from a Gaussian NOTES: Note that the 2nd (1992) edition of Numerical Recipes includes a more accurate computation of the K-S significance for small values of N. PROCEDURE CALLS procedure PROB_KUIPER - computes significance of Kuiper distribution REVISION HISTORY: Written W. Landsman August, 1992 Accept _EXTRA keywords W. Landsman September, 1995 Fixed possible bug in plot display showing position maximum difference in histogram M. Fardal/ W. Landsman March, 1997 Adapted from KSONE J. Ballet July 2003 Use Coyote graphics W. Landsman Feb 2011(See astrolib/pro/kuiperone.pro)
KUIPERTWO
[Previous Routine] [Next Routine] [List of Routines]NAME: KUIPERTWO PURPOSE: Compute the two-sided Kuiper statistic (invariant Kolmogorov-Smirnov) EXPLANATION: Returns the Kuiper statistic and associated probability that two arrays of data values are drawn from the same distribution Algorithm adapted from KSTWO in "Numerical Recipes" by Press et al., 2nd edition (1992), Chapter 14 CALLING SEQUENCE: kuipertwo, data1, data2, D, prob, [ /PLOT ] INPUT PARAMETERS: data1 - vector of data values, at least 4 data values must be included for the Kuiper statistic to be meaningful data2 - second set of data values, does not need to have the same number of elements as data1 OUTPUT PARAMETERS: D - floating scalar giving the Kuiper statistic. It specifies the sum of positive and negative deviations between the cumulative distributions of the two data sets prob - floating scalar between 0 and 1 giving the significance level of the Kuiper statistic. Small values of PROB show that the cumulative distribution function of DATA1 is significantly different from DATA2 OPTIONAL INPUT KEYWORD: /PLOT - If this keyword is set and non-zero, then KUIPERTWO will display a plot of the CDF of the two data sets. The data values where the Kuiper statistic is computed (i.e. at the maximum difference between the CDF of the two data sets) are indicated by vertical dashed lines. KUIPERTWO accepts the _EXTRA keyword, so that most plot keywords (e.g. TITLE, XTITLE, XSTYLE) can also be passed to KUIPERTWO. /WINDOW - If set the plot to a resizeable graphics window. EXAMPLE: Test whether two vectors created by the RANDOMN function likely came from the same distribution IDL> data1 = randomn(seed,40) ;Create data vectors to be IDL> data2 = randomn(seed,70) ;compared IDL> kuipertwo, data1, data2, D, prob & print,D,prob PROCEDURE CALLS procedure PROB_KUIPER - computes significance of Kuiper distribution REVISION HISTORY: Written W. Landsman August, 1992 FP computation of N_eff H. Ebeling/W. Landsman March 1996 Fix for arrays containing equal values J. Ballet/W. Landsman Oct. 2001 Adapted from KSTWO, added PLOT keyword J. Ballet July 2004 Use Coyote Graphics W. Landsman Feb 2011(See astrolib/pro/kuipertwo.pro)
LINEID_PLOT
[Previous Routine] [Next Routine] [List of Routines]NAME: LINEID_PLOT PURPOSE: Plot spectrum with specified line identifications annotated at the top of the plot. CALLING SEQUENCE: lineid_plot, wave, flux, wline, text1, [ text2, LCHARSIZE=, LCHARTHICK=, EXTEND =, ...plotting keywords] INPUTS: wave - wavelength vector for the plot flux - flux vector wline - wavelength vector of line identifications. (only the lines between the plot limits will be used) text1 - string array of text to be used to annotate each line text2 - (OPTIONAL) second string array of text to be used for line annotation. Since the text is written with proportional spaced characters, TEXT2 can be used if you want two sets of annotation to be alinged: eg: Cr IV 1390.009 Fe V 1390.049 Ni IV 1390.184 instead of Cr IV 1390.009 Fe V 1390.049 Ni IV 1390.184 OPTIONAL KEYWORD INPUTS: EXTEND - specifies that the annotated lines should have a dotted line extended to the spectrum to indicate the line position. EXTEND can be a scalar (applies to all lines) or a vector with a different value for each line. The value of EXTEND gives the line IDL plot line thickness for the dotted lines. If EXTEND is a vector each dotted line can have a different thickness. A value of 0 indicates that no dotted line is to be drawn. (default = scalar 0) LCHARSIZE - the character size of the annotation for each line. If can be a vector so that different lines are annotated with different size characters. LCHARSIZE can be used to make stronger lines have a larger annotation. (default = scalar 1.0). LCHARTHICK = the character thickness of the annotation for each line. It can be a vector so that different lines are annotated with characters of varying thickness. LCHARTHICK can be used to make stronger lines have a bolder annotation. (default = !p.charthick) LINEID_PLOT uses the _EXTRA facility to allow the use of any cgPLOT keywords (e.g. AXISCOLOR, LINESTYLE, CHARSIZE) to be passed to the plot. SIDE EFFECTS: Program uses SET_VIEWPORT to set the !P.POSITION parameter to allow room for the annotation. This system variable can be reset to the default value by setting !P.POSTION=0 or typing SET_VIEWPORT with no parameters OPERATIONAL NOTES: Once the program has completed, You can use OPLOT to draw additional plots on the display. If your annotated characters are not being rotated properly, try setting !P.FONT to a non zero value. EXAMPLE: Annotate some interstellar lines between 1240 and 1270 A. IDL> w = 1240+ indgen(300)*0.1 ;Make a wavelength vector IDL> f = randomn(seed,300) ;Random flux vector IDL> id = ['N V','Si II','Si II','Si II'] ;Line IDs IDL> wl = [1242.80,1260.42,1264.74,1265.00] ;Line positions IDL> lineid_plot,w,f,wl,id,wl,/ext Note that LINEID_PLOT is smart enough not to overlap the annotation for the two closely spaced lines at 1264.74 and 1265.00 HISTORY: version 1 D. Lindler Jan, 1992 Sept 27, 1993 DJL fixed bug in /extend option Apr 19, 1994 DJL corrected bug in sorting of charthick (cthick) Sep 1996, W. Landsman, added _EXTRA keyword, changed keyword names CHARTHICK==>LCHARTHICK, CHARSIZE==>LCHARSIZE Work with !P.MULTI W. Landsman December 2003 Use Coyote graphics routines W. Landsman February 2011(See astrolib/pro/lineid_plot.pro)
LINMIX_ERR
[Previous Routine] [Next Routine] [List of Routines]NAME: LINMIX_ERR PURPOSE: Bayesian approach to linear regression with errors in both X and Y EXPLANATION: Perform linear regression of y on x when there are measurement errors in both variables. the regression assumes : ETA = ALPHA + BETA * XI + EPSILON X = XI + XERR Y = ETA + YERR Here, (ALPHA, BETA) are the regression coefficients, EPSILON is the intrinsic random scatter about the regression, XERR is the measurement error in X, and YERR is the measurement error in Y. EPSILON is assumed to be normally-distributed with mean zero and variance SIGSQR. XERR and YERR are assumed to be normally-distributed with means equal to zero, variances XSIG^2 and YSIG^2, respectively, and covariance XYCOV. The distribution of XI is modelled as a mixture of normals, with group proportions PI, mean MU, and variance TAUSQR. Bayesian inference is employed, and a structure containing random draws from the posterior is returned. Convergence of the MCMC to the posterior is monitored using the potential scale reduction factor (RHAT, Gelman et al.2004). In general, when RHAT < 1.1 then approximate convergence is reached. Simple non-detections on y may also be included. CALLING SEQUENCE: LINMIX_ERR, X, Y, POST, XSIG=, YSIG=, XYCOV=, DELTA=, NGAUSS=, /SILENT, /METRO, MINITER= , MAXITER= INPUTS : X - THE OBSERVED INDEPENDENT VARIABLE. THIS SHOULD BE AN NX-ELEMENT VECTOR. Y - THE OBSERVED DEPENDENT VARIABLE. THIS SHOULD BE AN NX-ELEMENT VECTOR. OPTIONAL INPUTS : XSIG - THE 1-SIGMA MEASUREMENT ERRORS IN X, AN NX-ELEMENT VECTOR. YSIG - THE 1-SIGMA MEASUREMENT ERRORS IN Y, AN NX-ELEMENT VECTOR. XYCOV - THE COVARIANCE BETWEEN THE MEASUREMENT ERRORS IN X AND Y, AND NX-ELEMENT VECTOR. DELTA - AN NX-ELEMENT VECTOR INDICATING WHETHER A DATA POINT IS CENSORED OR NOT. IF DELTA[i] = 1, THEN THE SOURCE IS DETECTED, ELSE IF DELTA[i] = 0 THE SOURCE IS NOT DETECTED AND Y[i] SHOULD BE AN UPPER LIMIT ON Y[i]. NOTE THAT IF THERE ARE CENSORED DATA POINTS, THEN THE MAXIMUM-LIKELIHOOD ESTIMATE (THETA) IS NOT VALID. THE DEFAULT IS TO ASSUME ALL DATA POINTS ARE DETECTED, IE, DELTA = REPLICATE(1, NX). METRO - IF METRO = 1, THEN THE MARKOV CHAINS WILL BE CREATED USING THE METROPOLIS-HASTINGS ALGORITHM INSTEAD OF THE GIBBS SAMPLER. THIS CAN HELP THE CHAINS CONVERGE WHEN THE SAMPLE SIZE IS SMALL OR IF THE MEASUREMENT ERRORS DOMINATE THE SCATTER IN X AND Y. SILENT - SUPPRESS TEXT OUTPUT. MINITER - MINIMUM NUMBER OF ITERATIONS PERFORMED BY THE GIBBS SAMPLER OR METROPOLIS-HASTINGS ALGORITHM. IN GENERAL, MINITER = 5000 SHOULD BE SUFFICIENT FOR CONVERGENCE. THE DEFAULT IS MINITER = 5000. THE MCMC IS STOPPED AFTER RHAT < 1.1 FOR ALL PARAMETERS OF INTEREST, AND THE NUMBER OF ITERATIONS PERFORMED IS GREATER THAN MINITER. MAXITER - THE MAXIMUM NUMBER OF ITERATIONS PERFORMED BY THE MCMC. THE DEFAULT IS 1D5. THE MCMC IS STOPPED AUTOMATICALLY AFTER MAXITER ITERATIONS. NGAUSS - THE NUMBER OF GAUSSIANS TO USE IN THE MIXTURE MODELLING. THE DEFAULT IS 3. IF NGAUSS = 1, THEN THE PRIOR ON (MU, TAUSQR) IS ASSUMED TO BE UNIFORM. OUTPUT : POST - A STRUCTURE CONTAINING THE RESULTS FROM THE MCMC. EACH ELEMENT OF POST IS A DRAW FROM THE POSTERIOR DISTRIBUTION FOR EACH OF THE PARAMETERS. ALPHA - THE CONSTANT IN THE REGRESSION. BETA - THE SLOPE OF THE REGRESSION. SIGSQR - THE VARIANCE OF THE INTRINSIC SCATTER. PI - THE GAUSSIAN WEIGHTS FOR THE MIXTURE MODEL. MU - THE GAUSSIAN MEANS FOR THE MIXTURE MODEL. TAUSQR - THE GAUSSIAN VARIANCES FOR THE MIXTURE MODEL. MU0 - THE HYPERPARAMETER GIVING THE MEAN VALUE OF THE GAUSSIAN PRIOR ON MU. ONLY INCLUDED IF NGAUSS > 1. USQR - THE HYPERPARAMETER DESCRIBING FOR THE PRIOR VARIANCE OF THE INDIVIDUAL GAUSSIAN CENTROIDS ABOUT MU0. ONLY INCLUDED IF NGAUSS > 1. WSQR - THE HYPERPARAMETER DESCRIBING THE `TYPICAL' SCALE FOR THE PRIOR ON (TAUSQR,USQR). ONLY INCLUDED IF NGAUSS > 1. XIMEAN - THE MEAN OF THE DISTRIBUTION FOR THE INDEPENDENT VARIABLE, XI. XISIG - THE STANDARD DEVIATION OF THE DISTRIBUTION FOR THE INDEPENDENT VARIABLE, XI. CORR - THE LINEAR CORRELATION COEFFICIENT BETWEEN THE DEPENDENT AND INDEPENDENT VARIABLES, XI AND ETA. CALLED ROUTINES : RANDOMCHI, MRANDOMN, RANDOMGAM, RANDOMDIR, MULTINOM REFERENCES : Carroll, R.J., Roeder, K., & Wasserman, L., 1999, Flexible Parametric Measurement Error Models, Biometrics, 55, 44 Kelly, B.C., 2007, Some Aspects of Measurement Error in Linear Regression of Astronomical Data, The Astrophysical Journal, 665, 1489 (arXiv:0705.2774) Gelman, A., Carlin, J.B., Stern, H.S., & Rubin, D.B., 2004, Bayesian Data Analysis, Chapman & Hall/CRC REVISION HISTORY AUTHOR : BRANDON C. KELLY, STEWARD OBS., JULY 2006 - MODIFIED PRIOR ON MU0 TO BE UNIFORM OVER [MIN(X),MAX(X)] AND PRIOR ON USQR TO BE UNIFORM OVER [0, 1.5 * VARIANCE(X)]. THIS TENDS TO GIVE BETTER RESULTS WITH FEWER GAUSSIANS. (B.KELLY, MAY 2007) - FIXED BUG SO THE ITERATION COUNT RESET AFTER THE BURNIN STAGE WHEN SILENT = 1 (B. KELLY, JUNE 2009) - FIXED BUG WHEN UPDATING MU VIA THE METROPOLIS-HASTING UPDATE. PREVIOUS VERSIONS DID NO INDEX MUHAT, SO ONLY MUHAT[0] WAS USED IN THE PROPOSAL DISTRIBUTION. THANKS TO AMY BENDER FOR POINTING THIS OUT. (B. KELLY, DEC 2011)(See astrolib/pro/linmix_err.pro)
LINTERP
[Previous Routine] [Next Routine] [List of Routines]NAME: LINTERP PURPOSE: Linearly interpolate tabulated 1-d data from one grid to a new one. EXPLANATION: The results of LINTERP are numerically equivalent to the IDL intrinsic INTERPOL() function, but note the following: (1) LINTERP is a procedure rather than a function (2) INTERPOL() extrapolates beyond the end points whereas LINTERP truncates to the endpoints (or uses the MISSING keyword) (3) LINTERP (unlike INTERPOL) uses the intrinsic INTERPOLATE function and thus may have a speed advantage (4) LINTERP always converts the new grid vector to floating point (because INTERPOLATE does this) whereas INTERPOL() will keep double precision if supplied. Use QUADTERP for quadratic interpolation. CALLING SEQUENCE: LINTERP, Xtab, Ytab, Xint, Yint, [MISSING =, /NoInterp ] INPUT PARAMETERS: Xtab - Vector containing the current independent variable grid. Must be monotonic increasing or decreasing Ytab - Vector containing the current dependent variable values at the XTAB grid points. Xint - Scalar or vector containing the new independent variable grid points for which interpolated value(s) of the dependent variable are sought. Note that -- due to a limitation of the intrinsic INTERPOLATE() function -- Xint is always converted to floating point internally. OUTPUT PARAMETERS: Yint - Scalar or vector with the interpolated value(s) of the dependent variable at the XINT grid points. YINT is double precision if XTAB or YTAB are double, otherwise YINT is REAL*4 OPTIONAL INPUT KEYWORD: MISSING - Scalar specifying YINT value(s) to be assigned, when Xint value(s) are outside of the range of Xtab. Default is to truncate the out of range YINT value(s) to the nearest value of YTAB. See the help for the INTERPOLATE function. /NoINTERP - If supplied then LINTERP returns the YTAB value(s) associated with the closest XTAB value(s)rather than interpolating. EXAMPLE: To linearly interpolate from a spectrum wavelength-flux pair Wave, Flux to another wavelength grid defined as: WGrid = [1540., 1541., 1542., 1543., 1544, 1545.] IDL> LINTERP, Wave, Flux, WGrid, FGrid FGRID will be a 6 element vector containing the values of Flux linearly interpolated onto the WGrid wavelength scale PROCEDURE: Uses TABINV to calculate the effective index of the values in Xint in the table Xtab. The resulting index is used with the intrinsic INTERPOLATE function to find the corresponding Yint value in Ytab. Unless the MISSING keyword is supplied, out of range Yint values are truncated to the nearest value of Ytab. PROCEDURES CALLED: TABINV, ZPARCHECK MODIFICATION HISTORY: Adapted from the IUE RDAF, W. Landsman October, 1988 Modified to use the new INTERPOLATE function June, 1992 Modified to always return REAL*4 October, 1992 Added MISSING keyword August, 1993 Converted to IDL V5.0 W. Landsman September 1997 Added NoInterp keyword W. Landsman July 1999 Work for unsigned, 64 bit integers W. Landsman October 2001(See astrolib/pro/linterp.pro)
LIST_WITH_PATH
[Previous Routine] [Next Routine] [List of Routines]NAME: LIST_WITH_PATH PURPOSE: Search for files in a specified directory path. EXPLANATION: Lists files in a set of default paths, similar to using FILE_SEARCH, except that a list of paths to be searched can be given. CALLING SEQUENCE: Result = LIST_WITH_PATH( FILENAME, PATHS ) INPUTS: FILENAME = Name of file to be searched for. It may contain wildcard characters, e.g. "*.dat". PATHS = One or more default paths to use in the search in case FILENAME does not contain a path itself. 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. The current directory is always searched first, unless the keyword NOCURRENT is set. A leading $ can be used in any path to signal that what follows is an environmental variable, but the $ is not necessary. Environmental variables can themselves contain multiple paths. OUTPUTS: The result of the function is a list of filenames. EXAMPLE: FILENAME = '' READ, 'File to open: ', FILENAME FILE = LIST_WITH_PATH( FILENAME, 'SERTS_DATA', '.fix' ) IF FILE NE '' THEN ... PROCEDURE CALLS: BREAK_PATH, CONCAT_DIR() Category : Utilities, Operating_system REVISION HISTORY: Version 1, William Thompson, GSFC, 3 November 1994 Documentation modified Wayne Landsman HSTX November 1994 Assume since V5.5, vector call to FILE_SEARCH() W. Landsman Sep 2006 Restore pre-Sep 2006 behavior of not searching subdirectories W.Landsman. Feb 2007(See astrolib/pro/list_with_path.pro)
LSF_ROTATE:
[Previous Routine] [Next Routine] [List of Routines]NAME: LSF_ROTATE: PURPOSE: Create a 1-d convolution kernel to broaden a spectrum from a rotating star EXPLANATION: Can be used to derive the broadening effect (line spread function; LSF) due to rotation on a synthetic stellar spectrum. Assumes constant limb darkening across the disk. CALLING SEQUENCE lsf = LSF_ROTATE(deltav, vsini, EPSILON=, VELGRID=) INPUT PARAMETERS: deltaV - numeric scalar giving the step increment (in km/s) in the output rotation kernel. Vsini - the rotational velocity projected along the line of sight (km/s) OUTPUT PARAMETERS: LSF - The convolution kernel vector for the specified rotational velocity. The number of points in LSF will be always be odd (the kernel is symmetric) and equal to either ceil(2*Vsini/deltav) or ceil(2*Vsini/deltav) +1 (whichever number is odd). LSF will always be of type FLOAT. To actually compute the broadening. the spectrum should be convolved with the rotational LSF. OPTIONAL INPUT PARAMETERS: Epsilon - numeric scalar giving the limb-darkening coefficient, default = 0.6 which is typical for photospheric lines. The specific intensity I at any angle theta from the specific intensity Icen at the center of the disk is given by: I = Icen*(1-epsilon*(1-cos(theta)) OPTIONAL OUTPUT PARAMETER: Velgrid - Vector with the same number of elements as LSF EXAMPLE: (1) Plot the LSF for a star rotating at 90 km/s in both velocity space and for a central wavelength of 4300 A. Compute the LSF every 3 km/s IDL> lsf = lsf_rotate(3,90,velgrid=vel) ;LSF will contain 61 pts IDL> plot,vel,lsf ;Plot the LSF in velocity space IDL> wgrid = 4300*(1+vel/3e5) ;Speed of light = 3e5 km/s IDL> oplot,wgrid,lsf ;Plot in wavelength space NOTES: Adapted from rotin3.f in the SYNSPEC software of Hubeny & Lanz .http://nova.astro.umd.edu/index.html Also see Eq. 17.12 in "The Observation and Analysis of Stellar Photospheres" by D. Gray (1992) REVISION HISTORY: Written, W. Landsman November 2001(See astrolib/pro/lsf_rotate.pro)
LUMDIST
[Previous Routine] [Next Routine] [List of Routines]NAME: LUMDIST PURPOSE: Calculate luminosity distance (in Mpc) of an object given its redshift EXPLANATION: The luminosity distance in the Friedmann-Robertson-Walker model is taken from Caroll, Press, and Turner (1992, ARAA, 30, 499), p. 511 Uses a closed form (Mattig equation) to compute the distance when the cosmological constant is zero. Otherwise integrates the function using QSIMP. CALLING SEQUENCE: result = lumdist(z, [H0 = , k = , Omega_M =, Lambda0 = , q0 = ,/SILENT]) INPUTS: z = redshift, positive scalar or vector OPTIONAL KEYWORD INPUTS: /SILENT - If set, the program will not display adopted cosmological parameters at the terminal. H0: Hubble parameter in km/s/Mpc, default is 70 No more than two of the following four parameters should be specified. None of them need be specified -- the adopted defaults are given. k - curvature constant, normalized to the closure density. Default is 0, indicating a flat universe Omega_m - Matter density, normalized to the closure density, default is 0.3. Must be non-negative Lambda0 - Cosmological constant, normalized to the closure density, default is 0.7 q0 - Deceleration parameter, numeric scalar = -R*(R'')/(R')^2, default is -0.55 OUTPUTS: The result of the function is the luminosity distance (in Mpc) for each input value of z. EXAMPLE: (1) Plot the distance of a galaxy in Mpc as a function of redshift out to z = 5.0, assuming the default cosmology (Omega_m=0.3, Lambda = 0.7, H0 = 70 km/s/Mpc) IDL> z = findgen(50)/10. IDL> plot,z,lumdist(z),xtit='z',ytit='Distance (Mpc)' Now overplot the relation for zero cosmological constant and Omega_m=0.3 IDL> oplot,z,lumdist(z,lambda=0,omega=0.3),linestyle=1 COMMENTS: (1) Integrates using the IDL Astronomy Version procedure QSIMP. (The intrinsic IDL QSIMP function is not called because of its ridiculous restriction that only scalar arguments can be passed to the integrating function.) (2) Can fail to converge at high redshift for closed universes with non-zero lambda. This can presumably be fixed by replacing QSIMP with an integrator that can handle a singularity PROCEDURES CALLED: COSMO_PARAM, QSIMP REVISION HISTORY: Written W. Landsman Raytheon ITSS April 2000 Avoid integer overflow for more than 32767 redshifts July 2001 Use double precision J. Moustakas/W. Landsman April 2008(See astrolib/pro/lumdist.pro)
MAG2FLUX
[Previous Routine] [Next Routine] [List of Routines]NAME: MAG2FLUX PURPOSE: Convert from magnitudes to flux (ergs/s/cm^2/A). EXPLANATION: Use FLUX2MAG() for the opposite direction. CALLING SEQUENCE: flux = mag2flux( mag, [ zero_pt, ABwave = ] ) INPUTS: mag - scalar or vector of magnitudes OPTIONAL INPUT: zero_pt - scalar giving the zero point level of the magnitude. If not supplied then zero_pt = 21.1 (Code et al. 1976) Ignored if the ABwave keyword is set. OPTIONAL KEYWORD INPUT: ABwave - wavelength scalar or vector in Angstroms. If supplied, then the input vector, mag, is assumed to contain Oke AB magnitudes (Oke & Gunn 1983, ApJ, 266, 713) OUTPUT: flux - scalar or vector flux vector, in erg cm-2 s-1 A-1 If the ABwave keyword is set, then the flux is given by f = 10^(-0.4*(mag +2.406 + 4*alog10(ABwave))) Otherwise the flux is given by f = 10^(-0.4*(mag + zero_pt)) EXAMPLE: Suppose one is given vectors of wavelengths and AB magnitudes, w (in Angstroms) and mag. Plot the spectrum in erg cm-2 s-1 A-1 IDL> plot, w, mag2flux(mag,ABwave = w) REVISION HISTORY: Written J. Hill STX Co. 1988 Converted to IDL V5.0 W. Landsman September 1997 Added ABwave keyword, W. Landsman September 1998(See astrolib/pro/mag2flux.pro)
MAG2GEO()
[Previous Routine] [Next Routine] [List of Routines]NAME: MAG2GEO() PURPOSE: Convert from geomagnetic to geographic coordinates EXPLANATION: Converts from GEOMAGNETIC (latitude,longitude) to GEOGRAPHIC (latitude, longitude). (altitude remains the same) CALLING SEQUENCE: gcoord=mag2geo(mcoord) INPUT: mcoord = a 2-element array of magnetic [latitude,longitude], or an array [2,n] of n such coordinates. KEYWORD INPUTS: None OUTPUT: a 2-element array of geographic [latitude,longitude], or an array [2,n] of n such coordinates COMMON BLOCKS: None EXAMPLES: IDL> gcoord=mag2geo([90,0]) ; coordinates of magnetic south pole IDL> print,gcoord 79.300000 -71.409990 MODIFICATION HISTORY: Written by Pascal Saint-Hilaire (Saint-Hilaire@astro.phys.ethz.ch), May 2002(See astrolib/pro/mag2geo.pro)
MAKE_2D
[Previous Routine] [Next Routine] [List of Routines]NAME: MAKE_2D PURPOSE: Change from 1-d indexing to 2-d indexing EXPLANATION: Convert an N element X vector, and an M element Y vector, into N x M arrays giving all possible combination of X and Y pairs. Useful for obtaining the X and Y positions of each element of a regular grid. CALLING SEQUENCE: MAKE_2D, X, Y, [ XX, YY ] INPUTS: X - N element vector of X positions Y - M element vector of Y positions OUTPUTS: XX - N x M element array giving the X position at each pixel YY - N x M element array giving the Y position of each pixel If only 2 parameters are supplied then X and Y will be updated to contain the output arrays EXAMPLE: To obtain the X and Y position of each element of a 30 x 15 array IDL> x = indgen(30) & y = indgen(15) IDL> make_2d, x, y REVISION HISTORY: Written, Wayne Landsman ST Systems Co. May, 1988 Added /NOZERO keyword W. Landsman Mar, 1991 Converted to IDL V5.0 W. Landsman September 1997 Improved speed P. Broos July 2000(See astrolib/pro/make_2d.pro)
MAKE_ASTR
[Previous Routine] [Next Routine] [List of Routines]NAME: MAKE_ASTR PURPOSE: Build an astrometry structure from input parameter values EXPLANATION: This structure can be subsequently placed in a FITS header with PUTAST CALLING SEQUENCE: MAKE_ASTR, astr, CD = , DELT =, CRPIX =, CRVAL =, CTYPE =, LATPOLE = , LONGPOLE =, PV2_1 = PV2_2 = , PV2_3 = OUTPUT PARAMETER: ASTR - Anonymous structure containing astrometry info. See the documentation for EXTAST for descriptions of the individual tags REQUIRED INPUT KEYWORDS CRPIX - 2 element vector giving X and Y coordinates of reference pixel (def = NAXIS/2). VALUES MUST BE IN FITS CONVENTION (first pixel is [1,1]) AND NOT IDL CONVENTION (first pixel is [0,0]). CRVAL - 2 element double precision vector giving R.A. and DEC of reference pixel in DEGREES OPTIONAL INPUT KEYWORDS CD - 2 x 2 array containing the astrometry parameters CD1_1 CD1_2 in DEGREES/PIXEL CD2_1 CD2_2 DELT - 2 element vector giving physical increment at reference pixel in DEGREES/PIXEL default = [-1.0D, 1.0D]/3600. (1 arcsec/pixel) CTYPE - 2 element string vector giving projection types, default ['RA---TAN','DEC--TAN'] LATPOLE - Scalar latitude of the north pole, default = 0 LONGPOLE - scalar longitude of north pole, default = 180 Note that the default value of 180 is valid only for zenithal projections; it should be set to PV2_1 for conic projections, and zero for other projections. PV2 - Vector of projection parameters. Not required for some projections (e.g. TAN) and optional for others (e.g. SIN). Usually a 2 element vector, but may contain up to 21 elements for the Zenithal Polynomial (ZPN) projection. Corresponds to the keywords PV2_1, PV2_2... Defaults to 0.0 NOTES: (1) An anonymous structure is created to avoid structure definition conflicts. This is needed because some projection systems require additional dimensions (i.e. spherical cube projections require a specification of the cube face). (2) The name of the keyword for the CDELT parameter is DELT because the IDL keyword CDELT would conflict with the CD keyword (3) The astrometry structure definition was slightly modified in July 2003; all angles are now double precision, and the LATPOLE tag was added. In April 2007 the CRPIX tag was also changed to double precision. REVISION HISTORY: Written by W. Landsman Mar. 1994 Added LATPOLE, all angles double precision W. Landsman July 2003 Use PV2 keyword rather than PROJP1, PROJP2 W. Landsman May 2004 Make .CRPIX tag double precision, change CDELT default to 1"/pixel W. Landsman April 2007 Default plate scale is now 1"/pixel (not 1 deg/pix) WL Oct. 2010 Oct 2010 change should only apply when CD matrix not given M. Cushing/W.L. Aug 2011(See astrolib/pro/make_astr.pro)
MATCH
[Previous Routine] [Next Routine] [List of Routines]NAME: MATCH PURPOSE: Routine to match values in two vectors. CALLING SEQUENCE: match, a, b, suba, subb, [ COUNT =, /SORT, EPSILON = ] INPUTS: a,b - two vectors to match elements, numeric or string data types OUTPUTS: suba - subscripts of elements in vector a with a match in vector b subb - subscripts of the positions of the elements in vector b with matchs in vector a. suba and subb are ordered such that a[suba] equals b[subb] OPTIONAL INPUT KEYWORD: /SORT - By default, MATCH uses two different algorithm: (1) the /REVERSE_INDICES keyword to HISTOGRAM is used for integer data, while (2) a sorting algorithm is used for non-integer data. The histogram algorithm is usually faster, except when the input vectors are sparse and contain very large numbers, possibly causing memory problems. Use the /SORT keyword to always use the sort algorithm. epsilon - if values are within epsilon, they are considered equal. Used only only for non-integer matching. Note that input vectors should be unique to within epsilon to provide one-to-one mapping.. Default=0. OPTIONAL KEYWORD OUTPUT: COUNT - set to the number of matches, integer scalar SIDE EFFECTS: The obsolete system variable !ERR is set to the number of matches; however, the use !ERR is deprecated in favor of the COUNT keyword RESTRICTIONS: The vectors a and b should not have duplicate values within them. You can use rem_dup function to remove duplicate values in a vector EXAMPLE: If a = [3,5,7,9,11] & b = [5,6,7,8,9,10] then IDL> match, a, b, suba, subb, COUNT = count will give suba = [1,2,3], subb = [0,2,4], COUNT = 3 and a[suba] = b[subb] = [5,7,9] METHOD: For non-integer data types, the two input vectors are combined and sorted and the consecutive equal elements are identified. For integer data types, the /REVERSE_INDICES keyword to HISTOGRAM of each array is used to identify where the two arrays have elements in common. HISTORY: D. Lindler Mar. 1986. Fixed "indgen" call for very large arrays W. Landsman Sep 1991 Added COUNT keyword W. Landsman Sep. 1992 Fixed case where single element array supplied W. Landsman Aug 95 Use a HISTOGRAM algorithm for integer vector inputs for improved performance W. Landsman March 2000 Work again for strings W. Landsman April 2000 Use size(/type) W. Landsman December 2002 Work for scalar integer input W. Landsman June 2003 Assume since V5.4, use COMPLEMENT to WHERE() W. Landsman Apr 2006 Added epsilon keyword Kim Tolbert March 14, 2008(See astrolib/pro/match.pro)
MATCH2
[Previous Routine] [Next Routine] [List of Routines]NAME: MATCH2 PURPOSE: Routine to cross-match values in two vectors (including non-matches) EXPLANATION: This procedure *appears* similar to MATCH of the IDL astronomy library. However, this routine is quite different in that it reports an index value for each element of the input arrays. In other words, while MATCH reports the *existence* of matching elements in each array, MATCH2 reports explicitly *which* elements match. Furthermore, while MATCH reports only unique matching elements, MATCH2 will always report a cross-match for every element in each array, even if it is a repeat. In cases where no match was found, an index of -1 is reported. CALLING SEQUENCE: match2, a, b, suba, subb INPUTS: a,b - two vectors to match elements, numeric or string data types OUTPUTS: suba - vector with same number of elements as A, such that A EQ B[SUBA], except non-matches which are indicated by SUBA EQ -1 subb - vector with same number of elements as B, such that B EQ A[SUBB], except non-matches which are indicated by SUBB EQ -1 RESTRICTIONS: The vectors A and B are allowed to have duplicates in them, but for matching purposes, only the first one found will be reported. EXAMPLE: A = [0,7,14,23,24,30] B = [7,8,14,25,14] IDL> match2, a, b, suba, subb --> suba = [ -1 , 0, 4, -1, -1, -1 ] (indicates that A[1] matches B[1] and A[3] matches B[2]) --> subb = [ 1 , -1, 2, -1, 2 ] (indicates that B[1] matches A[1] and B[2] matches A[3]) Compare to the results of the original MATCH procedure, IDL> match, a, b, suba, subb --> suba = [ 1, 3] (indicates that A[1] and A[3] match elements in B, but not which ones) --> subb = [ 1, 2] (indicates that B[1] and B[2] match elements in A, but not which ones) MODIFICATION HISTORY Derived from the IDL Astronomy Library MATCH, 14 Feb 2007 Updated documentation, 17 Jul 2007 More updated documentation (example), 03 Sep 2007(See astrolib/pro/match2.pro)
MAX_ENTROPY
[Previous Routine] [Next Routine] [List of Routines]NAME: MAX_ENTROPY PURPOSE: Deconvolution of data by Maximum Entropy analysis, given the PSF EXPLANATION: Deconvolution of data by Maximum Entropy analysis, given the instrument point spread response function (spatially invariant psf). Data can be an observed image or spectrum, result is always positive. Default is convolutions using FFT (faster when image size = power of 2). CALLING SEQUENCE: for i=1,Niter do begin Max_Entropy, image_data, psf, image_deconv, multipliers, FT_PSF=psf_ft INPUTS: data = observed image or spectrum, should be mostly positive, with mean sky (background) near zero. psf = Point Spread Function of instrument (response to point source, must sum to unity). deconv = result of previous call to Max_Entropy, multipliers = the Lagrange multipliers of max.entropy theory (on first call, set = 0, giving flat first result). OUTPUTS: deconv = deconvolution result of one more iteration by Max_Entropy. multipliers = the Lagrange multipliers saved for next iteration. OPTIONAL INPUT KEYWORDS: FT_PSF = passes (out/in) the Fourier transform of the PSF, so that it can be reused for the next time procedure is called, /NO_FT overrides the use of FFT, using the IDL function convol() instead. /LINEAR switches to Linear convergence mode, much slower than the default Logarithmic convergence mode. LOGMIN = minimum value constraint for taking Logarithms (default=1.e-9). EXTERNAL CALLS: function convolve( image, psf ) for convolutions using FFT or otherwise. METHOD: Iteration with PSF to maximize entropy of solution image with constraint that the solution convolved with PSF fits data image. Based on paper by Hollis, Dorband, Yusef-Zadeh, Ap.J. Feb.1992, which refers to Agmon, Alhassid, Levine, J.Comp.Phys. 1979. A more elaborate image deconvolution program using maximum entropy is available at http://sohowww.nascom.nasa.gov/solarsoft/gen/idl/image/image_deconvolve.pro HISTORY: written by Frank Varosi at NASA/GSFC, 1992. Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/max_entropy.pro)
MAX_LIKELIHOOD
[Previous Routine] [Next Routine] [List of Routines]NAME: MAX_LIKELIHOOD PURPOSE: Maximum likelihood deconvolution of an image or a spectrum. EXPLANATION: Deconvolution of an observed image (or spectrum) given the instrument point spread response function (spatially invariant psf). Performs iteration based on the Maximum Likelihood solution for the restoration of a blurred image (or spectrum) with additive noise. Maximum Likelihood formulation can assume Poisson noise statistics or Gaussian additive noise, yielding two types of iteration. CALLING SEQUENCE: for i=1,Niter do Max_Likelihood, data, psf, deconv, FT_PSF=psf_ft INPUTS PARAMETERS: data = observed image or spectrum, should be mostly positive, with mean sky (background) near zero. psf = Point Spread Function of the observing instrument, (response to a point source, must sum to unity). INPUT/OUTPUT PARAMETERS: deconv = as input: the result of previous call to Max_Likelihood, (initial guess on first call, default = average of data), as output: result of one more iteration by Max_Likelihood. Re_conv = (optional) the current deconv image reconvolved with PSF for use in next iteration and to check convergence. OPTIONAL INPUT KEYWORDS: /GAUSSIAN causes max-likelihood iteration for Gaussian additive noise to be used, otherwise the default is Poisson statistics. FT_PSF = passes (out/in) the Fourier transform of the PSF, so that it can be reused for the next time procedure is called, /NO_FT overrides the use of FFT, using the IDL function convol() instead. POSITIVITY_EPS = value of epsilon passed to function positivity, default = -1 which means no action (identity). UNDERFLOW_ZERO = cutoff to consider as zero, if numbers less than this. EXTERNAL CALLS: function convolve( image, psf ) for convolutions using FFT or otherwise. function positivity( image, EPS= ) to make image positive. METHOD: Maximum Likelihood solution is a fixed point of an iterative eq. (derived by setting partial derivatives of Log(Likelihood) to zero). Poisson noise case was derived by Richardson(1972) & Lucy(1974). Gaussian noise case is similar with subtraction instead of division. NOTES: WARNING: The Poisson case may not conserve flux for an odd image size. This behavior is being investigated. HISTORY: written: Frank Varosi at NASA/GSFC, 1992. F.V. 1993, added optional arg. Re_conv (to avoid doing it twice). Converted to IDL V5.0 W. Landsman September 1997 Use COMPLEMENT keyword to WHERE() W. Landsman Jan 2008(See astrolib/pro/max_likelihood.pro)
MEANCLIP
[Previous Routine] [Next Routine] [List of Routines]NAME: MEANCLIP PURPOSE: Computes an iteratively sigma-clipped mean on a data set EXPLANATION: Clipping is done about median, but mean is returned. Called by SKYADJ_CUBE CATEGORY: Statistics CALLING SEQUENCE: MEANCLIP, Data, Mean, [ Sigma, SUBS = CLIPSIG=, MAXITER=, CONVERGE_NUM=, /VERBOSE, /DOUBLE ] INPUT POSITIONAL PARAMETERS: Data: Input data, any numeric array OUTPUT POSITIONAL PARAMETERS: Mean: N-sigma clipped mean. Sigma: Standard deviation of remaining pixels. INPUT KEYWORD PARAMETERS: CLIPSIG: Number of sigma at which to clip. Default=3 MAXITER: Ceiling on number of clipping iterations. Default=5 CONVERGE_NUM: If the proportion of rejected pixels is less than this fraction, the iterations stop. Default=0.02, i.e., iteration stops if fewer than 2% of pixels excluded. /VERBOSE: Set this flag to get messages. /DOUBLE - if set then perform all computations in double precision. Otherwise double precision is used only if the input data is double OUTPUT KEYWORD PARAMETER: SUBS: Subscript array for pixels finally used. MODIFICATION HISTORY: Written by: RSH, RITSS, 21 Oct 98 20 Jan 99 - Added SUBS, fixed misplaced paren on float call, improved doc. RSH Nov 2005 Added /DOUBLE keyword, check if all pixels are removed by clipping W. Landsman(See astrolib/pro/meanclip.pro)
MEDARR
[Previous Routine] [Next Routine] [List of Routines]NAME: MEDARR PURPOSE: Compute the median at each pixel across a set of 2-d images EXPLANATION: Each pixel in the output array contains the median of the corresponding pixels in the input arrays. Useful, for example to combine a stack of CCD images, while removing cosmic ray hits. This routine became partially obsolete in V5.6 with the introduction of the DIMENSION keyword to the intrinsic MEDIAN() function. However, it is still useful if a input mask is needed (though it is much faster to set invalid pixels to NaN values.) CALLING SEQUENCE: MEDARR, inarr, outarr, [ mask, output_mask ] INPUTS: inarr -- A three dimensional array containing the input arrays to combine together. Each of the input arrays must be two dimensional and must have the same dimensions. These arrays should then be stacked together into a single 3-D array, creating INARR. OPTIONAL INPUT: mask -- Same structure as inarr, byte array with 1b where pixels are to be included, 0b where they are to be excluded. For floating point images, it is much faster to set masked pixels in inarr equal to !VALUES.F_NAN (see below), rather than use the mask parameter. OUTPUTS: outarr -- The output array. It will have dimensions equal to the first two dimensions of the input array. OPTIONAL OUPUT: output_mask -- Same structure as outarr, byte array with 1b pixels are valid, 0b where all the input pixels have been masked out. RESTRICTIONS: This procedure was *SLOW* when using the Mask parameter because it has to loop over each pixel of the image. EXAMPLE: Suppose one wants to combine three floating point 1024 x 1024 bias frames which have been read into the IDL variables im1,im2,im3 IDL> bigim = fltarr(1024,1024,3) ;Create big array to hold images IDL> bigim(0,0,0) = im1 & bigim(0,0,1) = im2 & bigim(0,0,2) = im2 IDL> medarr, bigim, avgbias The variable avgbias will be the desired 1024x 1024 float image. PROCEDURE: If the MASK parameter is not set, then MEDARR is just a wrapper for MEDIAN(/EVEN, dimension = 3). If the MASK parameter is set, a scalar median function over the third dimension is looped over each pixel of the first two dimensions. The /EVEN keyword is used with MEDIAN (which averages the two middle values), since this avoids biasing the output for an even number of images. Any values set to NAN (not a number) are ignored when computing the median. If all values for a pixel location are NAN, then the median is also returned as NAN. MODIFICATION HISTORY: Written by Michael R. Greason, STX, 12 June 1990. Don't use MEDIAN function for even number of images. W. Landsman Sep 1996 Mask added. RS Hill, HSTX, 13 Mar. 1997 Converted to IDL V5.0 W. Landsman September 1997 Use /EVEN keyword to MEDIAN W. Landsman September 1997 Rearranged code for faster execution W. Landsman January 1998 Faster execution for odd number of images W. Landsman July 2000 V5.4 fix for change in SIZE() definition of undefined variable W. Landsman/E. Young May 2001 Use MEDIAN(/DIMEN) for V5.6 or later W. Landsman November 2002 Use keyword_set() instead of ARG_present() to test for presence of mask parameter D. Hanish/W. Landsman June 2003 Assume since V5.6 W. Landsman Feb 2004(See astrolib/pro/medarr.pro)
MEDSMOOTH
[Previous Routine] [Next Routine] [List of Routines]NAME: MEDSMOOTH PURPOSE: Median smoothing of a vector, including points near its ends. CALLING SEQUENCE: SMOOTHED = MEDSMOOTH( VECTOR, WINDOW_WIDTH ) INPUTS: VECTOR = The (1-d numeric) vector to be smoothed WINDOW = Odd integer giving the full width of the window over which the median is determined for each point. (If WINDOW is specified as an even number, then the effect is the same as using WINDOW+1) OUTPUT: Function returns the smoothed vector PROCEDURE: Each point is replaced by the median of the nearest WINDOW of points. The width of the window shrinks towards the ends of the vector, so that only the first and last points are not filtered. These points are replaced by forecasting from smoothed interior points. EXAMPLE: Create a vector with isolated high points near its ends IDL> a = randomn(seed,40) & a[1] = 10 & a[38] = 10 Now do median smoothing with a 7 point window IDL> b = medsmooth(a,7) Note that, unlike MEDIAN(), that MEDSMOOTH will remove the isolated high points near the ends. REVISION HISTORY: Written, H. Freudenreich, STX, 12/89 H.Freudenreich, 8/90: took care of end-points by shrinking window. Speed up using vector median when possible W. Landsman February 2002(See astrolib/pro/medsmooth.pro)
MINF_BRACKET
[Previous Routine] [Next Routine] [List of Routines]NAME: MINF_BRACKET PURPOSE: Bracket a local minimum of a 1-D function with 3 points, EXPLANATION: Brackets a local minimum of a 1-d function with 3 points, thus ensuring that a minimum exists somewhere in the interval. This routine assumes that the function has a minimum somewhere.... Routine can also be applied to a scalar function of many variables, for such case the local minimum in a specified direction is bracketed, This routine is called by minF_conj_grad, to bracket minimum in the direction of the conjugate gradient of function of many variables CALLING EXAMPLE: xa=0 & xb=1 minF_bracket, xa,xb,xc, fa,fb,fc, FUNC_NAME="name" ;for 1-D func. or: minF_bracket, xa,xb,xc, fa,fb,fc, FUNC="name", $ POINT=[0,1,1], $ DIRECTION=[2,1,1] ;for 3-D func. INPUTS: xa = scalar, guess for point bracketing location of minimum. xb = scalar, second guess for point bracketing location of minimum. KEYWORDS: FUNC_NAME = function name (string) Calling mechanism should be: F = func_name( px ) where: px = scalar or vector of independent variables, input. F = scalar value of function at px. POINT_NDIM = when working with function of N variables, use this keyword to specify the starting point in N-dim space. Default = 0, which assumes function is 1-D. DIRECTION = when working with function of N variables, use this keyword to specify the direction in N-dim space along which to bracket the local minimum, (default=1 for 1-D). (xa,xb,xc) are then relative distances from POINT_NDIM. OUTPUTS: xa,xb,xc = scalars, 3 points which bracket location of minimum, that is, f(xb) < f(xa) and f(xb) < f(xc), so minimum exists. When working with function of N variables (xa,xb,xc) are then relative distances from POINT_NDIM, in the direction specified by keyword DIRECTION, with scale factor given by magnitude of DIRECTION. OPTIONAL OUTPUT: fa,fb,fc = value of function at 3 points which bracket the minimum, again note that fb < fa and fb < fc if minimum exists. PROCEDURE: algorithm from Numerical Recipes (by Press, et al.), sec.10.1 (p.281). MODIFICATION HISTORY: Written, Frank Varosi NASA/GSFC 1992. Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/minf_bracket.pro)
MINF_CONJ_GRAD
[Previous Routine] [Next Routine] [List of Routines]NAME: MINF_CONJ_GRAD PURPOSE: Find the local minimum of a scalar function using conjugate gradient EXPLANATION: Find the local minimum of a scalar function of several variables using the Conjugate Gradient method (Fletcher-Reeves-Polak-Ribiere algorithm). Function may be anything with computable partial derivatives. Each call to minF_conj_grad performs one iteration of algorithm, and returns an N-dim point closer to the local minimum of function. CALLING EXAMPLE: p_min = replicate( 1, N_dim ) minF_conj_grad, p_min, f_min, conv_factor, FUNC_NAME="name",/INITIALIZE while (conv_factor GT 0) do begin minF_conj_grad, p_min, f_min, conv_factor, FUNC_NAME="name" endwhile INPUTS: p_min = vector of independent variables, location of minimum point obtained from previous call to minF_conj_grad, (or first guess). KEYWORDS: FUNC_NAME = function name (string) Calling mechanism should be: F = func_name( px, gradient ) where: F = scalar value of function at px. px = vector of independent variables, input. gradient = vector of partial derivatives of the function with respect to independent variables, evaluated at px. This is an optional output parameter: gradient should not be calculated if parameter is not supplied in call (Unless you want to waste some time). /INIT must be specified on first call (whenever p_min is a guess), to initialize the iteration scheme of algorithm. /USE_DERIV causes the directional derivative of function to be used in the 1-D minimization part of algorithm (default is not to use directional derivative). TOLERANCE = desired accuracy of minimum location, default=sqrt(1.e-7). /QUADRATIC runs simpler version which works only for quadratic function. OUTPUTS: p_min = vector giving improved solution for location of minimum point. f_min = value of function at p_min. conv_factor = gives the current rate of convergence (change in value), iteration should be stopped when rate gets near zero. EXTERNAL CALLS: pro minF_bracket, to find 3 points which bracket the minimum in 1-D. pro minF_parabolic, to find minimum point in 1-D. pro minF_parabol_D, to find minimum point in 1-D, using derivatives. COMMON BLOCKS: common minf_conj_grad, grad_conj, grad_save, gs_norm (to keep conjugate gradient, gradient and norm from previous iteration) PROCEDURE: Algorithm adapted from Numerical Recipes, sec.10.6 (p.305). Conjugate gradient is computed from gradient, which then gives the best direction (in N-dim space) in which to proceed to find the minimum point. The function is then minimized along this direction of conjugate gradient (a 1-D minimization). The algorithm is repeated starting at the new point by calling again. MODIFICATION HISTORY: Written, Frank Varosi NASA/GSFC 1992. Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/minf_conj_grad.pro)
MINF_PARABOLIC
[Previous Routine] [Next Routine] [List of Routines]NAME: MINF_PARABOLIC PURPOSE: Minimize a function using Brent's method with parabolic interpolation EXPLANATION: Find a local minimum of a 1-D function up to specified tolerance. This routine assumes that the function has a minimum nearby. (recommend first calling minF_bracket, xa,xb,xc, to bracket minimum). Routine can also be applied to a scalar function of many variables, for such case the local minimum in a specified direction is found, This routine is called by minF_conj_grad, to locate minimum in the direction of the conjugate gradient of function of many variables. CALLING EXAMPLES: minF_parabolic, xa,xb,xc, xmin, fmin, FUNC_NAME="name" ;for 1-D func. or: minF_parabolic, xa,xb,xc, xmin, fmin, FUNC="name", $ POINT=[0,1,1], $ DIRECTION=[2,1,1] ;for 3-D func. INPUTS: xa,xb,xc = scalars, 3 points which bracket location of minimum, that is, f(xb) < f(xa) and f(xb) < f(xc), so minimum exists. When working with function of N variables (xa,xb,xc) are then relative distances from POINT_NDIM, in the direction specified by keyword DIRECTION, with scale factor given by magnitude of DIRECTION. INPUT KEYWORDS: FUNC_NAME = function name (string) Calling mechanism should be: F = func_name( px ) where: px = scalar or vector of independent variables, input. F = scalar value of function at px. POINT_NDIM = when working with function of N variables, use this keyword to specify the starting point in N-dim space. Default = 0, which assumes function is 1-D. DIRECTION = when working with function of N variables, use this keyword to specify the direction in N-dim space along which to bracket the local minimum, (default=1 for 1-D). (xa, xb, xc, x_min are then relative distances from POINT_NDIM) MAX_ITER = maximum allowed number iterations, default=100. TOLERANCE = desired accuracy of minimum location, default=sqrt(1.e-7). OUTPUTS: xmin = estimated location of minimum. When working with function of N variables, xmin is the relative distance from POINT_NDIM, in the direction specified by keyword DIRECTION, with scale factor given by magnitude of DIRECTION, so that min. Loc. Pmin = Point_Ndim + xmin * Direction. fmin = value of function at xmin (or Pmin). PROCEDURE: Brent's method to minimize a function by using parabolic interpolation. Based on function BRENT in Numerical Recipes in FORTRAN (Press et al. 1992), sec.10.2 (p. 397). MODIFICATION HISTORY: Written, Frank Varosi NASA/GSFC 1992. Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/minf_parabolic.pro)
MINF_PARABOL_D
[Previous Routine] [Next Routine] [List of Routines]NAME: MINF_PARABOL_D PURPOSE: Minimize a function using a modified Brent's method with derivatives EXPLANATION: Based on the procedure DBRENT in Numerical Recipes by Press et al. Finds a local minimum of a 1-D function up to specified tolerance, using the first derivative of function in the algorithm. This routine assumes that the function has a minimum nearby. (recommend first calling minF_bracket, xa,xb,xc, to bracket minimum). Routine can also be applied to a scalar function of many variables, for such case the local minimum in a specified direction is found, This routine is called by minF_conj_grad, to locate minimum in the direction of the conjugate gradient of function of many variables. CALLING EXAMPLES: minF_parabol_D, xa,xb,xc, xmin, fmin, FUNC_NAME="name" ;for 1-D func. or: minF_parabol_D, xa,xb,xc, xmin, fmin, FUNC="name", $ POINT=[0,1,1], $ DIRECTION=[2,1,1] ;for 3-D func. INPUTS: xa,xb,xc = scalars, 3 points which bracket location of minimum, that is, f(xb) < f(xa) and f(xb) < f(xc), so minimum exists. When working with function of N variables (xa,xb,xc) are then relative distances from POINT_NDIM, in the direction specified by keyword DIRECTION, with scale factor given by magnitude of DIRECTION. KEYWORDS: FUNC_NAME = function name (string) Calling mechanism should be: F = func_name( px, gradient ) where: px = scalar or vector of independent variables, input. F = scalar value of function at px. gradient = derivative of function, a scalar if 1-D, a gradient vector if N-D, (should only be computed if arg. is present). POINT_NDIM = when working with function of N variables, use this keyword to specify the starting point in N-dim space. Default = 0, which assumes function is 1-D. DIRECTION = when working with function of N variables, use this keyword to specify the direction in N-dim space along which to bracket the local minimum, (default=1 for 1-D). (xa, xb, xc, x_min are then relative distances from POINT_NDIM) MAX_ITER = maximum allowed number iterations, default=100. TOLERANCE = desired accuracy of minimum location, default=sqrt(1.e-7). OUTPUTS: xmin = estimated location of minimum. When working with function of N variables, xmin is the relative distance from POINT_NDIM, in the direction specified by keyword DIRECTION, with scale factor given by magnitude of DIRECTION, so that min. Loc. Pmin = Point_Ndim + xmin * Direction. fmin = value of function at xmin (or Pmin). PROCEDURE: Brent's method to minimize a function by using parabolic interpolation and using first derivative of function, from Numerical Recipes (by Press, et al.), sec.10.3 (p.287), MODIFICATION HISTORY: Written, Frank Varosi NASA/GSFC 1992.(See astrolib/pro/minf_parabol_d.pro)
MINMAX
[Previous Routine] [Next Routine] [List of Routines]NAME: MINMAX PURPOSE: Return a 2 element array giving the minimum and maximum of an array EXPLANATION: Using MINMAX() is faster than doing a separate MAX and MIN. The procedure MAXMIN in http://www.idlcoyote.com/programs/maxmin.pro has a similar purpose but uses a procedure call rather than a function. CALLING SEQUENCE: value = minmax( array, [subs, /NAN, DIMEN= ] ) INPUTS: array - an IDL numeric scalar, vector or array. OUTPUTS: value = a two element vector (if DIMEN is not supplied) value[0] = minimum value of array value[1] = maximum value of array If the DIMEN keyword is supplied then value will be a 2 x N element array where N is the number of elements in the specified dimension OPTIONAL OUTPUT PARAMETER: subs - two-dimensional vector; the first element gives the subscript of the minimum value, the second element gives the subscript of the maximum value. OPTIONAL INPUT KEYWORD: /NAN - Set this keyword to cause the routine to check for occurrences of the IEEE floating-point value NaN in the input data. Elements with the value NaN are treated as missing data. DIMEN - integer (either 1 or 2) specifying which dimension of a 2-d array to take the minimum and maximum. Note that (unlike the DIMENSION keyword to the MIN() function) DIMEN is only valid for a 2-d array, larger dimensions are not supported. EXAMPLE: (1) Print the minimum and maximum of an image array, im IDL> print, minmax( im ) (2) Given a 2-dimension array of (echelle) wavelengths w, print the minimum and maximum of each order print,minmax(w,dimen=1) PROCEDURE: The MIN function is used with the MAX keyword REVISION HISTORY: Written W. Landsman January, 1990 Added NaN keyword. M. Buie June 1998 Added DIMEN keyword W. Landsman January 2002 Added SUBSCRIPT_MIN and SUBSCRIPT_MAX BT Jan 2005 Added optional subs output parameter W. Landsman July 2009(See astrolib/pro/minmax.pro)
MKHDR
[Previous Routine] [Next Routine] [List of Routines]NAME: MKHDR PURPOSE: Make a minimal primary (or IMAGE extension) FITS header EXPLANATION: If an array is supplied, then the created FITS header will be appropriate to the supplied array. Otherwise, the user can specify the dimensions and datatype. CALLING SEQUENCE: MKHDR, header ;Prompt for image size and type or MKHDR, header, im, [ /IMAGE, /EXTEND ] or MKHDR, header, type, naxisx, [/IMAGE, /EXTEND ] OPTIONAL INPUTS: IM - If IM is a vector or array then the header will be made appropriate to the size and type of IM. IM does not have to be the actual data; it can be a dummy array of the same type and size as the data. Set IM = '' to create a dummy header with NAXIS = 0. TYPE - If 2 parameters are supplied, then the second parameter is interpreted as an integer giving the IDL datatype e.g. 1 - Byte, 2 - 16 bit integer, 4 - float, 3 - Long NAXISX - Vector giving the size of each dimension (NAXIS1, NAXIS2, etc.). OUTPUT: HEADER - image header, (string array) with required keywords BITPIX, NAXIS, NAXIS1, ... Further keywords can be added to the header with SXADDPAR. OPTIONAL INPUT KEYWORDS: /IMAGE = If set, then a minimal header for a FITS IMAGE extension is created. An IMAGE extension header is identical to a primary FITS header except the first keyword is 'XTENSION' = 'IMAGE' instead of 'SIMPLE ' = 'T' /EXTEND = If set, then the keyword EXTEND is inserted into the file, with the value of "T" (true). The EXTEND keyword can optionally be included in a primary header, if the FITS file contains extensions. RESTRICTIONS: (1) MKHDR should not be used to make an STSDAS header or a FITS ASCII or Binary Table extension header. Instead use SXHMAKE - to create a minimal STSDAS header FXBHMAKE - to create a minimal FITS binary table header FTCREATE - to create a minimal FITS ASCII table header (2) Any data already in the header before calling MKHDR will be destroyed. EXAMPLE: Create a minimal FITS header, Hdr, for a 30 x 40 x 50 INTEGER*2 array IDL> mkhdr, Hdr, 2, [30,40,50] Alternatively, if the array already exists as an IDL variable, Array, IDL> mkhdr, Hdr, Array PROCEDURES CALLED: SXADDPAR, GET_DATE REVISION HISTORY: Written November, 1988 W. Landsman May, 1990, Adapted for IDL Version 2.0, J. Isensee Aug, 1997, Use SYSTIME(), new DATE format W. Landsman Allow unsigned data types W. Landsman December 1999 Set BZERO = 0 for unsigned integer data W. Landsman January 2000 EXTEND keyword must immediately follow last NAXISi W. Landsman Sep 2000 Add FITS definition COMMENT to primary headers W. Landsman Oct. 2001 Allow (nonstandard) 64 bit integers W. Landsman Feb. 2003 Add V6.0 notation W. Landsman July 2012(See astrolib/pro/mkhdr.pro)
MLINMIX_ERR
[Previous Routine] [Next Routine] [List of Routines]NAME: MLINMIX_ERR PURPOSE: Bayesian approach to multiple linear regression with errors in X and Y EXPLANATION: PERFORM LINEAR REGRESSION OF Y ON X WHEN THERE ARE MEASUREMENT ERRORS IN BOTH VARIABLES. THE REGRESSION ASSUMES : ETA = ALPHA + BETA ## XI + EPSILON X = XI + XERR Y = ETA + YERR HERE, (ALPHA, BETA) ARE THE REGRESSION COEFFICIENTS, EPSILON IS THE INTRINSIC RANDOM SCATTER ABOUT THE REGRESSION, XERR IS THE MEASUREMENT ERROR IN X, AND YERR IS THE MEASUREMENT ERROR IN Y. EPSILON IS ASSUMED TO BE NORMALLY-DISTRIBUTED WITH MEAN ZERO AND VARIANCE SIGSQR. XERR AND YERR ARE ASSUMED TO BE NORMALLY-DISTRIBUTED WITH MEANS EQUAL TO ZERO, COVARIANCE MATRICES XVAR^2 FOR X, VARIANCES YSIG^2 FOR Y, AND COVARIANCE VECTORS XYCOV. THE DISTRIBUTION OF XI IS MODELLED AS A MIXTURE OF NORMALS, WITH GROUP PROPORTIONS PI, MEANS MU, AND COVARIANCES T. BAYESIAN INFERENCE IS EMPLOYED, AND A STRUCTURE CONTAINING RANDOM DRAWS FROM THE POSTERIOR IS RETURNED. CONVERGENCE OF THE MCMC TO THE POSTERIOR IS MONITORED USING THE POTENTIAL SCALE REDUCTION FACTOR (RHAT, GELMAN ET AL.2004). IN GENERAL, WHEN RHAT < 1.1 THEN APPROXIMATE CONVERGENCE IS REACHED. SIMPLE NON-DETECTIONS ON Y MAY ALSO BE INCLUDED AUTHOR : BRANDON C. KELLY, STEWARD OBS., JULY 2006 INPUTS : X - THE OBSERVED INDEPENDENT VARIABLES. THIS SHOULD BE AN [NX, NP]-ELEMENT ARRAY. Y - THE OBSERVED DEPENDENT VARIABLE. THIS SHOULD BE AN NX-ELEMENT VECTOR. OPTIONAL INPUTS : XVAR - THE COVARIANCE MATRIX OF THE X ERRORS, AND [NX,NP,NP]-ELEMENT ARRAY. XVAR[I,*,*] IS THE COVARIANCE MATRIX FOR THE ERRORS ON X[I,*]. THE DIAGONAL OF XVAR[I,*,*] MUST BE GREATER THAN ZERO FOR EACH DATA POINT. YVAR - THE VARIANCE OF THE Y ERRORS, AND NX-ELEMENT VECTOR. YVAR MUST BE GREATER THAN ZERO. XYCOV - THE VECTOR OF COVARIANCES FOR THE MEASUREMENT ERRORS BETWEEN X AND Y. DELTA - AN NX-ELEMENT VECTOR INDICATING WHETHER A DATA POINT IS CENSORED OR NOT. IF DELTA[i] = 1, THEN THE SOURCE IS DETECTED, ELSE IF DELTA[i] = 0 THE SOURCE IS NOT DETECTED AND Y[i] SHOULD BE AN UPPER LIMIT ON Y[i]. NOTE THAT IF THERE ARE CENSORED DATA POINTS, THEN THE MAXIMUM-LIKELIHOOD ESTIMATE (THETA) IS NOT VALID. THE DEFAULT IS TO ASSUME ALL DATA POINTS ARE DETECTED, IE, DELTA = REPLICATE(1, NX). SILENT - SUPPRESS TEXT OUTPUT. MINITER - MINIMUM NUMBER OF ITERATIONS PERFORMED BY THE GIBBS SAMPLER. IN GENERAL, MINITER = 5000 SHOULD BE SUFFICIENT FOR CONVERGENCE. THE DEFAULT IS MINITER = 5000. THE GIBBS SAMPLER IS STOPPED AFTER RHAT < 1.1 FOR ALPHA, BETA, AND SIGMA^2, AND THE NUMBER OF ITERATIONS PERFORMED IS GREATER THAN MINITER. MAXITER - THE MAXIMUM NUMBER OF ITERATIONS PERFORMED BY THE MCMC. THE DEFAULT IS 1D5. THE GIBBS SAMPLER IS STOPPED AUTOMATICALLY AFTER MAXITER ITERATIONS. NGAUSS - THE NUMBER OF GAUSSIANS TO USE IN THE MIXTURE MODELLING. THE DEFAULT IS 3. OUTPUT : POST - A STRUCTURE CONTAINING THE RESULTS FROM THE GIBBS SAMPLER. EACH ELEMENT OF POST IS A DRAW FROM THE POSTERIOR DISTRIBUTION FOR EACH OF THE PARAMETERS. ALPHA - THE CONSTANT IN THE REGRESSION. BETA - THE SLOPES OF THE REGRESSION. SIGSQR - THE VARIANCE OF THE INTRINSIC SCATTER. PI - THE GAUSSIAN WEIGHTS FOR THE MIXTURE MODEL. MU - THE GAUSSIAN MEANS FOR THE MIXTURE MODEL. T - THE GAUSSIAN COVARIANCE MATRICES FOR THE MIXTURE MODEL. MU0 - THE HYPERPARAMETER GIVING THE MEAN VALUE OF THE GAUSSIAN PRIOR ON MU. U - THE HYPERPARAMETER DESCRIBING FOR THE PRIOR COVARIANCE MATRIX OF THE INDIVIDUAL GAUSSIAN CENTROIDS ABOUT MU0. W - THE HYPERPARAMETER DESCRIBING THE `TYPICAL' SCALE MATRIX FOR THE PRIOR ON (T,U). XIMEAN - THE MEAN OF THE DISTRIBUTION FOR THE INDEPENDENT VARIABLE, XI. XIVAR - THE STANDARD COVARIANCE MATRIX FOR THE DISTRIBUTION OF THE INDEPENDENT VARIABLE, XI. XICORR - SAME AS XIVAR, BUT FOR THE CORRELATION MATRIX. CORR - THE LINEAR CORRELATION COEFFICIENT BETWEEN THE DEPENDENT AND INDIVIDUAL INDEPENDENT VARIABLES, XI AND ETA. PCORR - SAME AS CORR, BUT FOR THE PARTIAL CORRELATIONS. CALLED ROUTINES : RANDOMCHI, MRANDOMN, RANDOMWISH, RANDOMDIR, MULTINOM REFERENCES : Carroll, R.J., Roeder, K., & Wasserman, L., 1999, Flexible Parametric Measurement Error Models, Biometrics, 55, 44 Kelly, B.C., 2007, Some Aspects of Measurement Error in Linear Regression of Astronomical Data, ApJ, In press (astro-ph/0705.2774) Gelman, A., Carlin, J.B., Stern, H.S., & Rubin, D.B., 2004, Bayesian Data Analysis, Chapman & Hall/CRC(See astrolib/pro/mlinmix_err.pro)
MMM
[Previous Routine] [Next Routine] [List of Routines]NAME: MMM PURPOSE: Estimate the sky background in a stellar contaminated field. EXPLANATION: MMM assumes that contaminated sky pixel values overwhelmingly display POSITIVE departures from the true value. Adapted from DAOPHOT routine of the same name. CALLING SEQUENCE: MMM, sky, [ skymod, sigma, skew, HIGHBAD = , READNOISE=, /DEBUG, NSKY=, /INTEGER,/SILENT] INPUTS: SKY - Array or Vector containing sky values. This version of MMM does not require SKY to be sorted beforehand. SKY is unaltered by this program. OPTIONAL OUTPUTS: skymod - Scalar giving estimated mode of the sky values SIGMA - Scalar giving standard deviation of the peak in the sky histogram. If for some reason it is impossible to derive skymod, then SIGMA = -1.0 SKEW - Scalar giving skewness of the peak in the sky histogram If no output variables are supplied or if /DEBUG is set then the values of skymod, SIGMA and SKEW will be printed. OPTIONAL KEYWORD INPUTS: HIGHBAD - scalar value of the (lowest) "bad" pixel level (e.g. cosmic rays or saturated pixels) If not supplied, then there is assumed to be no high bad pixels. MINSKY - Integer giving mininum number of sky values to be used. MMM will return an error if fewer sky elements are supplied. Default = 20. MAXITER - integer giving maximum number of iterations allowed,default=50 READNOISE - Scalar giving the read noise (or minimum noise for any pixel). Normally, MMM determines the (robust) median by averaging the central 20% of the sky values. In some cases where the noise is low, and pixel values are quantized a larger fraction may be needed. By supplying the optional read noise parameter, MMM is better able to adjust the fraction of pixels used to determine the median. /INTEGER - Set this keyword if the input SKY vector only contains discrete integer values. This keyword is only needed if the SKY vector is of type float or double precision, but contains only discrete integer values. (Prior to July 2004, the equivalent of /INTEGER was set for all data types) /DEBUG - If this keyword is set and non-zero, then additional information is displayed at the terminal. /SILENT - If set, then error messages will be suppressed when MMM cannot compute a background. Sigma will still be set to -1 OPTIONAL OUTPUT KEYWORD: NSKY - Integer scalar giving the number of pixels actually used for the sky computation (after outliers have been removed). NOTES: (1) Program assumes that low "bad" pixels (e.g. bad CCD columns) have already been deleted from the SKY vector. (2) MMM was updated in June 2004 to better match more recent versions of DAOPHOT. (3) Does not work well in the limit of low Poisson integer counts (4) MMM may fail for strongly skewed distributions. METHOD: The algorithm used by MMM consists of roughly two parts: (1) The average and sigma of the sky pixels is computed. These values are used to eliminate outliers, i.e. values with a low probability given a Gaussian with specified average and sigma. The average and sigma are then recomputed and the process repeated up to 20 iterations: (2) The amount of contamination by stars is estimated by comparing the mean and median of the remaining sky pixels. If the mean is larger than the median then the true sky value is estimated by 3*median - 2*mean REVISION HISTORY: Adapted to IDL from 1986 version of DAOPHOT in STSDAS, W. Landsman, STX Feb 1987 Added HIGHBAD keyword, W. Landsman January, 1991 Fixed occasional problem with integer inputs W. Landsman Feb, 1994 Avoid possible 16 bit integer overflow W. Landsman November 2001 Added READNOISE, NSKY keywords, new median computation W. Landsman June 2004 Added INTEGER keyword W. Landsman July 2004 Improve numerical precision W. Landsman October 2004 Fewer aborts on strange input sky histograms W. Landsman October 2005 Added /SILENT keyword November 2005 Fix too many /CON keywords to MESSAGE W.L. December 2005 Fix bug introduced June 2004 removing outliers when READNOISE not set N. Cunningham/W. Landsman January 2006 Make sure that MESSAGE never aborts W. Landsman January 2008 Add mxiter keyword and change default to 50 W. Landsman August 2011 Added MINSKY keyword W.L. December 2011(See astrolib/pro/mmm.pro)
MODFITS
[Previous Routine] [Next Routine] [List of Routines]NAME: MODFITS PURPOSE: Modify a FITS file by updating the header and/or data array. EXPLANATION: Update the data and/or header in a specified FITS extension or primary HDU. The size of the supplied FITS header or data array does not need to match the size of the existing header or data array. CALLING SEQUENCE: MODFITS, Filename_or_fcb, Data, [ Header, EXTEN_NO =, EXTNAME= , ERRMSG=] INPUTS: FILENAME/FCB = Scalar string containing either the name of the FITS file to be modified, or the IO file control block returned after opening the file with FITS_OPEN,/UPDATE. The explicit use of FITS_OPEN can save time if many extensions in a single file will be updated. DATA - data array to be inserted into the FITS file. Set DATA = 0 to leave the data portion of the FITS file unmodified. Data can also be an IDL structure (e.g. as returned by MRDFITS). provided that it does not include IDL pointers. HEADER - FITS header (string array) to be updated in the FITS file. OPTIONAL INPUT KEYWORDS: A specific extension can be specified with either the EXTNAME or EXTEN_NO keyword EXTEN_NO - scalar integer specifying the FITS extension to modified. For example, specify EXTEN = 1 or /EXTEN to modify the first FITS extension. EXTNAME - string name of the extension to modify. OPTIONAL OUTPUT KEYWORD: ERRMSG - If this keyword is supplied, then any error mesasges will be returned to the user in this parameter rather than depending on on the MESSAGE routine in IDL. If no errors are encountered then a null string is returned. EXAMPLES: (1) Modify the value of the DATE keyword in the primary header of a file TEST.FITS. IDL> h = headfits('test.fits') ;Read primary header IDL> sxaddpar,h,'DATE','2001-03-23' ;Modify value of DATE IDL> modfits,'test.fits',0,h ;Update header only (2) Replace the values of the primary image array in 'test.fits' with their absolute values IDL> im = readfits('test.fits') ;Read image array IDL> im = abs(im) ;Take absolute values IDL> modfits,'test.fits',im ;Update image array (3) Add some HISTORY records to the FITS header in the first extension of a file 'test.fits' IDL> h = headfits('test.fits',/ext) ;Read first extension hdr IDL> sxaddhist,['Comment 1','Comment 2'],h IDL> modfits,'test.fits',0,h,/ext ;Update extension hdr (4) Change 'OBSDATE' keyword to 'OBS-DATE' in every extension in a FITS file. Explicitly open with FITS_OPEN to save compute time. fits_open,'test.fits',io,/update ;Faster to explicity open for i = 1,nextend do begin ;Loop over extensions fits_read,io,0,h,/header_only,exten_no=i,/No_PDU ;Get header date= sxpar(h,'OBSDATE') ;Save keyword value sxaddpar,h,'OBS-DATE',date,after='OBSDATE' sxdelpar,h,'OBSDATE' ;Delete bad keyword modfits,io,0,h,exten_no=i ;Update header endfor Note the use of the /No_PDU keyword in the FITS_READ call -- one does *not* want to append the primary header, if the STScI inheritance convention is adopted. NOTES: Uses the BLKSHIFT procedure to shift the contents of the FITS file if the new data or header differs in size by more than 2880 bytes from the old data or header. If a file control block (FCB) structure is supplied, then the values of START_HEADER, START_DATA and NBYTES may be modified if the file size changes. Also see the procedures FXHMODIFY to add a single FITS keyword to a header in a FITS files, and FXBGROW to enlarge the size of a binary table. RESTRICTIONS: (1) Cannot be used to modify the data in FITS files with random groups or variable length binary tables. (The headers in such files *can* be modified.) (2) If a data array but no FITS header is supplied, then MODFITS does not check to make sure that the existing header is consistent with the new data. (3) Does not work with compressed files (4) The Checksum keywords will not be updated if the array to be updated is supplied as a structure (e.g. from MRDFITS). PROCEDURES USED: Functions: N_BYTES(), SXPAR() Procedures: BLKSHIFT, CHECK_FITS, FITS_OPEN, FITS_READ MODIFICATION HISTORY: Written, Wayne Landsman December, 1994 Fixed possible problem when using WRITEU after READU October 1997 New and old sizes need only be the same within multiple of 2880 bytes Added call to IS_IEEE_BIG() W. Landsman May 1999 Added ERRMSG output keyword W. Landsman May 2000 Update tests for incompatible sizes W. Landsman December 2000 Major rewrite to use FITS_OPEN procedures W. Landsman November 2001 Add /No_PDU call to FITS_READ call W. Landsman June 2002 Update CHECKSUM keywords if already present in header, add padding if new data size is smaller than old W.Landsman December 2002 Only check XTENSION value if EXTEN_NO > 1 W. Landsman Feb. 2003 Correct for unsigned data on little endian machines W. Landsman Apr 2003 Major rewrite to allow changing size of data or header W.L. Aug 2003 Fixed case where updated header exactly fills boundary W.L. Feb 2004 More robust error reporting W.L. Dec 2004 Make sure input header ends with a END W.L. March 2006 Assume since V5.5, remove VMS support, assume FITS_OPEN will perform byte swapping W.L. Sep 2006 Update FCB structure if file size changes W.L. March 2007 Fix problem when data size must be extended W.L. August 2007 Don't assume supplied FITS header is 80 bytes W. L. Dec 2007 Check for new END position after adding CHECKSUM W.L. July 2008 Added EXTNAME input keyword W.L. July 2008 Allow data to be an IDL structure A. Conley/W.L. June 2009 Use V6.0 notation, add /NOZERO to BLKSHIFT W.L. Feb 2011 Don't try to update Checksums when structure supplied W.L. April 2011 Allow structure with only 1 element W.L. Feb 2012(See astrolib/pro/modfits.pro)
MONTH_CNV
[Previous Routine] [Next Routine] [List of Routines]NAME: MONTH_CNV PURPOSE: Convert between a month name and the equivalent number EXPLANATION: (e.g., For example, converts from 'January' to 1 or vice-versa. CALLING SEQUENCE: Result = MONTH_CNV( MonthInput, [/UP, /LOW, /SHORT ] ) INPUTS: MonthInput - either a string ('January', 'Jan', 'Decem', etc.) or an number from 1 to 12. Scalar or array. OPTIONAL KEYWORDS: UP - if set and if a string is being returned, it will be in all uppercase letters. LOW - if set and if a string is being returned, it will be in all lowercase letters. SHORT - if set and if a string is being returned, only the first three letters are returned. OUTPUTS: If the input is a string, the output is the matching month number.If an input string isn't a valid month name, -1 is returned. If the input is a number, the output is the matching month name. The default format is only the first letter is capitalized. EXAMPLE: To get a vector of all the month names: Names = month_cnv(indgen(12)+1) MODIFICATION HISTORY: Written by: Joel Wm. Parker, SwRI, 1998 Dec 9(See astrolib/pro/month_cnv.pro)
MOONPOS
[Previous Routine] [Next Routine] [List of Routines]NAME: MOONPOS PURPOSE: To compute the RA and Dec of the Moon at specified Julian date(s). CALLING SEQUENCE: MOONPOS, jd, ra, dec, dis, geolong, geolat, [/RADIAN ] INPUTS: JD - Julian ephemeris date, scalar or vector, double precision suggested OUTPUTS: Ra - Apparent right ascension of the moon in DEGREES, referred to the true equator of the specified date(s) Dec - The declination of the moon in DEGREES Dis - The Earth-moon distance in kilometers (between the center of the Earth and the center of the Moon). Geolong - Apparent longitude of the moon in DEGREES, referred to the ecliptic of the specified date(s) Geolat - Apparent longitude of the moon in DEGREES, referred to the ecliptic of the specified date(s) The output variables will all have the same number of elements as the input Julian date vector, JD. If JD is a scalar then the output variables will be also. OPTIONAL INPUT KEYWORD: /RADIAN - If this keyword is set and non-zero, then all output variables are given in Radians rather than Degrees EXAMPLES: (1) Find the position of the moon on April 12, 1992 IDL> jdcnv,1992,4,12,0,jd ;Get Julian date IDL> moonpos, jd, ra ,dec ;Get RA and Dec of moon IDL> print,adstring(ra,dec,1) ==> 08 58 45.23 +13 46 6.1 This is within 1" from the position given in the Astronomical Almanac (2) Plot the Earth-moon distance for every day at 0 TD in July, 1996 IDL> jdcnv,1996,7,1,0,jd ;Get Julian date of July 1 IDL> moonpos,jd+dindgen(31), ra, dec, dis ;Position at all 31 days IDL> plot,indgen(31),dis, /YNOZ METHOD: Derived from the Chapront ELP2000/82 Lunar Theory (Chapront-Touze' and Chapront, 1983, 124, 50), as described by Jean Meeus in Chapter 47 of ``Astronomical Algorithms'' (Willmann-Bell, Richmond), 2nd edition, 1998. Meeus quotes an approximate accuracy of 10" in longitude and 4" in latitude, but he does not give the time range for this accuracy. Comparison of this IDL procedure with the example in ``Astronomical Algorithms'' reveals a very small discrepancy (~1 km) in the distance computation, but no difference in the position calculation. This procedure underwent a major rewrite in June 1996, and the new calling sequence is *incompatible with the old* (e.g. angles now returned in degrees instead of radians). PROCEDURES CALLED: CIRRANGE, ISARRAY(), NUTATE, TEN() - from IDL Astronomy Library POLY() - from IDL User's Library MODIFICATION HISTORY: Written by Michael R. Greason, STX, 31 October 1988. Major rewrite, new (incompatible) calling sequence, much improved accuracy, W. Landsman Hughes STX June 1996 Added /RADIAN keyword W. Landsman August 1997 Converted to IDL V5.0 W. Landsman September 1997 Use improved expressions for L',D,M,M', and F given in 2nd edition of Meeus (very slight change), W. Landsman November 2000 Avoid 32767 overflow W. Landsman January 2005(See astrolib/pro/moonpos.pro)
MPHASE
[Previous Routine] [Next Routine] [List of Routines]NAME: MPHASE PURPOSE: Return the illuminated fraction of the Moon at given Julian date(s) CALLING SEQUENCE: MPHASE, jd, k INPUT: JD - Julian date, scalar or vector, double precision recommended OUTPUT: k - illuminated fraction of Moon's disk (0.0 < k < 1.0), same number of elements as jd. k = 0 indicates a new moon, while k = 1 for a full moon. EXAMPLE: Plot the illuminated fraction of the moon for every day in July 1996 at 0 TD (~Greenwich noon). IDL> jdcnv, 1996, 7, 1, 0, jd ;Get Julian date of July 1 IDL> mphase, jd+dindgen(31), k ;Moon phase for all 31 days IDL> plot, indgen(31),k ;Plot phase vs. July day number METHOD: Algorithm from Chapter 46 of "Astronomical Algorithms" by Jean Meeus (Willmann-Bell, Richmond) 1991. SUNPOS and MOONPOS are used to get positions of the Sun and the Moon (and the Moon distance). The selenocentric elongation of the Earth from the Sun (phase angle) is then computed, and used to determine the illuminated fraction. PROCEDURES CALLED: MOONPOS, SUNPOS REVISION HISTORY: Written W. Landsman Hughes STX June 1996 Converted to IDL V5.0 W. Landsman September 1997 Use /RADIAN keywords to MOONPOS, SUNPOS internally W. Landsman Aug 2000(See astrolib/pro/mphase.pro)
MRANDOMN
[Previous Routine] [Next Routine] [List of Routines]NAME: MRANDOMN PURPOSE: Function to draw NRAND random deviates from a multivariate normal distribution with zero mean and covariance matrix COVAR. AUTHOR : Brandon C. Kelly, Steward Obs., Sept. 2004 INPUTS : SEED - The random number generator seed, the default is IDL's default in RANDOMN() COVAR - The covariance matrix of the multivariate normal distribution. OPTIONAL INPUTS : NRAND - The number of randomn deviates to draw. The default is one. OUTPUT : The random deviates, an [NRAND, NP] array where NP is the dimension of the covariance matrix, i.e., the number of parameters. ROUTINES CALLED : POSITIVE, DIAG(See astrolib/pro/mrandomn.pro)
MRDFITS
[Previous Routine] [Next Routine] [List of Routines]NAME: MRDFITS PURPOSE: Read all standard FITS data types into arrays or structures. EXPLANATION: Further information on MRDFITS is available at http://idlastro.gsfc.nasa.gov/mrdfits.html **This version requires a post March 2009 version of fxposit.pro** CALLING SEQUENCE: Result = MRDFITS( Filename/FileUnit,[Exten_no/Exten_name, Header], /FPACK, /NO_FPACK, /FSCALE , /DSCALE , /UNSIGNED, ALIAS=strarr[2,n], /USE_COLNUM, /NO_TDIM, ROWS = [a,b,...], $ /POINTER_VAR, /FIXED_VAR, EXTNUM= RANGE=[a,b], COLUMNS=[a,b,...]), ERROR_ACTION=x, COMPRESS=comp_prog, STATUS=status, /VERSION, /EMPTYSTRING ) INPUTS: Filename = String containing the name of the file to be read or file number of an open unit. If an empty string is supplied, then user will be prompted for the file name. The user will also be prompted if a wild card is given in the file name, and there is more than one file name match. If the file name ends in .gz or .fz (or .Z on Unix systems) the file will be dynamically decompressed. or FiluUnit = An integer file unit which has already been opened for input. Data will be read from this unit and the unit will be left pointing immediately after the HDU that is read. Thus to read a compressed file with many HDU's a user might do something like: lun=fxposit(filename, 3) ; Skip the first three HDU's repeat begin thisHDU = mrdfits(lun, 0, hdr, status=status) ... process the HDU ... endrep until status lt 0 Exten_no= Extension number to be read, 0 for primary array. Assumed 0 if not specified. If a unit rather than a filename is specified in the first argument, this is the number of HDU's to skip from the current position. Exten_name - Name of the extension to read (as stored in the EXTNAME keyword). This is a slightly slower method then specifying the extension number. OUTPUTS: Result = FITS data array or structure constructed from the designated extension. The format of result depends upon the type of FITS data read. Non-group primary array or IMAGE extension: A simple multidimensional array is returned with the dimensions given in the NAXISn keywords. Grouped image data with PCOUNT=0. As above but with GCOUNT treated as NAXIS(n+1). Grouped image data with PCOUNT>0. The data is returned as an array of structures. Each structure has two elements. The first is a one-dimensional array of the group parameters, the second is a multidimensional array as given by the NAXIS2-n keywords. ASCII and BINARY tables. The data is returned as a structure with one column for each field in the table. The names of the columns are normally taken from the TTYPE keywords (but see USE_COLNUM). Bit field columns are stored in byte arrays of the minimum necessary length. Spaces and invalid characters are replaced by underscores, and other invalid tag names are converted using the IDL_VALIDNAME(/CONVERT_ALL) function. Columns specified as variable length columns are stored with a dimension equal to the largest actual dimension used. Extra values in rows are filled with 0's or blanks. If the size of the variable length column is not a constant, then an additional column is created giving the size used in the current row. This additional column will have a tag name of the form L#_"colname" where # is the column number and colname is the column name of the variable length column. If the length of each element of a variable length column is 0 then the column is deleted. OPTIONAL OUTPUT: Header = String array containing the header from the FITS extension. OPTIONAL INPUT KEYWORDS: ALIAS The keyword allows the user to specify the column names to be created when reading FITS data. The value of this keyword should be a 2xn string array. The first value of each pair of strings should be the desired tag name for the IDL column. The second should be the FITS TTYPE value. Note that there are restrictions on valid tag names. The order of the ALIAS keyword is compatible with MWRFITS. COLUMNS - This keyword allows the user to specify that only a subset of columns is to be returned. The columns may be specified either as number 1,... n or by name or some combination of these two. If /USE_COLNUM is specified names should be C1,...Cn. The use of this keyword will not save time or internal memory since the extraction of specified columns is done after all columns have been retrieved from the FITS file. Structure columns are returned in the order supplied in this keyword. COMPRESS - This keyword allows the user to specify a decompression program to use to decompress a file that will not be automatically recognized based upon the file name. /DSCALE - As with FSCALE except that the resulting data is stored in doubles. /EMPTYSTRING - There was a bug in memory management for IDL versions prior to V8.0, causing a memory leak when reading empty strings in a FITS table. Setting /EMPTYSTRING will avoid this problem by first reading strings into bytes and then converting. However, there is a performance penalty. ERROR_ACTION - Set the on_error action to this value (defaults to 2). /FIXED_VAR- Translate variable length columns into fixed length columns and provide a length column for truly varying columns. This was only behavior prior to V2.5 for MRDFITS and remains the default (see /POINTER_VAR) /FPACK - If set, then assume the FITS file uses FPACK compression (http://heasarc.gsfc.nasa.gov/fitsio/fpack/). To read an FPACK compressed file, either this must be set or the file name must end in ".fz" /NO_FPACK - If present, then MRDFITS will not uncompress an extension compressed with FPACK (i.e with a .fz extension), but will just read the compressed binary stream. /FSCALE - If present and non-zero then scale data to float numbers for arrays and columns which have either non-zero offset or non-unity scale. If scaling parameters are applied, then the corresponding FITS scaling keywords will be modified. NO_TDIM - Disable processing of TDIM keywords. If NO_TDIM is specified MRDFITS will ignore TDIM keywords in binary tables. /POINTER_VAR- Use pointer arrays for variable length columns. In addition to changing the format in which variable length arrays are stored, if the pointer_var keyword is set to any value other than 1 this also disables the deletion of variable length columns. (See /FIXED_VAR) Note that because pointers may be present in the output structure, the user is responsible for memory management when deleting or reassigning the structure (e.g. use HEAP_FREE first). RANGE - A scalar or two element vector giving the start and end rows to be retrieved. For ASCII and BINARY tables this specifies the row number. For GROUPed data this will specify the groups. For array images, this refers to the last non-unity index in the array. E.g., for a 3 D image with NAXIS* values = [100,100,1], the range may be specified as 0:99, since the last axis is suppressed. Note that the range uses IDL indexing So that the first row is row 0. If only a single value, x, is given in the range, the range is assumed to be [0,x-1]. ROWS - A scalar or vector specifying a specific row or rows to read (first row is 0). For example to read rows 0, 12 and 23 only, set ROWS=[0,12,23]. Valid for images, ASCII and binary tables, but not GROUPed data. For images the row numbers refer to the last non-unity index in the array. Note that the use of the ROWS will not improve the speed of MRDFITS since the entire table will be read in, and then subset to the specified rows. Cannot be used at the same time as the RANGE keyword /SILENT - Suppress informative messages. STRUCTYP - The structyp keyword specifies the name to be used for the structure defined when reading ASCII or binary tables. Generally users will not be able to conveniently combine data from multiple files unless the STRUCTYP parameter is specified. An error will occur if the user specifies the same value for the STRUCTYP keyword in calls to MRDFITS in the same IDL session for extensions which have different structures. /UNSIGNED - For integer data with appropriate zero points and scales read the data into unsigned integer arrays. /USE_COLNUM - When creating column names for binary and ASCII tables MRDFITS attempts to use the appropriate TTYPE keyword values. If USE_COLNUM is specified and non-zero then column names will be generated as 'C1, C2, ... 'Cn' for the number of columns in the table. /VERSION Print the current version number OPTIONAL OUTPUT KEYWORDS: EXTNUM - the number of the extension actually read. Useful if the user specified the extension by name. OUTALIAS - This is a 2xn string array where the first column gives the actual structure tagname, and the second gives the corresponding FITS keyword name (e.g. in the TTYPE keyword). This array can be passed directly to the alias keyword of MWRFITS to recreate the file originally read by MRDFITS. STATUS - A integer status indicating success or failure of the request. A status of >=0 indicates a successful read. Currently 0 -> successful completion -1 -> error -2 -> end of file EXAMPLES: (1) Read a FITS primary array: a = mrdfits('TEST.FITS') or a = mrdfits('TEST.FITS', 0, header) The second example also retrieves header information. (2) Read rows 10-100 of the second extension of a FITS file. a = mrdfits('TEST.FITS', 2, header, range=[10,100]) (3) Read a table and ask that any scalings be applied and the scaled data be converted to doubles. Use simple column names, suppress outputs. a = mrdfits('TEST.FITS', 1, /dscale, /use_colnum, /silent) (4) Read rows 3, 34 and 52 of a binary table and request that variable length columns be stored as a pointer variable in the output structure a = mrdfits('TEST.FITS',1,rows=[3,34,52],/POINTER) RESTRICTIONS: (1) Cannot handle data in non-standard FITS formats. (2) Doesn't do anything with BLANK or NULL values or NaN's. They are just read in. They may be scaled if scaling is applied. (3) Does not automatically detect a FPACK compressed file. Either the file name must end in .fz, or the /FPACK keyword must be set NOTES: This multiple format FITS reader is designed to provide a single, simple interface to reading all common types of FITS data. MRDFITS DOES NOT scale data by default. The FSCALE or DSCALE parameters must be used. Null values in an FITS ASCII table are converted to NaN (floating data), or -2147483647L (longwords) or '...' (strings). PROCEDURES USED: The following procedures are contained in the main MRDFITS program. MRD_IMAGE -- Generate array/structure for images. MRD_READ_IMAGE -- Read image data. MRD_ASCII -- Generate structure for ASCII tables. MRD_READ_ASCII -- Read an ASCII table. MRD_TABLE -- Generate structure for Binary tables. MRD_READ_TABLE -- Read binary table info. MRD_READ_HEAP -- Read variable length record info. MRD_SCALE -- Apply scaling to data. MRD_COLUMNS -- Extract columns. Other ASTRON Library routines used FXPAR(), FXADDPAR, FXPOSIT, FXMOVE(), MATCH, MRD_STRUCT(), MRD_SKIP MODIfICATION HISTORY: V1.0 November 9, 1994 ---- Initial release. Creator: Thomas A. McGlynn V1.1 January 20, 1995 T.A. McGlynn Fixed bug in variable length records. Added TDIM support -- new routine mrd_tdim in MRD_TABLE. V1.2 Added support for dynamic decompression of files. Fixed further bugs in variable length record handling. V1.2a Added NO_TDIM keyword to turn off TDIM processing for those who don't want it. Bug fixes: Handle one row tables correctly, use BZERO rather than BOFFSET. Fix error in scaling of images. V1.2b Changed MRD_HREAD to handle null characters in headers. V2.0 April 1, 1996 -Handles FITS tables with an arbitrary number of columns. -Substantial changes to MRD_STRUCT to allow the use of substructures when more than 127 columns are desired. -All references to table columns are now made through the functions MRD_GETC and MRD_PUTC. See description above. -Use of SILENT will now eliminate compilation messages for temporary functions. -Bugs in handling of variable length columns with either a single row in the table or a maximum of a single element in the column fixed. -Added support for DCOMPLEX numbers in binary tables (M formats) for IDL versions above 4.0. -Created regression test procedure to check in new versions. -Added error_action parameter to allow user to specify on_error action. This should allow better interaction with new CHECK facility. ON_ERROR statements deleted from most called routines. - Modified MRDFITS to read in headers containing null characters with a warning message printed. V2.0a April 16, 1996 - Added IS_IEEE_BIG() checks (and routine) so that we don't worry about IEEE to host conversions if the machine's native format is IEEE Big-endian. V2.1 August 24, 1996 - Use resolve_routine for dynamically defined functions for versions > 4.0 - Fix some processing in random groups format. - Handle cases where the data segment is--legally--null. In this case MRDFITS returns a scalar 0. - Fix bugs with the values for BSCALE and BZERO (and PSCAL and PZERO) parameters set by MRDFITS. V2.1a April 24, 1997 Handle binary tables with zero length columns V2.1b May 13,1997 Remove whitespace from replicate structure definition V2.1c May 28,1997 Less strict parsing of XTENSION keyword V2.1d June 16, 1997 Fixed problem for >32767 entries introduced 24-Apr V2.1e Aug 12, 1997 Fixed problem handling double complex arrays V2.1f Oct 22, 1997 IDL reserved words can't be structure tag names V2.1g Nov 24, 1997 Handle XTENSION keywords with extra blanks. V2.1h Jul 26, 1998 More flexible parsing of TFORM characters V2.2 Dec 14, 1998 Allow fields with longer names for later versions of IDL. Fix handling of arrays in scaling routines. Allow >128 fields in structures for IDL >4.0 Use more efficient structure copying for IDL>5.0 V2.2b June 17, 1999 Fix bug in handling case where all variable length columns are deleted because they are empty. V2.3 March 7, 2000 Allow user to supply file handle rather than file name. Added status field. Now needs FXMOVE routine V2.3b April 4, 2000 Added compress option (from D. Palmer) V2.4 July 4, 2000 Added STATUS=-1 for "File access error" (Zarro/GSFC) V2.4a May 2, 2001 Trim binary format string (W. Landsman) V2.5 December 5, 2001 Add unsigned, alias, 64 bit integers. version, $ /pointer_val, /fixed_var. V2.5a Fix problem when both the first and the last character in a TTYPEnn value are invalid structure tag characters V2.6 February 15, 2002 Fix error in handling unsigned numbers, $ and 64 bit unsigneds. (Thanks to Stephane Beland) V2.6a September 2, 2002 Fix possible conflicting data structure for variable length arrays (W. Landsman) V2.7 July, 2003 Added Rows keyword (W. Landsman) V2.7a September 2003 Convert dimensions to long64 to handle huge files V2.8 October 2003 Use IDL_VALIDNAME() function to ensure valid tag names Removed OLD_STRUCT and TEMPDIR keywords W. Landsman V2.9 February 2004 Added internal MRD_FXPAR procedure for faster processing of binary table headers E. Sheldon V2.9a March 2004 Restore ability to read empty binary table W. Landsman Swallow binary tables with more columns than given in TFIELDS V2.9b Fix to ensure order of TFORMn doesn't matter V2.9c Check if extra degenerate NAXISn keyword are present W.L. Oct 2004 V2.9d Propagate /SILENT to MRD_HREAD, more LONG64 casting W. L. Dec 2004 V2.9e Add typarr[good] to fix a problem reading zero-length columns A.Csillaghy, csillag@ssl.berkeley.edu (RHESSI) V2.9f Fix problem with string variable binary tables, possible math overflow on non-IEEE machines WL Feb. 2005 V2.9g Fix problem when setting /USE_COLNUM WL Feb. 2005 V2.10 Use faster keywords to BYTEORDER WL May 2006 V2.11 Add ON_IOERROR, CATCH, and STATUS keyword to MRD_READ_IMAGE to trap EOF in compressed files DZ Also fix handling of unsigned images when BSCALE not present K Chu/WL June 2006 V2.12 Allow extension to be specified by name, added EXTNUM keyword WL December 2006 V2.12a Convert ASCII table column to DOUBLE if single precision is insufficient V2.12b Fixed problem when both /fscale and /unsigned are set C. Markwardt Aug 2007 V2.13 Use SWAP_ENDIAN_INPLACE instead of IEEE_TO_HOST and IS_IEEE_BIG W. Landsman Nov 2007 V2.13a One element vector allowed for file name W.L. Dec 2007 V2.13b More informative error message when EOF found W.L. Jun 2008 V2.14 Use vector form of VALID_NUM(), added OUTALIAS keyword W.L. Aug 2008 V2.15 Use new FXPOSIT which uses on-the-fly byteswapping W.L. Mar 2009 V2.15a Small efficiency updates to MRD_SCALE W.L. Apr 2009 V2.15b Fixed typo introduced Apr 2009 V2.15c Fix bug introduced Mar 2009 when file unit used W.L. July 2009 V2.16 Handle FPACK compressed files W. L. July 2009 V2.17 Use compile_opt hidden on all routines except mrdfits.pro W.L. July 2009 V2.18 Added /EMPTYSTRING keyword W. Landsman August 2009 V2.18a Fix Columns keyword output, A. Kimball/ W. Landsman Feb 2010 V2.18b Fix bug with /EMPTYSTRING and multidimensional strings S. Baldridge/W.L. August 2010 V2.18c Fix unsigned bug caused by compile_opt idl2 WL Nov 2010 V2.19 Use V6.0 operators WL Nov 2010 V2.19a Fix complex data conversion in variable length tables WL Dec 2010 V2.19b Fix bug with /FSCALE introduced Nov 2010 WL Jan 2011 V2.19c Fix bug with ROWS keyword introduced Nov 2010 WL Mar 2011 V2.20 Convert Nulls in ASCII tables, better check of duplicate keywords WL May 2011 V2.20a Better error checking for FPACK files WL October 2012(See astrolib/pro/mrdfits.pro)
MRD_HREAD
[Previous Routine] [Next Routine] [List of Routines]NAME: MRD_HREAD PURPOSE: Reads a FITS header from an opened disk file or Unix pipe EXPLANATION: Like FXHREAD but also works with compressed Unix files CALLING SEQUENCE: MRD_HREAD, UNIT, HEADER [, STATUS, /SILENT, ERRMSG =, /FIRSTBLOCK ] INPUTS: UNIT = Logical unit number of an open FITS file OUTPUTS: HEADER = String array containing the FITS header. OPT. OUTPUTS: STATUS = Condition code giving the status of the read. Normally, this is zero, but is set to -1 if an error occurs, or if the first byte of the header is zero (ASCII null). OPTIONAL KEYWORD INPUT: /FIRSTBLOCK - If set, then only the first block (36 lines or less) of the FITS header are read into the output variable. If only size information (e.g. BITPIX, NAXIS) is needed from the header, then the use of this keyword can save time. The file pointer is still positioned at the end of the header, even if the /FIRSTBLOCK keyword is supplied. /SILENT - If set, then warning messages about any invalid characters in the header are suppressed. /SKIPDATA - If set, then the file point is positioned at the end of the HDU after the header is read, i.e. the following data block is skipped. Useful, when one wants to the read the headers of multiple extensions. /NO_BADHEADER - if set, returns if FITS header has illegal characters By default, MRD_HREAD replaces bad characters with blanks, issues a warning, and continues. OPTIONAL OUTPUT PARAMETER: ERRMSG = If this keyword is present, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. RESTRICTIONS: The file must already be positioned at the start of the header. It must be a proper FITS file. SIDE EFFECTS: The file ends by being positioned at the end of the FITS header, unless an error occurs. REVISION HISTORY: Written, Thomas McGlynn August 1995 Modified, Thomas McGlynn January 1996 Changed MRD_HREAD to handle Headers which have null characters A warning message is printed out but the program continues. Previously MRD_HREAD would fail if the null characters were not in the last 2880 byte block of the header. Note that such characters are illegal in the header but frequently are produced by poor FITS writers. Added /SILENT keyword W. Landsman December 2000 Added /FIRSTBLOCK keyword W. Landsman February 2003 Added ERRMSG, SKIPDATA keyword W. Landsman April 2009 Close file unit even after error message W.L. October 2010 Added /NO_BADHEADER Zarro (ADNET), January 2012(See astrolib/pro/mrd_hread.pro)
MRD_SKIP
[Previous Routine] [Next Routine] [List of Routines]NAME: MRD_SKIP PURPOSE: Skip a number of bytes from the current location in a file or a pipe EXPLANATION: First tries using POINT_LUN and if this doesn't work, perhaps because the unit is a pipe or a socket, MRD_SKIP will just read in the requisite number of bytes. CALLING SEQUENCE: MRD_SKIP, Unit, Nskip INPUTS: Unit - File unit for the file or pipe in question, integer scalar Nskip - Number of bytes to be skipped, positive integer NOTES: This routine should be used in place of POINT_LUN wherever a pipe or socket may be the input unit (see the procedure FXPOSIT for an example). Note that it assumes that it can only work with nskip >= 0 so it doesn't even try for negative values. For reading a pipe, MRD_SKIP currently uses a maximum buffer size of 8 MB. This chunk value can be increased for improved efficiency (or decreased if you really have little memory.) REVISION HISTORY: Written, Thomas A. McGlynn July 1995 Don't even try to skip bytes on a pipe with POINT_LUN, since this might reset the current pointer W. Landsman April 1996 Increase buffer size, check fstat.compress W. Landsman Jan 2001 Only a warning if trying read past EOF W. Landsman Sep 2001 Use 64bit longword for skipping in very large files W. Landsman Sep 2003 Assume since V5.4, fstat.compress available W. Landsman April 2006 POINT_LUN for compressed files is as fast as any W. Landsman Oct 2006 Don't try to use POINT_LUN on compressed files W. Landsman Dec. 2006(See astrolib/pro/mrd_skip.pro)
MRD_STRUCT
[Previous Routine] [Next Routine] [List of Routines]NAME: MRD_STRUCT PURPOSE: Return a structure as defined in the names and values data. CALLING SEQUENCE: struct = MRD_STRUCT(NAMES, VALUES, NROW, STRUCTYP='name' ) INPUT PARAMETERS: NAMES = A string array of names of structure fields. VALUES = A string array giving the values of the structure fields. See examples below. NROW = The number of elements in the structure array. RETURNS: A structure as described in the parameters or 0 if an error is detected. OPTIONAL KEYWORD PARAMETERS: /NO_EXECUTE - If set then the use of the EXECUTE() statement is avoided. By default, the NO_EXECUTE pathway is used if IDL is running under the Virtual Machine. Note if /NO_EXECUTE is set, then the user cannot supply arbitary values, but all possible values used by MRDFITS will be allowed. STRUCTYP = The structure type. Since IDL does not allow the redefinition of a named structure it is an error to call MRD_STRUCT with different parameters but the same STRUCTYP in the same session. If this keyword is not set an anonymous structure is created. COMMON BLOCKS: MRD_COMMON SIDE EFFECTS: May create a temporary file if the structure definition is too long for the EXECUTE function and using old style structures RESTRICTIONS: By default, the program defines the structure in a long string which is executed with CREATE_STRUCT within a single EXECUTE statement. If program is being run in the IDL Virtual machine (EXECUTE statement not allowed), then a separate CREATE_STRUCT statement is called for each tag. This mode does not have the full capabilities of the normal mode, but should be sufficient for use with MRDFITS(). PROCEDURE: A structure definition is created using the parameter values. MRD_NSTRUCT is called and generates the structure in pieces using the execute and create_struct keywords. EXAMPLES: (1) str = mrd_struct(['fld1', 'fld2'], ['0','dblarr(10,10)'],3) print, str(0).fld2(3,3) Note that "0" is always considered short integer even if the default integer is set to long. (2) str = mrd_struct(['a','b','c','d'],['1', '1.', '1.d0', "'1'"],1) ; returns a structure with integer, float, double and string ; fields. PROCEDURE CALLS: GETTOK() - needed for virtual machine mode only MODIFICATION HISTORY: Created by T. McGlynn October, 1994. Modified by T. McGlynn September, 1995. Added capability to create substructures so that structure may contain up to 4096 distinct elements. [This can be increased by futher iteration of the process used if needed.] Removed V4.0 reference to common block October 1997 Allowed unlimited number of structure elements if the version is greater than 5.0. Put back in code to handle prior versions. The [] will need to be translated back to () for this to work. T. McGlynn December 15 1998. Add MRD_NSTRUCT since IDL has mysterious problems compiling very large structures. Removed TEMPDIR and OLD_STRUCT keywords W. Landsman October 2003 Alternate pathway without EXECUTE for V6.0 virtual machine, D. Lindler Removed limit on EXECUTE statement. W. Landsman October 2003 Restore EXECUTE limit (sigh...), added NO_EXECUTE keyword W. Landsman July 2004 Fix use of STRUCTYP with /NO_EXECUTE W. Landsman June 2005 Assume since V6.0 (lmgr function available), remove 131 string length limit for execute W. Landsman Jun 2009 Restore EXECUTE limit (sigh...) W. Landsman July 2009 Make sure "0" is a short integer even with compile_opt idl2 July 2010 Added "0.0", "0.0d", "0u", "0ul", and "0ull" as valid tags for /NO_EXECUTE E. Rykoff May 2012(See astrolib/pro/mrd_struct.pro)
MULTINOM
[Previous Routine] [Next Routine] [List of Routines]NAME: MULTINOM PURPOSE: SIMULATE MULTINOMIAL RANDOM VARIABLES AUTHOR : BRANDON C. KELLY, STEWARD OBS., APR 2006 INPUTS : N - THE NUMBER OF TRIALS P - A K-ELEMENT VECTOR CONTAINING THE PROBABILITIES FOR EACH CLASS. OPTIONAL INPUTS : NRAND - THE NUMBER OF RANDOM VARIABLES TO DRAW SEED - THE SEED FOR THE RANDOM NUMBER GENERATOR OUTPUT : NRAND RANDOM DRAWS FROM A MULTINOMIAL DISTRIBUTION WITH PARAMETERS N AND P.(See astrolib/pro/multinom.pro)
MULTIPLOT
[Previous Routine] [Next Routine] [List of Routines]Name: MULTIPLOT Purpose: Create multiple plots with simple control over the gaps between plots. By default, the gap is zero but this can be set with the gap= keyword, or xgap=, ygap= for individual control over different axes. You can also place a single title along the x, y and top axes of the matrix of plots using the mtitle, mxtitle and mytitle keywords. It is good for data with one or two shared axes and retains all the versatility of the plot commands (e.g. all keywords and log scaling). The plots are connected with the shared axes, which saves space by omitting redundant ticklabels and titles. Multiplot does this by setting !p.position, !x.tickname and !y.tickname automatically. A call (multiplot,/reset) restores original values. CALLING SEQUENCE: multiplot, pmulti, gap=, xgap=, ygap=, /square, /doxaxis, /doyaxis, mTitle=, mTitSize=, mTitOffset=, mxTitle=, mxTitSize=, mxTitOffset=, myTitle=, myTitSize=, myTitOffset=, xtickformat=, ytickformat= /default, /reset, /rowmajor, /initialize INPUTS: pmulti: Optional input. [Nx,Ny] array describing the shape of the matrix of plots. This is equivalent to the 2nd and 3rd elements of !p.multi. Or you can send all 5 elements of the !p.multi. KEYWORD INPUTS: gap=: Set the gap between plots in normalized units. Default is 0. This input overrides the xgap and ygap inputs. xgap=: Gap between plots in the x direction. Default 0. To set both x and y gap to the same value just use the gap keyword. ygap=: Gap between plots in the y direction. Default 0. To set both x and y gap to the same value just use the gap keyword. mTitle: A single title to go across the top of the matrix of plots, as opposed to the plot over single plots you generate with the plot command for example. mTitSize: The font size of the top title. Default is 1.25*!p.charsize mTitOffset: Offset of the title in the y-direction. mxTitle, mxTitSize, mxTitOffset: same as above but for the x-axis title myTitle, myTitSize, myTitOffset: same as above but for the y-axis title xtickformat, ytickformat: Set the default tick formats when the ticks are plotted. This allows the user to avoid sending this to each plotting command which can have unexpected results if that axis was not to get tick labels in a given point in the matrix. KEYWORDS SWITCHES: /square: Force the axis ratio of each plot to be square. Note if xgap and ygap are set to different values, this axis ratio will not be preserved. It will be preserved if gap= is used. /doxaxis: Put axis labels, etc on the axis. Default is to place labels only on the left side and bottom sides of the plot matrix, but may be useful when some cells are empty; for example the x-axis of a 2x2 grid when only 3 total plots will be created. /doyaxis: Put axis labels, etc on the yxis. Default is to place labels only on the left side and bottom sides of the plot matrix, but may be useful when some cells are empty; for example the x-axis of a 2x2 grid when only 3 total plots will be created. /rowmajor: Like setting 5th element of !p.multi to 1. /reset: Set plotting parameters to their saved values from before multiplot was initially called. /default: Set plotting parameters to IDL defaults. This is useful when the saved parameters get in a whacky state. /initialize: Just do the initialization. This is what happends when you first call multiplot anyway. EXAMPLES: ; Make an array of plots [4,3] with a gap of 0.1 (in norm. coords.) ; and overall titles along the x and y axes as given. Force the ; plots to be square. cgerase & multiplot, [4,3], /square, gap=0.1, mXtitle='R', mYtitle='F(R)' for i=0,4*3-1 do begin cgplot, struct[i].x, struct[i].y, psym=4 multiplot endfor multiplot,/reset Side Effects: Multiplot sets a number of system variables: !p.position, !p.multi, !x.tickname, !y.tickname, !P.noerase---but all can be reset with the call: multiplot,/reset Things can get out of wack if your program crashes in the middle of making a matrix of plots, and often /reset will not fix it. In those cases, calling multiplot,/default will often fix the problem. Restrictions: 1. If you use !p.multi as the method of telling how many plots are present, you have to set !p.multi at the beginning each time you use multiplot or call multiplot with the /reset keyword. 2. There is no way to make plots of different sizes; each plot covers the same area on the screen or paper. Modification history: write, 21-23 Mar 94, Fred Knight (knight@ll.mit.edu) alter plot command that sets !x.window, etc. per suggestion of Mark Hadfield (hadfield@storm.greta.cri.nz), 7 Apr 94, FKK add a /default keyword restore IDL's default values of system vars, 7 Apr 94, FKK modify two more sys vars !x(y).tickformat to suppress user-formatted ticknames, per suggestion of Mark Hadfield (qv), 8 Apr 94, FKK 2001-03-20 Added /square keyword Work in device coordinates so we can force aspect ratio to be square if requested. Erin Scott Sheldon UMichigan 2007-06-18 Can now place titles on the overall x and y axes, as well as a top title using these new keywords. mTitle=, mTitSize=, mTitOffset=, mxTitle=, mxTitSize=, mxTitOffset=, myTitle=, myTitSize=, myTitOffset=, Can also control overall tick formats. Useful because can just call multiplot initially and set this, while calling on each call to the plotting program will have unexpected results if the ticks are not to be labelled for that place in the matrix. xtickformat, ytickformat Erin Sheldon, NYU 2007-08-28: Can now add gaps between the plots with these keywords: gap=, xgap=, ygap= where the values are in normalized coordinates. Erin Sheldon, NYU 2009-11-23 Initialize common block if M[X/Y]TITLE set W. Landsman 2011-02-07 Use Coyote Graphics W. Landsman 2012-03-21 Use cgplot on initial call to get right background W.L.(See astrolib/pro/multiplot.pro)
MWRFITS
[Previous Routine] [Next Routine] [List of Routines]NAME: MWRFITS PURPOSE: Write all standard FITS data types from input arrays or structures. EXPLANATION: Must be used with a post-October 2009 version of FXADDPAR. CALLING SEQUENCE: MWRFITS, Input, Filename, [Header], /LSCALE , /ISCALE, /BSCALE, /USE_COLNUM, /Silent, /Create, /No_comment, /Version, $ Alias=, /ASCII, Separator=, Terminator=, Null=, /Logical_cols, /Bit_cols, /Nbit_cols, Group=, Pscale=, Pzero=, Status= INPUTS: Input = Array or structure to be written to FITS file. -When writing FITS primary data or image extensions input should be an array. --If data is to be grouped the Group keyword should be specified to point to a two dimensional array. The first dimension of the Group array will be PCOUNT while the second dimension should be the same as the last dimension of Input. --If Input is undefined, then a dummy primary dataset or Image extension is created [This might be done, e.g., to put appropriate keywords in a dummy primary HDU]. -When writing an ASCII table extension, Input should be a structure array where no element of the structure is a structure or array (except see below). --A byte array will be written as A field. No checking is done to ensure that the values in the byte field are valid ASCII. --Complex numbers are written to two columns with '_R' and '_I' appended to the TTYPE fields (if present). The complex number is enclosed in square brackets in the output. --Strings are written to fields with the length adjusted to accommodate the largest string. Shorter strings are blank padded to the right. -When writing a binary table extension, the input should be a structure array with no element of the structure being a substructure. If a structure is specified on input and the output file does not exist or the /CREATE keyword is specified a dummy primary HDU is created. Filename = String containing the name of the file to be written. By default MWRFITS appends a new extension to existing files which are assumed to be valid FITS. The /CREATE keyword can be used to ensure that a new FITS file is created even if the file already exists. OUTPUTS: OPTIONAL INPUTS: Header = Header should be a string array. Each element of the array is added as a row in the FITS header. No parsing is done of this data. MWRFITS will prepend required structural (and, if specified, scaling) keywords before the rows specified in Header. Rows describing columns in the table will be appended to the contents of Header. Header lines will be extended or truncated to 80 characters as necessary. If Header is specified then on return Header will have the header generated for the specified extension. OPTIONAL INPUT KEYWORDS: ALias= Set up aliases to convert from the IDL structure to the FITS column name. The value should be a STRARR(2,*) value where the first element of each pair of values corresponds to a column in the structure and the second is the name to be used in the FITS file. The order of the alias keyword is compatible with use in MRDFITS. ASCII - Creates an ASCII table rather than a binary table. This keyword may be specified as: /ASCII - Use default formats for columns. ASCII='format_string' allows the user to specify the format of various data types such using the following syntax 'column_type:format, column_type:format'. E.g., ASCII='A:A1,I:I6,L:I10,B:I4,F:G15.9,D:G23.17,C:G15.9,M:G23.17' gives the default formats used for each type. The TFORM fields for the real and complex types indicate will use corresponding E and D formats when a G format is specified. Note that the length of the field for ASCII strings and byte arrays is automatically determined for each column. BIT_COLS= An array of indices of the bit columns. The data should comprise a byte array with the appropriate dimensions. If the number of bits per row (see NBIT_COLS) is greater than 8, then the first dimension of the array should match the number of input bytes per row. BSCALE Scale floats, longs, or shorts to unsigned bytes (see LSCALE) /CREATE If this keyword is non-zero, then a new FITS file will be created regardless of whether the file currently exists. Otherwise when the file already exists, a FITS extension will be appended to the existing file which is assumed to be a valid FITS file. GROUP= This keyword indicates that GROUPed FITS data is to be generated. Group should be a 2-D array of the appropriate output type. The first dimension will set the number of group parameters. The second dimension must agree with the last dimension of the Input array. ISCALE Scale floats or longs to short integer (see LSCALE) LOGICAL_COLS= An array of indices of the logical column numbers. These should start with the first column having index *1*. The structure element should either be an array of characters with the values 'T' or 'F', or an array of bytes having the values byte('T')=84b, byte('F')=70b or 0b. The use of bytes allows the specification of undefined values (0b). LSCALE Scale floating point numbers to long integers. This keyword may be specified in three ways. /LSCALE (or LSCALE=1) asks for scaling to be automatically determined. LSCALE=value divides the input by value. I.e., BSCALE=value, BZERO=0. Numbers out of range are given the value of NULL if specified, otherwise they are given the appropriate extremum value. LSCALE=(value,value) uses the first value as BSCALE and the second as BZERO (or TSCALE and TZERO for tables). NBIT_COLS= The number of bits actually used in the bit array. This argument must point to an array of the same dimension as BIT_COLS. NO_TYPES If the NO_TYPES keyword is specified, then no TTYPE keywords will be created for ASCII and BINARY tables. No_comment Do not write comment keywords in the header NULL= Value to be written for integers/strings which are undefined or unwritable. PSCALE= An array giving scaling parameters for the group keywords. It should have the same dimension as the first dimension of Group. PZERO= An array giving offset parameters for the group keywords. It should have the same dimension as the first dimension of Group. Separator= This keyword can be specified as a string which will be used to separate fields in ASCII tables. By default fields are separated by a blank. /SILENT Suppress informative messages. Errors will still be reported. Terminator= This keyword can be specified to provide a string which will be placed at the end of each row of an ASCII table. No terminator is used when not specified. If a non-string terminator is specified (including when the /terminator form is used), a new line terminator is appended. USE_COLNUM When creating column names for binary and ASCII tables MWRFITS attempts to use structure field name values. If USE_COLNUM is specified and non-zero then column names will be generated as 'C1, C2, ... 'Cn' for the number of columns in the table. Version Print the version number of MWRFITS. OPTIONAL OUTPUT KEYWORD: Status - 0 if FITS file is successfully written, -1 if there is a a problem (e.g. nonexistent directory, or no write permission) EXAMPLE: Write a simple array: a=fltarr(20,20) mwrfits,a,'test.fits' Append a 3 column, 2 row, binary table extension to file just created. a={name:'M31', coords:(30., 20.), distance:2} a=replicate(a, 2); mwrfits,a,'test.fits' Now add on an image extension: a=lonarr(10,10,10) hdr=("COMMENT This is a comment line to put in the header", $ "MYKEY = "Some desired keyword value") mwrfits,a,'test.fits',hdr RESTRICTIONS: (1) Variable length columns are not supported for anything other than simple types (byte, int, long, float, double). (2) Empty strings are converted to 1 element blank strings (because IDL refuses to write an empty string (0b) from a structure) NOTES: This multiple format FITS writer is designed to provide a single, simple interface to writing all common types of FITS data. Given the number of options within the program and the variety of IDL systems available it is likely that a number of bugs are yet to be uncovered. PROCEDURES USED: FXPAR(), FXADDPAR MODIfICATION HISTORY: Version 0.9: By T. McGlynn 1997-07-23 Initial beta release. Dec 1, 1997, Lindler, Modified to work under VMS. Version 0.91: T. McGlynn 1998-03-09 Fixed problem in handling null primary arrays. Version 0.92: T. McGlynn 1998-09-09 Add no_comment flag and keep user comments on fields. Fix handling of bit fields. Version 0.93: T. McGlynn 1999-03-10 Fix table appends on VMS. Version 0.93a W. Landsman/D. Schlegel Update keyword values in chk_and_upd if data type has changed Version 0.94: T. McGlynn 2000-02-02 Efficient processing of ASCII tables. Use G rather than E formats as defaults for ASCII tables and make the default precision long enough that transformations binary to/from ASCII are invertible. Some loop indices made long. Fixed some ends to match block beginnings. Version 0.95: T. McGlynn 2000-11-06 Several fixes to scaling. Thanks to David Sahnow for documenting the problems. Added PCOUNT,GCOUNT keywords to Image extensions. Version numbers shown in SIMPLE/XTENSION comments Version 0.96: T. McGlynn 2001-04-06 Changed how files are opened to handle ~ consistently Version 1.0: T. McGlynn 2001-12-04 Unsigned integers, 64 bit integers. Aliases Variable length arrays Some code cleanup Version 1.1: T. McGlynn 2002-2-18 Fixed major bug in processing of unsigned integers. (Thanks to Stephane Beland) Version 1.2: Stephane Beland 2003-03-17 Fixed problem in creating dummy dataset when passing undefined data, caused by an update to FXADDPAR routine. Version 1.2.1 Stephane Beland 2003-09-10 Exit gracefully if write priveleges unavailable Version 1.3 Wayne Landsman 2003-10-24 Don't use EXECUTE() statement if on a virtual machine Version 1.3a Wayne Landsman 2004-5-21 Fix for variable type arrays Version 1.4 Wayne Landsman 2004-07-16 Use STRUCT_ASSIGN when modifying structure with pointer tags Version 1.4a Wayne Landsman 2005-01-03 Fix writing of empty strings in binary tables Version 1.4b Wayne Landsman 2006-02-23 Propagate /SILENT keyword to mwr_tablehdr Version 1.5 Wayne Landsman 2006-05-24 Open file using /SWAP_IF_LITTLE_ENDIAN keyword Convert empty strings to 1 element blank strings before writing Version 1.5a Wayne Landsman 2006-06-29 Fix problem introduced 2006-05-24 with multidimensional strings Version 1.5b K. Tolbert 2006-06-29 Make V1.5a fix work pre-V6.0 Version 1.5c I.Evans/W.Landsman 2006-08-08 Allow logical columns to be specified as bytes Version 1,5d K. Tolbert 2006-08-11 Make V1.5a fix work for scalar empty string Version 1.6 W. Landsman 2006-09-22 Assume since V5.5, remove VMS support Version 1.6a W. Landsman 2006-09-22 Don't right-justify strings Version 1.7 W. Landsman 2009-01-12 Added STATUS output keyword Version 1.7a W. Landsman 2009-04-10 Since V6.4 strings are no longer limited to 1024 elements Version 1.8 Pierre Chanial 2009-06-23 trim alias, implement logical TFORM 'L', don't add space after tform key. Version 1.9 W. Landsman 2009-07-20 Suppress compilation messages of supporting routines Version 1.10 W. Landsman 2009-09-30 Allow TTYPE values of 'T' and 'F', fix USE_COLNUM for bin tables Version 1.11 W. Landsman 2010-11-18 Allow LONG64 number of bytes, use V6.0 notation Version 1.11a W. Landsman 2012-08-12 Better documentation, error checking for logical columns Version 1.11b M. Haffner/W.L. 2012-10-12(See astrolib/pro/mwrfits.pro)
NGP
[Previous Routine] [Next Routine] [List of Routines]NAME: NGP PURPOSE: Interpolate an irregularly sampled field using Nearest Grid Point EXPLANATION: This function interpolates irregularly gridded points to a regular grid using Nearest Grid Point. CATEGORY: Mathematical functions, Interpolation CALLING SEQUENCE: Result = NGP, VALUE, POSX, NX[, POSY, NY, POSZ, NZ, /AVERAGE, /WRAPAROUND, /NO_MESSAGE] INPUTS: VALUE: Array of sample weights (field values). For e.g. a temperature field this would be the temperature and the keyword AVERAGE should be set. For e.g. a density field this could be either the particle mass (AVERAGE should not be set) or the density (AVERAGE should be set). POSX: Array of X coordinates of field samples, unit indices: [0,NX>. NX: Desired number of grid points in X-direction. OPTIONAL INPUTS: POSY: Array of Y coordinates of field samples, unit indices: [0,NY>. NY: Desired number of grid points in Y-direction. POSZ: Array of Z coordinates of field samples, unit indices: [0,NZ>. NZ: Desired number of grid points in Z-direction. KEYWORD PARAMETERS: AVERAGE: Set this keyword if the nodes contain field samples (e.g. a temperature field). The value at each grid point will then be the average of all the samples allocated to it. If this keyword is not set, the value at each grid point will be the sum of all the nodes allocated to it (e.g. for a density field from a distribution of particles). (D=0). WRAPAROUND: Set this keyword if the data is periodic and if you want the first grid point to contain samples of both sides of the volume (see below). (D=0). NO_MESSAGE: Suppress informational messages. Example of default NGP allocation: n0=4, *=gridpoint. 0 1 2 3 Index of gridpoints * * * * Grid points |---|---|---|---| Range allocated to gridpoints ([0.0,1.0> --> 0, etc.) 0 1 2 3 4 posx Example of NGP allocation for WRAPAROUND: n0=4, *=gridpoint. 0 1 2 3 Index of gridpoints * * * * Grid points |---|---|---|---|-- Range allocated to gridpoints ([0.5,1.5> --> 1, etc.) 0 1 2 3 4=0 posx OUTPUTS: Prints that a NGP interpolation is being performed of x samples to y grid points, unless NO_MESSAGE is set. RESTRICTIONS: All input arrays must have the same dimensions. Postition coordinates should be in `index units' of the desired grid: POSX=[0,NX>, etc. PROCEDURE: Nearest grid point is determined for each sample. Samples are allocated to nearest grid points. Grid point values are computed (sum or average of samples). EXAMPLE: nx = 20 ny = 10 posx = randomu(s,1000) posy = randomu(s,1000) value = posx^2+posy^2 field = ngp(value,posx*nx,nx,posy*ny,ny,/average) surface,field,/lego NOTES: Use tsc.pro or cic.pro for a higher order interpolation schemes. A standard reference for these interpolation methods is: R.W. Hockney and J.W. Eastwood, Computer Simulations Using Particles (New York: McGraw-Hill, 1981). MODIFICATION HISTORY: Written by Joop Schaye, Feb 1999. Check for LONG overflow P. Riley/W. Landsman December 1999(See astrolib/pro/ngp.pro)
NINT
[Previous Routine] [Next Routine] [List of Routines]NAME: NINT PURPOSE: Nearest integer function. EXPLANATION: NINT() is similar to the intrinsic ROUND function, with the following two differences: (1) if no absolute value exceeds 32767, then the array is returned as as a type INTEGER instead of LONG (2) NINT will work on strings, e.g. print,nint(['3.4','-0.9']) will give [3,-1], whereas ROUND() gives an error message CALLING SEQUENCE: result = nint( x, [ /LONG] ) INPUT: X - An IDL variable, scalar or vector, usually floating or double Unless the LONG keyword is set, X must be between -32767.5 and 32767.5 to avoid integer overflow OUTPUT RESULT - Nearest integer to X OPTIONAL KEYWORD INPUT: LONG - If this keyword is set and non-zero, then the result of NINT is of type LONG. Otherwise, the result is of type LONG if any absolute values exceed 32767, and type INTEGER if all all absolute values are less than 32767. EXAMPLE: If X = [-0.9,-0.1,0.1,0.9] then NINT(X) = [-1,0,0,1] PROCEDURE CALL: None: REVISION HISTORY: Written W. Landsman January 1989 Added LONG keyword November 1991 Use ROUND if since V3.1.0 June 1993 Always start with ROUND function April 1995 Return LONG values, if some input value exceed 32767 and accept string values February 1998 Use size(/TNAME) instead of DATATYPE() October 2001(See astrolib/pro/nint.pro)
NSTAR
[Previous Routine] [Next Routine] [List of Routines]NAME: NSTAR PURPOSE: Simultaneous point spread function fitting (adapted from DAOPHOT) EXPLANATION: This PSF fitting algorithm is based on a very old (~1987) version of DAOPHOT, and much better algorithms (e.g. ALLSTAR) are now available -- though not in IDL. CALLING SEQUENCE: NSTAR, image, id, xc, yc, mags, sky, group, [ phpadu, readns, psfname, magerr, iter, chisq, peak, /PRINT , /SILENT, /VARSKY, /DEBUG ] INPUTS: image - image array id - vector of stellar ID numbers given by FIND xc - vector containing X position centroids of stars (e.g. as found by FIND) yc - vector of Y position centroids mags - vector of aperture magnitudes (e.g. as found by APER) If 9 or more parameters are supplied then, upon output ID,XC,YC, and MAGS will be modified to contain the new values of these parameters as determined by NSTAR. Note that the number of output stars may be less than the number of input stars since stars may converge, or "disappear" because they are too faint. sky - vector of sky background values (e.g. as found by APER) group - vector containing group id's of stars as found by GROUP OPTIONAL INPUT: phpadu - numeric scalar giving number of photons per digital unit. Needed for computing Poisson error statistics. readns - readout noise per pixel, numeric scalar. If not supplied, NSTAR will try to read the values of READNS and PHPADU from the PSF header. If still not found, user will be prompted. psfname - name of FITS image file containing the point spread function residuals as determined by GETPSF, scalar string. If omitted, then NSTAR will prompt for this parameter. OPTIONAL OUTPUTS: MAGERR - vector of errors in the magnitudes found by NSTAR ITER - vector containing the number of iterations required for each output star. CHISQ- vector containing the chi square of the PSF fit for each output star. PEAK - vector containing the difference of the mean residual of the pixels in the outer half of the fitting circle and the mean residual of pixels in the inner half of the fitting circle OPTIONAL KEYWORD INPUTS: /SILENT - if set and non-zero, then NSTAR will not display its results at the terminal /PRINT - if set and non-zero then NSTAR will also write its results to a file nstar.prt. One also can specify the output file name by setting PRINT = 'filename'. /VARSKY - if this keyword is set and non-zero, then the sky level of each group is set as a free parameter. /DEBUG - if this keyword is set and non-zero, then the result of each fitting iteration will be displayed. PROCEDURES USED: DAO_VALUE(), READFITS(), REMOVE, SPEC_DIR(), STRN(), SXPAR() COMMON BLOCK: RINTER - contains pre-tabulated values for cubic interpolation REVISION HISTORY W. Landsman ST Systems Co. May, 1988 Adapted for IDL Version 2, J. Isensee, September, 1990 Minor fixes so that PRINT='filename' really prints to 'filename', and it really silent if SILENT is set. J.Wm.Parker HSTX 1995-Oct-31 Added /VARSKY option W. Landsman HSTX May 1996 Converted to IDL V5.0 W. Landsman September 1997 Replace DATATYPE() with size(/TNAME) W. Landsman November 2001 Assume since V5.5, remove VMS calls W. Landsman September 2006(See astrolib/pro/nstar.pro)
NULLTRIM
[Previous Routine] [Next Routine] [List of Routines]NAME: NULLTRIM PURPOSE: Trim a string of all characters after and including the first null EXPLANATION: The null character is an ascii 0b CALLING SEQUENCE: result = nulltrim( st ) INPUTS: st = input string OUTPUTS: trimmed string returned as the function value. HISTORY: D. Lindler July, 1987 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/nulltrim.pro)
NUTATE
[Previous Routine] [Next Routine] [List of Routines]NAME: NUTATE PURPOSE: Return the nutation in longitude and obliquity for a given Julian date CALLING SEQUENCE: NUTATE, jd, Nut_long, Nut_obliq INPUT: jd - Julian ephemeris date, scalar or vector, double precision OUTPUT: Nut_long - the nutation in longitude, same # of elements as jd Nut_obliq - nutation in latitude, same # of elements as jd EXAMPLE: (1) Find the nutation in longitude and obliquity 1987 on Apr 10 at Oh. This is example 22.a from Meeus IDL> jdcnv,1987,4,10,0,jul IDL> nutate, jul, nut_long, nut_obliq ==> nut_long = -3.788 nut_obliq = 9.443 (2) Plot the large-scale variation of the nutation in longitude during the 20th century IDL> yr = 1900 + indgen(100) ;Compute once a year IDL> jdcnv,yr,1,1,0,jul ;Find Julian date of first day of year IDL> nutate,jul, nut_long ;Nutation in longitude IDL> plot, yr, nut_long This plot will reveal the dominant (18.6 year) period, but a finer grid is needed to display the shorter periods in the nutation. METHOD: Uses the formula in Chapter 22 of ``Astronomical Algorithms'' by Jean Meeus (1998, 2nd ed.) which is based on the 1980 IAU Theory of Nutation and includes all terms larger than 0.0003". PROCEDURES CALLED: POLY() (from IDL User's Library) CIRRANGE, ISARRAY() (from IDL Astronomy Library) REVISION HISTORY: Written, W.Landsman (Goddard/HSTX) June 1996 Converted to IDL V5.0 W. Landsman September 1997 Corrected minor typos in values of d_lng W. Landsman December 2000 Updated typo in cdelt term December 2000 Avoid overflow for more than 32767 input dates W. Landsman January 2005(See astrolib/pro/nutate.pro)
N_BYTES()
[Previous Routine] [Next Routine] [List of Routines]NAME: N_bytes() PURPOSE: To return the total number of bytes in data element CALLING SEQUENCE: result = N_bytes(a) INPUTS: a - any idl data element, scalar or array OUTPUTS: total number of bytes in a is returned as the function value (64bit longword scalar) NOTES: (1) Not valid for object or pointer data types (2) For a string array, the number of bytes is computed after conversion with the BYTE() function, i.e. each element has the same length, equal to the maximum individual string length. MODIFICATION HISTORY: Version 1 By D. Lindler Oct. 1986 Include new IDL data types W. Landsman June 2001 Now return a 64bit integer W. Landsman April 2006(See astrolib/pro/n_bytes.pro)
OBSERVATORY
[Previous Routine] [Next Routine] [List of Routines]NAME: OBSERVATORY PURPOSE: Return longitude, latitude, altitude & time zones of an observatory EXPLANATION: Given an observatory name, returns a structure giving the longitude, latitude, altitude, and time zone CALLING SEQUENCE: Observatory, obsname, obs_struct, [ /PRINT ] INPUTS: obsname - scalar or vector string giving abbreviated name(s) of observatories for which location or time information is requested. If obsname is an empty string, then information is returned for all observatories in the database. See the NOTES: section for the list of 41 recognized observatories. The case of the string does not matter OUTPUTS: obs_struct - an IDL structure containing information on the specified observatories. The structure tags are as follows: .observatory - abbreviated observatory name .name - full observatory name .longitude - observatory longitude in degrees *west* .latitude - observatory latitude in degrees .altitude - observatory altitude in meters above sea level .tz - time zone, number of hours *west* of Greenwich OPTIONAL INPUT KEYWORD: /PRINT - If this keyword is set, (or if only 1 parameter is supplied) then OBSERVATORY will display information about the specified observatories at the terminal EXAMPLE: Get the latitude, longitude and altitude of Kitt Peak National Observatory IDL> observatory,'kpno',obs IDL> print,obs.longitude ==> 111.6 degrees west IDL> print,obs.latitude ==> +31.9633 degrees IDL> print,obs.altitude ==> 2120 meters above sea level NOTES: Observatory information is taken from noao$lib/obsdb.dat file in IRAF 2.11 Currently recognized observatory names are as follows: 'kpno': Kitt Peak National Observatory 'ctio': Cerro Tololo Interamerican Observatory 'eso': European Southern Observatory 'lick': Lick Observatory 'mmto': MMT Observatory 'cfht': Canada-France-Hawaii Telescope 'lapalma': Roque de los Muchachos, La Palma 'mso': Mt. Stromlo Observatory 'sso': Siding Spring Observatory 'aao': Anglo-Australian Observatory 'mcdonald': McDonald Observatory 'lco': Las Campanas Observatory 'mtbigelow': Catalina Observatory: 61 inch telescope 'dao': Dominion Astrophysical Observatory 'spm': Observatorio Astronomico Nacional, San Pedro Martir 'tona': Observatorio Astronomico Nacional, Tonantzintla 'Palomar': The Hale Telescope 'mdm': Michigan-Dartmouth-MIT Observatory 'NOV': National Observatory of Venezuela 'bmo': Black Moshannon Observatory 'BAO': Beijing XingLong Observatory 'keck': W. M. Keck Observatory 'ekar': Mt. Ekar 182 cm. Telescope 'apo': Apache Point Observatory 'lowell': Lowell Observatory 'vbo': Vainu Bappu Observatory 'flwo': Whipple Observatory 'oro': Oak Ridge Observatory 'lna': Laboratorio Nacional de Astrofisica - Brazil 'saao': South African Astronomical Observatory 'casleo': Complejo Astronomico El Leoncito, San Juan 'bosque': Estacion Astrofisica Bosque Alegre, Cordoba 'rozhen': National Astronomical Observatory Rozhen - Bulgaria 'irtf': NASA Infrared Telescope Facility 'bgsuo': Bowling Green State Univ Observatory 'ca': Calar Alto Observatory 'holi': Observatorium Hoher List (Universitaet Bonn) - Germany 'lmo': Leander McCormick Observatory 'fmo': Fan Mountain Observatory 'whitin': Whitin Observatory, Wellesley College 'mgio': Mount Graham International Observatory PROCEDURE CALLS: TEN() REVISION HISTORY: Written W. Landsman July 2000 Corrected sign error for 'holi' W.L/ Holger Israel Mar 2008 Correctly terminate when observatory name not recognized S. Koposov, July 2008(See astrolib/pro/observatory.pro)
ONE_ARROW
[Previous Routine] [Next Routine] [List of Routines]NAME: ONE_ARROW PURPOSE: Draws an arrow labeled with a single character on the current device EXPLANATION: ONE_ARROW is called, for example, by ARROWS to create a "weathervane" showing the N-E orientation of an image. CALLING SEQUENCE: one_arrow, xcen, ycen, angle, label, CHARSIZE = , THICK = , COLOR = ARROWSIZE=, FONT = ] INPUT PARAMETERS: xcen, ycen = starting point of arrow, floating point scalars, In device coordinates unless /DATA or /NORMAL set angle = angle of arrow in degrees counterclockwise from +X direction label = single-character label (may be blank) OUTPUT PARAMETERS: none OPTIONAL INPUT PARAMETERS: ARROWSIZE = 3-element vector defining appearance of arrow. For device coordinates the default is [30.0, 9.0, 35.0], meaning arrow is 30 pixels long; arrowhead lines 9 pixels long and inclined 35 degrees from arrow shaft. For normalized coordinates the default is divided by 512., for data coordinates the default is multiplied by (!X.crange[1] - !X.crange[0])/512.. CHARSIZE = usual IDL meaning, default = 2.0 COLOR = name or number give the color to draw the arrow. See cgCOLOR for a list of color names. /DATA - If set, then the input position (xcen, ycen) and the ARROWSIZE lengths are interpreted as being in data coordinates FONT - IDL vector font number to use (1-20). For example, to write the 'N' and 'E' characters in complex script, set font=13 /NORMAL - If set, then the input position (xcen, ycen) and the ARROWSIZE lengths are interpreted as being in normal coordinates THICK = usual IDL meaning, default = 2.0 EXAMPLE: Draw an triple size arrow emanating from the point (212,224) and labeled with the character 'S' IDL> one_arrow,212,224,270,'S',charsize=3 PROCEDURE: Calls one_ray to vector-draw arrow. MODIFICATION HISTORY: Written by R. S. Hill, Hughes STX Corp., 20-May-1992. Added font keyword, W.B. Landsman Hughes STX Corp. April 1995 Modified to work correctly for COLOR=0 J.Wm.Parker, HITC 1995 May 25 Add /NORMAL and /DATA keywords W.Landsman November 2006 Work with Coyote graphics W. Landsman February 2011(See astrolib/pro/one_arrow.pro)
ONE_RAY
[Previous Routine] [Next Routine] [List of Routines]NAME: ONE_RAY PURPOSE: Draw a line with a specified starting point, length, and angle CALLING SEQUENCE: one_ray, xcen, ycen, len, angle, terminus, /NODRAW ] INPUT PARAMETERS: xcen, ycen = starting point in device coordinates, floating point scalars len = length in pixels, device coordinates angle = angle in degrees counterclockwise from +X direction OUTPUT PARAMETERS: terminus = two-element vector giving ending point of ray in device coordinates OPTIONAL KEYWORD INPUT PARAMETERS: /nodraw if non-zero, the ray is not actually drawn, but the terminus is still calculated Any valid keyword to cgPLOTS can also be passed ot ONE_RAY. In particular, COLOR, THICK, and LINESTYLE control the color, thickness and linestyle of the drawn line. EXAMPLE: Draw a double thickness line of length 32 pixels from (256,256) 45 degrees counterclockwise from the X axis IDL> one_ray, 256, 256, 32, 45 ,term, THICK = 2 PROCEDURE: straightforward matrix arithmetic MODIFICATION HISTORY: Written by R. S. Hill, Hughes STX Corp., 20-May-1992. Modified to work correctly for COLOR=0 J.Wm.Parker HITC 1995 May 25 Added _EXTRA keywords to PLOT W. Landsman November 2006 Work with Coyote Graphcis W. Landsman February 2011(See astrolib/pro/one_ray.pro)
OPLOTERROR
[Previous Routine] [Next Routine] [List of Routines]NAME: OPLOTERROR PURPOSE: Over-plot data points with accompanying X or Y error bars. EXPLANATION: For use instead of PLOTERROR when the plotting system has already been defined. CALLING SEQUENCE: oploterror, [ x,] y, [xerr], yerr, [ /NOHAT, HATLENGTH= , ERRTHICK =, ERRSTYLE=, ERRCOLOR =, /LOBAR, /HIBAR, NSKIP = , NSUM = , /ADDCMD, ... OPLOT keywords ] INPUTS: X = array of abcissae, any datatype except string Y = array of Y values, any datatype except string XERR = array of error bar values (along X) YERR = array of error bar values (along Y) OPTIONAL INPUT KEYWORD PARAMETERS: /ADDCMD = Set this keyword if you want to add this command to a cgWindow. /NOHAT = if specified and non-zero, the error bars are drawn without hats. HATLENGTH = the length of the hat lines used to cap the error bars. Defaults to !D.X_VSIZE / 100). ERRTHICK = the thickness of the error bar lines. Defaults to the THICK plotting keyword. ERRSTYLE = the line style to use when drawing the error bars. Uses the same codes as LINESTYLE. ERRCOLOR = String (e.g. 'red') or scalar integer (0 - !D.N_TABLE) specifying the color to use for the error bars. See CGCOLOR() for a list of possible color names. See http://www.idlcoyote.com/cg_tips/legcolor.php for a warning about the use of indexed color NSKIP = Positive Integer specifying the error bars to be plotted. For example, if NSKIP = 2 then every other error bar is plotted; if NSKIP=3 then every third error bar is plotted. Default is to plot every error bar (NSKIP = 1) NSUM = Number of points to average over before plotting, default = !P.NSUM The errors are also averaged, and then divided by sqrt(NSUM). This approximation is meaningful only when the neighboring error bars have similar sizes. /LOBAR = if specified and non-zero, will draw only the -ERR error bars. /HIBAR = if specified and non-zero, will draw only the +ERR error bars. If neither LOBAR or HIBAR are set _or_ if both are set, you will get both error bars. Just specify one if you only want one set. Any valid keywords to the OPLOT command (e.g. PSYM, YRANGE) are also accepted by OPLOTERROR via the _EXTRA facility. NOTES: If only two parameters are input, they are taken as Y and YERR. If only three parameters are input, they will be taken as X, Y and YERR, respectively. EXAMPLE: Suppose one has X and Y vectors with associated errors XERR and YERR and that a plotting system has already been defined: (1) Overplot Y vs. X with both X and Y errors and no lines connecting the points IDL> oploterror, x, y, xerr, yerr, psym=3 (2) Like (1) but overplot only the Y errors bars and omits "hats" IDL> oploterror, x, y, yerr, psym=3, /NOHAT (3) Like (2) but suppose one has a positive error vector YERR1, and a negative error vector YERR2 (asymmetric error bars) IDL> oploterror, x, y, yerr1, psym=3, /NOHAT,/HIBAR IDL> oploterror, x, y, yerr2, psym=3, /NOHAT,/LOBAR PROCEDURE: A plot of X versus Y with error bars drawn from Y - YERR to Y + YERR and optionally from X - XERR to X + XERR is written to the output device WARNING: This an enhanced version of the procedure OPLOTERR in the standard RSI library. It was renamed to OPLOTERROR in June 1998 in the IDL Astronomy library. MODIFICATION HISTORY: Adapted from the most recent version of PLOTERR. M. R. Greason, Hughes STX, 11 August 1992. Added COLOR keyword option to error bars W. Landsman November 1993 Add ERRCOLOR, use _EXTRA keyword, W. Landsman, July 1995 Remove spurious call to PLOT_KEYWORDS W. Landsman, August 1995 OPLOT more than 32767 error bars W. Landsman, Feb 1996 Added NSKIP keyword W. Landsman, Dec 1996 Added HIBAR and LOBAR keywords, M. Buie, Lowell Obs., Feb 1998 Rename to OPLOTERROR W. Landsman June 1998 Ignore !P.PSYM when drawing error bars W. Landsman Jan 1999 Handle NSUM keyword correctly W. Landsman Aug 1999 Check limits for logarithmic axes W. Landsman Nov. 1999 Work in the presence of NAN values W. Landsman Dec 2000 Improve logic when NSUM or !P.NSUM is set W. Landsman Jan 2001 Remove NSUM keyword from PLOTS call W. Landsman March 2001 Only draw error bars with in XRANGE (for speed) W. Landsman Jan 2002 Fix Jan 2002 update to work with log plots W. Landsman Jun 2002 Added STRICT_EXTRA keyword W. Landsman July 2005 W. Landsman Fixed case of logarithmic axes reversed Mar 2009 Update for Coyote Graphics W. Landsman Feb. 2011 Hats were not being plotted by default W. Landsman Apr 2011 With latest CGPLOT, no need to deal special case of only a single point W. Landsman October 2012(See astrolib/pro/oploterror.pro)
ORDINAL
[Previous Routine] [Next Routine] [List of Routines]NAME: ORDINAL PURPOSE: Convert an integer to a correct English ordinal string: EXPLANATION: The first four ordinal strings are "1st", "2nd", "3rd", "4th" .... CALLING SEQUENCE: result = ordinal( num ) INPUT PARAMETERS: num = number to be made an ordinal. If float, will be FIXed. OUTPUT PARAMETERS: result = string such as '1st' '3rd' '164th' '87th', etc. MODIFICATION HISTORY: Written by R. S. Hill, STX, 8 Aug. 1991 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/ordinal.pro)
PARTVELVEC
[Previous Routine] [Next Routine] [List of Routines]NAME: PARTVELVEC PURPOSE: Plot the velocity vectors of particles at their positions EXPLANATION: This procedure plots the velocity vectors of particles (at the positions of the particles). CATEGORY: Plotting, Two-dimensional. CALLING SEQUENCE: PARTVELVEC, VELX, VELY, POSX, POSY [, X, Y] INPUTS: VELX: An array of any dimension, containing the x-components of the particle velocities. VELY: An array of the same dimension as velx, containing the y-components of the particle velocities. POSX: An array of the same dimension as velx, containing the x-components of the particle positions. POSY: An array of the same dimension as velx, containing the y-components of the particle positions. OPTIONAL INPUTS: X: Optional abcissae values. X must be a vector. Y: Optional ordinate values. Y must be a vector. If only X is specified, then Y is taken equal to be equal to X. OPTIONAL INPUT KEYWORD PARAMETERS: FRACTION: The fraction of the vectors to plot. They are taken at random from the complete sample. Default is FRACTION = 1.0, use all vectors LENGTH: The maximum vectorlength relative to the plot data window. Default = 0.08 COLOR: Color for the vectors, axes and titles by string name or number (see cgCOLOR). Note that if VECCOLORS is supplied, then the COLOR keyword still specifies the color of the axes and title. Default = 'Opposite' OVER: Plot over the previous plot VECCOLORS: The vector colors. Must be either a scalar, or a vector (nmeric or string) the same size as VELX. Set to COLOR by default. WINDOW - Set this keyword to plot to a resizeable graphics window Plot All other keywords available to cgPlot (e.g. AXISCOLOR, Keywords: LINESTYLE, XRANGE) are available (via _EXTRA) OUTPUTS: This procedure plots the velocity vectors (VELX,VELY) at the positions of the particles, (POSX,POSY). If X and Y are not specified, then the size of the plot is such that all vectors just fit within in the plot data window. SIDE EFFECTS: Plotting on the current device is performed. EXAMPLE: Generate some particle positions and velocities. POSX=RANDOMU(seed,200) POSY=RANDOMU(seed,200) VELX=RANDOMU(seed,200)-0.5 VELY=RANDOMU(seed,200)-0.5 Plot the particle velocities. PARTVELVEC, VELX, VELY, POSX, POSY Example using vector colors. POSX=RANDOMU(seed,200) POSY=RANDOMU(seed,200) VELX=RANDOMU(seed,200)-0.5 VELY=RANDOMU(seed,200)-0.5 magnitude = SQRT(velx^2 + vely^2) LOADCT, 5, NCOLORS=254, BOTTOM=1 ; Load vector colors colors = BytScl(magnitude, Top=254) + 1B PARTVELVEC, VELX, VELY, POSX, POSY, COLOR='green', VECCOLORS=colors MODIFICATION HISTORY: Written by: Joop Schaye (jschaye@astro.rug.nl), Sep 1996. Added /OVER keyword Theo Brauers (th.brauers@fz-juelich.de) Jul 2002 Added VECCOLORS keyword. David Fanning (david@dfanning.com) March, 2005 Incorporate the Coyote Graphics (cg) plot programs WL January 2011(See astrolib/pro/partvelvec.pro)
PCA
[Previous Routine] [Next Routine] [List of Routines]NAME: PCA PURPOSE: Carry out a Principal Components Analysis (Karhunen-Loeve Transform) EXPLANATION: Results can be directed to the screen, a file, or output variables See notes below for comparison with the intrinsic IDL function PCOMP. CALLING SEQUENCE: PCA, data, eigenval, eigenvect, percentages, proj_obj, proj_atr, [MATRIX =, TEXTOUT = ,/COVARIANCE, /SSQ, /SILENT ] INPUT PARAMETERS: data - 2-d data matrix, data(i,j) contains the jth attribute value for the ith object in the sample. If N_OBJ is the total number of objects (rows) in the sample, and N_ATTRIB is the total number of attributes (columns) then data should be dimensioned N_OBJ x N_ATTRIB. OPTIONAL INPUT KEYWORD PARAMETERS: /COVARIANCE - if this keyword is set, then the PCA will be carried out on the covariance matrix (rare), the default is to use the correlation matrix /SILENT - If this keyword is set, then no output is printed /SSQ - if this keyword is set, then the PCA will be carried out on on the sums-of-squares & cross-products matrix (rare) TEXTOUT - Controls print output device, defaults to !TEXTOUT textout=1 TERMINAL using /more option textout=2 TERMINAL without /more option textout=3.prt textout=4 laser.tmp textout=5 user must open file textout = filename (default extension of .prt) OPTIONAL OUTPUT PARAMETERS: eigenval - N_ATTRIB element vector containing the sorted eigenvalues eigenvect - N_ATRRIB x N_ATTRIB matrix containing the corresponding eigenvectors percentages - N_ATTRIB element containing the cumulative percentage variances associated with the principal components proj_obj - N_OBJ by N_ATTRIB matrix containing the projections of the objects on the principal components proj_atr - N_ATTRIB by N_ATTRIB matrix containing the projections of the attributes on the principal components OPTIONAL OUTPUT PARAMETER MATRIX = analysed matrix, either the covariance matrix if /COVARIANCE is set, the "sum of squares and cross-products" matrix if /SSQ is set, or the (by default) correlation matrix. Matrix will have dimensions N_ATTRIB x N_ATTRIB NOTES: This procedure performs Principal Components Analysis (Karhunen-Loeve Transform) according to the method described in "Multivariate Data Analysis" by Murtagh & Heck [Reidel : Dordrecht 1987], pp. 33-48. See http://astro.u-strasbg.fr/~fmurtagh/mda-sw/ Keywords /COVARIANCE and /SSQ are mutually exclusive. The printout contains only (at most) the first seven principle eigenvectors. However, the output variables EIGENVECT contain all the eigenvectors Different authors scale the covariance matrix in different ways. The eigenvalues output by PCA may have to be scaled by 1/N_OBJ or 1/(N_OBJ-1) to agree with other calculations when /COVAR is set. PCA uses the non-standard system variables !TEXTOUT and !TEXTUNIT. These can be added to one's session using the procedure ASTROLIB. The intrinsic IDL function PCOMP duplicates most most of the functionality of PCA, but uses different conventions and normalizations. Note the following: (1) PCOMP requires a N_ATTRIB x N_OBJ input array; this is the transpose of what PCA expects (2) PCA uses standardized variables for the correlation matrix: the input vectors are set to a mean of zero and variance of one and divided by sqrt(n); use the /STANDARDIZE keyword to PCOMP for a direct comparison. (3) PCA (unlike PCOMP) normalizes the eigenvectors by the square root of the eigenvalues. (4) PCA returns cumulative percentages; the VARIANCES keyword of PCOMP returns the variance in each variable (5) PCOMP divides the eigenvalues by (1/N_OBJ-1) when the covariance matrix is used. EXAMPLE: Perform a PCA analysis on the covariance matrix of a data matrix, DATA, and write the results to a file IDL> PCA, data, /COVAR, t = 'pca.dat' Perform a PCA analysis on the correlation matrix. Suppress all printing, and save the eigenvectors and eigenvalues in output variables IDL> PCA, data, eigenval, eigenvect, /SILENT PROCEDURES CALLED: TEXTOPEN, TEXTCLOSE REVISION HISTORY: Immanuel Freedman (after Murtagh F. and Heck A.). December 1993 Wayne Landsman, modified I/O December 1993 Fix MATRIX output, remove GOTO statements W. Landsman August 1998 Changed some index variable to type LONG W. Landsman March 2000 Fix error in computation of proj_atr, see Jan 1990 fix in http://astro.u-strasbg.fr/~fmurtagh/mda-sw/pca.f W. Landsman Feb 2008 (See astrolib/pro/pca.pro)
PENT
[Previous Routine] [Next Routine] [List of Routines]NAME: PENT PURPOSE: Return the information entropy of a time series EXPLANATION: This function will return S, the information entropy of a time series for a set of trial periods CATEGORY: Time series analysis, period finding, astronomical utilities. CALLING SEQUENCE: Result = PENT(P, T, X, [N, M ] ) INPUTS: P - array of trial period values. T - array of observation times (same units as P). X - array of observations. OPTIONAL INPUTS: N - If four parameters are given then the 4th parameter is assumed to be N. Then NxN boxes are used to calculate S. M,N - If five parameters are given then parameter 4 is M and parameter 5 is N. S is then calculated using MxN boxes - M partitions for the phase and N partitions for the data. OUTPUTS: This function returns S, the information entropy of the time series for the periods given in P as defined by Cincotta, Me'ndez & Nu'n~ez (Astrophysical Journal 449, 231-235, 1995). The minima of S occur at values of P where X shows periodicity. PROCEDURE: The procedure involves dividing the phase space into N^2 partitions (NxN boxes) and then calculating: __ N^2 S = - \ mu_i . ln(mu_i) for all mu_i <> 0 /_ i = 1 where mu_i is the number of data points in partition i normalised by the number of partitions. The option of using MxN boxes is an additional feature of this routine. EXAMPLE: To generate a similar sythetic data set to Cincotta et al. we do the following: IDL> P0 = 173.015 ; Fundamental period IDL> T = randomu(seed,400)*15000 ; 400 random observation times IDL> A0 = 14.0 ; Mean magnitude IDL> M0 = -0.5 * sin(2*!pi*T/P0) ; Fundamental mode IDL> M1 = -0.15 * sin(4*!pi*T/P0) ; 1st harmonic IDL> M2 = -0.05 * sin(6*!pi*T/P0) ; 2nd harmonic IDL> sig = randomu(seed,400)*0.03 ; noise IDL> U = A0 + M0 + M1 + M2 + sig ; Synthetic data IDL> Ptest = 100. + findgen(2000)/2. ; Trial periods IDL> S = pent(Ptest,T,U) ; Calculate S ... this takes a few seconds ... IDL> plot,Ptest,S,xtitle="P",ytitle="S" ; plot S v. P IDL> print,Ptest(where(S eq min(S))) ; Print best period (+/- 0.5) The plot produced should be similar to Fig. 2 of Cincotta et al. RESTRICTIONS: My own (limited) experience with this routine suggests that it is not as good as other techniques for finding weak, multi-periodic signals in poorly sampled data, but is good for establishing periods of eclipsing binary stars when M is quite large (try MxN = 64x16, 128x16 or even 256x16). This suggests it may be good for other periodic light curves (Cepheids, RR Lyrae etc.). I would be glad to receive reports of other peoples experience with this technique (e-mail pflm@bro730.astro.ku.dk). MODIFICATION HISTORY: Written by: Pierre Maxted, 14Sep95 Modifications: Normalisation of S corrected, T-min(T) taken out of loop. - Pierre Maxted, 15Sep95 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/pent.pro)
PERMUTE
[Previous Routine] [Next Routine] [List of Routines]NAME: PERMUTE PURPOSE: This function returns an array containing the numbers [0, ..., N-1] in random order. They are useful as indices when permuting a dataset, for example in a balanced bootstrap Monte Carlo algorithm. CATEGORY: Statistics. CALLING SEQUENCE: Result = PERMUTE(N) INPUTS: N: The number of items to be permuted. OPTIONAL INPUTS: SEED: A random number seed, see RANDOMU. OUTPUTS: This function returns an N-element array containing a random permutation of the integers from 0 through N-1. SIDE EFFECTS: Unless Seed is specified, IDL's global random number seed is changed. PROCEDURE: This is an in-place swapping algorithm. It starts with an index array. For each position in the array, it swaps the occupant of that position with the occupant of a random position from there (inclusive) to the end of the array. The last iteration is not necessary to compute, since it swaps with itself. See http://www.techuser.net/randpermgen.html for a proof. The 2-line code there has been optimized for IDL's vector architecture. This is a linear-time algorithm. EXAMPLE: Show some permutations of 6 numbers: print, permute(6) 0 2 1 3 4 5 print, permute(6) 2 4 3 5 1 0 print, permute(6) 0 4 3 1 2 5 Permute the array [2, 4, 6, 8] a = [2, 4, 6, 8] print, a[permute(4)] 4 8 6 2 Test randomness (results should be close to k): m = 6l k = 10000l n = m * k a = lonarr(m, n) for i = 0l, n-1, 1 do a[*, i] = permute(m) for i = 0l, m-1, 1 do print, histogram(a[i, *]) 9885 10062 10051 9915 10028 10059 10096 10087 10094 9913 9933 9877 10041 10013 9968 9958 9911 10109 9880 9858 10166 10049 10081 9966 10093 9915 9800 10166 9969 10057 10005 10065 9921 9999 10078 9932 Time the algorithm: maxn = 7 t = dblarr(maxn) n = 10L^(indgen(maxn)+1) for i = 0, maxn-1, 1 do begin &$ t1 = systime(/s) &$ print, n[i] &$ a = permute(n[i]) &$ t2 = systime(/s) &$ t[i] = t2-t1 &$ endfor print, ' Elements Seconds Elements Per Second' print, transpose([[n], [t], [t/n]]) Elements Seconds Elements Per Second 10.000000 0.00012397766 1.2397766e-05 100.00000 0.00015020370 1.5020370e-06 1000.0000 0.0011651516 1.1651516e-06 10000.000 0.018178225 1.8178225e-06 100000.00 0.13504505 1.3504505e-06 1000000.0 1.3817160 1.3817160e-06 10000000. 14.609985 1.4609985e-06 These times are for a 2.071 GHz AMD Athlon 2800+ CPU. MODIFICATION HISTORY: Written by: Joseph Harrington, Cornell. 2006-03-22 jh@alum.mit.edu(See astrolib/pro/permute.pro)
PIXCOLOR
[Previous Routine] [Next Routine] [List of Routines]NAME: PIXCOLOR PURPOSE: Assign colors to specified pixel values in a color lookup table EXPLANATION: Colors can be specified either from the list in cgcolor (http://www.idlcoyote.com/programs/cgcolor.pro ) or as 1 letter abbreviations for 8 common colors. CALLING SEQUENCE: PIXCOLOR, pixvalue, color ;Set color at specified pixel values INPUT PARMETERS: pixvalue - value or range of pixel values whose color will be modified. A single pixel value may be specified by an integer If a range of values is specified, then it must be written as a string, with a colon denoting the range (e.g.'102:123') If omitted, program will prompt for this parameter. OPTIONAL INPUT PARAMETER color - scalar string specifying either a full color name available in CGCOLOR, or a single character string giving one of the specified colors: 'R' (red), 'B' (blue), 'G' (green) 'Y' (yellow), 'T' (turquoise), 'V' (violet), 'W' (white) or 'D' (dark). If omitted, program will prompt for this parameter. OUTPUTS: None PROCEDURE: TVLCT is used in RGB mode to load the specified pixel values. EXAMPLE: Set pixel values of 245 to a color of red IDL> pixcolor,245,'R' Set pixel values 120 to 150 to Magenta IDL> pixcolor,'120:150','Magenta' REVISION HISTORY: Written, W. Landsman ST Systems Corp. February, 1987 Converted to IDL V5.0 W. Landsman September 1997 Allow specification of cgcolor names April 2011(See astrolib/pro/pixcolor.pro)
PIXWT
[Previous Routine] [Next Routine] [List of Routines]NAME: PIXWT PURPOSE: Circle-rectangle overlap area computation. DESCRIPTION: Compute the fraction of a unit pixel that is interior to a circle. The circle has a radius r and is centered at (xc, yc). The center of the unit pixel (length of sides = 1) is at (x, y). CATEGORY: CCD data processing CALLING SEQUENCE: area = Pixwt( xc, yc, r, x, y ) INPUTS: xc, yc : Center of the circle, numeric scalars r : Radius of the circle, numeric scalars x, y : Center of the unit pixel, numeric scalar or vector OPTIONAL INPUT PARAMETERS: None. KEYWORD PARAMETERS: None. OUTPUTS: Function value: Computed overlap area. EXAMPLE: What is the area of overlap of a circle with radius 3.44 units centered on the point 3.23, 4.22 with the pixel centered at [5,7] IDL> print,pixwt(3.23,4.22,3.44,5,7) ==> 0.6502 COMMON BLOCKS: None. PROCEDURE: Divides the circle and rectangle into a series of sectors and triangles. Determines which of nine possible cases for the overlap applies and sums the areas of the corresponding sectors and triangles. Called by aper.pro NOTES: If improved speed is needed then a C version of this routines, with notes on how to linkimage it to IDL is available at ftp://ftp.lowell.edu/pub/buie/idl/custom/ MODIFICATION HISTORY: Ported by Doug Loucks, Lowell Observatory, 1992 Sep, from the routine pixwt.c, by Marc Buie.(See astrolib/pro/pixwt.pro)
PKFIT
[Previous Routine] [Next Routine] [List of Routines]NAME: PKFIT PURPOSE: Subroutine of GETPSF to perform a one-star least-squares fit EXPLANATION: Part of the DAOPHOT PSF photometry sequence CALLING SEQUENCE: PKFIT, f, scale, x, y, sky, radius, ronois, phpadu, gauss, psf, errmag, chi, sharp, Niter, /DEBUG INPUTS: F - NX by NY array containing actual picture data. X, Y - the initial estimates of the centroid of the star relative to the corner (0,0) of the subarray. Upon return, the final computed values of X and Y will be passed back to the calling routine. SKY - the local sky brightness value, as obtained from APER RADIUS- the fitting radius-- only pixels within RADIUS of the instantaneous estimate of the star's centroid will be included in the fit, scalar RONOIS - readout noise per pixel, scalar PHPADU - photons per analog digital unit, scalar GAUSS - vector containing the values of the five parameters defining the analytic Gaussian which approximates the core of the PSF. PSF - an NPSF by NPSF look-up table containing corrections from the Gaussian approximation of the PSF to the true PSF. INPUT-OUTPUT: SCALE - the initial estimate of the brightness of the star, expressed as a fraction of the brightness of the PSF. Upon return, the final computed value of SCALE will be passed back to the calling routine. OUTPUTS: ERRMAG - the estimated standard error of the value of SCALE returned by this routine. CHI - the estimated goodness-of-fit statistic: the ratio of the observed pixel-to-pixel mean absolute deviation from the profile fit, to the value expected on the basis of the noise as determined from Poisson statistics and the readout noise. SHARP - a goodness-of-fit statistic describing how much broader the actual profile of the object appears than the profile of the PSF. NITER - the number of iterations the solution required to achieve convergence. If NITER = 25, the solution did not converge. If for some reason a singular matrix occurs during the least- squares solution, this will be flagged by setting NITER = -1. RESTRICTIONS: No parameter checking is performed REVISON HISTORY: Adapted from the official DAO version of 1985 January 25 Version 2.0 W. Landsman STX November 1988 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/pkfit.pro)
PLANCK()
[Previous Routine] [Next Routine] [List of Routines]NAME: PLANCK() PURPOSE: To calculate the Planck function in units of ergs/cm2/s/A CALLING SEQUENCE: bbflux = PLANCK( wave, temp) INPUT PARAMETERS: WAVE Scalar or vector giving the wavelength(s) in **Angstroms** at which the Planck function is to be evaluated. TEMP Scalar giving the temperature of the planck function in degree K OUTPUT PARAMETERS: BBFLUX - Scalar or vector giving the blackbody flux (i.e. !pi*Intensity) in erg/cm^2/s/A in at the specified wavelength points. EXAMPLES: To calculate the blackbody flux at 30,000 K every 100 Angstroms between 2000A and 2900 A IDL> wave = 2000 + findgen(10)*100 IDL> bbflux = planck(wave,30000) If a star with a blackbody spectrum has a radius R, and distance,d, then the flux at Earth in erg/cm^2/s/A will be bbflux*R^2/d^2 PROCEDURE: The wavelength data are converted to cm, and the Planck function is calculated for each wavelength point. See Allen (1973), Astrophysical Quantities, section 44 for more information. NOTES: See the procedure planck_radiance.pro in ftp://origin.ssec.wisc.edu/pub/paulv/idl/Radiance/planck_radiance.pro for computation of Planck radiance given wavenumber in cm-1 or wavelength in microns MODIFICATION HISTORY: Adapted from the IUE RDAF August, 1989 Converted to IDL V5.0 W. Landsman September 1997 Improve precision of constants W. Landsman January 2002(See astrolib/pro/planck.pro)
PLANET_COORDS
[Previous Routine] [Next Routine] [List of Routines]NAME: PLANET_COORDS PURPOSE: Find low or high precision RA and DEC for the planets given a date EXPLANATION: For low precision this routine uses HELIO to get the heliocentric ecliptic coordinates of the planets at the given date, then converts these to geocentric ecliptic coordinates ala "Astronomical Algorithms" by Jean Meeus (1991, p 209). These are then converted to RA and Dec using EULER. The accuracy between the years 1800 and 2050 is better than 1 arcminute for the terrestial planets, but reaches 10 arcminutes for Saturn. Before 1850 or after 2050 the accuracy can get much worse. For high precision use the /JPL option ito use the full JPL ephemeris. CALLING SEQUENCE: PLANET_COORDS, DATE, RA, DEC, [ PLANET = , /JD, /JPL] INPUTS: DATE - If /JD is not set, then date is a 3-6 element vector containing year,month (1-12), day, and optionally hour, minute, & second. If /JD is set then DATE is a Julian date. An advantage of the /JD option is that it allows the use of vector dates. OUTPUTS: RA - right ascension of planet(s), J2000 degrees, double precision DEC - declination of planet(s), J2000 degrees, double precision OPTIONAL INPUT KEYWORD: PLANET - scalar string giving name of a planet, e.g. 'venus'. Default is to compute coords for all of them (except Earth). /JD - If set, then the date parameter should be supplied as Julian date JPL - if /JPL set, then PLANET_COORDS will call the procedure JPLEPHINTERP to compute positions using the full JPL ephemeris. The JPL ephemeris FITS file JPLEPH.405 must exist in either the current directory, or in the directory specified by the environment variable ASTRO_DATA. Alternatively, the JPL keyword can be set to the full path and name of the ephemeris file. A copy of the JPL ephemeris FITS file JPLEPH.405 is available in http://idlastro.gsfc.nasa.gov/ftp/data/ EXAMPLES: (1) Find the RA, Dec of Venus on 1992 Dec 20 IDL> planet_coords, [1992,12,20], ra,dec ;Compute for all planets IDL> print,adstring(ra[1],dec[1],1) ;Venus is second planet ====> RA = 21 05 2.66 Dec = -18 51 45.7 This position is 37" from the full DE406 ephemeris position of RA = 21 05 5.24 -18 51 43.1 (2) Return the current RA and Dec of all 8 planets using JPL ephemeris IDL> get_juldate, jd ;Get current Julian Date IDL> planet_coords,jd,ra,dec,/jd,/jpl ;Find positions of all planets IDL> forprint,adstring(ra,dec,0) ;Display positions (3) Plot the declination of Mars for every day in the year 2001 IDL> jdcnv,2001,1,1,0,jd ;Get Julian date of midnight on Jan 1 Now get Mars RA,Dec for 365 consecutive days IDL> planet_coords,jd+indgen(365),ra,dec,/jd, planet = 'mars' IDL> plot,indgen(365)+1,dec NOTES: HELIO is based on the two-body problem and neglects interactions between the planets. This is why the worst results are for Saturn. Use the /JPL option or the online ephemeris generator http://ssd.jpl.nasa.gov/horizons.cgi for more accuracy. The procedure returns astrometric coordinates, i.e. no correction for aberration. A correction for light travel time is applied when /JPL is set, but not for the default low-precision calculation. PROCEDURES USED: JULDATE EULER, HELIO - if /JPL is not set JPLEPHREAD, JPLEPHINTERP - if /JPL is set REVISION HISTORY: Written P.Plait & W. Landsman August 2000 Fixed Julian date conversion W. Landsman August 2000 Added /JPL keyword W. Landsman July 2001 Allow vector Julian dates with JPL ephemeris W. Landsman December 2002(See astrolib/pro/planet_coords.pro)
PLOTERROR
[Previous Routine] [Next Routine] [List of Routines]NAME: PLOTERROR PURPOSE: Plot data points with accompanying X or Y error bars. EXPLANATION: This is a greatly enhanced version of the standard IDL Library routine PLOTERR CALLING SEQUENCE: ploterror, [ x,] y, [xerr], yerr [, TYPE=, /NOHAT, HATLENGTH= , NSUM = ERRTHICK=, ERRSTYLE=, ErrcolOR=, NSKIP=, .. PLOT keywords] INPUTS: X = array of abcissae. Y = array of Y values. XERR = array of error bar values (along X) YERR = array of error bar values (along Y) OPTIONAL INPUT KEYWORD PARAMETERS: TYPE = type of plot produced. The possible types are: TYPE = 0 : X Linear - Y Linear (default) TYPE = 1 : X Linear - Y Log TYPE = 2 : X Log - Y Linear TYPE = 3 : X Log - Y Log Actually, if 0 is specified, the XLOG and YLOG keywords are used. If these aren't specified, then a linear-linear plot is produced. This keyword is available to maintain compatibility with the previous version of PLOTERROR. /NOHAT = if specified and non-zero, the error bars are drawn without hats. HATLENGTH = the length of the hat lines in device units used to cap the error bars. Defaults to !D.X_VSIZE / 100). ERRTHICK = the thickness of the error bar lines. Defaults to the THICK plotting keyword. ERRSTYLE = the line style to use when drawing the error bars. Uses the same codes as LINESTYLE. ERRCOLOR = String (e.g. 'red') or scalar integer (0 - !D.N_TABLE) specifying the color to use for the error bars. See CGCOLOR() for a list of possible color names. See http://www.idlcoyote.com/cg_tips/legcolor.php for a warning about the use of indexed color NSKIP = Integer specifying the error bars to be plotted. For example, if NSKIP = 2 then every other error bar is plotted; if NSKIP=3 then every third error bar is plotted. Default is to plot every error bar (NSKIP = 1) NSUM = Number of points to average over before plotting, default=!P.NSUM The errors are also averaged, and then divided by sqrt(NSUM). This approximation is meaningful only when the neighboring error bars have similar sizes. PLOTERROR does not pass the NSUM keyword to the PLOT command, but rather computes the binning itself using the FREBIN function. TRADITIONAL - If set to 0 then a black plot is drawn on a white background in the graphcis window. The default value is 1, giving the traditional black background for a graphics window. WINDOW - Set this keyword to plot to a resizeable graphics window Any valid keywords to the cgPLOT command (e.g. PSYM, YRANGE, AXISCOLOR SYMCOLOR, ASPECT) are also accepted by PLOTERROR via the _EXTRA facility. RESTRICTIONS: Arrays must not be of type string, and there must be at least 1 point. If only three parameters are input, they will be taken as X, Y and YERR respectively. PLOTERROR cannot be used for asymmetric error bars. Instead use OPLOTERROR with the /LOBAR and /HIBAR keywords. Any data points with NAN values in the X, Y, or error vectors are ignored. EXAMPLE: Suppose one has X and Y vectors with associated errors XERR and YERR (1) Plot Y vs. X with both X and Y errors and no lines connecting the points IDL> ploterror, x, y, xerr, yerr, psym=3 (2) Like (1) but plot only the Y errors bars and omits "hats" IDL> ploterror, x, y, yerr, psym=3, /NOHAT WARNING: This an enhanced version of the procedure PLOTERR in the standard IDL distribution. It was renamed from PLOTERR to PLOTERROR in June 1998 in the IDL Astronomy Library to avoid conflict with the RSI procedure. PROCEDURE: A plot of X versus Y with error bars drawn from Y - YERR to Y + YERR and optionally from X - XERR to X + XERR is written to the output device PROCEDURE CALLS: cgPlot, cgPlots FREBIN - used to compute binning if NSUM keyword is present MODIFICATION HISTORY: William Thompson Applied Research Corporation July, 1986 DMS, April, 1989 Modified for Unix Michael R. Greason ST Systems May, 1991 Added most of the plotting keywords, put hats on the error bars. K. Venkatakrishna Added option to plot xerr, May, 1992 Michael R. Greason Corrected handling of reversed axes. Aug. 1992 W. Landsman Use _EXTRA keyword July 1995 W. Landsman Plot more than 32767 points Feb 1996 W. Landsman Fix Y scaling when only XRANGE supplied Nov 1996 W. Landsman Added NSKIP keyword Dec 1996 W. Landsman Use XLOG, YLOG instead of XTYPE, YTYPE Jan 1998 W. Landsman Rename to PLOTERROR, OPLOTERROR Jun 1998 W. Landsman Better default scaling when NSKIP supplied Oct 1998 W. Landsman Ignore !P.PSYM when drawing error bars Jan 1999 W. Landsman Handle NSUM keyword correctly Aug 1999 W. Landsman Fix case of /XLOG but no X error bars Oct 1999 W. Landsman Work in the presence of NAN values Nov 2000 W. Landsman Improve logic when NSUM or !P.NSUM is set Jan 2001 W. Landsman Only draw error bars with in XRANGE (for speed) Jan 2002 W. Landsman Fix Jan 2002 update to work with log plots Jun 2002 W. Landsman Added _STRICT_EXTRA Jul 2005 W. Landsman/D.Nidever Fixed case of logarithmic axes reversed Mar 2009 W. Landsman/S. Koch Allow input to be a single point Jan 2010 W. Landsman Add Coyote Graphics Feb 2011 W. Landsman Make keyword name ERRCOLOR instead of ECOLOR Speedup when no ERRCOLOR defined Feb 2011 D. Fanning Use PLOTS instead of CGPLOTS for speed Jan 2012(See astrolib/pro/ploterror.pro)
PLOTHIST
[Previous Routine] [Next Routine] [List of Routines]NAME: PLOTHIST PURPOSE: Plot the histogram of an array with the corresponding abcissa. CALLING SEQUENCE: plothist, arr, xhist, yhist, [, BIN=, /FILL, /NOPLOT, /OVERPLOT, PEAK=, /AUTOBIN, ...plotting keywords] INPUTS: arr - The array to plot the histogram of. It can include negative values, but non-integral values will be truncated. OPTIONAL OUTPUTS: xhist - X vector used in making the plot ( = lindgen( N_elements(h)) * bin + min(arr) ) yhist - Y vector used in making the plot (= histogram(arr/bin)) OPTIONAL INPUT KEYWORDS: /AUTOBIN - Automatically determines bin size of the histogram as the square root of the number of samples. Only valid when BIN is not set. AXISCOLOR - Color (string or number) of the plotting axes. BIN - The size of each bin of the histogram, scalar (not necessarily integral). If not present (or zero), the bin size is set to 1. /BOXPLOT - If set, then each histogram data value will be plotted "box style" with vertical lines drawn from Y=0 at each end of the bin width COLOR - Color (number or string) of the plotted data. See CGCOLOR for a list of available color names. /HALFBIN - Set this keyword to a nonzero value to shift the binning by half a bin size. This is useful for integer data, where e.g. the bin for values of 6 will go from 5.5 to 6.5. The default is to set the HALFBIN keyword for integer data, and not for non-integer data. /NAN - If set, then check for the occurence of IEEE not-a-number values /NOPLOT - If set, will not plot the result. Useful if intention is to only get the xhist and yhist outputs. /OVERPLOT - If set, will overplot the data on the current plot. User must take care that only keywords valid for OPLOT are used. PEAK - if non-zero, then the entire histogram is normalized to have a maximum value equal to the value in PEAK. If PEAK is negative, the histogram is inverted. /FILL - if set, will plot a filled (rather than line) histogram. /ROTATE - if set, the plot is rotated onto it's side, meaning the bars extend from left to right. Xaxis corresponds to the count within in each bin. Useful for placing a histogram plot at the side of a scatter plot, as shown at the bottom of http://www.dur.ac.uk/j.r.mullaney/pages/software.php WINDOW - Set this keyword to plot to a resizeable graphics window The following keywords take effect only if the FILL keyword is set: FCOLOR - color (string or number) to use for filling the histogram /FLINE - if set, will use lines rather than solid color for fill (see the LINE_FILL keyword in the cgcolorfill routine) FORIENTATION - angle of lines for fill (see the ORIENTATION keyword in the cgcolorfill routine) FPATTERN - the pattern to use for the fill (see the PATTERN keyword in the cgcolorfill routine) FSPACING - the spacing of the lines to use in the fill (see the SPACING keyword in the cgcolorfill routine) FTHICK - the thickness of the lines to use in the fill (see the THICK keyword in the cgcolorfill routine) Any input keyword that can be supplied to the cgPLOT procedure (e.g. XRANGE, AXISCOLOR, LINESTYLE, /XLOG, /YLOG) can also be supplied to PLOTHIST. EXAMPLE: (1) Create a vector of random 1000 values derived from a Gaussian of mean 0, and sigma of 1. Plot the histogram of these values with a binsize of 0.1, and use a box plotting style. IDL> a = randomn(seed,1000) IDL> plothist,a, bin = 0.1, /boxplot (2) As before, but fill the plot with diagonal lines at a 45 degree angle IDL> plothist,a, bin=0.1, /fill, /fline, forient=45 NOTES: David Fanning has written a similar program HISTOPLOT with more graphics options: See http://www.idlcoyote.com/programs/histoplot.pro MODIFICATION HISTORY: Written W. Landsman January, 1991 Add inherited keywords W. Landsman March, 1994 Use ROUND instead of NINT W. Landsman August, 1995 Add NoPlot and Overplot keywords. J.Wm.Parker July, 1997 Add Peak keyword. J.Wm.Parker Jan, 1998 Add FILL,FCOLOR,FLINE,FPATTERN,FSPACING keywords. J.Wm.Parker Jan, 1998 Add /NAN keyword W. Landsman October 2001 Don't plot out of range with /FILL, added HALFBIN keyword, make half bin shift default for integer only W. Landsman/J. Kurk May 2002 Add BOXPLOT keyword, use exact XRANGE as default W.L. May 2006 Allow use of /XLOG and /YLOG keywords W.L. June 2006 Adjust Ymin when /YLOG is used W. L. Sep 2007 Added AXISCOLOR keyword, fix color problem with overplots WL Nov 2007 Check when /NAN is used and all elements are NAN S. Koposov Sep 2008 Added /ROTATE keyword to turn plot on its side. J. Mullaney, 2009. Added FTHICK keyword for thickness of fill lines. L. Anderson Oct. 2010 Use Coyote Graphics W. Landsman Feb 2011 Explicit XSTYLE, YSTYLE keywords to avoid _EXTRA confusion WL. Aug 2011 Fix PLOT keyword problem with /ROTATE WL Dec 2011(See astrolib/pro/plothist.pro)
PLOTSYM
[Previous Routine] [Next Routine] [List of Routines]NAME: PLOTSYM PURPOSE: Define useful plotting symbols not in the standard !PSYM definitions. EXPLANATION: After a symbol has been defined with PLOTSYM, a plotting command should follow with either PSYM = 8 or !P.PSYM = 8 (see USERSYM) For additional rotationally symmetric plotting symbols, see VSYM.PRO Also see CGSYMCAT in the/coyote directory. CALLING SEQUENCE: PLOTSYM, PSYM,[ PSIZE, /FILL, THICK=, COLOR=] INPUTS: PSYM - The following integer values of PSYM will create the corresponding plot symbols 0 - circle 1 - downward arrow (upper limit), base of arrow begins at plot value value 2 - upward arrow (lower limt) 3 - 5 pointed star 4 - triangle 5 - upside down triangle 6 - left pointing arrow 7 - right pointing arrow 8 - square Arrows are defined such that their base begins at their origin. OPTIONAL INPUTS: PSIZE - Size of the plotting symbol in multiples of the default size (default PSIZE=1). Does not need to be an integer OPTIONAL INPUT KEYWORD: FILL - Parameter indicating whether to fill the symbol (see USERSYM) The default is 0, unfilled symbol. Does not affect arrows or character symbols. THICK - Thickness of unfilled symbols. Default is 1. COLOR - Color of the symbols, Default is !P.color OUTPUTS: None EXAMPLES: Plot Y vs. X with filled stars as the symbol, twice the default size IDL> PLOTSYM, 3 ,2, /FILL ;Plotting symbol is a filled star, ;twice default size IDL> PLOT,X,Y,PSYM=8 ;Set PSYM = 8 to get star symbol Now plot Y vs. X with an open circle as the symbol IDL> PLOTSYM, 0 ;Plotting symbol is a circle IDL> PLOT,X,Y,PSYM=8 METHOD: Appropriate X,Y vectors are used to define the symbol and passed to the USERSYM command. REVISION HISTORY Written W. Landsman June 1992 18-JAN-1996 Added a square symbol, HCW. 98Aug20 Added keyword thick parameter - RCB. April 2001 Added COLOR keyword WBL(See astrolib/pro/plotsym.pro)
POIDEV
[Previous Routine] [Next Routine] [List of Routines]NAME: POIDEV PURPOSE: Generate a Poisson random deviate EXPLANATION: Return an integer random deviate drawn from a Poisson distribution with a specified mean. Adapted from procedure of the same name in "Numerical Recipes" by Press et al. (1992), Section 7.3 NOTE: This routine became partially obsolete in V5.0 with the introduction of the POISSON keyword to the intrinsic functions RANDOMU and RANDOMN. However, POIDEV is still useful for adding Poisson noise to an existing image array, for which the coding is much simpler than it would be using RANDOMU (see example 1) CALLING SEQUENCE: result = POIDEV( xm, [ SEED = ] ) INPUTS: xm - numeric scalar, vector or array, specifying the mean(s) of the Poisson distribution OUTPUT: result - Long integer scalar or vector, same size as xm OPTIONAL KEYWORD INPUT-OUTPUT: SEED - Scalar to be used as the seed for the random distribution. For best results, SEED should be a large (>100) integer. If SEED is undefined, then its value is taken from the system clock (see RANDOMU). The value of SEED is always updated upon output. This keyword can be used to have POIDEV give identical results on consecutive runs. EXAMPLE: (1) Add Poisson noise to an integral image array, im IDL> imnoise = POIDEV( im) (2) Verify the expected mean and sigma for an input value of 81 IDL> p = POIDEV( intarr(10000) + 81) ;Test for 10,000 points IDL> print,mean(p),sigma(p) Mean and sigma of the 10000 points should be close to 81 and 9 METHOD: For small values (< 20) independent exponential deviates are generated until their sum exceeds the specified mean, the number of events required is returned as the Poisson deviate. For large (> 20) values, uniform random variates are compared with a Lorentzian distribution function. NOTES: Negative values in the input array will be returned as zeros. REVISION HISTORY: Version 1 Wayne Landsman July 1992 Added SEED keyword September 1992 Call intrinsic LNGAMMA function November 1994 Converted to IDL V5.0 W. Landsman September 1997 Use COMPLEMENT keyword to WHERE() W. Landsman August 2008(See astrolib/pro/poidev.pro)
POLINT
[Previous Routine] [Next Routine] [List of Routines]NAME: POLINT PURPOSE: Interpolate a set of N points by fitting a polynomial of degree N-1 EXPLANATION: Adapted from algorithm in Numerical Recipes, Press et al. (1992), Section 3.1. CALLING SEQUENCE POLINT, xa, ya, x, y, [ dy ] INPUTS: XA - X Numeric vector, all values must be distinct. The number of values in XA should rarely exceed 10 (i.e. a 9th order polynomial) YA - Y Numeric vector, same number of elements X - Numeric scalar specifying value to be interpolated OUTPUT: Y - Scalar, interpolated value in (XA,YA) corresponding to X OPTIONAL OUTPUT DY - Error estimate on Y, scalar EXAMPLE: Find sin(2.5) by polynomial interpolation on sin(indgen(10)) IDL> xa = indgen(10) IDL> ya = sin( xa ) IDL> polint, xa, ya, 2.5, y ,dy The above method gives y = .5988 & dy = 3.1e-4 a close approximation to the actual sin(2.5) = .5985 METHOD: Uses Neville's algorithm to iteratively build up the correct polynomial, with each iteration containing one higher order. REVISION HISTORY: Written W. Landsman January, 1992 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/polint.pro)
POLYLEG
[Previous Routine] [Next Routine] [List of Routines]NAME: POLYLEG PURPOSE: Evaluate a Legendre polynomial with specified coefficients. EXPLANATION: Meant to be used analogously to the POLY function in the IDL User's Library distribution. CALLING SEQUENCE: Result = POLYLEG( X, C ) INPUTS: X - input variable, scalar or vector C - vector of Legendre polynomial coefficients. OUTPUTS: POLYLEG returns a result equal to: C[0] + C[1]*P_1(x) + C[2]*P_2(x) + ... where P_j(x) is the jth Legendre polynomial. The output will have the same dimensions as the input X variable. EXAMPLE: If x = [0.5, 1.0] and C = [2.4, 1.3, 2.5] then print, polyleg(x, c) ====> [2.7375, 6.20] The result can be checked using the first 3 Legendre polynomial terms C[0] + C[1]*x + C[2]*(0.5*(3*x^2-1)) METHOD: Uses the recurrence relation of Legendre polynomials (n+1)*P_n+1(x) = (2n+1)*x*P_n(x) - n*P_n-1(x) evaluated with the Clenshaw recurrence formula, see Numerical Recipes by Press et al. (1992), Section 5.5 REVISION HISTORY: Written W. Landsman Hughes STX Co. April, 1995 Fixed for double precision W. Landsman May, 1997 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/polyleg.pro)
POLY_SMOOTH
[Previous Routine] [Next Routine] [List of Routines]NAME: POLY_SMOOTH PURPOSE: Apply a least-squares (Savitzky-Golay) polynomial smoothing filter EXPLANATION: Reduce noise in 1-D data (e.g. time-series, spectrum) but retain dynamic range of variations in the data by applying a least squares smoothing polynomial filter, Also called the Savitzky-Golay smoothing filter, cf. Numerical Recipes (Press et al. 1992, Sec.14.8) The low-pass filter coefficients are computed by effectively least-squares fitting a polynomial in moving window, centered on each data point, so the new value will be the zero-th coefficient of the polynomial. Approximate first derivates of the data can be computed by using first degree coefficient of each polynomial, and so on. The filter coefficients for a specified polynomial degree and window width are computed independent of any data, and stored in a common block. The filter is then convolved with the data array to result in smoothed data with reduced noise, but retaining higher order variations (better than SMOOTH). This procedure became partially obsolete in IDL V5.4 with the introduction of the SAVGOL function, which computes the smoothing coefficients. CALLING SEQUENCE: spectrum = poly_smooth( data, [ width, DEGREE = , NLEFT = , NRIGHT = DERIV_ORDER = ,COEFF = ] INPUTS: data = 1-D array, such as a spectrum or time-series. width = total number of data points to use in filter convolution, (default = 5, using 2 past and 2 future data points), must be larger than DEGREE of polynomials, and a guideline is to make WIDTH between 1 and 2 times the FWHM of desired features. OPTIONAL INPUT KEYWORDS: DEGREE = degree of polynomials to use in designing the filter via least squares fits, (default DEGREE = 2) The higher degrees will preserve sharper features. NLEFT = # of past data points to use in filter convolution, excluding current point, overrides width parameter, so that width = NLEFT + NRIGHT + 1. (default = NRIGHT) NRIGHT = # of future data points to use (default = NLEFT). DERIV_ORDER = order of derivative desired (default = 0, no derivative). OPTIONAL OUTPUT KEYWORD: COEFFICIENTS = optional output of the filter coefficients applied, but they are all stored in common block for reuse, anyway. RESULTS: Function returns the data convolved with polynomial filter coefs. EXAMPLE: Given a wavelength - flux spectrum (w,f), apply a 31 point quadratic smoothing filter and plot IDL> cgplot, w, poly_smooth(f,31) COMMON BLOCKS: common poly_smooth, degc, nlc, nrc, coefs, ordermax PROCEDURE: As described in Numerical Recipies, 2nd edition sec.14.8, Savitsky-Golay filter. Matrix of normal eqs. is formed by starting with small terms and then adding progressively larger terms (powers). The filter coefficients of up to derivative ordermax are stored in common, until the specifications change, then recompute coefficients. Coefficients are stored in convolution order, zero lag in the middle. MODIFICATION HISTORY: Written, Frank Varosi NASA/GSFC 1993. Converted to IDL V5.0 W. Landsman September 1997 Use /EDGE_TRUNCATE keyword to CONVOL W. Landsman March 2006(See astrolib/pro/poly_smooth.pro)
POSANG
[Previous Routine] [Next Routine] [List of Routines]NAME: POSANG PURPOSE: Computes rigorous position angle of source 2 relative to source 1 EXPLANATION: Computes the rigorous position angle of source 2 (with given RA, Dec) using source 1 (with given RA, Dec) as the center. CALLING SEQUENCE: POSANG, U, RA1, DC1, RA2, DC2, ANGLE INPUTS: U -- Describes units of inputs and output: 0: everything radians 1: RAx in decimal hours, DCx in decimal degrees, ANGLE in degrees RA1 -- Right ascension of point 1 DC1 -- Declination of point 1 RA2 -- Right ascension of point 2 DC2 -- Declination of point 2 OUTPUTS: ANGLE-- Angle of the great circle containing [ra2, dc2] from the meridian containing [ra1, dc1], in the sense north through east rotating about [ra1, dc1]. See U above for units. PROCEDURE: The "four-parts formula" from spherical trig (p. 12 of Smart's Spherical Astronomy or p. 12 of Green' Spherical Astronomy). EXAMPLE: For the star 56 Per, the Hipparcos catalog gives a position of RA = 66.15593384, Dec = 33.94988843 for component A, and RA = 66.15646079, Dec = 33.96100069 for component B. What is the position angle of B relative to A? IDL> RA1 = 66.15593384/15.d & DC1 = 33.95988843 IDL> RA2 = 66.15646079/15.d & DC2 = 33.96100069 IDL> posang,1,ra1,dc1,ra2,dc2, ang will give the answer of ang = 21.4 degrees NOTES: (1) If RA1,DC1 are scalars, and RA2,DC2 are vectors, then ANGLE is a vector giving the position angle between each element of RA2,DC2 and RA1,DC1. Similarly, if RA1,DC1 are vectors, and RA2, DC2 are scalars, then DIS is a vector giving the position angle of each element of RA1, DC1 and RA2, DC2. If both RA1,DC1 and RA2,DC2 are vectors then ANGLE is a vector giving the position angle between each element of RA1,DC1 and the corresponding element of RA2,DC2. If then vectors are not the same length, then excess elements of the longer one will be ignored. (2) Note that POSANG is not commutative -- the position angle between A and B is theta, then the position angle between B and A is 180+theta PROCEDURE CALLS: ISARRAY() HISTORY: Modified from GCIRC, R. S. Hill, RSTX, 1 Apr. 1998 Use V6.0 notation W.L. Mar 2011(See astrolib/pro/posang.pro)
POSITIVITY
[Previous Routine] [Next Routine] [List of Routines]NAME: POSITIVITY PURPOSE: Map an image uniquely and smoothly into all positive values. EXPLANATION: Take unconstrained x (usually an image), and map it uniquely and smoothly into positive values. Negative values of x get mapped to interval ( 0, sqrt( epsilon )/2 ], positive values go to ( sqrt( epsilon )/2, oo ) with deriv approaching 1. Derivative is always 1/2 at x=0. Derivative is used by the MRL deconvolution algorithm. CALLING SEQUENCE: result = POSITIVITY( x, [ /DERIVATIVE, EPSILON = ) INPUTS: x - input array, unconstrained OUTPUT: result = output array = ((x + sqrt(x^2 + epsilon))/2 if the /DERIV keyword is set then instead the derivative of the above expression with respect to X is returned OPTIONAL INPUT KEYWORDS: DERIV - if this keyword set, then the derivative of the positivity mapping is returned, rather than the mapping itself EPSILON - real scalar specifying the interval into which to map negative values. If EPSILON EQ 0 then the mapping reduces to positive truncation. If EPSILON LT then the mapping reduces to an identity (no change). Default is EPSILON = 1e-9 REVISION HISTORY: F.Varosi NASA/GSFC 1992, as suggested by R.Pina UCSD. Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/positivity.pro)
PRECESS
[Previous Routine] [Next Routine] [List of Routines]NAME: PRECESS PURPOSE: Precess coordinates from EQUINOX1 to EQUINOX2. EXPLANATION: For interactive display, one can use the procedure ASTRO which calls PRECESS or use the /PRINT keyword. The default (RA,DEC) system is FK5 based on epoch J2000.0 but FK4 based on B1950.0 is available via the /FK4 keyword. Use BPRECESS and JPRECESS to convert between FK4 and FK5 systems CALLING SEQUENCE: PRECESS, ra, dec, [ equinox1, equinox2, /PRINT, /FK4, /RADIAN ] INPUT - OUTPUT: RA - Input right ascension (scalar or vector) in DEGREES, unless the /RADIAN keyword is set DEC - Input declination in DEGREES (scalar or vector), unless the /RADIAN keyword is set The input RA and DEC are modified by PRECESS to give the values after precession. OPTIONAL INPUTS: EQUINOX1 - Original equinox of coordinates, numeric scalar. If omitted, then PRECESS will query for EQUINOX1 and EQUINOX2. EQUINOX2 - Equinox of precessed coordinates. OPTIONAL INPUT KEYWORDS: /PRINT - If this keyword is set and non-zero, then the precessed coordinates are displayed at the terminal. Cannot be used with the /RADIAN keyword /FK4 - If this keyword is set and non-zero, the FK4 (B1950.0) system will be used otherwise FK5 (J2000.0) will be used instead. /RADIAN - If this keyword is set and non-zero, then the input and output RA and DEC vectors are in radians rather than degrees RESTRICTIONS: Accuracy of precession decreases for declination values near 90 degrees. PRECESS should not be used more than 2.5 centuries from 2000 on the FK5 system (1950.0 on the FK4 system). EXAMPLES: (1) The Pole Star has J2000.0 coordinates (2h, 31m, 46.3s, 89d 15' 50.6"); compute its coordinates at J1985.0 IDL> precess, ten(2,31,46.3)*15, ten(89,15,50.6), 2000, 1985, /PRINT ====> 2h 16m 22.73s, 89d 11' 47.3" (2) Precess the B1950 coordinates of Eps Ind (RA = 21h 59m,33.053s, DEC = (-56d, 59', 33.053") to equinox B1975. IDL> ra = ten(21, 59, 33.053)*15 IDL> dec = ten(-56, 59, 33.053) IDL> precess, ra, dec ,1950, 1975, /fk4 PROCEDURE: Algorithm from Computational Spherical Astronomy by Taff (1983), p. 24. (FK4). FK5 constants from "Astronomical Almanac Explanatory Supplement 1992, page 104 Table 3.211.1. PROCEDURE CALLED: Function PREMAT - computes precession matrix REVISION HISTORY Written, Wayne Landsman, STI Corporation August 1986 Correct negative output RA values February 1989 Added /PRINT keyword W. Landsman November, 1991 Provided FK5 (J2000.0) I. Freedman January 1994 Precession Matrix computation now in PREMAT W. Landsman June 1994 Added /RADIAN keyword W. Landsman June 1997 Converted to IDL V5.0 W. Landsman September 1997 Correct negative output RA values when /RADIAN used March 1999 Work for arrays, not just vectors W. Landsman September 2003(See astrolib/pro/precess.pro)
PRECESS_CD
[Previous Routine] [Next Routine] [List of Routines]NAME: PRECESS_CD PURPOSE: Precess the CD (coordinate description) matrix from a FITS header EXPLANATION: The CD matrix is precessed from EPOCH1 to EPOCH2. Called by HPRECESS CALLING SEQUENCE: PRECESS_CD, cd, epoch1, epoch2, crval_old, crval_new, [/FK4] INPUTS/OUTPUT: CD - 2 x 2 CD (coordinate description) matrix in any units (degrees or radians). CD will altered on output to contain precessed values in the same units. On output CD will always be double precision no matter how input. INPUTS: EPOCH1 - Original equinox of coordinates, scalar (e.g. 1950.0). EPOCH2 - Equinox of precessed coordinates, scalar (e.g. 2000.0) CRVAL_OLD - 2 element vector containing RA and DEC in DEGREES of the reference pixel in the original equinox CRVAL_NEW - 2 elements vector giving CRVAL in the new equinox INPUT KEYWORD: /FK4 - If this keyword is set, then the precession constants are taken in the FK4 reference frame. The default is the FK5 frame. RESTRICTIONS: PRECESS_CD should not be used more than 2.5 centuries from the year 1900. PROCEDURE: Adapted from the STSDAS program FMATPREC. Precession changes the location of the north pole, and thus changes the rotation of an image from north up. This is reflected in the precession of the CD matrix. This is usually a very small change. PROCEDURE CALLS: PRECESS REVISION HISTORY: Written, Wayne Landsman, ST Systems February 1988 Fixed sign error in computation of SINRA March 1992 Added /FK4 keyword Feb 1994 Converted to IDL V5.0 W. Landsman September 1997 Use B/Jprecess for conversion between 1950 and 2000 W.L. Aug 2009(See astrolib/pro/precess_cd.pro)
PRECESS_XYZ
[Previous Routine] [Next Routine] [List of Routines]NAME: PRECESS_XYZ PURPOSE: Precess equatorial geocentric rectangular coordinates. CALLING SEQUENCE: precess_xyz, x, y, z, equinox1, equinox2 INPUT/OUTPUT: x,y,z: scalars or vectors giving heliocentric rectangular coordinates THESE ARE CHANGED UPON RETURNING. INPUT: EQUINOX1: equinox of input coordinates, numeric scalar EQUINOX2: equinox of output coordinates, numeric scalar OUTPUT: x,y,z are changed upon return NOTES: The equatorial geocentric rectangular coords are converted to RA and Dec, precessed in the normal way, then changed back to x, y and z using unit vectors. EXAMPLE: Precess 1950 equinox coords x, y and z to 2000. IDL> precess_xyz,x,y,z, 1950, 2000 HISTORY: Written by P. Plait/ACC March 24 1999 (unit vectors provided by D. Lindler) Use /Radian call to PRECESS W. Landsman November 2000 Use two parameter call to ATAN W. Landsman June 2001(See astrolib/pro/precess_xyz.pro)
PREMAT
[Previous Routine] [Next Routine] [List of Routines]NAME: PREMAT PURPOSE: Return the precession matrix needed to go from EQUINOX1 to EQUINOX2. EXPLANTION: This matrix is used by the procedures PRECESS and BARYVEL to precess astronomical coordinates CALLING SEQUENCE: matrix = PREMAT( equinox1, equinox2, [ /FK4 ] ) INPUTS: EQUINOX1 - Original equinox of coordinates, numeric scalar. EQUINOX2 - Equinox of precessed coordinates. OUTPUT: matrix - double precision 3 x 3 precession matrix, used to precess equatorial rectangular coordinates OPTIONAL INPUT KEYWORDS: /FK4 - If this keyword is set, the FK4 (B1950.0) system precession angles are used to compute the precession matrix. The default is to use FK5 (J2000.0) precession angles EXAMPLES: Return the precession matrix from 1950.0 to 1975.0 in the FK4 system IDL> matrix = PREMAT( 1950.0, 1975.0, /FK4) PROCEDURE: FK4 constants from "Computational Spherical Astronomy" by Taff (1983), p. 24. (FK4). FK5 constants from "Astronomical Almanac Explanatory Supplement 1992, page 104 Table 3.211.1. REVISION HISTORY Written, Wayne Landsman, HSTX Corporation, June 1994 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/premat.pro)
PRINT_STRUCT
[Previous Routine] [Next Routine] [List of Routines]NAME: PRINT_STRUCT PURPOSE: Print the tag values of an array of structures in nice column format. EXPLANATION: The tag names are displayed in a header line. CALLING SEQUENCE: print_struct, structure, Tags_to_print [ , title, string_matrix FILE=, LUN_OUT=, TNUMS= , TRANGE= , FRANGE=, WHICH= FORM_FLOAT =, MAX_ELEMENTS INPUTS: structure = array of structured variables Tags_to_print = string array specifying the names of tags to print. Default is to print all tags which are not arrays. OPTIONAL INPUT KEYWORDS: FILE = string, optional file name to which output will then be written. LUN_OUT = Logical unit number for output to an open file, default is to print to standard output. TNUMS = tag numbers to print (alternative to specifying tag names). TRANGE = [beg,end] tag number range to print. FRANGE = same as TRANGE. WHICH = optional array of subscripts to select which structure elements to print. FORM_FLOAT = string array of three elements specifying floating point format, ex: FORM=['f','9','2'] means "(F9.2)", (default float format is G12.4). MAX_ELEMENTS = positive integer, print only tags that have less than this number of elements (default is no screening). /NO_TITLE - If set, then the header line of tag names is not printed /STRINGS : instead of printing, return the array of strings in fourth argument of procedure: string_matrix. OUTPUTS: title = optional string, list of tags printed/processed. string_matrix = optional output of string matrix of tag values, instead of printing to terminal or file, if /STRINGS. PROCEDURE: Check the types and lengths of fields to decide formats, then loop and form text string from requested fields, then print. HISTORY: Written: Frank Varosi NASA/GSFC 1991. F.V.1993, fixed up the print formats. F.V.1994, added more keyword options. F.V.1997, added WHICH and MAX_ELEM keyword options. WBL 1997, Use UNIQ() rather than UNIQUE function Remove call to N_STRUCT() W. Landsman March 2004 Avoid overflow with more than 10000 elements W. Landsman Nov 2005 Really remove call to N_STRUCT() W. Landsman July 2009(See astrolib/pro/print_struct.pro)
PROB_KS
[Previous Routine] [Next Routine] [List of Routines]NAME: PROB_KS PURPOSE: Return the significance of the Kolmogoroff-Smirnov statistic EXPLANATION: Returns the significance level of an observed value of the Kolmogorov-Smirnov statistic D for an effective number of data points N_eff. Called by KSONE and KSTWO CALLING SEQUENCE: prob_ks, D, N_eff, probks INPUT PARAMATERS: D - Kolmogorov statistic, floating scalar, always non-negative N_eff - Effective number of data points, scalar. For a 2 sided test this is given by (N1*N2)/(N1+N2) where N1 and N2 are the number of points in each data set. OUTPUT PARAMETERS: probks - floating scalar between 0 and 1 giving the significance level of the K-S statistic. Small values of PROB suggest that the distribution being tested are not the same REVISION HISTORY: Written W. Landsman August, 1992 Corrected typo (termbv for termbf) H. Ebeling/W.Landsman March 1996 Probably did not affect numeric result, but iteration went longer than necessary Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/prob_ks.pro)
PROB_KUIPER
[Previous Routine] [Next Routine] [List of Routines]NAME: PROB_KUIPER PURPOSE: Return the significance of the Kuiper statistic EXPLANATION: Returns the significance level of an observed value of the Kuiper statistic D for an effective number of data points N_eff. Called by KUIPERONE CALLING SEQUENCE: prob_kuiper, D, N_eff, probks INPUT PARAMATERS: D - Kuiper statistic, floating scalar, always non-negative N_eff - Effective number of data points, scalar. For a 2 sided test this is given by (N1*N2)/(N1+N2) where N1 and N2 are the number of points in each data set. OUTPUT PARAMETERS: probks - floating scalar between 0 and 1 giving the significance level of the Kuiper statistic. Small values of PROB suggest that the distribution being tested are not the same REVISION HISTORY: Written W. Landsman August, 1992 Corrected typo (termbv for termbf) H. Ebeling/W.Landsman March 1996 Probably did not affect numeric result, but iteration went longer than necessary Converted to IDL V5.0 W. Landsman September 1997 Adapted from PROB_KS J. Ballet July 2003(See astrolib/pro/prob_kuiper.pro)
PSF_GAUSSIAN
[Previous Routine] [Next Routine] [List of Routines]NAME: PSF_GAUSSIAN PURPOSE: Create a 1-d, 2-d, or 3-d Gaussian with specified FWHM, center EXPLANATION: Return a point spread function having Gaussian profiles, as either a 1D vector, a 2D image, or 3D volumetric-data. CALLING SEQUENCE: psf = psf_Gaussian( NPIXEL=, FWHM= , CENTROID = [ /DOUBLE, /NORMALIZE, ST_DEV=, NDIMEN= ] ) or: psf = psf_Gaussian( parameters, NPIXEL = ,NDIMEN = ) REQUIRED INPUT KEYWORD: NPIXEL = number pixels for each dimension, specify as an array, or just one number to make all sizes equal. OPTIONAL KEYWORDS: CENTROID = floating scalar or vector giving position of PSF center. default is exact center of requested vector/image/volume. The number of elements in CENTROID should equal the number of dimensions. **The definition of Centroid was changed in March 2002, and now an integer defines the center of a pixel.** /DOUBLE = If set, then the output array is computed in double precision the default is to return a floating point array. FWHM = the desired Full-Width Half-Max (pixels) in each dimension, specify as an array, or single number to make all the same. NDIMEN = integer dimension of result: either 1 (vector), 2 (image), or 3 (volume), default = 2 (an image result). /NORMALIZE causes resulting PSF to be normalized so Total( psf ) = 1. ST_DEV = optional way to specify width by standard deviation param. Ignored if FWHM is specified. XY_CORREL = scalar between 0 and 1 specifying correlation coefficient Use this keyword, for example, to specify an elliptical Gaussian oriented at an angle to the X,Y axis. Only valid for 2-dimensional case. INPUTS (optional): parameters = an NDIMEN by 3 array giving for each dimension: [ maxval, center, st_dev ], overrides other keywords. EXAMPLE: (1) Create a 31 x 31 array containing a normalized centered Gaussian with an X FWHM = 4.3 and a Y FWHM = 3.6 IDL> array = PSF_GAUSSIAN( Npixel=31, FWHM=[4.3,3.6], /NORMAL ) (2) Create a 50 pixel 1-d Gaussian vector with a maximum of 12, centered at pixel 23 with a sigma of 19.2 IDL> psf = psf_gaussian([12,23,19.2],npixel=50) EXTERNAL CALLS: function Gaussian() NOTES: To improve speed, floating underflow exceptions are suppressed (using the MASK=32 keyword of CHECK_MATH() rather than being flagged. HISTORY: Written, Frank Varosi NASA/GSFC 1991. Suppress underflow messages, add DOUBLE keyword. **Modified centroid definition so integer position is pixel center** W. Landsman March 2002 Allow use of the ST_DEV (not STDEV) keyword W. Landsman Nov. 2002 Do not modify NPIXEL input keyword W. Landsman(See astrolib/pro/psf_gaussian.pro)
PUTAST
[Previous Routine] [Next Routine] [List of Routines]NAME: PUTAST PURPOSE: Put WCS astrometry parameters into a given FITS header. CALLING SEQUENCE: putast, hdr ;Prompt for all values or putast, hdr, astr, [EQUINOX =, CD_TYPE =, ALT= , NAXIS=] or putast, hdr, cd,[ crpix, crval, ctype], [ EQUINOX =, CD_TYPE =, ALT= ] INPUTS: HDR - FITS header, string array. HDR will be updated to contain the supplied astrometry. ASTR - IDL structure containing values of the astrometry parameters CDELT, CRPIX, CRVAL, CTYPE, LONGPOLE, and PV2 See EXTAST.PRO for more info about the structure definition or CD - 2 x 2 array containing the astrometry parameters CD1_1 CD1_2 CD2_1 CD2_2 in units of DEGREES/PIXEL CRPIX - 2 element vector giving X and Y coord of reference pixel BE SURE THE COORDINATES IN CRPIX ARE GIVEN IN FITS STANDARD (e.g. first pixel in image is [1,1] ) AND NOT IDL STANDARD (first pixel in image is [0,0] CRVAL - 2 element vector giving R.A. and DEC of reference pixel in degrees CTYPE - 2 element string vector giving projection types for the two axes. For example, to specify a tangent projection one should set ctype = ['RA---TAN','DEC--TAN'] OUTPUTS: HDR - FITS header now contains the updated astrometry parameters A brief HISTORY record is also added. OPTIONAL KEYWORD INPUTS: ALT - single character 'A' through 'Z' or ' ' specifying an alternate astrometry system to write in the FITS header. The default is to write primary astrometry or ALT = ' '. If /ALT is set, then this is equivalent to ALT = 'A'. See Section 3.3 of Greisen & Calabretta (2002, A&A, 395, 1061) for information about alternate astrometry keywords. CD_TYPE - Integer scalar, either 0, 1 or 2 specifying how the CD matrix is to be written into the header (0) write PCn_m values along with CDELT values (1) convert to rotation and write as a CROTA2 value (+ CDELT) (2) as CDn_m values (IRAF standard) All three forms are valid representations according to Greisen & Calabretta (2002, A&A, 395, 1061), also available at http://fits.gsfc.nasa.gov/fits_wcs.html ) although form (0) is preferred. Form (1) is the former AIPS standard and is now deprecated and cannot be used if any skew is present. If CD_TYPE is not supplied, PUTAST will try to determine the type of astrometry already in the header. If there is no astrometry in the header then the default is CD_TYPE = 2. EQUINOX - numeric scalar giving the year of equinox of the reference coordinates. Default (if EQUINOX keyword is not already present in header) is 2000. NAXIS - By default, PUTAST does not update the NAXIS keywords in the FITS header. If NAXIS is set, and an astrometry structure is supplied then the NAXIS1 and NAXIS2 keywords in the FITS header will be updated with the .NAXIS structure tags values. If an astrometry structure is not supplied, then one can set NAXIS to a two element vector to update the NAXIS1, NAXIS2 keywords. NOTES: The recommended use of this procedure is to supply an astrometry structure. PUTAST does not delete astrometry parameters already present in the header, unless they are explicity overwritten. As of April 2012, PUTAST will add SIP ( http://fits.gsfc.nasa.gov/registry/sip.html ) distortion parameters to a FITS header if present in the astrometry structure. PROMPTS: If only a header is supplied, the user will be prompted for a plate scale, the X and Y coordinates of a reference pixel, the RA and DEC of the reference pixel, the equinox of the RA and Dec and a rotation angle. PROCEDURES USED: ADD_DISTORT, GETOPT(), GET_COORDS, GET_EQUINOX, SXADDPAR, SXPAR(), TAG_EXIST(), ZPARCHECK REVISION HISTORY: Written by W. Landsman 9-3-87 Major rewrite, use new astrometry structure March, 1994 Use both CD and CDELT to get plate scale for CD_TYPE=1 September 1995 Use lower case for FITS keyword Comments W.L. March 1997 Fixed for CD_TYPE=1 and CDELT = [1.0,1.0] W.L September 1997 Default value of CD_TYPE is now 2, Use GET_COORDS to read coordinates to correct -0 problem W.L. September 1997 Update CROTA1 if it already exists W.L. October 1997 Convert rotation to degrees for CD_TYPE = 1 W. L. June 1998 Accept CD_TYPE = 0 keyword input W.L October 1998 Remove reference to obsolete !ERR W.L. February 2000 No longer support CD001001 format, write default tangent CTYPE value consistent conversion between CROTA and CD matrix W.L. October 2000 Use GET_EQUINOX to get equinox value W.L. January 2001 Update CTYPE keyword if previous value is 'LINEAR' W.L. July 2001 Use SIZE(/TNAME) instead of DATATYPE() W.L. November 2001 Allow direct specification of CTYPE W.L. June 2002 Don't assume celestial coordinates W. Landsman April 2003 Make default CD_TYPE = 2 W. Landsman September 2003 Add projection parameters, e.g. PV2_1, PV2_2 if present in the input structure W. Landsman May 2004 Correct interactive computation of image center W. Landsman Feb. 2005 Don't use CROTA (CD_TYPE=1) if a skew exists W. Landsman May 2005 Added NAXIS keyword W. Landsman January 2007 Update PC matrix, if CD_TYPE=0 and CD matrix supplied W.L. July 2007 Don't write PV2 keywords for WCS types that don't use it W.L. Aug 2011 Add SIP distortion parameters if present W.L. April 2012 Work if empty distortion structure present W.L. November 2012(See astrolib/pro/putast.pro)
QDCB_GRID
[Previous Routine] [Next Routine] [List of Routines]NAME: QDCB_GRID PURPOSE: Produce an overlay of latitude and longitude lines over a plot or image EXPLANATION: Grid is plotted on the current graphics device assuming that the current plot is a map in the so called quad cube projection. The output plot range is assumed to go from 7.0 to -1.0 on the X axis and -3.0 to 3.0 on the Y axis. Within this plotting space, the quad cube faces are laid out as follows (X=Empty, Astronomical Layout shown - X axis can be swapped for geographic maps): 3.0_ XXX0 4321 -3.0_XXX5 | | 7.0 -1.0 CATEGORY: Mapping Support Routine CALLING SEQUENCE: QDCB_GRID,[,DLONG,DLAT,[LINESTYLE=N,/LABELS] INPUT PARAMETERS: 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. OPTIONAL KEYWORD PARAMETERS: 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. OUTPUT PARAMETERS: NONE PROCEDURE: Uses WCSSPH2XY.PRO with projection 23 ("QSC" - COBE Quadrilatieralized Spherical Cube) to compute positions of grid lines and labels. COPYRIGHT NOTICE: Copyright 1991, The Regents of the University of California. This software was produced under U.S. Government contract (W-7405-ENG-36) by Los Alamos National Laboratory, which is operated by the University of California for the U.S. Department of Energy. The U.S. Government is licensed to use, reproduce, and distribute this software. Neither the Government nor the University makes any warranty, express or implied, or assumes any liability or responsibility for the use of this software. AUTHOR: Jeff Bloch MODIFICATIONS/REVISION LEVEL: %I% %G% Use WCSSPH2XY instead of QDCB Wayne Landsman December 1994 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/qdcb_grid.pro)
QGET_STRING
[Previous Routine] [Next Routine] [List of Routines]NAME: QGET_STRING PURPOSE: To get a string from the keyboard without echoing it to the screen. CALLING SEQUENCE: string = QGET_STRING() INPUTS: None. OUTPUTS: string The string read from the keyboard. SIDE EFFECTS: A string variable is created and filled. PROCEDURE: The IDL GET_KBRD functions is used to get each character in the string. Each character is added to the string until a carriage return is struck. The carriage return is not appended to the string. Striking the delete key or the backspace key removes the previous character from the string. NOTES: For a widget password procedure see http://idlcoyote.com/tip_examples/password.pro MODIFICATION HISTORY: Written by Michael R. Greason, STX, 8 January 1991. Work for Mac and Windows IDL W. Landsman September 1995(See astrolib/pro/qget_string.pro)
QSIMP
[Previous Routine] [Next Routine] [List of Routines]NAME: QSIMP PURPOSE: Integrate using Simpson's rule to specified accuracy. EXPLANATION: Integrate a function to specified accuracy using the extended trapezoidal rule. Adapted from algorithm in Numerical Recipes, by Press et al. (1992, 2nd edition), Section 4.2. This procedure has been partly obsolete since IDL V3.5 with the introduction of the intrinsic function QSIMP(), but see notes below. CALLING SEQUENCE: QSIMP, func, A, B, S, [ EPS = , MAX_ITER =, _EXTRA = ] INPUTS: func - scalar string giving name of function of one variable to be integrated A,B - numeric scalars giving the lower and upper bound of the integration OUTPUTS: S - Scalar giving the approximation to the integral of the specified function between A and B. OPTIONAL KEYWORD PARAMETERS: EPS - scalar specifying the fractional accuracy before ending the iteration. Default = 1E-6 MAX_ITER - Integer specifying the total number iterations at which QSIMP will terminate even if the specified accuracy has not yet been met. The maximum number of function evaluations will be 2^(MAX_ITER). Default value is MAX_ITER = 20 Any other keywords are passed directly to the user-supplied function via the _EXTRA facility. NOTES: (1) The function QTRAP is robust way of doing integrals that are not very smooth. However, if the function has a continuous 3rd derivative then QSIMP will likely be more efficient at performing the integral. (2) QSIMP can be *much* faster than the intrinsic QSIMP() function (as of IDL V7.1). This is because the intrinsic QSIMP() function only requires that the user supplied function accept a *scalar* variable. Thus on the the 16th iteration, the intrinsic QSIMP() makes 32,767 calls to the user function, whereas this procedure makes one call with a 32,767 element vector. Also, unlike the intrinsic QSIMP(), this procedure allows keywords in the user-supplied function. (3) Since the intrinsic QSIMP() is a function, and this file contains a procedure, there should be no name conflict. EXAMPLE: Compute the integral of sin(x) from 0 to !PI/3. IDL> QSIMP, 'sin', 0, !PI/3, S & print, S The value obtained should be cos(!PI/3) = 0.5 PROCEDURES CALLED: TRAPZD, ZPARCHECK REVISION HISTORY: W. Landsman ST Systems Co. August, 1991 Continue after max iter warning message W. Landsman March, 1996 Converted to IDL V5.0 W. Landsman September 1997 Pass keyword to function via _EXTRA facility W. Landsman July 1999(See astrolib/pro/qsimp.pro)
QTRAP
[Previous Routine] [Next Routine] [List of Routines]NAME: QTRAP PURPOSE: Integrate using trapezoidal rule to specified accuracy. EXPLANATION: Integrate a function to specified accuracy using the extended trapezoidal rule. Adapted from Numerical Recipes (1992, 2nd edition), Section 4.2. CALLING SEQUENCE: QTRAP, func, A, B, S, [EPS = , MAX_ITER =, _EXTRA = ] INPUTS: func - scalar string giving name of function of one variable to be integrated A,B - numeric scalars giving the lower and upper bound of the integration OUTPUTS: S - Scalar giving the approximation to the integral of the specified function between A and B. OPTIONAL KEYWORD PARAMETERS: EPS - scalar specify the fractional accuracy before ending the iteration. Default = 1E-6 MAX_ITER - Integer specifying the total number iterations at which QTRAP will terminate even if the specified accuracy has not yet been met. The maximum number of function evaluations will be 2^(MAX_ITER). Default value is MAX_ITER = 20 Any other keywords are passed directly to the user-supplied function via the _EXTRA facility. NOTES: QTRAP is robust way of doing integrals that are not very smooth. If the function has a continuous 3rd derivative then the function QSIMP will likely be more efficient at performing the integral. EXAMPLE: Compute the integral of sin(x) from 0 to !PI/3. IDL> QTRAP, 'sin', 0, !PI/3, S & print,S The value obtained should be cos(!PI/3) = 0.5 PROCEDURES CALLED: TRAPZD, ZPARCHECK REVISION HISTORY: W. Landsman ST Systems Co. August, 1991 Continue after Max Iter warning message, W. Landsman March 1996 Converted to IDL V5.0 W. Landsman September 1997 Pass keyword to function via _EXTRA facility W. Landsman July 1999(See astrolib/pro/qtrap.pro)
QUADTERP
[Previous Routine] [Next Routine] [List of Routines]NAME: QUADTERP PURPOSE: Quadratic interpolation of X,Y vectors onto a new X grid EXPLANATION: Interpolate a function Y = f(X) at specified grid points using an average of two neighboring 3 point quadratic (Lagrangian) interpolants. Use LINTERP for linear interpolation CALLING SEQUENCE: QUADTERP, Xtab, Ytab, Xint, Yint, [ MISSING = ] INPUT: Xtab - Vector (X TABle) containing the current independent variable Must be either monotonic increasing or decreasing Ytab - Vector (Y TABle) containing the dependent variable defined at each of the points of XTAB. Xint - Scalar or vector giving the values of X for which interpolated Y values are sought OUTPUT: Yint - Interpolated value(s) of Y, same number of points as Xint OPTIONAL INPUT KEYWORD: MISSING - Scalar specifying Yint value(s) to be assigned, when Xint value(s) are outside of the range of Xtab. Default is to truncate the out of range Yint value(s) to the nearest value of Ytab. See the help for the INTERPOLATE function. METHOD: 3-point Lagrangian interpolation. The average of the two quadratics derived from the four nearest points is returned in YTAB. A single quadratic is used near the end points. VALUE_LOCATE is used to locate center point of the interpolation. NOTES: QUADTERP provides one method of high-order interpolation. The RSI interpol.pro function includes the following alternatives: interpol(/LSQUADRATIC) - least squares quadratic fit to a 4 pt neighborhood interpol(/QUADRATIC) - quadratic fit to a 3 pt neighborhood interpol(/SPLINE) - cubic spline fit to a 4 pt neighborhood Also, the IDL Astro function HERMITE fits a cubic polynomial and its derivative to the two nearest points. RESTRICTIONS: Unless MISSING keyword is set, points outside the range of Xtab in which valid quadratics can be computed are returned at the value of the nearest end point of Ytab (i.e. Ytab[0] and Ytab[NPTS-1] ). EXAMPLE: A spectrum has been defined using a wavelength vector WAVE and a flux vector FLUX. Interpolate onto a new wavelength grid, e.g. IDL> wgrid = [1540.,1541.,1542.,1543.,1544.,1545.] IDL> quadterp, wave, flux, wgrid, fgrid FGRID will be a 5 element vector containing the quadratically interpolated values of FLUX at the wavelengths given in WGRID. EXTERNAL ROUTINES: ZPARCHECK REVISION HISTORY: 31 October 1986 by B. Boothman, adapted from the IUE RDAF 12 December 1988 J. Murthy, corrected error in Xint September 1992, W. Landsman, fixed problem with double precision August 1993, W. Landsman, added MISSING keyword June, 1995, W. Landsman, use single quadratic near end points Converted to IDL V5.0 W. Landsman September 1997 Fix occasional problem with integer X table, YINT is a scalar if XINT is a scalar W. Landsman Dec 1999 Use VALUE_LOCATE instead of TABINV W. Landsman Feb. 2000(See astrolib/pro/quadterp.pro)
QUERYDSS
[Previous Routine] [Next Routine] [List of Routines]NAME: QueryDSS PURPOSE: Query the digital sky survey (DSS) on-line at the STSCI (or ESO) server EXPLANATION: The script can query the DSS survey and retrieve an image and FITS header either from the the Space Telescope Science Institute (STScI) or European Space Observatory (ESO) servers. See http://archive.eso.org/dss/dss and/or http://archive.stsci.edu/dss/index.html for details. CALLING SEQUENCE: QueryDSS, targetname_or_coords, Im, Hdr, [IMSIZE= , /ESO, Outfile= ] INPUTS: TARGETNAME_OR_COORDS - Either a scalar string giving a target name, (with J2000 coordinates determined by SIMBAD (default) or NED), or a 2-element numeric vector giving the J2000 right ascension in *degrees* and the target declination in degrees. OPTIONAL INPUTS: None OPTIONAL KEYWORD PARAMETERS: ImSize - Numeric scalar giving size of the image to be retrieved in arcminutes. Default is 10 arcminute. /ESO - Use the ESO server for image retrieval. Default is to use the STScI server /NED - Query the Nasa Extragalactic Database (NED) for the target's coordinates. The default is to use Simbad for the target search. OUTPUT - scalar string specifying name of output FITS file. If set, then the output IDL variables are not used. /STSCI - obsolete keyword, now does nothing, since STSCI is the default Server. SURVEY - Scalar string specifying which survey to retrieve. Possible values are '1' - First generation (red), this is the default '2b' - Second generation blue '2r' - Second generation red '2i' - Second generation near-infrared Note that 2nd generation images may not be available for all regions of the sky. Also note that the first two letters of the 'REGION' keyword in the FITS header gives the bandpass 'XP' - Red IIIaF, 'XJ' - Blue IIIaJ, 'XF' - Near-IR IVN /VERBOSE - If set, then the query sent to the DSS server is displayed OUTPUTS: Im - The image returned by the server. If there is an error, this contains a single 0. Hdr - The FITS header of the image. Empty string in case of errors. If the OutFile keyword is set then no outputs are returned (only the file is written). SIDE EFFECTS: If Im and Hdr exist in advance, they are overwritten. RESTRICTIONS: Relies on a working network connection. PROCEDURE: Construct a query-url, call WEBGET() and sort out the server's answer. EXAMPLE: Retrieve an 10' image surrounding the ultracompact HII region G45.45+0.06. Obtain the 2nd generation blue image. IDL> QueryDSS, 'GAL045.45+00.06', image, header, survey = '2b' IDL> tvscl, image IDL> hprint, header IDL> writefits,'dss_image.fits', image, header Note that the coordinates could have been specified directly, rather than giving the target name. IDL> QueryDSS, [288.587, 11.1510], image, header,survey='2b' To write a file directly to disk, use the OutFile keyword IDL> QueryDSS, [288.587, 11.1510], survey='2b', out='gal045_2b.fits' PROCEDURES CALLED: QUERYSIMBAD, WEBGET() MODIFICATION HISTORY: Written by M. Feldt, Heidelberg, Oct 2001Option to supply target name instead of coords W. Landsman Aug. 2002 Added OUTFILE, /NED keywords W. Landsman April 2003 Don't abort on Simbad failure W. Landsman/J. Brauher June 2003 Added /VERBOSE keyword W. Landsman Jan 2009 Make /STScI server the default W. Landsman June 2010 Fix OUTPUT option W. Landsman June 2010 (See astrolib/pro/querydss.pro)
QUERYGSC
[Previous Routine] [Next Routine] [List of Routines]NAME: QUERYGSC PURPOSE: Query the Guide Star Catalog (GSC V2.3.2) at STScI by position EXPLANATION: Uses the IDL SOCKET command to query the GSC 2.3.2 database over the Web. Alternatively, (and more reliably) one can query the GSC 2.3.2 catalog using queryvizier.pro and the VIZIER database, e.g. IDL> st = queryvizier('GSC2.3',[23,35],10,/all) GSC2.3 is an all-sky export of calibrated photographic survey plate source parameters from the COMPASS database. The number of unique objects is approximately 945,592,683. All sources are from the second-generation plate-processing pipeline with the exception of Tycho-2 and Skymap sources in the case of very bright objects. The Skymap sources are exported when there is no matching GSC or Tycho sources. Each GSC 2.3 entry contains only one position and one magnitude per bandpass for each unique sky object CALLING SEQUENCE: info = QueryGSC(targetname_or_coords, [ dis, /HOURS] ) INPUTS: TARGETNAME_OR_COORDS - Either a scalar string giving a target name, (with J2000 coordinates determined by SIMBAD), or a 2-element numeric vector giving the J2000 right ascension in *degrees* (or hours if /HOURS is set) and the target declination in degrees. OPTIONAL INPUT: dis - Numeric scalar giving search radius in arcminutes to search around specified target Default is 5 arcminutes OPTIONAL INPUT KEYWORDS: /BOX - if set, then radius gives a box width in arcminutes /HOURS - If set, then the right ascension is both input and output (in the info .ra tag) in hours instead of degrees /VERBOSE - If set, then the CGI command to the Webserver will be displayed ; OUTPUTS: info - IDL structure containing information on the GSC stars within the specified distance of the specified center. There are (currently) 23 tags in this structure -- for further information see http://gsss.stsci.edu/Catalogs/GSC/GSC2/gsc23/gsc23_release_notes.htm .HSTID - GSC 2.3 name for HST operations .GSC1ID - GSC1 name .RA,.DEC - Position in degrees (double precision). RA is given in hours if the /HOURS keyword is set. .RAERR, .DECERR - uncertainty (in arcseconds) in the RA and Dec .EPOCH - mean epoch of the observation .FPGMAG, .FPGERR - magnitude and error in photographic F .JPGMAG, .JPGERR - magnitude and error in photographic J .VPGMAG, .VPGERR - V magnitude and error .NPGMAG, .NPGERR - magnitude and error .UMAG, .UERR - magnitude and error .BMAG, .BERR - magnitude and error .VMAG, .VERR - magnitude and error .RMAG, .RERR - magnitude and error .IMAG, .IERR - magnitude and error .JMAG, .JERR - magnitude and error .HMAG, .HERR - magnitude and error .KMAG, .KERR - magnitude and error .A - semi-major axis in pixels .PA - Position angle of extended objects in degrees .E - eccentricity of extended objects .CLASS - classification (0-5): 0-star, 1-galaxy, 2-blend, 3-nonstar, 4-unclassified, 5-defect .STATUS -10 digit field used to encode more detailed information about the properties of the catalog object. For more info, see http://www-gsss.stsci.edu/Catalogs/GSC/GSC2/gsc23/gsc23_release_notes.htm#ClassificationCodes .VFLAG, MFLAG - Variability nad multiplicity flags .FPGBAND, .NPGBAND, .JPGBAND. UBAND, BBAND, .VBAND - flag as to wether given bandpass is available EXAMPLE: Plot a histogram of the photographic J magnitudes of all GSC 2.3.2 stars within 10 arcminutes of the center of the globular cluster M13 IDL> info = querygsc('M13',10) IDL> plothist,info.jpgmag,xran=[10,20] PROCEDURES USED: QUERYSIMBAD, RADEC, WEBGET() MODIFICATION HISTORY: Written by W. Landsman SSAI August 2002 Fixed parsing of RA and Dec W. Landsman September 2002 Major rewrite to use new STScI Web server, remove magrange keyword W. Landsman Dec 2007 Update server name, added /BOX,/ VERBOSE keywords W.L 19 Dec 2007 Web server now also returns infrared data W.L. Feb 2010 Fixed case where dec neg. and deg or min 0 Pat Fry Jul 2010(See astrolib/pro/querygsc.pro)
QUERYSIMBAD
[Previous Routine] [Next Routine] [List of Routines]NAME: QUERYSIMBAD PURPOSE: Query the SIMBAD/NED/Vizier astronomical name resolver to obtain coordinates EXPLANATION: Uses the IDL SOCKET command to query either the SIMBAD or NED nameserver over the Web to return J2000 coordinates. ; By default, QuerySimbad first queries the Simbad database, then (if no match found) the NED database, and then the Vizier database. For details on the SIMBAD service, see http://simbad.u-strasbg.fr/Simbad and for the NED service, see http://ned.ipac.caltech.edu/ CALLING SEQUENCE: QuerySimbad, name, ra, dec, [ id, Found=, /NED, /CADC, ERRMSG=, /VERBOSE] INPUTS: name - a scalar string containing the target name in SIMBAD (or NED) nomenclature. For SIMBAD details see http://vizier.u-strasbg.fr/cgi-bin/Dic-Simbad . OUTPUTS: ra - Right ascension of the target in J2000.0 in *degrees*, scalar dec - declination of the target in degrees, scalar OPTIONAL INPUT KEYWORD: /CFA - if set, then use the Simbad server at the Center for Astrophysics rather than the default server in Strasbourg, France. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. /NED - if set, then only the nameserver of the NASA Extragalactic database is used to resolve the name and return coordinates. Note that /NED cannot be used with Galactic objects /VERBOSE - If set, then the HTTP-GET command is displayed /PRINT - if set, then output coordinates are displayed at the terminal By default, the coordinates are displayed if no output parameters are supplied to QUERYSIMBAD /SILENT - If set, then don't print warnings if multiple SIMBAD objects correspond to the supplied name. OPTIONAL OUTPUT: id - the primary SIMBAD (or NED) ID of the target, scalar string As of June 2009, a more reliable ID seems to be found when using CFA (/CFA) server. OPTIONAL KEYWORD OUTPUT: found - set to 1 if the translation was successful, or to 0 if the the object name could not be translated by SIMBAD or NED Errmsg - if supplied, then any error messages are returned in this keyword, rather than being printed at the terminal. May be either a scalar or array. Server - Character indicating which server was actually used to resolve the object, 'S'imbad, 'N'ed or 'V'izier EXAMPLES: (1) Display the J2000 coordinates for the ultracompact HII region G45.45+0.06 IDL> QuerySimbad,'GAL045.45+00.06' ===>19 14 20.77 +11 09 3.6 PROCEDURES USED: REPSTR(), WEBGET() NOTES: The actual query is made to the Sesame name resolver ( see http://cdsweb.u-strasbg.fr/doc/sesame.htx ). The Sesame resolver first searches the Simbad name resolver, then NED and then Vizier. MODIFICATION HISTORY: Written by M. Feldt, Heidelberg, Oct 2001Minor updates, W. Landsman August 2002 Added option to use NED server, better parsing of SIMBAD names such as IRAS F10190+5349 W. Landsman March 2003 Turn off extended name search for NED server, fix negative declination with /NED W. Landsman April 2003 Use Simbad Sesame sever, add /Verbose, /CADC keywords B. Stecklum, TLS Tautenburg/ W. Landsman, Feb 2007 Update NED query to account for new IPAC format, A. Barth March 2007 Update NED query to account for another new IPAC format, A. Barth July 2007 Update message when NED does not find object W.L. October 2008 Remove CADC keyword, add CFA keyword, warning if more than two matches W.L. November 2008 Make NED queries through the Sesame server, add Server output keyword W.L. June 2009 Don't get primary name if user didn't ask for it W.L. Aug 2009 Added /SILENT keyword W.L. Oct 2009 Added /PRINT keyword W.L. Oct 2011 (See astrolib/pro/querysimbad.pro)
QUERYVIZIER
[Previous Routine] [Next Routine] [List of Routines]NAME: QUERYVIZIER PURPOSE: Query any catalog in the Vizier database by position EXPLANATION: Uses the IDL SOCKET command to provide a positional query of any catalog in the the Vizier (http://vizier.u-strasbg.fr/) database over the Web and return results in an IDL structure. CALLING SEQUENCE: info = QueryVizier(catalog, targetname_or_coords, [ dis /ALLCOLUMNS, /CANADA, CONSTRAINT= ,/VERBOSE ]) INPUTS: CATALOG - Scalar string giving the name of the VIZIER catalog to be searched. The complete list of catalog names is available at http://vizier.u-strasbg.fr/vizier/cats/U.htx . Popular VIZIER catalogs include 'II/306' - Sloan SDSS photometric catalog Release 8 (2011) '2MASS-PSC' - 2MASS point source catalog (2003) 'GSC2.3' - Version 2.3.2 of the HST Guide Star Catalog (2006) 'USNO-B1' - Verson B1 of the US Naval Observatory catalog (2003) 'UCAC4' - 4th U.S. Naval Observatory CCD Astrograph Catalog (2012) 'B/DENIS/DENIS' - 2nd Deep Near Infrared Survey of southern Sky (2005) 'I/259/TYC2' - Tycho-2 main catalog (2000) 'I/311/HIP2' - Hipparcos main catalog, new reduction (2007) Note that some names will prompt a search of multiple catalogs and QUERYVIZIER will only return the result of the first search. Thus, setting catalog to "HIP2" will search all catalogs associated with the Hipparcos mission, and return results for the first catalog found. To specifically search the Hipparcos or Tycho main catalogs use the VIZIER catalog names listed above TARGETNAME_OR_COORDS - Either a scalar string giving a target name, (with J2000 coordinates determined by SIMBAD), or a 2-element numeric vector giving the J2000 right ascension in *degrees* and the target declination in degrees. If the targetname is set to 'NONE' then QUERYVIZIER will perform an all-sky search using the constraints given in the CONSTRAINT keyword. OPTIONAL INPUT: dis - scalar or 2-element vector. If one value is supplied then this is the search radius in arcminutes. If two values are supplied then this is the width (i.e., in longitude direction) and height of the search box. Default is a radius search with radius of 5 arcminutes OUTPUTS: info - Anonymous IDL structure containing information on the catalog sources within the specified distance of the specified center. The structure tag names are identical with the VIZIER catalog column names, with the exception of an occasional underscore addition, if necessary to convert the column name to a valid structure tag. The VIZIER Web page should consulted for the column names and their meaning for each particular catalog.. If the tagname is numeric and the catalog field is blank then either NaN (if floating) or -1 (if integer) is placed in the tag. If no sources are found within the specified radius, or an error occurs in the query then -1 is returned. OPTIONAL KEYWORDS: /ALLCOLUMNS - if set, then all columns for the catalog are returned The default is to return a smaller VIZIER default set. /CANADA - By default, the query is sent to the main VIZIER site in Strasbourg, France. If /CANADA is set then the VIZIER site at the Canadian Astronomical Data Center (CADC) is used instead. Note that not all Vizier sites have the option to return tab-separated values (TSV) which is required by this program. CONSTRAINT - string giving additional nonpositional numeric constraints on the entries to be selected. For example, when in the GSC2.3 catalog, to only select sources with Rmag < 16 set Constraint = 'Rmag<16'. Multiple constraints can be separated by commas. Use '!=' for "not equal", '<=' for smaller or equal, ">=" for greater than or equal. See the complete list of operators at http://vizier.u-strasbg.fr/doc/asu.html#AnnexQual For this keyword only, **THE COLUMN NAME IS CASE SENSITIVE** and must be written exactly as displayed on the VIZIER Web page. Thus for the GSC2.3 catalog one must use 'Rmag' and not 'rmag' or 'RMAG'. In addition, *DO NOT INCLUDE ANY BLANK SPACE* unless it is a necessary part of the query. /SILENT - If set, then no message will be displayed if no sources are found. Error messages are still displayed. /VERBOSE - If set then the query sent to the VIZIER site is displayed, along with the returned title(s) of found catalog(s) EXAMPLES: (1) Plot a histogram of the J magnitudes of all 2MASS point sources stars within 10 arcminutes of the center of the globular cluster M13 IDL> info = queryvizier('2MASS-PSC','m13',10) IDL> plothist,info.jmag,xran=[10,20] (2) Find the brightest J mag GSC2.3 source within 3' of the J2000 position ra = 10:12:34, dec = -23:34:35 IDL> str = queryvizier('GSC2.3',[ten(10,12,34)*15,ten(-23,34,35)],3) IDL> print,min(str.jmag,/NAN) (3) Find sources with V < 19 in the Magellanic Clouds Photometric Survey (Zaritsky+, 2002) within 5 arc minutes of the position 00:47:34 -73:06:27 Checking the VIZIER Web page we find that this catalog is IDL> catname = 'J/AJ/123/855/table1' IDL> ra = ten(0,47,34)*15 & dec = ten(-73,6,27) IDL> str = queryvizier(catname, [ra,dec], 5, constra='Vmag<19') (4) Perform an all-sky search of the Tycho-2 catalog for stars with BTmag = 13+/-0.1 IDL> str = queryvizier('I/259/TYC2','NONE',constrain='BTmag=13+/-0.1') PROCEDURES USED: GETTOK(), REMCHAR, REPSTR(), STRCOMPRESS2(), WEBGET() TO DO: (1) Allow specification of output sorting MODIFICATION HISTORY: Written by W. Landsman SSAI October 2003 Give structure name returned by VIZIER not that given by user W. Landsman February 2004 Don't assume same format for all found sources W. L. March 2004 Added CONSTRAINT keyword for non-positional constraints WL July 2004 Remove use of EXECUTE() statement WL June 2005 Make dis optional as advertised WL August 2005 Update for change in Vizier output format WL February 2006 Fix problem in Feb 2006 update when only 1 object found WL/D.Apai March 2006 Accept 'E' format for floating point. M. Perrin April 2006 Added /ALLCOLUMNS option to return even more data. M. Perrin, May 2006 Return anonymous structure W. Landsman May 2006 Removed V6.0 notation to restore V5 compatibility W.Landsman July2006 Accept target='NONE' for all-sky search, allow '+/-' constraints W. Landsman October 2006 Use HTTP 1.0 protocol in call to webget.pro Use vector form of IDL_VALIDNAME if V6.4 or later W.L. Dec 2007 Update Strasbourg Web address for target name W.L. 3 March 2008 Also update Web address for coordinate search W.L. 7 March 2008 Allow for 'D' specification format R. Gutermuth/W.L. June 2008 Allow for possible lower-case returned formats W.L. July 2008 Use STRCOMPRESS2()to remove blanks around operators in constraint string W.L. August 2008 Added /SILENT keyword W.L. Jan 2009 Avoid error if output columns but not data returned W.L. Mar 2010 Ignore vector tags (e.g. SED spectra) W.L. April 2011 Better checking when more than one catalog returned W.L. June 2012(See astrolib/pro/queryvizier.pro)
RADEC
[Previous Routine] [Next Routine] [List of Routines]NAME: RADEC PURPOSE: To convert RA and Dec from decimal to sexagesimal units. EXPLANATION: The conversion is to sexagesimal hours for RA, and sexagesimal degrees for declination. CALLING SEQUENCE: radec, ra, dec, ihr, imin, xsec, ideg, imn, xsc, [/HOURS} INPUTS: ra - Right ascension, scalar or vector, in DEGREES unless the /HOURS keyword is set dec - declination in decimal DEGREES, scalar or vector, same number of elements as RA OUTPUTS: ihr - right ascension hours (INTEGER*2) imin - right ascension minutes (INTEGER*2) xsec - right ascension seconds (REAL*4 or REAL*8) ideg - declination degrees (INTEGER*2) imn - declination minutes (INTEGER*2) xsc - declination seconds (REAL*4 or REAL*8) OPTIONAL KEYWORD INPUT: /HOURS - if set, then the input righ ascension should be specified in hours instead of degrees. RESTRICTIONS: RADEC does minimal parameter checking. REVISON HISTORY: Written by B. Pfarr, STX, 4/24/87 Converted to IDL V5.0 W. Landsman September 1997 Added /HOURS keyword W. Landsman August 2002(See astrolib/pro/radec.pro)
RANDOMCHI
[Previous Routine] [Next Routine] [List of Routines]NAME: RANDOMCHI PURPOSE: GENERATE CHI-SQUARE DISTRIBUTED RANDOM VARIABLES. AUTHOR : BRANDON C. KELLY, STEWARD OBS., SEP 2005 INPUTS : SEED - THE SEED FOR THE RANDOM NUMBER GENERATOR, CAN BE UNDEFINED. DOF - THE DEGREES OF FREEDOM FOR THE CHI-SQUARED DISTRIBUTION. OPTIONAL INPUTS : NRAND - THE NUMBER OF RANDOM NUMBERS TO DRAW(See astrolib/pro/randomchi.pro)
RANDOMDIR
[Previous Routine] [Next Routine] [List of Routines]NAME: RANDOMDIR PURPOSE: GENERATE DIRICHLET-DISTRIBUTED RANDOM VARIABLES. AUTHOR : BRANDON C. KELLY, STEWARD OBS., APRIL 2006 INPUTS : SEED - THE SEED FOR THE RANDOM NUMBER GENERATOR, CAN BE UNDEFINED. ALPHA - THE SHAPE PARAMETERS FOR THE DIRICHLET DISTRIBUTION. THIS SHOULD BE A K-ELEMENT VECTOR. OPTIONAL INPUTS : NRAND - THE NUMBER OF RANDOM NUMBERS TO DRAW CALLED ROUTINES : RANDOMGAM(See astrolib/pro/randomdir.pro)
RANDOMGAM
[Previous Routine] [Next Routine] [List of Routines]NAME: RANDOMGAM PURPOSE: GENERATE GAMMA-DISTRIBUTED RANDOM VARIABLES. AUTHOR : BRANDON C. KELLY, STEWARD OBS., APRIL 2006 INPUTS : SEED - THE SEED FOR THE RANDOM NUMBER GENERATOR, CAN BE UNDEFINED. ALPHA, BETA - THE SHAPE PARAMETERS FOR THE GAMMA DISTRIBUTION. OPTIONAL INPUTS : NRAND - THE NUMBER OF RANDOM NUMBERS TO DRAW(See astrolib/pro/randomgam.pro)
RANDOMP
[Previous Routine] [Next Routine] [List of Routines]NAME: RANDOMP PURPOSE: Generates an array of random numbers distributed as a power law. CALLING SEQUENCE: RANDOMP, X, Pow, N, [ RANGE_X = [low,high], SEED= ]' INPUTS: Pow: Exponent of power law. The pdf of X is f_X(x) = A*x^pow, low <= x <= high ASTRONOMERS PLEASE NOTE: pow is little gamma = big gamma - 1 for stellar IMFs. N: Number of elements in generated vector. OPTIONAL INPUT KEYWORD PARAMETER: RANGE_X: 2-element vector [low,high] specifying the range of output X values; the default is [5, 100]. OPTIONAL INPUT-OUTPUT KEYWORD PARAMETER: SEED: Seed value for RANDOMU function. As described in the documentation for RANDOMU, the value of SEED is updated on each call to RANDOMP, and taken from the system clock if not supplied. This keyword can be used to have RANDOMP give identical results on different runs. OUTPUTS: X: Vector of random numbers, distributed as a power law between specified range PROCEDURE: "Transformation Method" for random variables is described in Bevington & Robinson, "Data Reduction & Error Analysis for Physical Sciences", 2nd Edition (McGraw-Hill, 1992). p. 83. Output of RANDOMU function is transformed to power-law random variable. EXAMPLE: Create a stellar initial mass function (IMF) with 10000 stars ranging from 0.5 to 100 solar masses and a Salpeter slope. Enter: RANDOMP,MASS,-2.35,10000,RANGE_X=[0.5,100] NOTES: Versions 5.1.1 and V5.2 of IDL have a bug in RANDOMU such that the SEED value is initialized to the same value at the start of each session, rather than being initialized by the system clock. RANDOMP will be affected in a similar manner. MODIFICATION HISTORY: Written by R. S. Hill, Hughes STX, July 13, 1995 July 14, 1995 SEED keyword added at Landsman's suggestion. Documentation converted to standard format. RSH Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/randomp.pro)
RANDOMWISH
[Previous Routine] [Next Routine] [List of Routines]NAME: RANDOMWISH PURUPOSE: ROUTINE TO DRAW RANDOM MATRICES FROM A WISHART DISTRIBUTION WITH DOF DEGREES OF FREEDOM AND SCALE MATRIX S. AUTHOR : BRANDON C. KELLY, STEWARD OBS., JULY 2006 INPUTS : SEED - THE SEED FOR THE RANDOM NUMBER GENERATOR, CAN BE UNDEFINED. DOF - THE DEGREES OF FREEDOM FOR THE WISHART DISTRIBUTION. S - THE SCALE MATRIX. THE DIMENSION OF S CANNOT BE GREATER THAN DOF. OPTIONAL INPUTS : NRAND - THE NUMBER OF RANDOM MATRICES TO DRAW CALLED ROUTINES : MRANDOMN(See astrolib/pro/randomwish.pro)
RDFITS_STRUCT
[Previous Routine] [Next Routine] [List of Routines]NAME: RDFITS_STRUCT PURPOSE: Read an entire FITS file (all extensions) into a single IDL structure. EXPLANATION: Each header, image or table array is placed in a separate structure tag. CALLING SEQUENCE: RDFITS_STRUCT, filename, struct, /SILENT, /HEADER_ONLY, EXTEN= ] INPUT: FILENAME = Scalar string giving the name of the FITS file. One can also specify a gzip (.gz) compressed file OPTIONAL KEYWORD: /HEADER_ONLY - If set, then only the FITS headers (and not the data) are read into the structure. /SILENT - Set this keyword to suppress informational displays at the terminal. OUTPUT: struct = structure into which FITS data is read. The primary header and image are placed into tag names HDR0 and IM0. The ith extension is placed into the tag names HDRi, and either TABi (if it is a binary or ASCII table) or IMi (if it is an image extension) If /HEADER_ONLY is set, then struct will contain tags HDR0, HDR1 ....HDRn containing all the headers of a FITS file with n extensions OPTIONAL INPUT KEYWORD: EXTEN - positive integer array specifying which extensions to read. Default is to read all extensions. PROCEDURES USED: FITS_OPEN, FITS_READ, FITS_CLOSE METHOD: The file is opened with FITS_OPEN which return information on the number and type of each extension. The CREATE_STRUCT() function is used iteratively, with FITS_READ calls to build the final structure. EXAMPLE: Read the FITS file 'm33.fits' into an IDL structure, st IDL> rdfits_struct, 'm33.fits', st IDL> help, /str, st ;Display info about the structure To just read the second and fourth extensions IDL> rdfits_struct, 'm33.fits', st, exten=[2,4] RESTRICTIONS: Does not handle random groups or variable length binary tables MODIFICATION HISTORY: Written K. Venkatakrishna, STX April 1992 Code cleaned up a bit W. Landsman STX October 92 Modified for MacOS I. Freedman HSTX April 1994 Work under Windows 95 W. Landsman HSTX January 1996 Use anonymous structures, skip extensions without data WBL April 1998 Converted to IDL V5.0, W. Landsman, April 1998 OS-independent deletion of temporary file W. Landsman Jan 1999 Major rewrite to use FITS_OPEN and CREATE_STRUCT() W. Landsman Sep 2002 Added /HEADER_ONLY keyword W. Landsman October 2003 Do not copy primary header into extension headers W. Landsman Dec 2004 Do not modify NAXIS when using /HEADER_ONLY W. Landsman Jan 2005 Added EXTEN keyword W. Landsman July 2009(See astrolib/pro/rdfits_struct.pro)
RDFLOAT
[Previous Routine] [Next Routine] [List of Routines]NAME: RDFLOAT PURPOSE: Quickly read a numeric ASCII data file into IDL floating/double vectors. EXPLANATION: Columns of data may be separated by tabs or spaces. This program is fast but is restricted to data files where all columns can be read as floating point (or all double precision). Use READCOL if greater flexibility is desired. Use READFMT to read a fixed-format ASCII file. Use FORPRINT to print columns of data. CALLING SEQUENCE: RDFLOAT, name, v1, [ v2, v3, v4, v5, ... v19] COLUMNS, /DOUBLE, SKIPLINE = , NUMLINE = ] INPUTS: NAME - Name of ASCII data file, scalar string. In VMS, an extension of .DAT is assumed, if not supplied. OPTIONAL INPUT KEYWORDS: COLUMNS - Numeric scalar or vector specifying which columns in the file to read. For example, if COLUMNS = [3,7,11] then the first output variable (v1) would contain column 3, the second would contain column 7 and the third would contain column 11. If the number of elements in the COLUMNS vector is less than the number of output parameters, then consecutive columns are implied. For example, if 3 output parameters are supplied (v1,v2,v3) and COLUMNS = 3, then columns 3,4, and 5 will be read. SKIPLINE - Integer scalar specifying number of lines to skip at the top of file before reading. Default is to start at the first line. NUMLINE - Integer scalar specifying number of lines in the file to read. Default is to read the entire file /DOUBLE - If this keyword is set, then all variables are read in as double precision. /SILENT - Set this keyword to suppress any informative messages OUTPUTS: V1,V2,V3,...V19 - IDL vectors to contain columns of data. Up to 19 columns may be read. All output vectors are of type float, unless the /DOUBLE keyword is set, EXAMPLES: Each row in a file 'position.dat' contains a star number and 6 columns of data giving an RA and Dec in sexagesimal format. Read into IDL variables. IDL> rdfloat,'position.dat',ID,hr,min,sec,deg,dmin,dsec All output vectors will be floating point. To only read the declination vectors (Deg,dmin,dsec) IDL> rdfloat,'position.dat',deg,dmin,dsec,col=4 RESTRICTIONS: (1) All rows in the file must be formatted identically (except for those skipped by SKIPLINE). RDFLOAT reads the first line of the data (after SKIPLINE) to determine the number of columns of data. (2) Cannot be used to read strings PROCEDURES USED: None. REVISION HISTORY: Written W. Landsman September 1995 Call NUMLINES() function February 1996 Read up to 19 columns August 1997 Converted to IDL V5.0 W. Landsman September 1997 Allow to skip more than 32767 lines W. Landsman June 2001 Added /SILENT keyword W. Landsman March 2002 Added COLUMNS keyword, use STRSPLIT W. Landsman May 2002 Use SKIP_LUN if V5.6 or later W. Landsman Nov 2002 V5.6 version, use FILE_LINES() W. Landsman Dec 2002(See astrolib/pro/rdfloat.pro)
RDPLOT
[Previous Routine] [Next Routine] [List of Routines]NAME: RDPLOT PURPOSE: Like CURSOR but with a full-screen cursor and continuous readout option EXPLANATION: This program is designed to essentially mimic the IDL CURSOR command, but with the additional options of continuously printing out the data values of the cursor's position, and using a full-screen cursor rather than a small cross cursor. The full screen cursor uses OPLOT and X-windows graphics masking to emulate the cursor. One difference is that IF the PRINT keyword is set but the DOWN, WAIT, CHANGE, or NOWAIT keywords are not set, then the leftmost mouse button will print a "newline" line-feed, but not exit. CALLING SEQUENCE: RDPLOT [, X, Y] [, WaitFlag] [, /DATA | /DEVICE | /NORMAL] [, /NOWAIT | /WAIT | /DOWN | /CHANGE] [, /FULLCURSOR] [, /NOCLIP] [, /CROSS] [, /ACCUMULATE] [, ERR=, PRINT=, XTITLE=, YTITLE=, XVALUES=, YVALUES= , LINESTYLE=, THICK=, COLOR=, BACKGROUND=] REQUIRED INPUTS: None. OPTIONAL INPUTS: WAITFLAG = Uses the same table as the intrinsic CURSOR command, But note that unlike the CURSOR command, there is no UP keyword. WaitFlag=0 sets the NOWAIT keyword WaitFlag=1 sets the WAIT keyword {default} WaitFlag=2 sets the CHANGE keyword WaitFlag=3 sets the DOWN keyword OPTIONAL OUTPUTS: X - a named variable to receive the final cursor X position, scalar or vector (if /ACCUMULATE is set) Y - a named variable to receive the final cursor Y position, scalar or vector (if /ACCUMULATE is set) OPTIONAL KEYWORD INPUT PARAMETERS: /DATA - data coordinates are displayed and returned. /DEVICE - device coordinates are displayed and returned. /NORMAL - normal coordinates are displayed and returned. Default is to use DATA coordinates if available (see notes). /NOWAIT = if non-zero the routine will immediately return the cursor's present position. /WAIT - if non-zero will wait for a mouse key click before returning. If cursor key is already down, then procedure immediately exits. /DOWN - equivalent to WAIT *except* that if the mouse key is already down when the procedure is called, the procedure will wait until the mouse key is clicked down again. /CHANGE - returns when the mouse is moved OR a key is clicked up or down. PRINT = if non-zero will continuously print out (at the terminal) the data values of the cursor's position. If PRINT>1, program will printout a brief header describing the mouse button functions. However, note that the button functions are overridden if any of the DOWN, WAIT, or CHANGE values are non-zero. XTITLE = label used to describe the values of the abscissa if PRINT>0. YTITLE = label used to describe the values of the ordinate if PRINT>0. XVALUES = a vector corresponding to the values to be printed when the PRINT keyword is set. This allows the user the option of printing out other values rather than the default X coordinate position of the cursor. E.g., if XVALUES is a string vector of dates such as ['May 1', 'May 2', ...], then those dates will be printed rather than the X value of the cursor's position: if X=1 then 'May 2' would be printed, etc. This requires that the values of the X coordinate read by the cursor must be positive (can't access negative elements). If XVALUES=-1, then NO values for X will be printed. YVALUES = analogous to the XVALUES keyword. /FULLCURSOR - if non-zero default cursor is blanked out and full-screen (or full plot window, depending on the value of NOCLIP) lines are drawn; their intersecton is centered on the cursor position. /NOCLIP - if non-zero will make a full-screen cursor, otherwise it will default to the value in !P.NOCLIP. LINESTYLE = style of line that makes the full-screen cursor. THICK = thickness of the line that makes the full-screen cursor. COLOR = color of the full-screen cursor. BACKGROUND = color of the background of the plot device. If this has been set to !P.BackGround, then this keyword is unnecessary. CROSS = if non-zero will show the regular cross AND full screen cursors. /ACCUMULATE - all of the positions for which the left button was clicked are stored in the X and Y variables. Has no effect if X and Y are not present. OPTIONAL KEYWORD OUTPUT PARAMETER: ERR = returns the most recent value of the !mouse.button value. NOTES: Note that this procedure does not allow the "UP" keyword/flag...which doesn't seem to work too well in the origianl CURSOR version anyway. If a data coordinate system has not been established, then RDPLOT will create one identical to the device coordinate system. Note that this kluge is required even if the user specified /NORMAL coordinates, since RDPLOT makes use of the OPLOT procedure. This new data coordinate system is effectively "erased" (!X.CRange and !Y.CRange are both set to zero) upon exit of the routine so as to not change the plot status from the user's point of view. Only tested on X-windows systems. If this program is interrupted, the graphics function might be left in a non-standard state; in that case, run the program RESET_RDPLOT to return the standard graphics functions, or type the command: DEVICE, /CURSOR_CROSS, SET_GRAPHICS=3, BYPASS=0 Robishaw added /ACCUMULATE keyword to pass back all the positions at which the mouse was left-clicked. In addition, the value of the exit click is returned unless the cursor did not change position between the last left-click and the exit click. BUGS: NOTE: (1/27/05) The bugs below have been fixed by Robishaw and tested on Solaris, Linux and OS-X. It is assumed that the current background of the plot is correctly defined by the value in !P.Background. Otherwise, the color of the long cursor probably will not be correct. Sometimes the color doesn't work anyway, and I'm not sure why. NOTE: Robishaw fixed this 1/27/05. There may be some cases (e.g., when THICK>1 and NOCLIP=0) when the full-screen cursor is not correctly erased, leaving "ghost images" on the plot. It just seems that the screen updates get slow or the positions ambiguous with a thick line and the cursor off the plot. NOTE: Robishaw fixed this 1/27/05. PROCEDURE: Basically is a bells-n-whistles version of the CURSOR procedure. All the details are covered in the above discussion of the keywords. EXAMPLES: A silly, but informative one: Months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', $ 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'] plot, indgen(12), xrange=[-5, 15] rdplot, /FULL, /PRINT, XTITLE='Month: ', YTITLE='Y-value per month = ', $ xvalues=Months If your plot has a non-black background color, be sure to set either !p.background or the BACKGROUND keyword. Here are examples of how to use a blue full-screen cursor on a plot with a red background and yellow axes and data. First, deal with color decomposition off: device, decomposed=0 tvlct, [255,255,0], [0,255,0], [0,0,255], 1 plot, randomn(seed,1024), XSTYLE=19, PSYM=3, COLOR=2, BACK=1 rdplot, /PRINT, /FULL, THICK=5, /NOCLIP, BACK=1, COLOR=3 For decomposition on (TrueColor or DirectColor only): device, decomposed=1 plot, randomn(seed,1024), XSTYLE=19, PSYM=3, COLOR=65535l, BACK=255l rdplot, /PRINT, /FULL, THICK=5, /NOCLIP, BACK=255l, COLOR=16711680l MODIFICATION HISTORY: Written (originally named CURFULL) by J.Wm.Parker 1993 Nov 22 Created data coordinates if not already present, W. Landsman Nov. 93 Added continuous printout of data values, COLOR and FULLCURSOR keywords (so that default is that it acts just like the cursor command). Changed name from CURFULL to RDPLOT. J.Wm.Parker 1994 Apr 20 Modified (with some translation table assistance from the IDL support group) to correctly plot the crosshair with the desired IDL color using the device's translation table to determine the XOR function and using the BYPASS function. Added the RESET_RDPLOT procedure to cleanup crashes that might occur while running RDPLOT. Other minor changes/bug fixes. J.Wm.Parker 1994 May 21 Modified DOWN, WAIT, CHANGE functions to behave more similar to the generic CURSOR procedure. J.Wm.Parker 1995 April 24 Added XVALUES, YVALUES keywords and cleanup. J.Wm.Parker 1995 April 24 Convert to IDL V5.0, W. Landsman July 1998 Change !D.NCOLORS to !D.TABLE_SIZE for 24 bit displays W. Landsman May 2000 Skip translation table for TrueColor visuals W. Landsman March 2001 Fixed /FULLCURSOR ghosts. Fixed to properly deal with background colors in 24-bit visual classes (TrueColor and DirectColor). Added BACKGROUND keyword. Tim Robishaw 2005 Jan 27 Added /ACCUMULATE keyword. T. Robishaw 2006 Nov 8 Corrected following problems. When /CHANGE and /PRINT were set, returned X & Y were different than those printed. When /PRINT and /NOWAIT were set, or /PRINT and /WAIT were set and the routine was entered with a mouse button clicked, nothing was printed. When /PRINT and /DOWN were set, if routine was started with button down, advertised behavior was that routine would exit on next down click; in practice if cursor was not moved, successive down clicks had no effect. Now, if X is passed as an output variable, requires that Y is also passed, like CURSOR. Bottom line is that RDPLOT now really does behave like CURSOR and when /PRINT is set, the values printed correspond to those returned in X & Y. T. Robishaw 2006 Nov 12 Fixed misbehavior when color decomposition was set to off for TrueColor and DirectColor. Now thoroughly tested on PseudoColor displays as well as both decomposition states for TrueColor and DirectColor. Also made the default cursor color white when decomposition is on (this has been its default value for decomposition off). T. Robishaw 2006 Nov 16(See astrolib/pro/rdplot.pro)
RDPSF
[Previous Routine] [Next Routine] [List of Routines]NAME: RDPSF PURPOSE: Read the FITS file created by GETPSF in the DAOPHOT sequence EXPLANATION: Combines the Gaussian with the residuals to create an output PSF array. CALLING SEQUENCE: RDPSF, PSF, HPSF, [ PSFname] OPTIONAL INPUTS PSFname - string giving the name of the FITS file containing the PSF residuals OUTPUTS psf - array containing the actual PSF hpsf - header associated with psf PROCEDURES CALLED: DAO_VALUE(), MAKE_2D, SXADDPAR, READFITS(), SXPAR() REVISION HISTORY: Written W. Landsman December, 1988 Checked for IDL Version 2, J. Isensee & J. Hill, December, 1990 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/rdpsf.pro)
READCOL
[Previous Routine] [Next Routine] [List of Routines]NAME: READCOL PURPOSE: Read a free-format ASCII file with columns of data into IDL vectors EXPLANATION: Lines of data not meeting the specified format (e.g. comments) are ignored. By default, columns may be separated by commas or spaces. Use READFMT to read a fixed-format ASCII file. Use RDFLOAT for much faster I/O (but less flexibility). Use FORPRINT to write columns of data (inverse of READCOL). If you sure that all lines meet the specified format (excluding commented and SKIPed lines) then the speed for reading large files can be significantly improved by setting the /QUICK keyword. CALLING SEQUENCE: READCOL, name, v1, [ v2, v3, v4, v5, ... v40 , COMMENT=, /NAN DELIMITER= ,FORMAT = , /DEBUG , /SILENT , SKIPLINE = , NUMLINE = COUNT =, STRINGSKIP= INPUTS: NAME - Name of ASCII data file, scalar string. OPTIONAL INPUT KEYWORDS: FORMAT - scalar string containing a letter specifying an IDL type for each column of data to be read. Allowed letters are A - string data, B - byte, D - double precision, F- floating point, I - short integer, L - longword, LL - 64 bit integer, U - unsigned short integer, UL - unsigned long integer Z - longword hexadecimal, and X - skip a column. Columns without a specified format are assumed to be floating point. Examples of valid values of FMT are 'A,B,I' ;First column to read as a character string, then 1 column of byte data, 1 column integer data 'L,L,L,L' ;Four columns will be read as longword arrays. ' ' ;All columns are floating point If a FORMAT keyword string is not supplied, then all columns are assumed to be floating point. /SILENT - Normally, READCOL will display each line that it skips over. If SILENT is set and non-zero then these messages will be suppressed. /DEBUG - If this keyword is non-zero, then additional information is printed as READCOL attempts to read and interpret the file. COMMENT - single character specifying comment character. Any line beginning with this character will be skipped. Default is no comment lines. /COMPRESS - If set, then the file is assumed to be gzip compressed. There is no automatic recognition of compressed files by extension type. DELIMITER - Character(s) specifying delimiter used to separate columns. Usually a single character but, e.g. delimiter=':,' specifies that either a colon or comma as a delimiter. Set DELIM = string(9b) to read tab separated data The default delimiter is either a comma or a blank. /NAN - if set, then an empty field will be read into a floating or double numeric variable as NaN; by default an empty field is converted to 0.0. /PRESERVE_NULL - If set, then spaces are considered to be valid fields, useful if the columns contain missing data. Note that between April and December 2006, /PRESERVE_NULL was the default. /QUICK - If set, then READCOL does not check that each individual line matches the supplied format. This makes READCOL less flexible but can provide a significant speed improvement when reading large files. SKIPLINE - Scalar specifying number of lines to skip at the top of file before reading. Default is to start at the first line. NUMLINE - Scalar specifying number of lines in the file to read. Default is to read the entire file STRINGSKIP - will skip all lines that begin with the specified string. (Unlike COMMENT this can be more than 1 character.) Useful to skip over comment lines. OUTPUTS: V1,V2,V3,...V40 - IDL vectors to contain columns of data. Up to 40 columns may be read. The type of the output vectors are as specified by FORMAT. OPTIONAL OUTPUT KEYWORDS: COUNT - integer giving the number of valid lines actually read NLINES - integer giving the total number of lines in the file (as returned by FILE_LINES) EXAMPLES: Each row in a file position.dat contains a star name and 6 columns of data giving an RA and Dec in sexagesimal format. Read into IDL variables. (NOTE: The star names must not include the delimiter as a part of the name, no spaces or commas as default.) IDL> FMT = 'A,I,I,F,I,I,F' IDL> READCOL,'position.dat',F=FMT,name,hr,min,sec,deg,dmin,dsec The HR,MIN,DEG, and DMIN variables will be integer vectors. Alternatively, all except the first column could be specified as floating point. IDL> READCOL,'position.dat',F='A',name,hr,min,sec,deg,dmin,dsec To read just the variables HR,MIN,SEC IDL> READCOL,'position.dat',F='X,I,I,F',HR,MIN,SEC RESTRICTIONS: This procedure is designed for generality and not for speed. If a large ASCII file is to be read repeatedly, it may be worth writing a specialized reader. Columns to be read as strings must not contain the delimiter character (i.e. commas or spaces by default). Either change the default delimiter with the DELIMITER keyword, or use READFMT to read such files. Numeric values are converted to specified format. For example, the value 0.13 read with an 'I' format will be converted to 0. PROCEDURES CALLED GETTOK(), STRNUMBER() The version of STRNUMBER() must be after August 2006. REVISION HISTORY: Written W. Landsman November, 1988 Modified J. Bloch June, 1991 (Fixed problem with over allocation of logical units.) Added SKIPLINE and NUMLINE keywords W. Landsman March 92 Read a maximum of 25 cols. Joan Isensee, Hughes STX Corp., 15-SEP-93. Call NUMLINES() function W. Landsman Feb. 1996 Added DELIMITER keyword W. Landsman Nov. 1999 Fix indexing typos (i for k) that mysteriously appeared W. L. Mar. 2000 Hexadecimal support added. MRG, RITSS, 15 March 2000. Default is comma or space delimiters as advertised W.L. July 2001 Faster algorithm, use STRSPLIT if V5.3 or later W.L. May 2002 Accept null strings separated by delimiter ,e.g. ',,,' Use SCOPE_VARFETCH instead of EXECUTE() for >V6.1 W.L. Jun 2005 Added compile_opt idl2 W. L. July 2005 Added the NaN keyword W. L August 2006 Added /PRESERVE_NULL keyword W.L. January 2007 Assume since V5.6 (FILE_LINES available ) W.L. Nov 2007 Added COUNT output keyword W.L. Aug 2008 Added NLINES output keyword W.L. Nov 2008 Added SKIPSTART keyword Stephane Beland January 2008 Renamed SKIPSTART to STRINGSKIP to keep meaning of SKIP W.L. Feb 2008 Assume since V6.1, SCOPE_VARFETCH available W.L. July 2009 Read up to 40 columns W.L. Aug 2009 Use pointers instead of SCOPE_VARFETCH. Fixes bug with IDL Workbench and runs 20% faster Douglas J. Marshall/W.L. Nov 2009 Recognize LL, UL, and ULL data types, don't use 'val' output from STRNUMBER() W.L. Feb 2010 Graceful return even if no valid lines are present D. Sahnow April 2010 Ability to read tab separated data WL April 2010 Free memory used by pointers WL July 2010 Added /QUICK keyword WL Sep 2010 Accept normal FORTRAN formats (e.g. F5.1) P. Noterdaeme/W.L Jan 2011 Add COMPRESS keyword, IDL 6 notation W. Landsman/J. Bailin Feb 2011 Allow filename to be 1 element array W.Landsman/S.Antonille Apr 2011 Feb 2010 change caused errors when reading blanks as numbers. W.L. July 2012(See astrolib/pro/readcol.pro)
READFITS
[Previous Routine] [Next Routine] [List of Routines]NAME: READFITS PURPOSE: Read a FITS file into IDL data and header variables. EXPLANATION: READFITS() can read FITS files compressed with gzip or Unix (.Z) compression. FPACK ( http://heasarc.gsfc.nasa.gov/fitsio/fpack/ ) compressed FITS files can also be read provided that the FPACK software is installed. See http://idlastro.gsfc.nasa.gov/fitsio.html for other ways of reading FITS files with IDL. CALLING SEQUENCE: Result = READFITS( Filename/Fileunit,[ Header, heap, /NOSCALE, EXTEN_NO=, NSLICE=, /SILENT , STARTROW =, NUMROW = , HBUFFER=, /CHECKSUM, /COMPRESS, /FPACK, /No_Unsigned, NaNVALUE = ] INPUTS: Filename = Scalar string containing the name of the FITS file (including extension) to be read. If the filename has a *.gz extension, it will be treated as a gzip compressed file. If it has a .Z extension, it will be treated as a Unix compressed file. If Filename is an empty string then the user will be queried for the file name. OR Fileunit - A scalar integer specifying the unit of an already opened FITS file. The unit will remain open after exiting READFITS(). There are two possible reasons for choosing to specify a unit number rather than a file name: (1) For a FITS file with many extensions, one can move to the desired extensions with FXPOSIT() and then use READFITS(). This is more efficient than repeatedly starting at the beginning of the file. (2) For reading a FITS file across a Web http: address after opening the unit with the SOCKET procedure OUTPUTS: Result = FITS data array constructed from designated record. If the specified file was not found, then Result = -1 OPTIONAL OUTPUT: Header = String array containing the header from the FITS file. If you don't need the header, then the speed may be improved by not supplying this parameter. Note however, that omitting the header can imply /NOSCALE, i.e. BSCALE and BZERO values may not be applied. heap = For extensions, the optional heap area following the main data array (e.g. for variable length binary extensions). OPTIONAL INPUT KEYWORDS: /CHECKSUM - If set, then READFITS() will call FITS_TEST_CHECKSUM to verify the data integrity if CHECKSUM keywords are present in the FITS header. Cannot be used with the NSLICE, NUMROW or STARTROW keywords, since verifying the checksum requires that all the data be read. See FITS_TEST_CHECKSUM() for more information. /COMPRESS - Signal that the file is gzip compressed. By default, READFITS will assume that if the file name extension ends in '.gz' then the file is gzip compressed. The /COMPRESS keyword is required only if the the gzip compressed file name does not end in '.gz' or .ftz EXTEN_NO - non-negative scalar integer specifying the FITS extension to read. For example, specify EXTEN = 1 or /EXTEN to read the first FITS extension. /FPACK - Signal that the file is compressed with the FPACK software. http://heasarc.gsfc.nasa.gov/fitsio/fpack/ ) By default, (READFITS will assume that if the file name extension ends in .fz that it is fpack compressed. The FPACK software must be installed on the system HBUFFER - Number of lines in the header, set this to slightly larger than the expected number of lines in the FITS header, to improve performance when reading very large FITS headers. Should be a multiple of 36 -- otherwise it will be modified to the next higher multiple of 36. Default is 180 /NOSCALE - If present and non-zero, then the ouput data will not be scaled using the optional BSCALE and BZERO keywords in the FITS header. Default is to scale. /NO_UNSIGNED - By default, if the header indicates an unsigned integer (BITPIX = 16, BZERO=2^15, BSCALE=1) then READFITS() will output an IDL unsigned integer data type (UINT). But if /NO_UNSIGNED is set, then the data is converted to type LONG. NSLICE - An integer scalar specifying which N-1 dimensional slice of a N-dimensional array to read. For example, if the primary image of a file 'wfpc.fits' contains a 800 x 800 x 4 array, then IDL> im = readfits('wfpc.fits',h, nslice=2) is equivalent to IDL> im = readfits('wfpc.fits',h) IDL> im = im[*,*,2] but the use of the NSLICE keyword is much more efficient. Note that any degenerate dimensions are ignored, so that the above code would also work with a 800 x 800 x 4 x 1 array. NUMROW - Scalar non-negative integer specifying the number of rows of the image or table extension to read. Useful when one does not want to read the entire image or table. POINT_LUN - Position (in bytes) in the FITS file at which to start reading. Useful if READFITS is called by another procedure which needs to directly read a FITS extension. Should always be a multiple of 2880, and not be used with EXTEN_NO keyword. /SILENT - Normally, READFITS will display the size the array at the terminal. The SILENT keyword will suppress this STARTROW - Non-negative integer scalar specifying the row of the image or extension table at which to begin reading. Useful when one does not want to read the entire table. NaNVALUE - This keyword is included only for backwards compatibility with routines that require IEEE "not a number" values to be converted to a regular value. /UNIXPIPE - When a FileUnit is supplied to READFITS(), then /UNIXPIPE indicates that the unit is to a Unix pipe, and that no automatic byte swapping is performed. EXAMPLE: Read a FITS file test.fits into an IDL image array, IM and FITS header array, H. Do not scale the data with BSCALE and BZERO. IDL> im = READFITS( 'test.fits', h, /NOSCALE) If the file contains a FITS extension, it could be read with IDL> tab = READFITS( 'test.fits', htab, /EXTEN ) The function TBGET() can be used for further processing of a binary table, and FTGET() for an ASCII table. To read only rows 100-149 of the FITS extension, IDL> tab = READFITS( 'test.fits', htab, /EXTEN, STARTR=100, NUMR = 50 ) To read in a file that has been compressed: IDL> tab = READFITS('test.fits.gz',h) ERROR HANDLING: If an error is encountered reading the FITS file, then (1) the system variable !ERROR_STATE.CODE is set negative (via the MESSAGE facility) (2) the error message is displayed (unless /SILENT is set), and the message is also stored in !!ERROR_STATE.MSG (3) READFITS returns with a value of -1 RESTRICTIONS: (1) Cannot handle random group FITS NOTES: (1) If data is stored as integer (BITPIX = 16 or 32), and BSCALE and/or BZERO keywords are present, then the output array is scaled to floating point (unless /NOSCALE is present) using the values of BSCALE and BZERO. In the header, the values of BSCALE and BZERO are then reset to 1. and 0., while the original values are written into the new keywords O_BSCALE and O_BZERO. If the BLANK keyword was present (giving the value of undefined elements *prior* to the application of BZERO and BSCALE) then the *keyword* value will be updated with the values of BZERO and BSCALE. (2) The use of the NSLICE keyword is incompatible with the NUMROW or STARTROW keywords. (3) On some Unix shells, one may get a "Broken pipe" message if reading a Unix compressed (.Z) file, and not reading to the end of the file (i.e. the decompression has not gone to completion). This is an informative message only, and should not affect the output of READFITS. PROCEDURES USED: Functions: SXPAR() Procedures: MRD_SKIP, SXADDPAR, SXDELPAR MODIFICATION HISTORY: Original Version written in 1988, W.B. Landsman Raytheon STX Revision History prior to October 1998 removed Major rewrite to eliminate recursive calls when reading extensions W.B. Landsman Raytheon STX October 1998 Add /binary modifier needed for Windows W. Landsman April 1999 Read unsigned datatypes, added /no_unsigned W. Landsman December 1999 Output BZERO = 0 for unsigned data types W. Landsman January 2000 Update to V5.3 (see notes) W. Landsman February 2000 Fixed logic error in use of NSLICE keyword W. Landsman March 2000 Fixed byte swapping for Unix compress files on little endian machines W. Landsman April 2000 Added COMPRESS keyword, catch IO errors W. Landsman September 2000 Option to read a unit number rather than file name W.L October 2001 Fix undefined variable problem if unit number supplied W.L. August 2002 Don't read entire header unless needed W. Landsman Jan. 2003 Added HBUFFER keyword W. Landsman Feb. 2003 Added CHECKSUM keyword W. Landsman May 2003 Restored NaNVALUE keyword for backwards compatibility, William Thompson, 16-Aug-2004, GSFC Recognize .ftz extension as compressed W. Landsman September 2004 Fix unsigned integer problem introduced Sep 2004 W. Landsman Feb 2005 Don't modify header for unsigned integers, preserve double precision BSCALE value W. Landsman March 2006 Use gzip instead of compress for Unix compress files W.Landsman Sep 2006 Call MRD_SKIP to skip bytes on different file types W. Landsman Oct 2006 Make ndata 64bit for very large files E. Hivon/W. Landsman May 2007 Fixed bug introduced March 2006 in applying Bzero C. Magri/W.L. Aug 2007 Check possible 32bit overflow when using NSKIP W. Landsman Mar 2008 Always reset BSCALE, BZERO even for unsigned integers W. Landsman May 2008 Make ndata 64bit for very large extensions J. Schou/W. Landsman Jan 2009 Use PRODUCT() to compute # of data points W. Landsman May 2009 Read FPACK compressed file via UNIX pipe. W. Landsman May 2009 Fix error using NUMROW,STARTROW with non-byte data, allow these keywords to be used with primary array W. Landsman July 2009 Ignore degenerate trailing dimensions with NSLICE keyword W.L. Oct 2009 Add DIALOG_PICKFILE() if filename is an empty string W.L. Apr 2010 Set BLANK values *before* applying BSCALE,BZERO, use short-circuit operators W.L. May 2010 Skip extra SPAWN with FPACK decompress J. Eastman, W.L. July 2010 Fix possible problem when startrow=0 supplied J. Eastman/W.L. Aug 2010 First header is not necessarily primary if unit supplied WL Jan 2011 Fix test for 'SIMPLE' at beginning of header WL November 2012(See astrolib/pro/readfits.pro)
READFMT
[Previous Routine] [Next Routine] [List of Routines]NAME: READFMT PURPOSE: Quickly read a fixed format ASCII data file into IDL variables. EXPLANATION: Lines of data not meeting the specified format (e.g. comments) are ignored. To read a free format ASCII data file use the procedures READCOL or RDFLOAT. To print (formatted or free) columns of data use the procedure FORPRINT. CALLING SEQUENCE: READFMT, name, fmt, v1,[ v2, v3, v4, ..., v25 , /SILENT, /DEBUG, SKIPLINE= , NUMLINE =] INPUTS: NAME - Name of ASCII data file. An extension of .DAT is assumed, if not supplied. FMT - scalar string containing a valid FORTRAN read format. Must include a field length specification. Cannot include internal parenthesis. A format field must be included for each output vector. Multiple format fields are allowed, but the repetition factor must be less than 100, (.i.e. 19X is allowed but 117X is illegal) Examples of valid FMT values are FMT = 'A7,3X,2I4' or FMT = '1H ,5I7,2A7' Examples of INVALID FMT values are FMT = 'A7,B3' ;'B' is not a valid FORTRAN format FMT = 'A7,2(I3,F5.1)' ;Internal parenthesis not allowed FMT = 'A7,F,I' ;Field length not included OUTPUTS: V1,V2,V3,V4... - IDL vectors to contain columns of data. Up to 25 output vectors may be read. The type of the output vectors are specified by FMT. OPTIONAL KEYWORD INPUTS: /SILENT - If this keyword is set and non-zero, then certain terminal output is suppressed while reading the file /DEBUG - Set this keyword to display additional information while reading the file. SKIPLINE - Scalar specifying number of lines to skip at the top of file before reading. Default is to start at first line NUMLINE - Scalar specifying number of lines in the file to read. Default is to read the entire file EXAMPLES: Each row in a fixed-format file POSITION.DAT contains a 5 character star name and 6 columns of data giving an RA and Dec in sexagesimal format. A possible format for such data might be IDL> FMT = 'A5,2I3,F5.1,2x,3I3' and the file could be quickly read with IDL> READFMT,'POSITION', fmt, name, hr, min, sec, deg, dmin, dsec NAME will be a string vector,SEC will be a floating point vector, and the other vectors will be of integer type. RESTRICTIONS: This procedure is designed for generality and not for speed. If a large ASCII file is to be read repeatedly, it may be worth writing a specialized reader. NOTES: When reading a field with an integer format I, the output vector is byte - if n = 1 integer*2 - if 1 < n < 5 integer*4 - in all other cases Octal ('O') and hexadecimal ('Z') formats are read into longwords PROCEDURE CALLS: GETTOK(), REMCHAR, ZPARCHECK REVISION HISTORY: Written W. Landsman November, 1988 Added SKIPLINE and NUMLINE keywords March 92 Allow up to 25 columns to be read June 92 Call NUMLINES() function Feb 1996 Recognize 'O' and 'Z' formats W. Landsman September 1997 Recognize 'G' format, use SKIP_LUN W. Landsman May 2010 (See astrolib/pro/readfmt.pro)
READ_FMR
[Previous Routine] [Next Routine] [List of Routines]NAME: READ_FMR PURPOSE: Read a journal (ApJ, AJ) machine-readable table into IDL EXPLANATION: Given a machine readable table name and optionally column numbers, this FUNCTION reads the format information in the meta-header and outputs a IDL function containing either the complete table or only the requested columns. CALLING SEQUENCE: data = read_fmr(filename) INPUTS: filename [STRING]: the name of the file containing the machine readable table. If filename is missing a dialog to select the filename will be presented INPUT KEYWORD PARAMETERS: /HELP - if set show the help COLUMNS - [(array of) integers or strings] of column(s) to be returned. If columns is of type integer they represent indices for which column numbers to return, if they are strings the columns with the corresponding names will be returned in the order as given. MISSINGVALUE [float]: value with which to replace the missing values in the table, default is NaN. /USE_COLNUM - If specified and non-zero then column names will be generated as 'C1, C2, .... Cn' for the number of columns in the table, rather than using the table names. OUTPUTS: The ouput data structure will look like: TYPE STRING 'mr_structure' NAME STRING Array[X] UNIT STRING Array[X] DESCRIPTION STRING Array[X] DATA STRUCT ->Array[1] where name contains the names of each columns unit contains the given units description contains the short descriptions and data holds the values of the separate columns. By default the tag names are taken from the column names, with modifications necessary to make them a valid tag name. For example, the column name 'B-V' will be converted to 'B_V' to become a valid tag name. If the /USE_COLNUM keyword is set, then the column will be named C0, C1, ... , CX, where X stands for the total number of columns read. RESTRICTIONS: (1) The file to be read should be formatted as a machine readable datafile. (2) Use of the COLUMN keyword currently requires use of the EXECUTE, and so cannot be used with the IDL Virtural machine. EXAMPLE: meas = read_fmr('smith.dat',col=[2,5,6], /Use_colnum) plot,meas.data.c1,ytitle=meas.name[1]+' ('+meas.unit[1]+')' and data = read_fmr('smith.dat',col=['Name','Date'], /Use_colnum) print,meas.data.c0 MODIFICATION HISTORY: Version 1: Written by Sacha Hony (ESA) Nov 14 2003 Based heavily on mrcolextract by Greg Schwarz (AAS Journals staff scientist) on 8/16/00. Version 1.1: Fixed bug where column=[3,4] always returned the first few columns VErsion 2.0 By default use column names as tag names W. Landsman Feb 2010 (See astrolib/pro/read_fmr.pro)
READ_KEY
[Previous Routine] [Next Routine] [List of Routines]NAME: READ_KEY PURPOSE: To read a keystroke and return its ASCII equivalent EXPLANATION: If an ESCAPE sequence was produced and the sequence is recognized (e.g. up arrow), then a code is returned. This functionality is mostly made obsolete by the addition of the ESCAPE and KEY_NAME keywords to GET_KBRD in IDL V6.2 CALLING SEQUENCE: key = READ_KEY(Wait) INPUTS: Wait - The wait flag. If non-zero, execution is halted until a key is struck. If zero, execution returns immediately and a zero is returned if there was no keystroke waiting in the keyboard buffer. If not specified, zero is assumed. OUTPUT: Returned - The key struck. The ASCII code for non-escape sequences. Escape sequence equivalents: Up Arrow -- 128 Down Arrow -- 130 Left Arrow -- 129 Right Arrow -- 131 Else -- 0 The return value is a byte value. MODIFICATION HISTORY: Written by Michael R. Greason, STX, 22 June 1990. Rewritten for a SUN workstation. MRG, STX, 23 August 1990. Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/read_key.pro)
REMCHAR
[Previous Routine] [Next Routine] [List of Routines]NAME: REMCHAR PURPOSE: Remove all appearances of character (char) from string (st) CALLING SEQUENCE: REMCHAR, ST, CHAR INPUT-OUTPUT: ST - String from which character will be removed, scalar or vector INPUT: CHAR- Single character to be removed from string or all elements of a string array EXAMPLE: If a = 'a,b,c,d,e,f,g' then IDL> remchar,a, ',' will give a = 'abcdefg' REVISIONS HISTORY Written D. Lindler October 1986 Test if empty string needs to be returned W. Landsman Feb 1991 Work on string arrays W. Landsman August 1997 Avoid 32 bit integer overflow K. Tolbert/W. Landsman Feb 2007(See astrolib/pro/remchar.pro)
REMOVE
[Previous Routine] [Next Routine] [List of Routines]NAME: REMOVE PURPOSE: Contract a vector or up to 25 vectors by removing specified elements CALLING SEQUENCE: REMOVE, index, v1,[ v2, v3, v4, v5, v6, ... v25] INPUTS: INDEX - scalar or vector giving the index number of elements to be removed from vectors. Duplicate entries in index are ignored. An error will occur if one attempts to remove all the elements of a vector. REMOVE will return quietly (no error message) if index is !NULL or undefined. INPUT-OUTPUT: v1 - Vector or array. Elements specifed by INDEX will be removed from v1. Upon return v1 will contain N fewer elements, where N is the number of distinct values in INDEX. OPTIONAL INPUT-OUTPUTS: v2,v3,...v25 - additional vectors containing the same number of elements as v1. These will be contracted in the same manner as v1. EXAMPLES: (1) If INDEX = [2,4,6,4] and V = [1,3,4,3,2,5,7,3] then after the call IDL> remove,index,v V will contain the values [1,3,3,5,3] (2) Suppose one has a wavelength vector W, and three associated flux vectors F1, F2, and F3. Remove all points where a quality vector, EPS is negative IDL> bad = where( EPS LT 0, Nbad) IDL> if Nbad GT 0 then remove, bad, w, f1, f2, f3 METHOD: If more than one element is to be removed, then HISTOGRAM is used to generate a 'keep' subscripting vector. To minimize the length of the subscripting vector, it is only computed between the minimum and maximum values of the index. Therefore, the slowest case of REMOVE is when both the first and last element are removed. REVISION HISTORY: Written W. Landsman ST Systems Co. April 28, 1988 Cleaned up code W. Landsman September, 1992 Major rewrite for improved speed W. Landsman April 2000 Accept up to 25 variables, use SCOPE_VARFETCH internally W. Landsman Feb 2010 Fix occasional integer overflow problem V. Geers Feb 2011 Quietly return if index is !null or undefined W.L. Aug 2011(See astrolib/pro/remove.pro)
REM_DUP
[Previous Routine] [Next Routine] [List of Routines]NAME: REM_DUP PURPOSE: Function to remove duplicate values from a vector. CALLING SEQUENCE: result = rem_dup( a, [ flag ] ) INPUTS: a - vector of values from which duplicates are to be found flag - (optional) if supplied then when duplicates occur, the one with the largest value of flag is selected. If not supplied the the first occurence of the value in a is selected. Should be a vector with the same number of elements as a. OUTPUT: A vector of subscripts in a is returned. Each subscript points to a selected value such that a(rem_dup(a,flag)) has no duplicates. SIDE EFFECTS: The returned subscripts will sort the values in a in ascending order with duplicates removed. EXAMPLES: Remove duplicate values in vector a. a = a[ rem_dup(a)] Remove duplicates in vector WAVE. When duplicate values are found, select the one with the largest intensity, INTE. sub = rem_dup( wave, inte) wave = wave[sub] inte = inte[sub] NOTES: The UNIQ function in the User's Library uses a faster algorithm, but has no equivalent of the "flag" parameter. Also, note that REM_DUP() gives the index of the *first* equal value found, while UNIQ() gives the index of the *last* equal value found. MODIFICATION HISTORY: D. Lindler Mar. 87 11/16/90 JKF ACC - converted to IDL Version 2. August 1997 -- Changed loop index to type LONG October 1997 -- Also changed NGOOD index to LONG April 2007 - Use faster algorithm when Flag vector not set, W. Landsman Feb 2011 - Remove spurious line W.L. Jan 2012 - Call BSORT() to ensure original order maintained for equal values(See astrolib/pro/rem_dup.pro)
REPSTR
[Previous Routine] [Next Routine] [List of Routines]NAME: REPSTR PURPOSE: Replace all occurences of one substring by another. EXPLANATION: Meant to emulate the string substitution capabilities of text editors For a more sophisticated routine that allows regular expressions look at MG_STRREPLACE() http://docs.idldev.com/idllib/strings/mg_streplace.html CALLING SEQUENCE: result = repstr( obj, in, out ) INPUT PARAMETERS: obj = object string for editing, scalar or array in = substring of 'obj' to be replaced, scalar OPTIONAL INPUT PARMETER: out = what 'in' is replaced with, scalar. If not supplied then out = '', i.e. 'in' is not replaced by anything. OUTPUT PARAMETERS: Result returned as function value. Input object string not changed unless assignment done in calling program. PROCEDURE: Searches for 'in', splits 'obj' into 3 pieces, reassembles with 'out' in place of 'in'. Repeats until all cases done. EXAMPLE: If a = 'I am what I am' then print,repstr(a,'am','was') will give 'I was what I was'. MODIFICATION HISTORY: Written by Robert S. Hill, ST Systems Corp., 12 April 1989. Accept vector object strings, W. Landsman HSTX, April, 1996 Convert loop to LONG, vectorize STRLEN call W. Landsman June 2002 Correct bug in optimization, case where STRLEN(OBJ) EQ STRLEN(IN), C. Markwardt, Jan 2003 Fixed problem when multiple replacements extend the string length D. Finkbeiner, W. Landsman April 2003 Allow third parameter to be optional again W. Landsman August 2003 Remove limitation of 9999 characters, C. Markwardt Dec 2003 Test for empty "in" string (causing infinite loop) W. Landsman Jan 2010 Streamline code W Landsman Dec 2011(See astrolib/pro/repstr.pro)
RESISTANT_MEAN
[Previous Routine] [Next Routine] [List of Routines]NAME: RESISTANT_Mean PURPOSE: Outlier-resistant determination of the mean and standard deviation. EXPLANATION: RESISTANT_Mean trims away outliers using the median and the median absolute deviation. An approximation formula is used to correct for the truncation caused by trimming away outliers CALLING SEQUENCE: RESISTANT_Mean, ARRAY, Sigma_CUT, Mean, Sigma_Mean, Num_RejECTED [/DOUBLE, DIMENSION= , GOODVEC = ] INPUT ARGUMENT: ARRAY = Vector or array to average Sigma_CUT = Data more than this number of standard deviations from the median is ignored. Suggested values: 2.0 and up. OUTPUT ARGUMENT: Mean = the mean of the input array, numeric scalar, If the DIMENSION keyword is set, then MEAN will be an array with one less dimension than the input. OPTIONAL OUTPUTS: Sigma_Mean = the approximate standard deviation of the mean, numeric scalar. This is the Sigma of the distribution divided by sqrt(N-1) where N is the number of unrejected points. The larger SIGMA_CUT, the more accurate. It will tend to underestimate the true uncertainty of the mean, and this may become significant for cuts of 2.0 or less. Num_RejECTED = the number of points trimmed, integer scalar OPTIONAL INPUT KEYWORDS: /DOUBLE - If set, then all calculations are performed internally in double precision. DIMENSION - for a multi-dimensional array, the dimension over which to take the mean, starting at 1. If not set, then the scalar mean over all elements is used. If this argument is present, the result is an array with one less dimension than Array. For example, if the dimensions of Array are N1, N2, N3, and Dimension is 2, then the dimensions of the result are (N1, N3) SUMDIM - Obsolete synonym for DIMENSION OPTIONAL OUTPUT KEYWORD: Goodvec - Indices of non-trimmed elements of the input vector Wused - synonym for Goodvec (for solarsoft compatibility) EXAMPLE: IDL> a = randomn(seed, 10000) ;Normal distribution with 10000 pts IDL> RESISTANT_Mean,a, 3, mean, meansig, num ;3 Sigma clipping IDL> print, mean, meansig,num The mean should be near 0, and meansig should be near 0.01 ( = 1/sqrt(10000) ). PROCEDURES USED: MEAN() - compute simple mean, in Exelis library REVISION HISTORY: Written, H. Freudenreich, STX, 1989; Second iteration added 5/91. Use MEDIAN(/EVEN) W. Landsman April 2002 Correct conditional test, higher order truncation correction formula R. Arendt/W. Landsman June 2002 New truncation formula for sigma H. Freudenriech July 2002 Divide Sigma_mean by Num_good rather than Npts W. Landsman/A. Conley January 2006 Use of double precision S. Bianchi February 2008 More double precision B. Carcich December 2009 Added DIMENSION keyword (from M. Desnoyer) B. Carcich December 2009 Use IDL's MEAN() function instead of AVG() W. Landsman Jan 2012 Use of Dimension keyword yielded transpose of correct value W. Landsman July 2012(See astrolib/pro/resistant_mean.pro)
RHOTHETA
[Previous Routine] [Next Routine] [List of Routines]NAME: RHOTHETA PURPOSE: Calculate the separation and position angle of a binary star EXPLANATION: This function will return the separation rho and position angle theta of a visual binary star derived from its orbital elements. The algorithms described in the following book will be used: Meeus J., 1992, Astronomische Algorithmen, Barth. Compared to the examples given at p. 400 and no discrepancy found. Input parameters will never be changed. CALLING SEQUENCE: Result = RHOTHETA ( P, T, e, a, i, Omega, omega2, t2) INPUT: P - Period [year] T - Time of periastron passage [year] e - eccentricity of the orbit a - semi-major axis [arc second] i - inclination [degree] Omega - node [degree] omega2 - longitude of periastron [degree] t2 - epoch of observation [year] OUTPUT: structure containing rho - separation [arc second] theta - position angle [degree] In case of errors rho and theta are -1. RESTRICTIONS: All input parameters have to be scalars and floating point numbers. EXAMPLE: Find the position of Eta Coronae Borealis at the epoch 1980.0 IDL> test=rhotheta(41.623,1934.008,0.2763,0.907,59.025,23.717,219.907,1980.0) rho= 0.411014 theta= 318.42307 PROCEDURES CALLED: CIRRANGE - from IDL Astronomy Library MODIFICATION HISTORY: Written by: Sebastian Kohl Hamburg Observatory, November, 2012(See astrolib/pro/rhotheta.pro)
RINTER
[Previous Routine] [Next Routine] [List of Routines]NAME: RINTER PURPOSE: Cubic interpolation of an image at a set of reference points. EXPLANATION: This interpolation program is equivalent to using the intrinsic INTERPOLATE() function with CUBIC = -0.5. However, RINTER() has two advantages: (1) one can optionally obtain the X and Y derivatives at the reference points, and (2) if repeated interpolation is to be applied to an array, then some values can be pre-computed and stored in Common. RINTER() was originally for use with the DAOPHOT procedures, but can also be used for general cubic interpolation. CALLING SEQUENCE: Z = RINTER( P, X, Y, [ DFDX, DFDY ] ) or Z = RINTER(P, /INIT) INPUTS: P - Two dimensional data array, X - Either an N element vector or an N x M element array, containing X subscripts where cubic interpolation is desired. Y - Either an N element vector or an N x M element array, containing Y subscripts where cubic interpolation is desired. OUTPUT: Z - Result = interpolated vector or array. If X and Y are vectors, then so is Z, but if X and Y are arrays then Z will be also. If P is DOUBLE precision, then so is Z, otherwise Z is REAL. OPTIONAL OUTPUT: DFDX - Vector or Array, (same size and type as Z), containing the derivatives with respect to X DFDY - Array containing derivatives with respect to Y OPTIONAL KEYWORD INPUT: /INIT - Perform computations associated only with the input array (i.e. not with X and Y) and store in common. This can save time if repeated calls to RINTER are made using the same array. EXAMPLE: suppose P is a 256 x 256 element array and X = FINDGEN(50)/2. + 100. and Y = X. Then Z will be a 50 element array, containing the cubic interpolated points. SIDE EFFECTS: can be time consuming. RESTRICTION: Interpolation is not possible at positions outside the range of the array (including all negative subscripts), or within 2 pixel units of the edge. No error message is given but values of the output array are meaningless at these positions. PROCEDURE: invokes CUBIC interpolation algorithm to evaluate each element in Z at virtual coordinates contained in X and Y with the data in P. COMMON BLOCKS: If repeated interpolation of the same array is to occur, then one can save time by initializing the common block RINTER. REVISION HISTORY: March 1988 written W. Landsman STX Co. Checked for IDL Version 2, J. Isensee, September, 1990 Corrected call to HISTOGRAM, W. Landsman November 1990 Converted to IDL V5.0 W. Landsman September 1997 Fix output derivatives for 2-d inputs, added /INIT W. Landsman May 2000(See astrolib/pro/rinter.pro)
ROBUST_LINEFIT
[Previous Routine] [Next Routine] [List of Routines]NAME: ROBUST_LINEFIT PURPOSE: An outlier-resistant two-variable linear regression. EXPLANATION: Either Y on X or, for the case in which there is no true independent variable, the bisecting line of Y vs X and X vs Y is calculated. No knowledge of the errors of the input points is assumed. CALLING SEQUENCE: COEFF = ROBUST_LINEFIT( X, Y, YFIT, SIG, COEF_SIG, [ /BISECT, BiSquare_Limit = , Close_factor = , NumIT = ] ) INPUTS: X = Independent variable vector, floating-point or double-precision Y = Dependent variable vector OUTPUTS: Function result = coefficient vector. If = 0.0 (scalar), no fit was possible. If vector has more than 2 elements (the last=0) then the fit is dubious. OPTIONAL OUTPUT PARAMETERS: YFIT = Vector of calculated y's SIG = The "standard deviation" of the fit's residuals. If BISECTOR is set, this will be smaller by ~ sqrt(2). COEF_SIG = The estimated standard deviations of the coefficients. If BISECTOR is set, however, this becomes the vector of fit residuals measured orthogonal to the line. OPTIONAL INPUT KEYWORDS: NUMIT = the number of iterations allowed. Default = 25 BISECT if set, the bisector of the "Y vs X" and "X vs Y" fits is determined. The distance PERPENDICULAR to this line is used in calculating weights. This is better when the uncertainties in X and Y are comparable, so there is no true independent variable. Bisquare_Limit Limit used for calculation of bisquare weights. In units of outlier-resistant standard deviations. Default: 6. Smaller limit ==>more resistant, less efficient Close_Factor - Factor used to determine when the calculation has converged. Convergence if the computed standard deviation changes by less than Close_Factor * ( uncertainty of the std dev of a normal distribution ). Default: 0.03. SUBROUTINE CALLS: ROB_CHECKFIT ROBUST_SIGMA, to calculate a robust analog to the std. deviation PROCEDURE: For the initial estimate, the data is sorted by X and broken into 2 groups. A line is fitted to the x and y medians of each group. Bisquare ("Tukey's Biweight") weights are then calculated, using the a limit of 6 outlier-resistant standard deviations. This is done iteratively until the standard deviation changes by less than CLOSE_ENOUGH = CLOSE_FACTOR * {uncertainty of the standard deviation of a normal distribution} REVISION HISTORY: Written, H. Freudenreich, STX, 4/91. 4/13/93 to return more realistic SS's HF 2/94 --more error-checking, changed convergence criterion HF 5/94 --added BISECT option. HF. 8/94 --added Close_Factor and Bisquare_Limit options Jack Saba. 4/02 --V5.0 version, use MEDIAN(/EVEN) W. Landsman(See astrolib/pro/robust_linefit.pro)
ROBUST_POLY_FIT
[Previous Routine] [Next Routine] [List of Routines]NAME: ROBUST_POLY_FIT PURPOSE: An outlier-resistant polynomial fit. CALLING SEQUENCE: COEFF = ROBUST_POLY_FIT(X,Y,NDEGREE, [ YFIT,SIG, /DOUBLE, NUMIT=] ) INPUTS: X = Independent variable vector, floating-point or double-precision Y = Dependent variable vector NDEGREE - integer giving degree of polynomial to fit, maximum = 6 OUTPUTS: Function result = coefficient vector, length NDEGREE+1. IF COEFF=0.0, NO FIT! If N_ELEMENTS(COEFF) > degree+1, the fit is poor (in this case the last element of COEFF=0.) Either floating point or double precision. OPTIONAL OUTPUT PARAMETERS: YFIT = Vector of calculated y's SIG = the "standard deviation" of the residuals OPTIONAL INPUT KEYWORD: /DOUBLE - If set, then force all computations to double precision. NUMIT - Maximum number of iterations to perform, default = 25 RESTRICTIONS: Large values of NDEGREE should be avoided. This routine works best when the number of points >> NDEGREE. PROCEDURE: For the initial estimate, the data is sorted by X and broken into NDEGREE+2 sets. The X,Y medians of each set are fitted to a polynomial via POLY_FIT. Bisquare ("Tukey's Biweight") weights are then calculated, using a limit of 6 outlier-resistant standard deviations. The fit is repeated iteratively until the robust standard deviation of the residuals changes by less than .03xSQRT(.5/(N-1)). PROCEDURES CALLED: POLY(), POLY_FIT() ROB_CHECKFIT() REVISION HISTORY Written, H. Freudenreich, STX, 8/90. Revised 4/91. 2/94 -- changed convergence criterion Added /DOUBLE keyword, remove POLYFITW call W. Landsman Jan 2009(See astrolib/pro/robust_poly_fit.pro)
ROBUST_SIGMA
[Previous Routine] [Next Routine] [List of Routines]NAME: ROBUST_SIGMA PURPOSE: Calculate a resistant estimate of the dispersion of a distribution. EXPLANATION: For an uncontaminated distribution, this is identical to the standard deviation. CALLING SEQUENCE: result = ROBUST_SIGMA( Y, [ /ZERO, GOODVEC = ] ) INPUT: Y = Vector of quantity for which the dispersion is to be calculated OPTIONAL INPUT KEYWORD: /ZERO - if set, the dispersion is calculated w.r.t. 0.0 rather than the central value of the vector. If Y is a vector of residuals, this should be set. OPTIONAL OUPTUT KEYWORD: GOODVEC = Vector of non-trimmed indices of the input vector OUTPUT: ROBUST_SIGMA returns the dispersion. In case of failure, returns value of -1.0 PROCEDURE: Use the median absolute deviation as the initial estimate, then weight points using Tukey's Biweight. See, for example, "Understanding Robust and Exploratory Data Analysis," by Hoaglin, Mosteller and Tukey, John Wiley & Sons, 1983, or equation 9 in Beers et al. (1990, AJ, 100, 32) REVSION HISTORY: H. Freudenreich, STX, 8/90 Replace MED() call with MEDIAN(/EVEN) W. Landsman December 2001 Don't count NaN values W.Landsman June 2010(See astrolib/pro/robust_sigma.pro)
ROB_CHECKFIT
[Previous Routine] [Next Routine] [List of Routines]NAME: ROB_CHECKFIT PURPOSE: Used by ROBUST_... routines to determine the quality of a fit and to return biweights. CALLING SEQUENCE: status = ROB_CHECKFIT( Y, YFIT, EPS, DEL, SIG, FRACDEV, NGOOD, W, B BISQUARE_LIMIT = ) INPUT: Y = the data YFIT = the fit to the data EPS = the "too small" limit DEL = the "close enough" for the fractional median abs. deviations RETURNS: Integer status. if =1, the fit is considered to have converged OUTPUTS: SIG = robust standard deviation analog FRACDEV = the fractional median absolute deviation of the residuals NGOOD = the number of input point given non-zero weight in the calculation W = the bisquare weights of Y B = residuals scaled by sigma OPTIONAL INPUT KEYWORD: BISQUARE_LIMIT = allows changing the bisquare weight limit from default 6.0 PROCEDURES USED: ROBUST_SIGMA() REVISION HISTORY: Written, H.T. Freudenreich, HSTX, 1/94(See astrolib/pro/rob_checkfit.pro)
SELECT_W
[Previous Routine] [Next Routine] [List of Routines]NAME: SELECT_W PURPOSE: Create a non-exclusive widget menu of items EXPLANATION: More than one item may be selected or 'de-selected'. Normally called by SCREEN_SELECT CALLING SEQUENCE: SELECT_W, items ,iselected, [ comments, command_line, only_one ] INPUTS: items - string array giving list of items that can be selected. OPTIONAL INPUTS: comments - comments which can be requested for each item in array selections. NOT YET IMPLEMENTED command_line - optional command line to be placed at the bottom of the screen. It is usually used to specify what the user is selecting. only_one - integer flag. If set to 1 then the user can only select one item. The routine returns immediately after the first selection is made. OPTIONAL KEYWORD INPUT SELECTIN - vector of items to be pre-selected upon input (not used for only_one option) OUTPUT: iselected - list of indices in selections giving the selected items. OPTIONAL OUTPUT KEYWORD: COUNT - Integer scalar giving the number of items selected COMMON BLOCKS: SELECT_W - Used to communicate with the SELECT_W_EVENT procedure MODIFICATION HISTORY: Written, K. Venkatakrishna & W. Landsman, Hughes/STX January, 1992 Widgets made MODAL. M. Greason, Hughes STX, 15 July 1992. Changed handling of MODAL keyword for V5.0 W.Thompson September 1997 Added selectin keyword D. Lindler 01/12/99(See astrolib/pro/select_w.pro)
SIGMA_FILTER
[Previous Routine] [Next Routine] [List of Routines]NAME: SIGMA_FILTER PURPOSE: Replace pixels more than a specified pixels deviant from its neighbors EXPLANATION: Computes the mean and standard deviation of pixels in a box centered at each pixel of the image, but excluding the center pixel. If the center pixel value exceeds some # of standard deviations from the mean, it is replaced by the mean in box. Note option to process pixels on the edges. CALLING SEQUENCE: Result = sigma_filter( image, box_width, N_sigma=(#), /ALL,/MON ) INPUTS: image = 2-D image (matrix) box_width = width of square filter box, in # pixels (default = 3) KEYWORDS: N_sigma = # standard deviations to define outliers, floating point, recommend > 2, default = 3. For gaussian statistics: N_sigma = 1 smooths 35% of pixels, 2 = 5%, 3 = 1%. RADIUS = alternative to specify box radius, so box_width = 2*radius+1. /ALL_PIXELS causes computation to include edges of image, /KEEP causes opposite effect: pixels with values outside of specified deviation are not changed, pixels within deviation are smoothed. /ITERATE causes sigma_filter to be applied recursively (max = 20 times) until no more pixels change (only allowed when N_sigma >= 2). /MONITOR prints information about % pixels replaced. Optional Outputs: N_CHANGE = # of pixels changed (replaced with neighborhood mean). VARIANCE = image of pixel neighborhood variances * (N_sigma)^2, DEVIATION = image of pixel deviations from neighborhood means, squared. CALLS: function filter_image( ) PROCEDURE: Compute mean over moving box-cars using smooth, subtract center values, compute variance using smooth on deviations from mean, check where pixel deviation from mean is within variance of box, replace those pixels in smoothed image (mean) with orignal values, return the resulting partial mean image. MODIFICATION HISTORY: Written, 1991, Frank Varosi and Dan Gezari NASA/GSFC F.V.1992, added optional keywords /ITER,/MON,VAR=,DEV=,N_CHANGE=. Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/sigma_filter.pro)
SIGRANGE()
[Previous Routine] [Next Routine] [List of Routines]NAME: SIGRANGE() PURPOSE: Selects the most significant data range in an image. EXPLANATION: Selects out the most significant range in the data to be used in displaying images. The histogram of ARRAY is used to select the most significant range. Useful for scaling an image display. CALLING SEQUENCE: OUTPUT = SIGRANGE( ARRAY ) INPUTS: ARRAY = Array to take most significant range of. OPTIONAL INPUTS: None. OUTPUTS: The function returns an array where values above and below the selected range are set equal to the maximum and minimum of the range respectively. OPTIONAL INPUT KEYWORDS: FRACTION = Fraction of data to consider most significant. Defaults to 0.99 MISSING = Value used to flag missing points. Data points with this value are not considered or changed. OPTIONAL OUTPUT KEYWORD RANGE = 2 element vector, giving the range (minimum and maxmimum) used NOTES: If the image array contains more than 10,000 points then SIGRANGE() uses random indexing of a subset of the points to determine the range (for speed). Thus identical calls to SIGRANGE() might not yield identical results (although they should be very close). RESTRICTIONS: ARRAY must have more than two points. Fraction must be greater than 0 and less than 1. SIGRANGE was originally part of the SERTS image display package. Other routines from this package are available at http://sohowww.nascom.nasa.gov/solarsoft/gen/idl/image/ Note that this version of SIGRANGE does not include the non-standard system variables used in the SERTS package. REVISION HISTORY: Version 1, William Thompson, GSFC, 12 May 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 25 May 1993. Changed call to HISTOGRAM to be compatible with OpenVMS/ALPHA Version 3, CDP, RAL, Add RANGE keyword. 16-Apr-96 Version 4, William Thompson, GSFC, 17 April 1996 Corrected some problems when range is too high. Version 5, 13-Jan-1998, William Thompson, GSFC Use random numbers to improve statistics when only using a fraction of the array. Version 6, 06-Mar-1998, William Thompson, GSFC Change default to 0.99(See astrolib/pro/sigrange.pro)
SIXLIN
[Previous Routine] [Next Routine] [List of Routines]NAME: SIXLIN PURPOSE: Compute linear regression coefficients by six different methods. EXPLANATION: Adapted from the FORTRAN program (Rev. 1.1) supplied by Isobe, Feigelson, Akritas, and Babu Ap. J. Vol. 364, p. 104 (1990). Suggested when there is no understanding about the nature of the scatter about a linear relation, and NOT when the errors in the variable are calculable. CALLING SEQUENCE: SIXLIN, xx, yy, a, siga, b, sigb, [WEIGHT = ] INPUTS: XX - vector of X values YY - vector of Y values, same number of elements as XX OUTPUTS: A - Vector of 6 Y intercept coefficients SIGA - Vector of standard deviations of 6 Y intercepts B - Vector of 6 slope coefficients SIGB - Vector of standard deviations of slope coefficients The output variables are computed using linear regression for each of the following 6 cases: (0) Ordinary Least Squares (OLS) Y vs. X (c.f. linfit.pro) (1) Ordinary Least Squares X vs. Y (2) Ordinary Least Squares Bisector (3) Orthogonal Reduced Major Axis (4) Reduced Major-Axis (5) Mean ordinary Least Squares OPTIONAL INPUT KEYWORD: WEIGHT - vector of weights, same number of elements as XX and YY For 1 sigma Gausssian errors, the weights are 1/sigma^2 but the weight vector can be more general. Default is no weighting. NOTES: Isobe et al. make the following recommendations (1) If the different linear regression methods yield similar results then quoting OLS(Y|X) is probably the most familiar. (2) If the linear relation is to be used to predict Y vs. X then OLS(Y|X) should be used. (3) If the goal is to determine the functional relationship between X and Y then the OLS bisector is recommended. REVISION HISTORY: Written Wayne Landsman February, 1991 Corrected sigma calculations February, 1992 Converted to IDL V5.0 W. Landsman September 1997 Added WEIGHT keyword J. Moustakas Februrary 2007(See astrolib/pro/sixlin.pro)
SIXTY()
[Previous Routine] [Next Routine] [List of Routines]NAME: SIXTY() PURPOSE: Converts a decimal number to sexagesimal. EXPLANATION: Reverse of the TEN() function. CALLING SEQUENCE: X = SIXTY( SCALAR, [ /TrailSign ] ) INPUTS: SCALAR -- Decimal quantity. OUTPUTS: Function value returned = real vector of three elements, sexagesimal equivalent of input decimal quantity. Double precision if the input is double, otherwise floating point. By default, a negative number is signified by making the first non-zero element of the output vection negative, but this can be modfied with the /TrailSign keyword. OPTIONAL INPUT KEYWORD: /TrailSign - By default, SIXTY() returns a negative sign in the first nonzero element. If /TrailSign is set, then SIXTY() will return always return a negative sign in the first element, even if it is zero PROCEDURE: Mostly involves checking arguments and setting the sign. EXAMPLE: If x = -0.345d then sixty(x) = [0.0, -20.0, 42.0] and sixty(x,/trail) = [-0.0, 20.0, 42.0] MODIFICATION HISTORY: Written by R. S. Hill, STX, 19-OCT-87 Output changed to single precision. RSH, STX, 1/26/88 Accept single element vector W. Landsman Sep. 1996 Converted to IDL V5.0 W. Landsman September 1997 Added /TrailSign keyword, preserve data type B. Stecklum/ W. Landsman March 2006(See astrolib/pro/sixty.pro)
SKY
[Previous Routine] [Next Routine] [List of Routines]NAME: SKY PURPOSE: Determine the sky level in an image EXPLANATION: Approximately 10000 uniformly spaced pixels are selected for the computation. Adapted from the DAOPHOT routine of the same name. The sky is computed either by using the procedure mmm.pro (default) or by sigma clipping (if /MEANBACK is set) CALLING SEQUENCE: SKY, image, [ skymode, skysig ,/SILENT, /MEANBACK, /NAN, CIRCLERAD= ] Keywords available when MEANBACK is not set (passed to mmm.pro): /DEBUG, HIGHBAD=, /INTEGER, MAXITER=. READNOISE= Keywords available when /MEANBACK is set: CLIPSIG=, /DOUBLE, CONVERGE_NUM=, MAXITER=, /VERBOSE INPUTS: IMAGE - One or two dimensional array OPTIONAL OUTPUT ARRAYS: SKYMODE - Scalar, giving the mode of the sky pixel values of the array IMAGE, as determined by the procedures MMM or MEANCLIP SKYSIG - Scalar, giving standard deviation of sky brightness. If it was not possible to derive a mode then SKYSIG is set to -1 INPUT KEYWORD PARAMETERS: CIRCLERAD - Use this keyword to have SKY only select pixels within specified pixel radius of the center of the image. If CIRCLERAD =1, then the radius is set equal to half the image width. Can only be used with square images. /MEANBACK - if set, then the background is computed using the 3 sigma clipped mean (using meanclip.pro) rather than using the mode computed with mmm.pro. This keyword is useful for the Poisson count regime or where contamination is known to be minimal. /NAN - This keyword must be set to ignore NaN values when computing the sky. /SILENT - If this keyword is supplied and non-zero, then SKY will not display the sky value and sigma at the terminal The _EXTRA facility can is used to pass optional keywords to the programs that actually perform the sky computation: either mmm.pro (default) or meanclip.pro (if /MEANBACK) is set. The following keywords are available with the mmm.pro (default) setting HIGHBAD - scalar value of the (lowest) "bad" pixel level (e.g. cosmic rays or saturated pixels) If not supplied, then there is assumed to be no high bad pixels. READNOISE - Scalar giving the read noise (or minimum noise for any pixel). Normally, MMM determines the (robust) median by averaging the central 20% of the sky values. In some cases where the noise is low, and pixel values are quantized a larger fraction may be needed. By supplying the optional read noise parameter, MMM is better able to adjust the fraction of pixels used to determine the median. /INTEGER - Set this keyword if the input SKY image only contains discrete integer values. This keyword is only needed if the SKY image is of type float or double precision, but contains only discrete integer values. If the /MEANBACK keyword is set then the following keywords are available CLIPSIG: Number of sigma at which to clip. Default=3 MAXITER: Ceiling on number of clipping iterations. Default=5 CONVERGE_NUM: If the proportion of rejected pixels is less than this fraction, the iterations stop. Default=0.02, i.e., iteration stops if fewer than 2% of pixels excluded. /DOUBLE - if set then perform all computations in double precision. Otherwise double precision is used only if the input data is double PROCEDURE: A grid of points, not exceeding 10000 in number, is extracted from the srray. The mode of these pixel values is determined by the procedure mmm.pro or meanclip.pro. In a 2-d array the grid is staggered in each row to avoid emphasizing possible bad columns PROCEDURE CALLS: MEANCLIP, MMM, DIST_CIRCLE REVISION HISTORY: Written, W. Landsman STX Co. September, 1987 Changed INDGEN to LINDGEN January, 1994 Fixed display of # of points used March, 1994 Stagger beginning pixel in each row, added NSKY, READNOISE, HIGHBAD W. Landsman June 2004 Adjustments for unbiased sampling W. Landsman June 2004 Added /NAN keyword, put back CIRCLERAD keyword W. Landsman July 2004 Added MEANBACK keyword, _EXTRA kewyord ,preserve data type in calculations W. Landsman November 2005 Fix problem for very large images by requiring at least 2 pixels to be sampled per row. March 2007 W. Landsman Avoid possible out of bounds if /NAN set W. Landsman Jan 2008 Use TOTAL(/INTEGER) June 2009(See astrolib/pro/sky.pro)
SKYADJ_CUBE
[Previous Routine] [Next Routine] [List of Routines]NAME: SKYADJ_CUBE PURPOSE: Sky adjust the planes of a datacube. EXPLANATION: When removing cosmic rays from a set of images, it is desirable that all images have the same sky level. This procedure (called by CR_REJECT) removes the sky from each image in a data cube. CALLING SEQUENCE: SKYADJ_CUBE,Datacube,Skyvals,Totsky MODIFIED ARGUMENT: Datacube: 3-D array with one image of same field in each plane. Returned with sky in each plane adjusted to zero. OUTPUT ARGUMENTS: Skyvals: Array of sky values used on each plane of datacube. For a scalar sky, this parameter is a vector containing the sky value for each image plane. For a vector sky, this parameter is a 2-D array where each line corresponds to one image plane. INPUT KEYWORD PARAMETERS: REGION - [X0,X1,Y0,Y1] to restrict area used for computation of sky. Default is 0.1*Xdim, 0.9*Xdim, 0.1*Ydim, 0.9*Ydim. If INPUT_MASK is specified, the two specs are combined, i.e., the intersection of the areas is used. VERBOSE - Flag. If set, print information on skyvals. NOEDIT - Flag. If set, return sky values without changing datacube. XMEDSKY - Flag. If set, return vector sky as a function of X. SELECT - Array of subscripts of planes of the cube to process. (Default=all) EXTRAPR - Applies only in XMEDSKY mode. Subregion to use for polynomial extrapolation of sky vector into portions excluded by REGION parameter. (Default=first and last 10% of pixels; set to zero to defeat extrapolation) EDEGREE - Applies only in XMEDSKY mode. Degree of polynomial for extrapolation (Default=1) INPUT_MASK - Cube of flags corresponding to data cube. If used, the sky computation is restricted to the smallest contiguous rectangle containing all the pixels flagged valid (with 1 rather than 0). PROCEDURE: Uses astronomy library "sky" routine for scalar sky and column-by-column median for vector sky. MODIFICATION HISTORY: 10 Jul. 1997 - Written. R. S. Hill, Hughes STX 20 Oct. 1997 - 1-D sky option. RSH 7 Aug. 1998 - SELECT keyword. RSH 6 Oct. 1998 - Extrapolation. RSH 7 Oct. 1998 - INPUT_MASK added. RSH 21 Oct. 1998 - Fallback to 3-sigma clipped mean if mode fails. RSH 22 Mar. 2000 - Combine mask with region rather having mask override region. Improve comments. RSH 16 June 2000 - On_error and message used. Square brackets for array subscripts. EXTRAP included in this file. WBL & RSH, 16 June 2000(See astrolib/pro/skyadj_cube.pro)
SPEC_DIR()
[Previous Routine] [Next Routine] [List of Routines]NAME: SPEC_DIR() PURPOSE: Complete a file specification by appending the default disk or directory CALLING SEQUENCE: File_spec = SPEC_DIR( filename, [ extension ] ) INPUT: filename - character string giving partial specification of a file name. Examples for different operating systems include the following: Unix: 'pro/test.dat', '$IDL_HOME/test','~/subpro' MacOS: ':Programs:test' Windows: '\pro\test.dat','d:\pro\test' OPTIONAL INPUT: exten - string giving a default file name extension to be used if filename does not contain one. Do not include the period. OUTPUT: File_spec - Complete file specification using default disk or directory when necessary. EXAMPLE: IDL> a = spec_dir('test','dat') is equivalent to the commands IDL> cd, current=cdir IDL> a = cdir + delim + 'test.dat' where delim is the OS-dependent separator METHOD: SPEC_DIR() decomposes the file name using FDECOMP, and appends the default directory (obtained from the FILE_EXPAND_PATH) if necessary. SPEC_DIR() does not check whether the constructed file name actually exists. PROCEDURES CALLED: FDECOMP, EXPAND_TILDE() REVISION HISTORY: Written W. Landsman STX July, 1987 Expand Unix tilde if necessary W. Landsman September 1997 Assume since V5.5, use FILE_EXPAND_PATH, remove VMS support W. Landsman September 2006(See astrolib/pro/spec_dir.pro)
SRCOR
[Previous Routine] [Next Routine] [List of Routines]NAME: SRCOR PURPOSE: Correlate the source positions found on two lists. EXPLANATION: Source matching is done by finding sources within a specified radius. If you have position errors available and wish to match by significance level, then try match_xy.pro in the TARA library (http://www.astro.psu.edu/xray/docs/TARA/) CALLING SEQUENCE: srcor,x1in,ylin,x2in,y2in,dcr,ind1,ind2, [MAGNITUDE=,SPHERICAL=,COUNT=,/SILENT] INPUTS: x1in,y1in - First set of x and y coordinates. The program marches through this list element by element, looking in list 2 for the closest match. So, the program will run faster if this is the shorter of the two lists. Unless you use the option or magnitude keyword, there is nothing to guarantee unique matches. x2in,y2in - Second set of x and y coordinates. This list is searched in its entirety every time one element of list 1 is processed. dcr - Critical radius outside which correlations are rejected; but see 'option' below. OPTIONAL KEYWORD INPUT: option - Changes behavior of program and description of output lists slightly, as follows: OPTION=0 or left out Same as older versions of SRCOR. The closest match from list2 is found for each element of list 1, but if the distance is greater than DCR, the match is thrown out. Thus the index of that element within list 1 will not appear in the IND1 output array. OPTION=1 Forces the output mapping to be one-to-one. OPTION=0 results, in general, in a many-to-one mapping from list 1 to list 2. Under OPTION=1, a further processing step is performed to keep only the minimum-distance match, whenever an entry from list 1 appears more than once in the initial mapping. OPTION=2 Same as OPTION=1, except the critical distance parameter DCR is ignored. I.e., the closest object is retrieved from list 2 for each object in list 1 WITHOUT a critical-radius criterion, then the clean-up of duplicates is done as under OPTION=1. magnitude An array of stellar magnitudes corresponding to x1in and y1in. If this is supplied, then the brightest star from list 1 within the selected distance of the star in list 2 is taken. The option keyword is ignored in this case. spherical If SPHERICAL=1, it is assumed that the input arrays are in celestial coordinates (RA and Dec), with x1in and x2in in decimal hours and y1in and y2in in decimal degrees. If SPHERICAL=2 then it is assumed that the input arrays are in longitude and latitude with x1in,x2in,y1in,y2in in decimal degrees. In both cases, the critial radius dcr is in *arcseconds*. Calculations of spherical distances are made with the gcirc program. OUTPUTS: ind1 - index of matched stars in first list, set to -1 if no matches found ind2 - index of matched stars in second list OPTIONAL OUTPUT KEYWORD: Count - integer giving number of matches returned PROCEDURES USED: GCIRC, REMOVE REVISON HISTORY: Adapted from UIT procedure J.Wm.Parker, SwRI 29 July 1997 Improve speed for spherical searches, added /SILENT keyword W. Landsman Mar 2009 Avoid error when no matches found with /SPHERICAL O. Trottier June 2009 Added output Count keyword W.L June 2009 Adjust right ascension for cosine angle W.L. December 2009 Return as soon as no matches found W.L. December 2009 Use some V6.0 notation W.L. February 2011 Fix problem when /Spherical and Option =2 set, and sources separated by more han 180 degrees. W.L. March 2011(See astrolib/pro/srcor.pro)
STARAST
[Previous Routine] [Next Routine] [List of Routines]NAME: STARAST PURPOSE: Compute astrometric solution using positions of 2 or 3 reference stars EXPLANATION: Computes an exact astrometric solution using the positions and coordinates from 2 or 3 reference stars and assuming a tangent (gnomonic) projection. If 2 stars are used, then the X and Y plate scales are assumed to be identical, and the axis are assumed to be orthogonal. Use of three stars will allow a unique determination of each element of the CD matrix. CALLING SEQUENCE: starast, ra, dec, x, y, cd, [/Righthanded, HDR = h, PROJECTION=] INPUTS: RA - 2 or 3 element vector containing the Right Ascension in DEGREES DEC- 2 or 3 element vector containing the Declination in DEGREES X - 2 or 3 element vector giving the X position of reference stars Y - 2 or 3 element vector giving the Y position of reference stars OUTPUTS: CD - CD (Coordinate Description) matrix (DEGREES/PIXEL) determined from stellar positions and coordinates. OPTIONAL INPUT KEYWORD: /RightHanded - If only 2 stars are supplied, then there is an ambiguity in the orientation of the coordinate system. By default, STARAST assumes the astronomical standard left-handed system (R.A. increase to the left). If /Right is set then a righthanded coordinate is assumed. This keyword has no effect if 3 star positions are supplied. PROJECTION - Either a 3 letter scalar string giving the projection type (e.g. 'TAN' or 'SIN') or an integer 1 - 25 specifying the projection as given in the WCSSPH2XY procedure. If not specified then a tangent projection is computed. OPTIONAL INPUT-OUTPUT KEYWORD: HDR - If a FITS header string array is supplied, then an astrometry solution is added to the header using the CD matrix and star 0 as the reference pixel (see example). Equinox 2000 is assumed. EXAMPLE: To use STARAST to add astrometry to a FITS header H; IDL> starast,ra,dec,x,y,cd ;Determine CD matrix IDL> crval = [ra[0],dec[0]] ;Use Star 0 as reference star IDL> crpix = [x[0],y[0]] +1 ;FITS is offset 1 pixel from IDL IDL> putast,H,cd,crpix,crval ;Add parameters to header This is equivalent to the following command: IDL> STARAST,ra,dec,x,y,hdr=h METHOD: The CD parameters are determined by solving the linear set of equations relating position to local coordinates (l,m) For highest accuracy the first star position should be the one closest to the reference pixel. REVISION HISTORY: Written, W. Landsman January 1988 Converted to IDL V5.0 W. Landsman September 1997 Added /RightHanded and HDR keywords W. Landsman September 2000 Write CTYPE values into header W. Landsman/A. Surkov December 2002 CD matrix was mistakenly transpose in 3 star solution Added projection keyword W. Landsman September 2003 Test for singular matrix W. Landsman August 2011(See astrolib/pro/starast.pro)
STORE_ARRAY
[Previous Routine] [Next Routine] [List of Routines]NAME: STORE_ARRAY PURPOSE: Insert array INSERT into the array DESTINATION EXPLANATION: The dimensions of the DESTINATION array are adjusted to accommodate the inserted array. CATEGOBY: Utility CALLING SEQUENCE: STORE_ARRAY, DESTINATION, INSERT, INDEX INPUT: DESTINATION = Array to be expanded. INSERT = Array to insert into DESTINATION. INDEX = Index of the final dimension of DESTINATION to insert INSERT into. OUTPUTS: DESTINATION = Expanded output array. If both input arrays have the same number of dimensions, then the DESTINATION will be replaced with INSERT. RESTRICTIONS: DESTINATION and INSERT have to be either both of type string or both of numerical types. INSERT must not have more dimensions than DESTINATION. MODIFICATION HISTOBY: William Thompson, Feb. 1992, from BOOST_ARRAY by D. Zarro and P. Hick. Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/store_array.pro)
STRCOMPRESS2
[Previous Routine] [Next Routine] [List of Routines]NAME: STRCOMPRESS2 PURPOSE: Remove blanks around specified characters in a string CALLING SEQUENCE newstring = strcompress2( st, chars) INPUTS: st - any scalar string chars - scalar or vector string specifing which characters around which blanks should be removed. For example, if chars=['=','-','+'] then spaces around the three characters "=', '-', and '+' will be removed. OUTPUTS: newstring - input string with spaces removed around the specified characters. EXAMPLE: The Vizier constraint string (see queryvizier.pro) does not allow blanks around the operators '=','<', or '>'. But we do not want to remove blanks around names (e.g. 'NGC 5342'): IDL> st = 'name = NGC 5342, v< 23' IDL> print,strcompress2(st, ['=','<','>']) name=NGC 5342, v<23 MODIFICATION HISTORY: Written by W.Landsman July 2008(See astrolib/pro/strcompress2.pro)
STRN
[Previous Routine] [Next Routine] [List of Routines]NAME: STRN PURPOSE: Convert a number to a string and remove padded blanks. EXPLANATION: The main and original purpose of this procedure is to convert a number to an unpadded string (i.e. with no blanks around it.) However, it has been expanded to be a multi-purpose formatting tool. You may specify a length for the output string; the returned string is either set to that length or padded to be that length. You may specify characters to be used in padding and which side to be padded. Finally, you may also specify a format for the number. NOTE that the input "number" need not be a number; it may be a string, or anything. It is converted to string. CALLING SEQEUNCE: tmp = STRN( number, [ LENGTH=, PADTYPE=, PADCHAR=, FORMAT = ] ) INPUT: NUMBER This is the input variable to be operated on. Traditionally, it was a number, but it may be any scalar type. OPTIONAL INPUT: LENGTH This KEYWORD specifies the length of the returned string. If the output would have been longer, it is truncated. If the output would have been shorter, it is padded to the right length. PADTYPE This KEYWORD specifies the type of padding to be used, if any. 0=Padded at End, 1=Padded at front, 2=Centered (pad front/end) IF not specified, PADTYPE=1 PADCHAR This KEYWORD specifies the character to be used when padding. The default is a space (' '). FORMAT This keyword allows the FORTRAN type formatting of the input number (e.g. '(f6.2)') OUTPUT: tmp The formatted string USEFUL EXAMPLES: print,'Used ',strn(stars),' stars.' ==> 'Used 22 stars.' print,'Attempted ',strn(ret,leng=6,padt=1,padch='0'),' retries.' ==> 'Attempted 000043 retries.' print,strn('M81 Star List',length=80,padtype=2) ==> an 80 character line with 'M81 Star List' centered. print,'Error: ',strn(err,format='(f15.2)') ==> 'Error: 3.24' or ==> 'Error: 323535.22' HISTORY: 03-JUL-90 Version 1 written by Eric W. Deutsch 10-JUL-90 Trimming and padding options added (E. Deutsch) 29-JUL-91 Changed to keywords and header spiffed up (E. Deutsch) Ma7 92 Work correctly for byte values (W. Landsman) 19-NOV-92 Added Patch to work around IDL 2.4.0 bug which caused an error when STRN('(123)') was encountered. (E. Deutsch) Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/strn.pro)
STRNUMBER()
[Previous Routine] [Next Routine] [List of Routines]NAME: STRNUMBER() PURPOSE: Function to determine if a string is a valid numeric value. EXPLANATION: A string is considered a valid numeric value if IDL can convert it to a numeric variable without error. CALLING SEQUENCE: result = strnumber( st, [val, /HEX] ) INPUTS: st - any IDL scalar string OUTPUTS: 1 is returned as the function value if the string st has a valid numeric value, otherwise, 0 is returned. OPTIONAL OUTPUT: val - (optional) value of the string. double precision unless /L64 is set OPTIONAL INPUT KEYWORD: /HEX - If present and nonzero, the string is treated as a hexadecimal longword integer. /L64 - If present and nonzero, the val output variable is returned as a 64 bit integer. This to ensure that precision is not lost when returning a large 64 bit integer as double precision. This keyword has no effect on the function result. /NAN - if set, then the value of an empty string is returned as NaN, by default the returned value is 0.0d. In either case, an empty string is considered a valid numeric value. EXAMPLES: IDL> res = strnumber('0.2d', val) returns res=1 (a valid number), and val = 0.2000d NOTES: (1) STRNUMBER was modified in August 2006 so that an empty string is considered a valid number. Earlier versions of strnumber.pro did not do this because in very early (pre-V4.0) versions of IDL this could corrupt the IDL session. (2) STRNUMBER will return a string such as '23.45uyrg' as a valid number (=23.45) since this is how IDL performs the type conversion. If you want a stricter definition of valid number then use the VALID_NUM() function. HISTORY: version 1 By D. Lindler Aug. 1987 test for empty string, W. Landsman February, 1993 Hex keyword added. MRG, RITSS, 15 March 2000. An empty string is a valid number W. Landsman August 2006 Added /NAN keyword W. Landsman August 2006 Added /L64 keyword W. Landsman Feb 2010(See astrolib/pro/strnumber.pro)
STR_INDEX()
[Previous Routine] [Next Routine] [List of Routines]NAME: STR_INDEX() PURPOSE: Get indices of a substring (SUBSTR) in string. EXPLANATION: The IDL intrinsic function STRPOS returns only the index of the first occurrence of a substring. This routine calls itself recursively to get indices of the remaining occurrences. CALLING SEQUENCE: result= STR_INDEX(str, substr [, offset]) INPUTS: STR -- The string in which the substring is searched for SUBSTR -- The substring to be searched for within STR OPTIONAL INPUTS: OFFSET -- The character position at which the search is begun. If omitted or being negative, the search begins at the first character (character position 0). OUTPUTS: RESULT -- Integer scalar or vector containing the indices of SUBSTR within STR. If no substring is found, it is -1. CALLS: DELVARX COMMON BLOCKS: STR_INDEX -- internal common block. The variable save in the block is deleted upon final exit of this routine. CATEGORY: Utility, string MODIFICATION HISTORY: Written January 3, 1995, Liyun Wang, GSFC/ARC Converted to IDL V5.0 W. Landsman September 1997 Use size(/TNAME) instead of DATATYPE() W. Landsman October 2001(See astrolib/pro/str_index.pro)
ST_DISKREAD
[Previous Routine] [Next Routine] [List of Routines]NAME: ST_DISKREAD PURPOSE: Read HST FITS formatted disk files and reconstruct GEIS (STSDAS) files. CALLING SEQUENCE: ST_DISKREAD, infiles INPUT PARAMETER: infiles - (scalar string) input disk files to be converted into GEIS files. Wildcards are allowed. FILES CREATED: GEIS files: The GEIS file is reconstructed from each input Fits file. The output filename is composed from the rootname of the observation and the appropriate GEIS file extension (i.e. d0h/d, c0h/d, etc.). Tables: If input file is a fits table, the output is an SDAS table. EXAMPLES: a) Reconstruct the GEIS file for disk FITS file z29i020ct*.fits. st_diskread,'z29i020ct*.fits' PROCEDURES CALLED: ST_DISK_DATA, ST_DISK_TABLE, ST_DISK_GEIS FTSIZE,SXPAR(),TAB_CREATE, TAB_WRITE HISTORY: 10/17/94 JKF/ACC - taken from ST_TAPEREAD. 11/02/94 JKF/ACC - added /block on open statement to handle files with 512 bytes/record. 12/6/95 JKF/ACC - include new jitter files...replaces st_read_jitter.pro. 03/5/96 W. Landsman, change FORRD to READU, remove Version 1 type codes, add message facility 05/20/00 W. Landsman, remove obsolete !ERR calls, new calling sequence to FTINFO 09/2006 W. Landsman, remove obsolete keywords to OPEN **************************************************************************** Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/st_diskread.pro)
ST_DISK_DATA
[Previous Routine] [Next Routine] [List of Routines]NAME: ST_DISK_DATA PURPOSE: Routine to read next header and data array from an HST FITS disk file. This is a subroutine of ST_DISKREAD and not intended for stand alone use. CALLING SEQUENCE: st_disk_data,unit,h,data,name,gcount,dimen,opsize,nbytes,itype INPUTS: unit - logical unit number. OUTPUTS: h - FITS header data - data array name - file name gcount - number of groups dimen - data dimensions opsize - parameter blocks size nbytes - bytes per data group itype - idl data type Notes: This is not a standalone program. Use ST_DISKREAD. PROCEDURES CALLED: GETTOK(), SXPAR() HISTORY: 10/17/94 JKF/ACC - taken from ST_TAPE_DATA. ***************************************************************************(See astrolib/pro/st_diskread.pro)
ST_DISK_GEIS
[Previous Routine] [Next Routine] [List of Routines]NAME: ST_DISK_GEIS PURPOSE: Routine to construct GEIS files from ST FITS disk files. CALLING SEQUENCE: ST_DISK_GEIS, h, data, htab, tab, table_available, name, gcount, dimen,opsize, nbytes_g,itype INPUT PARAMETERS: h - header for data data - data array htab - header for the table tab - fits table table_available - logical variable (1 if table was found) name - data set name gcount - number of groups dimen - data dimensions opsize - original parameter block size nbytes_g - number of bytes per group itype - idl integer data type value for the output data groups SIDE EFFECTS: GEIS file updated with group parameters in unit 1 (already open) and header file created NOTES: This is not a standalone program. Use st_diskread. During the creation of the header, this routine performs the following steps: 1) create a basic fits header (7 keywords) 2) adjust basic fits header for the number of axis present (i.e. >1) 3) adjust basic fits header for parameter keywords (i.e. ptype,etc) 4) from this point, sequentially copies keywords until it hits one of the following keywords 'INSTRUME','INSTRUID', or 'CONFG'. 5) append 'END' statement PROCEDURES CALLED: FTSIZE, SXADDPAR, SXHWRITE HISTORY: 10/17/94 JKF/ACC - taken from ST_DISK_GEIS ****************************************************************************(See astrolib/pro/st_diskread.pro)
ST_DISK_TABLE
[Previous Routine] [Next Routine] [List of Routines]NAME: ST_DISK_TABLE PURPOSE: Routine to read FITS table from an ST fits on disk. This is a subroutine of st_diskread and not intended for stand alone use. CALLING SEQUENCE: st_disk_table,unit,h,data INPUTS PARAMETER: unit - disk unit number OUTPUTS: h - FITS header data - table array NOTES: This is not a standalone program. Use ST_DISKREAD. HISTORY: 10/17/94 JKF/ACC - taken from ST_TAPE_TABLE. 12/7/95 JKF/ACC - handle tables for jitter data. ****************************************************************************(See astrolib/pro/st_diskread.pro)
SUBSTAR
[Previous Routine] [Next Routine] [List of Routines]NAME: SUBSTAR PURPOSE: Subtract a scaled point spread function at specified star position(s). EXPLANATION: Part of the IDL-DAOPHOT photometry sequence CALLING SEQUENCE: SUBSTAR, image, x, y, mag, [ id, psfname, /VERBOSE] INPUT-OUTPUT: IMAGE - On input, IMAGE is the original image array. A scaled PSF will be subtracted from IMAGE at specified star positions. Make a copy of IMAGE before calling SUBSTAR, if you want to keep a copy of the unsubtracted image array INPUTS: X - REAL Vector of X positions found by NSTAR (or FIND) Y - REAL Vector of Y positions found by NSTAR (or FIND) MAG - REAL Vector of stellar magnitudes found by NSTAR (or APER) Used to scale the PSF to match intensity at star position. Stars with magnitude values of 0.0 are assumed missing and ignored in the subtraction. OPTIONAL INPUTS: ID - Index vector indicating which stars are to be subtracted. If omitted, (or set equal to -1), then stars will be subtracted at all positions specified by the X and Y vectors. PSFNAME - Name of the FITS file containing the PSF residuals, as generated by GETPSF. SUBSTAR will prompt for this parameter if not supplied. OPTIONAL INPUT KEYWORD: VERBOSE - If this keyword is set and nonzero, then SUBSTAR will display the star that it is currently processing COMMON BLOCKS: The RINTER common block is used (see RINTER.PRO) to save time in the PSF calculations PROCEDURES CALLED: DAO_VALUE(), READFITS(), REMOVE, SXOPEN, SXPAR(), SXREAD() REVISION HISTORY: Written, W. Landsman August, 1988 Added VERBOSE keyword January, 1992 Fix star subtraction near edges, W. Landsman May, 1996 Assume the PSF file is in FITS format W. Landsman July, 1997 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/substar.pro)
SUNPOS
[Previous Routine] [Next Routine] [List of Routines]NAME: SUNPOS PURPOSE: To compute the RA and Dec of the Sun at a given date. CALLING SEQUENCE: SUNPOS, jd, ra, dec, [elong, obliquity, /RADIAN ] INPUTS: jd - The Julian date of the day (and time), scalar or vector usually double precision OUTPUTS: ra - The right ascension of the sun at that date in DEGREES double precision, same number of elements as jd dec - The declination of the sun at that date in DEGREES OPTIONAL OUTPUTS: elong - Ecliptic longitude of the sun at that date in DEGREES. obliquity - the obliquity of the ecliptic, in DEGREES OPTIONAL INPUT KEYWORD: /RADIAN - If this keyword is set and non-zero, then all output variables are given in Radians rather than Degrees NOTES: Patrick Wallace (Rutherford Appleton Laboratory, UK) has tested the accuracy of a C adaptation of the sunpos.pro code and found the following results. From 1900-2100 SUNPOS gave 7.3 arcsec maximum error, 2.6 arcsec RMS. Over the shorter interval 1950-2050 the figures were 6.4 arcsec max, 2.2 arcsec RMS. The returned RA and Dec are in the given date's equinox. Procedure was extensively revised in May 1996, and the new calling sequence is incompatible with the old one. METHOD: Uses a truncated version of Newcomb's Sun. Adapted from the IDL routine SUN_POS by CD Pike, which was adapted from a FORTRAN routine by B. Emerson (RGO). EXAMPLE: (1) Find the apparent RA and Dec of the Sun on May 1, 1982 IDL> jdcnv, 1982, 5, 1,0 ,jd ;Find Julian date jd = 2445090.5 IDL> sunpos, jd, ra, dec IDL> print,adstring(ra,dec,2) 02 31 32.61 +14 54 34.9 The Astronomical Almanac gives 02 31 32.58 +14 54 34.9 so the error in SUNPOS for this case is < 0.5". (2) Find the apparent RA and Dec of the Sun for every day in 1997 IDL> jdcnv, 1997,1,1,0, jd ;Julian date on Jan 1, 1997 IDL> sunpos, jd+ dindgen(365), ra, dec ;RA and Dec for each day MODIFICATION HISTORY: Written by Michael R. Greason, STX, 28 October 1988. Accept vector arguments, W. Landsman April,1989 Eliminated negative right ascensions. MRG, Hughes STX, 6 May 1992. Rewritten using the 1993 Almanac. Keywords added. MRG, HSTX, 10 February 1994. Major rewrite, improved accuracy, always return values in degrees W. Landsman May, 1996 Added /RADIAN keyword, W. Landsman August, 1997 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/sunpos.pro)
SUNSYMBOL
[Previous Routine] [Next Routine] [List of Routines]NAME: SUNSYMBOL PURPOSE: Return the Sun symbol as a subscripted postscript character string EXPLANATION: Returns the Sun symbol (circle with a dot in the middle) as a (subscripted) postscript character string. Needed because although the Sun symbol is available using the vector fonts as the string '!9n', it is not in the standard postscript set. CALLING SEQUENCE: result = SUNSYMBOL([FONT= ]) INPUTS: None OPTIONAL INPUT KEYWORDS: font = scalar font graphics keyword (-1,0 or 1) for text. Note that this keyword is useful for printing text with XYOUTS but *not* e.g. the XTIT keyword to PLOT where the font call to PLOT takes precedence. OUTPUTS: result - a scalar string representing the Sun symbol. A different string is output depending (1) the device is postscript and hardware fonts are used (!P.FONT=0), (2) vector fonts are used, or (3) hardware fonts are used on a non-postscript device. For case (3), SUNSYMBOL simply outputs the 3 character string 'Sun' EXAMPLE: To make the X-axis of a plot read M/M_Sun IDL> plot,indgen(10),xtit = 'M / M' + sunsymbol() RESTRICTIONS: (1) The postscript output does not have the dot perfectly centered in the circle. For a better symbol, consider postprocessing with psfrag (see http://www.astrobetter.com/idl-psfrag/ ). (2) SUNSYMBOL() includes subscript output positioning commands in the output string. (3) True type fonts (!p.font = 1) are not supported. If you want to make a Sun symbol with true type fonts, see the discussion of installing the Marvosym font at http://tinyurl.com/mst5q REVISION HISTORY: Written, W. Landsman, HSTX April, 1997 Converted to IDL V5.0 W. Landsman September 1997 Allow font keyword to be passed. T. Robishaw Apr. 2006(See astrolib/pro/sunsymbol.pro)
SXADDHIST
[Previous Routine] [Next Routine] [List of Routines]NAME: SXADDHIST PURPOSE: Procedure to add HISTORY (or COMMENT) line(s) to a FITS header EXPLANATION: The advantage of using SXADDHIST instead of SXADDPAR is that with SXADDHIST many HISTORY or COMMENT records can be added in a single call. CALLING SEQUENCE sxaddhist, history, header, [ /PDU, /COMMENT ] INPUTS: history - string or string array containing history or comment line(s) to add to the FITS header INPUT/OUTPUT header - FITS header (string array). Upon output, it will contain the specified HISTORY records added to the end OPTIONAL KEYWORD INPUTS: /BLANK - If specified then blank (' ') keywords will be written rather than 'HISTORY ' keywords. /COMMENT - If specified, then 'COMMENT ' keyword will be written rather than 'HISTORY ' keywords. Note that according to the FITS definition, any number of 'COMMENT' and 'HISTORY' or blank keywords may appear in a header, whereas all other keywords may appear only once. LOCATION=key - If present, the history will be added before this keyword. Otherwise put it at the end. /PDU - if specified, the history will be added to the primary data unit header, (before the line beginning BEGIN EXTENSION...) Otherwise, it will be added to the end of the header. This has meaning only for extension headers using the STScI inheritance convention. OUTPUTS: header - updated FITS header EXAMPLES: sxaddhist, 'I DID THIS', header ;Add one history record hist = strarr(3) hist[0] = 'history line number 1' hist[1[ = 'the next history line' hist[2] = 'the last history line' sxaddhist, hist, header ;Add three history records SIDE EFFECTS: Header array is truncated to the final END statement LOCATION overrides PDU. HISTORY: D. Lindler Feb. 87 April 90 Converted to new idl D. Lindler Put only a single space after HISTORY W. Landsman November 1992 Aug. 95 Added PDU keyword parameters LOCATION added. M. Greason, 28 September 2004. Missing minus sign (1 -> -1) in testing for WHERE output when looking for location to insert a comment M. Haffner Oct 2012(See astrolib/pro/sxaddhist.pro)
SXADDPAR
[Previous Routine] [Next Routine] [List of Routines]NAME: SXADDPAR PURPOSE: Add or modify a parameter in a FITS header array. CALLING SEQUENCE: SXADDPAR, Header, Name, Value, [ Comment, Location, /SaveComment, BEFORE =, AFTER = , FORMAT= , /PDU] INPUTS: Header = String array containing FITS or STSDAS header. The length of each element must be 80 characters. If not defined, then SXADDPAR will create an empty FITS header array. Name = Name of parameter. If Name is already in the header the value and possibly comment fields are modified. Otherwise a new record is added to the header. If name is equal to 'COMMENT' or 'HISTORY' or a blank string then the value will be added to the record without replacement. For these cases, the comment parameter is ignored. Value = Value for parameter. The value expression must be of the correct type, e.g. integer, floating or string. String values of 'T' or 'F' are considered logical values. OPTIONAL INPUT PARAMETERS: Comment = String field. The '/' is added by this routine. Added starting in position 31. If not supplied, or set equal to '', or /SAVECOMMENT is set, then the previous comment field is retained (when found) Location = Keyword string name. The parameter will be placed before the location of this keyword. This parameter is identical to the BEFORE keyword and is kept only for consistency with earlier versions of SXADDPAR. OPTIONAL INPUT KEYWORD PARAMETERS: BEFORE = Keyword string name. The parameter will be placed before the location of this keyword. For example, if BEFORE='HISTORY' then the parameter will be placed before the first history location. This applies only when adding a new keyword; keywords already in the header are kept in the same position. AFTER = Same as BEFORE, but the parameter will be placed after the location of this keyword. This keyword takes precedence over BEFORE. FORMAT = Specifies FORTRAN-like format for parameter, e.g. "F7.3". A scalar string should be used. For complex numbers the format should be defined so that it can be applied separately to the real and imaginary parts. If not supplied then the default is 'G19.12' for double precision, and 'G14.7' for floating point. /PDU = specifies keyword is to be added to the primary data unit header. If it already exists, it's current value is updated in the current position and it is not moved. /SAVECOMMENT = if set, then any existing comment is retained, i.e. the COMMENT parameter only has effect if the keyword did not previously exist in the header. OUTPUTS: Header = updated FITS header array. EXAMPLE: Add a keyword 'TELESCOP' with the value 'KPNO-4m' and comment 'Name of Telescope' to an existing FITS header h. IDL> sxaddpar, h, 'TELESCOPE','KPNO-4m','Name of Telescope' NOTES: The functions SXADDPAR() and FXADDPAR() are nearly identical, with the major difference being that FXADDPAR forces required FITS keywords BITPIX, NAXISi, EXTEND, PCOUNT, GCOUNT to appear in the required order in the header, and FXADDPAR supports the OGIP LongString convention. There is no particular reason for having two nearly identical procedures, but both are too widely used to drop either one. All HISTORY records are inserted in order at the end of the header. All COMMENT records are also inserted in order at the end of the header header, but before the HISTORY records. The BEFORE and AFTER keywords can override this. All records with no keyword (blank) are inserted in order at the end of the header, but before the COMMENT and HISTORY records. The BEFORE and AFTER keywords can override this. RESTRICTIONS: Warning -- Parameters and names are not checked against valid FITS parameter names, values and types. MODIFICATION HISTORY: DMS, RSI, July, 1983. D. Lindler Oct. 86 Added longer string value capability Converted to NEWIDL D. Lindler April 90 Added Format keyword, J. Isensee, July, 1990 Added keywords BEFORE and AFTER. K. Venkatakrishna, May '92 Pad string values to at least 8 characters W. Landsman April 94 Aug 95: added /PDU option and changed routine to update last occurence of an existing keyword (the one SXPAR reads) instead of the first occurence. Comment for string data can start after column 32 W. Landsman June 97 Make sure closing quote supplied with string value W. Landsman June 98 Converted to IDL V5.0 W. Landsman June 98 Increase precision of default formatting of double precision floating point values. C. Gehman, JPL September 1998 Mar 2000, D. Lindler, Modified to use capital E instead of lower case e for exponential formats. Apr 2000, Make user-supplied format upper-case W. Landsman Oct 2001, Treat COMMENT or blank string like HISTORY keyword W. Landsman Jan 2002, Allow BEFORE, AFTER to apply to COMMENT keywords W. Landsman June 2003, Added SAVECOMMENT keyword W. Landsman Jan 2004, If END is missing, then add it at the end W. Landsman May 2005 Fix SAVECOMMENT error with non-string values W. Landsman Oct 2005 Jan 2004 change made SXADDPAR fail for empty strings W.L. May 2011 Fix problem with slashes in string values W.L.(See astrolib/pro/sxaddpar.pro)
SXDELPAR
[Previous Routine] [Next Routine] [List of Routines]NAME: SXDELPAR PURPOSE: Procedure to delete a keyword parameter(s) from a FITS header CALLING SEQUENCE: sxdelpar, h, parname INPUTS: h - FITS or STSDAS header, string array parname - string or string array of keyword name(s) to delete OUTPUTS: h - updated FITS header, If all lines are deleted from the header, then h is returned with a value of 0 EXAMPLE: Delete the astrometry keywords CDn_n from a FITS header, h IDL> sxdelpar, h, ['CD1_1','CD1_2','CD2_1','CD2_2'] NOTES: (1) No message is returned if the keyword to be deleted is not found (2) All appearances of a keyword in the header will be deleted HISTORY: version 1 D. Lindler Feb. 1987 Test for case where all keywords are deleted W. Landsman Aug 1995 Allow for headers with more than 32767 lines W. Landsman Jan. 2003 Use ARRAY_EQUAL, cleaner syntax W. L. July 2009(See astrolib/pro/sxdelpar.pro)
SXGINFO
[Previous Routine] [Next Routine] [List of Routines]NAME: SXGINFO PURPOSE: Return information on all group parameters in an STSDAS header. EXPLANATION: Return datatype, starting byte, and number bytes for all group parameters in an STSDAS file. Obtaining these values greatly speed up execution time in subsequent calls to SXGPAR. CALLING SEQUENCE: sxginfo, h, par, type, sbyte, nbytes INPUTS: h - header returned by SXOPEN par - parameter block returned by SXREAD or multiple parameter blocks stored in array of dimension greater than one. OUTPUT: type - data type (if not supplied or null string, the header is searched for type,sbyte, and nbytes) sbyte - starting byte in parameter block for data nbytes - number of bytes in parameter block for data The number of elements in type,sbyte and nbytes equals the total number of group parameters. METHOD: The parameter type for each parameter is obtained from PDTYPEn keyword. If not found then DATATYPE keyword value is used. If that is not found then BITPIX is used. BITPIX=8, byte; BITPIX=16 integer*2; BITPIX=32 integer*4. NOTES: For an example of the use of SXGINFO, see CONV_STSDAS HISTORY: version 1 W. Landsman Apr. 93 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/sxginfo.pro)
SXGPAR
[Previous Routine] [Next Routine] [List of Routines]NAME: SXGPAR PURPOSE: Obtain group parameter value in SDAS/FITS file CALLING SEQUENCE: result = sxgpar( h, par, name, [ type, sbyte, nbytes] ) INPUTS: h - header returned by SXOPEN par - parameter block returned by SXREAD or multiple parameter blocks stored in array of dimension greater than one. name - parameter name (keyword PTYPEn) or integer parameter number. OPTIONAL INPUT/OUTPUT type - data type (if not supplied or null string, the header is searched for type,sbyte, and nbytes) sbyte - starting byte in parameter block for data nbytes - number of bytes in parameter block for data OUTPUT: parameter value or value(s) returned as function value SIDE EFFECTS: If an error occured then !err is set to -1 OPERATIONAL NOTES: Supplying type, sbyte and nbytes greatly decreases execution time. The best way to get the types is on the first call pass undefined variables for the three parameters or set type = ''. The routine will then return their values for use in subsequent calls. METHOD: The parameter type for parameter n is obtained from PDTYPEn keyword. If not found then DATATYPE keyword value is used. If that is not found then BITPIX is used. BITPIX=8, byte; BITPIX=16 integer*2; BITPIX=32 integer*4. HISTORY: version 1 D. Lindler Oct. 86 version 2 D. Lindler Jan. 90 added ability to process multiple parameter blocks in single call version 3 D. Lindler (converted to New vaxidl) Apr 14 1991 JKF/ACC - fixed make_array datatypes(float/double) Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/sxgpar.pro)
SXGREAD
[Previous Routine] [Next Routine] [List of Routines]NAME: SXGREAD PURPOSE: Read group parameters from a Space Telescope STSDAS image file CALLING SEQUENCE: grouppar = sxgread( unit, group ) INPUTS: UNIT = Supply same unit as used in SXOPEN. GROUP = group number to read. if omitted, read first group. The first group is number 0. OUTPUTS: GROUPPAR = parameter values from fits group parameter block. It is a byte array which may contain multiple data types. The function SXGPAR can be used to retrieve values from it. COMMON BLOCKS: Uses IDL Common STCOMMN to access parameters. SIDE EFFECTS: IO is performed. MODIFICATION HISTORY: WRITTEN, Don Lindler, July, 1 1987 MODIFIED, Don Neill, Jan 11, 1991 - derived from sxread.pro Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/sxgread.pro)
SXHCOPY
[Previous Routine] [Next Routine] [List of Routines]NAME: SXHCOPY PURPOSE: Copies selected portions of one header to another CALLING SEQUENCE: sxhcopy, h, keyword1, keyword2, hout INPUTS: h - input header keyword1 - first keyword to copy keyword2 - last keyword to copy INPUT/OUTPUT: hout - header to copy the information to. METHOD: the headers lines from keyword1 to keyword2 are copied to the end of the output header. No check is made to verify that a keyword value already exists in the output header. HISTORY: version 1 D. Lindler Sept. 1989 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/sxhcopy.pro)
SXHMAKE
[Previous Routine] [Next Routine] [List of Routines]NAME: SXHMAKE PURPOSE: Create a basic STSDAS header file from an IDL data array CALLING SEQUENCE: sxhmake, Data, Groups, Header INPUTS: Data = IDL data array of the same type, dimensions and size as are to be written to file. Groups = # of groups to be written. OUTPUTS: Header = String array containing ST header file. PROCEDURE: Call sxhmake to create a header file. Then call sxopen to open output image, followed by sxwrite to write the data. If you do not plan to change the header created by sxhmake before calling sxopen, you might consider using sxmake which does both steps. MODIFICATION HISTORY: Don Lindler Feb 1990 modified from SXMAKE by DMS, July, 1983. D. Lindler April 90 Converted to new VMS IDL M. Greason May 1990 Header creation bugs eliminated. W. Landsman Aug 1997 Use SYSTIME() instead of !STIME for V5.0 Converted to IDL V5.0 W. Landsman September 1997 Recognize unsigned datatype January 2000 W. Landsman(See astrolib/pro/sxhmake.pro)
SXHREAD
[Previous Routine] [Next Routine] [List of Routines]NAME: SXHREAD PURPOSE: Procedure to read a STSDAS header from disk. EXPLANATION: This version of SXHREAD can read two types of disk files (1) Unix stream files with a CR after every 80 bytes (2) Variable length record files (3) Fixed length (80 byte) record files CALLING SEQUENCE: sxhread, name, header INPUT: name - file name, scalar string. An extension of .hhh is appended if not already supplied. (Note STSDAS headers are required to have a 3 letter extension ending in 'h'.) gzip extensions .gz will be recognized as compressed. OUTPUT: header - STSDAS header, string array NOTES: SXHREAD does not do any checking to see if the file is a valid STSDAS header. It simply reads the file into a string array with 80 byte elements HISTORY: Version 1 D. Lindler July, 1987 Version 2 M. Greason, August 1990 Use READU for certain ST VAX GEIS files W. Landsman January, 1992 Read variable length Unix files E. Deutsch/W. Landsman November, 1994 Converted to IDL V5.0 W. Landsman September 1997 Updated by E. Artigau to handle gzipped fits August 2004 Remove VMS support, W. Lnadsman September 2006(See astrolib/pro/sxhread.pro)
SXHWRITE
[Previous Routine] [Next Routine] [List of Routines]NAME: SXHWRITE PURPOSE: Procedure to write an STSDAS or FITS header to disk as a *.hhh file. CALLING SEQUENCE: SXHWRITE,name,h INPUTS: name - file name. If an extension is supplied it must be 3 characters ending in "h". h - FITS header, string array SIDE EFFECTS: File with specified name is written. If qualifier not specified then .hhh is used SXHWRITE will modify the header in the following ways, if necessary (1) If not already present, an END statement is added as the last line. Lines after an existing END statment are deleted. (2) Spaces are appended to force each line to be 80 characters. (3) On Unix machines, a carriage return is appended at the end of each line. This is consistent with STSDAS and allows the file to be directly displayed on a stream device PROCEDURES USED: zparcheck, fdecomp HISTORY: version 1 D. Lindler June 1987 conversion cleaned up. M. Greason, June 1990 Add carriage return at the end of Unix files W. Landsman Oct 1991 Use SYSTIME() instead of !STIME for V5.0 compatibility Aug 1997 Assume since V55, remove VMS support(See astrolib/pro/sxhwrite.pro)
SXMAKE
[Previous Routine] [Next Routine] [List of Routines]NAME: SXMAKE PURPOSE: Create a basic ST header file from an IDL array prior to writing data. CALLING SEQUENCE: sxmake, Unit, File, Data, Par, Groups, Header, [ PSIZE = ] INPUTS: Unit = Logical unit number from 1 to 9. File = file name of data and header files to create. If no file name extension is supplied then the default is to use .hhh for the header file extension and .hhd for the data file extension If an extension is supplied, it should be of the form .xxh where xx are any alphanumeric characters. Data = IDL data array of the same type, dimensions and size as are to be written to file. Par = # of elements in each parameter block for each data record. If set equal to 0, then parameter blocks will not be written. The data type of the parameter blocks must be the same as the data array. To get around this restriction, use the PSIZE keyword. Groups = # of groups to write. If 0 then write in basic format without groups. OPTIONAL INPUT PARAMETERS: Header = String array containing ST header file. If this parameter is omitted, a basic header is constructed. If included, the basic parameters are added to the header using sxaddpar. The END keyword must terminate the parameters in Header. OPTIONAL KEYWORD INPUT PARAMETER: PSIZE - Integer scalar giving the number of bits in the parameter block. If the PSIZE keyword is given, then the Par input parameter is ignored. OPTIONAL OUTPUT PARAMETERS: Header = ST header array, an 80 by N character array. COMMON BLOCKS: Stcommn - as used in sxwrite, sxopen, etc. SIDE EFFECTS: The header file is created and written and then the data file is opened on the designated unit. RESTRICTIONS: Header files must be named .xxh and data files must be named .xxd, where xx are any alphanumeric characters. PROCEDURE: Call sxmake to create a header file. Then call sxwrite to output each group. PROCEDURES USED: GET_DATE, SXADDPAR, SXOPEN MODIFICATION HISTORY: DMS, July, 1983. converted to new VMS IDL April 90 Use SYSTIME() instead of !STIME W. Landsman Aug 1997 Converted to IDL V5.0 W. Landsman September 1997 Added optional PSIZE keyword August 1999 W. Landsman Recognize unsigned datatype January 2000 W. Landsman(See astrolib/pro/sxmake.pro)
SXOPEN
[Previous Routine] [Next Routine] [List of Routines]NAME: SXOPEN PURPOSE: Open a Space Telescope formatted (STSDAS) header file. EXPLANATION: Saves the parameters required subsequent SX routines in the common block Stcommn. Optionally save the header in the string array Header, and the history in the string array History. Open the data file associated with this header on the same unit. CALLING SEQUENCE: SXOPEN, Unit, Fname [, Header [,History] [,Access]] INPUTS: Unit = IDL unit used for IO. Must be from 1 to 9. Fname = File name of header file. Default extension is .hhh for header files and .hhd for data files. If an extension is supplied it must have the form .xxh where xx are any alphanumeric characters. The data file must have extension .xxd No version number is allowed. Most recent versions of the files are used. OPTIONAL INPUT PARAMETER: Access = 'R' to open for read, 'W' to open for write. OUTPUTS: Stcommn = Common block containing ST parameter blocks. (Long arrays.) OPTIONAL OUTPUT PARAMETERS: Header = 80 char by N string array containing the names, values and comments from the FITS header. Use the function SXPAR to obtain individual parameter values. History = String array containing the value of the history parameter. COMMON BLOCKS: STCOMMN - Contains RESULT(20,10) where RESULT(i,LUN) = 0 - 121147 for consistency check, 1 - Unit for consistency, 2 - bitpix, 3 - naxis, 4 - groups (0 or 1), 5 - pcount, 6 - gcount, 7 - psize, 8 - data type as idl type code, 9 - bytes / record, 10 to 10+N-1 - dimension N, 17 = record length of file in bytes. 18 - # of groups written, 19 = gcount. SIDE EFFECTS: The data and header files are accessed. RESTRICTIONS: Works only for disc files. The data file must have must have the extension ".xxd" and the header file must have the extension ".xxh" where x is any alphanumeric character PROCEDURE: The header file is opened and each line is read. Important parameters are stored in the output parameter. If the last two parameters are specified the parameter names and values are stored. The common block STCOMMN is filled with the type of data, dimensions, etc. for use by SXREAD. If access is for write, each element of the header array, which must be supplied, is written to the header file. The common block is filled with relevant parameters for SXWRITE. A keyword of "END" ends the header. MODIFICATION HISTORY: Written, DMS, May, 1983. D. Lindler Feb. 1990 Modified to allow var. record length header files. D. Lindler April 1990 Conversion to new VMS IDL Added /BLOCK when opening new .hhd file Converted to IDL V5.0 W. Landsman September 1997 Recognize unsigned datatype for V5.1 or greater W. Landsman Jan 2000 Assume since V5.5 W. Landsman Sep 2006(See astrolib/pro/sxopen.pro)
SXPAR
[Previous Routine] [Next Routine] [List of Routines]NAME: SXPAR PURPOSE: Obtain the value of a parameter in a FITS header CALLING SEQUENCE: result = SXPAR( Hdr, Name, [ Abort, COUNT=, COMMENT =, /NoCONTINUE, /SILENT ]) INPUTS: Hdr = FITS header array, (e.g. as returned by READFITS) string array, each element should have a length of 80 characters Name = String name of the parameter to return. If Name is of the form 'keyword*' then an array is returned containing values of keywordN where N is a positive (non-zero) integer. The value of keywordN will be placed in RESULT[N-1]. The data type of RESULT will be the type of the first valid match of keywordN found. OPTIONAL INPUTS: ABORT - string specifying that SXPAR should do a RETALL if a parameter is not found. ABORT should contain a string to be printed if the keyword parameter is not found. If not supplied, SXPAR will return quietly with COUNT = 0 (and !ERR = -1) if a keyword is not found. OPTIONAL INPUT KEYWORDS: /NOCONTINUE = If set, then continuation lines will not be read, even if present in the header /SILENT - Set this keyword to suppress warning messages about duplicate keywords in the FITS header. OPTIONAL OUTPUT KEYWORDS: COUNT - Optional keyword to return a value equal to the number of parameters found by SXPAR, integer scalar COMMENT - Array of comments associated with the returned values OUTPUTS: Function value = value of parameter in header. If parameter is double precision, floating, long or string, the result is of that type. Apostrophes are stripped from strings. If the parameter is logical, 1b is returned for T, and 0b is returned for F. If Name was of form 'keyword*' then a vector of values are returned. SIDE EFFECTS: !ERR is set to -1 if parameter not found, 0 for a scalar value returned. If a vector is returned it is set to the number of keyword matches found. The use of !ERR is deprecated, and instead the COUNT keyword is preferred If a keyword (except HISTORY or COMMENT) occurs more than once in a header, a warning is given, and the *last* occurence is used. EXAMPLES: Given a FITS header, h, return the values of all the NAXISi values into a vector. Then place the history records into a string vector. IDL> naxisi = sxpar( h ,'NAXIS*') ; Extract NAXISi value IDL> history = sxpar( h, 'HISTORY' ) ; Extract HISTORY records PROCEDURE: The first 8 chacters of each element of Hdr are searched for a match to Name. The value from the last 20 characters is returned. An error occurs if there is no parameter with the given name. If a numeric value has no decimal point it is returned as type LONG. If it contains more than 8 numerals, or contains the characters 'D' or 'E', then it is returned as type DOUBLE. Otherwise it is returned as type FLOAT. Very large integer values, outside the range of valid LONG, are returned as DOUBLE. If the value is too long for one line, it may be continued on to the the next input card, using the OGIP CONTINUE convention. For more info, see http://fits.gsfc.nasa.gov/registry/continue_keyword.html Complex numbers are recognized as two numbers separated by one or more space characters. If a numeric value has no decimal point (or E or D) it is returned as type LONG. If it contains more than 8 numerals, or contains the character 'D', then it is returned as type DOUBLE. Otherwise it is returned as type FLOAT. If an integer is too large to be stored as type LONG, then it is returned as DOUBLE. NOTES: The functions SXPAR() and FXPAR() are nearly identical, although FXPAR() has slightly more sophisticated parsing, and additional keywords to specify positions in the header to search (for speed), and to force the output to a specified data type.. There is no particular reason for having two nearly identical procedures, but both are too widely used to drop either one. PROCEDURES CALLED: GETTOK(), VALID_NUM() MODIFICATION HISTORY: DMS, May, 1983, STPAR Written. D. Lindler Jan 90 added ABORT input parameter J. Isensee Jul,90 added COUNT keyword W. Thompson, Feb. 1992, added support for FITS complex values. W. Thompson, May 1992, corrected problem with HISTORY/COMMENT/blank keywords, and complex value error correction. W. Landsman, November 1994, fix case where NAME is an empty string W. Landsman, March 1995, Added COMMENT keyword, ability to read values longer than 20 character W. Landsman, July 1995, Removed /NOZERO from MAKE_ARRAY call T. Beck May 1998, Return logical as type BYTE W. Landsman May 1998, Make sure integer values are within range of LONG W. Landsman Feb 1998, Recognize CONTINUE convention W. Landsman Oct 1999, Recognize numbers such as 1E-10 as floating point W. Landsman Jan 2000, Only accept integer N values when name = keywordN W. Landsman Dec 2001, Optional /SILENT keyword to suppress warnings W. Landsman/D. Finkbeiner Mar 2002 Make sure extracted vectors of mixed data type are returned with the highest type. W.Landsman Aug 2008 Use vector form of VALID_NUM() W. Landsman Jul 2009 Eliminate internal recursive call W. Landsman Apr 2012 Require vector numbers be greater than 0(See astrolib/pro/sxpar.pro)
SXREAD
[Previous Routine] [Next Routine] [List of Routines]NAME: SXREAD PURPOSE: Read a Space Telescope STSDAS image file CALLING SEQUENCE: result = sxread( Unit, group , [par] ) INPUTS: UNIT = Unit number of file, must be from 1 to 9. Unit must have been opened with SXOPEN. GROUP = group number to read. if omitted, read first record. The first record is number 0. OUTPUTS: Result of function = array constructed from designated record. OPTIONAL OUTPUT: PAR = Variable name into which parameter values from STSDAS group parameter block are read. It is a byte array which may contain multiple data types. The function SXGPAR can be used to retrieve values from it. COMMON BLOCKS: Uses IDL Common STCOMMN to access parameters. NOTES: Use the function SXGREAD to read the group parameter blocks without having to read the group array. If the STSDAS file does not contain groups, then the optional output parameter PAR is returned undefined, but no error message is given. SIDE EFFECTS: IO is performed. MODIFICATION HISTORY: WRITTEN, Don Lindler, July, 1 1987 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/sxread.pro)
SXWRITE
[Previous Routine] [Next Routine] [List of Routines]NAME: SXWRITE PURPOSE: Write a group of data and parameters in ST format to a STSDAS data file. CALLING SEQUENCE: SXWRITE, Unit, Data,[ Par] INPUTS: Unit = unit number of file. The file must have been previously opened by SXOPEN. Data = Array of data to be written. The dimensions must agree with those supplied to SXOPEN and written into the FITS header. The type is converted if necessary. OPTIONAL INPUT PARAMETERS: Par = parameter block. The size of this array must agree with the Psize parameter in the FITS header. OUTPUTS: None. COMMON BLOCKS: STCOMMN - Contains RESULT(20,10) where RESULT(i,LUN) = 0 - 121147 for consistency check, 1 - Unit for consistency, 2 - bitpix, 3 - naxis, 4 - groups (0 or 1), 5 - pcount, 6 - gcount, 7 - psize, 8 - data type as idl type code, 9 - bytes / record, 10 to 10+N-1 - dimension N, 18 - # of groups written, 19 = gcount. SIDE EFFECTS: The data are written into the next group. RESTRICTIONS: SXOPEN must have been called to initialize the header and the common block. MODIFICATION HISTORY: DMS, July, 1983. D.Lindler July, 1986 - changed block size of file to 512 moved group parameters after the groups data. D.Lindler July, 1987 - modified to allow any size parameter block (in bytes). D. Lindler April, 1990 - converted to new VMS IDL Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/sxwrite.pro)
TABINV
[Previous Routine] [Next Routine] [List of Routines]NAME: TABINV PURPOSE: To find the effective index of a function value in an ordered vector. CALLING SEQUENCE: TABINV, XARR, X, IEFF, [/FAST] INPUTS: XARR - the vector array to be searched, must be monotonic increasing or decreasing X - the function value(s) whose effective index is sought (scalar or vector) OUTPUT: IEFF - the effective index or indices of X in XARR always floating point, same # of elements as X OPTIONAL KEYWORD INPUT: /FAST - If this keyword is set, then the input vector is not checked for monotonicity, in order to improve the program speed. RESTRICTIONS: TABINV will abort if XARR is not monotonic. (Equality of neighboring values in XARR is allowed but results may not be unique.) This requirement may mean that input vectors with padded zeroes could cause routine to abort. PROCEDURE: VALUE_LOCATE() is used to find the values XARR[I] and XARR[I+1] where XARR[I] < X < XARR[I+1]. IEFF is then computed using linear interpolation between I and I+1. IEFF = I + (X-XARR[I]) / (XARR[I+1]-XARR[I]) Let N = number of elements in XARR if x < XARR[0] then IEFF is set to 0 if x > XARR[N-1] then IEFF is set to N-1 EXAMPLE: Set all flux values of a spectrum (WAVE vs FLUX) to zero for wavelengths less than 1150 Angstroms. IDL> tabinv, wave, 1150.0, I IDL> flux[ 0:fix(I) ] = 0. FUNCTIONS CALLED: None REVISION HISTORY: Adapted from the IUE RDAF January, 1988 More elegant code W. Landsman August, 1989 Mod to work on 2 element decreasing vector August, 1992 Updated for V5.3 to use VALUE_LOCATE() W. Landsman January 2000 Work when both X and Xarr are integers W. Landsman August 2001 Use ARRAY_EQUAL, always internal double precision W.L. July 2009 Allow Double precision output, faster test for monotonicity. WL, January 2012(See astrolib/pro/tabinv.pro)
TAG_EXIST()
[Previous Routine] [Next Routine] [List of Routines]NAME: TAG_EXIST() PURPOSE: To test whether a tag name exists in a structure. EXPLANATION: Routine obtains a list of tagnames and tests whether the requested one exists or not. The search is recursive so if any tag names in the structure are themselves structures the search drops down to that level. (However, see the keyword TOP_LEVEL). CALLING SEQUENCE: status = TAG_EXIST(str, tag, [ INDEX =, /TOP_LEVEL, /QUIET ] ) INPUT PARAMETERS: str - structure variable to search tag - tag name to search for, scalar string OUTPUTS: Function returns 1b if tag name exists or 0b if it does not. OPTIONAL INPUT KEYWORD: /TOP_LEVEL = If set, then only the top level of the structure is searched. /QUIET - if set, then do not print messages if invalid parameters given /RECURSE - does nothing but kept for compatibility with the Solarsoft version for which recursion is not the default http://sohowww.nascom.nasa.gov/solarsoft/gen/idl/struct/tag_exist.pro OPTIONAL OUTPUT KEYWORD: INDEX = index of matching tag, scalar longward, -1 if tag name does not exist EXAMPLE: Determine if the tag 'THICK' is in the !P system variable IDL> print,tag_exist(!P,'THICK') PROCEDURE CALLS: None. MODIFICATION HISTORY: : Written, C D Pike, RAL, 18-May-94 Passed out index of matching tag, D Zarro, ARC/GSFC, 27-Jan-95 William Thompson, GSFC, 6 March 1996 Added keyword TOP_LEVEL Zarro, GSFC, 1 August 1996 Added call to help Use SIZE(/TNAME) rather than DATATYPE() W. Landsman October 2001 Added /RECURSE and /QUIET for compatibility with Solarsoft version W. Landsman March 2009 Slightly faster algorithm W. Landsman July 2009 July 2009 update was not setting Index keyword W. L Sep 2009. Use V6.0 notation W.L. Jan 2012 Not setting index again, sigh W.L./ K. Allers Jan 2012(See astrolib/pro/tag_exist.pro)
TBDELCOL
[Previous Routine] [Next Routine] [List of Routines]NAME: TBDELCOL PURPOSE: Delete a column of data from a FITS binary table CALLING SEQUENCE: TBDELCOL, h, tab, name INPUTS-OUPUTS h,tab - FITS binary table header and data array. H and TAB will be updated with the specified column deleted INPUTS: name - Either (1) a string giving the name of the column to delete or (2) a scalar giving the column number to delete EXAMPLE: Delete the column "FLUX" from FITS binary table test.fits IDL> tab = readfits('test.fits',h,/ext) ;Read table IDL> tbdelcol, h, tab, 'FLUX' ;Delete Flux column IDL> modfits,'test.fits',tab,h,/ext ;Write back table PROCEDURES USED: SXADDPAR, TBINFO, TBSIZE REVISION HISTORY: Written W. Landsman STX Co. August, 1988 Use new structure returned by TBINFO, August, 1997 Use SIZE(/TNAME) instead of DATATYPE() October 2001 Use /NOSCALE in call to TBINFO, update TDISP W. Landsman March 2007(See astrolib/pro/tbdelcol.pro)
TBDELROW
[Previous Routine] [Next Routine] [List of Routines]NAME: TBDELROW PURPOSE: Delete specified row or rows of data from a FITS binary table CALLING SEQUENCE: TBDELROW, h, tab, rows INPUTS-OUPUTS h,tab - FITS binary table header and data array. H and TAB will be updated on output with the specified row(s) deleted. rows - scalar or vector, specifying the row numbers to delete First row has index 0. If a vector it will be sorted and duplicates removed by TBDELROW EXAMPLE: Compress a table to include only non-negative flux values flux = TBGET(h,tab,'FLUX') ;Obtain original flux vector bad = where(flux lt 0) ;Find negative fluxes TBDELROW,h,tab,bad ;Delete rows with negative fluxes PROCEDURE: Specified rows are deleted from the data array, TAB. The NAXIS2 keyword in the header is updated. REVISION HISTORY: Written W. Landsman STX Co. August, 1988 Checked for IDL Version 2, J. Isensee, July, 1990 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/tbdelrow.pro)
TBGET
[Previous Routine] [Next Routine] [List of Routines]NAME: TBGET PURPOSE: Return value(s) from specified column in a FITS binary table CALLING SEQUENCE values = TBGET( h, tab, field, [ rows, nulls, /NOSCALE] ) or values = TBGET( tb_str, tab, field, [ rows, nulls, /NOSCALE] ) INPUTS: h - FITS binary table header, e.g. as returned by FITS_READ or tb_str - IDL structure extracted from FITS header by TBINFO. Use of the IDL structure will improve processing speed tab - FITS binary table array, e.g. as returned by FITS_READ field - field name or number, scalar OPTIONAL INPUTS: rows - scalar or vector giving row number(s) Row numbers start at 0. If not supplied or set to -1 then values for all rows are returned OPTIONAL KEYWORD INPUT: /NOSCALE - If this keyword is set and nonzero, then the TSCALn and TZEROn keywords will *not* be used to scale to physical values Default is to perform scaling CONTINUE - This keyword does nothing, it is kept for consistency with with earlier versions of TBGET(). OUTPUTS: the values for the row are returned as the function value. Null values are set to 0 or blanks for strings. OPTIONAL OUTPUT: nulls - null value flag of same length as the returned data. Only used for integer data types, B, I, and J It is set to 1 at null value positions and 0 elsewhere. If supplied then the optional input, rows, must also be supplied. EXAMPLE: Read the columns labeled 'WAVELENGTH' and 'FLUX' from the second extension of a FITS file 'spectra.fits' into IDL vectors w and f IDL> fits_read,'spectra.fits',tab,htab,exten=2 ;Read 2nd extension IDL> w = tbget(htab,tab,'wavelength') IDL> f = tbget(htab,tab,'flux') NOTES: (1) If the column is variable length ('P') format, then TBGET() will return the longword array of pointers into the heap area. TBGET() currently lacks the ability to actually extract the data from the heap area. (2) Use the higher-level procedure FTAB_EXT (which calls TBGET()) to extract vectors directly from the FITS file. (3) Use the procedure FITS_HELP to determine which extensions are binary tables, and FTAB_HELP or TBHELP to determine the columns of the table PROCEDURE CALLS: TBINFO, TBSIZE HISTORY: Written W. Landsman February, 1991 Work for string and complex W. Landsman April, 1993 Default scaling by TSCALn, TZEROn, Added /NOSCALE keyword, Fixed nulls output, return longword pointers for variable length binary tables, W. Landsman December 1996 Added a check for zero width column W. Landsman April, 1997 Add TEMPORARY() and REFORM() for speed W. Landsman May, 1997 Use new structure returned by TBINFO W. Landsman August 1997 Add IS_IEEE_BIG(), No subscripting when all rows requested W. Landsman March 2000 Use SIZE(/TNAME) instead of DATATYPE() W. Landsman October 2001 Bypass IEEE_TO_HOST call for improved speed W. Landsman November 2002 Cosmetic changes to SIZE() calls W. Landsman December 2002 Added unofficial support for 64bit integers W. Landsman February 2003 Support unsigned integers, new pointer types of TSCAL and TZERO returned by TBINFO W. Landsman April 2003 Add an i = i[0] for V6.0 compatibility W. Landsman August 2003 Use faster BYTEORDER byteswapping W. Landsman April 2006 Free pointers if FITS header supplied W. Landsman March 2007(See astrolib/pro/tbget.pro)
TBHELP
[Previous Routine] [Next Routine] [List of Routines]NAME: TBHELP PURPOSE: Routine to print a description of a FITS binary table header CALLING SEQUENCE: TBHELP, h, [TEXTOUT = ] INPUTS: h - FITS header for a binary table, string array OPTIONAL INPUT KEYWORD: TEXTOUT - scalar number (0-7) or string (file name) controling output device (see TEXTOPEN). Default is TEXTOUT=1, output to the user's terminal METHOD: FITS Binary Table keywords NAXIS*,EXTNAME,TFIELDS,TTYPE*,TFORM*,TUNIT*, are read from the header and displayed at the terminal A FITS header is recognized as bein for a binary table if the keyword XTENSION has the value 'BINTABLE' or 'A3DTABLE' NOTES: Certain fields may be truncated in the display SYSTEM VARIABLES: Uses the non-standard system variables !TEXTOUT and !TEXTUNIT. These are automatically defined by TBHELP if they have not been defined previously. PROCEDURES USED: REMCHAR, SXPAR(), TEXTCLOSE, TEXTOPEN, ZPARCHECK HISTORY: W. Landsman February, 1991 Parsing of a FITS binary header made more robust May, 1992 Added TEXTOUT keyword August 1997 Define !TEXTOUT if not already present W. Landsman November 2002 Slightly more compact display W. Landsman August 2005 Fix Aug 2005 error omitting TFORM display W. Landsman Sep 2005(See astrolib/pro/tbhelp.pro)
TBINFO
[Previous Routine] [Next Routine] [List of Routines]NAME: TBINFO PURPOSE: Return an informational IDL structure from a FITS binary table header. CALLING SEQUENCE: tbinfo, h, tb_str, [ERRMSG = ] INPUTS: h - FITS binary table header, e.g. as returned by READFITS() OUTPUTS: tb_str - IDL structure with extracted info from the FITS binary table header. Tags include .tbcol - starting column position in bytes, integer vector .width - width of the field in bytes, integer vector .idltype - idltype of field, byte vector 7 - string, 4- real*4, 3-integer*4, 5-real*8 .numval - repeat count, longword vector .tunit - string unit numbers, string vector .tnull - integer null value for the field, stored as a string vector so that an empty string indicates that TNULL is not present .tform - format for the field, string vector .ttype - field name, string vector .maxval- maximum number of elements in a variable length array, long vector .tscal - pointer array giving the scale factor for converting to physical values, default 1.0 .tzero - pointer array giving the additive offset for converting to physical values, default 0.0 .tdisp - recommended output display format All of the output vectors will have same number of elements, equal to the number of columns in the binary table. The .tscal and .tzero values are stored as pointers so as to preserve the individual data types (e.g. float or double) which may differ in different columns. For example, to obtain the value of TSCAL for the third column use *tab_str.tscal[2] OPTIONAL INPUT KEYWORD: /NOSCALE - if set, then the TSCAL* and TZERO* keywords are not extracted from the FITS header, and the .tscal and .tzero pointers do not appear in the output structure. OPTIONAL OUTPUT KEYWORD: ERRMSG = if present, then error messages are returned in this keyword rather than displayed using the MESSAGE facility PROCEDURES USED: SXPAR() NOTES: For variable length ('P' format) column, TBINFO returns values for reading the 2 element longward array of pointers (numval=2, idltype = 3, width=4) HISTORY: Major rewrite to return a structure W. Landsman August 1997 Added "unofficial" 64 bit integer "K" format W. Landsamn Feb. 2003 Store .tscal and .tzero tags as pointers, so as to preserve type information W. Landsman April 2003 Treat repeat count for string as specifying string length, not number of elements, added ERRMSG W. Landsman July 2006 Treat logical as character string 'T' or 'F' W. Landsman October 2006 Added NOSCALE keyword W. Landsman March 2007(See astrolib/pro/tbinfo.pro)
TBPRINT
[Previous Routine] [Next Routine] [List of Routines]NAME: TBPRINT PURPOSE: Procedure to print specified columns & rows of a FITS binary table CALLING SEQUENCE: TBPRINT, h, tab, columns, [ rows, TEXTOUT =, FMT=, NUM_HEADER= ] or TBPRINT,tb_str, tab, columns, [ rows, TEXTOUT =, FMT=, NUM_HEADER = ] INPUTS: h - FITS header for table, string array or tb_str - IDL structure extracted from FITS header by TBINFO, useful when TBPRINT is called many times with the same header tab - table array columns - string giving column names, or vector giving column numbers (beginning with 1). If string supplied then column names should be separated by comma's. If set to '*' then all columns are printed in table format (1 row per line, binary tables only). rows - (optional) vector of row numbers to print. If not supplied or set to scalar, -1, then all rows are printed. OUTPUTS: None OPTIONAL INPUT KEYWORDS: FMT = Format string for print display. If not supplied, then any formats in the TDISP keyword fields of the table will be used, otherwise IDL default formats. NUM_HEADER_LINES - Number of lines to display the column headers default = 1). By setting NUM_HEADER_LINES to an integer larger than 1, one can avoid truncation of the column header labels. In addition, setting NUM_HEADER_LINES will display commented lines indicating a FORMAT for reading the data, and a suggested call to readfmt.pro. NVAL_PER_LINE - The maximum number of values displayed from a multivalued column when printing in table format. Default = 6 TEXTOUT - scalar number (0-7) or string (file name) determining output device (see TEXTOPEN). Default is TEXTOUT=1, output to the user's terminal SYSTEM VARIABLES: Uses nonstandard system variables !TEXTOUT and !TEXTOPEN Set !TEXTOUT = 3 to direct output to a disk file. The system variable is overriden by the value of the keyword TEXTOUT EXAMPLES: tab = readfits('test.fits',htab,/ext) ;Read first extension into vars tbprint,h,tab,'STAR ID,RA,DEC' ;print id,ra,dec for all stars tbprint,h,tab,[2,3,4],indgen(100) ;print columns 2-4 for first 100 stars tbprint,h,tab,text="stars.dat" ;Convert entire FITS table to ;an ASCII file named 'stars.dat' PROCEDURES USED: GETTOK(), STRNUMBER(), TEXTOPEN, TEXTCLOSE, TBINFO RESTRICTIONS: (1) Program does not check whether output length exceeds output device capacity (e.g. 80 or 132). (2) Column heading may be truncated to fit in space defined by the FORMAT specified for the column. Use NUM_HEADER_LINES to avoid truncation. (3) Program does not check for null values (4) Does not work with variable length columns (5) Will only the display the first value of fields with multiple values (unless there is one row each with the same number of mulitple values) If printing in table format (column='*') then up to 6 values can be printed per line. HISTORY: version 1 D. Lindler Feb. 1987 Accept undefined values of rows,columns W. Landsman August 1997 Use new structure returned by TBINFO W. Landsman August 1997 Made formatting more robust W. Landsman March 2000 Use STRSPLIT to parse string column listing W. Landsman July 2002 Wasn't always printing last row W. Landsman Feb. 2003 Better formatting (space between columns) W. Landsman Oct. 2005 Use case-insensitive match with TTYPE, use STRJOIN W.L. June 2006 Fixed check for multiple values W.L. August 2006 Fixed bad index value in August 2006 fix W.L Aug 15 2006 Free-up pointers after calling TBINFO W.L. Mar 2007 Add table format capability W.L. Mar 2010 Add NUM_HEADER_LINE keyword P. Broos Apr 2010(See astrolib/pro/tbprint.pro)
TBSIZE
[Previous Routine] [Next Routine] [List of Routines]NAME: TBSIZE PURPOSE: Procedure to return the size of a FITS binary table. CALLING SEQUENCE: tbsize, h, tab, ncols, nrows, tfields, ncols_all, nrows_all INPUTS: h - FITS table header tab - FITS table array OUTPUTS: ncols - number of characters per row in table nrows - number of rows in table tfields - number of fields per row ncols_all - number of characters/row allocated (size of tab) nrows_all - number of rows allocated PROCEDURES USED: SXPAR() HISTORY D. Lindler July, 1987 Converted to IDL V5.0 W. Landsman September 1997 Remove obsolete !ERR call W. Landsman May 2000(See astrolib/pro/tbsize.pro)
TDB2TDT
[Previous Routine] [Next Routine] [List of Routines]NAME: TDB2TDT AUTHOR: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 craigm@lheamail.gsfc.nasa.gov UPDATED VERSIONs can be found on my WEB PAGE: http://cow.physics.wisc.edu/~craigm/idl/idl.html PURPOSE: Relativistic clock corrections due to Earth motion in solar system MAJOR TOPICS: Planetary Orbits CALLING SEQUENCE: corr = TDB2TDT(JD, TBASE=, DERIV=deriv) DESCRIPTION: The function TDB2TDT computes relativistic corrections that must be applied when performing high precision absolute timing in the solar system. According to general relativity, moving clocks, and clocks at different gravitational potentials, will run at different rates with respect to each other. A clock placed on the earth will run at a time-variable rate because of the non-constant influence of the sun and other planets. Thus, for the most demanding astrophysical timing applications -- high precision pulsar timing -- times in the accelerating earth observer's frame must be corrected to an inertial frame, such as the solar system barycenter (SSB). This correction is also convenient because the coordinate time at the SSB is the ephemeris time of the JPL Planetary Ephemeris. In general, the difference in the rate of Ti, the time kept by an arbitrary clock, and the rate of T, the ephemeris time, is given by the expression (Standish 1998): dTi/dT = 1 - (Ui + vi^2/2) / c^2 where Ui is the potential of clock i, and vi is the velocity of clock i. However, when integrated, this expression depends on the position of an individual clock. A more convenient approximate expression is: T = Ti + (robs(Ti) . vearth(T))/c^2 + dtgeo(Ti) + TDB2TDT(Ti) where robs is the vector from the geocenter to the observer; vearth is the vector velocity of the earth; and dtgeo is a correction to convert from the observer's clock to geocentric TT time. TDB2TDT is the value computed by this function, the correction to convert from the geocenter to the solar system barycenter. As the above equation shows, while this function provides an important component of the correction, the user must also be responsible for (a) correcting their times to the geocenter (ie, by maintaining atomic clock corrections); (b) estimating the observatory position vector; and and (c) estimating earth's velocity vector (using JPLEPHINTERP). Users may note a circularity to the above equation, since vearth(T) is expressed in terms of the SSB coordinate time. This appears to be a chicken and egg problem since in order to get the earth's velocity, the ephemeris time is needed to begin with. However, to the precision of the above equation, < 25 ns, it is acceptable to replace vearth(T) with vearth(TT). The method of computation of TDB2TDT in this function is based on the analytical formulation by Fairhead, Bretagnon & Lestrade, 1988 (so-called FBL model) and Fairhead & Bretagnon 1990, in terms of sinusoids of various amplitudes. TDB2TDT has a dominant periodic component of period 1 year and amplitude 1.7 ms. The set of 791 coefficients used here were drawn from the Princeton pulsar timing program TEMPO version 11.005 (Taylor & Weisberg 1989). Because the TDB2TDT quantity is rather expensive to compute but slowly varying, users may wish to also retrieve the time derivative using the DERIV keyword, if they have many times to convert over a short baseline. Verification This implementation has been compared against a set of FBL test data found in the 1996 IERS Conventions, Chapter 11, provided by T. Fukushima. It has been verified that this routine reproduces the Fukushima numbers to the accuracy of the table, within 10^{-14} seconds. Fukushima (1995) has found that the 791-term Fairhead & Bretagnon analytical approximation use here has a maximum error of 23 nanoseconds in the time range 1980-2000, compared to a numerical integration. In comparison the truncated 127-term approximation has an error of ~130 nanoseconds. PARAMETERS: JD - Geocentric time TT, scalar or vector, expressed in Julian days. The actual time used is (JD + TBASE). For maximum precision, TBASE should be used to express a fixed epoch in whole day numbers, and JD should express fractional offset days from that epoch. KEYWORD PARAMETERS: TBASE - scalar Julian day of a fixed epoch, which provides the origin for times passed in JD. Default: 0 DERIV - upon return, contains the derivative of TDB2TDT in units of seconds per day. As many derivatives are returned as values passed in JD. RETURNS: The correction offset(s) in units of seconds, to be applied as noted above. EXAMPLE: Find the correction at ephemeris time 2451544.5 (JD): IDL> print, tdb2tdt(2451544.5d) -0.00011376314 or 0.11 ms. REFERENCES: Princeton TEMPO Program http://pulsar.princeton.edu/tempo/ FBL Test Data Set ftp://maia.usno.navy.mil/conventions/chapter11/fbl.results Fairhead, L. & Bretagnon, P. 1990, A&A, 229, 240 (basis of this routine) Fairhead, L. Bretagnon, P. & Lestrade, J.-F. 1988, in *The Earth's Rotation and Reference Frames for Geodesy and Geodynamics*, ed. A. K. Babcock and G. A. Wilkins, (Dordrecht: Kluwer), p. 419 (original "FBL" paper) Fukushima, T. 1995, A&A, 294, 895 (error analysis) Irwin, A. W. & Fukushima, T. 1999, A&A, 348, 642 (error analysis) Standish, E. M. 1998, A&A, 336, 381 (description of time scales) Taylor, J. H. & Weisberg, J. M. 1989, ApJ, 345, 434 (pulsar timing) SEE ALSO JPLEPHREAD, JPLEPHINTERP, JPLEPHTEST MODIFICATION HISTORY: Original logic from Fairhead & Bretagnon, 1990 Drawn from TEMPO v. 11.005, copied 20 Jun 2001 Documented and vectorized, 30 Jun 2001 $Id: tdb2tdt.pro,v 1.4 2001/07/01 07:37:40 craigm Exp $(See astrolib/pro/tdb2tdt.pro)
TEN()
[Previous Routine] [Next Routine] [List of Routines]NAME: TEN() PURPOSE: Converts a sexagesimal number or string to decimal. EXPLANATION: Inverse of the SIXTY() function. CALLING SEQUENCES: X = TEN( [ HOUR_OR_DEG, MIN, SEC ] ) X = TEN( HOUR_OR_DEG, MIN, SEC ) X = TEN( [ HOUR_OR_DEG, MIN ] ) X = TEN( HOUR_OR_DEG, MIN ) X = TEN( [ HOUR_OR_DEG ] ) <-- Trivial cases X = TEN( HOUR_OR_DEG ) <-- or X = TEN(HRMNSC_STRING) INPUTS: HOUR_OR_DEG,MIN,SEC -- Scalars giving sexagesimal quantity in in order from largest to smallest. or HRMNSC_STRING - String giving sexagesmal quantity separated by spaces or colons e.g. "10 23 34" or "-3:23:45.2" Any negative values should begin with a minus sign. OUTPUTS: Function value returned = double real scalar, decimal equivalent of input sexigesimal quantity. A minus sign on any nonzero element of the input vector causes all the elements to be taken as < 0. EXAMPLES: IDL> print,ten(0,-23,34) --> -0.39277778 IDL> print,ten("-0:23:34") --> -0.39277778 PROCEDURE: Mostly involves checking arguments and setting the sign. The procedure TENV can be used when dealing with a vector of sexigesimal quantities. MODIFICATION HISTORY: Written by R. S. Hill, STX, 21 April 87 Modified to allow non-vector arguments. RSH, STX, 19-OCT-87 Recognize -0.0 W. Landsman/B. Stecklum Dec 2005 Work with string input W. Landsman Dec 2008(See astrolib/pro/ten.pro)
TENV()
[Previous Routine] [Next Routine] [List of Routines]NAME: TENV() PURPOSE: Converts sexagesimal number or string vector to decimal. EXPLANATION: Like TEN() but allows vector input. CALLING SEQUENCES: Result = TENV( dd, mm ) ; result = dd + mm/60. Result = TENV( dd, mm, ss) ; result = dd + mm/60. + ss/3600. or Result = TENV(ddmmss_string) INPUTS: dd - sexagesimal element(s) corresponding to hours or degrees mm - sexagesimal element(s) corresponding to minutes ss - sexagesimal element(s) corresponding to seconds (optional) The input parameters can be scalars or vectors. However, the number of elements in each parameter must be the same. HRMNSC_STRING - String scalar or vector giving sexagesmal quantity separated by spaces or colons e.g. "10 23 34" or "-3:23:45.2" Any negative values should begin with a minus sign. OUTPUTS: Result - double, decimal equivalent of input sexagesimal quantities. Same number of elements as the input parameters. If the nth element in any of the input parameters is negative then the nth element in Result will also be negative. EXAMPLE: If dd = [60,60,0], and mm = [30,-30,-30], then IDL> Result = TENV(dd,mm) ====> Result = [60.5,-60.5,-0.5] Alternatively, the input could be written as the string vector IDL> str = ['60:30','-60:30','-0:30'] IDL> print,tenv(str) ====> Result = [60.5,-60.5,-0.5] WARNING: TENV() will recognize floating point values of -0.0 as negative numbers. However, there is no distinction in the binary representation of -0 and 0 (integer values), and so TENV will treat both values as positive. PROCEDURES USED: GETTOK(), REPCHR() for string processing. PROCEDURE: Mostly involves checking arguments and setting the sign. MODIFICATION HISTORY: Written by W.B. Landsman April, 1991 Recognize -0.0 W. Landsman/B. Stecklum Dec 2005 Work with string input W. Landsman Feb 2009(See astrolib/pro/tenv.pro)
TEXTCLOSE
[Previous Routine] [Next Routine] [List of Routines]NAME: TEXTCLOSE PURPOSE: Close a text outpu file previously opened with TEXTOPEN EXPLANATION: procedure to close file for text output as specifed by the (non-standard) system variable !TEXTOUT. CALLING SEQUENCE: textclose, [ TEXTOUT = ] KEYWORDS: textout - Indicates output device that was used by TEXTOPEN SIDE EFFECTS: if !textout is not equal to 5 and the textunit is opened. Then unit !textunit is closed and released HISTORY: D. Lindler Dec. 1986 (Replaces PRTOPEN) Test if TEXTOUT is a scalar string W. Landsman August 1993 Can't close unit -1 (Standard Output) I. Freedman April 1994 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/textclose.pro)
TEXTOPEN
[Previous Routine] [Next Routine] [List of Routines]NAME: TEXTOPEN PURPOSE: Open a device specified by TEXTOUT with unit !TEXTUNIT EXPLANATION: Procedure to open file for text output. The type of output device (disk file or terminal screen) is specified by the TEXTOUT keyword or the (nonstandard) system variable !TEXTOUT. CALLING SEQUENCE: textopen, program, [ TEXTOUT =, /STDOUT, /SILENT, MORE_SET=, WIDTH= ] INPUTS: program - scalar string giving name of program calling textopen OPTIONAL INPUT KEYWORDS: TEXTOUT - Integer scalar (0-7) specifying output file/device to be opened (see below) or scalar string giving name of output file. If TEXTOUT is not supplied, then the (non-standard) system variable !TEXTOUT is used. /SILENT - By default, TEXTOPEN prints an informational message when opening a file for hardcopy output. Set /SILENT (or !QUIET) to suppress this message. /STDOUT - if this keyword is set and non-zero, then the standard output (unit = -1) is used for TEXTOUT=1 or TEXTOUT=2. The use of STDOUT has 2 possible advantages: (1) the output will appear in a journal file (2) Many Unix machines print spurious control characters when printing to /dev/tty. These characters are eliminated by setting /STDOUT The disadvantage of /STDOUT is that the /MORE option is not available. WIDTH - Specify line width for hardcopy output line wrapping (passed onto OPENW). OPTIONAL OUTPUT KEYWORD: MORE_SET - Returns 1 if the output unit was opened with /MORE. This occurs if (1) TEXTOUT = 1 and (2) the device is a tty, and (3) /STDOUT is not set. User can use the returned value of MORE_SET to determine whether to end output when user presses 'Q'. SIDE EFFECTS: The following dev/file is opened for output. Different effects occur depending whether the standard output is a GUI (Macintosh, Windows, Unix/IDLTool) or a TTY textout=0 Nowhere textout=1 if a TTY then TERMINAL using /more option otherwise standard (Unit=-1) output textout=2 if a TTY then TERMINAL without /more option otherwise standard (Unit=-1) output textout=3.prt textout=4 laser.tmp textout=5 user must open file textout=7 same as 3 but text is appended to .prt file if it already exists. textout = filename (default extension of .prt) The unit to be opened is obtained with the procedure GET_LUN unless !TEXTOUT=5. The unit number is placed in system variable !TEXTUNIT. For !TEXTOUT=5 the user must set !TEXTUNIT to the appropriate unit number. NOTES: When printing to a TTY terminal, the output will *not* appear in an IDL JOURNAL session, unlike text printed with the PRINT command. NON-STANDARD SYSTEM VARIABLES: TEXTOPEN will automatically define the following system variables if they are not previously defined: DEFSYSV,'!TEXTOUT',1 DEFSYSV,'!TEXTUNIT',0 HISTORY: D. Lindler Dec. 1986 Keyword textout added, J. Isensee, July, 1990 Made transportable, D. Neill, April, 1991 Trim input PROGRAM string W. Landsman Feb 1993 Don't modify TEXTOUT value W. Landsman Aug 1993 Modified for MacOS I. Freedman April 1994 Modified for output terminals without a TTY W. Landsman August 1995 Added /STDOUT keyword W. Landsman April 1996 added textout=7 option, D. Lindler, July, 1996 Exit with RETURN instead of RETALL W. Landsman June 1999 In IDL V5.4 filepath(/TERMINAL) not allowed in the IDLDE WL August 2001 Added MORE_SET output keyword W.Landsman January 2002 Added /SILENT keyword W. Landsman June 2002 Define !TEXTOUT and !TEXTUNIT if needed. R. Sterner, 2002 Aug 27 Return Calling Sequence if no parameters supplied W.Landsman Nov 2002 Remove VMS specific code W. Landsman Sep 2006 Make sure MORE_SET is always defined W. Landsman Jan 2007 Added WIDTH keyword J. Bailin Nov 2010 Use V6.0 notation W. Landsman April 2011 (See astrolib/pro/textopen.pro)
TICLABELS
[Previous Routine] [Next Routine] [List of Routines]NAME: TICLABELS PURPOSE: Create tic labels for labeling astronomical images. EXPLANATION: Used to display images with right ascension or declination axes. This routine creates labels for already determined tic marks (every other tic mark by default) CALLING SEQUENCE: TICLABELS, minval, numtics, incr, ticlabs, [ RA = ,DELTA = ] INPUTS: minval - minimum value for labels (degrees) numtics - number of tic marks incr - increment in minutes for labels OUTPUTS: ticlabs - array of charater string labels OPTIONAL INPUT KEYWORDS: /RA - if this keyword is set then the grid axis is assumed to be a Right Ascension. Otherwise a declination axis is assumed DELTA - Scalar specifying spacing of labels. The default is DELTA = 2 which means that a label is made for every other tic mark. Set DELTA=1 to create a label for every tic mark. FONT - scalar font graphics keyword (-1,0 or 1) for text PROCEDURES USED: RADEC RESTRICTIONS: Invalid for wide field (> 2 degree) images since it assumes that a fixed interval in Y (or X) corresponds to a fixed interval in Dec (or RA) REVISON HISTORY: written by B. Pfarr, 4/15/87 Added DELTA keywrd for compatibility with IMCONTOUR W. Landsman Nov 1991 Added nicer hms and dms symbols when using native PS fonts Deutsch 11/92 Added Patch for bug in IDL <2.4.0 as explained in NOTES E. Deutsch 11/92 Fix when crossing 0 dec or 24h RA Fix DELTA keyword so that it behaves according to the documentation W. Landsman Hughes STX, Nov 95 Allow sub arcsecond formatting W. Landsman May 2000 Better formatting for non-unity DELTA values W. Landsman July 2004 Allow FONT keyword to be passed. T. Robishaw Apr. 2006 Write 0h rather than 24h W. L. August 2008 Fix problem when tic values is exactly 0 degrees Mar 2012 Only modulo 24 when /RA is set WL. October 2012(See astrolib/pro/ticlabels.pro)
TICPOS
[Previous Routine] [Next Routine] [List of Routines]NAME: TICPOS PURPOSE: Specify distance between tic marks for astronomical coordinate overlays EXPLANATION: User inputs number an approximate distance between tic marks, and the axis length in degrees. TICPOS will return a distance between tic marks such that the separation is a round multiple in arc seconds, arc minutes, or degrees CALLING SEQUENCE: TICPOS, deglen, pixlen, ticsize, incr, units INPUTS: deglen - length of axis in DEGREES pixlen - length of axis in plotting units (pixels) ticsize - distance between tic marks (pixels). This value will be adjusted by TICPOS such that the distance corresponds to a round multiple in the astronomical coordinate. OUTPUTS: ticsize - distance between tic marks (pixels), positive scalar incr - incremental value for tic marks in round units given by the UNITS parameter units - string giving units of ticsize, either 'ARC SECONDS', 'ARC MINUTES', or 'DEGREES' EXAMPLE: Suppose a 512 x 512 image array corresponds to 0.2 x 0.2 degrees on the sky. A tic mark is desired in round angular units, approximately every 75 pixels. IDL> ticsize = 75 IDL> TICPOS,0.2,512,ticsize,incr,units ==> ticsize = 85.333, incr = 2. units = 'Arc Minutes' i.e. a good tic mark spacing is every 2 arc minutes, corresponding to 85.333 pixels. REVISON HISTORY: written by W. Landsman November, 1988 Converted to IDL V5.0 W. Landsman September 1997 Don't use all capital letters W. Landsman May 2003 Fix case where incr crosses degree/minute or minute/degree boundary A. Mortier/W.Landsman April 2005(See astrolib/pro/ticpos.pro)
TICS
[Previous Routine] [Next Routine] [List of Routines]NAME: TICS PURPOSE: Compute a nice increment between tic marks for astronomical images. EXPLANATION: For use in labelling a displayed image with right ascension or declination axes. An approximate distance between tic marks is input, and a new value is computed such that the distance between tic marks is in simple increments of the tic label values. CALLING SEQUENCE: tics, radec_min, radec_max, numx, ticsize, incr, [ /RA ] INPUTS: radec_min - minimum axis value (degrees) radec_max - maximum axis value (degrees) numx - number of pixels in x direction INPUT/OUTPUT ticsize - distance between tic marks (pixels) OUTPUTS: incr - incremental value for tic labels (in minutes of time for R.A., minutes of arc for dec.) REVISON HISTORY: written by B. Pfarr, 4/14/87 Added some more tick precision (i.e. 1 & 2 seconds in case:) EWD May92 Added sub arcsecond tick precision W. Landsman May 2000 Plate scale off by 1 pixel W. Landsman July 2004(See astrolib/pro/tics.pro)
TIC_ONE
[Previous Routine] [Next Routine] [List of Routines]NAME: TIC_ONE PURPOSE: Determine the position of the first tic mark for astronomical images. EXPLANATION: For use in labelling images with right ascension and declination axes. This routine determines the position in pixels of the first tic. CALLING SEQUENCE: tic_one, zmin, pixx, incr, min2, tic1, [RA = ] INPUTS: zmin - astronomical coordinate value at axis zero point (degrees or hours) pixx - distance in pixels between tic marks (usually obtained from TICS) incr - increment in minutes for labels (usually an even number obtained from the procedure TICS) OUTPUTS: min2 - astronomical coordinate value at first tic mark tic1 - position in pixels of first tic mark EXAMPLE: Suppose a declination axis has a value of 30.2345 degrees at its zero point. A tic mark is desired every 10 arc minutes, which corresponds to 12.74 pixels. Then IDL> TIC_ONE, 30.2345, 1, 12.74, min2, tic1 yields values of min2 = 30.333 and tic1 = 5.74, i.e. the first tic mark should be labeled 30 deg 20 minutes and be placed at pixel value 5.74 REVISION HISTORY: by B. Pfarr, 4/15/87 Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/tic_one.pro)
TO_HEX
[Previous Routine] [Next Routine] [List of Routines]NAME: TO_HEX PURPOSE: Translate a non-negative decimal integer to a hexadecimal string CALLING SEQUENCE: HEX = TO_HEX( D, [ NCHAR ] ) INPUTS: D - non-negative decimal integer, scalar or vector. If input as a string, (e.g. '32') then all leading blanks are removed. OPTIONAL INPUT: NCHAR - number of characters in the output hexadecimal string. If not supplied, then the hex string will contain no leading zeros. OUTPUT: HEX - hexadecimal translation of input integer, string EXAMPLES: IDL> A = TO_HEX([11,16]) ==> A = ['B','10'] IDL> A = TO_HEX(100,3) ==> A = '064' METHOD: The hexadecimal format code '(Z)' is used to convert. No parameter checking is done. PROCEDURES CALLED: None. REVISION HISTORY: Written W. Landsman November, 1990 Converted to IDL V5.0 W. Landsman September 1997 Use FSTRING() for more than 1024 values March 2000 Assume since V5.4, omit FSTRING() call April 2006(See astrolib/pro/to_hex.pro)
TRANSFORM_COEFF()
[Previous Routine] [Next Routine] [List of Routines]NAME: TRANSFORM_COEFF() PURPOSE: Compute new polynomial coefficients under a linear transformation EXPLANATION: Suppose one has a (nonlinear) polynomial (similar to the POLY() function) y = C[0] + C[1]*x + C[2]*x^2 + C[3]*x^3 + ... and one has a linear transformation in X x = alpha*x' + beta This function computes the new polynomial coefficients under the linear transformation. CALLING SEQUENCE: newcoeff = TRANSFORM_COEFF( coeff, alpha, beta) INPUTS: Coeff - vector of polynomial coefficients (as with POLY()). The degree of the polynomial is N_elements(coeff) - 1 Alpha, Beta - numeric scalars defining the linear transformation in X OUTPUTS: NewCoeff - Vector (same size as Coeff) giving the new polyomial coefficients EXAMPLE: Suppose one has polynomial mapping a nonlinear distortion in the X direction of a spectrum y = 0.2 + 1.1*x + 0.1*x^2 if one rebins the spectrum to half the size then the linear transformation is x = 2.*x' so alpha = 2 and beta = 0 The new coefficients are IDL> print, transform_coeff([0.2,1.1,0.1],2.,0) ==> [0.2, 2.2, 0.4] METHOD: Performs a binomial expansion of the polynomial and collect like terms groups.google.com/group/comp.lang.idl-pvwave/msg/11132d96d9c0f93d?hl=en& REVISION HISTORY: Written W. Landsman December 2007(See astrolib/pro/transform_coeff.pro)
TRAPZD
[Previous Routine] [Next Routine] [List of Routines]NAME: TRAPZD PURPOSE: Compute the nth stage of refinement of an extended trapezoidal rule. EXPLANATION: This procedure is called by QSIMP and QTRAP. Algorithm from Numerical Recipes, Section 4.2. TRAPZD is meant to be called iteratively from a higher level procedure. CALLING SEQUENCE: TRAPZD, func, A, B, S, step, [ _EXTRA = ] INPUTS: func - scalar string giving name of function to be integrated. This must be a function of one variable. A,B - scalars giving the limits of the integration INPUT-OUTPUT: S - scalar giving the total sum from the previous iterations on input and the refined sum after the current iteration on output. step - LONG scalar giving the number of points at which to compute the function for the current iteration. If step is not defined on input, then S is intialized using the average of the endpoints of limits of integration. OPTIONAL INPUT KEYWORDS: Any supplied keywords will be passed to the user function via the _EXTRA facility. NOTES: (1) TRAPZD will check for math errors (except for underflow) when computing the function at the endpoints, but not on subsequent iterations. (2) TRAPZD always uses double precision to sum the function values but the call to the user-supplied function is double precision only if one of the limits A or B is double precision. REVISION HISTORY: Written W. Landsman August, 1991 Always use double precision for TOTAL March, 1996 Pass keyword to function via _EXTRA facility W. Landsman July 1999 Don't check for floating underflow W.Landsman April 2008(See astrolib/pro/trapzd.pro)
TSC
[Previous Routine] [Next Routine] [List of Routines]NAME: TSC PURPOSE: Interpolate an irregularly sampled field using a Triangular Shaped Cloud EXPLANATION: This function interpolates an irregularly sampled field to a regular grid using Triangular Shaped Cloud (nearest grid point gets weight 0.75-dx^2, points before and after nearest grid points get weight 0.5*(1.5-dx)^2, where dx is the distance from the sample to the grid point in units of the cell size). CATEGORY: Mathematical functions, Interpolation CALLING SEQUENCE: Result = TSC, VALUE, POSX, NX[, POSY, NY, POSZ, NZ, AVERAGE = average, WRAPAROUND = wraparound, ISOLATED = isolated, NO_MESSAGE = no_message] INPUTS: VALUE: Array of sample weights (field values). For e.g. a temperature field this would be the temperature and the keyword AVERAGE should be set. For e.g. a density field this could be either the particle mass (AVERAGE should not be set) or the density (AVERAGE should be set). POSX: Array of X coordinates of field samples, unit indices: [0,NX>. NX: Desired number of grid points in X-direction. OPTIONAL INPUTS: POSY: Array of Y coordinates of field samples, unit indices: [0,NY>. NY: Desired number of grid points in Y-direction. POSZ: Array of Z coordinates of field samples, unit indices: [0,NZ>. NZ: Desired number of grid points in Z-direction. KEYWORD PARAMETERS: AVERAGE: Set this keyword if the nodes contain field samples (e.g. a temperature field). The value at each grid point will then be the weighted average of all the samples allocated to it. If this keyword is not set, the value at each grid point will be the weighted sum of all the nodes allocated to it (e.g. for a density field from a distribution of particles). (D=0). WRAPAROUND: Set this keyword if you want the first grid point to contain samples of both sides of the volume (see below). ISOLATED: Set this keyword if the data is isolated, i.e. not periodic. In that case total `mass' is not conserved. This keyword cannot be used in combination with the keyword WRAPAROUND. NO_MESSAGE: Suppress informational messages. Example of default allocation of nearest grid points: n0=4, *=gridpoint. 0 1 2 3 Index of gridpoints * * * * Grid points |---|---|---|---| Range allocated to gridpoints ([0.0,1.0> --> 0, etc.) 0 1 2 3 4 posx Example of ngp allocation for WRAPAROUND: n0=4, *=gridpoint. 0 1 2 3 Index of gridpoints * * * * Grid points |---|---|---|---|-- Range allocated to gridpoints ([0.5,1.5> --> 1, etc.) 0 1 2 3 4=0 posx OUTPUTS: Prints that a TSC interpolation is being performed of x samples to y grid points, unless NO_MESSAGE is set. RESTRICTIONS: Field data is assumed to be periodic with the sampled volume the basic cell, unless ISOLATED is set. All input arrays must have the same dimensions. Postition coordinates should be in `index units' of the desired grid: POSX=[0,NX>, etc. Keywords ISOLATED and WRAPAROUND cannot both be set. PROCEDURE: Nearest grid point is determined for each sample. TSC weights are computed for each sample. Samples are interpolated to the grid. Grid point values are computed (sum or average of samples). EXAMPLE: nx=20 ny=10 posx=randomu(s,1000) posy=randomu(s,1000) value=posx^2+posy^2 field=tsc(value,posx*nx,nx,posy*ny,ny,/average) surface,field,/lego NOTES: Use csc.pro or ngp.pro for lower order interpolation schemes. A standard reference for these interpolation methods is: R.W. Hockney and J.W. Eastwood, Computer Simulations Using Particles (New York: McGraw-Hill, 1981). MODIFICATION HISTORY: Written by Joop Schaye, Feb 1999. Check for overflow for large dimensions P. Riley/W. Landsman Dec. 1999(See astrolib/pro/tsc.pro)
TSUM
[Previous Routine] [Next Routine] [List of Routines]NAME: TSUM PURPOSE: Trapezoidal summation of the area under a curve. EXPLANATION: Adapted from the procedure INTEG in the IUE procedure library. CALLING SEQUENCE: Result = TSUM(y) or Result = TSUM( x, y, [ imin, imax ] ) INPUTS: x = array containing monotonic independent variable. If omitted, then x is assumed to contain the index of the y variable. x = lindgen( N_elements(y) ). y = array containing dependent variable y = f(x) OPTIONAL INPUTS: imin = scalar index of x array at which to begin the integration If omitted, then summation starts at x[0]. imax = scalar index of x value at which to end the integration If omitted then the integration ends at x[npts-1]. OUTPUTS: result = area under the curve y=f(x) between x[imin] and x[imax]. EXAMPLE: IDL> x = [0.0,0.1,0.14,0.3] IDL> y = sin(x) IDL> print,tsum(x,y) ===> 0.0445843 In this example, the exact curve can be computed analytically as 1.0 - cos(0.3) = 0.0446635 PROCEDURE: The area is determined of individual trapezoids defined by x[i], x[i+1], y[i] and y[i+1]. If the data is known to be at all smooth, then a more accurate integration can be found by interpolation prior to the trapezoidal sums, for example, by the standard IDL User Library int_tabulated.pro. MODIFICATION HISTORY: Written, W.B. Landsman, STI Corp. May 1986 Modified so X is not altered in a one parameter call Jan 1990 Converted to IDL V5.0 W. Landsman September 1997 Allow non-integer values of imin and imax W. Landsman April 2001 Fix problem if only 1 parameter supplied W. Landsman June 2002(See astrolib/pro/tsum.pro)
TVBOX
[Previous Routine] [Next Routine] [List of Routines]NAME: TVBOX PURPOSE: Draw a box(es) or rectangle(s) of specified width EXPLANATION: Positions can be specified either by the cursor position or by supplying a vector of X,Y positions. By default, TVBOX now (since Jan 2012) assumes data coordinates if !X.crange is set. CALLING SEQUENCE: TVBOX, width, [ x, y, color, /DATA, ANGLE= ,COLOR =, _EXTRA = ] INPUTS: WIDTH - either a scalar giving the width of a box, or a 2 element vector giving the length and width of a rectangle. OPTIONAL INPUTS: X - x position for box center, scalar or vector Y - y position for box center, scalar or vector. If vector, then Y must have the same number of elements as X Positions are specified in device coordinates unless /DATA is set If X and Y are not specified, and device has a cursor, then TVBOX will draw a box at current cursor position COLOR - String or integer specifying the color to draw the box(es) If COLORS is a scalar then all boxes are drawn with the same color value. Otherwise, the Nth box is drawn with the Nth value of color. Color can also be specified as string (e.g.'red'). See cgCOLOR for a list of available color names. Default = "opposite". OUTPUTS: None OPTIONAL KEYWORD INPUTS: ANGLE - numeric scalar specifying the clockwise rotation of the boxes or rectangles. COLOR - Scalar or vector, overrides the COLOR input parameter Color can be specified as a string (e.g. 'red') or intensity value. See cgCOLOR() for a list of color names. Default = 'opposite' (i.e. color opposite the background). /DATA - if this keyword is set and non-zero, then the box width and X,Y position center are interpreted as being in DATA coordinates. Note that data coordinates must be previously defined (with a PLOT or CONTOUR call). The default is to assume data coordinates if !X.CRANGE is set. Force device coordinates by setting DATA = 0 or /DEVICE /DEVICE Set this keyword to force use of device coordinates /FILL - If set, fill the box using cgCOLORFILL /SQUARE - If set, then a square is drawn, even if in data coordinates with unequal X and Y axes. The X width is used for the square width, and the Y width is ignored. Any keyword recognized by cgPLOTS (or cgCOLORFILL if /FILL is set) is also recognized by TVBOX. In particular, the linestyle, thickness and clipping of the boxes is controlled by the LINESTYLE, THICK and NOCLIP keywords. (Clipping is turned off by default, set NOCLIP=0 to activate it.) If /FILL is set then available keywords include LINE_FILL and FILL_PATTERN. SIDE EFFECTS: A square or rectangle will be drawn on the device For best results WIDTH should be odd when using the default DEVICE coordinates. (If WIDTH is even, the actual size of the box will be WIDTH + 1, so that box remains centered.) EXAMPLES: (1) Draw a double thick box of width 13, centered at 221,256 in the currently active window IDL> tvbox, 13, 221, 256, thick=2 (2) Overlay a "slit" with dimension 52" x 2" on a previously displayed image at a position angle (East of North) of 32 degrees. The slit is to be centered at XC, YC and the plate scale arcsec_per_pixel is known. IDL> w = [2.,52.]/arcsec_per_pixel ;Convert slit size to pixel units IDL> tvbox,w,XC,YC,ang=-32 ;Draw slit RESTRICTIONS: Allows use of only device (default) or data (if /DATA is set) coordinates. Normalized coordinates are not allowed PROCEDURES USED: cgpolygon, zparcheck REVISON HISTORY: Written, W. Landsman STX Co. 10-6-87 Modified to take vector arguments. Greg Hennessy Mar 1991 Fixed centering of odd width W. Landsman Sep. 1991 Let the user specify COLOR=0, accept vector color, W. Landsman Nov. 1995 Fixed typo in _EXTRA keyword W. Landsman August 1997 Added ANGLE keyword W.Landsman February 2000 Make sure ANGLE is a scalar W. Landsman September 2001 Don't round coordinates if /DATA is set. M. Perrin August 2005 Use STRICT_EXTRA to flag valid keywords W. Landsman Sep 2005 Check that width has only 1 or 2 elements W. Landsman August 2010 Use Coyote Graphcis W. Landsman February 2011 Added /FILL keyword W. Landsman July 2011 Default to data coordinates if !X.crange present WL Jan 2012 Added Square keyword WL. April 2012(See astrolib/pro/tvbox.pro)
TVCIRCLE
[Previous Routine] [Next Routine] [List of Routines]NAME: TVCIRCLE PURPOSE: Draw circle(s) of specified radius at specified position(s) EXPLANATION: If a position is not specified, and device has a cursor, then a circle is drawn at the current cursor position. By default, TVCIRCLE now (since Jan 2012) assumes data coordinates if !X.crange is set. CALLING SEQUENCE: TVCIRCLE, rad, x, y, color, [ /DATA, /FILL, _EXTRA = ] INPUTS: RAD - radius of circle(s) to be drawn, positive numeric scalar OPTIONAL INPUT: X - x position for circle center, vector or scalar Y - y position for circle center, vector or scalar If X and Y are not specified, and the device has a cursor, then program will draw a circle at the current cursor position COLOR - color name or intensity value(s) (0 - !D.N_COLORS) used to draw the circle(s). If COLOR is a scalar then all circles are drawn with the same color value. Otherwise, the Nth circle is drawn with the Nth value of color. See cgCOLOR() for a list of color names. Default = 'opposite' (i.e. color opposite the background). OPTIONAL KEYWORD INPUTS: /DATA - if this keyword is set and non-zero, then the circle width and X,Y position center are interpreted as being in DATA coordinates. Note that data coordinates must be previously defined (with a PLOT or CONTOUR call). TVCIRCLE will internally convert to device coordinates before drawing the circle, in order to maintain optimal smoothness. The default is to assume data coordinates if !X.CRANGE is set. Force device coordinates by setting DATA = 0 or /DEVICE /DEVICE - If set, then force use of device coordinates.. /FILL - If set, fill the circle using cgCOLORFILL Any keyword recognized by cgPLOTS (or cgCOLORFILL if /FILL is set) is also recognized by TVCIRCLE. In particular, the color, linestyle, thickness and clipping of the circles are controlled by the COLOR, LINESTYLE, THICK and NOCLIP keywords. (Clipping is turned off by default, set NOCLIP=0 to activate it.) If /FILL is set then available keywords are LINE_FILL and FILL_PATTERN. OUTPUTS: None RESTRICTIONS: (1) Some round-off error may occur when non-integral values are supplied for both the radius and the center coordinates (2) TVCIRCLE does not accept /NORMAL coordinates. (3) TVCIRCLE always draws a circle --- even when in data coordinates and the X and Y data scales are unequal. (The X data scale is used to define the circle radius.) If this is not the behaviour you want, then use TVELLIPSE instead. EXAMPLE: (1) Draw circles of radius 9 pixels at the positions specified by X,Y vectors, using double thickness lines IDL> tvcircle, 9, x, y, THICK = 2 Now fill in the circles using the LINE_FILL method IDL> tvcircle, 9, x, y, /FILL, /LINE_FILL METHOD: The method used is that of Michener's, modified to take into account the fact that IDL plots arrays faster than single points. See "Fundamental of Interactive Computer Graphics" by Foley and Van Dam" p. 445 for the algorithm. REVISON HISTORY: Original version written by B. Pfarr STX 10-88 Major rewrite adapted from CIRCLE by Allyn Saroyan LNLL Wayne Landsman STX Sep. 91 Added DATA keyword Wayne Landsman HSTX June 1993 Added FILL keyword. R. S. Hill, HSTX, 4-Nov-1993 Always convert to device coords, add _EXTRA keyword, allow vector colors. Wayne Landsman, HSTX, May 1995 Allow one to set COLOR = 0, W. Landsman, HSTX, November 1995 Check if data axes reversed. P. Mangifico, W. Landsman May 1996 Use strict_extra to check input keywords W. Landsman July 2005 Update documentation to note NOCLIP=0 option W.L. Oct. 2006 Make all integers default to LONG W. Landsman Dec 2006 Use Coyote Graphics procedures W. Landsman Feb 2011 Default to data coordinates if !X.crange present WL Jan 2012 Add /DEVICE coords, fix Jan 2012 update. Mar 2012(See astrolib/pro/tvcircle.pro)
TVELLIPSE
[Previous Routine] [Next Routine] [List of Routines]NAME: TVELLIPSE PURPOSE: Draw an ellipse on the current graphics device. CALLING SEQUENCE: TVELLIPSE, rmax, rmin, xc, yc, [ pos_ang, color, COLOR= ,/DATA, NPOINTS= LINESTYLE=, THICK=, /MAJOR, /MINOR ] INPUTS: RMAX,RMIN - Scalars giving the semi-major and semi-minor axes of the ellipse OPTIONAL INPUTS: XC,YC - Scalars giving the position on the TV of the ellipse center If not supplied (or if XC, YC are negative and /DATA is not set), and an interactive graphics device (e.g. not postscript) is set, then the user will be prompted for X,Y POS_ANG - Position angle of the major axis, measured counter-clockwise from the X axis. Default is 0. COLOR - Scalar integer or string specifying color to draw ellipse. See cgcolor.pro for a list of possible color names OPTIONAL KEYWORD INPUT: COLOR - Intensity value or color name used to draw the circle, overrides parameter value. Default = 'opposite' See cgCOLOR() for a list of color names.; /DATA - if this keyword is set and non-zero, then the ellipse radii and X,Y position center are interpreted as being in DATA coordinates. Note that the data coordinates must have been previously defined (with a PLOT or CONTOUR call). The default is to assume data coordinates if !X.CRANGE has been set by a previous plot. Force device coordinates by setting DATA = 0. /DEVICE - Set to force use of device coordinates. /FILL - If set, then fill the ellipse using cgCOLORFILL NPOINTS - Number of points to connect to draw ellipse, default = 120 Increase this value to improve smoothness /MAJOR - Plot a line along the ellipse's major axis /MINOR - Plot a line along the ellipse's minor axis Any keyword recognized by cgPLOTS is also recognized by TVELLIPSE. In particular, the color, linestyle, thickness and clipping of the ellipses are controlled by the COLOR, LINESTYLE, THICK and NOCLIP keywords. (Clipping is turned off by default, set NOCLIP=0 to activate it.) If /FILL is set then available keywords include LINE_FILL and FILL_PATTERN. RESTRICTIONS: TVELLIPSE does not check whether the ellipse is within the boundaries of the window. The ellipse is evaluated at NPOINTS (default = 120) points and connected by straight lines, rather than using the more sophisticated algorithm used by TVCIRCLE TVELLIPSE does not accept normalized coordinates. TVELLIPSE is not vectorized; it only draws one ellipse at a time EXAMPLE: Draw an ellipse of semi-major axis 50 pixels, minor axis 30 pixels, centered on (250,100), with the major axis inclined 25 degrees counter-clockwise from the X axis. Use a double thickness line and device coordinates IDL> tvellipse,50,30,250,100,25,thick=2,/device NOTES: Note that the position angle for TVELLIPSE (counter-clockwise from the X axis) differs from the astronomical position angle (counter-clockwise from the Y axis). REVISION HISTORY: Written W. Landsman STX July, 1989 Converted to use with a workstation. M. Greason, STX, June 1990 LINESTYLE keyword, evaluate at 120 points, W. Landsman HSTX Nov 1995 Added NPOINTS keyword, fixed /DATA keyword W. Landsman HSTX Jan 1996 Check for reversed /DATA coordinates P. Mangiafico, W.Landsman May 1996 Work correctly when X & Y data scales are unequal December 1998 Removed cursor input when -ve coords are entered with /data keyword set P. Maxted, Keele, 2002 Use _EXTRA keywords including NOCLIP W. Landsman October 2006 Add plotting of major and minor axes and /MAJOR, /MINOR keywords; fixed description of RMAX,RMIN (semi-axes). J. Guerber Feb. 2007 Update to use Coyote graphics W. Landsman Feb 2011 Default to data coordinates if a previous plot has been made (X.crange is non-zero) W. Landsman Jan 2012 Added /DEVICE keyword W. Landsman Mar 2012 Added /FILL keyword W. Landsman Mar 2012(See astrolib/pro/tvellipse.pro)
TVLASER
[Previous Routine] [Next Routine] [List of Routines]NAME: TVLASER PURPOSE: Prints screen or image array onto a Postscript file or printer. Information from FITS header is optionally used for labeling. CALLING SEQUENCE: TVLASER, [header, Image, BARPOS = ,CARROWS =, CLABELS = ,/COLORPS, COMMENTS = ,CSIZE = ,CTITLE = , DX = , DY =, /ENCAP, FILENAME = HEADER = ,/HELP, IMAGEOUT = ,/INTERP, /MAGNIFY, /NoCLOSE, /NoDELETE, /NO_PERS_INFO, /NoEIGHT, /NoPRINT, /NoRETAIN, /PORTRAIT, PRINTER = , /REVERSE, /SCALE, TITLE = , /TrueColor, XDIM=, XSTART=, YDIM=, YSTART=, BOTTOMDW=, NCOLORSDW= ] Note that the calling sequence was changed in May 1997 OPTIONAL INPUTS: HEADER - FITS header string array. Object and astrometric info from the FITS header will be used for labeling, if available IMAGE - if an array is passed through this parameter, then this image will be used rather than reading off the current window. This allows easy use of large images. It is usually preferable to optimally byte scale IMAGE before supplying it to TVLASER OPTIONAL KEYWORD INPUT PARAMETERS: BARPOS - A four- or five-element vector giving the position and orientation of the color bar. The first four elements [X0,Y0,XSize,YSize] indicate the position and size of the color bar in INCHES, relative to origin of the displayed image. (X0,Y0) are the position of the lower left corner and (XSize,YSize) are the width and height. The fifth element is optional, and if present, the color bar will be printed horizontally rather than vertically. If BARPOS is set to anything but a four- or five-element vector, the bar is NOT printed. The default value is BARPOS = [-0.25, 0.0, 0.2, 2.0] BOTTOMDW - The lowest value to use in building the density wedge. Used with NCOLORSDW. Compatible with BOTTOM and NCOLORS keywords of XLOADCT. CARROWS - The color to print the North-East arrows. Default is dark. Three types of values can be passed: SCALAR: that value's color in the current color table 3-ELEMENT VECTOR: the color will be [R,G,B] STRING: A letter indicating the color. Valid names are: 'W' (white), 'D' (dark/black), 'R' (red), 'G' (green), 'B' (blue), 'T' (turquoise), 'V' (violet), 'Y' (yellow), If the keyword is set to a value of -1, the arrows are NOT printed. COLORPS - If present and non-zero, the idl.ps file is written using color postscript. COMMENTS - A string that will be included in the comment line below the image. For multi-line comments you can either use "!C" in the string as a carriage return {although the vertical spacing might be a little off} or, preferably, make the COMMENTS a string array with each line as a separate element. CLABELS - Color to print the labels, same format as for CARROWS. CSIZE - Color to print the size-scale bar and label, same format as for CARROWS. CTITLE - Color to print the title, same format as for CARROWS. DX,DY - offsets in INCHES added to the position of the figure on the paper. As is the case for the device keywords XOFFSET and YOFFSET, when in landscape mode DX and DY are the same *relative to the paper*, not relative to the plot (e.g., DX is the horizontal offset in portrait mode, but the *vertical* offset in landscape mode). ENCAP - If present and non-zero, the IDL.PS file is written in encapsulated postscript for import into LaTeX documents FILENAME - scalar string giving name of output postscript file. Default is idl.ps. Automatically sets /NODELETE HEADER = FITS header. This is an alternative to supplying the FITS header in the first parameter. HELP - print out the sytax for this procedure. INTERP - If present and non-zero, current color table will be interpolated to fill the full range of the PostScript color table (256 colors). Otherwise, the current color table will be directly copied. You probably will want to use this if you are using IMAGE keyword and a shared color table. MAGNIFY - The net magnification of the entire figure. At this point, the figure is not automatically centered on the paper if the value of MAGNIFY is not equal to 1, but the DX and DY keywords can be used to shift location. For example, to fit a full plot on the printable area (8.5x8.5 inches) of the Tek PhaserIISD color printer use: MAGNIFY=0.8, DX=0.5, DY=0.5.; NCOLORSDW - The number of values to include in the density wedge. Used with BOTTOMDW. Compatible with BOTTOM/NCOLORS keywords of XLOADCT. NoCLOSE - If present and non-zero, then the postscript file is not closed (or printed), the device is set to 'PS', and the data coordinate system is set to match the image size. This allows the user to add additional plotting commands before printing. For example, to include a 15 pixel circle around a source at coordinates (150,160), around an image, im, with FITS header array, h IDL> tvlaser,h,im,/NoClose ;Write image & annotation IDL> tvcircle,15,150,160,/data ;Draw circle IDL> device,/close ;Close postscript file & print NoDELETE - If present and non-zero, the postscript file is kept AND is also sent to the printer NoEIGHT - if set then only four bits sent to printer (saves space) NO_PERS_INFO - if present and non-zero, output notation will NOT include date/user block of information. NoPRINT - If present and non-zero, the output is sent to a file (default name 'idl.ps'), which is NOT deleted and is NOT sent to the printer. NoRETAIN - In order to avoid possible problems when using TVRD with an obscured window, TVLASER will first copy the current window to a temporary RETAIN=2 window. Set /NORETAIN to skip this step and improve performance PORTRAIT - if present and non-zero, the printer results will be in portrait format; otherwise, they will be in landscape format. If labels are requested, image will be in portrait mode, regardless PRINTER - scalar string giving the OS command to send a the postscript file to the printer. Under Unix, the default value of PRINTER is 'lpr ' while for other OS it is 'print ' REVERSE - if present and non-zero, color table will be fliped, so black and white are reversed. SCALE - if present and non-zero, image will be bytscaled before being sent to postscript file. TITLE - if present and non-zero, the string entered here will be the title of the picture. Default is the OBJECT field in the header (if present). TRUECOLOR - if present and non-zero, the postscript file is created using the truecolor switch (i.e. true=3). The colorbar is not displayed in this mode. XDIM,YDIM - Number of pixels. Default is from !d.x_size and !d.y_size, or size of image if passed with IMAGE keyword. XSTART,YSTART - lower left corner (default of (0,0)) OPTIONAL KEYWORD OUTPUT PARAMETER IMAGEOUT = the image byte array actually sent to the postscript file. SIDE EFFECTS: A postscript file is created in the current directory. User must have write privileges in the current directory. The file is named idl.ps unless the FILENAME keyword is given. The file is directed to the printer unless the /ENCAP, /NoCLOSE, or /NOPRINT keywords are given. After printing, the file is deleted unless the /NODELETE or FILENAME keywords are given. PROCEDURE: Read display or take IMAGE and then redisplay into a postscript file. If a header exists, printout header information. If header has astrometry, then print out orientation and scale information. PROCEDURES USED: ARROWS, EXTAST, FDECOMP, GETROT, PIXCOLOR, SXPAR(), XYAD, ZPARCHECK *EXAMPLE: 1) Send a true color image (xsize,ysize,3) to a printer (i.e. print23l), tvlaser,huv,cpic,/colorps,/truecolor,printer="print23l" % TVLASER: Now printing image: $print23l idl.ps MODIFICATION HISTORY: Major rewrite from UIT version W. Landsman Dec 94 Massive rewrite. Added North-East arrows, pixel scale bar, color bar, and keywords DX, DY, MAGNIFY, INTERP, HELP, and COMMENTS. Created ablility to define colors for annotation and text. Repositioned text labels. J.Wm.Parker, HITC, 5/95 Make Header and Image parameters instead of keywords. Add PRINTER keyword. Include alternate FITS keywords. W. Landsman May 97 Copy to a RETAIN=2 window, work without FITS header W. Landsman June 97 Cleaner output when no astrometry in header W. Landsman June 97 Added /INFO to final MESSAGE W. Landsman July 1997 12/4/97 jkf/acc - added TrueColor optional keyword. Added /NoClose keyword, trim Equinox format W. Landsman 9-Jul-1998 Don't display coordinate labels if no astrometry, more flexible formatting of exposure time W. Landsman 30-Aug-1998 BottomDW and NColorsDW added. R. S. Hill, 1-Mar-1999 Apply func tab to color bar if not colorps. RSH, 21 Mar 2000 Fix problem with /NOCLOSE and unequal X,Y sizes W. Landsman Feb 2001 Use TVRD(True=3) if /TRUECOLOR set W. Landsman November 2001 More synonyms, check for header supplied W. Landsman November 2007(See astrolib/pro/tvlaser.pro)
TVLIST
[Previous Routine] [Next Routine] [List of Routines]NAME: TVLIST PURPOSE: Cursor controlled listing of image pixel values in a window. CALLING SEQUENCE: TVLIST, [image, dx, dy, TEXTOUT=, OFFSET= , ZOOM= ] OPTIONAL INPUTS: IMAGE - Array containing the image currently displayed on the screen. If omitted, the byte pixel intensities are read from the TV If the array does not start at position (0,0) on the window then the OFFSET keyword should be supplied. DX -Integer scalar giving the number of pixels in the X direction to be displayed. If omitted then DX = 18 for byte images, and DX = 14 for integer images. TVLIST will display REAL data with more significant figures if more room is availble to print. DY - Same as DX, but in Y direction. If omitted, then DY = DX OPTIONAL INPUT KEYWORDS: 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. TEXTOUT - Optional keyword that determines output device. The following dev/file is opened for output. textout=1 TERMINAL using /more option (default) textout=2 TERMINAL without /more option textout=3.prt textout=4 laser.tmp textout=5 user must open file textout=7 Append to an existing .prt file if it exists textout = filename (default extension of .prt) If TEXTOUT > 3 or set to a filename, then TVLIST will prompt for a brief description to be included in the output file OUTPUTS: None. PROCEDURE: Program prompts user to place cursor on region of interest in image display. Corresponding region of image is then displayed at the terminal. A compression factor between the image array and the displayed image is determined using the ratio of image sizes. If necessary, TVLIST will divide all pixel values in a REAL*4 image by a (displayed) factor of 10^n (n=1,2,3...) to make a pretty format. SYSTEM VARIABLE: The nonstandard system variable !TEXTOUT is used as an alternative to the keyword TEXTOUT. The procedure ASTROLIB can be used to define !TEXTOUT (and !TEXTUNIT) if necessary. RESTRICTIONS: TVLIST may not be able to correctly format all pixel values if the dynamic range near the cursor position is very large. For the cursor to work under Mac OSX the "Click-through Inactive Windows" setting the in X11:Preferences:Window needs to be enabled. PROCEDURES CALLED: IMLIST, UNZOOM_XY REVISION HISTORY: Written by rhc, SASC Tech, 3/14/86. Added textout keyword option, J. Isensee, July, 1990 Check for readable pixels W. Landsman May 1992 Use integer format statement from F_FORMAT W. Landsman Feb 1994 Added OFFSET, ZOOM keywords W. Landsman Mar 1996 More intelligent formatting of longword, call TEXTOPEN with /STDOUT W. Landsman April, 1996 Added check for valid dx value W. Landsman Mar 1997 Converted to IDL V5.0 W. Landsman September 1997 Major rewrite to call IMLIST, recognize new integer data types W. Landsman Jan 2000 Remove all calls to !TEXTUNIT W. Landsman Sep 2000 Always call UNZOOM_XY for MOUSSE compatibility W. Landsman Sep. 2004 (See astrolib/pro/tvlist.pro)
T_APER
[Previous Routine] [Next Routine] [List of Routines]NAME: T_APER PURPOSE: Driver procedure (for APER) to compute concentric aperture photometry. EXPLANATION: Data is read from and written to disk FITS ASCII tables. Part of the IDL-DAOPHOT photometry sequence CALLING SEQUENCE: T_APER, image, fitsfile, [ apr, skyrad, badpix, PRINT=, NEWTABLE=, /EXACT, /SILENT, SETSKYVAL = ] INPUTS: IMAGE - input data array FITSFILE - disk FITS ASCII table name (from T_FIND). Must contain the keywords 'X' and 'Y' giving the centroid of the source positions in FORTRAN (first pixel is 1) convention. An extension of .fit is assumed if not supplied. OPTIONAL INPUTS: User will be prompted for the following parameters if not supplied. 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 pixel (Default [-32765,32767]) OPTIONAL KEYWORDS INPUTS: /EXACT - If this keyword is set, then intersection of the circular aperture is computed exactly (and slowly) rather than using an approximation. See APER for more info. /PRINT - if set and non-zero then NSTAR will also write its results to a file aper.prt. One can specify a different output file name by setting PRINT = 'filename'. /SILENT - If this keyword is set and non-zero, then APER will not display photometry results at the screen, and the results will be automatically incorporated in the FITS table without prompting the user NEWTABLE - Name of output disk FITS ASCII table, scalar string. If not supplied, then the input FITSFILE will be updated with the aperture photometry results. 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. PROMPTS: T_APER requires the number of photons per analog digital unit (PHPADU), so that it can compute Poisson noise statistics to assign photometry errors. It first tries to find the PHPADU keyword in the original image header, and if not found will look for the GAIN, CCDGAIN and finally ATODGAIN keywords. If still not found, T_APER will prompt the user for this value. PROCEDURES: APER, FTADDCOL, FTGET(), FTINFO, FTPUT, READFITS(), SXADDPAR, SXPAR(), WRITEFITS REVISON HISTORY: Written W. Landsman ST Systems Co. May 1988 Store results as flux or magnitude August 1988 Added SILENT keyword W. Landsman Sep. 1991 Changed ERR SKY to ERR_SKY W. Landsman March 1996 Replace TEXTOUT keyword with PRINT keyword W. Landsman May 1996 Check CCDGAIN or ATODGAIN keywords to find phpadu W. Landsman May 1997 Converted to IDL V5.0 W. Landsman September 1997 Updated for new FTINFO calling sequence W. Landsman May 2000 Added /EXACT keyword W. Landsman June 2000(See astrolib/pro/t_aper.pro)
T_FIND
[Previous Routine] [Next Routine] [List of Routines]NAME: T_FIND PURPOSE: Driver procedure (for FIND) to locate stars in an image. EXPLANATION: Finds positive brightness perturbations (i.e stars) in a 2 dimensional image. Output is to a FITS ASCII table. CALLING SEQUENCE: T_FIND, image, im_hdr, [ fitsfile, hmin, fwhm, sharplim, roundlim, PRINT = , /SILENT ] INPUTS: image - 2 dimensional image array (integer or real) for which one wishes to identify the stars present im_hdr - FITS header associated with image array OPTIONAL INPUTS: T_FIND will prompt for these parameters if not supplied fitsfile - scalar string specifying the name of the output FITS ASCII table file fwhm - FWHM to be used in the convolving filter hmin - Threshold intensity for a point source - should generally be 3 or 4 sigma above background level sharplim - 2 element vector giving low and high Limit for sharpness statistic (Default: [0.2,1.0] ) roundlim - 2 element vector giving low and high Limit for roundness statistic (Default: [-1.0,1.0] ) OPTIONAL INPUT KEYWORDS: /PRINT - if set and non-zero then NSTAR will also write its results to a file find.prt. One can specify the output file name by setting PRINT = 'filename'. /SILENT - If this keyword is set and non-zero, then FIND will work silently, and not display each star found OUTPUTS: None PROCEDURES CALLED: CHECK_FITS, FDECOMP, FIND, FTADDCOL, FTCREATE, SXADDHIST, SXADDPAR, SXDELPAR, SXPAR(), WRITEFITS REVISION HISTORY: Written W. Landsman, STX May, 1988 Added phpadu, J. Hill, STX, October, 1990 New calling syntax output to disk FITS table, W. Landsman May 1996 Work with more than 32767 stars W. Landsman August 1997 Converted to IDL V5.0 W. Landsman September 1997 Remove obsolete !ERR system variable W. Landsman May 2000(See astrolib/pro/t_find.pro)
T_GETPSF
[Previous Routine] [Next Routine] [List of Routines]NAME: T_GETPSF PURPOSE: Driver procedure (for GETPSF) to generate a PSF from isolate stars. EXPLANATION: Generates a point-spread function from one or more isolated stars. List of stars is read from the FITS ASCII table output of T_APER. PSF is represented as a sum of a Gaussian plus residuals. Ouput residuals are written to a FITS image file. CALLING SEQUENCE: T_GETPSF, image, fitsfile, [ idpsf, psfrad, fitrad, psfname, /DEBUG, NEWTABLE =] INPUTS: IMAGE - image array FITSFILE - scalar string giving name of disk FITS ASCII table. Must contain the keywords 'X','Y' (from T_FIND) and 'AP1_MAG','SKY' (from T_APER). OPTIONAL INPUTS: IDPSF - vector of stellar ID indices indicating which stars are to be used to create the PSF. Not that the PSF star should be specified *not* by its STAR_ID value, but rather by the its row number (starting with 0) in the FITS table PSFRAD - the radius for which the PSF will be defined FITRAD - fitting radius, always smaller than PSFRAD PSFNAME - name of FITS image file to contain PSF residuals, scalar string GETPSF will prompt for all the above values if not supplied. OPTIONAL KEYWORD INPUT NEWTABLE - scalar string specifying the name of the output FITS ASCII table. If not supplied, then the input table is updated with the keyword PSF_CODE, specifying which stars were used for the PSF. DEBUG - if this keyword is set and non-zero, then the result of each fitting iteration will be displayed. PROMPTS: T_GETPSF will prompt for the readout noise (in data numbers), and the gain (in photons or electrons per data number) so that pixels can be weighted during the PSF fit. To avoid the prompt, add the keywords RONOIS and PHPADU to the FITS ASCII table header. PROCEDURES USED: FTADDCOL, FTGET(), FTPUT, GETPSF, READFITS(), SXADDHIST, SXADDPAR, SXPAR(), WRITEFITS, ZPARCHECK REVISION HISTORY: Written W. Landsman STX May, 1988 Update PSF_CODE to indicate PSF stars in order used, W. Landsman Mar 96 I/O to FITS ASCII disk files W. Landsman May 96 Converted to IDL V5.0 W. Landsman September 1997 Update for new FTINFO call W. Landsman May 2000(See astrolib/pro/t_getpsf.pro)
T_GROUP
[Previous Routine] [Next Routine] [List of Routines]NAME: T_GROUP PURPOSE: Driver procedure (for GROUP) to place stars in non-overlapping groups. EXPLANATION: This procedure is part of the DAOPHOT sequence that places star positions with non-overlapping PSFs into distinct groups Input and output are to FITS ASCII tables CALLING SEQUENCE: T_GROUP, fitsfile, [ rmax, XPAR = , YPAR = , NEWTABLE = ] INPUTS: FITSFILE - Name of disk FITS ASCII table containing the X,Y positions in FITS (FORTRAN) convention (first pixel is 1,1) OPTIONAL INPUTS: rmax - maximum allowable distance between stars in a single group OPTIONAL INPUT KEYWORDS: XPAR, YPAR - scalar strings giving the field name in the output table containing the X and Y coordinates. If not supplied, then the fields 'X' and 'Y' are read. NEWTABLE - scalar giving name of output disk FITS ASCII table. If not supplied, PROCEDURES: FTADDCOL, FTGET(), FTINFO, FTPUT, GROUP, READFITS(), SXADDHIST, SXADDHIST, WRITEFITS REVISION HISTORY: Written, W. Landsman STX Co. May, 1996 Converted to IDL V5.0 W. Landsman September 1997 Updated for new FTINFO call W. Landsman May 2000(See astrolib/pro/t_group.pro)
T_NSTAR
[Previous Routine] [Next Routine] [List of Routines]NAME: T_NSTAR PURPOSE: Driver procedure (for NSTAR) for simultaneous PSF fitting. EXPLANATION: Input and output are to disk FITS ASCII tables. CALLING SEQUENCE: T_NSTAR, image, fitsfile, [psfname, groupsel, /SILENT, /PRINT NEWTABLE = , /VARSKY ] INPUTS: IMAGE - 2-d image array FITSFILE - scalar string giving name of disk FITS ASCII table. Must contain the keywords 'X','Y' (from T_FIND) 'AP1_MAG','SKY' (from T_APER) and 'GROUP_ID' (from T_GROUP). This table will be updated with the results of T_NSTAR, unless the keyword NEWTABLE is supplied. OPTIONAL INPUTS: PSFNAME - Name of the FITS file created by T_GETPSF containing PSF residuals, scalar string GROUPSEL - Scalar or vector listing the groups to process. For example, to process stars in groups 2 and 5 set GROUPSEL = [2,5]. If omitted, or set equal to -1, then NSTAR will process all groups. OPTIONAL KEYWORD INPUTS: VARSKY - If this keyword is set and non-zero, then the mean sky level in each group of stars, will be fit along with the brightness and positions. /SILENT - if set and non-zero, then NSTAR will not display its results at the terminal /PRINT - if set and non-zero then NSTAR will also write its results to a file NSTAR.PRT. One can specify the output file name by setting PRINT = 'filename'. NEWTABLE - Name of output disk FITS ASCII table to contain the results of NSTAR. If not supplied, then the input FITSFILE will be updated. DEBUG - if this keyword is set and non-zero, then the result of each fitting iteration will be displayed. PROCEDURES CALLED: FTADDCAL, FTINFO, FTGET(), FTPUT, NSTAR, SXADDHIST, SXADDPAR, SXPAR(), READFITS(), WRITEFITS REVISION HISTORY: Written W. Landsman STX Co. May, 1988 Check for CCDGAIN, ATODGAIN keywords to get PHPADU W. Landsman May 1997 Fixed typo preventing compilation, groupsel parameter W.L. July 1997 Converted to IDL V5.0 W. Landsman September 1997 Update for new FTINFO call W. Landsman May 2000(See astrolib/pro/t_nstar.pro)
T_SUBSTAR
[Previous Routine] [Next Routine] [List of Routines]NAME: T_SUBSTAR PURPOSE: Driver procedure (for SUBSTAR) to subtract scaled PSF values EXPLANATION: Computes residuals of the PSF fitting program CALLING SEQUENCE: T_SUBSTAR, image, fitsfile, id,[ psfname, /VERBOSE, /NOPSF ] INPUT-OUTPUT: IMAGE - On input, IMAGE is the original image array. A scaled PSF will be subtracted from IMAGE at specified star positions. Make a copy of IMAGE before calling SUBSTAR, if you want to keep a copy of the unsubtracted image array INPUTS: FITSFILE - scalar string giving the name of the disk FITS ASCII produced as an output from T_NSTAR. OPTIONAL INPUTS: ID - Index vector indicating which stars are to be subtracted. If omitted, (or set equal to -1), then stars will be subtracted at all positions specified by the X and Y vectors. (IDL convention - zero-based subscripts) PSFNAME - Name of the FITS file containing the PSF residuals, as generated by GETPSF. SUBSTAR will prompt for this parameter if not supplied. OPTIONAL INPUT KEYWORD: /VERBOSE - If this keyword is set and non-zero, then the value of each star number will be displayed as it is processed. /NOPSF - if this keyword is set and non-zero, then all stars will be be subtracted *except* those used to determine the PSF. An improved PSF can then be derived from the subtracted image. If NOPSF is supplied, then the ID parameter is ignored NOTES: T_SUBSTAR does not modify the input FITS table. PROCEDURES USED: FTGET(), FTINFO, READFITS(), REMOVE, SUBSTAR REVISION HISTORY: Written, R. Hill, ST Sys. Corp., 22 August 1991 Added NOPSF keyword W. Landsman March, 1996 Use FITS format for PSF resduals July, 1997 Converted to IDL V5.0 W. Landsman September 1997 Call FTINFO first to improve efficiency W. Landsman May 2000(See astrolib/pro/t_substar.pro)
UNZOOM_XY
[Previous Routine] [Next Routine] [List of Routines]NAME: UNZOOM_XY PURPOSE: Converts X, Y position on the image display to the the X,Y position on the corresponding image array. (These positions are identical only for an unroamed, unzoomed image with with pixel (0,0) of the image placed at position (0,0) on the TV.) CALLING SEQUENCE: UNZoom_XY, Xtv,Ytv,Xim,Yim, [ OFFSET =, ZOOM = ] INPUTS: XTV - Scalar or vector giving X position(s) as read on the image display (e.g. with CURSOR,XTV,YTV,/DEVICE) XTV - Scalar or vector giving Y position(s) on the image display. If only 2 parameters are supplied then XTV and YTV will be modfied on output to contain the image array coordinates. OPTIONAL KEYWORD INPUT: 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. OUTPUTS: XIM,YIM - X and Y coordinates of the image corresponding to the cursor position on the TV display. COMMON BLOCKS: If present, ZOOM_XY will use the TV and IMAGE common blocks which are defined in the MOUSSE software system (see http://archive.stsci.edu/uit/analysis.html) If the user is not using the MOUSSE software (which keeps track of the offset and zoom in each window) then the common blocks are ignored. NOTES: The integer value of a pixel is assumed to refer to the *center* of a pixel. REVISON HISTORY: Adapted from MOUSSE procedure W. Landsman March 1996 Converted to IDL V5.0 W. Landsman September 1997 Proper handling of offset option S. Ott/W. Landsman May 2000 Put back common blocks for MOUSSE compatibility September 2004(See astrolib/pro/unzoom_xy.pro)
UPDATE_DISTORT
[Previous Routine] [Next Routine] [List of Routines]NAME: UPDATE_DISTORT PURPOSE: Update SIP nonlinear distortion coefficients for a linear transformation EXPLANATION: The SIP coefficients can account for nonlinearities in the astrometry of an astronomical image. When the image is compressed or expanded these coefficients must be adjusted in a nonlinear way. CALLING SEQUENCE: UPDATE_DISTORT, distort, xcoeff, ycoeff INPUT/OUTPUT: distort - structure giving SIP coefficients. See extast.pro for description of the SIP distortion structure xcoeff - 2 element numeric vector describing the linear transformation xp = xcoeff[0]*x + xcoeff[1] xcoeff - 2 element numeric vector describing the linear transformation yp = ycoeff[0]*x + ycoeff[1] METHOD: The procedure TRANSFORM_COEFF is used to determine how the coefficients change under the linear transformation. See example of usage in hrebin.pro REVISION HISTORY: Written, December 2007 W. Landsman(See astrolib/pro/update_distort.pro)
UVBYBETA
[Previous Routine] [Next Routine] [List of Routines]NAME: UVBYBETA PURPOSE: Derive dereddened colors, metallicity, and Teff from Stromgren colors. EXPLANATION: Adapted from FORTRAN routine of same name published by T.T. Moon, Communications of University of London Observatory, No. 78. Parameters can either be input interactively (with /PROMPT keyword) or supplied directly. CALLING SEQUENCE: uvbybeta, /PROMPT ;Prompt for all parameters uvbybeta,by,m1,c1,Hbeta,n ;Supply inputs, print outputs uvbybeta, by, m1, c1, Hbeta, n, Te, Mv, Eby, delm0, radius, [ TEXTOUT=, Eby_in =, Name = ] INPUTS: by - Stromgren b-y color, scalar or vector m1 - Stromgren line-blanketing parameter, scalar or vector c1 - Stromgren Balmer discontinuity parameter, scalar or vector Hbeta - H-beta line strength index. Set Hbeta to 0 if it is not known, and UVBYBETA will estimate a value based on by, m1,and c1. Hbeta is not used for stars in group 8. n - Integer (1-8), scalar or vector, giving approximate stellar classification (1) B0 - A0, classes III - V, 2.59 < Hbeta < 2.88,-0.20 < c0 < 1.00 (2) B0 - A0, class Ia , 2.52 < Hbeta < 2.59,-0.15 < c0 < 0.40 (3) B0 - A0, class Ib , 2.56 < Hbeta < 2.61,-0.10 < c0 < 0.50 (4) B0 - A0, class II , 2.58 < Hbeta < 2.63,-0.10 < c0 < 0.10 (5) A0 - A3, classes III - V, 2.87 < Hbeta < 2.93,-0.01 < (b-y)o< 0.06 (6) A3 - F0, classes III - V, 2.72 < Hbeta < 2.88, 0.05 < (b-y)o< 0.22 (7) F1 - G2, classes III - V, 2.60 < Hbeta < 2.72, 0.22 < (b-y)o< 0.39 (8) G2 - M2, classes IV _ V, 0.20 < m0 < 0.76, 0.39 < (b-y)o< 1.00 OPTIONAL INPUT KEYWORD: Eby_in - numeric scalar specifying E(b-y) color to use. If not supplied, then E(b-y) will be estimated from the Stromgren colors NAME - scalar or vector string giving name(s) of star(s). Used only when writing to disk for identification purposes. /PROMPT - if set, then uvbybeta.pro will prompt for Stromgren indicies interactively TEXTOUT - Used to determine output device. If not present, the value of the !TEXTOUT system variable is used (see TEXTOPEN) textout=1 Terminal with /MORE (if a tty) textout=2 Terminal without /MORE textout=3 uvbybeta.prt (output file) textout=4 Laser Printer textout=5 User must open file textout=7 Append to existing uvbybeta.prt file textout = filename (default extension of .prt) /PRINT - if set, then force display output information to the device specified by !TEXTOUT. By default, UVBYBETA does not display information if output variables are supplied (and TEXTOUT is not set). OPTIONAL OUTPUTS: Te - approximate effective temperature MV - absolute visible magnitude Eby - Color excess E(b-y) delm0 - metallicity index, delta m0, (may not be calculable for early B stars). radius - Stellar radius (R/R(solar)) EXAMPLE: Suppose 5 stars have the following Stromgren parameters by = [-0.001 ,0.403, 0.244, 0.216, 0.394 ] m1 = [0.105, -0.074, -0.053, 0.167, 0.186 ] c1 = [0.647, 0.215, 0.051, 0.785, 0.362] hbeta = [2.75, 2.552, 2.568, 2.743, 0 ] nn = [1,2,3,7,8] ;Processing group number Determine stellar parameters and write to a file uvbybeta.prt IDL> uvbybeta, by,m1,c1,hbeta, nn, t=3 ==> E(b-y) = 0.050 0.414 0.283 0.023 -0.025 Teff = 13060 14030 18420 7250 5760 M_V = -0.27 -6.91 -5.94 2.23 3.94 radius= 2.71 73.51 39.84 2.02 1.53 SYSTEM VARIABLES: The non-standard system variables !TEXTOUT and !TEXTUNIT will be automatically defined if they are not already present. DEFSYSV,'!TEXTOUT',1 DEFSYSV,'!TEXTUNIT',0 NOTES: (1) **This procedure underwent a major revision in January 2002 and the new calling sequence may not be compatible with the old** (NAME is now a keyword rather than a parameter.) (2) Napiwotzki et al. (1993, A&A, 268, 653) have written a FORTRAN program that updates some of the Moon (1985) calibrations. These updates are *not* included in this IDL procedure. PROCEDURES USED: DEREDD, TEXTOPEN, TEXTCLOSE REVISION HISTORY: W. Landsman IDL coding February, 1988 Keyword textout added, J. Isensee, July, 1990 Made some constants floating point. W. Landsman April, 1994 Converted to IDL V5.0 W. Landsman September 1997 Added Eby_in, /PROMPT keywords, make NAME a keyword and not a parameter W. Landsman January 2002(See astrolib/pro/uvbybeta.pro)
VACTOAIR
[Previous Routine] [Next Routine] [List of Routines]NAME: VACTOAIR PURPOSE: Convert vacuum wavelengths to air wavelengths EXPLANATION: Corrects for the index of refraction of air under standard conditions. Wavelength values below 2000 A will not be altered. Accurate to about 10 m/s. CALLING SEQUENCE: VACTOAIR, WAVE_VAC, [WAVE_AIR] INPUT/OUTPUT: WAVE_VAC - Vacuum Wavelength in Angstroms, scalar or vector If the second parameter is not supplied, then this will be updated on output to contain double precision air wavelengths. OPTIONAL OUTPUT: WAVE_AIR - Air wavelength in Angstroms, same number of elements as WAVE_VAC, double precision EXAMPLE: If the vacuum wavelength is W = 2000, then IDL> VACTOAIR, W yields an air wavelength of W = 1999.353 Angstroms METHOD: Formula from Ciddor 1996 Applied Optics , 35, 1566 REVISION HISTORY Written, D. Lindler 1982 Documentation W. Landsman Feb. 1989 Use Ciddor (1996) formula for better accuracy in the infrared Added optional output vector, W Landsman Mar 2011(See astrolib/pro/vactoair.pro)
VALID_NUM()
[Previous Routine] [Next Routine] [List of Routines]NAME: VALID_NUM() PURPOSE: Check if a string is a valid number representation. EXPLANATION: The input string is parsed for characters that may possibly form a valid number. It is more robust than simply checking for an IDL conversion error because that allows strings such as '22.3qwert' to be returned as the valid number 22.3 This function had a major rewrite in August 2008 to use STREGEX and allow vector input. It should be backwards compatible. CALLING SEQUENCE: IDL> status = valid_num(string [,value] [,/integer]) INPUTS: string - the string to be tested, scalar or array RETURNS status - byte scalar or array, same size as the input string set to 1 where the string is a valid number, 0 for invalid OPTIONAL OUTPUT: value - The value the string decodes to, same size as input string. This will be returned as a double precision number unless /INTEGER is present, in which case a long integer is returned. OPTIONAL INPUT KEYWORD: /INTEGER - if present code checks specifically for an integer. EXAMPLES: (1) IDL> print,valid_num(3.2,/integer) --> 0 ;Since 3.2 is not an integer (2) IDL> str =['-0.03','2.3g', '3.2e12'] IDL> test = valid_num(str,val) test = [1,0,1] & val = [-0.030000000 ,NaN ,3.2000000e+12] REVISION HISTORY: Version 1, C D Pike, RAL, 24-May-93 Version 2, William Thompson, GSFC, 14 October 1994 Added optional output parameter VALUE to allow VALID_NUM to replace STRNUMBER in FITS routines. Version 3 Wayne Landsman rewrite to use STREGEX, vectorize Version 4 W.L. (fix from C. Markwardt) Better Stregex expression, was missing numbers like '134.' before Jan 1 2010(See astrolib/pro/valid_num.pro)
VECT
[Previous Routine] [Next Routine] [List of Routines]NAME: VECT PURPOSE: Print a set of numbers as a string with delimiters included EXPLANATION: This function returns the given vector in parenthesized coordinates as in the form (X,Y). No limit on the number of dimensions. Also note that the vector does not need to be numbers. It may also be a string vector. e.g. ['X','Y'] CALLING SEQEUNCE: tmp = VECT( vctr, [ form, FORMAT = , DELIM = ] ) INPUT: VCTR The vector to be displayed e.g. [56,44] OPTIONAL KEYWORD INPUT: FORMAT This KEYWORD allows the specification of a format for the elements. e.g.: VECT([2,3],format='(f7.1)') gives '(2.0,3.0)' DELIM This KEYWORD specifies the delimeter. The default is ',' but other useful examples might be ', ' or ':' OPTIONAL INPUT FORM This parameter may be used instead of the keyword FORMAT OUTPUT: tmp A returned string of the parenthesized vector Other Procedures/Functions Called: STRN HISTORY: 03-JUL-90 Version 1 written by Eric W. Deutsch 24-AUG-91 Format='' keyword added (E. Deutsch) 29-AUG-91 FORM parameter added (E. Deutsch) Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/vect.pro)
VSYM
[Previous Routine] [Next Routine] [List of Routines]NAME: VSYM PURPOSE: Create "Mongo"-like polygonal plot symbols EXPLANATION: This procedure generates a subset of Mongo-like plot symbols. The symbols are the rotationally symmetric ones that have a specified number of vertices and are either open or filled. (The half-filled symbols are not included.) After defining the plot symbol with VSYM, make the call to PLOT (or PLOTS or OPLOT) with PSYM=8. CATEGORY: Graphics CALLING SEQUENCE: VSYM, Nvert INPUT POSITIONAL PARAMETERS: Nvert: Number of vertices in plot symbol. Maximum value used is 24. INPUT KEYWORD PARAMETERS: STAR: Set this flag to get a star. E.g., vsym, 5,/star gets you a pentagram. SKELETON: Set this flag to get an asterisk-like symbol, where the center is connected to each vertex. E.g., vsym, 4, /skel gets you an X. POLYGON: Set this flag to get a regular polygon. This is the default symbol type. FILL: Set this flag to get filled symbol. Default=open ROT: Rotation of symbol about center, in degrees. E.g., vsym, 4, rot=45 gets you a diamond, whereas vsym, 4 gets you a square. THICK: Line thickness of symbol. Default=!P.thick MODIFICATION HISTORY: Written by: R. S. Hill, RITSS, 2 Oct 98(See astrolib/pro/vsym.pro)
WCSSPH2XY
[Previous Routine] [Next Routine] [List of Routines]NAME: WCSSPH2XY PURPOSE: Convert spherical coordinates to x and y (map) angular coordinates EXPLANATION: Convert spherical (longitude and latitude -- sky) coordinates to x and y (map) angular coordinates. This procedure is the inverse of WCSXY2SPH. See WCS_DEMO for example of use. This is a lower level procedure -- given a FITS header, the user will usually use ADXY which will then call WCSSPH2XY with the appropriate parameters. CATEGORY: Mapping and Auxiliary FITS Routine CALLING SEQUENCE: wcssph2xy, longitude, latitude, x, y, [ map_type , CTYPE = , FACE =,PV2= , CRVAL = , CRXY = , LONGPOLE = , LATPOLE = , NORTH_OFFSET =, SOUTH_OFFSET =, BADINDEX =] INPUT PARAMETERS: longitude - longitude of data, scalar or vector, in degrees latitude - latitude of data, same number of elements as longitude, in degrees map_type - optional positional parameter, numeric scalar (0-26) corresponding to a particular map projection. This is not a FITS standard, it is simply put in to allow function similar to that of less general map projection procedures (eg AITOFF). The following list gives the map projection types and their respective numbers. FITS Number Name Comments code code ---- ------ ----------------------- ----------------------------------- DEF 0 Default = Cartesian AZP 1 Zenithal perspective PV2_1 required TAN 2 Gnomic AZP w/ mu = 0 SIN 3 Orthographic PV2_1,PV2_2 optional STG 4 Stereographic AZP w/ mu = 1 ARC 5 Zenithal Equidistant ZPN 6 Zenithal polynomial PV2_0, PV2_1....PV2_20 possible ZEA 7 Zenithal equal area AIR 8 Airy PV2_1 required CYP 9 Cylindrical perspective PV2_1 and PV2_2 required CAR 10 Cartesian MER 11 Mercator CEA 12 Cylindrical equal area PV2_1 required COP 13 Conical perspective PV2_1 and PV2_2 required COD 14 Conical equidistant PV2_1 and PV2_2 required COE 15 Conical equal area PV2_1 and PV2_2 required COO 16 Conical orthomorphic PV2_1 and PV2_2 required BON 17 Bonne's equal area PV2_1 required PCO 18 Polyconic SFL 19 Sanson-Flamsteed PAR 20 Parabolic AIT 21 Hammer-Aitoff MOL 22 Mollweide CSC 23 Cobe Quadrilateralized convergence of inverse is poor Spherical Cube QSC 24 Quadrilateralized Spherical Cube TSC 25 Tangential Spherical Cube SZP 26 Slant Zenithal Projection PV2_1,PV2_2, PV2_3 optional HPX 27 HealPix HCT 28 HealCart (Cartesian approximation of Healpix) OPTIONAL INPUT KEYWORD PARAMETERS: CTYPE - One, two, or three element vector containing 8 character strings corresponding to the CTYPE1, CTYPE2, and CTYPE3 FITS keywords: CTYPE[0] - first four characters specify standard system ('RA--','GLON' or 'ELON' for right ascension, Galactic longitude or ecliptic longitude respectively), second four letters specify the type of map projection (eg '-AIT' for Aitoff projection) CTYPE[1] - first four characters specify standard system ('DEC-','GLAT' or 'ELAT' for declination, galactic latitude or ecliptic latitude respectively; these must match the appropriate system of ctype1), second four letters of ctype2 must match second four letters of ctype1. CTYPE[2] - if present must be the 8 character string,'CUBEFACE', only used for spherical cube projections to identify an axis as containing the face on which each x and y pair of coordinates lie. PV2 - Vector of projection parameter associated with latitude axis PV2 will have up to 21 elements for the ZPN projection, up to 3 for the SIN projection and no more than 2 for any other projection. The first element corresponds to PV2_1, the second to PV2_2, etc. CRVAL - 2 element vector containing standard system coordinates (the longitude and latitude) of the reference point CRXY - 2 element vector giving the x and y coordinates of the reference point, if this is not set the offset is [0,0] This is not a FITS standard -- it is similar to CRPIX but in angular X,Y coordinates (degrees) rather than pixel coordinates LATPOLE - native latitude of the standard system's North Pole LONGPOLE - native longitude of standard system's North Pole, default is 180 degrees for Zenithal systems NORTH_OFFSET - offset (radians) added to input points near north pole. SOUTH_OFFSET - offset (radians) added to input points near south pole. BADINDEX - vector, list of transformed points too close to poles. OUTPUT PARAMETERS: x - x coordinate of data, same number of elements as longitude, in degrees; if CRXY is set, then x will be returned offset by crxy(0). NOTE: x in all map projections increases to the left, not the right. y - y coordinate of data, same number of elements as longitude, in degrees; if CRXY is set, y will be returned offset by crxy[1] bad - vector returning index to transformed points close to pole. OPTIONAL OUTPUT KEYWORD PARAMETERS: FACE - a output variable used for spherical cube projections to designate the face of the cube on which the x and y coordinates lie. Will contain the same number of elements as X and Y. Must contain at least 1 arbitrary element on input If FACE is NOT defined on input, it is assumed that the spherical cube projection is laid out over the whole sky in the "sideways T" configuration. NOTES: The conventions followed here are described in more detail in "Representations of Celestial Coordinates in FITS" by Calabretta and Greisen (2002, A&A, 395, 1077; also see http://fits.gsfc.nasa.gov/fits_wcs.html). The general scheme outlined in that article is to first use WCS_ROTATE to convert coordinates in one of three standard systems (celestial, galactic, or ecliptic) into a "native system" of latitude and longitude. The latitude and longitude are then converted into x and y coordinates which depend on the map projection which is performed. The rotation from standard to native coordinates can be skipped if one so desires. This procedure necessitates two basic sections. The first converts "standard" coordinates to "native" coordinates while the second converts "native" coordinates to x and y coordinates. The first section is simply a call to WCS_ROTATE, while the second contains the guts of the code in which all of the map projection is done. This procedure can be called in a form similar to AITOFF, EQPOLE, or QDCB by calling wcssph2xy with a fifth parameter specifying the map projection by number and by not using any of the keywords related to the map projection type (e.g. CTYPE). PROCEDURE: The first task of the procedure is to do general error-checking to make sure the procedure was called correctly and none of the parameters or keywords conflict. This is particularly important because the procedure can be called in two ways (either using FITS-type keywords or using a number corresponding to a map projection type). All variables are converted into double precision values and angular measurements are converted from degrees into radians. If necessary, longitude values are converted into the range -pi to pi. Any latitude points close to the of the poles are mapped to a specific latitude of from the pole so that the map transformations become completely invertible. The magnitude of this correction is given by the keywords NORTH_OFFSET and SOUTH_OFFSET and a list of affected points is optionally returned in the "badindex" output parameter. The next task of the procedure is to convert the "standard" coordinates to "native" coordinates by rotating the coordinate system. This rotation is performed by the procedure WCS_ROTATE and is governed by the keywords CRVAL and LONGPOLE. The final task of the WCSSPH2XY is to take "native" latitude and longitude coordinates and convert them into x and y coordinates. Any map specific error-checking is done at this time. All of the equations were obtained from "Representations of Celestial Coordinates in FITS" and cases needing special attention are handled appropriately (see the comments with individual map projections for more information on special cases). Note that a further transformation (using the CD matrix) is required to convert the (x,y) coordinates to pixel coordinates. COMMON BLOCKS: none PROCEDURES CALLED: WCS_ROTATE AUTHOR: Rick Balsano MODIFICATIONS/REVISION LEVEL: 1.1 8/31/93 2.3 9/15/93 W. Landsman (HSTX) Update quad cube coords, vectorize keywords 2.4 12/29/93 I. Freedman (HSTX) Eliminated LU decomposition 2.5 1/5/93 I. Freedman (HSTX) Offset keywords / bad point index 2.6 Dec 94 Compute pole for transformations where the reference pixel is at the native origin W. Landsman (HSTX) 2.7 May 95 Change internal variable BETA for V4.0 compatibility 2.8 June 95 Change loop indices from integer to long 2.9 3/18/96 Change FACE usage for cube projections to match WCSLIB C/FORTRAN software library. 2.10 02/18/99 Fixed implementation of ARC algorithm 2.11 June 2003 Update conic projections, add LATPOLE keyword 2.12 Aug 2003, N.Rich - Fix pre-V5.5 bug from previous update 2.13 Sep 2003, W. Landsman CTYPE keywords need not be 8 characters 2.14 Jan 2004, W. Landsman don't modify scalars, fix PARabolic code 2.15 Feb 2004, W. Landsman Fix AZP and AIR algorithms 3.0 May 2004 W. Landsman Support extended SIN (=NCP), slant zenithal (SZP), and zenithal polynomail (ZPN) projections, use PV2 keyword vector instead of PROJP1, PROJP2 3.1 Jul 2005 W.Landsman/C. Markwardt Set unprojectable points in tangent projection to NaN 3.1.1 Jul 2005 Fixed 3.1 mod to work for scalars 3.2 Dec 2005 Fixed Airy projection for latitude centered at 90 deg 3.3 Aug 2007 R. Munoz, W.Landsman Correct treatment of PV1_2 and PV2_2 parameters 3.4 Oct 2007 Sergey Koposov Support HEALPIX projection 3.4.1 June 2009 Check for range of validity of ZPN polynomial W.L. 3.5 May 2012 Benjamin Alan Weaver, Add nonstandard HEALCART projection, Allow map_index to be > 25(See astrolib/pro/wcssph2xy.pro)
WCSXY2SPH
[Previous Routine] [Next Routine] [List of Routines]NAME: WCSXY2SPH PURPOSE: Convert x and y (map) coordinates to spherical coordinates EXPLANATION: To convert x and y (map) coordinates to spherical (longitude and latitude or sky) coordinates. This procedure is the inverse of WCSSPH2XY. This is a lower level procedure -- given a FITS header, the user will usually use XYAD which will then call WCSXY2SPH with the appropriate parameters. CATEGORY: Mapping and Auxilary FITS Routine CALLING SEQUENCE: wcsxy2sph, x, y, longitude, latitude, [map_type], [ CTYPE = ,$ FACE = ,PV2 = ,CRVAL =, CRXY =, LONGPOLE=, LATPOLE=] INPUT PARAMETERS: x - x coordinate of data, scalar or vector, in degrees, NOTE: x increases to the left, not the right y - y coordinate of data, same number of elements as x, in degrees map_type - optional positional parameter, scalar corresponding to a particular map projection. This is not a FITS standard, it is simply put in to allow function similar to that of less general map projection procedures (eg AITOFF). The following list gives the map projection types and their respective numbers. FITS Number Name Comments code code ---- ------ ----------------------- ----------------------------------- DEF 0 Default = Cartesian AZP 1 Zenithal perspective pv2_1 required TAN 2 Gnomic AZP w/ pv2_1 = 0 SIN 3 Orthographic pv2_1, pv2_2 optional STG 4 Stereographic AZP w/ pv2_1 = 1 ARC 5 Zenithal Equidistant ZPN 6 Zenithal polynomial PV2_0, PV2_1....PV2_20 possible ZEA 7 Zenithal equal area AIR 8 Airy pv2_1 required CYP 9 Cylindrical perspective pv2_1 and pv2_2 required CAR 10 Cartesian MER 11 Mercator CEA 12 Cylindrical equal area pv2_1 required COP 13 Conical perspective pv2_1 and pv2_2 required COD 14 Conical equidistant pv2_1 and pv2_2 required COE 15 Conical equal area pv2_1 and pv2_2 required COO 16 Conical orthomorphic pv2_1 and pv2_2 required BON 17 Bonne's equal area pv2_1 required PCO 18 Polyconic SFL 19 Sanson-Flamsteed PAR 20 Parabolic AIT 21 Hammer-Aitoff MOL 22 Mollweide CSC 23 Cobe Quadrilateralized inverse converges poorly Spherical Cube QCS 24 Quadrilateralized Spherical Cube TSC 25 Tangential Spherical Cube SZP 26 Slant Zenithal perspective PV2_1,PV2_2, PV2_3 optional HPX 27 HealPix HCT 28 HealCart (Cartesian approximation of Healpix) OPTIONAL KEYWORD PARAMETERS: CTYPE - One, two, or three element vector containing 8 character strings corresponding to the CTYPE1, CTYPE2, and CTYPE3 FITS keywords: CTYPE[0] - first four characters specify standard system ('RA--','GLON' or 'ELON' for right ascension, galactic longitude or ecliptic longitude respectively), second four letters specify the type of map projection (eg '-AIT' for Aitoff projection) CTYPE[1] - first four characters specify standard system ('DEC-','GLAT' or 'ELAT' for declination, galactic latitude or ecliptic latitude respectively; these must match the appropriate system of ctype1), second four letters of ctype2 must match second four letters of ctype1. CTYPE[2] - if present must be the 8 character string,'CUBEFACE', only used for spherical cube projections to identify an axis as containing the face on which each x and y pair of coordinates lie. FACE - a input variable used for spherical cube projections to designate the face of the cube on which the x and y coordinates lie. Must contain the same number of elements as X and Y. CRVAL - 2 element vector containing standard system coordinates (the longitude and latitude) of the reference point CRXY - 2 element vector giving the x and y coordinates of the reference point, if this is not set the offset of the x coordinate is assumed to be 0. LATPOLE - native latitude of the standard system's North Pole LONGPOLE - native longitude of standard system's North Pole, default is 180 degrees, numeric scalar PV2 - Vector of projection parameter associated with latitude axis PV2 will have up to 21 elements for the ZPN projection, up to 3 for the SIN projection and no more than 2 for any other projection. The first element corresponds to PV2_1, the second to PV2_2, etc. OUTPUT PARAMETERS: longitude - longitude of data, same number of elements as x, in degrees latitude - latitude of data, same number of elements as x, in degrees Longitude and latitude will be set to NaN, wherever elements of X,Y have no corresponding longitude, latitude values. NOTES: The conventions followed here are described in more detail in the paper "Representations of Celestial Coordinates in FITS" by Calabretta & Greisen (2002, A&A, 395, 1077, also see http://fits.gsfc.nasa.gov/fits_wcs.html). The general scheme outlined in that article is to convert x and y coordinates into a "native" longitude and latitude and then rotate the system into one of three generally recognized systems (celestial, galactic or ecliptic). This procedure necessitates two basic sections. The first converts x and y coordinates to "native" coordinates while the second converts "native" to "standard" coordinates. The first section contains the guts of the code in which all of the map projection is done. The second step is performed by WCS_ROTATE and only involves rotation of coordinate systems. WCSXY2SPH can be called in a form similar to AITOFF, EQPOLE, or QDCB by calling wcsxy2sph with a fifth parameter specifying the map projection by number and by not using any of the keywords related to the map projection type (eg ctype1 and ctyp2). PROCEDURE: The first task of the procedure is to do general error-checking to make sure the procedure was called correctly and none of the parameters or keywords conflict. This is particularly important because the procedure can be called in two ways (either using FITS-type keywords or using a number corresponding a map projection type). All variables are converted into double precision values. The second task of the procedure is to take x and y coordinates and convert them into "native" latitude and longitude coordinates. Map-specific error-checking is done at this time. All of the equations were obtained from "Representations of Celestial Coordinates in FITS" and cases needing special attention are handled appropriately (see the comments with individual map projections for more information on special cases). WCS_ROTATE is then called to convert the "native" coordinates to "standard" coordinates by rotating the coordinate system. This rotation is governed by the keywords CRVAL, and LONGPOLE. The transformation is a straightforward application of euler angles. Finally, longitude values are converted into the range from 0 to 360 degrees. COMMON BLOCKS: none PROCEDURES CALLED: WCS_ROTATE AUTHOR: Rick Balsano MODIFICATIONS/REVISION LEVEL: 1.1 8/31/93 1.2 9/12/93 W. Landsman Vectorized CRXY, CRVAL, CTYPE 1.3 29/12/93 I. Freedman Eliminated LU decomposition 1.4 22/09/94 W. Landsman If scalar input, then scalar output 1.5 02/03/05 W. Landsman Change variable name BETA for V4.0 compatibility 1.6 06/07/05 W. Landsman Change loop index from integer to long 1.7 02/18/99 W. Landsman Fixed implementation of ARC algorithm 1.8 June 2003 W. Landsman Update conic projections, add LATPOLE keyword 1.81 Sep 2003 W. Landsman Avoid divide by zero 1.82 Sep 2003 W. Landsman CTYPE keywords need not be 8 characters 1.83 Sep 2003 W. Landsman Preserve input array sizes 1.9 Jan 2004 W. Landsman don't modify scalars, fix PARabolic code 2.0 Feb 2004 W. Landsman Fix AIR and AZP projections 2.1 Feb 2004 W. Landsman Fix tangent projection for matrix input 3.0 May 2004 W. Landsman Support extended SIN (=NCP), slant zenithal (SZP), and zenithal polynomial (ZPN) projections, use PV2 keyword vector instead of PROJP1, PROJP2 3.1 May 2004 W. Landsman/J. Ballet Handle NaN values, flag invalid output for AITOFF projection 3.1.1 Dec 2005 W. Landsman/W. Thompson Fixed problem with Airy projection centered on 90 degree latitude 3.1.2 May 2006 W. Landsman/Y.Sato Fix problem selecting the correct root for the ZPN projection 3.2 Aug 2007 W. Landsman Correct treatment of PVi_j parameters 3.3 Oct 2007 Sergey Koposov Support HEALPIX projection 3.4 May 2012 Benjamin Alan Weaver, Add nonstandard HEALCART projection, Allow map_index to be > 25(See astrolib/pro/wcsxy2sph.pro)
WCS_DEMO
[Previous Routine] [Next Routine] [List of Routines]NAME: WCS_DEMO PURPOSE: Demonstrate the basic capabilities of procedures WCSSPH2XY & WCSXY2SPH CATEGORY: Mapping and Auxilary FITS Demo Routine CALLING SEQUENCE: .run wcs_demo: compiles wcs_demo and the supporting demo routines wcs_demo: run the demo INPUT PARAMETERS: none OUTPUT PARAMETERS: none PROCEDURE: This is a demo program which is meant to call the routines wcssph2xy.pro and wcsxy2sph.pro. Since the purpose of this routine is both to show what the routines can do and what the user has to do, a file is created with all of the commands needed to complete the desired operation. Wcs_demo actually executes this command file, so the user can exactly duplicate the results by simply re-executing this file. Also, this allows a user to edit an already existing file which calls wcssph2xy.pro and wcsxy2sph.pro properly and extend the file's usefulness. This demo program allows several possible tests. The first option is to simply draw a grid of evenly spaced latitude and longitude lines in a particular map transformation. Another possibility is to do a full loop, creating a Cartesian grid of latitude and longitude lines and calling wcssph2xy.pro to convert them to a particular map. Then, wcsxy2sph.pro is called to invert the process and the difference between the original and final latitudes and longitudes can be plotted. This allows one to assess the level of the numerical errors introduced by the mapping routines. A third possible option is to look at some of the map transformations and include rotations of the reference points so that a different perspective is given. COMMON BLOCKS: none PROCEDURES CALLED: SPHDIST(), WCSXY2SPH, WCSSPH2XY COPYRIGHT NOTICE: Copyright 1991, The Regents of the University of California. This software was produced under U.S. Government contract (W-7405-ENG-36) by Los Alamos National Laboratory, which is operated by the University of California for the U.S. Department of Energy. The U.S. Government is licensed to use, reproduce, and distribute this software. Neither the Government nor the University makes any warranty, express or implied, or assumes any liability or responsibility for the use of this software. AUTHOR: Rick Balsano MODIFICATIONS/REVISION LEVEL: 1.1 8/31/93 1.2 3/19/96 - J. Bloch - LANL - Made compatible with wcslib-2.2 by Calabretta. Converted to IDL V5.0 W. Landsman September 1997 Updated for conical projections W. Landsman July 2003(See astrolib/pro/wcs_demo.pro)
WCS_GETPOLE
[Previous Routine] [Next Routine] [List of Routines]NAME: WCS_GETPOLE PURPOSE: Compute the coordinates of the native pole for a non-polar projection EXPLANATION: For non-polar (cylindrical or conic) projections, the native pole is not at the reference point, and WCS_GETPOLE is used to determine the position of the native pole. See section 2.4 of the paper "Representation of Celestial Coordinates in FITS" by Calabretta Greisen (2002, A&A, 395, 1077, also available at http://fits.gsfc.nasa.gov/fits_wcs.html Called by WCS_ROTATE CALLING SEQUENCE: WCS_GETPOLE, crval, lonpole, theta0, alpha_p, delta_p, LATPOLE= ] INPUT PARAMETERS: crval - 2 element vector containing standard system coordinates (the longitude and latitude) of the reference point in degrees lonpole - native longitude of the celestial North Pole (degrees) theta0 - native latitude of the fiducial point OUTPUT PARAMETERS: alpha_p, delta_p - celestial longitude and latitude of the native pole (Radians) OPTIONAL KEYWORD INPUT PARAMETERS: LATPOLE - native latitude of the celestial North Pole (degrees) REVISION HISTORY: Written W. Landsman June, 2003 Fix calculation when theta0 is not 0 or 90 February 2004 E. Hivon: alpha_p, delta_p consistenly in Radians May 2010(See astrolib/pro/wcs_getpole.pro)
WCS_ROTATE
[Previous Routine] [Next Routine] [List of Routines]NAME: WCS_ROTATE PURPOSE: Rotate between standard (e.g. celestial) and native coordinates EXPLANATION: Computes a spherical coordinate rotation between native coordinates and standard celestial coordinate system (celestial, Galactic, or ecliptic). Applies the equations in Appendix B of the paper "Representation of Celestial Coordinates in FITS" by Calabretta Greisen (2002, A&A, 395, 1077). Also see http://fits.gsfc.nasa.gov/fits_wcs.html CATEGORY: Mapping and Auxiliary FITS Routine CALLING SEQUENCE: WCS_ROTATE, longitude, latitude, phi, theta, crval, [LONGPOLE = , LATPOLE = , /REVERSE, /ORIGIN ] INPUT PARAMETERS: crval - 2 element vector containing standard system coordinates (the longitude and latitude) of the reference point INPUT OR OUTPUT PARAMETERS longitude - longitude of data, scalar or vector, in degrees, in the standard celestial coordinate system latitude - latitude of data, same number of elements as longitude, in degrees phi - longitude of data in the native system, in degrees, scalar or vector theta - latitude of data in the native system, in degrees, scalar or vector If the keyword(REVERSE) is set then phi and theta are input parameters and longitude and latitude are computed. Otherwise, longitude and latitude are input parameters and phi and theta are computed. OPTIONAL KEYWORD INPUT PARAMETERS: ORIGIN - If this keyword is set and non-zero, then the reference point given by CRVAL in the native system is assumed to be at the origin of the coordinates, rather than at the North Pole. ORIGIN should be set for cylindrical projections (Cylindrical perspective-CYP, Cartesian - CAR, Mercator - MER, Cylindrical Equal area - CEA) and conventional projections (Bonne's equal area - BON, Polyconic - PCO, Sinusoidal - GLS, Parabolic - PAR, Aitoff - AIT, Mollweide - MOL, COBE quadrilateralized sphere - CSC, Quadrilateralized Spherical Cube - QSC, and Tangential Spherical Cube - TSC) LONGPOLE - native longitude of standard system's North Pole, default for a Zenithal system is 180 degrees LATPOLE - native latitude of the standard system's North Pole /REVERSE - if set then phi and theta are input parameters and longitude and latitude are computed. By default, longitude and latitude are input parameters and phi and theta are computed. REVISION HISTORY: Written W. Landsman December, 1994 Fixed error in finding North Pole if /ORIGIN and LONGPOLE NE 180 Xiaoyi Wu and W. Landsman, March, 1996 Fixed implementation of March 96 error, J. Thieler, April 1996 Updated to IDL V5.0 W. Landsman December 1997 Fixed determination of alpha_p if /ORIGIN and LONGPOLE EQ 180 W. Landsman May 1998 Ensure argument of ASIN() is -1(See astrolib/pro/wcs_rotate.pro)
WEBGET()
[Previous Routine] [Next Routine] [List of Routines]NAME: WEBGET() PURPOSE: Use the IDL SOCKET procedure to get data from http servers EXPLANATION: WEBGET() can access http servers - even from behind a firewall - and perform simple downloads. Currently, text and FITS files can be accessed. CALLING SEQUENCE: a=webget(URL) INPUTS: URL - scalar string giving a fully qualified url of the form 'http://server.eso.org/path/file.html'. WEBGET() can also use other valid URLs that contain 'GET' or 'POST' codes. OPTIONAL INPUT KEYWORD PARAMETERS: COPYFILE - if set to a valid filename (file must have write permission), the data contents of the web server's answer is copied to that file. HTTP10 - If set, then use the HTTP 1.0 POST - if set to a structure, the structure tags and values will be used as post variables and POST'ed to the URL. If POST is not set, the normal HTTP GET is used to retrieve the URL. /SILENT - If set, the information error messages are suppressed TIMEOUT - Integer scalar giving number of seconds to wait to connect or for data to arrive before giving up and issuing an error. Default=15 seconds OUTPUTS: A structure with the following fields: .Header - the HTTP header sent by the server .Text - The text part of the downloaded file. If the content type of the file was not of class 'text', this will be an empty string. .ImageHeader - Header file of a FITS-image. FITS images are read when the content type is 'image/fits' or 'application/octet-stream' (for dss-access). If the file is not a FITS image, this will be an empty string. .Image - The FITS image read from the server. If the file did not contain a FITS image, this will be zero. RESTRICTIONS: The mime-type recognition is extremely limited. Only the content-type is determined. Any text-file will be stored in out.Text. The only other category which can be fetched is FITS files, which will be stored in out.Image and out.ImageHeader. PROXY: If you are behind a firewall and have to access the net through a Web proxy, set the environment variable 'http_proxy' to point to your proxy server and port, e.g. 'setenv http_proxy=http://web-proxy.mpia-hd.mpg.de:3128' The URL *MUST* begin with "http://". PROCEDURE: Open a socket to the webserver and download the header. After deciding whether it is text or binary, either store the text or try to read a FITS file. EXAMPLE: IDL> a=webget('http://www.mpia.de/index.html') IDL> print,a.Text or > PointingRA=0.0 > PointingDE=30.0 > QueryURL = strcompress("http://archive.eso.org/dss/dss/image?ra="+$ > string(PointingRA)+$ > "&dec="+$ > string(PointingDE)+$ > "&x=10&y=10&Sky-Survey=DSS1&mime-type=download-fits", $ > /remove) > a=webget(QueryURL) > tvscl,a.Image > print,a.ImageHead MODIFICATION HISTORY: Written by M. Feldt, Heidelberg, Oct 2001Use /swap_if_little_endian keyword to SOCKET W. Landsman August 2002 Less restrictive search on Content-Type W. Landsman April 2003 Modified to work with FIRST image server- A. Barth, Nov 2006 Better recovery from errors W. Landsman April 2007 Add support for POST access J.D. Smith June 2007 Recognize "fits" image type used by SKYVIEW W. Landsman June 2007 Upgraded, partially, to HTTP 1.1 M. Perrin, July 2007 The HTTP 1.1 support is presently INCOMPLETE: virtual servers are supported, but chunked transfer encoding is not yet supported, so technically this is not fully HTTP 1.1 compliant. Added http10 keyword W. Landsman August 2007 Assume since V5.6, sockets always available W. Landsman Nov 2007 Fix problem when using proxy server W. Landsman July 2008 Fix problem with /SILENT keyword W. Landsman Jan 2009 Added check for missing Mime TYPE in CLASSANDTYPE, Zarro, December 2011 Timeout applies to connecting as well as reading, default is now 15 seconds W Landsman January 2012 (See astrolib/pro/webget.pro)
WFPC2_METRIC
[Previous Routine] [Next Routine] [List of Routines]NAME: WFPC2_METRIC PURPOSE: Compute the distortion in a WFPC2 image and optionally return coordinates EPLANATION: Uses the distortion solution of Anderson & King (2003, PASP, 115, 113) Pixel 424, 424 on each chip remains fixed, and other pixel positions are mapped to remove nonlinearities. If /GLOBAL is set, then all chips are put on the same reference frame where pixel 424, 424 in the WF3 chip remains fixed. CALLING SEQUENCE: WFPC2_METRIC, xin, yin, xout, yout, [ChipNum, HEADER=, /GLOBAL YEAR =, FILTER= or WFPC2_METRIC, xin, yin, a, d, HEADER=, /RAdec, /GLOBAL ] INPUTS: XIN, YIN - X,Y positions (0-799) on a WFPC2 chip in IDL convention (first pixel is 0,0), scalar or vectors OUTPUTS: XOUT, YOUT - X,Y positions in the undistorted frame, same number of elements as XIN, YIN or if /RADEC is set AA, DD - Right ascension and declination (in degrees) corresponding to the input coordinates after distortion correction. OPTIONAL INPUT: ChipNum - Integer 1, 2, 3, or 4 specifying the WFPC2 chip number 1-PC, 2-WF2, 3-WF3, 4-WF4. If not supplied, then WFPC2_METRIC will try to read the value from the DETECTOR in the FITS header. OPTIONAL INPUTS: /GLOBAL - If set, then positions are returned in a master reference frame with pixel 424,424 of WF3 remaining fixed. Thus, information concerning the interchip separation and orientation (with a weak dependence on time and filter) is incorporated. Header - FITS header with astrometry for a particular chip. If both /RADec and /Global are set, then the header must be from the WF3 chip. /RADec - If set, then astrometry information in the FITS header (which must be supplied as a keyword) is used to convert the output to Right Ascension and declination (both in degrees). FILTER - Filter name needed if /GLOBAL is set, must be either 'F300W' 'F336W', 'F439W', 'F555W' or 'F814W'; otherwise the plate scale for F555W is assumed. WFPC2_METRIC will try to read this value from the FITS header if not supplied as a keyword. YEAR - Observation year including fraction (e.g. 1998.56) needed if /GLOBAL is set. WFPC2_METRIC will try to read this value from the FITS header if not supplied as a keyword. The time correction is currently applied through the year 2002; later dates will use the year 2002 correction. EXAMPLES: (1) Find the undistorted X,Y coordinates of position 682.3,234.2 on chip 1 (the PC chip). IDL> WFPC2_METRIC, 682.3, 234.2, xout, yout, 1 ==> xout = 681.13 yout = 235.05 (2) Determine the RA and Dec of position 682.3, 234.2 on chip 1 on the WFPC2 image U2Z30201T IDL> WFPC2_READ, 'u2z30201t.c0h', im,h ;Get header for chip 1 IDL> WFPC2_METRIC, 682.3, 234.2, aa, dd, header= h,/RADec IDL> print, adstring(aa,dd,2) 05 20 53.572 -69 35 18.17 Note that a chip number did not need to be specified since its value is in the FITS header (3) As above, but now compute coordinates in the global frame, needed for example, to compute the distance between stars on two different chips. First get headers for chips 1 and 3 IDL> WFPC2_READ, 'u2z30201t.c0h', im1,h1, im3,h3,num=[1,3] IDL> WFPC2_METRIC, 682.3, 234.2, aa, dd, 1, header=h3,/RADec,/GLOBAL IDL> print, adstring(aa,dd,2) 05 20 53.513 -69 35 17.98 Note that with /GLOBAL set, that the header must be for WF3, even though coordinates are being computed for chip 1. Also note that the time and filter will be read from the FITS header. Finally, note that the coordinates given in examples (2) and (3) differ slightly, because the chip separations incorporated in the FITS headers differ slightly from those in the Anderson & King solution. PROCEDURES USED: LINTERP, SXPAR(), XYAD, YMD2DN() REVISION HISTORY: Written W. Landsman March 2003(See astrolib/pro/wfpc2_metric.pro)
WFPC2_READ
[Previous Routine] [Next Routine] [List of Routines]NAME: WFPC2_READ PURPOSE: Read WFPC2 images in either FITS or STSDAS format into IDL variables. EXPLANATION: This a versatile procedure for reading Wide Field Planetary Camera 2 (WFPC2) images. One can read either multi-extension FITS or STSDAS or STSDAS converted to FITS format, and specific chip or chips. One can also read all four chips into a "batwing" mosaic-- so-called because the PC chip (chip 1) has a plate scale of 0.045", while the other three WF chips have a plate scale of 0.1" CALLING SEQUENCE: WFPC2_READ,filename,chip1,hdr1,chip2,hdr2,chip3,hdr3,chip4,hdr4 or WFPC2_READ,filename,chip,hdr, NUM_CHIP = [1,2,3,4], [/TRIM, PATH = ] or WFPC2_READ,filename,image,hdr,/BATWING INPUTS: filename - Name of FITS or STSDAS file with a stack of images from the four WF/PC-2 chips, followed by a FITS ASCII table with header parameters for each chip. If the file name extension ends in 'h' then it is assumed to be an STSDAS file. If no extension is supplied, and the file is is not found, then WFPC2_READ first tries appending a '.fits' extension, and then tries appending a '.c0h' extension. The file may als be gzip compressed (with a .gz extension) INPUT KEYWORD PARAMETERS: NUM_CHIP - Integer scalar or vector, subset of 1, 2, 3, 4, specifying particular chip numbers to read. Outputs will be in same order as specification of subset. (See Example 2.) /TRIM - If set, trim off areas with no image and re-orient so that all the chips have a common orientation suitable for insertion into "bat-wing" mosaic (no image distortion removal, however). PATH - scalar string specifying a !PATH-like list of directories in which to search for the file. Default is to look only in the current directory. /BATWING - Return a 1600 x 1600 array containing all four chips in a "bat wing" mosaic formation. This image is mainly for display purposes, since the PC chip is compressed to match the plate scale of the WF chips. In addition, a small astrometry error is introduced since chips do not have the same rotation, nor are they aligned at the integer pixel level. OUTPUTS: chipN - 800 X 800 image from chip N. If /TRIM is set then the output size is somewhat smaller (e.g. 756 x 757) headerN - Individual FITS header for chip N with correct astrometry. PROCEDURES USED: For FITS I/O: FITS_CLOSE, FITS_OPEN, FITS_READ For STSDAS I/O: EXTGRP, FTGET(), SXOPEN, SXREAD() Other procedures: CHECK_FITS, FDECOMP, FIND_WITH_DEF(), FREBIN, HEXTRACT, HROTATE, SXADDHIST, SXADDPAR, SXPAR() EXAMPLE: (1) Read all four chips of the FITS file u2ou0201t_c0f.fits IDL> wfpc2_read,'u2ou0201t_c0f',c1,h1,c2,h2,c3,h3,c4,h4 (2) Note that supplying the .fits extension is optional. Now read only chips 1 (the PC chip) and 3. Trim off portions of the arrays where there is no image. IDL> wfpc2_read,'u2ou0201t_c0f',c1,h1,c3,h3,num=[1,3],/trim (3) Note that with the /TRIM option the output chip sizes are no longer 800 x 800 but odd sizes such as 770 by 753. Now read all 4 chips into a 1600 x 1600 "batwing" mosaic IDL> wfpc2_read,'u2ou0201t_c0f',im,h,/batwing MODIFICATION HISTORY: Written by W. Landsman, Raytheon STX, for IDL V5.0 June 1998 Based on code by Robert Hill, Raytheon STX Better astrometry of PC image in "batwing" configuration, W. Landsman August 1999 Use vector call to SXADDHIST W. Landsman March 2003 Don't use EXECUTE() for V6.1 or later W. Landsman Dec 2006 Assume since V6.1 W. Landsman June 2009 Ability to read multi-extension format FITS W. Landsman May 2010 Correct header in MEF form when only reading PC chip. W.L. July 2010(See astrolib/pro/wfpc2_read.pro)
WHERENAN()
[Previous Routine] [Next Routine] [List of Routines]NAME: WHERENAN() PURPOSE: Find the indices of all big-endian NaN values in an array. OBSOLETE EXPLANATION: Find the positions of all values within an array that correspond to the big-endian NaN (not-a-number) special values. THIS PROCEDURE ONLY IDENTIFIES BIG_ENDIAN NaN VALUES. DO NOT USE IT TO IDENTIFY NaN VALUES IN GENERAL. Instead, to identify NaN values on the host machine use the FINITE() function IDL> result = where( finite(array,/NAN) ) The main purpose of this routine is to catch NaN special values written in big_endian format (e.g. FITS data) on a little endian machine prior to conversion with e.g. IEEE_TO_HOST. It was needed many years ago because VMS machines could not handle big-endian special values, but this routine is now kept only for backwards compatibility. CALLING SEQUENCE: Result = WHERENAN( ARRAY [, COUNT ] ) INPUT PARAMETERS: ARRAY = Array to test against the IEEE NaN special values. Must be of either floating point, double-precision, or complex type. OUTPUTS: The result of the function is the indices of all values of ARRAY corresponding to the IEEE NaN specification, similar to the IDL WHERE function. OPTIONAL OUTPUT PARAMETERS: COUNT = Number of values found corresponding to IEEE NaN. SIDE EFFECTS: If no NaN values are found, or if ARRAY is not of type float, double precision, or complex, then -1 is returned, and COUNT is set to 0. RESTRICTIONS: ARRAY must be of type float, double-precision, or complex. PROCEDURE: The bit patterns of the numbers being tested are compared against the IEEE NaN standard. MODIFICATION HISTORY: William Thompson, Feb. 1992. William Thompson, Oct. 1992, fixed bug regarding order of bytes on VAX machines. Converted to IDL V5.0 W. Landsman September 1997(See astrolib/pro/wherenan.pro)
WHERE_TAG
[Previous Routine] [Next Routine] [List of Routines]NAME: WHERE_TAG PURPOSE: Like WHERE but works on structure tag names EXPLANATION: Obtain subscripts of elements in structure array for which a particular Tag has values in a range or matching specified values. Like the WHERE function but for use with structures CATEGORY: Structures CALLING SEQUENCE: w = where_tag( struct, [ Nfound, TAG_NAME=, TAG_NUMBER = , RANGE =, VALUES =, RANGE =, ISELECT =, /NOPRINT ] INPUTS: Struct = structure array to search. INPUT KEYWORDS: User *must* specify (1) TAG_NAME or TAG_NUMBER to search, and (2) the VALUES or RANGE to search on TAG_NAME = Scalar string specifying Tag Name TAG_NUMBER = otherwise give the Tag Number, RANGE = [min,max] range to search for in Struct, VALUES = one or array of numbers to match for in Struct, ISELECT= specifies indices to select only part of structure array, (use it to recycle subscripts from previous searches). /NOPRINT = suppress informational messages about nothing found. OUTPUTS: Nfound = # of occurences found. RESULT: Function returns subscripts (indices) to desired elements. EXAMPLES: Suppose STR is a structure with tags CAT_NO:indgen(10), and NAME:strarr(10). Find the indices where STR.CAT_NO is between 3 and 5. IDL> print, WHERE_TAG( str, TAG_NAME = 'CAT_NO', VALUE = [3,4,5] ) ;or IDL> print, WHERE_TAG( str, TAG_NUM = 0, RANGE = [3,5]) PROCEDURE: Get tag number and apply the WHERE function appropriately. MODIFICATION HISTORY: written 1990 Frank Varosi STX @ NASA/GSFC Stop printing "Tagnot found" with /NOPRINT, CD Pike 8-Jun-93 Use STRJOIN for display W.L. July 2009 (See astrolib/pro/where_tag.pro)
WRITEFITS
[Previous Routine] [Next Routine] [List of Routines]NAME: WRITEFITS PURPOSE: Write IDL array and header variables to a disk FITS file. EXPLANATION: A minimal FITS header is created if not supplied. WRITEFITS works for all types of FITS files except random groups CALLING SEQUENCE: WRITEFITS, filename, data [, header, /APPEND, /COMPRESS, /CHECKSUM] INPUTS: FILENAME = String containing the name of the file to be written. DATA = Image array to be written to FITS file. If DATA is undefined or a scalar, then only the FITS header (which must have NAXIS = 0) will be written to disk OPTIONAL INPUT: HEADER = String array containing the header for the FITS file. If variable HEADER is not given, the program will generate a minimal FITS header. HEAP - A byte array giving the heap area following, e.g. a variable length binary table OPTIONAL INPUT KEYWORD: /APPEND - If this keyword is set then the supplied header and data array are assumed to be an extension and are appended onto the end of an existing FITS file. If the file does not exist, then WRITEFITS will create one with a minimal primary header (and /EXTEND keyword) and then append the supplied extension header and array. Note that the primary header in an existing file must already have an EXTEND keyword to indicate the presence of an FITS extension. /COMPRESS - If this keyword is set, then the FITS file is written as a gzip compressed file. An extension '.gz' is appended to to the file name if it does not already exist. The /COMPRESS option is incompatible with the /APPEND option. /Checksum - If set, then the CHECKSUM keywords to monitor data integrity will be included in the FITS header. For more info, see http://heasarc.gsfc.nasa.gov/docs/heasarc/fits/checksum.html By default, checksum keywords will updated if they are already in the FITS header. NaNvalue - Value in the data array which represents missing pixels. This keyword should only used when missing pixels are not represented by NaN values in the input array. OUTPUTS: None RESTRICTIONS: (1) It recommended that BSCALE and BZERO not be used (or set equal to 1. and 0) except with integer data (2) WRITEFITS will remove any group parameters from the FITS header (3) As of Feb 2008, WRITEFITS no longer requires the primary header of a FITS file with extension contain the EXTEND keyword, consistent with Section 4.4.2.1 of the FITS 3.0 standard. A warning is still given. See http://fits.gsfc.nasa.gov/fits_standard.html EXAMPLE: Write a randomn 50 x 50 array as a FITS file creating a minimal header. IDL> im = randomn(seed, 50, 50) ;Create array IDL> writefits, 'test', im ;Write to a FITS file "test" PROCEDURES USED: CHECK_FITS, FITS_ADD_CHECKSUM, MKHDR, MRD_HREAD, SXDELPAR, SXADDPAR, SXPAR() MODIFICATION HISTORY: WRITTEN, Jim Wofford, January, 29 1989 Added call to IS_IEEE_BIG() W. Landsman Apr 96 Make sure SIMPLE is written in first line of header W. Landsman Jun 97 Use SYSTIME() instead of !STIME W. Landsman July 97 Create a default image extension header if needed W. Landsman June 98 Write unsigned data types W. Landsman December 1999 Update for IDL V5.3, add /COMPRESS keyword W. Landsman February 2000 Correct BZERO value for unsigned data W. Landsman July 2000 Eliminate duplication of input array if possible W. Landsman April 2001 Use FILE_SEARCH for V5.5 or later W. Landsman April 2002 Create the file if not already present and /APPEND is set W. Landsman September 2002 Proper call to MRD_HREAD if /APPEND is set W. Landsman December 2002 Added /CHECKSUM keyword W. Landsman December 2002 Restored NANvalue keyword, William Thompson, October 2003 Write BZERO in beginning of header for unsigned integers WL April 2004 Added ability to write heap array WL October 2004 Correct checksum if writing heap array WL November 2004 Assume since V5.5, no VMS support, use file_search() WL September 2006 Set nbytes variable to LONG64 for very large files WL May 2007 Update CHECKSUM keywords if already present WL Oct 2007 EXTEND keyword no longer required in FITS files with extensions WL Feb 2008 Bug fix when filename ends with '.gz' and COMPRESS is used, the output file must be compressed S. Koposov June 2008 Introduce V6.0 notation W.L. Nov. 2010 Set /APPEND if XTENSION specifies a table W.L. July 2012(See astrolib/pro/writefits.pro)
XDISPSTR
[Previous Routine] [Next Routine] [List of Routines]NAME: XDISPSTR PURPOSE: Display a string array in a text widget with a simple search capability. EXPLANATION: Similar to the IDL XDISPLAYFILE procedure but includes a search capbility. CALLING SEQUENCE: xdispstr, array, [/BLOCK, WIDTH= , HEIGHT=, TITLE=, GROUP_LEADER=, FONT= TOP_LINE = ] INPUT PARAMETER: array - String array (.e.g. FITS header) to be displayed OPTIONAL INPUT KEYWORD PARAMETERS: block - Set to 1 to make widget blocking. Default = block=0 width, height - Scalars giving number of characters per line, number of lines. Default = 80x24 title - Scalar Title for outermost base widget. group_leader - Group leader for top level base. top_line - first line in the string array to display (default is 0) font - Display font for text. MODIFICATION HISTORY: Written by R. S. Hill, RITSS, 17 Nov 2000 Use cumulative keyword to TOTAL W. Landsman May 2006(See astrolib/pro/xdispstr.pro)
XMEDSKY
[Previous Routine] [Next Routine] [List of Routines]NAME: XMEDSKY PURPOSE: Subtract sky from an image as a 1-D function of X EXPLANATION: This procedure is designed to remove the sky from slitless spectra. The sky is assumed to vary with wavelength (along a row) but not with position (along a column). The sky is computed as the column-by-column median of pixels within 3 sigma of the image global median. This procedure is called by the cosmic ray rejection routine CR_REJECT CALLING SEQUENCE: XMEDSKY, Image, Bkg, [ CLIP=[x0, x1, y0, y1], NSIG= ] INPUTS: Image: Input image for which sky vector is to be computed. INPUT KEYWORD PARAMETERS: CLIP: [x0, x1, y0, y1]: region of image to be used for all statistical computations. Default is to use the entire image. For STIS 1024 x 512 slitless spectra, the suggested value is CLIP = [32,1023,12,499] NSIG: Positive scalar giving the number of sigma a pixel must be above the global median to be reject. Default is 3 sigma. OUTPUT PARAMETER: Bkg: Vector of sky values. ; MODIFICATION HISTORY: Written by: R. S. Hill, Hughes STX, 20 Oct. 1997 Converted to V5.0, use STDDEV() W. Landsman June 1998 Check for valid WHERE, added NSIG keyword W. Landsman December 2000 Assume since V5.1 so always use STDDEV W. Landsman Feb 2004 Assume since V5.6 use DIMEN keyword to MEDIAN W. Landsman Jan 2008(See astrolib/pro/xmedsky.pro)
XY2AD
[Previous Routine] [Next Routine] [List of Routines]NAME: XY2AD PURPOSE: Compute R.A. and Dec from X and Y and a FITS astrometry structure EXPLANATION: The astrometry structure must first be extracted by EXTAST from a FITS header. The offset from the reference pixel is computed and the CD matrix is applied. If distortion is present then this is corrected. If a WCS projection (Calabretta & Greisen 2002, A&A, 395, 1077) is present, then the procedure WCSXY2SPH is used to compute astronomical coordinates. Angles are returned in degrees. XY2AD is meant to be used internal to other procedures. For interactive purposes use XYAD. CALLING SEQUENCE: XY2AD, x, y, astr, a, d INPUTS: X - row position in pixels, scalar or vector Y - column position in pixels, scalar or vector X and Y should be in the standard IDL convention (first pixel is 0), and not the FITS convention (first pixel is 1). 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 physical increment at reference 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 .LONGPOLE - scalar longitude of north pole .LATPOLE - scalar giving native latitude of the celestial pole .PV2 - Vector of projection parameter associated with latitude axis PV2 will have up to 21 elements for the ZPN projection, up to 3 for the SIN projection and no more than 2 for any other projection .DISTORT - Optional substructure specifying distortion parameters OUTPUT: A - R.A. in DEGREES, same number of elements as X and Y D - Dec. in DEGREES, same number of elements as X and Y RESTRICTIONS: Note that all angles are in degrees, including CD and CRVAL Also note that the CRPIX keyword assumes an FORTRAN type array beginning at (1,1), while X and Y give the IDL position beginning at (0,0). No parameter checking is performed. NOTES: AD2XY tests for presence of WCS coordinates by the presence of a dash in the 5th character position in the value of CTYPE (e.g 'DEC--SIN'). PROCEDURES USED: TAG_EXIST(), WCSXY2SPH REVISION HISTORY: Written by R. Cornett, SASC Tech., 4/7/86 Converted to IDL by B. Boothman, SASC Tech., 4/21/86 Perform CD multiplication in degrees W. Landsman Dec 1994 Understand reversed X,Y (X-Dec, Y-RA) axes, W. Landsman October 1998 Consistent conversion between CROTA and CD matrix W. Landsman Oct. 2000 No special case for tangent projection W. Landsman June 2003 Work for non-WCS coordinate transformations W. Landsman Oct 2004 Use CRVAL reference point for non-WCS transformation W.L. March 2007 Use post V6.0 notation W.L. July 2009(See astrolib/pro/xy2ad.pro)
XYAD
[Previous Routine] [Next Routine] [List of Routines]NAME: XYAD PURPOSE: Use a FITS header to convert pixel (X,Y) to world coordinates EXPLANATION: Use astrometry in a FITS image header to compute world coordinates in decimal degrees from X and Y. If spherical coordinates (Calabretta & Greisen 2002, A&A, 395, 1077) are not present, then XYAD will still perform the transformation specified by the CD, CRVAL, and CRPIX keywords. CALLING SEQUENCE: XYAD, HDR ;Prompt for X and Y positions XYAD, HDR, X, Y, A, D, [ /PRINT, /Galactic, /Celestial, /Ecliptic, ALT =, PRECISION=] INPUTS: HDR - FITS Image header containing astrometry info OPTIONAL INPUTS: X - row position in pixels, scalar or vector Y - column position in pixels, scalar or vector X and Y should be in IDL convention, (first pixel is (0,0) where the integral value corresponds to the center of the pixel.) OPTIONAL OUTPUT: A - Output longitude in decimal DEGREES (for spherical coordinates), same number of elements as X and Y. For celestial coordinates, this is the Right ascension. D - Output latitude in decimal DEGREES. For celestial coordinates, this is the declination. OPTIONAL KEYWORD INPUT: ALT - single character 'A' through 'Z' or ' ' specifying an alternate astrometry system present in the FITS header. The default is to use the primary astrometry or ALT = ' '. If /ALT is set, then this is equivalent to ALT = 'A'. See Section 3.3 of Greisen & Calabretta (2002, A&A, 395, 1061) for information about alternate astrometry keywords. PRECISION - Integer scalar (0-4) specifying the number of digits displayed after the decimal of declination. The RA is automatically one digit more. See ADSTRING() for more info. Default value is 1, and the keyword is ignored if results are not displayed at the terminal /PRINT - If this keyword is set and non-zero, then results are displayed at the terminal.in both decimal and sexagesimal notation. The default for XYAD is to return the coordinate system present in in the FITS header. However, the following mutually exclusive keywords can be used to convert to a particular coordinate system: /CELESTIAL - Output is Right Ascension and declination /ECLIPTIC - Output is Ecliptic longitude and latitude /GALACTIC - Output is Galactic longitude and latitude OPERATIONAL NOTES: If less than 5 parameters are supplied, or if the /PRINT keyword is set, then the computed astronomical coordinates are displayed at the terminal. If this procedure is to be used repeatedly with the same header, then it would be faster to use XY2AD. EXAMPLE: A FITS header, hdr, contains astrometric information in celestial coordinates. Find the RA and Dec corresponding to position X=23.3 Y = 100.2 on an image IDL> xyad, hdr, 23.3, 100.2 ;Displays results at the terminal To display the results in Galactic coordinates IDL> xyad, hdr, 23.3, 100.2, /GALACTIC PROCEDURES CALLED ADSTRING(), EULER, EXTAST, GSSSXYAD, REPCHR(), XY2AD REVISION HISTORY: W. Landsman STX Jan, 1988 Use astrometry structure W. Landsman Jan, 1994 Recognize GSSS header W. Landsman June, 1994 Changed ADSTRING output format W. Landsman September 1995 Converted to IDL V5.0 W. Landsman September 1997 Use vector call to ADSTRING() W. Landsman February 2000 Added ALT input keyword W. Landsman June 2003 Add precision keyword W. Landsman February 2004 Fix display if 'RA','DEC' reversed in CTYPE W. Landsman Feb. 2004 Handle display of NaN values W. Landsman May 2004 Work for non-spherical coordinate transformations W. Landsman Oct 2004 Fix output display units if ALT keyword used W. Landsman March 2005 More informative error message if no astrometry present W.L Nov 2007 Fix display when no equinox in header W.L. Dec 2007 Fix header display for noncelestial coords W.L. Jan 2008(See astrolib/pro/xyad.pro)
XYXY
[Previous Routine] [Next Routine] [List of Routines]NAME: XYXY PURPOSE: To use a pair of headers to convert X/Y positions from one frame to another. CALLING SEQUENCE: XYXY, hdra, hdrb, xa, ya, [ xb, yb ] INPUTS: hdra - The header containing the plate solution describing the frame of reference being converted FROM. hdra - The header containing the plate solution describing the frame of reference being converted TO. xa - A scalar or vector containing the x coordinate(s) to convert. ya - A scalar or vector containing the y coordinate(s) to convert. Must have the same number of elements as 'xa'. OUTPUTS: xb - The converted x coordinate(s). If this parameter is not specified, it is returned through 'xa'. yb - The converted y coordinate(s). If this parameter is not specified, it is returned through 'ya'. PROCEDURE: The procedures 'xyad' and 'adxy' are used to perform the conversion. The equinoxes of each header are checked with "get_equinox" to make sure that they are identical, and "precess" is used if they are not. HEULER used if the headers have a different coordinate system (e.g. Celestial, Galactic, Ecliptic) Note that all X,Y coordinates are in the IDL convention (starting with 0,0) and not the FITS convention (first pixel is 1,1) PROCEDURES USED: GET_EQUINOX(), EXTAST, XYAD, ADXY, PRECESS, HEULER MODIFICATION HISTORY: Written by Michael R. Greason, Hughes-STX, 13 April 1992. Updated to use ASTROMETRY structures. J.D.Offenberg, HSTX, Jan 1993 Converted to IDL V5.0 W. Landsman September 1997 Check coordinate system J. Ballet/ W. Landsman April 2004(See astrolib/pro/xyxy.pro)
XYZ
[Previous Routine] [Next Routine] [List of Routines]NAME: XYZ PURPOSE: Calculate geocentric X,Y, and Z and velocity coordinates of the Sun EXPLANATION: Calculates geocentric X,Y, and Z vectors and velocity coordinates (dx, dy and dz) of the Sun. (The positive X axis is directed towards the equinox, the y-axis, towards the point on the equator at right ascension 6h, and the z axis toward the north pole of the equator). Typical position accuracy is <1e-4 AU (15000 km). CALLING SEQUENCE: XYZ, date, x, y, z, [ xvel, yvel, zvel, EQUINOX = ] INPUT: date: reduced julian date (=JD - 2400000), scalar or vector OUTPUT: x,y,z: scalars or vectors giving heliocentric rectangular coordinates (in A.U) for each date supplied. Note that sqrt(x^2 + y^2 + z^2) gives the Earth-Sun distance for the given date. xvel, yvel, zvel: velocity vectors corresponding to X, Y and Z. OPTIONAL KEYWORD INPUT: EQUINOX: equinox of output. Default is 1950. EXAMPLE: What were the rectangular coordinates and velocities of the Sun on Jan 22, 1999 0h UT (= JD 2451200.5) in J2000 coords? NOTE: Astronomical Almanac (AA) is in TDT, so add 64 seconds to UT to convert. IDL> xyz,51200.5+64.d/86400.d,x,y,z,xv,yv,zv,equinox = 2000 Compare to Astronomical Almanac (1999 page C20) X (AU) Y (AU) Z (AU) XYZ: 0.51456871 -0.76963263 -0.33376880 AA: 0.51453130 -0.7697110 -0.3337152 abs(err): 0.00003739 0.00007839 0.00005360 abs(err) (km): 5609 11759 8040 NOTE: Velocities in AA are for Earth/Moon barycenter (a very minor offset) see AA 1999 page E3 X VEL (AU/DAY) YVEL (AU/DAY) Z VEL (AU/DAY) XYZ: -0.014947268 -0.0083148382 -0.0036068577 AA: -0.01494574 -0.00831185 -0.00360365 abs(err): 0.000001583 0.0000029886 0.0000032077 abs(err) (km/sec): 0.00265 0.00519 0.00557 PROCEDURE CALLS: PRECESS_XYZ REVISION HISTORY Original algorithm from Almanac for Computers, Doggett et al. USNO 1978 Adapted from the book Astronomical Photometry by A. Henden Written W. Landsman STX June 1989 Correct error in X coefficient W. Landsman HSTX January 1995 Added velocities, more terms to positions and EQUINOX keyword, some minor adjustments to calculations P. Plait/ACC March 24, 1999(See astrolib/pro/xyz.pro)
YDN2MD
[Previous Routine] [Next Routine] [List of Routines]NAME: YDN2MD PURPOSE: Convert from year and day number of year to month and day of month. CALLING SEQUENCE: YDN2MD,yr,dy,m,d INPUTS: yr = 4 digit year (like 1988), integer scalar dy = day number in year (like 310), integer scalar or vector OUTPUTS: m = month number (1-12, e.g. 11 = Nov) d = day of month (like 5). Note: On error returns m = d = -1. EXAMPLE: Find the month/day of days 155 and 255 in the year 2001 IDL> ydn2md, 2001, [155,255], m, d ==> m = [6,9] & d = [4,12] ; = June 4 and September 12 MODIFICATION HISTORY: Adapted from Johns Hopkins University/Applied Physics Laboratory Update to use VALUE_LOCATE, W. Landsman January 2001(See astrolib/pro/ydn2md.pro)
ZANG
[Previous Routine] [Next Routine] [List of Routines]NAME: ZANG PURPOSE: Determine the angular size of an object as a function of redshift EXPLANATION: Requires an input size in kpc and returns an angular size in arc seconds Default cosmology has a Hubble constant of 70 km/s/Mpc, Omega (matter) =0.3 and a normalized cosmological constant Lambda = 0.7; however these values can be changed with appropriate keywords. CALLING SEQUENCE: angsiz = zang( dl, [ z, H0 =, Omega_m =, Lambda0 = , q0 = , k =, /SILENT] ) INPUTS: dl - linear size of the object *in kpc*, non-negative scalar or vector z - redshift of object, postive scalar or vector Either dl and z must have the same number of elements, or at least one of them must be a vector. OPTIONAL INPUT KEYWORDS H0 - Hubble constant in km/s/Mpc, default is 70 No more than two of the following four parameters should be specified. None of them need be specified, default values are given k - curvature constant, normalized to the closure density. Default is 0, indicating a flat universe Omega_m - Matter density, normalized to the closure density, default is 0.3. Must be non-negative Lambda0 - Cosmological constant, normalized to the closure density, default is 0.7 q0 - Deceleration parameter, numeric scalar = -R*(R'')/(R')^2, default is -0.55 Note that Omega_m + lambda0 + k = 1 and q0 = 0.5*omega_m - lambda0 OUTPUT: angsiz - Angular size of the object at the given redshift in arc seconds EXAMPLE: (1) What would be the angular size of galaxy of diameter 50 kpc at a redshift of 1.5 in an open universe with Lambda = 0 and Omega (matter) = 0.3. Assume the default Hubble constant value of 70 km/s/Mpc. IDL> print,zang(50,1.5, Lambda = 0,omega_m = 0.3) ====> 6.58 arc seconds (2) Now plot the angular size of a 50 kpc diameter galaxy as a function of redshift for the default cosmology (Lambda = 0.7, Omega_m=0.3) up to z = 0.5 IDL> z = findgen(50)/10. + 0.1 ;Angular size undefined at z = 0 IDL> plot,z,zang(50,z),xtit='z',ytit='Angular Size (")' NOTES: This procedure underwent a major revision in April 2000 to allow for a cosmological constant, ***including a change of the calling sequence*** Be sure to supply the input linear size dl in units of kpc. PROCEDURES CALLED: LUMDIST() -- Calculates the luminosity distance REVISION HISTORY: Written J. Hill STX July, 1988 Converted to IDL V5.0 W. Landsman September 1997 Major rewrite to call LUMDIST function W. Landsman April 2000(See astrolib/pro/zang.pro)
ZBRENT
[Previous Routine] [Next Routine] [List of Routines]NAME: ZBRENT PURPOSE: Find the zero of a 1-D function up to specified tolerance. EXPLANTION: This routine assumes that the function is known to have a zero. Adapted from procedure of the same name in "Numerical Recipes" by Press et al. (1992), Section 9.3 CALLING: x_zero = ZBRENT( x1, x2, FUNC_NAME="name", MaX_Iter=, Tolerance=, _EXTRA = ) INPUTS: x1, x2 = scalars, 2 points which bracket location of function zero, that is, F(x1) < 0 < F(x2). Note: computations are performed with same precision (single/double) as the inputs and user supplied function. REQUIRED INPUT KEYWORD: FUNC_NAME = function name (string) Calling mechanism should be: F = func_name( px ) where: px = scalar independent variable, input. F = scalar value of function at px, should be same precision (single/double) as input. OPTIONAL INPUT KEYWORDS: MAX_ITER = maximum allowed number iterations, default=100. TOLERANCE = desired accuracy of minimum location, default = 1.e-3. Any other keywords are passed directly to the user-supplied function via the _EXTRA facility. OUTPUTS: Returns the location of zero, with accuracy of specified tolerance. PROCEDURE: Brent's method to find zero of a function by using bracketing, bisection, and inverse quadratic interpolation, EXAMPLE: Find the root of the COSINE function between 1. and 2. radians IDL> print, zbrent( 1, 2, FUNC = 'COS') and the result will be !PI/2 within the specified tolerance MODIFICATION HISTORY: Written, Frank Varosi NASA/GSFC 1992. FV.1994, mod to check for single/double prec. and set zeps accordingly. Use MACHAR() to define machine precision W. Landsman September 2002 Added _EXTRA keyword W. Landsman December 2011 Need to check whether user function accepts keywords W.L. Jan 2012(See astrolib/pro/zbrent.pro)
ZENPOS
[Previous Routine] [Next Routine] [List of Routines]NAME: ZENPOS PURPOSE: Return the zenith RA and Dec in radians for a given Julian date. CALLING SEQUENCE: ZENPOS, Date, Ra, Dec INPUT: Date The Julian date, in double precision, of the date and time for which the zenith position is desired, scalar or vector. OUTPUTS: Ra The right ascension in RADIANS of the zenith. Dec The declination in RADIANS of the zenith. PROCEDURE: The local sidereal time is computed; this is the RA of the zenith. It and the observatories latitude (corresponding to the Dec.) are converted to radians and returned as the zenith direction. PROMPTS: ZENPOS will prompt for the following 3 parameters if they are not defined in the common block SITE (see below) LAT,LNG - north latitude and east longitude of the desired location in DEGREES TZONE - Time Zone (in hours) of the desired location (e.g. 4 = EDT, 5 = EST) COMMON BLOCKS: SITE - This common block should contain the three scalars LAT, LNG and TZONE PROCEDURE CALLS: CT2LST - Convert to Local Mean Sidereal Time MODIFICATION HISTORY: Written by Michael R. Greason, STX, 14 October 1988. Converted to IDL V5.0 W. Landsman September 1997 Update documentation, longitude now *east* of Greenwich W.L. July 2000(See astrolib/pro/zenpos.pro)
ZOOM_XY
[Previous Routine] [Next Routine] [List of Routines]NAME: ZOOM_XY PURPOSE: Converts X, Y position on the image array to the the X,Y position in the current window. (These positions are identical only for an unroamed, zoomed image with with pixel (0,0) of the image placed at position (0,0) on the TV.) CALLING SEQUENCE: ZOOM_XY, Xim,Yim,Xtv,Ytv, [ OFFSET =, ZOOM = ] INPUTS: XIM - Scalar or vector giving X position(s) as read on the image display (e.g. with CURSOR,XIM,YIM,/DEVICE) YIM - Like XTV but giving Y position(s) as read on the image display. If only 2 parameters are supplied then XIM and YIM will be modfied on output to contain the converted coordinates. OPTIONAL KEYWORD INPUT: 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. OUTPUTS: XTV,YTV - REAL*4 X and Y coordinates of the image corresponding to the cursor position on the TV display. Same number of elements as XIM, YIM. COMMON BLOCKS: If present, ZOOM_XY will use the TV and IMAGE common blocks which are defined in the MOUSSE software system (see http://archive.stsci.edu/uit/analysis.html) If the user is not using the MOUSSE software (which keeps track of the offset and zoom in each window) then the common blocks are ignored. NOTES: The integer value of a pixel is assumed to refer to the *center* of a pixel. REVISON HISTORY: Adapted from MOUSSE procedure of the same name W. Landsman HSTX Mar 1996 Converted to IDL V5.0 W. Landsman September 1997 Properly include ZOOM keyword W. Landsman May 2000 Put back common blocks for MOUSSE compatibility September 2004(See astrolib/pro/zoom_xy.pro)
ZPARCHECK
[Previous Routine] [List of Routines]NAME: ZPARCHECK PURPOSE: Routine to check user parameters to a procedure CALLING SEQUENCE: zparcheck, progname, parameter, parnum, types, dimens, [ message ] INPUTS: progname - scalar string name of calling procedure parameter - parameter passed to the routine parnum - integer parameter number types - integer scalar or vector of valid types 1 - byte 2 - integer 3 - int*4 4 - real*4 5 - real*8 6 - complex 7 - string 8 - structure 9 - double complex 10 - pointer 11 - object ref 12 - Unsigned integer 13 - unsigned int*4 14 - int*8 15 - Unsigned int*8 dimens - integer scalar or vector giving number of allowed dimensions. OPTIONAL INPUT: message - string message describing the parameter to be printed if an error is found OUTPUTS: none EXAMPLE: IDL> zparcheck, 'HREBIN', hdr, 2, 7, 1, 'FITS Image Header' This example checks whether the parameter 'hdr' is of type string (=7) and is a vector (1 dimension). If either of these tests fail, a message will be printed "Parameter 2 (FITS Image Header) is undefined" "Valid dimensions are 1" "Valid types are string" SIDE EFFECTS: If an error in the parameter is a message is printed a RETALL issued HISTORY version 1 D. Lindler Dec. 86 documentation updated. M. Greason, May 1990. Recognize double complex datatype W. Landsman September 1995 Converted to IDL V5.0 W. Landsman September 1997 Check for new data types (e.g. unsigned) W. Landsman February 2000 Print a traceback if an error occurs W. Landsman Aug 2011(See astrolib/pro/zparcheck.pro)