ST2RPSF (Feb95) ftools.caltools ST2RPSF (Feb95) NAME st2rpsf -- converts radial PSF dataset from stwfits to OGIP format USAGE st2rpsf infil outfil bkgd DESCRIPTION st2rpsf reads i/p data from a FITS file produced by the IRAF task stwfits (within the stsdas/fitsio sub-package) assumed to contain a 1-dimensional radial profile of a image, and writes an o/p FITS data file in OGIP standard format for radial profiles. The data is written in the form of a BINTABLE in the first extension of the o/p file (with EXTNAME = OBS RPSF). Notes on which which IRAF tasks should be used to generate a radial profile dataset prior to export via stwfits (with particular emphasis on ROSAT data) are given in OGIP Calibration Memo CAL/ROS/93-014 available via the OGIP anonymous ftp account on legacy.gsfc.nasa.gov as caldb/docs/memos/cal_gen_93_004.ps. Details of the o/p file formats supported can be found in the OGIP Calibration Memo CAL/GEN/92-020 available via the OGIP anonymous ftp account on legacy.gsfc.nasa.gov as caldb/docs/memos/cal_gen_92_020.ps. WARNINGS ON USAGE The task was designed with the analysis of X-ray radial profiles in mind, though it may be applicable to datasets in other wavebands. It is anticipated that most users of st2rpsf will have created the FITS i/p file with stwfits after having run the imcnts task (within the xray/xspatial sub-package) to construct the initial radial profile dataset. Thus the anticipated sequence of events is that the dataset is first written to an STSDAS table file by imcnts, the STSDAS table is converted to a FITS format by stwfits, then converted to an OGIP standard format for radial profiles by st2rpsf. However, it should be noted that the FITS extension created by stwfits containing the dataset MUST contain an annular source region descriptor expressed in either arcseconds or arcminutes. More specifically, an extension containing (say) a 30 bin radial profile between 0 & 10 arcminutes from a source at coordinates (123,456) requires the presence of the FITS keyword SOU_A, the value of which must adhere to either of the following formats: SOU_A = 'ANNULUS 123. 456. 0." 600." n=30 or SOU_A = 'ANNULUS 123. 456. 0.' 10.' n=30 This enables physical units to be assigned to the radial bins as required by OGIP standards. Note that the coordinates of the source are not used by st2rpsf and hence can be expressed in any coordinate scheme (eg image pixels, RA & dec etc). The above mandatory information required within the i/p file to st2rpsf can be obtained in a straightforward way by specifying the source region descriptor (parameter) for imcnts with the inner & outer radii specified in either arcseconds or arcminutes. Thus in the above examples, the region parameter to imcnts should be in the form: region = "a 123 456 0" 600" n=30" or region = "a 123 456 0' 10' n=30" where the coordinates (123,456) are in either image pixels or RA & dec. Given these inputs, the default values for the stwfits parameters can be used. PARAMETERS infil [character string] The input filename (produced by stwfits) containing the 1-dimensional radial profile of a source. By default the task will assume the dataset is contained within the first extension on the i/p file. This will always be the case unless the o/p file from stwfits has been operated on by other FITS manipulation tools (for example if the extension containing the radial profile has been appended to another FITS file). In such cases the specific extension of the input file containing the radial profile dataset to be converted can be specified by including the integer extension number in square ("["extn#"]") brackets after the filename. outfil [character string] The name of the output file to be created (in OGIP standard format). telescope [character string] The OGIP-standard string for the mission/satellite from which the data was collected. (This parameter must unfortunately be entered since the o/p from stwfits does not contain this information, but the OGIP-standard for RPSF datasets requires the information be present within the o/p FITS file). instrume [character string] The OGIP-standard string for the instrument/detector from which the data was collected. (This parameter must unfortunately be entered since the o/p from stwfits does not contain this information, but the OGIP-standard for RPSF datasets requires the information be present within the o/p FITS file). chanmin [integer] This parameter is currently only required for the ROSAT PSPC and gives the lowest PHA/PI channel used to construct the radial profile. (This parameter must unfortunately be entered since the o/p from stwfits does not contain this information, but the OGIP-standard for RPSF datasets requires the information be present within the o/p FITS file in cases where the RPSF is a function of energy). chanmax [integer] This parameter is currently only required for the ROSAT PSPC and gives the highest PHA/PI channel used to construct the radial profile. (This parameter must unfortunately be entered since the o/p from stwfits does not contain this information, but the OGIP-standard for RPSF datasets requires the information be present within the o/p FITS file in cases where the RPSF is a function of energy). bkgd [character string (real value parsed)] The background count rate in units of ct/pixel (over the channel range chanmin-chanmax) associated with the radial profile. This information is required to be present in OGIP-standard RPSF datasets, but can be zero. If the special value "CALC" is used then the background is calculated using a user defined inner radius (bkgd_rad), it is assumed that from this inner radius to the outer radius there is background contamination. NOTE : The theoretical sum of counts ,sumtcts (corrected for any excluded regions) is calculated using the background : sumtcts = sumcts - (bkgd * sumpix) where sumcts is the actual sum of counts, and sumpix is the sum of the pixels, calculated using the area of a circle. sumtcts is later used to normalise the theoretical PSF. If the background is too large then sumtcts can be negative, that is the background is dominating the source, if a background value has been entered then try a smaller value. If the user asks the program to calculate an appropriate background value, then in cases where the source is weak or there are many excluded regions, the background is calculated using the above formula such that sumtcts is set to 1. bkgd_rad [real] Only prompted for if bkgd="CALC". This is the inner radius for background calculation. NOTE: For Rosat PSPC an inner radius less than 2 arcmins is not recommended as the background estimate could be contaminated by the PSF. For ROSAT HRI data an inner radius less than 1/2 arcmin is not recommended. chatter [character string] The value of the chatter flag, useful for reassurance & diagostics purposes. The default value is chatter=10, with chatter <= 5 being very quite and chatter >= 20 very verbose. (clobber = false) [boolean] Flag specifying whether or not a pre-existing file with the same name as that requested as the output file from this task will be overwritten. BUGS None known SEE ALSO imcnts (xray/xspatial) stwfits (stsdas/fitsio) rbnrpsf (ftools/caltools) pcrpsf (ftools/rosat) rpsfqdp (ftools/caltools) calcrpsf (ftools/caltools) PRIMARY AUTHOR Rehana Yusaf HEASARC NASA/GFSC http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp (301) 286-6115