514 A_B 0 ABSCAL 1483 AD2XY 2518 ADSTRING 4472 ADXY 8525 AFHREAD 10100 AIRTOVAC 11179 AITOFF 12199 AITOFF_GRID 13302 APER 15949 ARCBAR 21206 ARROWS 23944 ASINH 27237 ASTDISP 28114 ASTRMFIX 29615 ASTRO 30768 ASTROLIB 33119 AUTOHIST 33915 AVG 35169 BARYVEL 38081 BIWEIGHT_MEAN 41327 BLINK 42259 BOOST_ARRAY 43077 BOXAVE 44109 BPRECESS 46728 BREAK_PATH 50427 BSORT 52519 CALZ_UNRED 53815 CCM_UNRED 56055 CHECK_FITS 58882 CHECKSUM32 63158 CIC 64529 CIRRANGE 68875 CLEANPLOT 69864 CNTRD 72283 CO_ABERRATION 74890 CO_NUTATE 76195 CO_REFRACT 77995 COMPARE_STRUCT 82606 CONCAT_DIR 84204 CONS_DEC 86013 CONS_RA 88153 CONV_STSDAS 90222 CONV_UNIX_VAX 92853 CONV_VAX_UNIX 94821 CONVOLVE 97489 COPY_STRUCT 98754 COPY_STRUCT_INX101861 CORREL_IMAGES 104759 CORREL_OPTIMIZE107433 CORRMAT_ANALYZE109439 COSMO_PARAM 111641 CR_REJECT 113567 CREATE_STRUCT 127922 CSPLINE 132841 CT2LST 134997 CURVAL 137644 DAO_VALUE 140281 DAOERF 142004 DATE 143217 DATE_CONV 143978 DAYCNV 146359 DB_ENT2EXT 147521 DB_ENT2HOST 148245 DB_INFO 149248 DB_ITEM 151187 DB_ITEM_INFO 153623 DB_OR 154893 DB_TITLES 155738 DBBUILD 156349 DBCIRCLE 159249 DBCLOSE 162324 DBCOMPARE 162874 DBCOMPRESS 165104 DBCREATE 166061 DBDELETE 169713 DBEDIT 171503 DBEDIT_BASIC 174716 DBEXT 176789 DBEXT_DBF 177862 DBEXT_IND 180196 DBFIND 181177 DBFIND_ENTRY 187555 DBFIND_SORT 188578 DBFPARSE 190333 DBGET 191461 DBHELP 193956 DBINDEX 197322 DBINDEX_BLK 198840 DBMATCH 199836 DBOPEN 202827 DBPRINT 204983 DBPUT 209700 DBRD 210692 DBSEARCH 212312 DBSORT 213373 DBTITLE 214635 DBUPDATE 215051 DBVAL 217137 DBWRT 217710 DBXPUT 219115 DBXVAL 220251 DEF_DIRLIST 221873 DELVARX 223358 DEREDD 223940 DETABIFY 224800 DIST_CIRCLE 225444 DIST_ELLIPSE 227814 ECI2GEO 230835 EQ2HOR 232653 EQPOLE 238650 EQPOLE_GRID 239683 EULER 242929 EXPAND_TILDE 244686 EXTAST 245660 EXTGRP 249416 F_FORMAT 250342 FACTOR 251587 FDECOMP 252926 FILTER_IMAGE 255234 FIND 260186 FIND_ALL_DIR 262830 FIND_WITH_DEF 266324 FINDPRO 271084 FITEXY 275140 FITS_CD_FIX 277860 FITS_CLOSE 279838 FITS_HELP 281117 FITS_INFO 281693 FITS_OPEN 284822 FITS_READ 289872 FITS_WRITE 298545 FITSDIR 302980 FITSRGB_TO_TIFF308339 FLEGENDRE 310987 FLUX2MAG 312762 FM_UNRED 314164 FORPRINT 318250 FREBIN 322531 FSTRING 325386 FTAB_DELROW 326786 FTAB_EXT 328170 FTAB_HELP 330309 FTAB_PRINT 331749 FTADDCOL 333659 FTCREATE 334881 FTDELCOL 335580 FTDELROW 336721 FTGET 337695 FTHELP 340151 FTHMOD 341273 FTINFO 342820 FTKEEPROW 344028 FTPRINT 344546 FTPUT 346532 FTSIZE 349535 FTSORT 350621 FXADDPAR 352751 FXBADDCOL 358815 FXBCLOSE 362938 FXBCOLNUM 364438 FXBCREATE 366503 FXBDIMEN 369063 FXBFIND 371554 FXBFINDLUN 374082 FXBFINISH 375438 FXBGROW 377324 FXBHEADER 380070 FXBHELP 381666 FXBHMAKE 382880 FXBINTABLE 385012 FXBISOPEN 387594 FXBOPEN 389071 FXBPARSE 392186 FXBREAD 394353 FXBREADM 399688 FXBSTATE 407828 FXBTDIM 409143 FXBTFORM 410631 FXBWRITE 412736 FXBWRITM 415529 FXFINDEND 420955 FXHCLEAN 422288 FXHMAKE 424098 FXHMODIFY 426884 FXHREAD 430534 FXMOVE 431812 FXPAR 432753 FXPARPOS 439390 FXPOSIT 440948 FXREAD 443663 FXWRITE 448927 GAL_FLAT 452434 GAL_UVW 453761 GALAGE 456765 GAUSSIAN 459720 GCIRC 461828 GEO2ECI 464058 GEO2GEODETIC 465591 GEO2MAG 469467 GEODETIC2GEO 470463 GET_COORDS 473513 GET_DATE 475657 GET_EQUINOX 479235 GET_JULDATE 480972 GETFILES 482627 GETLOG 483221 GETOPT 484812 GETPRO 486598 GETPSF 488806 GETROT 492418 GETTOK 494828 GETWRD 495728 GLACTC 498032 GROUP 500139 GSSS_STDAST 501785 GSSSADXY 503652 GSSSEXTAST 505500 GSSSXYAD 507096 HADEC2ALTAZ 508953 HASTROM 510472 HBOXAVE 515232 HCONGRID 517862 HEADFITS 522747 HELIO 526762 HELIO_JD 530214 HELIO_RV 532744 HERMITE 535641 HEXTRACT 538472 HGREP 540868 HISTOGAUSS 542016 HOR2EQ 544692 HOST_TO_IEEE 550537 HPRECESS 551959 HPRINT 553439 HREBIN 555270 HREVERSE 558712 HROT 561246 HROTATE 565753 IEEE_TO_HOST 568473 IMCONTOUR 570018 IMDBASE 574289 IMF 577488 IMGREAD 580436 IMLIST 584249 IRAFDIR 587838 IRAFRD 589344 IRAFWRT 592376 IS_IEEE_BIG 595466 ISARRAY 596326 ISMEUV 597230 JDCNV 599765 JPLEPHINTERP 600854 JPLEPHREAD 608907 JPLEPHTEST 614015 JPRECESS 616151 JULDATE 620241 KSONE 622784 KSTWO 625899 LEGEND 627792 LEGENDTEST 639652 LINEID_PLOT 640324 LINTERP 643594 LIST_WITH_PATH 647150 LSF_ROTATE 648834 LUMDIST 651133 MAG2FLUX 653704 MAG2GEO 655055 MAKE_2D 655959 MAKE_ASTR 657136 MATCH 659101 MAX_ENTROPY 661640 MAX_LIKELIHOOD 663744 MEANCLIP 666083 MEDARR 667212 MID_RD_DIRDSC 670641 MID_RD_IMAGE 672267 MID_RD_TABLE 674198 MID_UP_IMAGE 675765 MID_UP_TABLE 677828 MINF_BRACKET 680507 MINF_CONJ_GRAD 683211 MINF_PARABOL_D 686510 MINF_PARABOLIC 689850 MINMAX 692890 MKHDR 694641 MMM 697895 MODFITS 700510 MONTH_CNV 705392 MOONPOS 706652 MPHASE 709936 MRD_HREAD 711342 MRD_SKIP 712985 MRD_STRUCT 714493 MRDFITS 718279 MULTIPLOT 735417 MWRFITS 740164 N_BYTES 751930 N_STRUCT 752651 NGP 753285 NINT 756854 NSTAR 758174 NULLTRIM 761702 NUMLINES 762072 NUTATE 762777 OBSERVATORY 764606 ONE_ARROW 768283 ONE_RAY 769960 OPLOTERROR 771123 ORDINAL 775908 OSFCNVRT 776407 PARTVELVEC 777158 PCA 779642 PENT 784390 PIXCOLOR 787865 PIXWT 788951 PKFIT 790390 PLANCK 792740 PLANET_COORDS 794325 PLOTERROR 798281 PLOTHIST 803683 POIDEV 807214 POLINT 809886 POLREC 811152 POLY_SMOOTH 812222 POLYLEG 815721 POSANG 817050 POSITIVITY 819528 PRECESS 820811 PRECESS_CD 823980 PRECESS_XYZ 825787 PREMAT 826746 PRIME 828055 PRINT_STRUCT 829190 PROB_KS 831088 PRODUCT 832287 PSF_GAUSSIAN 833589 PUTAST 836495 QDCB_GRID 840784 QGET_STRING 842984 QSIMP 843979 QTRAP 846825 QUADTERP 848816 QUERYDSS 852235 QUERYGSC 855322 QUERYSIMBAD 858712 QUERYUSNO 860073 RADEC 862882 RANDOMP 863995 RDFITS_STRUCT 866192 RDFLOAT 868115 RDPLOT 871441 RDPSF 878582 READ_KEY 879336 READCOL 880335 READFITS 885348 READFMT 894343 RECPOL 897950 REDSHIFT 899050 REM_DUP 900267 REMCHAR 901631 REMOVE 902265 REPCHR 904285 REPSTR 905378 RESISTANT_MEAN 906517 RINTER 908403 ROB_CHECKFIT 911448 ROBUST_LINEFIT 912394 ROBUST_POLY_FIT915485 ROBUST_SIGMA 916752 SCR_ATTRIB 917744 SCR_CHARSET 919099 SCR_CURMOV 920115 SCR_CURPOS 921032 SCR_ERASE 921848 SCR_OTHER 922851 SCR_RESET 923687 SCR_SCROLL 924236 SCREEN_SELECT 925257 SELECT_O 927100 SELECT_W 928700 SIGMA_FILTER 930013 SIGRANGE 932063 SIXLIN 934275 SIXTY 936178 SIZE_STRUCT 936984 SKY 938029 SKYADJ_CUBE 939652 SKYADJ_CUBE 942664 SPEC_DIR 943655 SPHDIST 945636 SPLINE_SMOOTH 947638 SRCOR 951824 ST_DISKREAD 954996 ST_DISKREAD 956636 ST_DISKREAD 957497 ST_DISKREAD 958188 STARAST 959756 STORE_ARRAY 962278 STR_INDEX 963197 STRD 964520 STRN 966313 STRNUMBER 968671 STSUB 970178 STSUBIM 971345 STWRT 973841 SUBSTAR 975831 SUNPOS 977682 SUNSYMBOL 980182 SXADDHIST 981435 SXADDPAR 983476 SXDELPAR 988866 SXGINFO 989723 SXGPAR 990962 SXGREAD 992584 SXHCOPY 993360 SXHEDIT 993972 SXHMAKE 994750 SXHREAD 995847 SXHWRITE 996923 SXMAKE 998061 SXOPEN 1000707 SXPAR 1003867 SXREAD 1009418 SXWRITE 1010536 T_APER 1011935 T_FIND 1015642 T_GETPSF 1017736 T_GROUP 1020270 T_NSTAR 1021426 T_SUBSTAR 1023826 TAB_ADDCOL 1025926 TAB_COL 1026379 TAB_CREATE 1027178 TAB_DEL 1027902 TAB_EXPAND 1028309 TAB_FORTOSPP 1028991 TAB_MODCOL 1029345 TAB_NULL 1030386 TAB_NULLROW 1030928 TAB_PRINT 1031367 TAB_PUT 1032079 TAB_READ 1032592 TAB_SIZE 1034098 TAB_SORT 1034656 TAB_SPPTOFOR 1035002 TAB_VAL 1035459 TAB_WRITE 1036195 TABINV 1036574 TABLE_APPEND 1038877 TABLE_CALC 1039626 TABLE_CONV 1040698 TABLE_DELETE 1042297 TABLE_EXT 1042718 TABLE_HELP 1043517 TABLE_LIST 1044023 TABLE_PRINT 1045217 TABLE_SORT 1045821 TAG_EXIST 1046220 TBDELCOL 1047828 TBDELROW 1048794 TBGET 1049829 TBHELP 1053177 TBINFO 1054491 TBPRINT 1056260 TBSIZE 1059037 TDB2TDT 1059738 TEN 1065816 TENV 1066854 TEXTCLOSE 1068029 TEXTOPEN 1068736 TIC_ONE 1072965 TICLABELS 1074134 TICPOS 1075727 TICS 1077180 TO_HEX 1078240 TRAPZD 1079385 TSC 1081170 TSUM 1085535 TVBOX 1087368 TVCIRCLE 1090867 TVELLIPSE 1094677 TVLASER 1097952 TVLIST 1108374 UNZOOM_XY 1111806 UVBYBETA 1113405 VACTOAIR 1118636 VALID_NUM 1119518 VALUE_LOCATE 1121194 VECT 1124867 VSYM 1126019 WCS_DEMO 1127496 WCS_ROTATE 1130237 WCSSPH2XY 1133418 WCSXY2SPH 1144126 WEBGET 1152631 WFPC2_READ 1155884 WFPCREAD 1159593 WHERE_NEGZERO 1160708 WHERE_TAG 1162150 WHERENAN 1163750 WRITEFITS 1165626 XMEDSKY 1168779 XY2AD 1170298 XYAD 1172675 XYXY 1174336 XYZ 1175817 YDN2MD 1178414 YMD2DN 1179362 ZANG 1180443 ZBRENT 1183215 ZENPOS 1184982 ZOOM_XY 1186393 ZPARCHECK 1188150 ;+ NAME: A_b PURPOSE: Compute B band interstellar extinction according to the RC2. EXPLANATION: The predicted B band extinction is computed as a function of Galactic position using the 21 parameter function given by deVaucouleurs in the 2nd Reference Catalog of Galaxies (RC2). Note that this formula was not used for the RC3 and that reddenings were instead obtained from the Burstein-Heiles 21 cm maps. CALLING SEQUENCE: result = A_b( l2, b2) INPUT PARAMETERS l2 = Galactic longitude (degrees), scalar or vector b2 = Galactic latitude (degrees), scalar or vector OUTPUT PARAMETERS RESULT - Interstellar extinction Ab in magnitudes, same number of elements as input l2 and b2 parameters NOTES: The controversial aspect of the deVaucouleurs reddening curve is that it predicts an extinction of about 0.2 at the poles The parameters used here differ from the ones printed in the RC2 but are the ones actually used for entries in the catalog (see Rowan-Robinson 1985) This procedure is mainly of historical interest only, and reddening is now better determined using dust maps, such as those available at http://astro.berkeley.edu/davis/dust/index.html REVISION HISTORY Written by R. Cornett and W. Landsman, STX October 1987 Vectorized code W. Landsman STX December 1992 Converted to IDL V5.0 W. Landsman September 1997 ;- ;+ NAME: ABSCAL PURPOSE: Apply the FITS BZERO and BSCALE keyword values to a data array CALLING SEQUENCE: RESULT = ABSCAL( Value, Header, /DEBUG) INPUTS: VALUE - Any scalar, vector, or array (usually an integer type giving a relative intensity). HEADER - A FITS header array containing the absolute calibration keyword BSCALE, and optionally BZERO and BUNIT. OUTPUT: RESULT = BSCALE*VALUE + BZERO, where the BSCALE and BZERO scalars are taken from the FITS header. If the absolute calibration keywords do not exist, then RESULT = VALUE, and !ERR = -1. OPTIONAL INPUT KEYWORD: /DEBUG - If DEBUG is set, then ABSCAL will print the calibration units given by the BUNIT keyword. REVISION HISTORY: Written W. Landsman, STX Corporation January 1987 Use DEBUG keyword instead of !DEBUG September 1995 Converted to IDL V5.0 W. Landsman September 1997 ;- ;+ NAME: AD2XY PURPOSE: Compute X and Y from RA and DEC and a FITS astrometry structure EXPLANATION: A tangent (gnomonic) projection is computed directly; other projections are computed using WCSXY2SPH. AD2XY is meant to be used internal to other procedures. For interactive purposes, use ADXY. CALLING SEQUENCE: AD2XY, a ,d, astr, x, y INPUTS: A - R.A. in DEGREES, scalar or vector D - Dec. in DEGREES, scalar or vector ASTR - astrometry structure, output from EXTAST procedure containing: .CD - 2 x 2 array containing the astrometry parameters CD1_1 CD1_2 in DEGREES/PIXEL CD2_1 CD2_2 .CDELT - 2 element vector giving increment at reference point in DEGREES/PIXEL .CRPIX - 2 element vector giving X and Y coordinates of reference pixel (def = NAXIS/2) in FITS convention (first pixel is 1,1) .CRVAL - 2 element vector giving R.A. and DEC of reference pixel in DEGREES .CTYPE - 2 element vector giving projection types OUTPUTS: X - row position in pixels, scalar or vector Y - column position in pixels, scalar or vector X,Y will be in the standard IDL convention (first pixel is 0), and *not* the FITS convention (first pixel is 1) REVISION HISTORY: Converted to IDL by B. Boothman, SASC Tech, 4/21/86 Use astrometry structure, W. Landsman Jan. 1994 Do computation correctly in degrees W. Landsman Dec. 1994 Only pass 2 CRVAL values to WCSSPH2XY W. Landsman June 1995 Don't subscript CTYPE W. Landsman August 1995 Converted to IDL V5.0 W. Landsman September 1997 Understand reversed X,Y (X-Dec, Y-RA) axes, W. Landsman October 1998 Consistent conversion between CROTA and CD matrix W. Landsman October 2000 ;- ;+ NAME: ADSTRING PURPOSE: Return RA and Dec as character string(s) in sexigesimal format. EXPLANATION: RA and Dec may be entered as either a 2 element vector or as two separate vectors (or scalars). One can also specify the precision of the declination in digits after the decimal point. CALLING SEQUENCE result = ADSTRING( ra_dec, precision, /TRUNCATE ) or result = ADSTRING( ra,dec,[ precision, /TRUNCATE ] ) INPUTS: RA_DEC - 2 element vector giving the Right Ascension and declination in decimal degrees. or RA - Right ascension in decimal degrees, numeric scalar or vector DEC - Declination in decimal degrees, numeric scalar or vector OPTIONAL INPUT: PRECISION - Integer scalar (0-4) giving the number of digits after the decimal of DEClination. The RA is automatically 1 digit more. This parameter may either be the third parameter after RA,DEC or the second parameter after [RA,DEC]. It is not available for just DEC. If no PRECISION parameter is passed, a precision of 1 for both RA and DEC is returned to maintain compatibility with past ADSTRING functions. Values of precision larger than 4 will be truncated to 4. If PRECISION is 3 or 4, then RA and Dec should be input as double precision. OPTIONAL INPUT KEYWORD: /TRUNCATE - if set, then the last displayed digit in the output is truncated in precision rather than rounded. This option is useful if ADSTRING() is used to form an official IAU name (see http://vizier.u-strasbg.fr/Dic/iau-spec.htx) with coordinate specification. The IAU name will typically be be created by applying STRCOMPRESS/REMOVE) after the ADSTRING() call, e.g. strcompress( adstring(ra,dec,0,/truncate), /remove) ;IAU format OUTPUT: RESULT - Character string(s) containing HR,MIN,SEC,DEC,MIN,SEC formatted as ( 2I3,F5.(p+1),2I3,F4.p ) where p is the PRECISION parameter. If only a single scalar is supplied it is converted to a sexigesimal string (2I3,F5.1). EXAMPLE: (1) Display CRVAL coordinates in a FITS header, H IDL> crval = sxpar(h,'CRVAL*') ;Extract 2 element CRVAL vector (degs) IDL> print, adstring(crval) ;Print CRVAL vector sexigesimal format (2) print,adstring(30.42,-1.23,1) ==> ' 02 01 40.80 -01 13 48.0' print,adstring(30.42,+0.23) ==> ' 02 01 40.8 +00 13 48.0' print,adstring(+0.23) ==> '+00 13 48.0' (3) The first two calls in (2) can be combined in a single call using vector input print,adstring([30.42,30.42],[-1.23,0.23], 1) PROCEDURES CALLED: FSTRING(), RADEC, SIXTY() REVISION HISTORY: Written W. Landsman June 1988 Addition of variable precision and DEC seconds precision fix. ver. Aug. 1990 [E. Deutsch] Output formatting spiffed up October 1991 [W. Landsman] Remove ZPARCHECK call, accept 1 element vector April 1992 [W. Landsman] Call ROUND() instead of NINT() February 1996 [W. Landsman] Check roundoff past 60s October 1997 [W. Landsman] Work for Precision =4 November 1997 [W. Landsman] Converted to IDL V5.0 W. Landsman 24-Nov-1997 Major rewrite to allow vector inputs W. Landsman February 2000 Fix possible error in seconds display when Precision=0 P. Broos/W. Landsman April 2002 Added /TRUNCATE keyword, put leading zeros in seconds display P. Broos/W. Landsman September 2002 Hours values always less than 24 W. Landsman September 2002 ;- ;+ NAME: ADXY PURPOSE: Use a FITS header to convert celestial (RA,Dec) to pixel coordinates EXPLANATION: Use an image header to compute X and Y positions, given the RA and Dec in decimal degrees. CALLING SEQUENCE: ADXY, HDR ;Prompt for Ra and DEC ADXY, hdr, a, d, x, y, [ /PRINT ] INPUTS: HDR - FITS Image header containing astrometry parameters OPTIONAL INPUTS: A - Right ascension in decimal DEGREES, scalar or vector D - Declination in decimal DEGREES, scalar or vector If A and D are not supplied, user will be prompted to supply them in either decimal degrees or HR,MIN,SEC,DEG,MN,SC format. OPTIONAL OUTPUT: X - row position in pixels, same number of elements as A and D Y - column position in pixels X and Y will be in standard IDL convention (first pixel is 0) and not the FITS convention (first pixel is 1). OPTIONAL KEYWORD INPUT: /PRINT - If this keyword is set and non-zero, then results are displayed at the terminal. OPERATIONAL NOTES: If less than 5 parameters are supplied, or if the /PRINT keyword is set, then then the X and Y positions are displayed at the terminal. If the procedure is to be used repeatedly with the same header, then it would be faster to use AD2XY. PROCEDURES CALLED: AD2XY, ADSTRING(), EXTAST, GETOPT() REVISION HISTORY: W. Landsman HSTX January, 1988 Use astrometry structure W. Landsman January, 1994 Changed default ADSTRING format W. Landsman September, 1995 Converted to IDL V5.0 W. Landsman September 1997 ;- ;+ NAME: AFhread PURPOSE: Subroutine of WFPCREAD to read a GEIS header from an HST STSDAS image. EXPLANATION: This procedure reads a GEIS header from an HST image. It then looks if a .SHH file is present for FOC images to calculate better astrometry by getting the current PSANGLV3 from this file. Called by WFPCREAD.PRO CALLING SEQUENCE: AFhread, HdrFile, hdr INPUTS: HdrFile - scalar string giving name of STSDAS header for an FOC image OUTPUTS: hdr - string array, FITS header for the FOC image. The position angle of the V3 axis of HST (PSANGLV3) is added, if it could be found in the .SHH file PROCEDURE CALLS: STRN(), SXADDPAR, SXHREAD, SXPAR() REVISION HISTORY: Written Eric W. Deutsch (U. of Washington) June, 1994 Documentation update W. Landsman (HSTX) July, 1994 Converted to IDL V5.0 W. Landsman September 1997 Removed call to EXIST() function W. Landsman April 1999 ;- ;+ NAME: AIRTOVAC PURPOSE: Convert air wavelengths to vacuum wavelengths EXPLANATION: Wavelengths are corrected for the index of refraction of air under standard conditions. Wavelength values below 2000 A will not be altered. Uses the IAU standard for conversion given in Morton (1991 Ap.J. Suppl. 77, 119) CALLING SEQUENCE: AIRTOVAC, WAVE INPUT/OUTPUT: WAVE - Wavelength in Angstroms, scalar or vector WAVE should be input as air wavelength(s), it will be returned as vacuum wavelength(s). WAVE is always converted to double precision upon return. EXAMPLE: If the air wavelength is W = 6056.125 (a Krypton line), then AIRTOVAC, W yields an vacuum wavelength of W = 6057.8019 METHOD: See Morton (Ap. J. Suppl. 77, 119) for the formula used REVISION HISTORY Written W. Landsman November 1991 Converted to IDL V5.0 W. Landsman September 1997 ;- ;+ 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 ;- ;+ NAME: AITOFF_GRID PURPOSE: Produce an overlay of latitude and longitude lines over a plot or image EXPLANATION: The grid is plotted on the current graphics device. AITOFF_GRID assumes that the ouput plot coordinates span the x-range of -180 to 180 and the y-range goes from -90 to 90. CALLING SEQUENCE: AITOFF_GRID [,DLONG,DLAT, LABEL=, /NEW, CHARTHICK=, CHARSIZE=, _EXTRA=] OPTIONAL INPUTS: DLONG = Optional input longitude line spacing in degrees. If left out, defaults to 30. DLAT = Optional input latitude line spacing in degrees. If left out, defaults to 30. OPTIONAL INPUT KEYWORDS: LABEL = Optional keyword specifying that the latitude and longitude lines on the prime meridian and the equator should be labeled in degrees. If LABELS is given a value of 2, i.e. LABELS=2, then the longitude labels will be in hours instead of degrees. CHARSIZE = If /LABEL is set, then CHARSIZE specifies the size of the label characters (passed to XYOUTS) CHARTHICK = If /LABEL is set, then CHARTHICK specifies the thickness of the label characters (passed to XYOUTS) /NEW = If this keyword is set, then AITOFF_GRID will create a new plot grid, rather than overlay an existing plot. Any valid keyword to OPLOT such as COLOR, LINESTYLE, THICK can be passed to AITOFF_GRID (though the _EXTRA facility) to to specify the color, style, or thickness of the grid lines. OUTPUTS: Draws grid lines on current graphics device. EXAMPLE: Create a labeled Aitoff grid of the Galaxy, and overlay stars at specified Galactic longitudes, glong and latitudes, glat IDL> aitoff_grid,/label,/new ;Create labeled grid IDL> aitoff, glong, glat, x,y ;Convert to X,Y coordinates IDL> plots,x,y,psym=2 ;Overlay "star" positions PROCEDURES USED: AITOFF NOTES: If labeling in hours (LABEL=2) then the longitude spacing should be a multiple of 15 degrees AUTHOR AND MODIFICATIONS: J. Bloch 1.2 6/2/91 Converted to IDL V5.0 W. Landsman September 1997 Create default plotting coords, if needed W. Landsman August 2000 Added _EXTRA, CHARTHICK, CHARSIZE keywords W. Landsman March 2001 Several tweaks, plot only hours not minutes W. Landsman January 2002 ;- ;+ 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, /EXACT, /FLUX, PRINT = , /SILENT, SETSKYVAL = ] INPUTS: IMAGE - input image array XC - vector of x coordinates. YC - vector of y coordinates OPTIONAL INPUTS: PHPADU - Photons per Analog Digital Units, numeric scalar. Converts the data numbers in IMAGE to photon units. (APER assumes Poisson statistics.) APR - Vector of up to 12 REAL photometry aperture radii. SKYRAD - Two element vector giving the inner and outer radii to be used for the sky annulus BADPIX - Two element vector giving the minimum and maximum value of a good pix (Default [-32765,32767]). If BADPIX[0] is equal to BADPIX[1] then it is assumed that there are no bad pixels. OPTIONAL KEYWORD INPUTS: /EXACT - By default, APER counts subpixels, but uses a polygon approximation for the intersection of a circular aperture with a square pixel (and normalize the total area of the sum of the pixels to exactly match the circular area). If the /EXACT keyword, then the intersection of the circular aperture with a square pixel is computed exactly. The /EXACT keyword is much slower and is only needed when small (~2 pixels) apertures are used with very undersampled data. /FLUX - By default, APER uses a magnitude system where a magnitude of 25 corresponds to 1 flux unit. If set, then APER will keep results in flux units instead of magnitudes. PRINT - if set and non-zero then APER will also write its results to a file aper.prt. One can specify the output file name by setting PRINT = 'filename'. /SILENT - If supplied and non-zero then no output is displayed to the terminal. 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 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 APER was modified in June 2000 in two ways: (1) the /EXACT keyword was added (2) the approximation of the intersection of a circular aperture with square pixels was improved (i.e. when /EXACT is not used) REVISON HISTORY: Adapted to IDL from DAOPHOT June, 1989 B. Pfarr, STX Adapted for IDL Version 2, J. Isensee, July, 1990 Code, documentation spiffed up W. Landsman August 1991 TEXTOUT may be a string W. Landsman September 1995 FLUX keyword added J. E. Hollis, February, 1996 SETSKYVAL keyword, increase maxsky W. Landsman, May 1997 Work for more than 32767 stars W. Landsman, August 1997 Converted to IDL V5.0 W. Landsman September 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 ;- ;+ NAME: ARCBAR PURPOSE: Draw an arc bar on an image showing the astronomical plate scale CALLING SEQUENCE: ARCBAR, hdr, arclen,[ COLOR= , /DATA, LABEL= , /NORMAL, POSITION =, /SECONDS, SIZE=, THICK= ] INPUTS: hdr - image FITS header with astrometry, string array arclen - numeric scalar giving length of bar in arcminutes (default) or arcseconds (if /SECONDS is set) OPTIONAL KEYWORD INPUTS: COLOR - integer scalar specifying the color to draw the arcbar (using PLOTS), default = !P.COLOR /DATA - if set and non-zero, then the POSITION keyword is given in data units LABEL - string giving user defined label for bar. Default label is size of bar in arcminutes /NORMAL - if this keyword is set and non-zero, then POSITION is given in normalized units POSITION - 2 element vector giving the (X,Y) position in device units (or normalized units if /NORMAL is set, or data units if /DATA is set) at which to place the scale bar. If not supplied, then the user will be prompted to place the cursor at the desired position SIZE - scalar specifying character size of label, default = 1.0 THICK - Character thickness of the label, default = !P.THICK EXAMPLE: Place a 3' arc minute scale bar, at position 300,200 of the current image window, (which is associated with a FITS header, HDR) IDL> arcbar, HDR, 3, pos = [300,200] RESTRICTIONS: When using using a device with scalable pixels (e.g. postscript) the data coordinate system must be established before calling ARCBAR. If data coordinates are not set, then ARCBAR assumes that the displayed image size is given by the NAXIS1 keyword in the FITS header. PROCEDURE CALLS: AD2XY, EXTAST, GSSSADXY, SXPAR() REVISON HISTORY: written by L. Taylor (STX) from ARCBOX (Boothman) modified for Version 2 IDL, B. Pfarr, STX, 4/91 New ASTROMETRY structures W.Landsman, HSTX, Jan 94 Recognize a GSSS header W. Landsman June 94 Added /NORMAL keyword W. Landsman Feb. 96 Use NAXIS1 for postscript if data coords not set, W. Landsman Aug 96 Fixed typo for postscript W. Landsman Oct. 96 Account for zeropoint offset in postscript W. Landsman Apr 97 Converted to IDL V5.0 W. Landsman September 1997 Added /DATA, /SECONDS keywords W. Landsman July 1998 Use device-independent label offset W. Landsman August 2001 ;- ;+ NAME: ARROWS PURPOSE: To display "weathervane" directional arrows on an astronomical image EXPLANATION: Overlays a graphic showing orientation of North and East. CALLING SEQUENCE: ARROWS,h, [ xcen, ycen, ARROWLEN= , CHARSIZE= COLOR= , /DATA FONT=, /NORMAL, /NOTVERTEX, THICK= ] INPUTS: h - FITS or STSDAS header array, must include astrometry OPTIONAL INPUTS: xcen,ycen - numeric scalars, specifying the center position of arrows. Position in device units unless the /NORMALIZED keyword is specified. If not supplied, then ARROWS will prompt for xcen and ycen OPTIONAL KEYWORD INPUTS: arrowlen - length of arrows in terms of normal Y size of vector-drawn character, default = 3.5, floating point scalar charsize - character size, default = 2.0, floating point scalar color - color that the arrows and NE letters should be. Default value is !P.COLOR Data - if this keyword is set and nonzero, the input center (xcen, ycen) is understood to be in data coordinates font - IDL vector font number (1-20) to use to display NE letters. For example, set font=13 to use complex italic font. NotVertex - Normally (historically) the specified xcen,ycen indicated the position of the vertex of the figure. If this keyword is set, the xcen,ycen coordinates refer to a sort of 'center of mass' of the figure. This allows the figure to always appear with the area irregardless of the rotation angle. Normal - if this keyword is set and nonzero, the input center (xcen,ycen) is taken to be in normalized coordinates. The default is device coordinates. thick - line thickness, default = 2.0, floating point scalar OUTPUTS: none EXAMPLE: Draw a weathervane at (400,100) on the currently active window, showing the orientation of the image associated with a FITS header, hdr IDL> arrows, hdr, 400, 100 METHOD: Uses EXTAST to EXTract ASTrometry from the FITS header. The directions of North and East are computed and the procedure ONE_ARROW called to create the "weathervane". PROCEDURES USED: EXTAST - Extract astrometry structure from FITS header ONE_ARROW - Draw a labeled arrow ZPARCHECK REVISON HISTORY: written by B. Boothman 2/5/86 Recoded with new procedures ONE_ARROW, ONE_RAY. R.S.Hill,HSTX,5/20/92 Added separate determination for N and E arrow to properly display arrows irregardless of handedness or other peculiarities and added /NotVertex keyword to improve positioning of figure. E.Deutsch 1/10/93 Added /DATA and /NORMAL keywords W. Landsman July 1993 Recognize GSSS header W. Landsman June 1993 Added /FONT keyword W. Landsman April 1995 Modified to work correctly for COLOR=0 J.Wm.Parker, HITC 1995 May 25 Work correctly for negative CDELT values W. Landsman Feb. 1996 Converted to IDL V5.0 W. Landsman September 1997 ;- ;+ 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 ;- ;+ NAME: ASTDISP PURPOSE: Print astronomical and pixel coordinates in a standard format EXPLANATION: This procedure (ASTrometry DISPlay) prints the astronomical and pixel coordinates in a standard format. X,Y must be supplied. RA,DEC may also be supplied, and a data number (DN) may also be supplied. With use of the Coords= keyword, a string containing the formatted data can be returned in addition or instead (with /silent) of printing. CALLING SEQUENCE: ASTDISP, x, y, [Ra, Dec, DN, COORD = , /SILENT ] INPUT: X - The X pixel coordinate(s), scalar or vector Y - The Y pixel coordinate(s), scalar or vector OPTIONAL INPUTS: RA - Right Ascention in *degrees*, scalar or vector DEC - DEClination in *degrees*, scalar or vector (if RA is supplied, DEC must also be supplied) DN - Data Number or Flux values Each of the inputs X,Y, RA, DEC, DN should have the same number of elements OPTIONAL INPUT KEYWORDS: SILENT Prevents printing. Only useful when used with Coords= OUTPUT: Printed positions in both degrees and sexigesimal format All passed variables remain unchanged OPTIONAL KEYWORD OUTPUT: COORDS Returns the formatted coordinates in a string PROCEDURES CALLED: ADSTRING - used to format the RA and Dec HISTORY: 10-AUG-90 Version 1 written by Eric W. Deutsch 20-AUG-91 Converted to standard header. Vectorized Code. E. Deutsch 20-NOV-92 Added Coords= and /silent. E.Deutsch Converted to IDL V5.0 W. Landsman September 1997 ;- ;+ NAME: ASTRMFIX PURPOSE: Calculate a rough HST WFPC or FOC astrometry solution EXPLANATION: This program will calculate a rough HST WFPC or FOC astrometry solution using the keyword PSANGLEV3 which gives the angle of the V3 axis of HST. Called by WFPCREAD. CALLING SEQUENCE: AstrmFix, hdr, chip INPUT - OUTPUT: hdr - FITS header (string array) from either WFPC or FOC. Header will be updated with rough astrometry INPUT: chip - Scalar (typically 0-3) giving the WFPC chip to read. PROCEDURES CALLED: EXTAST, SXPAR(), SXADDPAR HISTORY: ??-???-???? Written by Eric W. Deutsch 22-OCT-1992 Changed all calculations to double precision. (E. Deutsch) 22-OCT-1992 Updated PC Pixel size of 0.04389 from WFPC IDT OV/SV manual(EWD) 22-OCT-1992 Updated WF Pixel size of 0.1016 from WFPC IDT OV/SV manual(EWD) 11-JAN-1993 Added warning message and changed CD001001... to CD1_1... (EWD) Converted to IDL V5.0 W. Landsman September 1997 Remove calls to obsolete !ERR variable W. Landsman December 2000 ;- ;+ 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 ;- ;+ NAME: ASTROLIB PURPOSE: Add the non-standard system variables used by the IDL Astronomy Library EXPLANATION: Also defines the environment variable or VMS logical ASTRO_DATA pointing to the directory containing data files associated with the IDL Astronomy library (system dependent). CALLING SEQUENCE: ASTROLIB INPUTS: None. OUTPUTS: None. METHOD: The non-standard system variables !PRIV, !DEBUG, !TEXTUNIT, and !TEXTOUT are added using DEFSYSV. REVISION HISTORY: Written, Wayne Landsman, July 1986. Use DEFSYSV instead of ADDSYSVAR December 1990 Converted to IDL V5.0 W. Landsman September 1997 Test for system variable existence before definition July 2001 ;- ;+ 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 = the x coordinates of the points that trace the rectangular histogram bins YLINES = the y coordinates. To draw the histogram plot ZY vs ZX. 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 ;- ;+ NAME: AVG PURPOSE: Return the average value of an array, or 1 dimension of an array EXPLANATION: Calculate the average value of an array (in which case AVG is identical to the RSI procedure mean.pro), or calculate the average value over one dimension of an array as a function of all the other dimensions. CALLING SEQUENCE: RESULT = AVG( ARRAY, [ DIMENSION, /NAN, /DOUBLE ] ) INPUTS: ARRAY = Input array. May be any type except string. OPTIONAL INPUT PARAMETERS: DIMENSION = Optional dimension to do average over, integer scalar OPTIONAL KEYWORD INPUT: /NAN - Set this keyword to cause the routine to check for occurrences of the IEEE floating-point value NaN in the input data. Elements with the value NaN are treated as missing data. /DOUBLE - By default, if the input Array is double-precision, complex, or double complex, the result is of the same type; 64 bit integers are also returned as double. Otherwise the result the result is floating-point. Use of the /DOUBLE keyword forces a double precision output. Note that internal computations are always done in double precision. OUTPUTS: The average value of the array when called with one parameter. If DIMENSION is passed, then the result is an array with all the dimensions of the input array except for the dimension specified, each element of which is the average of the corresponding vector in the input array. For example, if A is an array with dimensions of (3,4,5), then the command B = AVG(A,1) is equivalent to B = FLTARR(3,5) FOR J = 0,4 DO BEGIN FOR I = 0,2 DO BEGIN B[I,J] = TOTAL( A[I,*,J] ) / 4. ENDFOR ENDFOR RESTRICTIONS: Dimension specified must be valid for the array passed; otherwise the input array is returned as the output array. PROCEDURE: AVG(ARRAY) = TOTAL(ARRAY, /DOUBLE)/N_ELEMENTS(ARRAY) when called with one parameter. MODIFICATION HISTORY: William Thompson Applied Research Corporation July, 1986 8201 Corporate Drive Landover, MD 20785 Converted to Version 2 July, 1990 Replace SUM call with TOTAL W. Landsman May, 1992 Converted to IDL V5.0 W. Landsman September 1997 Added /NAN keyword W. Landsman July 2000 Accept a scalar input value W. Landsman/jimm@berkeley November 2000 Internal calculations always in double precision W. Landsman March 2002 Return NAN if all values in array are NAN W. Landsman April 2002 ;- ;+ NAME: BARYVEL PURPOSE: Calculates heliocentric and barycentric velocity components of Earth. EXPLANATION: BARYVEL takes into account the Earth-Moon motion, and is useful for radial velocity work to an accuracy of ~1 m/s. CALLING SEQUENCE: BARYVEL, dje, deq, dvelh, dvelb, [ JPL = ] INPUTS: DJE - (scalar) Julian ephemeris date. DEQ - (scalar) epoch of mean equinox of dvelh and dvelb. If deq=0 then deq is assumed to be equal to dje. OUTPUTS: DVELH: (vector(3)) heliocentric velocity component. in km/s DVELB: (vector(3)) barycentric velocity component. in km/s The 3-vectors DVELH and DVELB are given in a right-handed coordinate system with the +X axis toward the Vernal Equinox, and +Z axis toward the celestial pole. OPTIONAL KEYWORD SET: JPL - if /JPL set, then BARYVEL will call the procedure JPLEPHINTERP to compute the Earth velocity using the full JPL ephemeris. The JPL ephemeris FITS file JPLEPH.405 must exist in either the current directory, or in the directory specified by the environment variable ASTRO_DATA. Alternatively, the JPL keyword can be set to the full path and name of the ephemeris file. A copy of the JPL ephemeris FITS file is available in http://idlastro.gsfc.nasa.gov/ftp/data/ PROCEDURES CALLED: Function PREMAT() -- computes precession matrix JPLEPHREAD, JPLEPHINTERP, TDB2TDT - if /JPL keyword is set NOTES: Algorithm taken from FORTRAN program of Stumpff (1980, A&A Suppl, 41,1) Stumpf claimed an accuracy of 42 cm/s for the velocity. A comparison with the JPL FORTRAN planetary ephemeris program PLEPH found agreement to within about 65 cm/s between 1986 and 1994 If /JPL is set (using JPLEPH.405 ephemeris file) then velocities are given in the ICRS system; otherwise in the FK4 system. EXAMPLE: Compute the radial velocity of the Earth toward Altair on 15-Feb-1994 using both the original Stumpf algorithm and the JPL ephemeris IDL> jdcnv, 1994, 2, 15, 0, jd ;==> JD = 2449398.5 IDL> baryvel, jd, 2000, vh, vb ;Original algorithm ==> vh = [-17.07809, -22.80063, -9.885281] ;Heliocentric km/s ==> vb = [-17.08083, -22.80471, -9.886582] ;Barycentric km/s IDL> baryvel, jd, 20000, vh, vb, /jpl ;JPL ephemeris ==> vh = [-17.10746, -22.78912, -9.879800] ;Heliocentric km/s ==> vb = [-17.11591, -22.78269, -9.876785] ;Barycentric km/s IDL> ra = ten(19,50,46.77)*15/!RADEG ;RA in radians IDL> dec = ten(08,52,3.5)/!RADEG ;Dec in radians IDL> v = vb(0)*cos(dec)*cos(ra) + $ ;Project velocity toward star vb(1)*cos(dec)*sin(ra) + vb(2)*sin(dec) REVISION HISTORY: Jeff Valenti, U.C. Berkeley Translated BARVEL.FOR to IDL. W. Landsman, Cleaned up program sent by Chris McCarthy (SfSU) June 1994 Converted to IDL V5.0 W. Landsman September 1997 Added /JPL keyword W. Landsman July 2001 ;- ;+ 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. The half-width of the 95% confidence interval = |T_CVF( .95, .7*(N-1) )*SIGMA/SQRT(N)|, where N = number of points. Weights = The weights applied to the data in the last iteration. 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. ;- ;+ 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 ;- ;+ NAME: BOOST_ARRAY PURPOSE: Append one array onto a destination array EXPLANATION: Add array APPEND to array DESTINATION, allowing the dimensions of DESTINATION to adjust to accomodate it. If both input arrays have the same number of dimensions, then the output array will have one additional dimension. Otherwise, the last dimension of DESTINATION will be incremented by one. CATEGOBY: Utility CALLING SEQUENCE: BOOST_ARRAY, DESTINATION, APPEND INPUT: DESTINATION = Array to be expanded. APPEND = Array to append to DESTINATION. OUTPUTS: DESTINATION = Expanded output array. RESTRICTIONS: DESTINATION and APPEND have to be either both of type string or both of numerical types. APPEND cannot have more dimensions than DESTINATION. MODIFICATION HISTOBY: Written Aug'88 (DMZ, ARC) Modified Sep'89 to handle byte arrays (DMZ) Modifed to version 2, Paul Hick (ARC), Feb 1991 Removed restriction to 2D arrays, William Thompson (ARC), Feb 1992. Converted to IDL V5.0 W. Landsman September 1997 ;- ;+ NAME: BOXAVE PURPOSE: Box-average a 1 or 2 dimensional array. EXPLANATION: This procedure differs from the intrinsic REBIN function in the following 2 ways: (1) the box size parameter is specified rather than the output array size (2) for INTEGER arrays, BOXAVE computes intermediate steps using REAL*4 arithmetic. This is considerably slower than REBIN but avoids integer truncation A version of BOXAVE() that supports 64 bit integers is available for V5.4 or later in http://idlastro.gsfc.nasa.gov/ftp/v54/ CALLING SEQUENCE: result = BOXAVE( Array, Xsize,[ Ysize ] ) INPUTS: ARRAY - Two dimensional input Array to be box-averaged. Array may be one or 2 dimensions and of any type except character. OPTIONAL INPUTS: XSIZE - Size of box in the X direction, over which the array is to be averaged. If omitted, program will prompt for this parameter. YSIZE - For 2 dimensional arrays, the box size in the Y direction. If omitted, then the box size in the X and Y directions are assumed to be equal OUTPUT: RESULT - Output array after box averaging. If the input array has dimensions XDIM by YDIM, then RESULT has dimensions XDIM/NBOX by YDIM/NBOX. The type of RESULT is the same as the input array. However, the averaging is always computed using REAL arithmetic, so that the calculation should be exact. If the box size did not exactly divide the input array, then then not all of the input array will be boxaveraged. PROCEDURE: BOXAVE boxaverages all points simultaneously using vector subscripting NOTES: If im_int is a 512 x 512 integer array, then the two statements IDL> im = fix(round(rebin(float(im_int), 128, 128))) IDL> im = boxave( im_int,4) give equivalent results. The use of REBIN is faster, but BOXAVE is is less demanding on virtual memory, since one does not need to make a floating point copy of the entire array. REVISION HISTORY: Written, W. Landsman, October 1986 Call REBIN for REAL*4 and REAL*8 input arrays, W. Landsman Jan, 1992 Removed /NOZERO in output array definition W. Landsman 1995 Fixed occasional integer overflow problem W. Landsman Sep. 1995 Allow unsigned data types W. Landsman Jan. 2000 ;- ;+ NAME: BPRECESS PURPOSE: Precess positions from J2000.0 (FK5) to B1950.0 (FK4) EXPLANATION: Calculates the mean place of a star at B1950.0 on the FK4 system from the mean place at J2000.0 on the FK5 system. CALLING SEQUENCE: bprecess, ra, dec, ra_1950, dec_1950, [ MU_RADEC = , PARALLAX = RAD_VEL =, EPOCH = ] INPUTS: RA,DEC - Input J2000 right ascension and declination in *degrees*. Scalar or N element vector OUTPUTS: RA_1950, DEC_1950 - The corresponding B1950 right ascension and declination in *degrees*. Same number of elements as RA,DEC but always double precision. OPTIONAL INPUT-OUTPUT KEYWORDS MU_RADEC - 2xN element double precision vector containing the proper motion in seconds of arc per tropical *century* in right ascension and declination. PARALLAX - N_element vector giving stellar parallax (seconds of arc) RAD_VEL - N_element vector giving radial velocity in km/s The values of MU_RADEC, PARALLAX, and RADVEL will all be modified upon output to contain the values of these quantities in the B1950 system. The parallax and radial velocity will have a very minor influence on the B1950 position. EPOCH - scalar giving epoch of original observations, default 2000.0d This keyword value is only used if the MU_RADEC keyword is not set. NOTES: The algorithm is taken from the Explanatory Supplement to the Astronomical Almanac 1992, page 186. Also see Aoki et al (1983), A&A, 128,263 BPRECESS distinguishes between the following two cases: (1) The proper motion is known and non-zero (2) the proper motion is unknown or known to be exactly zero (i.e. extragalactic radio sources). In this case, the reverse of the algorithm in Appendix 2 of Aoki et al. (1983) is used to ensure that the output proper motion is exactly zero. Better precision can be achieved in this case by inputting the EPOCH of the original observations. The error in using the IDL procedure PRECESS for converting between B1950 and J1950 can be up to 1.5", mainly in right ascension. If better accuracy than this is needed then BPRECESS should be used. An unsystematic comparison of BPRECESS with the IPAC precession routine (http://nedwww.ipac.caltech.edu/forms/calculator.html) always gives differences less than 0.15". EXAMPLE: The SAO2000 catalogue gives the J2000 position and proper motion for the star HD 119288. Find the B1950 position. RA(2000) = 13h 42m 12.740s Dec(2000) = 8d 23' 17.69'' Mu(RA) = -.0257 s/yr Mu(Dec) = -.090 ''/yr IDL> mu_radec = 100D* [ -15D*.0257, -0.090 ] IDL> ra = ten(13, 42, 12.740)*15.D IDL> dec = ten(8, 23, 17.69) IDL> bprecess, ra, dec, ra1950, dec1950, mu_radec = mu_radec IDL> print, adstring(ra1950, dec1950,2) ===> 13h 39m 44.526s +08d 38' 28.63" REVISION HISTORY: Written, W. Landsman October, 1992 Vectorized, W. Landsman February, 1994 Treat case where proper motion not known or exactly zero November 1994 Handling of arrays larger than 32767 Lars L. Christensen, march, 1995 Converted to IDL V5.0 W. Landsman September 1997 Fixed bug where A term not initialized for vector input W. Landsman February 2000 ;- ;+ NAME: BREAK_PATH() PURPOSE: Breaks up a path string into its component directories. CALLING SEQUENCE: Result = BREAK_PATH( PATHS [ /NoCurrent]) INPUTS: PATHS = A string containing one or more directory paths. The individual paths are separated by commas, although in UNIX, colons can also be used. In other words, PATHS has the same format as !PATH, except that commas can be used as a separator regardless of operating system. A leading $ can be used in any path to signal that what follows is an environmental variable, but the $ is not necessary. (In VMS the $ can either be part of the path, or can signal logical names for compatibility with Unix.) Environmental variables can themselves contain multiple paths. OUTPUT: The result of the function is a string array of directories. Unless the NOCURRENT keyword is set, the first element of the array is always the null string, representing the current directory. All the other directories will end in the correct separator character for the current operating system. OPTIONAL INPUT KEYWORD: /NOCURRENT = If set, then the current directory (represented by the null string) will not automatically be prepended to the output. PROCEDURE CALLS: Functions: STR_SEP() V5.3 or earlier REVISION HISTORY: Version 1, William Thompson, GSFC, 6 May 1993. Added IDL for Windows compatibility. Version 2, William Thompson, GSFC, 16 May 1995 Added keyword NOCURRENT Version 3, William Thompson, GSFC, 29 August 1995 Modified to use OS_FAMILY Version 4, Zarro, GSFC, 4 August 1997 Added trim to input Converted to IDL V5.0 W. Landsman 25-Nov-1997 Fix directory character on Macintosh system A. Ferro February 2000 Use STRSPLIT instead of STR_SEP W. Landsman July 2002 ;- ;+ NAME: BSORT PURPOSE: Function to sort data into ascending order, like a simple bubble sort. EXPLANATION: Original subscript order is maintained when values are equal (FIFO). (This differs from the IDL SORT routine alone, which may rearrange order for equal values) CALLING SEQUENCE: result = bsort( array, [ asort, /INFO, /REVERSE ] ) INPUT: Array - array to be sorted OUTPUT: result - sort subscripts are returned as function value OPTIONAL OUTPUT: Asort - sorted array OPTIONAL KEYWORD INPUTS: /REVERSE - if this keyword is set, and non-zero, then data is sorted in descending order instead of ascending order. /INFO = optional keyword to cause brief message about # equal values. HISTORY written by F. Varosi Oct.90: uses WHERE to find equal clumps, instead of looping with IF ( EQ ). compatible with string arrays, test for degenerate array 20-MAY-1991 JKF/ACC via T AKE- return indexes if the array to be sorted has all equal values. Aug - 91 Added REVERSE keyword W. Landsman Always return type LONG W. Landsman August 1994 Converted to IDL V5.0 W. Landsman September 1997 ;- ;+ 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 ;- ;+ 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. 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 ;- ;+ NAME: CHECK_FITS PURPOSE: Check that keywords in a FITS header array match the associated data EXPLANATION: Given a FITS array IM, and a associated FITS or STSDAS header HDR, this procedure will check that (1) HDR is a string array, and IM is defined and numeric (2) The NAXISi values in HDR are appropriate to the dimensions of IM (3) The BITPIX value in HDR is appropriate to the datatype of IM If HDR contains a DATATYPE keyword (as in STSDAS headers), then this is also checked against the datatype of of IM If the /UPDATE keyword is present, then the FITS header will be modified, if necessary, to force agreement with the image array CALLING SEQUENCE: check_FITS, im, hdr, [ dimen, idltype, /UPDATE, /NOTYPE, /SDAS, /SILENT ERRMSG = ]' INPUT PARAMETERS: IM - FITS (or STSDAS) array, e.g. as read by READFITS HDR - FITS (or STSDAS) header (string array) associated with IM OPTIONAL OUTPUTS: dimen - vector containing actual array dimensions idltype- data type of the FITS array as specified in the IDL SIZE function (1 for BYTE, 2 for INTEGER*2, 3 for INTEGER*4, etc.) OPTIONAL KEYWORD INPUTS: /NOTYPE - If this keyword is set, then only agreement of the array dimensions with the FITS header are checked, and not the data type. /UPDATE - If this keyword is set then the BITPIX, NAXIS and DATATYPE FITS keywords will be updated to agree with the array /SDAS - If this keyword is set then the header is assumed to be from an SDAS (.hhh) file. CHECK_FITS will then ensure that (1) a DATATYPE keyword is included in the header and (2) BITPIX is always written with positive values. /FITS - If this keyword is present then CHECK_FITS assumes that it is dealing with a FITS header and not an SDAS header, see notes below. /SILENT - If keyword is set and nonzero, the informational messages will not be printed 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. SYSTEM VARIABLE: For consistency with previous versions, CHECK_FITS sets the obsolete !ERR keyword, although its use is discouraged in favor of the ERRMSG keyword. If there is a fatal problem with the FITS array or header then !ERR is set to -1. ( If the UPDATE keyword was supplied, and the header could be fixed, then !ERR = 0.) PROCEDURE: Program checks the NAXIS1 and NAXIS2 parameters in the header to see if they match the image array dimensions. NOTES: An important distinction between an STSDAS header and a FITS header is that the BITPIX value in an STSDAS header is always positive, e.g. BITPIX=32 for REAL*4 data. Users should use either the /SDAS or the /FITS keyword if it is important whether the STSDAS or FITS convention for REAL*4 data is used. Otherwise, CHECK_FITS assumes that if a DATATYPE keyword is present then it is dealing with an STSDAS header. PROCEDURE CALLS: STRN(),FXADDPAR, fxpar() 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 ;- ;+ 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://www.cv.nrao.edu/fits/documents/proposals/checksum/ CALLING SEQUENCE: CHECKSUM32, array, checksum INPUTS: array - any idl array. The number of bytes in the array must be a multiple of four. OUTPUTS: checksum - unsigned long scalar, giving sum of array elements using ones-complement arithmetic METHOD: Uses TOTAL() to sum the array into a double precision variable. The overflow bits beyond 2^32 are then shifted back to the least significant bits. Due to the limited precision of a DOUBLE variable, the summing is done in chunks determined by MACHAR(). Adapted from FORTRAN code in heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/general/checksum/node30.html Could probably be done in a cleverer way (similar to the C implementation) but then the array-oriented TOTAL() function could not be used. RESTRICTIONS: (1) Requires V5.2 or later (uses unsigned integers) (2) Not valid for object or pointer data types FUNCTION CALLED: N_BYTES() MODIFICATION HISTORY: Written W. Landsman June 2001 ;- ;+ 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 ;- ;+ 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, Hughex STX, May 1996 Converted to IDL V5.0 W. Landsman September 1997 ;- ;+ 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 ;- ;+ NAME: CNTRD PURPOSE: Compute the centroid coordinates of a stellar object EXPLANATION: CNTRD uses the 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 , /SILENT, /DEBUG] INPUTS: IMG - Two dimensional image array X,Y - Scalar or vector integers giving approximate stellar center OPTIONAL INPUT: FWHM - floating scalar; Centroid is computed using a box of half width equal to 1.5 sigma = 0.637* FWHM. CNTRD will prompt for FWHM if not supplied OUTPUTS: XCEN - the computed X centroid position, same number of points as X YCEN - computed Y centroid position, same number of points as Y Values for XCEN and YCEN will not be computed if the computed centroid falls outside of the box, or if the computed derivatives are non-decreasing. If the centroid cannot be computed, then a message is displayed and XCEN and YCEN are set to -1. OPTIONAL OUTPUT KEYWORDS: /SILENT - Normally CNTRD prints an error message if it is unable to compute the centroid. Set /SILENT to suppress this. /DEBUG - If this keyword is set, then CNTRD will display the subarray it is using to compute the centroid. PROCEDURE: Maximum pixel within distance from input pixel X, Y determined from FHWM is found and used as the center of a square, within which the centroid is computed as the value (XCEN,YCEN) at which the derivatives of the partial sums of the input image over (y,x) with respect to (x,y) = 0. MODIFICATION HISTORY: Written 2/25/86, by J. K. Hill, S.A.S.C., following algorithm used by P. Stetson in DAOPHOT. Allowed input vectors G. Hennessy April, 1992 Fixed to prevent wrong answer if floating pt. X & Y supplied W. Landsman March, 1993 Convert byte, integer subimages to float W. Landsman May 1995 Converted to IDL V5.0 W. Landsman September 1997 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 ;- ;+ NAME: CO_ABERRATION PURPOSE: Calculate changes to Ra and Dec due to "the effect of 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, ra and dec MUST be vectors of the same length. OUTPUTS d_ra, d_dec: the corrections to ra and dec due to aberration (must then be added to ra and dec to get corrected values). 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" 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" d_dec = 6.697" NOTES: These formula are from Meeus, Chapters 23. Accuracy is much better than 1 arcsecond. REVISION HISTORY: Written, June 2002, Chris O'Dell, U. of Wisconsin ;- ;+ 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 ;- ;+ 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 ;- ;+ NAME: COMPARE_STRUCT PURPOSE: Compare all matching tag names and return differences EXPLANATION: Compare all matching Tags names (except for "except_Tags") between two structure arrays (may be different struct.defs.), and return a structured List of fields found different. CATEGORY: Structures CALLING SEQUENCE: diff_List = compare_struct( struct_A, struct_B ) INPUTS: struct_A, struct_B : the two structure arrays to compare. Struct_Name : for internal recursion use only. KeyWords: EXCEPT = string array of Tag names to ignore (NOT to compare). /BRIEF = number of differences found for each matching field of two structures is printed. /FULL = option to print even if zero differences found. /RECUR_A = option to search for Tag names in sub-structures of struct_A, and then call compare_struct recursively for those nested sub-structures. /RECUR_B = search for sub-structures of struct_B, and then call compare_struct recursively for those nested sub-structures. Note: compare_struct is automatically called recursively for those nested sub-structures in both struct_A and struct_B (otherwise cannot take difference) OUTPUT: Returns a structure array describing differences found, which can be examined using print,diff_List or help,/st,diff_List. PROCEDURE: Match Tag names and then use where function on tags. MODIFICATION HISTORY: written 1990 Frank Varosi STX @ NASA/GSFC (using copy_struct) modif Aug.90 by F.V. to check and compare same # of elements only. Converted to IDL V5.0 W. Landsman September 1997 ;- ;+ NAME: CONCAT_DIR PURPOSE: To concatenate directory and file names for current OS. EXPLANATION: The given file name is appended to the given directory name with the format appropriate to the current operating system. CALLING SEQUENCE: result = concat_dir( directory, file) INPUTS: directory - the directory path (string) file - the basic file name and extension (string) can be an array of filenames. OUTPUTS: The function returns the concatenated string. If the file input is a string array then the output will be a string array also. EXAMPLES: IDL> pixfile = concat_dir('$DIR_GIS_MODEL','pixels.dat') IDL> file = ['f1.dat','f2.dat','f3.dat'] IDL> dir = '$DIR_NIS_CAL' IDL> f = concat_dir(dir,file) RESTRICTIONS: Assumes Unix type format if os is not vms, MacOS or Windows. 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 ;- ;+ NAME: CONS_DEC PURPOSE: Obtain the X and Y coordinates of a line of constant declination EXPLANATION: Returns a set of Y pixels values, given an image with tangent projection astrometry, and either (1) A set of X pixel values, and a scalar declination value, or (2) A set of declination values, and a scalar X value Form (1) can be used to find the (X,Y) values of a line of constant declination. Form (2) can be used to find the Y positions of a set declinations, along a line of constant X. CALLING SEQUENCE: Y = CONS_DEC( DEC, X, CD, ASTR, [ ALPHA ]) INPUTS: DEC - Declination value(s) in DEGREES (-!PI/2 < DEC < !PI/2). If X is a vector, then DEC must be a scalar. X - Specified X pixel value(s) for line of constant declination If DEC is a vector, then X must be a scalar. ASTR - Astrometry structure, as extracted from a FITS header by the procedure EXTAST OUTPUT: Y - Computed set of Y pixel values. The number of Y values is the same as either DEC or X, whichever is greater. OPTIONAL OUTPUT: ALPHA - the right ascensions (DEGREES) associated with the (X,Y) points RESTRICTIONS: Implemented only for the TANgent and SIN projections NOTES: The algorithm (and notation) is based on AIPS Memo 27 by Eric Greisen, with modifications for a coordinate description (CD) matrix as described in Paper II of Greisen & Calabretta (2002, A&A, in press). 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 ;- ;+ NAME: CONS_RA PURPOSE: Obtain the X and Y coordinates of a line of constant right ascension EXPLANATION: Return a set of X pixel values given an image with astrometry, and either (1) a set of Y pixel values, and a scalar right ascension, or (2) a set of right ascension values, and a scalar Y value. In usage (1), CONS_RA can be used to determine the (X,Y) values of a line of constant right ascension. In usage (2), CONS_RA can used to determine the X positions of specified RA values, along a line of constant Y. CALLING SEQUENCE: X = CONS_RA( RA, Y, ASTR, [ 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 Greisen & Calabretta (2002, A&A, in press). These documents are available from http://www.cv.nrao.edu/fits/documents/wcs/wcs.html RESTRICTIONS: Implemented only for the TANgent and SIN projections REVISION HISTORY: Written, Wayne Landsman STX Co. April, 1988 Algorithm adapted from AIPS memo No. 27 by Eric Griessen New astrometry structure Converted to IDL V5.0 W. Landsman September 1997 Added SIN projection W. Landsman January 2000 Fix possible sign error introduced Jan. 2000 W. Landsman May 2000 ;- ;+ NAME: CONV_STSDAS PURPOSE: Convert internal format of an STSDAS image to host machine architecture EXPLANATION: Converts the internal format of an STSDAS image (.hhh and .hhd file) to the host machine architecture. Useful for copying STSDAS files between different machines. If the host is not a VMS machine, then by default CONV_STSDAS assumes the image originated on VMS. If the host is VMS, then CONV_STSDAS assumes that the image originated on an IEEE machine (e.g. SparcStation). CALLING SEQUENCE: CONV_STSDAS, sdas_name, [ /FROM_IEEE] INPUTS: sdas_name - scalar string giving name of the STSDAS image CONV_STSDAS assumes a default header extension of .hhh -- otherwise the header extension should be included in sdas_name. The internal format of the file will be modified by CONV_STSDAS. OPTIONAL KEYWORD INPUT: /FROM_IEEE - On little endian machines (OSF, windows) this keyword indicates that the STSDAS file originated on an IEEE machine (e.g SparcStation) rather than a VMS machine EXAMPLE: Suppose files test.hhd and test.hhh have been copied with FTP from a Vax to a Sparcstation. Convert these files to the SparcStation internal format. IDL> conv_stsdas, 'test' METHOD: CONV_STSDAS reads each group image and parameter block and uses IEEE_TO_HOST or CONV_VAX_UNIX to convert the internal format. The converted images and parameter blocks are written back to the orginal file. PROCEDURE CALLS sxopen, fdecomp, sxgpar(), sxpar(), ieee_to_host, conv_vax_unix() NOTES: (1) When copying STSDAS files to VMS, be sure the .hhh file is formatted as fixed block 80 byte. (2) CONV_STSDAS has no way of knowing if a file really came from a different machine architecture. If it is applied to a file that already has the correct internal format, then CONV_STSDAS will "convert" this file and corrupt the internal format. (3) Note that CONV_STSDAS currently does not support conversion *from* a little-endian machine (OSF, windows) REVISION HISTORY: Written W. Landsman January, 1993 Don't require .hhh extension April, 1993 Increase speed by calling SXGINFO May, 1993 Converted to IDL V5.0 W. Landsman September 1997 Replace DATATYPE() with size(/TNAME) W. Landsman November 2001 ;- ;+ NAME: CONV_UNIX_VAX PURPOSE: To convert Unix IDL data types to Vax IDL data types. EXPLANATION: CONV_UNIX_VAX assumes the Unix IDL data type is IEEE standard in either big-endian or little-endian format. CALLING SEQUENCE: CONV_UNIX_VAX, variable, [ SOURCE_ARCH = ] PARAMETERS: variable - The data variable to be converted. This may be a scalar or an array. Valid datatypes are integer, longword, floating point, and double precision. The result of the conversion is passed back in the original variable. OPTIONAL INPUT KEYWORD: SOURCE_ARCH = name (string) of source architecture if using this function on a VAX, otherwise !VERSION.ARCH is used to determine the conversion. **If run on a VAX, the default is to assume the source to be a little-endian machine with IEEE floating point (e.g. MIPSEL or Alpha***). RESTRICTIONS: Requires that data be from IEEE standard Unix machines (e.g. SUN, MIPSEL, or Alpha). EXAMPLE: Read a 100 by 100 matrix of floating point numbers from a data file created on a Sun. Then convert the matrix values into VAX format. IDL> openr,1,'vax_float.dat IDL> data = fltarr(100,100) IDL> forrd,1,data IDL> CONV_UNIX_VAX,data,SOURCE_ARCH='sparc' MODIFICATION HISTORY: Version 1 By John Hoegy 13-Jun-88 04-May-90 - WTT: Created CONV_UNIX_VAX from VAX2SUN, reversing floating point procedure. Modified P. Keegstra September 1994 Implemented MIPSEL and ALPHA architecture, distinguishing VMS and OSF Modified P. Keegstra February 1995 Added 386 PC based architectures If since V5.1 then VMS is always little endian June 1998 Convert to IDL V5.0 W. Landsman June 1998 ;- ;+ NAME: CONV_VAX_UNIX PURPOSE: To convert VAX IDL data types to UNIX (Sun,MIPS,etc.) IDL data types. EXPLANTION: Generally used on non-Vax machines to parse data created on Vaxes. The architecture is obtained from IDL sys.var. !VERSION.ARCH. CALLING SEQUENCE: var_unix = conv_vax_unix( var_vax, [TARGET_ARCH = ] ) INPUT PARAMETER: var_vax - The data variable to be converted. This may be a scalar or an array. All IDL datatypes are valid (including structures). The result of the conversion is returned by the function. OPTIONAL INPUT KEYWORD: TARGET_ARCH = name (string) of desired target architecture (e.g. 'sparc' or 'mipsel'). If not supplied, then !VERSION.ARCH is used to determine the target architecture. Note that CONV_VAX_UNIX will leave variables unchanged on a VMS machine, unless the TARGET_ARCH keyword is set. EXAMPLE: Read a 100 by 100 matrix of floating point numbers from a data file created on a VAX. Then convert the matrix values into Sun format. IDL> openr,1,'vax_float.dat' IDL> data = fltarr(100,100) IDL> readu,1,data IDL> data = conv_vax_unix( data ) NOTE: Prior to IDL V5.1, the architecture "alpha" was ambiguous, since VMS alpha IDL used VAX D-float while OSF/1 alpha IDL uses little-endian IEEE. The program uses !VERSION.OS to do the right thing when converting to a representation appropriate for the current platform. To convert to a representation appropriate for an OSF/1 alpha on a VAX or (pre V5.1) VMS alpha, please specify the "mipsel" (or "i386") architecture. MODIFICATION HISTORY: Written F. Varosi August 1990 Modified P. Keegstra April 1992 Implemented MIPSEL architecture Modified P. Keegstra July 1994 Implemented ALPHA architecture, distinguishing VMS and OSF Modified P. Keegstra February 1995 Added 386 PC based architectures Modified P. Keegstra March 1995 Added note, restored and fixed old specifiers for 386 PC based architectures Modified W. Landsman for VAX problems in V4.0 August 1995 Work for double complex variables August 1995 Remove informational messages under VMS August 1997 Since V5.1, IDL VMS uses little endian IEEE June 1998 Convert to IDL V5.0 June 1998 ;- ;+ NAME: CONVOLVE PURPOSE: Convolution of an image with a Point Spread Function (PSF) EXPLANATION: The default is to compute the convolution using a product of Fourier transforms (for speed). CALLING SEQUENCE: imconv = convolve( image1, psf, FT_PSF = psf_FT ) or: correl = convolve( image1, image2, /CORREL ) or: correl = convolve( image, /AUTO ) INPUTS: image = 2-D array (matrix) to be convolved with psf psf = the Point Spread Function, (size < or = to size of image). OPTIONAL INPUT KEYWORDS: FT_PSF = passes out/in the Fourier transform of the PSF, (so that it can be re-used the next time function is called). FT_IMAGE = passes out/in the Fourier transform of image. /CORRELATE uses the conjugate of the Fourier transform of PSF, to compute the cross-correlation of image and PSF, (equivalent to IDL function convol() with NO rotation of PSF) /AUTO_CORR computes the auto-correlation function of image using FFT. /NO_FT overrides the use of FFT, using IDL function convol() instead. (then PSF is rotated by 180 degrees to give same result) METHOD: When using FFT, PSF is centered & expanded to size of image. HISTORY: written, Frank Varosi, NASA/GSFC 1992. Converted to IDL V5.0 W. Landsman September 1997 ;- ;+ NAME: COPY_STRUCT PURPOSE: Copy all fields with matching tag names from one structure to another EXPLANATION Fields with matching tag names are copied from one structure array to another structure array of different type. This allows copying of tag values when equating the structures of different types is not allowed, or when not all tags are to be copied. Can also recursively copy from/to structures nested within structures. Note that the number of elements in the output structure array is automatically adjusted to equal the length of input structure array. If this not desired then use pro copy_struct_inx which allows specifying via subscripts which elements are copied where in the arrays. CALLING SEQUENCE: copy_struct, struct_From, struct_To, NT_copied copy_struct, struct_From, struct_To, EXCEPT=["image","misc"] copy_struct, struct_From, struct_To, /RECUR_TANDEM INPUTS: struct_From = structure array to copy from. struct_To = structure array to copy values to. KEYWORDS: EXCEPT_TAGS = string array of tag names to ignore (to NOT copy). Used at all levels of recursion. SELECT_TAGS = tag names to copy (takes priority over EXCEPT). This keyword is not passed to recursive calls in order to avoid the confusion of not copying tags in sub-structures. /RECUR_FROM = search for sub-structures in struct_From, and then call copy_struct recursively for those nested structures. /RECUR_TO = search for sub-structures of struct_To, and then call copy_struct recursively for those nested structures. /RECUR_TANDEM = call copy_struct recursively for the sub-structures with matching Tag names in struct_From and struct_To (for use when Tag names match but sub-structure types differ). OUTPUTS: struct_To = structure array to which new tag values are copied. NT_copied = incremented by total # of tags copied (optional) INTERNAL: Recur_Level = # of times copy_struct calls itself. This argument is for internal recursive execution only. The user call is 1, subsequent recursive calls increment it, and the counter is decremented before returning. The counter is used just to find out if argument checking should be performed, and to set NT_copied = 0 first call. EXTERNAL CALLS: pro match (when keyword SELECT_TAGS is specified) PROCEDURE: Match Tag names and then use corresponding Tag numbers. HISTORY: written 1989 Frank Varosi STX @ NASA/GSFC mod Jul.90 by F.V. added option to copy sub-structures RECURSIVELY. mod Aug.90 by F.V. adjust # elements in TO (output) to equal # elements in FROM (input) & count # of fields copied. mod Jan.91 by F.V. added Recur_Level as internal argument so that argument checking done just once, to avoid confusion. Checked against Except_Tags in RECUR_FROM option. mod Oct.91 by F.V. added option SELECT_TAGS= selected field names. mod Aug.95 by W. Landsman to fix match of a single selected tag. mod Mar.97 by F.V. do not pass the SELECT_TAGS keyword in recursion. Converted to IDL V5.0 W. Landsman September 1997 mod May 01 by D. Schlegel use long integers ;- ;+ 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 ;- ;+ 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 ;- ;+ 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 ;- ;+ 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 ;- ;+ 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 cosmolgical constant, Omega_lambda (2) 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 Caroll, 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.5 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 parmeter, 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 ;- ;+ 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