ST2RPSF

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