Last modified: Tue Aug 7 08:53:42 2007.
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
(See ../pfidl/astro_lib/check_fits.pro)
NAME: CONVOLVE PURPOSE: Convolution of an image with a Point Spread Function (PSF) EXPLANATION: The default is to compute the convolution using a product of Fourier transforms (for speed). CALLING SEQUENCE: imconv = convolve( image1, psf, FT_PSF = psf_FT ) or: correl = convolve( image1, image2, /CORREL ) or: correl = convolve( image, /AUTO ) INPUTS: image = 2-D array (matrix) to be convolved with psf psf = the Point Spread Function, (size < or = to size of image). OPTIONAL INPUT KEYWORDS: FT_PSF = passes out/in the Fourier transform of the PSF, (so that it can be re-used the next time function is called). FT_IMAGE = passes out/in the Fourier transform of image. /CORRELATE uses the conjugate of the Fourier transform of PSF, to compute the cross-correlation of image and PSF, (equivalent to IDL function convol() with NO rotation of PSF) /AUTO_CORR computes the auto-correlation function of image using FFT. /NO_FT overrides the use of FFT, using IDL function convol() instead. (then PSF is rotated by 180 degrees to give same result) METHOD: When using FFT, PSF is centered & expanded to size of image. HISTORY: written, Frank Varosi, NASA/GSFC 1992. Converted to IDL V5.0 W. Landsman September 1997
(See ../pfidl/astro_lib/convolve.pro)
NAME: CORREL_OPTIMIZE PURPOSE: Find the optimal (x,y) pixel offset of image_B relative to image_A EXPLANATION" Optimal offset is computed by means of maximizing the correlation function of the two images. CALLING SEQUENCE: CORREL_OPTIMIZE, image_A, image_B, xoffset_optimum, yoffset_optimum [ XOFF_INIT=, YOFF_INIT=, MAGNIFICATION=, /PRINT, /NUMPIX, /MONITOR, PLATEAU_THRESH= ] INPUTS: image_A, image_B = the two images of interest. OPTIONAL INPUT KEYWORDS: XOFF_INIT = initial X pixel offset of image_B relative to image_A, YOFF_INIT = Y pixel offset, (default offsets are 0 and 0). MAGNIFICATION = option to determine offsets up to fractional pixels, (example: MAG=2 means 1/2 pixel accuracy, default=1). /NUMPIX: sqrt( sqrt( # pixels )) used as correlation weighting factor. /MONITOR causes the progress of computation to be briefly printed. /PRINT causes the results of analysis to be printed. PLATEAU_THRESH = threshold used for detecting plateaus in the cross-correlation matrix near maximum, (default=0.01), used only if MAGNIFICATION > 1. Decrease this value for high signal-to-noise data OUTPUTS: xoffset_optimum = optimal X pixel offset of image_B relative to image_A. yoffset_optimum = optimal Y pixel offset. CALLS: function correl_images( image_A, image_B ) pro corrmat_analyze PROCEDURE: The combination of function correl_images( image_A, image_B ) and corrmat_analyze of the result is used to obtain the (x,y) offset yielding maximal correlation. The combination is first executed at large REDUCTION factors to speed up computation, then zooming in recursively on the optimal (x,y) offset by factors of 2. Finally, the MAGNIFICATION option (if specified) is executed to determine the (x,y) offset up to fractional pixels. MODIFICATION HISTORY: Written, July,1991, Frank Varosi, STX @ NASA/GSFC Added PLATEAU_THRESH keyword June 1997, Wayne Landsman STX Converted to IDL V5.0 W. Landsman September 1997
(See ../pfidl/astro_lib/correl_optimize.pro)
NAME: DAYCNV PURPOSE: Converts Julian dates to Gregorian calendar dates CALLING SEQUENCE: DAYCNV, XJD, YR, MN, DAY, HR INPUTS: XJD = Julian date, positive double precision scalar or vector OUTPUTS: YR = Year (Integer) MN = Month (Integer) DAY = Day (Integer) HR = Hours and fractional hours (Real). If XJD is a vector, then YR,MN,DAY and HR will be vectors of the same length. EXAMPLE: IDL> DAYCNV, 2440000.D, yr, mn, day, hr yields yr = 1968, mn =5, day = 23, hr =12. WARNING: Be sure that the Julian date is specified as double precision to maintain accuracy at the fractional hour level. METHOD: Uses the algorithm of Fliegel and Van Falndern (1968) as reported in the "Explanatory Supplement to the Astronomical Almanac" (1992), p. 604 Works for all Gregorian calendar dates with XJD > 0, i.e., dates after -4713 November 23. REVISION HISTORY: Converted to IDL from Yeoman's Comet Ephemeris Generator, B. Pfarr, STX, 6/16/88 Converted to IDL V5.0 W. Landsman September 1997
(See ../pfidl/astro_lib/daycnv.pro)
NAME: FITS_ADD_CHECKSUM PURPOSE: Add or update the CHECKSUM and DATASUM keywords in a FITS header EXPLANATION: Follows the 23 May 2002 version of the FITS checksum proposal at http://heasarc.gsfc.nasa.gov/docs/heasarc/fits/checksum.html CALLING SEQUENCE: FITS_ADD_CHECKSUM, Hdr, [ Data, /No_TIMESTAMP, /FROM_IEEE ] INPUT-OUTPUT: Hdr - FITS header (string array), it will be updated with new (or modfied) CHECKSUM and DATASUM keywords OPTIONAL INPUT: Data - data array associated with the FITS header. If not supplied, or set to a scalar, then the program checks whether there is a DATASUM keyword already in the FITS header containing the 32bit checksum for the data. if there is no such keyword then ther assumed to be no data array associated with the FITS header. OPTIONAL INPUT KEYWORDS: /FROM_IEEE - If this keyword is set, then the input is assumed to be in big endian format (e.g. an untranslated FITS array). This keyword only has an effect on little endian machines (e.g. a Linux box). /No_TIMESTAMP - If set, then a time stamp is not included in the comment field of the CHECKSUM and DATASUM keywords. Unless the /No_TIMESTAMP keyword is set, repeated calls to FITS_ADD_CHECKSUM with the same header and data will yield different values of CHECKSUM (as the date stamp always changes). However, use of the date stamp is recommended in the checksum proposal. PROCEDURES USED: CHECKSUM32, FITS_ASCII_ENCODE(), GET_DATE, SXADDPAR, SXPAR() REVISION HISTORY: W. Landsman SSAI December 2002
(See ../pfidl/astro_lib/fits_add_checksum.pro)
NAME: FITS_CLOSE *PURPOSE: Close a FITS data file *CATEGORY: INPUT/OUTPUT *CALLING SEQUENCE: FITS_CLOSE,fcb *INPUTS: FCB: FITS control block returned by FITS_OPEN. *KEYWORD PARAMETERS: /NO_ABORT: Set to return to calling program instead of a RETALL when an I/O error is encountered. If set, the routine will return a non-null string (containing the error message) in the keyword MESSAGE. (For backward compatibility, the obsolete system variable !ERR is also set to -1 in case of an error.) If /NO_ABORT not set, then FITS_CLOSE will print the message and issue a RETALL MESSAGE = value: Output error message *EXAMPLES: Open a FITS file, read some data, and close it with FITS_CLOSE FITS_OPEN,'infile',fcb FITS_READ,fcb,data FITS_READ,fcb,moredata FITS_CLOSE,fcb *HISTORY: Written by: D. Lindler August, 1995 Converted to IDL V5.0 W. Landsman September 1997 Do nothing if fcb an invalid structure D. Schlegel/W. Landsman Oct. 2000 Return Message='' for to signal normal operation W. Landsman Nov. 2000
(See ../pfidl/astro_lib/fits_close.pro)
NAME: FITS_HELP *PURPOSE: To print a summary of the primary data units and extensions in a FITS file. *CATEGORY: INPUT/OUTPUT *CALLING SEQUENCE: FITS_HELP,filename_or_fcb *INPUTS: FILENAME_OR_FCB - name of the fits file or the FITS Control Block (FCB) returned by FITS_OPEN. For versions since V5.3, the file name is allowed to be gzip compressed (with a .gz extension) *OUTPUTS: a summary of the fits file is printed. *EXAMPLES: FITS_HELP,'myfile.fits' FITS_OPEN,'anotherfile.fits',fcb FITS_HELP,fcb *PROCEDURES USED: FITS_OPEN, FITS_CLOSE *HISTORY: Written by: D. Lindler August, 1995 Converted to IDL V5.0 W. Landsman September 1997
(See ../pfidl/astro_lib/fits_help.pro)
NAME: FITS_INFO PURPOSE: Provide information about the contents of a FITS file EXPLANATION: Information includes number of header records and size of data array. Applies to primary header and all extensions. Information can be printed at the terminal and/or stored in a common block CALLING SEQUENCE: FITS_INFO, Filename, [ /SILENT , TEXTOUT = , N_ext = ] INPUT: Filename - Scalar string giving the name of the FITS file(s) Can include wildcards such as '*.fits'. In IDL V5.5 one can use the regular expressions allowed by the FILE_SEARCH() function. Since V5.3 one can also search gzip compressed FITS files. OPTIONAL INPUT KEYWORDS: /SILENT - If set, then the display of the file description on the terminal will be suppressed TEXTOUT - specifies output device. textout=1 TERMINAL using /more option textout=2 TERMINAL without /more option textout=3.prt textout=4 laser.tmp textout=5 user must open file, see TEXTOPEN textout=7 append to existing file textout = filename (default extension of .prt) If TEXTOUT is not supplied, then !TEXTOUT is used OPTIONAL OUTPUT KEYWORD: N_ext - Returns an integer scalar giving the number of extensions in the FITS file COMMON BLOCKS DESCRIPTOR = File descriptor string of the form N_hdrrec Naxis IDL_type Naxis1 Naxis2 ... Naxisn [N_hdrrec table_type Naxis IDL_type Naxis1 ... Naxisn] (repeated for each extension) See the procedure RDFITS_STRUCT for an example of the use of this common block EXAMPLE: Display info about all FITS files of the form '*.fit' in the current directory IDL> fits_info, '*.fit' Any time a *.fit file is found which is *not* in FITS format, an error message is displayed at the terminal and the program continues PROCEDURES USED: GETTOK(), MRD_SKIP, STRN(), SXPAR(), TEXTOPEN, TEXTCLOSE SYSTEM VARIABLES: The non-standard system variables !TEXTOUT and !TEXTUNIT will be created by FITS_INFO if they are not previously defined. DEFSYSV,'!TEXTOUT',1 DEFSYSV,'!TEXTUNIT',0 See TEXTOPEN.PRO for more info MODIFICATION HISTORY: Written, K. Venkatakrishna, Hughes STX, May 1992 Added N_ext keyword, and table_name info, G. Reichert Work on *very* large FITS files October 92 More checks to recognize corrupted FITS files February, 1993 Proper check for END keyword December 1994 Correctly size variable length binary tables WBL December 1994 EXTNAME keyword can be anywhere in extension header WBL January 1998 Correctly skip past extensions with no data WBL April 1998 Converted to IDL V5.0, W. Landsman, April 1998 No need for !TEXTOUT if /SILENT D.Finkbeiner February 2002 Define !TEXTOUT if needed. R. Sterner, 2002 Aug 27 Work on gzip compressed files for V5.3 or later W. Landsman 2003 Jan Improve speed by only reading first 36 lines of header Count headers with more than 32767 lines W. Landsman Feb. 2003
(See ../pfidl/astro_lib/fits_info.pro)
NAME: FITS_OPEN *PURPOSE: Opens a FITS (Flexible Image Transport System) data file. *CATEGORY: INPUT/OUTPUT *CALLING SEQUENCE: FITS_OPEN, filename, fcb *INPUTS: filename : name of the FITS file to open, scalar string FITS_OPEN can also open gzip compressed (.gz) file *for reading only*, in IDL V5.3 or later, although there is a performance penalty *OUTPUTS: fcb : (FITS Control Block) a IDL structure containing information concerning the file. It is an input to FITS_READ, FITS_WRITE and FITS_CLOSE INPUT KEYWORD PARAMETERS: /APPEND: Set to append to an existing file. /HPRINT - print headers with routine HPRINT as they are read. (useful for debugging a strange file) /NO_ABORT: Set to return to calling program instead of a RETALL when an I/O error is encountered. If set, the routine will return a non-null string (containing the error message) in the keyword MESSAGE. (For backward compatibility, the obsolete system variable !ERR is also set to -1 in case of an error.) If /NO_ABORT not set, then FITS_OPEN will print the message and issue a RETALL /UPDATE Set this keyword to open an existing file for update /WRITE: Set this keyword to open a new file for writing. OUTPUT KEYWORD PARAMETERS: MESSAGE = value: Output error message. If the FITS file was opened successfully, then message = ''. *NOTES: The output FCB should be passed to the other FITS routines (FITS_OPEN, FITS_READ, FITS_HELP, and FITS_WRITE). It has the following structure when FITS_OPEN is called without /WRITE or /APPEND keywords set. FCB.FILENAME - name of the input file .UNIT - unit number the file is opened to .NEXTEND - number of extensions in the file. .XTENSION - string array giving the extension type for each extension. .EXTNAME - string array giving the extension name for each extension. (null string if not defined the extension) .EXTVER - vector of extension version numbers (0 if not defined) .EXTLEVEL - vector of extension levels (0 if not defined) .GCOUNT - vector with the number of groups in each extension. .PCOUNT - vector with parameter count for each group .BITPIX - BITPIX for each extension with values 8 byte data 16 short word integers 32 long word integers -32 IEEE floating point -64 IEEE double precision floating point .NAXIS - number of axes for each extension. (0 for null data units) .AXIS - 2-D array where axis(*,N) gives the size of each axes for extension N .START_HEADER - vector giving the starting byte in the file where each extension header begins .START_DATA - vector giving the starting byte in the file where the data for each extension begins .HMAIN - keyword parameters (less standard required FITS keywords) for the primary data unit. .OPEN_FOR_WRITE - flag (0= open for read, 1=open for write, 2=open for update) .LAST_EXTENSION - last extension number read. .RANDOM_GROUPS - 1 if the PDU is random groups format, 0 otherwise .NBYTES - total number of (uncompressed) bytes in the FITS file When FITS open is called with the /WRITE or /APPEND option, FCB contains: FCB.FILENAME - name of the input file .UNIT - unit number the file is opened to .NEXTEND - number of extensions in the file. .OPEN_FOR_WRITE - flag (1=open for write, 2=open for append 3=open for update) *EXAMPLES: Open a FITS file for reading: FITS_OPEN,'myfile.fits',fcb Open a new FITS file for output: FITS_OPEN,'newfile.fits',fcb,/write PROCEDURES USED: HPRINT, SXDELPAR, SXPAR() *HISTORY: Written by: D. Lindler August, 1995 July, 1996 NICMOS Modified to allow open for overwrite to allow primary header to be modified DJL Oct. 15, 1996 corrected to properly extend AXIS when more than 100 extensions present Converted to IDL V5.0 W. Landsman September 1997 Use Message = '' rather than !ERR =1 as preferred signal of normal operation W. Landsman November 2000 Lindler, Dec, 2001, Modified to use 64 bit words for storing byte positions within the file to allow support for very large files Work with gzip compressed files W. Landsman January 2003
(See ../pfidl/astro_lib/fits_open.pro)
NAME: FITS_READ *PURPOSE: To read a FITS file. *CATEGORY: INPUT/OUTPUT *CALLING SEQUENCE: FITS_READ, filename_or_fcb, data [,header, group_par] *INPUTS: FILENAME_OR_FCB - this parameter can be the FITS Control Block (FCB) returned by FITS_OPEN or the file name of the FITS file. If a file name is supplied, FITS_READ will open the file with FITS_OPEN and close the file with FITS_CLOSE before exiting. When multiple extensions are to be read from the file, it is more efficient for the user to call FITS_OPEN and leave the file open until all extensions are read. *OUTPUTS: DATA - data array. If /NOSCALE is specified, BSCALE and BZERO (if present in the header) will not be used to scale the data. If Keywords FIRST and LAST are used to read a portion of the data or the heap portion of an extension, no scaling is done and data is returned as a 1-D vector. The user can use the IDL function REFORM to convert the data to the correct dimensions if desired. If /DATA_ONLY is specified, no scaling is done. HEADER - FITS Header. If an extension is read, and the /NO_PDU keyword parameter is not supplied, the primary data unit header and the extension header will be combined. The header will have the form:BEGIN MAIN HEADER -------------------------------- BEGIN EXTENSION HEADER --------------------------- 1. (Default=0, the first group) *OUTPUT KEYWORD PARAMETERS: ENUM - Output extension number that was read. MESSAGE = value: Output error message *NOTES: Determination or which extension to read. case 1: EXTEN_NO specified. EXTEN_NO will give the number of the extension to read. The primary data unit is refered to as extension 0. If EXTEN_NO is specified, XTENSION, EXTNAME, EXTVER, and EXTLEVEL parameters are ignored. case 2: if EXTEN_NO is not specified, the first extension with the specified XTENSION, EXTNAME, EXTVER, and EXTLEVEL will be read. If any of the 4 parameters are not specified, they will not be used in the search. Setting EXTLEVEL=0, EXTVER=0, EXTNAME='', or XTENSION='' is the same as not supplying them. case 3: if none of the keyword parameters, EXTEN_NO, XTENSION, EXTNAME, EXTVER, or EXTLEVEL are supplied. FITS_READ will read the next extension in the file. If the primary data unit (PDU), extension 0, is null, the first call to FITS_READ will read the first extension of the file. The only way to read a null PDU is to use EXTEN_NO = 0. If FIRST and LAST are specified, the data is returned without applying any scale factors (BSCALE and BZERO) and the data is returned in a 1-D vector. This will allow you to read any portion of a multiple dimension data set. Once returned, the IDL function REFORM can be used to place the correct dimensions on the data. IMPLICIT IMAGES: FITS_READ will construct an implicit image for cases where NAXIS=0 and the NPIX1, NPIX2, and PIXVALUE keywords are present. The output image will be: image = replicate(PIXVALUE,NPIX1,NPIX2) *EXAMPLES: Read the primary data unit of a FITS file, if it is null read the first extension: FITS_READ, 'myfile.fits', data, header Read the first two extensions of a FITS file and the extension with EXTNAME = 'FLUX' and EXTVER = 4 FITS_OPEN, 'myfile.fits', fcb FITS_READ, fcb,data1, header2, exten_no = 1 FITS_READ, fcb,data1, header2, exten_no = 2 FITS_READ, fcb,data3, header3, extname='flux', extver=4 FITS_CLOSE, fcb Read the sixth image in a data cube for the fourth extension. FITS_OPEN, 'myfile.fits', fcb image_number = 6 ns = fcb.axis(0,4) nl = fcb.axis(1,4) i1 = (ns*nl)*(image_number-1) i2 = i2 + ns*nl-1 FITS_READ,fcb,image,header,first=i1,last=i2 image = reform(image,ns,nl,/overwrite) FITS_CLOSE *PROCEDURES USED: FITS_CLOSE, FITS_OPEN, IEEE_TO_HOST, IS_IEEE_BIG() SXADDPAR, SXDELPAR, SXPAR() *HISTORY: Written by: D. Lindler, August 1995 Converted to IDL V5.0 W. Landsman September 1997 Avoid use of !ERR W. Landsman August 1999 Read unsigned datatypes, added /no_unsigned W. Landsman December 1999 Don't call FITS_CLOSE unless fcb is defined W. Landsman January 2000 Set BZERO = 0 for unsigned integer data W. Landsman January 2000 Only call IEEE_TO_HOST if needed W. Landsman February 2000 Ensure EXTEND keyword in primary header W. Landsman April 2001 Don't erase ERROR message when closing file W. Landsman April 2002 Assume at least V5.1 remove NANValue keyword W. Landsman November 2002 Work with compress files (read file size from fcb), requires updated (Jan 2003) version of FITS_OPEN W. Landsman Jan 2003
(See ../pfidl/astro_lib/fits_read.pro)
NAME: FITS_TEST_CHECKSUM() PURPOSE: Verify the values of the CHECKSUM and DATASUM keywords in a FITS header EXPLANATION: Follows the 23 May 2002 version of the FITS checksum proposal at http://heasarc.gsfc.nasa.gov/docs/heasarc/fits/checksum.html CALLING SEQUENCE: result = FITS_TEST_CHECKSUM(HDR, [ DATA, ERRMSG=, /FROM_IEEE ]) INPUTS: HDR - FITS header (vector string) OPTIONAL DATA: DATA - data array associated with the FITS header. If not supplied, or set to a scalar, then there is assumed to be no data array associated with the FITS header. RESULT: An integer -1, 0 or 1 indicating the following conditions: 1 - CHECKSUM (and DATASUM) keywords are present with correct values 0 - CHECKSUM keyword is not present -1 - CHECKSUM or DATASUM keyword does not have the correct value indicating possible data corruption. OPTIONAL INPUT KEYWORD: /FROM_IEEE - If this keyword is set, then the input is assumed to be in big endian format (e.g. an untranslated FITS array). This keyword only has an effect on little endian machines (e.g. a Linux box). OPTIONAL OUTPUT KEYWORD: ERRMSG - will contain a scalar string giving the error condition. If RESULT = 1 then ERRMSG will be an empty string. If this output keyword is not supplied, then the error message will be printed at the terminal. NOTES: The header and data must be *exactly* as originally written in the FITS file. By default, some FITS readers may alter keyword values (e.g. BSCALE) or append information (e.g. HISTORY or an inherited primary header) and this will alter the checksum value. PROCEDURES USED: CHECKSUM32, FITS_ASCII_ENCODE(), SXPAR() EXAMPLE: Verify the CHECKSUM keywords in the primary header/data unit of a FITS file 'test.fits' FITS_READ,'test.fits',data,hdr,/no_PDU,/NoSCALE print,FITS_TEST_CHECKSUM(hdr,data) Note the use of the /No_PDU and /NoSCALE keywords to avoid any alteration of the FITS header REVISION HISTORY: W. Landsman SSAI December 2002
(See ../pfidl/astro_lib/fits_test_checksum.pro)
NAME: FITS_WRITE *PURPOSE: To write a FITS primary data unit or extension. *CATEGORY: INPUT/OUTPUT *CALLING SEQUENCE: FITS_WRITE, filename_or_fcb, data, [header_in] *INPUTS: FILENAME_OR_FCB: name of the output data file or the FITS control block returned by FITS_OPEN (called with the /WRITE or /APPEND) parameters. *OPTIONAL INPUTS: DATA: data array to write. If not supplied or set to a scalar, a null image is written. HEADER_IN: FITS header keyword. If not supplied, a minimal basic header will be created. Required FITS keywords, SIMPLE, BITPIX, XTENSION, NAXIS, ... are added by FITS_WRITE and do not need to be supplied with the header. If supplied, their values will be updated as necessary to reflect DATA. *INPUT KEYWORD PARAMETERS: XTENSION: type of extension to write (Default="IMAGE"). If not supplied, it will be taken from HEADER_IN. If not in either place, the default is "IMAGE". This parameter is ignored when writing the primary data unit. EXTNAME: EXTNAME for the extension. If not supplied, it will be taken from HEADER_IN. If not supplied and not in HEADER_IN, no EXTNAME will be written into the output extension. EXTVER: EXTVER for the extension. If not supplied, it will be taken from HEADER_IN. If not supplied and not in HEADER_IN, no EXTVER will be written into the output extension. EXTLEVEL: EXTLEVEL for the extension. If not supplied, it will be taken from HEADER_IN. If not supplied and not in HEADER_IN, no EXTLEVEL will be written into the output extension. /NO_ABORT: Set to return to calling program instead of a RETALL when an I/O error is encountered. If set, the routine will return a non-null string (containing the error message) in the keyword MESSAGE. (For backward compatibility, the obsolete system variable !ERR is also set to -1 in case of an error.) If /NO_ABORT not set, then FITS_WRITE will print the message and issue a RETALL /NO_DATA: Set if you only want FITS_WRITE to write a header. The header supplied will be written without modification and the user is expected to write the data using WRITEU to unit FCB.UNIT. When FITS_WRITE is called with /NO_DATA, the user is responsible for the validity of the header, and must write the correct amount and format of the data. When FITS_WRITE is used in this fashion, it will pad the data from a previously written extension to 2880 blocks before writting the header. *OUTPUT KEYWORD PARAMETERS: MESSAGE: value of the error message for use with /NO_ABORT HEADER: actual output header written to the FITS file. *NOTES: If the first call to FITS_WRITE is an extension, FITS_WRITE will automatically write a null image as the primary data unit. Keywords and history in the input header will be properly separated into the primary data unit and extension portions when constructing the output header (See FITS_READ for information on the internal Header format which separates the extension and PDU header portions). *EXAMPLES: Write an IDL variable to a FITS file with the minimal required header. FITS_WRITE,'newfile.fits',ARRAY Write the same array as an image extension, with a null Primary data unit. FITS_WRITE,'newfile.fits',ARRAY,xtension='IMAGE' Write 4 additional image extensions to the same file. FITS_OPEN,'newfile.fits',fcb FITS_WRITE,fcb,data1,extname='FLUX',extver=1 FITS_WRITE,fcb,err1,extname'ERR',extver=1 FITS_WRITE,fcb,data2,extname='FLUX',extver=2 FITS_WRITE,fcb,err2,extname='ERR',extver=2 FITS_CLOSE,FCB *PROCEDURES USED: FITS_OPEN, SXADDPAR, SXDELPAR, SXPAR() *HISTORY: Written by: D. Lindler August, 1995 Work for variable length extensions W. Landsman August 1997 Converted to IDL V5.0 W. Landsman September 1997 PCOUNT and GCOUNT added for IMAGE extensions J. Graham October 1999 Write unsigned data types W. Landsman December 1999 Pad data area with zeros not blanks W. McCann/W. Landsman October 2000 Return Message='' to signal normal operation W. Landsman Nov. 2000 Ensure that required extension table keywords are in proper order W.V. Dixon/W. Landsman March 2001 Assume since V5.1, remove NaNValue keyword W. Landsman Nov. 2002
(See ../pfidl/astro_lib/fits_write.pro)
NAME: FXADDPAR Purpose : Add or modify a parameter in a FITS header array. Explanation : This version of FXADDPAR will write string values longer than 68 characters using the FITS continuation convention described at http://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/ofwg_recomm/r13.html Use : FXADDPAR, HEADER, NAME, VALUE, COMMENT Inputs : HEADER = String array containing FITS header. The maximum string length must be equal to 80. If not defined, then FXADDPAR will create an empty FITS header array. NAME = Name of parameter. If NAME is already in the header the value and possibly comment fields are modified. Otherwise a new record is added to the header. If NAME is equal to either "COMMENT" or "HISTORY" then the value will be added to the record without replacement. In this case the comment parameter is ignored. VALUE = Value for parameter. The value expression must be of the correct type, e.g. integer, floating or string. String values of 'T' or 'F' are considered logical values. If the value is a string and is "long" (more than 69 characters), then it may be continued over more than one line using the OGIP CONTINUE standard. Opt. Inputs : COMMENT = String field. The '/' is added by this routine. Added starting in position 31. If not supplied, or set equal to '' (the null string), then any previous comment field in the header for that keyword is retained (when found). Outputs : HEADER = Updated header array. Opt. Outputs: None. Keywords : BEFORE = Keyword string name. The parameter will be placed before the location of this keyword. For example, if BEFORE='HISTORY' then the parameter will be placed before the first history location. This applies only when adding a new keyword; keywords already in the header are kept in the same position. AFTER = Same as BEFORE, but the parameter will be placed after the location of this keyword. This keyword takes precedence over BEFORE. FORMAT = Specifies FORTRAN-like format for parameter, e.g. "F7.3". A scalar string should be used. For complex numbers the format should be defined so that it can be applied separately to the real and imaginary parts. /NOCONTINUE = By default, FXADDPAR will break strings longer than 68 characters into multiple lines using the continuation convention. If this keyword is set, then the line will instead be truncated to 68 characters. This was the default behaviour of FXADDPAR prior to December 1999. Calls : DETABIFY(), FXPAR(), FXPARPOS() Common : None. Restrictions: Warning -- Parameters and names are not checked against valid FITS parameter names, values and types. The required FITS keywords SIMPLE (or XTENSION), BITPIX, NAXIS, NAXIS1, NAXIS2, etc., must be entered in order. The actual values of these keywords are not checked for legality and consistency, however. Side effects: All HISTORY records are inserted in order at the end of the header. All COMMENT records are also inserted in order at the end of the header, but before the HISTORY records. The BEFORE and AFTER keywords can override this. All records with no keyword (blank) are inserted in order at the end of the header, but before the COMMENT and HISTORY records. The BEFORE and AFTER keywords can override this. All other records are inserted before any of the HISTORY, COMMENT, or "blank" records. The BEFORE and AFTER keywords can override this. String values longer than 68 characters will be split into multiple lines using the OGIP CONTINUE convention, unless the /NOCONTINUE keyword is set. For a description of the CONTINUE convention see http://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/ofwg_recomm/r13.htm Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Jan 1992, from SXADDPAR by D. Lindler and J. Isensee. Differences include: * LOCATION parameter replaced with keywords BEFORE and AFTER. * Support for COMMENT and "blank" FITS keywords. * Better support for standard FITS formatting of string and complex values. * Built-in knowledge of the proper position of required keywords in FITS (although not necessarily SDAS/Geis) primary headers, and in TABLE and BINTABLE extension headers. William Thompson, May 1992, fixed bug when extending length of header, and new record is COMMENT, HISTORY, or blank. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 5 September 1997 Fixed bug replacing strings that contain "/" character--it interpreted the following characters as a comment. Version 3, Craig Markwardt, GSFC, December 1997 Allow long values to extend over multiple lines Version 4, D. Lindler, March 2000, modified to use capital E instead of a lower case e for exponential format. Version 4.1 W. Landsman April 2000, make user-supplied format uppercase Version 4.2 W. Landsman July 2002, positioning of EXTEND keyword Version : Version 4.2, July 2002
(See ../pfidl/astro_lib/fxaddpar.pro)
NAME: FXHREAD Purpose : Reads a FITS header from an opened disk file. Explanation : Reads a FITS header from an opened disk file. Use : FXHREAD, UNIT, HEADER [, STATUS ] Inputs : UNIT = Logical unit number. Opt. Inputs : Outputs : HEADER = String array containing the FITS header. Opt. Outputs: STATUS = Condition code giving the status of the read. Normally, this is zero, but is set to !ERR if an error occurs, or if the first byte of the header is zero (ASCII null). Keywords : None. Calls : None. Common : None. Restrictions: The file must already be positioned at the start of the header. It must be a proper FITS file. Side effects: The file ends by being positioned at the end of the FITS header, unless an error occurs. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Feb 1992, from READFITS by J. Woffard and W. Landsman. W. Thompson, Aug 1992, added test for SIMPLE keyword. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version : Version 1, 12 April 1993. Converted to IDL V5.0 W. Landsman September 1997
(See ../pfidl/astro_lib/fxhread.pro)
NAME: FXMOVE PURPOSE: Skip a specified number of extensions in a FITS file CALLING SEQUENCE: STATUS=FXMOVE(UNIT, N_EXT, /Silent) INPUT PARAMETERS: UNIT = An open unit descriptor for a FITS data stream. N_EXT = Number of extensions to skip. OPTIONAL INPUT PARAMETER: /SILENT - If set, then any messages about invalid characters in the FITS file are suppressed. RETURNS: 0 if successful. -1 if an error is encountered. COMMON BLOCKS: None. SIDE EFFECTS: Repositions the file pointer. PROCEDURE: Each FITS header is read in and parsed, and the file pointer is moved to where the next FITS extension header until the desired extension is reached. PROCEDURE CALLS: FXPAR(), MRD_HREAD, MRD_SKIP MODIFICATION HISTORY: Extracted from FXPOSIT 8-March-2000 by T. McGlynn Added /SILENT keyword 14-Dec-2000 by W. Landsman Save time by not reading the full header W. Landsman Feb. 2003
(See ../pfidl/astro_lib/fxmove.pro)
NAME: FXPAR() PURPOSE: Obtain the value of a parameter in a FITS header. EXPLANATION: The first 8 chacters of each element of HDR are searched for a match to NAME. If the keyword is one of those allowed to take multiple values ("HISTORY", "COMMENT", or " " (blank)), then the value is taken as the next 72 characters. Otherwise, it is assumed that the next character is "=", and the value (and optional comment) is then parsed from the last 71 characters. An error occurs if there is no parameter with the given name. If the value is too long for one line, it may be continued on to the the next input card, using the OGIP CONTINUE convention. For more info, http://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/ofwg_recomm/r13.html Complex numbers are recognized as two numbers separated by one or more space characters. If a numeric value has no decimal point (or E or D) it is returned as type LONG. If it contains more than 8 numerals, or contains the character 'D', then it is returned as type DOUBLE. Otherwise it is returned as type FLOAT. If an integer is too large to be stored as type LONG, then it is returned as DOUBLE. CALLING SEQUENCE: Result = FXPAR( HDR, NAME [, ABORT, COUNT=, COMMENT=, /NOCONTINUE ] ) Result = FXPAR(HEADER,'DATE') ;Finds the value of DATE Result = FXPAR(HEADER,'NAXIS*') ;Returns array dimensions as ;vector REQUIRED INPUTS: HDR = FITS header string array (e.g. as returned by FXREAD). Each element should have a length of 80 characters NAME = String name of the parameter to return. If NAME is of the form 'keyword*' then an array is returned containing values of keywordN where N is an integer. The value of keywordN will be placed in RESULT(N-1). The data type of RESULT will be the type of the first valid match of keywordN found. OPTIONAL INPUT: ABORT = String specifying that FXPAR should do a RETALL if a parameter is not found. ABORT should contain a string to be printed if the keyword parameter is not found. If not supplied, FXPAR will return with a negative !err if a keyword is not found. START = A best-guess starting position of the sought-after keyword in the header. If specified, then FXPAR first searches for scalar keywords in the header in the index range bounded by START-PRECHECK and START+POSTCHECK. This can speed up keyword searches in large headers. If the keyword is not found, then FXPAR searches the entire header. If not specified then the entire header is searched. Searches of the form 'keyword*' also search the entire header and ignore START. Upon return START is changed to be the position of the newly found keyword. Thus the best way to search for a series of keywords is to search for them in the order they appear in the header like this: START = 0L P1 = FXPAR('P1', START=START) P2 = FXPAR('P2', START=START) PRECHECK = If START is specified, then PRECHECK is the number of keywords preceding START to be searched. Default: 5 POSTCHECK = If START is specified, then POSTCHECK is the number of keywords after START to be searched. Default: 20 OUTPUT: The returned value of the function is the value(s) associated with the requested keyword in the header array. If the parameter is complex, double precision, floating point, long or string, then the result is of that type. Apostrophes are stripped from strings. If the parameter is logical, 1 is returned for T, and 0 is returned for F. If NAME was of form 'keyword*' then a vector of values are returned. OPTIONAL INPUT KEYWORDS: /NOCONTINUE = If set, then continuation lines will not be read, even if present in the header OPTIONAL OUTPUT KEYWORD: COUNT = Optional keyword to return a value equal to the number of parameters found by FXPAR. COMMENTS= Array of comments associated with the returned values. PROCEDURE CALLS: GETTOK(), VALID_NUM SIDE EFFECTS: The system variable !err is set to -1 if parameter not found, 0 for a scalar value returned. If a vector is returned it is set to the number of keyword matches found. If a keyword occurs more than once in a header, a warning is given, and the first occurence is used. However, if the keyword is "HISTORY", "COMMENT", or " " (blank), then multiple values are returned. NOTES: The functions SXPAR() and FXPAR() are nearly identical, although FXPAR() has slightly more sophisticated parsing. There is no particular reason for having two nearly identical procedures, but both are too widely used to drop either one. REVISION HISTORY: Version 1, William Thompson, GSFC, 12 April 1993. Adapted from SXPAR Version 2, William Thompson, GSFC, 14 October 1994 Modified to use VALID_NUM instead of STRNUMBER. Inserted additional call to VALID_NUM to trap cases where character strings did not contain quotation marks. Version 3, William Thompson, GSFC, 22 December 1994 Fixed bug with blank keywords, following suggestion by Wayne Landsman. Version 4, Mons Morrison, LMSAL, 9-Jan-98 Made non-trailing ' for string tag just be a warning (not a fatal error). It was needed because "sxaddpar" had an error which did not write tags properly for long strings (over 68 characters) Version 5, Wayne Landsman GSFC, 29 May 1998 Fixed potential problem with overflow of LONG values Version 6, Craig Markwardt, GSFC, 28 Jan 1998, Added CONTINUE parsing Version 7, Craig Markwardt, GSFC, 18 Nov 1999, Added START, PRE/POSTCHECK keywords for better performance
(See ../pfidl/astro_lib/fxpar.pro)
NAME: FXPARPOS() Purpose : Finds position to insert record into FITS header. Explanation : Finds the position to insert a record into a FITS header. Called from FXADDPAR. Use : Result = FXPARPOS(KEYWRD, IEND [, BEFORE=BEFORE ] [, AFTER=AFTER ]) Inputs : KEYWRD = Array of eight-character keywords in header. IEND = Position of END keyword. Opt. Inputs : None. Outputs : Result of function is position to insert record. Opt. Outputs: None. Keywords : BEFORE = Keyword string name. The parameter will be placed before the location of this keyword. For example, if BEFORE='HISTORY' then the parameter will be placed before the first history location. This applies only when adding a new keyword; keywords already in the header are kept in the same position. AFTER = Same as BEFORE, but the parameter will be placed after the location of this keyword. This keyword takes precedence over BEFORE. If neither BEFORE or AFTER keywords are passed, then IEND is returned. Calls : None. Common : None. Restrictions: KEYWRD and IEND must be consistent with the relevant FITS header. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Jan 1992. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version : Version 1, 12 April 1993. Converted to IDL V5.0 W. Landsman September 1997
(See ../pfidl/astro_lib/fxparpos.pro)
NAME: FXPOSIT PURPOSE: Return the unit number of a FITS file positioned at specified extension EXPLANATION: The FITS file will be ready to be read at the beginning of the specified extension. CALLING SEQUENCE: unit=FXPOSIT(FILE, EXT_NO, /READONLY, COMPRESS=program, /SILENT) INPUT PARAMETERS: FILE = FITS file name, scalar string EXT_NO = Extension to be moved to, scalar nonnegative integer RETURNS: Unit number of file or -1 if an error is detected. OPTIONAL KEYWORD PARAMETER: /READONLY - If this keyword is set and non-zero, then OPENR rather than OPENU will be used to open the FITS file. COMPRESS - If this keyword is set and non-zero, then then treat the file as compressed. If 1 assume a gzipped file. Where possible use IDLs internal decompression facilities (i.e., v5.3 or greater) or on Unix systems spawn off a process to decompress and use its output as the FITS stream. If the keyword is not 1, then use its value as a string giving the command needed for decompression. /SILENT If set, then suppress any messages about invalid characters in the FITS file. COMMON BLOCKS: None. SIDE EFFECTS: Opens and returns the descriptor of a file. PROCEDURE: Open the appropriate file, or spawn a command and intercept the output. Call FXMOVE to get to the appropriate extension. PROCEDURE CALLS: EXPAND_TILDE() (Unix only), FXPAR(), FXMOVE() MODIFICATION HISTORY: Derived from William Thompson's FXFINDEND routine. Modified by T.McGlynn, 5-October-1994. Modified by T.McGlynn, 25-Feb-1995 to handle compressed files. Pipes cannot be accessed using FXHREAD so MRD_HREAD was written. W. Landsman 23-Apr-1997 Force the /bin/sh shell when uncompressing W. Landsman 26-May-1997 Non-unix is not just VMS T. McGlynn 22-Apr-1999 Add /binary modifier needed for Windows T. McGlynn 03-June-1999 Use /noshell option to get rid of processes left by spawn. Use findfile to retain ability to use wildcards W. Landsman 03-Aug-1999 Use EXPAND_TILDE under Unix to find file T. McGlynn 04-Apr-2000 Put reading code into FXMOVE, additional support for compression from D.Palmer. W. Landsman/D.Zarro 04-Jul-2000 Added test for !VERSION.OS EQ 'Win32' (WinNT) W. Landsman 12-Dec-2000 Added /SILENT keyword W. Landsman April 2002 Use FILE_SEARCH for V5.5 or later
(See ../pfidl/astro_lib/fxposit.pro)
NAME: FXREAD Purpose : Read basic FITS files. Explanation : Read the primary array from a disk FITS file. Optionally allows the user to read in only a subarray and/or every Nth pixel. Use : FXREAD, FILENAME, DATA [, HEADER [, I1, I2 [, J1, J2 ]] [, STEP]] Inputs : FILENAME = String containing the name of the file to be read. Opt. Inputs : I1,I2 = Data range to read in the first dimension. If passed, then HEADER must also be passed. If not passed, or set to -1,-1, then the entire range is read. J1,J2 = Data range to read in the second dimension. If passed, then HEADER and I1,J2 must also be passed. If not passed, or set to -1,-1, then the entire range is read. STEP = Step size to use in reading the data. If passed, then HEADER must also be passed. Default value is 1. Ignored if less than 1. Outputs : DATA = Data array to be read from the file. Opt. Outputs: HEADER = String array containing the header for the FITS file. Keywords : NANVALUE = Value signalling data dropout. All points corresponding to IEEE NaN (not-a-number) are set to this value. Ignored unless DATA is of type float or double-precision. PROMPT = If set, then the optional parameters are prompted for at the keyboard. AVERAGE = If set, then the array size is reduced by averaging pixels together rather than by subselecting pixels. Ignored unless STEP is nontrivial. Note: this is much slower. YSTEP = If passed, then STEP is the step size in the 1st dimension, and YSTEP is the step size in the 2nd dimension. Otherwise, STEP applies to both directions. NOSCALE = If set, then the output data will not be scaled using the optional BSCALE and BZERO keywords in the FITS header. Default is to scale, if and only if BSCALE and BZERO are present and nontrivial. NOUPDATE = If set, then the optional BSCALE and BZERO keywords in the optional HEADER array will not be changed. The default is to reset these keywords to BSCALE=1, BZERO=0. Ignored if NOSCALE is set. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXREAD, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : GET_DATE, IEEE_TO_HOST, FXADDPAR, FXHREAD, FXPAR, WHERENAN Common : None. Restrictions: Groups are not supported. The optional parameters I1, I2, and STEP only work with one or two-dimensional arrays. J1 and J2 only work with two-dimensional arrays. Use of the AVERAGE keyword is not compatible with arrays with missing pixels. Side effects: If the keywords BSCALE and BZERO are present in the FITS header, and have non-trivial values, then the returned array DATA is formed by the equation DATA = BSCALE*original + BZERO However, this behavior can overridden by using the /NOSCALE keyword. If the data is scaled, then the optional HEADER array is changed so that BSCALE=1 and BZERO=0. This is so that these scaling parameters are not applied to the data a second time by another routine. Also, history records are added storing the original values of these constants. Note that only the returned array is modified--the header in the FITS file itself is untouched. If the /NOUPDATE keyword is set, however, then the BSCALE and BZERO keywords are not changed. It is then the user's responsibility to ensure that these parameters are not reapplied to the data. In particular, these keywords should not be present in any header when writing another FITS file, unless the user wants their values to be applied when the file is read back in. Otherwise, FITS readers will read in the wrong values for the data array. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, May 1992, based in part on READFITS by W. Landsman, and STSUB by M. Greason and K. Venkatakrishna. W. Thompson, Jun 1992, added code to interpret BSCALE and BZERO records, and added NOSCALE and NOUPDATE keywords. W. Thompson, Aug 1992, changed to call FXHREAD, and to add history records for BZERO, BSCALE. Written : William Thompson, GSFC, May 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 17 November 1993. Corrected bug with AVERAGE keyword on non-IEEE compatible machines. Corrected bug with subsampling on VAX machines. Version 3, William Thompson, GSFC, 31 May 1994 Added ERRMSG keyword. Version 4, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 5, Zarro (SAC/GSFC), 14 Feb 1997 Added I/O error checking Version 6, 20-May-1998, David Schlegel/W. Thompson Allow a single pixel to be read in. Change the signal to read in the entire array to be -1 Version : Version 6, 20-May-1998
(See ../pfidl/astro_lib/fxread.pro)
NAME: GAUSSIAN PURPOSE: Compute the 1-d Gaussian function and optionally the derivative EXPLANATION: Compute the 1-D Gaussian function and optionally the derivative at an array of points. CALLING SEQUENCE: y = gaussian( xi, parms,[ pderiv ]) INPUTS: xi = array, independent variable of Gaussian function. parms = parameters of Gaussian, 2, 3 or 4 element array: parms[0] = maximum value (factor) of Gaussian, parms[1] = mean value (center) of Gaussian, parms[2] = standard deviation (sigma) of Gaussian. (if parms has only 2 elements then sigma taken from previous call to gaussian(), which is stored in a common block). parms[3] = optional, constant offset added to Gaussian. OUTPUT: y - Function returns array of Gaussian evaluated at xi. Values will be floating pt. (even if xi is double) unless the /DOUBLE keyword is set. OPTIONAL INPUT: /DOUBLE - set this keyword to return double precision for both the function values and (optionally) the partial derivatives. OPTIONAL OUTPUT: pderiv = [N,3] or [N,4] output array of partial derivatives, computed only if parameter is present in call. pderiv[*,i] = partial derivative at all xi absisca values with respect to parms[i], i=0,1,2,[3]. EXAMPLE: Evaulate a Gaussian centered at x=0, with sigma=1, and a peak value of 10 at the points 0.5 and 1.5. Also compute the derivative IDL> f = gaussian( [0.5,1.5], [10,0,1], DERIV ) ==> f= [8.825,3.25]. DERIV will be a 2 x 3 array containing the numerical derivative at the two points with respect to the 3 parameters. COMMON BLOCKS: None HISTORY: Written, Frank Varosi NASA/GSFC 1992. Converted to IDL V5.0 W. Landsman September 1997 Use machar() for machine precision, added /DOUBLE keyword, add optional constant 4th parameter W. Landsman November 2001
(See ../pfidl/astro_lib/gaussian.pro)
NAME: GETPSF PURPOSE: To generate a point-spread function (PSF) from observed stars. EXPLANATION: The PSF is represented as a 2-dimensional Gaussian (integrated over each pixel) and a lookup table of residuals. The lookup table and Gaussian parameters are output in a FITS image file. The PSF FITS file created by GETPSF can be read with the procedure RDPSF. Adapted from the 1986 STSDAS version of DAOPHOT CALLING SEQUENCE: GETPSF, image, xc, yc, apmag, sky, [ronois, phpadu, gauss, psf, idpsf, psfrad, fitrad, psfname, /DEBUG ] INPUTS: IMAGE - input image array XC - input vector of x coordinates (from FIND), these should be IDL (first pixel is (0,0)) convention. YC - input vector of y coordinates (from FIND) APMAG - vector of magnitudes (from APER), used for initial estimate of gaussian intensity. If APMAG is multidimensional, (more than 1 aperture was used in APER) then the first aperture is used. SKY - vector of sky values (from APER) OPTIONAL INPUTS: The user will be prompted for the following parameters if not supplied. RONOIS - readout noise per pixel, (in electrons, or equivalent photons) PHPADU - photons per analog digital unit, used to scale the data numbers in IMAGE into photon units IDPSF - subscripts of the list of stars created by APER which will be used to define the PSF. Stars whose centroid does not fall within PSFRAD of the edge of the frame, or for which a Gaussian fit requires more than 25 iterations, will be ignored when creating the final PSF. PSFRAD - the scalar radius, in pixels, of the circular area within which the PSF will be defined. This should be slightly larger than the radius of the brightest star that one will be interested in. FITRAD - the scalar radius, in pixels of the circular area used in the least-square star fits. Stetson suggest that FITRAD should approximately equal to the FWHM, slightly less for crowded fields. (FITRAD must be smaller than PSFRAD.) PSFNAME- Name of the FITS file that will contain the table of residuals, and the best-fit Gaussian parameters. This file is subsequently required for use by NSTAR. OPTIONAL OUTPUTS: GAUSS - 5 element vector giving parameters of gaussian fit to the first PSF star GAUSS(0) - height of the gaussian (above sky) GAUSS(1) - the offset (in pixels) of the best fitting gaussian and the original X centroid GAUSS(2) - similiar offset from the Y centroid GAUSS(3) - Gaussian sigma in X GAUSS(4) - Gaussian sigma in Y PSF - 2-d array of PSF residuals after a Gaussian fit. PROCEDURE: GETPSF fits a Gaussian profile to the core of the first PSF star and generates a look-up table of the residuals of the actual image data from the Gaussian fit. If desired, it will then fit this PSF to another star (using PKFIT) to determine its precise centroid, scale the same Gaussian to the new star's core, and add the differences between the actual data and the scaled Gaussian to the table of residuals. (In other words, the Gaussian fit is performed only on the first star.) OPTIONAL KEYWORD INPUT: DEBUG - if this keyword is set and non-zero, then the result of each fitting iteration will be displayed. PROCEDURES CALLED DAOERF, MAKE_2D, MKHDR, RINTER(), PKFIT, STRNUMBER(), STRN(), WRITEFITS REVISON HISTORY: Adapted from the 1986 version of DAOPHOT in STSDAS IDL Version 2 W Landsman November 1988 Use DEBUG keyword instead of !DEBUG W. Landsman May 1996 Converted to IDL V5.0 W. Landsman September 1997
(See ../pfidl/astro_lib/getpsf.pro)
NAME: GETTOK PURPOSE: Retrieve the first part of the string up to a specified character EXPLANATION: GET TOKen - Retrieve first part of string until the character char is encountered. CALLING SEQUENCE: token = gettok( st, char ) INPUT: char - character separating tokens, scalar string INPUT-OUTPUT: st - (scalar) string to get token from (on output token is removed) OUTPUT: token - scalar string value is returned EXAMPLE: If ST is 'abc=999' then gettok(ST,'=') would return 'abc' and ST would be left as '999' NOTES: A version of GETTOK that accepts vector strings is available for users of IDL V5.3 or later from http://idlastro.gsfc.nasa.gov/ftp/v53/ HISTORY version 1 by D. Lindler APR,86 Remove leading blanks W. Landsman (from JKF) Aug. 1991 Converted to IDL V5.0 W. Landsman September 1997
(See ../pfidl/astro_lib/gettok.pro)
NAME: GET_DATE PURPOSE: Return the (current) UTC date in CCYY-MM-DD format for FITS headers EXPLANATION: This is the format required by the DATE and DATE-OBS keywords in a FITS header. CALLING SEQUENCE: GET_DATE, FITS_date, [ in_date, /OLD, /TIMETAG, LOCAL_DIFF=] OPTIONAL INPUTS: in_date - string (scalar or vector) containing dates in IDL systime() format (e.g. 'Tue Sep 25 14:56:14 2001') OUTPUTS: FITS_date = A scalar character string giving the current date. Actual appearance of dte depends on which keywords are supplied. No Keywords supplied - dte is a 10 character string with the format CCYY-MM-DD whererepresents a calendar year, the ordinal number of a calendar month within the calendar year, and the ordinal number of a day within the calendar month. /TIMETAG set - dte is a 19 character string with the format CCYY-MM-DDThh:mm:ss where represents the hour in the day, the minutes, the seconds, and the literal 'T' the ISO 8601 time designator /OLD set - dte is an 8 character string in DD/MM/YY format INPUT KEYWORDS: /TIMETAG - Specify the time to the nearest second in the DATE format /OLD - Return the DATE format formerly (pre-1997) recommended for FITS Note that this format is now deprecated because it uses only a 2 digit representation of the year. LOCAL_DIFF - numeric scalar giving the difference between local time and Greenwich Mean Time (GMT) in hours. This keyword is only needed for non-Unix users prior to V5.4. Unix users should not use this keyword because under Unix (or since V5.4 with any OS), SYSTIME(1) returns the UTC (=GMT) time directly. Users on other machines must either supply a LOCAL_DIFF keyword, or use the TIME_CONV environment variable discussed below. For example, a user on U.S. Eastern Standard Time should set LOCAL_DIFF = -5 EXAMPLE: Add the current date to the DATE keyword in a FITS header,h IDL> GET_DATE,dte IDL> sxaddpar, h, 'DATE', dte, 'Date header was created' ENVIRONMENT VARIABLE: An alternate method of inputing the difference between local and GMT time for non-Unix machines is to specify this information in a file named local_diff.dat in a directory specified with the environment variable TIME_CONV. For example, a user in EST should write -5 on this first (and only) line of this file. NOTES: (1) A discussion of the DATExxx syntax in FITS headers can be found in http://www.cv.nrao.edu/fits/documents/standards/year2000.txt (2) Those who wish to use need further flexibility in their date formats (e.g. to use TAI time) should look at Bill Thompson's time routines in http://sohowww.nascom.nasa.gov/solarsoft/gen/idl/time PROCEDURES USED: DAYCNV - Convert Julian date to Gregorian calendar date REVISION HISTORY: Written W. Landsman March 1991 Major rewrite to write new DATExxx syntax W. Landsman August 1997 Converted to IDL V5.0 W. Landsman September 1997 Work after year 2000 even with /OLD keyword W. Landsman January 2000 Don't need to worry about TIME_DIFF since V5.4 W. Landsman July 2001
(See ../pfidl/astro_lib/get_date.pro)
NAME: HEADFITS PURPOSE: Read a FITS (primary or extension) header into a string array. EXPLANATION: Under Unix, HEADFITS() can also read gzip (.gz) or Unix compressed (.Z) FITS files. In IDL V5.3 or later, HEADFITS() can read gzip files under any machine OS. CALLING SEQUENCE: Result = HEADFITS(Filename/Fileunit ,[ ERRMSG =, EXTEN= , COMPRESS=, /SILENT ]) INPUTS: Filename = String containing the name of the FITS file to be read. File names ending in '.gz' are assumed to be gzip'ed compressed and under Unix file names ending in '.Z' are assumed to be Unix compressed. If this default behaviour is not sufficient then use the COMPRESS keyword. or Fileunit - A scalar integer specifying the unit of an already opened FITS file. The unit will remain open after exiting HEADFITS(). There are two possible reasons for choosing to specify a unit number rather than a file name: (1) For a FITS file with many extensions, one can move to the desired extensions with FXPOSIT() and then use HEADFITS(). This is more efficient that repeatedly starting at the beginning of the file. (2) For reading a FITS file across a Web http: address after opening the unit with the SOCKET procedure (IDL V5.4 or later, Unix and Windows only) OPTIONAL INPUT KEYWORDS: EXTEN = integer scalar, specifying which FITS extension to read. For example, to read the header of the first extension set EXTEN = 1. Default is to read the primary FITS header (EXTEN = 0). The EXTEN keyword cannot be used when a unit number is supplied instead of a file name. COMPRESS - If this keyword is set and non-zero, then treat the file as compressed. If 1 assume a gzipped file. Where possible use IDLs internal decompression facilities (i.e., v5.3 or greater) or on Unix systems spawn off a process to decompress and use its output as the FITS stream. If the keyword is not 1, then use its value as a string giving the command needed for decompression. See FXPOSIT for more info. /SILENT - If set, then suppress any warning messages about invalid characters in the FITS file. OPTIONAL KEYWORD OUTPUT: ERRMSG = If this keyword is present, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. OUTPUTS: Result of function = FITS header, string array EXAMPLE: Print the main FITS header of a file 'test.fits' into a string variable, h IDL> print, headfits( 'test.fits') Print the second extension header of a gzip compressed FITS file 'test.fits.gz'. Use HPRINT for pretty format IDL> hprint, headfits( 'test.fits.gz', ext=2) PROCEDURES CALLED FXPOSIT(), MRD_HREAD MODIFICATION HISTORY: adapted by Frank Varosi from READFITS by Jim Wofford, January, 24 1989 Keyword EXTEN added, K.Venkatakrishna, May 1992 Make sure first 8 characters are 'SIMPLE' W. Landsman October 1993 Check PCOUNT and GCOUNT W. Landsman December 1994 Major rewrite, work for Unix gzip files, W. Landsman April 1996 Converted to IDL V5.0 W. Landsman September 1997 Added COMPRESS keyword W. Landsman April 2000 Added ERRMSG keyword W. Landsman July 2000 Added /SILENT keyword W. Landsman December 2000 Option to read a unit number rather than file name W.L October 2001
(See ../pfidl/astro_lib/headfits.pro)
NAME: HPRINT PURPOSE: Print a FITS header (or other string array) one line at a time EXPLANATION: The string array is printed 1 line at a time. Needed because IDL will add an extra space to the 80 character FITS lines on TTY terminals, causing a space to appear between lines. CALLING SEQUENCE: HPRINT, h, [ firstline ] INPUTS: H - FITS header (or any other string array). OPTIONAL INPUT: FIRSTLINE - scalar integer specifying the first line to begin displaying. The default is FIRSTLINE = 1, i.e. display all the lines. If Firstline is negative, then the first line to be printed is counted backward from the last line. NOTES: HPRINT has the following differences from the intrinsic PRINT procedure (1) Arrays are printed one line at a time to avoid a space between 80 character lines (2) Lines are trimmed with STRTRIM before being printed to speed up display (3) The /more option is used for output. EXAMPLE: Read the header from a FITS file named 'test.fits' and display it at the terminal beginning with line 50 IDL> h = headfits( 'test.fits') ;Read FITS header IDL> hprint, h, 50 ;Display starting at line 50 To print the last 25 lines of the header IDL> hprint, h, -25 REVISION HISTORY: Written W. Landsman July, 1990 Added test for user quit July, 1991 Added optional FIRSTLINE parameter November, 1992 Modified for when STDOUT is not a TTY W. Landsman September 1995 Converted to IDL V5.0 W. Landsman September 1997 Fixed printing in IDLDE, C. Gehman August, 1998
(See ../pfidl/astro_lib/hprint.pro)
NAME: IEEE_TO_HOST PURPOSE: Translate an IDL variable from IEEE-754 to host representation EXPLANATION: The variable is translated from IEEE-754 (as used, for example, in FITS data ), into the host machine architecture. Duplicates most of the functionality of the SWAP_ENDIAN_INPLACE procedure introduced in V5.6, with the addition of the IDLTYPE keyword. CALLING SEQUENCE: IEEE_TO_HOST, data, [ IDLTYPE = , ] INPUT-OUTPUT PARAMETERS: data - any IDL variable, scalar or vector. It will be modified by IEEE_TO_HOST to convert from IEEE to host representation. Byte and string variables are returned by IEEE_TO_HOST unchanged OPTIONAL KEYWORD INPUTS: IDLTYPE - scalar integer (1-15) specifying the IDL datatype according to the code given by the SIZE function. This keyword is usually when DATA is a byte array to be interpreted as another datatype (e.g. FLOAT). EXAMPLE: A 2880 byte array (named FITARR) from a FITS record is to be interpreted as floating and converted to the host representaton: IDL> IEEE_TO_HOST, fitarr, IDLTYPE = 4 METHOD: The BYTEORDER procedure is called with the appropriate keyword MODIFICATION HISTORY: Written, W. Landsman Hughes/STX May, 1992 Converted to IDL V5.0 W. Landsman September 1997 Under VMS check for IEEE -0.0 values January 1998 VMS now handle -0.0 values under IDL V5.1 July 1998 Added new integer datatypes C. Markwardt/W. Landsman July 2000 Post-V5.1 version, no VMS negative zero check W. Landsman July 2001 Use size(/type) W. Landsman December 2002 Use /SWAP_IF_LITTLE_ENDIAN keyword for 64bit types W. Landsman Feb 2003
(See ../pfidl/astro_lib/ieee_to_host.pro)
unction image_deconvolve,datain,psfin,sigmain,guess=guess, $ maxiterations=maxiter,double=double, $ uselog=uselogin, positive=positive, $ quiet=quietin, mask=maskin, float=float, $ usepsfcorr=usepsfcorrin, $ useautocorr=useautocorrin, chi2limit=chi2limitin, $ memweight=memweight, usepoisson=usepoissonin, $ chi2aim=chi2aimin, fixmemweight=fixmemweight, $ flux=fluxin,fftguess=fftguess NAME: IMAGE_DECONVOLVE PURPOSE: Deconvolve a PSF from an image CATEGORY: CALLING SEQUENCE: new_image = image_deconvolve(image,psf,sigma) INPUTS: image = raw image psf = PSF centered on floor(nx/2),floor(ny/2) sigma = error estimate for image (must be positive and non-zero) OPTIONAL INPUT PARAMETERS: KEYWORD PARAMETERS guess = initial guess (default = image) /fftguess = Use the direct FFT inversion as the initial guess. The inversion is returned in teh guess keyword, overwriting the contents of guess. maxiterations = maximum number of iterattions (def = 100) /double = use double precision in the FFT's (DEFAULT) /float = use single precision in the FFT's (faster but less robust) /uselog = Iterate the log of the image to provide an absolute positivity constraint. /positive = Apply crude positivity constraint. Can cause failure to converge. Ignored if /uselog is set. If neither /positive not /uselog is set, then the deconvolved image is allowed to go negative. flux = Try to force flux to be conserved by adding a condition that the residuals are balanced (i.e. sum to zero). The value of flux is the weight given to the condition, start at 1.0 and work work your way up or down from there (bigger means more weight on this condition). There is no guarantee that the flux conservation will succeed. Note that masked areas are allowed to float and are not included in the flux calculation. /quiet = Do not print diagnostics or plot intermediate images. mask = index vector of pixels in image that should be NOT be included in the GOF calculation. If not set, all pixels are used. Slows down the calculation, so should not be used unless necessary. /usepsfcorr = add a term to force the correlation of the residual and the PSF to be flat. This is sometimes useful for avoiding overcorrections. chi2limit = limit for chi^2. When this value is reached the iteration is terminated. chi2aim = The value of chi^2 that the algorithm should aim for. The weight is dynamically adjusted to get chi^2 to this value. there's no guarantee it will succeed, however. Default = 1.0. /usepoisson = Use poisson statistics instead of Gaussian statistics. In this case sigma isn't really used, but you have to put in something reasonalbe to make the displays look right. Also if /usepsfcorr is set, sigma is used in the gradient calculation even when /usepoisson is set. memweight = Initial weight of the entropy terms. Will be adjusted by the algorithm to make chi^2=chi2aim. Default = 1.0. /fixmemweight = Force memweight to reamain fixed at the value given by the memweight keyword. Try setting this if the algorithm fails to converge. OUTPUTS: COMMON BLOCKS: SIDE EFFECTS: RESTRICTIONS: The deconvolution is done with the FFT so the dimension of the input data should be a power of two for speed. The iteration is done on the log of the image to give a strict positivity constraint. Hence, if the data is anywhere equal to zero, the zero values are changed to 1. PROCEDURE: Uses a simple (and slow!) maximum entropy technique. Iterates the log of the image for a positivity constraint with the /uselog keyword set. MODIFICATION HISTORY: T. Metcalf 1999-Sep-21 T. Metcalf 1999-Oct-01 Added /uselog and /positive. T. Metcalf 2000-Feb-09 Added /quiet keyword T. Metcalf 2000-Mar-01 Added /float and made /double the default. T. Metcalf 2000-Mar-07 Changed the weighting of the entropy term T. Metcalf 2000-Mar-21 New implementation of usepsfcorr T. Metcalf 2000-Mar-23 Fixed bug in entropy gradient T. Metcalf 2000-Mar-24 Added /usepoisson, chi2aim keywords. T. Metcalf 2000-Mar-31 Added memweight and /fixmemweight keywords and allow a crude search for the best value of the MEM weighting by attempting to reach a final chi^2 value given by the chi2aim keyword. Also changed the implementation of the usepsfcorr term slightly. T. Metcalf 2000-Sep-15 Added /flux keyword. T. Metcalf 2001-Jan-10 Fixed calculation of flux when mask is set. T. Metcalf 2001-Jan-16 Added check for sigma > 0.0 T. Metcalf 2001-Jan-24 Added /fftguess keyword T. Metcalf 2001-Jan-29 The main code now uses the C-statistic when /usepoisson is set. The image_decon_func always used this anyway, but the change makes the MEM Lagrange multiplier calculation better with /usepoisson.
(See ../pfidl/astro_lib/image_deconvolve.pro)
NAME: IS_IEEE_BIG PURPOSE: Determine if the current machine uses IEEE, big-endian numbers. EXPLANATION: (Big endian implies that byteorder XDR conversions are no-ops). CALLING SEQUENCE: flag = is_ieee_big() INPUT PARAMETERS: None RETURNS: 1 if the machine appears to be IEEE-compliant, 0 if not. COMMON BLOCKS: None. SIDE EFFECTS: None RESTRICTIONS: PROCEDURE: A sample int, long, float and double are converted using byteorder and compared with the original. If there is no change, the machine is assumed to be IEEE compliant and big-endian. MODIFICATION HISTORY: Written 15-April-1996 by T. McGlynn for use in MRDFITS. 13-jul-1997 jkf/acc - added calls to check_math to avoid underflow messages in V5.0 on Win32 (NT). Converted to IDL V5.0 W. Landsman September 1997
(See ../pfidl/astro_lib/is_ieee_big.pro)
NAME: MAX_ENTROPY PURPOSE: Deconvolution of data by Maximum Entropy analysis, given the PSF EXPLANATION: Deconvolution of data by Maximum Entropy analysis, given the instrument point spread response function (spatially invariant psf). Data can be an observed image or spectrum, result is always positive. Default is convolutions using FFT (faster when image size = power of 2). CALLING SEQUENCE: for i=1,Niter do begin Max_Entropy, image_data, psf, image_deconv, multipliers, FT_PSF=psf_ft INPUTS: data = observed image or spectrum, should be mostly positive, with mean sky (background) near zero. psf = Point Spread Function of instrument (response to point source, must sum to unity). deconv = result of previous call to Max_Entropy, multipliers = the Lagrange multipliers of max.entropy theory (on first call, set = 0, giving flat first result). OUTPUTS: deconv = deconvolution result of one more iteration by Max_Entropy. multipliers = the Lagrange multipliers saved for next iteration. OPTIONAL INPUT KEYWORDS: FT_PSF = passes (out/in) the Fourier transform of the PSF, so that it can be reused for the next time procedure is called, /NO_FT overrides the use of FFT, using the IDL function convol() instead. /LINEAR switches to Linear convergence mode, much slower than the default Logarithmic convergence mode. LOGMIN = minimum value constraint for taking Logarithms (default=1.e-9). EXTERNAL CALLS: function convolve( image, psf ) for convolutions using FFT or otherwise. METHOD: Iteration with PSF to maximize entropy of solution image with constraint that the solution convolved with PSF fits data image. Based on paper by Hollis, Dorband, Yusef-Zadeh, Ap.J. Feb.1992, which refers to Agmon, Alhassid, Levine, J.Comp.Phys. 1979. A more elaborate image deconvolution program using maximum entropy is available at http://sohowww.nascom.nasa.gov/solarsoft/gen/idl/image/image_deconvolve.pro HISTORY: written by Frank Varosi at NASA/GSFC, 1992. Converted to IDL V5.0 W. Landsman September 1997
(See ../pfidl/astro_lib/max_entropy.pro)
NAME: MAX_LIKELIHOOD PURPOSE: Maximum likelihood deconvolution of an image or a spectrum. EXPLANATION: Deconvolution of an observed image (or spectrum) given the instrument point spread response function (spatially invariant psf). Performs iteration based on the Maximum Likelihood solution for the restoration of a blurred image (or spectrum) with additive noise. Maximum Likelihood formulation can assume Poisson noise statistics or Gaussian additive noise, yielding two types of iteration. CALLING SEQUENCE: for i=1,Niter do Max_Likelihood, data, psf, deconv, FT_PSF=psf_ft INPUTS PARAMETERS: data = observed image or spectrum, should be mostly positive, with mean sky (background) near zero. psf = Point Spread Function of the observing instrument, (response to a point source, must sum to unity). INPUT/OUTPUT PARAMETERS: deconv = as input: the result of previous call to Max_Likelihood, (initial guess on first call, default = average of data), as output: result of one more iteration by Max_Likelihood. Re_conv = (optional) the current deconv image reconvolved with PSF for use in next iteration and to check convergence. OPTIONAL INPUT KEYWORDS: /GAUSSIAN causes max-likelihood iteration for Gaussian additive noise to be used, otherwise the default is Poisson statistics. FT_PSF = passes (out/in) the Fourier transform of the PSF, so that it can be reused for the next time procedure is called, /NO_FT overrides the use of FFT, using the IDL function convol() instead. POSITIVITY_EPS = value of epsilon passed to function positivity, default = -1 which means no action (identity). UNDERFLOW_ZERO = cutoff to consider as zero, if numbers less than this. EXTERNAL CALLS: function convolve( image, psf ) for convolutions using FFT or otherwise. function positivity( image, EPS= ) to make image positive. METHOD: Maximum Likelihood solution is a fixed point of an iterative eq. (derived by setting partial derivatives of Log(Likelihood) to zero). Poisson noise case was derived by Richardson(1972) & Lucy(1974). Gaussian noise case is similar with subtraction instead of division. HISTORY: written: Frank Varosi at NASA/GSFC, 1992. F.V. 1993, added optional arg. Re_conv (to avoid doing it twice). Converted to IDL V5.0 W. Landsman September 1997
(See ../pfidl/astro_lib/max_likelihood.pro)
NAME: MKHDR PURPOSE: Make a minimal primary (or IMAGE extension) FITS header EXPLANATION: If an array is supplied, then the created FITS header will be appropriate to the supplied array. Otherwise, the user can specify the dimensions and datatype. CALLING SEQUENCE: MKHDR, header ;Prompt for image size and type or MKHDR, header, im, [ /IMAGE, /EXTEND ] or MKHDR, header, type, naxisx, [/IMAGE, /EXTEND ] OPTIONAL INPUTS: IM - If IM is a vector or array then the header will be made appropriate to the size and type of IM. IM does not have to be the actual data; it can be a dummy array of the same type and size as the data. Set IM = '' to create a dummy header with NAXIS = 0. TYPE - If more than 2 parameters are supplied, then the second parameter is interpreted as an integer giving the IDL datatype e.g. 1 - LOGICAL*1, 2 - INTEGER*2, 4 - REAL*4, 3 - INTEGER*4 NAXISX - Vector giving the size of each dimension (NAXIS1, NAXIS2, etc.). OUTPUT: HEADER - image header, (string array) with required keywords BITPIX, NAXIS, NAXIS1, ... Further keywords can be added to the header with SXADDPAR. OPTIONAL INPUT KEYWORDS: /IMAGE = If set, then a minimal header for a FITS IMAGE extension is created. An IMAGE extension header is identical to a primary FITS header except the first keyword is 'XTENSION' = 'IMAGE' instead of 'SIMPLE ' = 'T' /EXTEND = If set, then the keyword EXTEND is inserted into the file, with the value of "T" (true). The EXTEND keyword must be included in a primary header, if the FITS file contains extensions. RESTRICTIONS: (1) MKHDR should not be used to make an STSDAS header or a FITS ASCII or Binary Table extension header. Instead use SXHMAKE - to create a minimal STSDAS header FXBHMAKE - to create a minimal FITS binary table header FTCREATE - to create a minimal FITS ASCII table header (2) Any data already in the header before calling MKHDR will be destroyed. EXAMPLE: Create a minimal FITS header, Hdr, for a 30 x 40 x 50 INTEGER*2 array IDL> mkhdr, Hdr, 2, [30,40,50] Alternatively, if the array already exists as an IDL variable, Array, IDL> mkhdr, Hdr, Array PROCEDURES CALLED: SXADDPAR, GET_DATE REVISION HISTORY: Written November, 1988 W. Landsman May, 1990, Adapted for IDL Version 2.0, J. Isensee Aug, 1997, Use SYSTIME(), new DATE format W. Landsman Converted to IDL V5.0 W. Landsman September 1997 Allow unsigned data types W. Landsman December 1999 Set BZERO = 0 for unsigned integer data W. Landsman January 2000 EXTEND keyword must immediately follow last NAXISi W. Landsman Sep 2000 Add FITS definition COMMENT to primary headers W. Landsman Oct. 2001 Allow (nonstandard) 64 bit integers W. Landsman Feb. 2003
(See ../pfidl/astro_lib/mkhdr.pro)
NAME: MRDFITS PURPOSE: Read all standard FITS data types into arrays or structures. EXPLANATION: Further information on MRDFITS is available at http://idlastro.gsfc.nasa.gov/mrdfits.html CALLING SEQUENCE: Result = MRDFITS( Filename/FileUnit,[Extension, Header], /FSCALE , /DSCALE , /UNSIGNED, ALIAS=strarr[2,n], /USE_COLNUM, /NO_TDIM, /OLD_STRUCT, $ /POINTER_VAR, /FIXED_VAR, RANGE=[a,b], COLUMNS=[a,b,...]), ERROR_ACTION=x, COMPRESS=comp_prog, STATUS=status, /VERSION ) INPUTS: Filename = String containing the name of the file to be read or file number of an open unit. If a unit is specified if will be left open positioned to read the next HDU. Note that the file name may be of the form name.gz or name.Z on UNIX systems. If so the file will be dynamically decompressed. FiluUnit = An integer file unit which has already been opened for input. Data will be read from this unit and the unit will be left pointing immediately after the HDU that is read. Thus to read a compressed file with many HDU's a user might do something like: lun=fxposit(filename, 3) ; Skip the first three HDU's repeat begin thisHDU = mrdfits(lun, 0, hdr, status=status) ... process the HDU ... endrep until status lt 0 Extension= Extension number to be read, 0 for primary array. Assumed 0 if not specified. If a unit rather than a filename is specified in the first argument, this is the number of HDU's to skip from the current position. OUTPUTS: Result = FITS data array or structure constructed from the designated extension. The format of result depends upon the type of FITS data read. Non-group primary array or IMAGE extension: A simple multidimensional array is returned with the dimensions given in the NAXISn keywords. Grouped image data with PCOUNT=0. As above but with GCOUNT treated as NAXIS(n+1). Grouped image data with PCOUNT>0. The data is returned as an array of structures. Each structure has two elements. The first is a one-dimensional array of the group parameters, the second is a multidimensional array as given by the NAXIS2-n keywords. ASCII and BINARY tables. The data is returned as a structure with one column for each field in the table. The names of the columns are normally taken from the TTYPE keywords (but see USE_COLNUM). Bit field columns are stored in byte arrays of the minimum necessary length. Column names are truncated to 15 characters if longer, spaces are removed, and invalid characters are replaced by underscores. Columns specified as variable length columns are stored with a dimension equal to the largest actual dimension used. Extra values in rows are filled with 0's or blanks. If the size of the variable length column is not a constant, then an additional column is created giving the size used in the current row. This additional column will have a tag name of the form L#_"colname" where # is the column number and colname is the column name of the variable length column. If the length of each element of a variable length column is 0 then the column is deleted. Prior to V5.0, IDL structures were limited to 128 tags. If the version is before V5.0, or the /OLD_STRUCT is set, then for FITS files with more than 127 columns, data in the first 64 elements of the structure are stored in the primary structure, the next 64 as a substructure of the 65th element, the next 64 as a substructure of the 66th element and so forth. OPTIONAL OUTPUT: Header = String array containing the header from the FITS extension. OPTIONAL INPUT KEYWORDS: ALIAS The keyword allows the user to specify the column names to be created when reading FITS data. The value of this keyword should be a 2xn string array. The first value of each pair of strings should be the desired tag name for the IDL column. The second should be the FITS TTYPE value. Note that there are restrictions on valid tag names. The order of the ALIAS keyword is compatible with MWRFITS. COLUMNS - This keyword allows the user to specify that only a subset of columns is to be returned. The columns may be specified either as number 1,... n or by name or some combination of these two. If USE_COLNUM is specified names should be C1,...Cn. The use of this keyword will not save time or internal memory since the extraction of specified columns is done after all columns have been retrieved from the FITS file. COMPRESS - This keyword allows the user to specify a decompression program to use to decompress a file that will not be automatically recognized based upon the file name. /DSCALE - As with FSCALE except that the resulting data is stored in doubles. ERROR_ACTION - Set the on_error action to this value (defaults to 2). /FIXED_VAR- Translate variable length columns into fixed length columns and provide a length column for truly varying columns. This was only behavior prior to V2.5 or MRDFITS and remains the default (see /POINTER_VAR) /FSCALE - If present and non-zero then scale data to float numbers for arrays and columns which have either non-zero offset or non-unity scale. If scaling parameters are applied, then the corresponding FITS scaling keywords will be modified. NO_TDIM - Disable processing of TDIM keywords. If NO_TDIM is specified MRDFITS will ignore TDIM keywords in binary tables. OLD_STRUCT- Use the recursive structures formats required prior to IDL 5.0 for tables with more than 127 columns. /POINTER_VAR- Use pointer arrays for variable length columns. In addition to changing the format in which variable length arrays are stored, if the pointer_var keyword is set to any value other than 1 this also disables the deletion of variable length columns. (See /FIXED_VAR) RANGE - A scalar or two element vector giving the start and end rows to be retrieved. For ASCII and BINARY tables this specifies the row number. For GROUPed data this will specify the groups. For array images, this refers to the last non-unity index in the array. E.g., for a 3 D image with NAXIS* values = [100,100,1], the range may be specified as 0:99, since the last axis is suppressed. Note that the range uses IDL indexing So that the first row is row 0. If only a single value, x, is given in the range, the range is assumed to be [0,x-1]. /SILENT - Suppress informative messages. STRUCTYP - The structyp keyword specifies the name to be used for the structure defined when reading ASCII or binary tables. Generally users will not be able to conveniently combine data from multiple files unless the STRUCTYP parameter is specified. An error will occur if the user specifies the same value for the STRUCTYP keyword in calls to MRDFITS in the same IDL session for extensions which have different structures. TEMPDIR - The tempdir keyword allows the user to specify the directory where temporary files may be created. This directory should be both in the IDL path and writable by the user. Generally only needed for IDL /UNSIGNED - For integer data with appropriate zero points and scales read the data into unsigned integer arrays. /USE_COLNUM - When creating column names for binary and ASCII tables MRDFITS attempts to use the appropriate TTYPE keyword values. If USE_COLNUM is specified and non-zero then column names will be generated as 'C1, C2, ... 'Cn' for the number of columns in the table. /VERSION Print the current version number OPTIONAL OUTPUT KEYWORDS: STATUS - A integer status indicating success or failure of the request. A status of >=0 indicates a successful read. Currently 0 -> successful completion -1 -> error -2 -> end of file EXAMPLE: Read a FITS primary array: a = mrdfits('TEST.FITS') or a = mrdfits('TEST.FITS', 0, header) The second example also retrieves header information. Read rows 10-100 of the second extension of a FITS file. a = mrdfits('TEST.FITS', 2, header, range=[10,100]) Read a table and ask that any scalings be applied and the scaled data be converted to doubles. Use simple column names, suppress outputs. a = mrdfits('TEST.FITS', 1, /dscale, /use_colnum, /silent) RESTRICTIONS: (1) Cannot handle data in non-standard FITS formats. (2) Doesn't do anything with BLANK or NULL values or NaN's. They are just read in. They may be scaled if scaling is applied. NOTES: This multiple format FITS reader is designed to provide a single, simple interface to reading all common types of FITS data. MRDFITS DOES NOT scale data by default. The FSCALE or DSCALE parameters must be used. As of version 2.5 MRDFITS support 64 bit integer data types. These are not standard FITS. 64 bit data also requires IDL version 5.2 or greater. PROCEDURES USED: The following procedures are contained in the main MRDFITS program. MRD_IMAGE -- Generate array/structure for images. MRD_READ_IMAGE -- Read image data. MRD_ASCII -- Generate structure for ASCII tables. MRD_READ_ASCII -- Read an ASCII table. MRD_TABLE -- Generate structure for Binary tables. MRD_READ_TABLE -- Read binary table info. MRD_READ_HEAP -- Read variable length record info. MRD_SCALE -- Apply scaling to data. MRD_COLUMNS -- Extract columns. Other ASTRON Library routines used FXPAR(), FXADDPAR, IEEE_TO_HOST, FXPOSIT, FXMOVE(), IS_IEEE_BIG() MRD_STRUCT(), MRD_SKIP MODIfICATION HISTORY: V1.0 November 9, 1994 ---- Initial release. Creator: Thomas A. McGlynn V1.1 January 20, 1995 T.A. McGlynn Fixed bug in variable length records. Added TDIM support -- new routine mrd_tdim in MRD_TABLE. V1.2 Added support for dynamic decompression of files. Fixed further bugs in variable length record handling. V1.2a Added NO_TDIM keyword to turn off TDIM processing for those who don't want it. Bug fixes: Handle one row tables correctly, use BZERO rather than BOFFSET. Fix error in scaling of images. V1.2b Changed MRD_HREAD to handle null characters in headers. V2.0 April 1, 1996 -Handles FITS tables with an arbitrary number of columns. -Substantial changes to MRD_STRUCT to allow the use of substructures when more than 127 columns are desired. -All references to table columns are now made through the functions MRD_GETC and MRD_PUTC. See description above. -Use of SILENT will now eliminate compilation messages for temporary functions. -Bugs in handling of variable length columns with either a single row in the table or a maximum of a single element in the column fixed. -Added support for DCOMPLEX numbers in binary tables (M formats) for IDL versions above 4.0. -Created regression test procedure to check in new versions. -Added error_action parameter to allow user to specify on_error action. This should allow better interaction with new CHECK facility. ON_ERROR statements deleted from most called routines. - Modified MRDFITS to read in headers containing null characters with a warning message printed. V2.0a April 16, 1996 - Added IS_IEEE_BIG() checks (and routine) so that we don't worry about IEEE to host conversions if the machine's native format is IEEE Big-endian. V2.1 August 24, 1996 - Use resolve_routine for dynamically defined functions for versions > 4.0 - Fix some processing in random groups format. - Handle cases where the data segment is--legally--null. In this case MRDFITS returns a scalar 0. - Fix bugs with the values for BSCALE and BZERO (and PSCAL and PZERO) parameters set by MRDFITS. V2.1a April 24, 1997 Handle binary tables with zero length columns V2.1b May 13,1997 Remove whitespace from replicate structure definition V2.1c May 28,1997 Less strict parsing of XTENSION keyword V2.1d June 16, 1997 Fixed problem for >32767 entries introduced 24-Apr V2.1e Aug 12, 1997 Fixed problem handling double complex arrays V2.1f Oct 22, 1997 IDL reserved words can't be structure tag names Converted to IDL V5.0 W. Landsman 2-Nov-1997 V2.1g Nov 24, 1997 Handle XTENSION keywords with extra blanks. V2.1h Jul 26, 1998 More flexible parsing of TFORM characters V2.2 Dec 14, 1998 Allow fields with longer names for later versions of IDL. Fix handling of arrays in scaling routines. Allow >128 fields in structures for IDL >4.0 Use more efficient structure copying for IDL>5.0 V2.2b June 17, 1999 Fix bug in handling case where all variable length columns are deleted because they are empty. V2.3 March 7, 2000 Allow user to supply file handle rather than file name. Added status field. Now needs FXMOVE routine V2.3b April 4, 2000 Added compress option (from D. Palmer) V2.4 July 4, 2000 Added STATUS=-1 for "File access error" (Zarro/GSFC) V2.4a May 2, 2001 Trim binary format string (W. Landsman) V2.5 December 5, 2001 Add unsigned, alias, 64 bit integers. version, $ /pointer_val, /fixed_var. V2.5a Fix problem when both the first and the last character in a TTYPEnn value are invalid structure tag characters V2.6 February 15, 2002 Fix error in handling unsigned numbers, $ and 64 bit unsigneds. (Thanks to Stephane Beland) V2.6a September 2, 2002 Fix possible conflicting data structure for variable length arrays (W. Landsman) Note to users of IDL prior to V5.0: This version is compiled with the [] array syntax. To convert this version to run under the earlier syntax you use W. Landsman's IDL5to4 routine at http://idlastro.gsfc.nasa.gov/ftp/contrib/landsman/v5. You need to change all array subscripts from the [] to () but this cannot be done as a global replace since array initializations of the form x=[1,2] must be left unchanged. Subroutines called by this routine may need similar modification. Also the use of the pointer syntax (in versions 2.5 and above is not parseable by earlier version of IDL.
(See ../pfidl/astro_lib/mrdfits.pro)
NAME: MRD_HREAD PURPOSE: Reads a FITS header from an opened disk file or Unix pipe EXPLANATION: Like FXHREAD but also works with compressed Unix files CALLING SEQUENCE: MRD_HREAD, UNIT, HEADER [, STATUS, /SILENT ] INPUTS: UNIT = Logical unit number of an open FITS file OUTPUTS: HEADER = String array containing the FITS header. OPT. OUTPUTS: STATUS = Condition code giving the status of the read. Normally, this is zero, but is set to -1 if an error occurs, or if the first byte of the header is zero (ASCII null). OPTIONAL KEYWORD INPUT: /SILENT - If set, then warning messages about any invalid characters in the header are suppressed. /FIRSTBLOCK - If set, then only the first block (36 lines or less) of the FITS header are read into the output variable. If only size information (e.g. BITPIX, NAXIS) is needed from the header, then the use of this keyword can save time. The file pointer is still positioned at the end of the header, even if the /FIRSTBLOCK keyword is supplied. RESTRICTIONS: The file must already be positioned at the start of the header. It must be a proper FITS file. SIDE EFFECTS: The file ends by being positioned at the end of the FITS header, unless an error occurs. REVISION HISTORY: Written, Thomas McGlynn August 1995 Modified, Thomas McGlynn January 1996 Changed MRD_HREAD to handle Headers which have null characters A warning message is printed out but the program continues. Previously MRD_HREAD would fail if the null characters were not in the last 2880 byte block of the header. Note that such characters are illegal in the header but frequently are produced by poor FITS writers. Converted to IDL V5.0 W. Landsman September 1997 Added /SILENT keyword W. Landsman December 2000 Added /FIRSTBLOCK keyword W. Landsman February 2003
(See ../pfidl/astro_lib/mrd_hread.pro)
NAME: MRD_SKIP PURPOSE: Skip a number of bytes from the current location in a file or a pipe EXPLANATION: First tries using POINT_LUN and if this doesn't work, perhaps because the unit is a pipe, MRD_SKIP will just read in the requisite number of bytes. GZIP files opened with /COMPRESS (in V5.3 or later) are also read as a series of bytes, since this is faster than using POINT_LUN when not at the beginning of a file. CALLING SEQUENCE: MRD_SKIP, Unit, Nskip INPUTS: Unit - File unit for the file or pipe in question, integer scalar Nskip - Number of bytes to be skipped, positive integer NOTES: This routine should be used in place of POINT_LUN wherever a pipe may be the input unit (see the procedure FXPOSIT for an example). Note that it assumes that it can only work with nskip >= 0 so it doesn't even try for negative values. For reading a pipe, MRD_SKIP currently uses a maximum buffer size of 8 MB. This chunk value can be increased for improved efficiency (or decreased if you really have little memory.) REVISION HISTORY: Written, Thomas A. McGlynn July 1995 Don't even try to skip bytes on a pipe with POINT_LUN, since this might reset the current pointer W. Landsman April 1996 Increase buffer size, check fstat.compress W. Landsman Jan 2001 Only a warning if trying read past EOF W. Landsman Sep 2001
(See ../pfidl/astro_lib/mrd_skip.pro)
NAME: MRD_STRUCT PURPOSE: Return a structure as defined in the names and values data. CALLING SEQUENCE: struct = MRD_STRUCT(NAMES, VALUES, NROW, $ STRUCTYP=structyp, $ TEMPDIR=tempdir, /OLD_STRUCT) INPUT PARAMETERS: NAMES = A string array of names of structure fields. VALUES = A string array giving the values of the structure fields. See examples below. NROW = The number of elements in the structure array. RETURNS: A structure as described in the parameters or 0 if an error is detected. OPTIONAL KEYWORD PARAMETERS: STRUCTYP = The structure type. Since IDL does not allow the redefinition of a named structure it is an error to call MRD_STRUCT with different parameters but the same STRUCTYP in the same session. If this keyword is not set an anonymous structure is created. TEMPDIR = If the structure is more than modestly complex a temporary file is created. This file will be created in the current directory unless the TEMPDIR keyword is specified. Note that the temporary directory should also be in the IDL search path. OLD_STRUCT=Use old format structures. COMMON BLOCKS: MRD_COMMON SIDE EFFECTS: May create a temporary file if the structure definition is too long for the EXECUTE function and using old style structures RESTRICTIONS: By default this program uses a series of execute commands and create_struct's to create the structure. If the old_struct keyword is set, then a program may be dynamically compiled. The nominal maximum length of the execute string is 131 characters, but many systems seem to allow longer values. This code may execute more efficiently with a longer execute buffer. PROCEDURE: A structure definition is created using the parameter values. MRD_NSTRUCT is called if the OLD_STRUCT keyword is not specified and generates the structure in pieces using the execute and create_struct keywords. If the old_struct flag is set, then the program tries to compile the structure with a single execute command. If the structure definition is too long MRD_FSTRUCT is called to write, compile and execute a function which will define the structure. EXAMPLES: str = mrd_struct(['fld1', 'fld2'], ['0','dblarr(10,10)'],3) print, str(0).fld2(3,3) str = mrd_struct(['a','b','c','d'],['1', '1.', '1.d0', "'1'"],1) ; returns a structure with integer, float, double and string ; fields. PROCEDURE CALLS: CONCAT_DIR - Used to concatenate temporary directory with filename MODIFICATION HISTORY: Created by T. McGlynn October, 1994. Modified by T. McGlynn September, 1995. Added capability to create substructures so that structure may contain up to 4096 distinct elements. [This can be increased by futher iteration of the process used if needed.] Converted to IDL V5.0 W. Landsman September 1997 Removed V4.0 reference to common block October 1997 Allowed unlimited number of structure elements if the version is greater than 5.0. Put back in code to handle prior versions. The [] will need to be translated back to () for this to work. T. McGlynn December 15 1998. Add MRD_NSTRUCT since IDL has mysterious problems compiling very large structures.
(See ../pfidl/astro_lib/mrd_struct.pro)
NAME: PKFIT PURPOSE: Subroutine of GETPSF to perform a one-star least-squares fit EXPLANATION: Part of the DAOPHOT PSF photometry sequence CALLING SEQUENCE: PKFIT, f, scale, x, y, sky, radius, ronois, phpadu, gauss, psf, errmag, chi, sharp, Niter, /DEBUG INPUTS: F - NX by NY array containing actual picture data. X, Y - the initial estimates of the centroid of the star relative to the corner (0,0) of the subarray. Upon return, the final computed values of X and Y will be passed back to the calling routine. SKY - the local sky brightness value, as obtained from APER RADIUS- the fitting radius-- only pixels within RADIUS of the instantaneous estimate of the star's centroid will be included in the fit, scalar RONOIS - readout noise per pixel, scalar PHPADU - photons per analog digital unit, scalar GAUSS - vector containing the values of the five parameters defining the analytic Gaussian which approximates the core of the PSF. PSF - an NPSF by NPSF look-up table containing corrections from the Gaussian approximation of the PSF to the true PSF. INPUT-OUTPUT: SCALE - the initial estimate of the brightness of the star, expressed as a fraction of the brightness of the PSF. Upon return, the final computed value of SCALE will be passed back to the calling routine. OUTPUTS: ERRMAG - the estimated standard error of the value of SCALE returned by this routine. CHI - the estimated goodness-of-fit statistic: the ratio of the observed pixel-to-pixel mean absolute deviation from the profile fit, to the value expected on the basis of the noise as determined from Poisson statistics and the readout noise. SHARP - a goodness-of-fit statistic describing how much broader the actual profile of the object appears than the profile of the PSF. NITER - the number of iterations the solution required to achieve convergence. If NITER = 25, the solution did not converge. If for some reason a singular matrix occurs during the least- squares solution, this will be flagged by setting NITER = -1. RESTRICTIONS: No parameter checking is performed REVISON HISTORY: Adapted from the official DAO version of 1985 January 25 Version 2.0 W. Landsman STX November 1988 Converted to IDL V5.0 W. Landsman September 1997
(See ../pfidl/astro_lib/pkfit.pro)
NAME: POSITIVITY PURPOSE: Map an image uniquely and smoothly into all positive values. EXPLANATION: Take unconstrained x (usually an image), and map it uniquely and smoothly into positive values. Negative values of x get mapped to interval ( 0, sqrt( epsilon )/2 ], positive values go to ( sqrt( epsilon )/2, oo ) with deriv approaching 1. Derivative is always 1/2 at x=0. Derivative is used by the MRL deconvolution algorithm. CALLING SEQUENCE: result = POSITIVITY( x, [ /DERIVATIVE, EPSILON = ) INPUTS: x - input array, unconstrained OUTPUT: result = output array = ((x + sqrt(x^2 + epsilon))/2 if the /DERIV keyword is set then instead the derivative of the above expression with respect to X is returned OPTIONAL INPUT KEYWORDS: DERIV - if this keyword set, then the derivative of the positivity mapping is returned, rather than the mapping itself EPSILON - real scalar specifying the interval into which to map negative values. If EPSILON EQ 0 then the mapping reduces to positive truncation. If EPSILON LT then the mapping reduces to an identity (no change). Default is EPSILON = 1e-9 REVISION HISTORY: F.Varosi NASA/GSFC 1992, as suggested by R.Pina UCSD. Converted to IDL V5.0 W. Landsman September 1997
(See ../pfidl/astro_lib/positivity.pro)
NAME: PSF_GAUSSIAN PURPOSE: Create a 1-d, 2-d, or 3-d Gaussian with specified FWHM, center EXPLANATION: Return a point spread function having Gaussian profiles, as either a 1D vector, a 2D image, or 3D volumetric-data. CALLING SEQUENCE: psf = psf_Gaussian( NPIXEL=, FWHM= , CENTROID = [ /DOUBLE, /NORMALIZE, /ST_DEV, NDIMEN= ] ) or: psf = psf_Gaussian( parameters, NPIXEL = ,NDIMEN = ) REQUIRED INPUT KEYWORD: NPIXEL = number pixels for each dimension, specify as an array, or just one number to make all sizes equal. OPTIONAL KEYWORDS: CENTROID = floating scalar or vector giving position of PSF center. default is exact center of requested vector/image/volume. The number of elements in CENTROID should equal the number of dimensions. **The definition of Centroid was changed in March 2002, and now an integer defines the center of a pixel.** /DOUBLE = If set, then the output array is computed in double precision the default is to return a floating point array. FWHM = the desired Full-Width Half-Max (pixels) in each dimension, specify as an array, or single number to make all the same. NDIMEN = integer dimension of result: either 1 (vector), 2 (image), or 3 (volume), default = 2 (an image result). /NORMALIZE causes resulting PSF to be normalized so Total( psf ) = 1. STDEV = optional way to specify width by standard deviation param. XY_CORREL = scalar between 0 and 1 specifying correlation coefficient Use this keyword, for example, to specify an elliptical Gaussian oriented at an angle to the X,Y axis. Only valid for 2-dimensional case. INPUTS (optional): parameters = an NDIMEN by 3 array giving for each dimension: [ maxval, center, stdev ], overrides other keywords. EXAMPLE: (1) Create a 31 x 31 array containing a normalized centered Gaussian with an X FWHM = 4.3 and a Y FWHM = 3.6 IDL> array = PSF_GAUSSIAN( Npixel=31, FWHM=[4.3,3.6], /NORMAL ) (2) Create a 50 pixel 1-d Gaussian vector with a maximum of 12, centered at pixel 23 with a sigma of 19.2 IDL> psf = psf_gaussian([12,23,19.2],npixel=50) EXTERNAL CALLS: function Gaussian() NOTES: To improve speed, floating underflow exceptions are suppressed (using the MASK=32 keyword of CHECK_MATH() rather than being flagged. HISTORY: Written, Frank Varosi NASA/GSFC 1991. Converted to IDL V5.0 W. Landsman September 1997 Suppress underflow messages, add DOUBLE keyword. **Modified centroid definition so integer position is pixel center** W. Landsman March 2002
(See ../pfidl/astro_lib/psf_gaussian.pro)
NAME: READFITS PURPOSE: Read a FITS file into IDL data and header variables. EXPLANATION: See http://idlastro.gsfc.nasa.gov/fitsio.html for other ways of reading FITS files with IDL. CALLING SEQUENCE: Result = READFITS( Filename/Fileunit,[ Header, heap, /NOSCALE, EXTEN_NO=, NSLICE=, /SILENT, STARTROW =, NUMROW = , HBUFFER=, /COMPRESS, /No_Unsigned ] ) INPUTS: Filename = Scalar string containing the name of the FITS file (including extension) to be read. If the filename has a *.gz extension, it will be treated as a gzip compressed file. If it has a .Z extension, it will be treated as a Unix compressed file. OR Fileunit - A scalar integer specifying the unit of an already opened FITS file. The unit will remain open after exiting READFITS(). There are two possible reasons for choosing to specify a unit number rather than a file name: (1) For a FITS file with many extensions, one can move to the desired extensions with FXPOSIT() and then use READFITS(). This is more efficient that repeatedly starting at the beginning of the file. (2) For reading a FITS file across a Web http: address after opening the unit with the SOCKET procedure (IDL V5.4 or later, Unix and Windows only) OUTPUTS: Result = FITS data array constructed from designated record. If the specified file was not found, then Result = -1 OPTIONAL OUTPUT: Header = String array containing the header from the FITS file. If you don't need the header, then the speed may be improved by not supplying this parameter. heap = For extensions, the optional heap area following the main data array (e.g. for variable length binary extensions). OPTIONAL INPUT KEYWORDS: /COMPRESS - Signal that the file is gzip compressed. By default, READFITS will assume that if the file name extension ends in '.gz' then the file is gzip compressed. The /COMPRESS keyword is required only if the the gzip compressed file name does not end in '.gz'. Keyword only valid for IDL V5.3 or later. EXTEN_NO - positive scalar integer specifying the FITS extension to read. For example, specify EXTEN = 1 or /EXTEN to read the first FITS extension. /NOSCALE - If present and non-zero, then the ouput data will not be scaled using the optional BSCALE and BZERO keywords in the FITS header. Default is to scale. /NO_UNSIGNED -By default, if the header indicates an unsigned integer (BITPIX = 16, BZERO=2^15, BSCALE=1) then FITS_READ will output an IDL unsigned integer data type (UINT). But if /NO_UNSIGNED is set, then the data is converted to type LONG. NSLICE - Non-negative integer scalar specifying which N-1 dimensional slice of a N-dimensional array to read. For example, if the primary image of a file 'wfpc.fits' contains a 800 x 800 x 4 array, then IDL> im = readfits('wfpc.fits',h, nslice=2) is equivalent to IDL> im = readfits('wfpc.fits',h) IDL> im = im[*,*,2] but the use of the NSLICE keyword is much more efficient. NUMROW - Scalar non-negative integer specifying the number of rows of the image or table extension to read. Useful when one does not want to read the entire image or table. POINT_LUN - Position (in bytes) in the FITS file at which to start reading. Useful if READFITS is called by another procedure which needs to directly read a FITS extension. Should always be a multiple of 2880, and not be used with EXTEN_NO keyword. /SILENT - Normally, READFITS will display the size the array at the terminal. The SILENT keyword will suppress this STARTROW - Non-negative integer scalar specifying the row of the image or extension table at which to begin reading. Useful when one does not want to read the entire table. HBUFFER - Number of lines in the header, set this to slightly larger than the expected number of lines in the FITS header, to improve performance when reading very large FITS headers. Should be a multiple of 36 -- otherwise it will be modified to the next higher multiple of 36. Default is 180 EXAMPLE: Read a FITS file test.fits into an IDL image array, IM and FITS header array, H. Do not scale the data with BSCALE and BZERO. IDL> im = READFITS( 'test.fits', h, /NOSCALE) If the file contains a FITS extension, it could be read with IDL> tab = READFITS( 'test.fits', htab, /EXTEN ) The function TBGET() can be used for further processing of a binary table, and FTGET() for an ASCII table. To read only rows 100-149 of the FITS extension, IDL> tab = READFITS( 'test.fits', htab, /EXTEN, STARTR=100, NUMR = 50 ) To read in a file that has been compressed: IDL> tab = READFITS('test.fits.gz',h) ERROR HANDLING: If an error is encountered reading the FITS file, then (1) the system variable !ERROR is set (via the MESSAGE facility) (2) the error message is displayed (unless /SILENT is set), and the message is also stored in !ERR_STRING (3) READFITS returns with a value of -1 RESTRICTIONS: (1) Cannot handle random group FITS NOTES: (1) If data is stored as integer (BITPIX = 16 or 32), and BSCALE and/or BZERO keywords are present, then the output array is scaled to floating point (unless /NOSCALE is present) using the values of BSCALE and BZERO. In the header, the values of BSCALE and BZERO are then reset to 1. and 0., while the original values are written into the new keywords O_BSCALE and O_BZERO. If the BLANK keyword was present, then any input integer values equal to BLANK in the input integer image are unchanged by BSCALE or BZERO (2) The use of the NSLICE keyword is incompatible with the NUMROW or STARTROW keywords. (3) READFITS() underwent a substantial rewrite in October 1998 to eliminate recursive calls, and improve efficiency when reading extensions. 1. The NUMROW and STARTROW keywords can now be used when reading a primary image (extension = 0). 2. There is no error check for moving past the end of file when reading the data array. (4) On some Unix shells, one may get a "Broken pipe" message if reading a UNIX compressed file, and not reading to the end of the file (i.e. the decompression has not gone to completion). This is an informative message only, and should not affect the output of READFITS(). PROCEDURES USED: Functions: SXPAR() Procedures: SXADDPAR, SXDELPAR MODIFICATION HISTORY: Original Version written in 1988, W.B. Landsman Raytheon STX Revision History prior to October 1998 removed Major rewrite to eliminate recursive calls when reading extensions W.B. Landsman Raytheon STX October 1998 Add /binary modifier needed for Windows W. Landsman April 1999 Read unsigned datatypes, added /no_unsigned W. Landsman December 1999 Output BZERO = 0 for unsigned data types W. Landsman January 2000 Open with /swap_if_little_endian if since V5.1 W. Landsman February 2000 Fixed logic error when using NSLICE keyword W. Landsman March 2000 Fixed byte swapping problem for compressed files on little endian machines introduced in Feb 2000 W. Landsman April 2000 Fix error handling so FREE_LUN is called in case of READU error W. Landsman N. Rich, Aug. 2000 Assume since V5.1, remove NANvalue keyword W. Landsman July 2001 Support the unofficial 64bit integer format W. Landsman September 2001 Option to read a unit number rather than file name W.L October 2001 Fix byte swapping problem for compressed files again (sigh...) W. Landsman March 2002 Make sure gzip defined when using a unit number W. Landsman Oct. 2002 Assume V5.2 or later W. Landsman Jan. 2003 Don't read entire header unless needed W. Landsman Jan. 2003 Added HBUFFER keyword W. Landsman Feb. 2003
(See ../pfidl/astro_lib/readfits.pro)
NAME: STRN PURPOSE: Convert a number to a string and remove padded blanks. EXPLANATION: The main and original purpose of this procedure is to convert a number to an unpadded string (i.e. with no blanks around it.) However, it has been expanded to be a multi-purpose formatting tool. You may specify a length for the output string; the returned string is either set to that length or padded to be that length. You may specify characters to be used in padding and which side to be padded. Finally, you may also specify a format for the number. NOTE that the input "number" need not be a number; it may be a string, or anything. It is converted to string. CALLING SEQEUNCE: tmp = STRN( number, [ LENGTH=, PADTYPE=, PADCHAR=, FORMAT = ] ) INPUT: NUMBER This is the input variable to be operated on. Traditionally, it was a number, but it may be any scalar type. OPTIONAL INPUT: LENGTH This KEYWORD specifies the length of the returned string. If the output would have been longer, it is truncated. If the output would have been shorter, it is padded to the right length. PADTYPE This KEYWORD specifies the type of padding to be used, if any. 0=Padded at End, 1=Padded at front, 2=Centered (pad front/end) IF not specified, PADTYPE=1 PADCHAR This KEYWORD specifies the character to be used when padding. The default is a space (' '). FORMAT This keyword allows the FORTRAN type formatting of the input number (e.g. '(f6.2)') OUTPUT: tmp The formatted string USEFUL EXAMPLES: print,'Used ',strn(stars),' stars.' ==> 'Used 22 stars.' print,'Attempted ',strn(ret,leng=6,padt=1,padch='0'),' retries.' ==> 'Attempted 000043 retries.' print,strn('M81 Star List',length=80,padtype=2) ==> an 80 character line with 'M81 Star List' centered. print,'Error: ',strn(err,format='(f15.2)') ==> 'Error: 3.24' or ==> 'Error: 323535.22' HISTORY: 03-JUL-90 Version 1 written by Eric W. Deutsch 10-JUL-90 Trimming and padding options added (E. Deutsch) 29-JUL-91 Changed to keywords and header spiffed up (E. Deutsch) Ma7 92 Work correctly for byte values (W. Landsman) 19-NOV-92 Added Patch to work around IDL 2.4.0 bug which caused an error when STRN('(123)') was encountered. (E. Deutsch) Converted to IDL V5.0 W. Landsman September 1997
(See ../pfidl/astro_lib/strn.pro)
NAME: SXADDPAR PURPOSE: Add or modify a parameter in a FITS header array. CALLING SEQUENCE: SXADDPAR, Header, Name, Value, [ Comment, Location, /SaveComment, BEFORE =, AFTER = , FORMAT= , /PDU] INPUTS: Header = String array containing FITS or STSDAS header. The length of each element must be 80 characters. If not defined, then SXADDPAR will create an empty FITS header array. Name = Name of parameter. If Name is already in the header the value and possibly comment fields are modified. Otherwise a new record is added to the header. If name is equal to 'COMMENT' or 'HISTORY' or a blank string then the value will be added to the record without replacement. For these cases, the comment parameter is ignored. Value = Value for parameter. The value expression must be of the correct type, e.g. integer, floating or string. String values of 'T' or 'F' are considered logical values. OPTIONAL INPUT PARAMETERS: Comment = String field. The '/' is added by this routine. Added starting in position 31. If not supplied, or set equal to '', or /SAVECOMMENT is set, then the previous comment field is retained (when found) Location = Keyword string name. The parameter will be placed before the location of this keyword. This parameter is identical to the BEFORE keyword and is kept only for consistency with earlier versions of SXADDPAR. OPTIONAL INPUT KEYWORD PARAMETERS: BEFORE = Keyword string name. The parameter will be placed before the location of this keyword. For example, if BEFORE='HISTORY' then the parameter will be placed before the first history location. This applies only when adding a new keyword; keywords already in the header are kept in the same position. AFTER = Same as BEFORE, but the parameter will be placed after the location of this keyword. This keyword takes precedence over BEFORE. FORMAT = Specifies FORTRAN-like format for parameter, e.g. "F7.3". A scalar string should be used. For complex numbers the format should be defined so that it can be applied separately to the real and imaginary parts. If not supplied then the default is 'G19.12' for double precision, and 'G14.7' for floating point. /PDU = specifies keyword is to be added to the primary data unit header. If it already exists, it's current value is updated in the current position and it is not moved. /SAVECOMMENT = if set, then any existing comment is retained, i.e. the COMMENT parameter only has effect if the keyword did not previously exist in the header. OUTPUTS: Header = updated FITS header array. EXAMPLE: Add a keyword 'TELESCOP' with the value 'KPNO-4m' and comment 'Name of Telescope' to an existing FITS header h. IDL> sxaddpar, h, 'TELESCOPE','KPNO-4m','Name of Telescope' NOTES: The functions SXADDPAR() and FXADDPAR() are nearly identical, with the major difference being that FXADDPAR forces required FITS keywords BITPIX, NAXISi, EXTEND, PCOUNT, GCOUNT to appear in the required order in the header, and FXADDPAR supports the OGIP LongString convention. There is no particular reason for having two nearly identical procedures, but both are too widely used to drop either one. All HISTORY records are inserted in order at the end of the header. All COMMENT records are also inserted in order at the end of the header header, but before the HISTORY records. The BEFORE and AFTER keywords can override this. All records with no keyword (blank) are inserted in order at the end of the header, but before the COMMENT and HISTORY records. The BEFORE and AFTER keywords can override this. RESTRICTIONS: Warning -- Parameters and names are not checked against valid FITS parameter names, values and types. MODIFICATION HISTORY: DMS, RSI, July, 1983. D. Lindler Oct. 86 Added longer string value capability Converted to NEWIDL D. Lindler April 90 Added Format keyword, J. Isensee, July, 1990 Added keywords BEFORE and AFTER. K. Venkatakrishna, May '92 Pad string values to at least 8 characters W. Landsman April 94 Aug 95: added /PDU option and changed routine to update last occurence of an existing keyword (the one SXPAR reads) instead of the first occurence. Comment for string data can start after column 32 W. Landsman June 97 Make sure closing quote supplied with string value W. Landsman June 98 Converted to IDL V5.0 W. Landsman June 98 Increase precision of default formatting of double precision floating point values. C. Gehman, JPL September 1998 Mar 2000, D. Lindler, Modified to use capital E instead of lower case e for exponential formats. Apr 2000, Make user-supplied format upper-case W. Landsman Oct 2001, Treat COMMENT or blank string like HISTORY keyword W. Landsman Jan 2002, Allow BEFORE, AFTER to apply to COMMENT keywords W. Landsman June 2003, Added SAVECOMMENT keyword W. Landsman
(See ../pfidl/astro_lib/sxaddpar.pro)
NAME: SXDELPAR PURPOSE: Procedure to delete a keyword parameter(s) from a FITS header CALLING SEQUENCE: sxdelpar, h, parname INPUTS: h - FITS or STSDAS header, string array parname - string or string array of keyword name(s) to delete OUTPUTS: h - updated FITS header, If all lines are deleted from the header, then h is returned with a value of 0 EXAMPLE: Delete the astrometry keywords CDn_n from a FITS header, h IDL> sxdelpar, h, ['CD1_1','CD1_2','CD2_1','CD2_2'] NOTES: (1) No message is returned if the keyword to be deleted is not found (2) All appearances of a keyword in the header will be deleted HISTORY: version 1 D. Lindler Feb. 1987 Converted to new IDL April 1990 by D. Lindler Test for case where all keywords are deleted W. Landsman Aug 1995 Converted to IDL V5.0 W. Landsman September 1997 Allow for headers with more than 32767 lines W. Landsman Jan. 2003
(See ../pfidl/astro_lib/sxdelpar.pro)
NAME: SXPAR PURPOSE: Obtain the value of a parameter in a FITS header CALLING SEQUENCE: result = SXPAR( Hdr, Name, [ Abort, COUNT=, COMMENT =, /NoCONTINUE ]) INPUTS: Hdr = FITS header array, (e.g. as returned by READFITS) string array, each element should have a length of 80 characters Name = String name of the parameter to return. If Name is of the form 'keyword*' then an array is returned containing values of keywordN where N is an integer. The value of keywordN will be placed in RESULT(N-1). The data type of RESULT will be the type of the first valid match of keywordN found. OPTIONAL INPUTS: ABORT - string specifying that SXPAR should do a RETALL if a parameter is not found. ABORT should contain a string to be printed if the keyword parameter is not found. If not supplied, SXPAR will return quietly with COUNT = 0 (and !ERR = -1) if a keyword is not found. OPTIONAL INPUT KEYWORDS: /NOCONTINUE = If set, then continuation lines will not be read, even if present in the header /SILENT - Set this keyword to suppress warning messages about duplicate keywords in the FITS header. OPTIONAL OUTPUT KEYWORDS: COUNT - Optional keyword to return a value equal to the number of parameters found by SXPAR, integer scalar COMMENT - Array of comments associated with the returned values OUTPUTS: Function value = value of parameter in header. If parameter is double precision, floating, long or string, the result is of that type. Apostrophes are stripped from strings. If the parameter is logical, 1b is returned for T, and 0b is returned for F. If Name was of form 'keyword*' then a vector of values are returned. SIDE EFFECTS: !ERR is set to -1 if parameter not found, 0 for a scalar value returned. If a vector is returned it is set to the number of keyword matches found. The use of !ERR is deprecated, and instead the COUNT keyword is preferred If a keyword (except HISTORY or COMMENT) occurs more than once in a header, a warning is given, and the *last* occurence is used. EXAMPLES: Given a FITS header, h, return the values of all the NAXISi values into a vector. Then place the history records into a string vector. IDL> naxisi = sxpar( h ,'NAXIS*') ; Extract NAXISi value IDL> history = sxpar( h, 'HISTORY' ) ; Extract HISTORY records PROCEDURE: The first 8 chacters of each element of Hdr are searched for a match to Name. The value from the last 20 characters is returned. An error occurs if there is no parameter with the given name. If a numeric value has no decimal point it is returned as type LONG. If it contains more than 8 numerals, or contains the characters 'D' or 'E', then it is returned as type DOUBLE. Otherwise it is returned as type FLOAT. Very large integer values, outside the range of valid LONG, are returned as DOUBLE. If the value is too long for one line, it may be continued on to the the next input card, using the OGIP CONTINUE convention. For more info, http://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/ofwg_recomm/r13.html Complex numbers are recognized as two numbers separated by one or more space characters. If a numeric value has no decimal point (or E or D) it is returned as type LONG. If it contains more than 8 numerals, or contains the character 'D', then it is returned as type DOUBLE. Otherwise it is returned as type FLOAT. If an integer is too large to be stored as type LONG, then it is returned as DOUBLE. NOTES: The functions SXPAR() and FXPAR() are nearly identical, although FXPAR() has slightly more sophisticated parsing. There is no particular reason for having two nearly identical procedures, but both are too widely used to drop either one. PROCEDURES CALLED: GETTOK(), VALID_NUM() MODIFICATION HISTORY: DMS, May, 1983, STPAR Written. D. Lindler Jan 90 added ABORT input parameter J. Isensee Jul,90 added COUNT keyword W. Thompson, Feb. 1992, added support for FITS complex values. W. Thompson, May 1992, corrected problem with HISTORY/COMMENT/blank keywords, and complex value error correction. W. Landsman, November 1994, fix case where NAME is an empty string W. Landsman, March 1995, Added COMMENT keyword, ability to read values longer than 20 character W. Landsman, July 1995, Removed /NOZERO from MAKE_ARRAY call T. Beck May 1998, Return logical as type BYTE W. Landsman May 1998, Make sure integer values are within range of LONG Converted to IDL V5.0, May 1998 W. Landsman Feb 1998, Recognize CONTINUE convention W. Landsman Oct 1999, Recognize numbers such as 1E-10 as floating point W. Landsman Jan 2000, Only accept integer N values when name = keywordN W. Landsman Dec 2001, Optional /SILENT keyword to suppress warnings W. Landsman/D. Finkbeiner Mar 2002 Make sure extracted vectors of mixed data type are returned with the highest type.
(See ../pfidl/astro_lib/sxpar.pro)
NAME: TEXTCLOSE PURPOSE: Close a text outpu file previously opened with TEXTOPEN EXPLANATION: procedure to close file for text output as specifed by the (non-standard) system variable !TEXTOUT. CALLING SEQUENCE: textclose, [ TEXTOUT = ] KEYWORDS: textout - Indicates output device that was used by TEXTOPEN SIDE EFFECTS: if !textout is not equal to 5 and the textunit is opened. Then unit !textunit is closed and released HISTORY: D. Lindler Dec. 1986 (Replaces PRTOPEN) Test if TEXTOUT is a scalar string W. Landsman August 1993 Can't close unit -1 (Standard Output) I. Freedman April 1994 Converted to IDL V5.0 W. Landsman September 1997
(See ../pfidl/astro_lib/textclose.pro)
NAME: TEXTOPEN PURPOSE: Open a device specified by TEXTOUT with unit !TEXTUNIT EXPLANATION: Procedure to open file for text output. The type of output device (disk file or terminal screen) is specified by the TEXTOUT keyword or the (nonstandard) system variable !TEXTOUT. CALLING SEQUENCE: textopen, program, [ TEXTOUT =, /STDOUT, /SILENT, MORE_SET= ] INPUTS: program - scalar string giving name of program calling textopen OPTIONAL INPUT KEYWORDS: TEXTOUT - Integer scalar (0-7) specifying output file/device to be opened (see below) or scalar string giving name of output file. If TEXTOUT is not supplied, then the (non-standard) system variable !TEXTOUT is used. /SILENT - By default, TEXTOPEN prints an informational message when opening a file for hardcopy output. Set /SILENT (or !QUIET) to suppress this message. /STDOUT - if this keyword is set and non-zero, then the standard output (unit = -1) is used for TEXTOUT=1 or TEXTOUT=2. The use of STDOUT has 2 possible advantages: (1) the output will appear in a journal file (2) Many Unix machines print spurious control characters when printing to /dev/tty. These characters are eliminated by setting /STDOUT The disadvantage of /STDOUT is that the /MORE option is not available. OPTIONAL OUTPUT KEYWORD: MORE_SET - Returns 1 if the output unit was opened with /MORE. This occurs if (1) TEXTOUT = 1 and (2) the device is a tty, and (3) /STDOUT is not set. User can use the returned value of MORE_SET to determine whether to end output when user presses 'Q'. SIDE EFFECTS: The following dev/file is opened for output. Different effects occur depending whether the standard output is a GUI (Macintosh, Windows, Unix/IDLTool) or a TTY textout=0 Nowhere textout=1 if a TTY then TERMINAL using /more option otherwise standard (Unit=-1) output textout=2 if a TTY then TERMINAL without /more option otherwise standard (Unit=-1) output textout=3.prt textout=4 laser.tmp textout=5 user must open file textout=7 same as 3 but text is appended to .prt file if it already exists. textout = filename (default extension of .prt) The unit to be opened is obtained with the procedure GET_LUN unless !TEXTOUT=5. The unit number is placed in system variable !TEXTUNIT. For !TEXTOUT=5 the user must set !TEXTUNIT to the appropriate unit number. NOTES: When printing to a TTY terminal, the output will *not* appear in an IDL JOURNAL session, unlike text printed with the PRINT command. NON-STANDARD SYSTEM VARIABLES: TEXTOPEN will automatically define the following system variables if they are not previously defined: DEFSYSV,'!TEXTOUT',1 DEFSYSV,'!TEXTUNIT',0 HISTORY: D. Lindler Dec. 1986 Keyword textout added, J. Isensee, July, 1990 Made transportable, D. Neill, April, 1991 Trim input PROGRAM string W. Landsman Feb 1993 Don't modify TEXTOUT value W. Landsman Aug 1993 Modified for MacOS I. Freedman April 1994 Modified for output terminals without a TTY W. Landsman August 1995 Added /STDOUT keyword W. Landsman April 1996 added textout=7 option, D. Lindler, July, 1996 Converted to IDL V5.0 W. Landsman September 1997 Exit with RETURN instead of RETALL W. Landsman June 1999 In IDL V5.4 filepath(/TERMINAL) not allowed in the IDLDE WL August 2001 Added MORE_SET output keyword W.Landsman January 2002 Added /SILENT keyword W. Landsman June 2002 Define !TEXTOUT and !TEXTUNIT if needed. R. Sterner, 2002 Aug 27 Return Calling Sequence if no parameters supplied W.Landsman Nov 2002
(See ../pfidl/astro_lib/textopen.pro)
NAME: T_GETPSF PURPOSE: Driver procedure (for GETPSF) to generate a PSF from isolate stars. EXPLANATION: Generates a point-spread function from one or more isolated stars. List of stars is read from the FITS ASCII table output of T_APER. PSF is represented as a sum of a Gaussian plus residuals. Ouput residuals are written to a FITS image file. CALLING SEQUENCE: T_GETPSF, image, fitsfile, [ idpsf, psfrad, fitrad, psfname, /DEBUG, NEWTABLE =] INPUTS: IMAGE - image array FITSFILE - scalar string giving name of disk FITS ASCII table. Must contain the keywords 'X','Y' (from T_FIND) and 'AP1_MAG','SKY' (from T_APER). OPTIONAL INPUTS: IDPSF - vector of stellar ID indices indicating which stars are to be used to create the PSF. Not that the PSF star should be specified *not* by its STAR_ID value, but rather by the its row number (starting with 0) in the FITS table PSFRAD - the radius for which the PSF will be defined FITRAD - fitting radius, always smaller than PSFRAD PSFNAME - name of FITS image file to contain PSF residuals, scalar string GETPSF will prompt for all the above values if not supplied. OPTIONAL KEYWORD INPUT NEWTABLE - scalar string specifying the name of the output FITS ASCII table. If not supplied, then the input table is updated with the keyword PSF_CODE, specifying which stars were used for the PSF. DEBUG - if this keyword is set and non-zero, then the result of each fitting iteration will be displayed. PROMPTS: T_GETPSF will prompt for the readout noise (in data numbers), and the gain (in photons or electrons per data number) so that pixels can be weighted during the PSF fit. To avoid the prompt, add the keywords RONOIS and PHPADU to the FITS ASCII table header. PROCEDURES USED: FTADDCOL, FTGET(), FTPUT, GETPSF, READFITS(), SXADDHIST, SXADDPAR, SXPAR(), WRITEFITS, ZPARCHECK REVISION HISTORY: Written W. Landsman STX May, 1988 Update PSF_CODE to indicate PSF stars in order used, W. Landsman Mar 96 I/O to FITS ASCII disk files W. Landsman May 96 Converted to IDL V5.0 W. Landsman September 1997 Update for new FTINFO call W. Landsman May 2000
(See ../pfidl/astro_lib/t_getpsf.pro)
NAME: VALID_NUM PURPOSE: Check if a string is a valid number representation. EXPLANATION: The input string is parsed for characters that may possibly form a valid number. It is more robust than simply checking for an IDL conversion error because that allows strings such as '22.3qwert' to be returned as the valid number 22.3 See also the original NUM_CHK which returns the status in the opposite sense. CALLING SEQUENCE: IDL> status = valid_num(string [,value] [,/integer]) Inputs : string - the string to be tested Opt. Inputs : None Outputs : The function returns 1 for valid, 0 for invalid number Opt. Outputs: value - The value the string decodes to. This will be returned as a double precision number unless /INTEGER is present, in which case a long integer is returned. Keywords : Integer - if present code checks specifically for an integer. Calls : None Restrictions: None Category : Utilities, Numerical Prev. Hist. : Small changes from NUM_CHK by Andrew Bowen, Tessella Support Services, 8/3/93 Written : CDS version by C D Pike, RAL, 24-May-93 Modified : Version 1, C D Pike, RAL, 24-May-93 Version 2, William Thompson, GSFC, 14 October 1994 Added optional output parameter VALUE to allow VALID_NUM to replace STRNUMBER in FITS routines. Version : Version 1 24-May-93 Converted to IDL V5.0 W. Landsman September 1997
(See ../pfidl/astro_lib/valid_num.pro)
NAME: WRITEFITS PURPOSE: Write IDL array and header variables to a disk FITS file. EXPLANATION: A minimal FITS header is created if not supplied. WRITEFITS works for all types of FITS files except random groups CALLING SEQUENCE: WRITEFITS, filename, data [, header, /APPEND, /CHECKSUM] INPUTS: FILENAME = String containing the name of the file to be written. DATA = Image array to be written to FITS file. If DATA is undefined or a scalar, then only the FITS header (which must have NAXIS = 0) will be written to disk OPTIONAL INPUT: HEADER = String array containing the header for the FITS file. If the variable HEADER is not supplied, the program will generate a minimal FITS header. OPTIONAL INPUT KEYWORD: /APPEND - If this keyword is set then the supplied header and data array are assumed to be an extension and are appended onto the end of an existing FITS file. If the file does not exist, then WRITEFITS will create one with a minimal primary header (and /EXTEND keyword) and then append the supplied extension header and array. Note that the primary header in an existing file must already have an EXTEND keyword to indicate the presence of an FITS extension. /Checksum - If set, then the CHECKSUM keywords to monitor data integrity will be included in the FITS header. For more info, see http://heasarc.gsfc.nasa.gov/docs/heasarc/fits/checksum.html NaNvalue - Value in the data array which represents missing pixels. This keyword is only used when missing pixels are not represented by NaN values in the input array. OUTPUTS: None RESTRICTIONS: (1) It recommended that BSCALE and BZERO not be used (or set equal to 1. and 0) with REAL*4 or REAL*8 data. (2) WRITEFITS will remove any group parameters from the FITS header EXAMPLE: Write a randomn 50 x 50 array as a FITS file creating a minimal header. IDL> im = randomn(seed, 50, 50) ;Create array IDL> writefits, 'test', im ;Write to a FITS file "test" PROCEDURES USED: CHECK_FITS, FITS_ADD_CHECKSUM, MKHDR, MRD_HREAD, SXDELPAR, SXADDPAR, SXPAR() MODIFICATION HISTORY: WRITTEN, Jim Wofford, January, 29 1989 MODIFIED, Wayne Landsman, added BITPIX = -32,-64 support for UNIX Use new BYTEODER keywords 22-Feb-92 Modify OPENW for V3.0.0 W. Landsman Dec 92 Work for "windows" R. Isaacman Jan 93 More checks for null data Mar 94 Work for Linux W. Landsman Sep 95 Added call to IS_IEEE_BIG() W. Landsman Apr 96 Make sure SIMPLE is written in first line of header W. Landsman Jun 97 Use SYSTIME() instead of !STIME W. Landsman July 97 Create a default image extension header if needed W. Landsman June 98 Converted to IDL V5.0 W. Landsman June 98 Write unsigned data types W. Landsman December 1999 Correct BZERO value for unsigned data W. Landsman July 2000 Assume at least V5.1 remove NANValue keyword W. Landsman July 2001 Use FILE_SEARCH for V5.5 or later W. Landsman April 2002 Create the file if not already present and /APPEND is set W. Landsman September 2002 Fix MRD_HREAD call if /APPEND is set W. Landsman December 2002 Added /CHECKSUM keyword W. Landsman December 2002 Restored NANvalue keyword, William Thompson, October 2003
(See ../pfidl/astro_lib/writefits.pro)