.help st2rpsf Feb95 ftools.caltools 
.ih
NAME
st2rpsf -- converts radial PSF dataset from stwfits to OGIP format 
.ih
USAGE
st2rpsf infil outfil bkgd
.ih
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. 


.ih
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: 
.ls  SOU_A   = 'ANNULUS 123. 456. 0." 600." n=30      
.le
or 
.ls  SOU_A   = 'ANNULUS 123. 456. 0.' 10.' n=30      
.le
 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:
.ls  region = "a 123 456 0" 600" n=30"
.le
or
.ls  region = "a 123 456 0' 10' n=30"
.le
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.

.ih
PARAMETERS
.ls 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. 
.le
.ls outfil [character string]
 The name of the output file to be created (in OGIP standard format).
.le
.ls 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).
.le
.ls 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).
.le
.ls 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).
.le
.ls 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).
.le
.ls 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.
.le
.ls 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.
.le
.ls 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.
.le
.ls (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.
.le

.ih
BUGS
None known 
.ih
SEE ALSO
.ls imcnts (xray/xspatial) 
.le
.ls stwfits (stsdas/fitsio) 
.le
.ls rbnrpsf (ftools/caltools) 
.le
.ls pcrpsf (ftools/rosat)
.le
.ls rpsfqdp (ftools/caltools)
.le
.ls calcrpsf (ftools/caltools)
.le

.ih
PRIMARY AUTHOR
 
.nj
Rehana Yusaf
.br
.nj
HEASARC
.br
.nj
NASA/GFSC
.br
.nj
http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp
.br
.nj
(301) 286-6115
.ju

.endhelp

