hrirpsf HEADAS help file

NAME

hrirpsf - calculates a theoretical radial PSF for the ROSAT HRI

USAGE

hrirpsf infile detfil outfile (chatter) bkgd bkgd_rad sumtcts pix_size (rad_min) (rad_max) (n_rad) off_ang (clobber)

DESCRIPTION

hrirpsf generates a theoretical radial (1-dimensional) point spread function dataset for the ROSAT HRI, and writes the results to an output FITS file (in OGIP-standard format for RPSFs). Details of the o/p file formats supported can be found in the OGIP Calibration Memo CAL/GEN/92-020; see http://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/summary/cal_gen_92_020_summary.html

A number of options are available, controlled via user-defined parameters, such that the task hopefully serves the needs of users interested in generating predicted profiles for direct comparison with observations, and users who simply require a theoretical profile. Besides being able to specify the inner & outer radii, and number of steps used to calculate the theoretical RPSF, the following functionality is also available:

Users may define an input FITS file (via the parameter infile) containing: an observed radial profile dataset (in OGIP-standard format). If such a dataset is entered then a number of variables required for the construction of the theoretical RPSF dataset are (or can be) read from this FITS extension such as to enable a direct comparison between the observed and theoretical profiles (see below).
The PSF of the ROSAT HRI is a function of off-axis angle, hence the off-axis: angle is required in order to calculate the correct theoretical curve. A 'wobble' of the spacecraft was performed for most 'pointed' HRI observations, and an off-axis histogram is stored within the 'DETECTOR' extension of PHA files conforming to OGIP standards for the HRI. Such a histogram can be specified using the detfil parameter within hrirpsf. If such a histogram is not available/required, an off-axis angle can be specified directly via the parameter off_ang.
Users may specify the intensity of the background (via the parameter: bkgd; in units of counts per pixel) which will be scaled and added appropriately to the theoretical profile generated. If a dataset has been entered via the parameter infile, then the specification of the bkgd parameter will override the value stored within the dataset. In addition, if a dataset is entered as INFILE then users may ask for a bkgd value to be calculated.

The algorithm in use was supplied by Larry David (CfA) in 1993 Nov. THIS IS ONLY A CRUDE ESTIMATE of the actual radial point spread function. Variations in the quality of the aspect solution will affect the derived PSF for real data. It is therefore advised that the use of this model be limited to performing relatively crude tests as to whether a source is extended and/or performing corrections to count rates derived from extraction cells smaller than the PSF. It is NOT recommended that this model be used for detailed deconvolution of extended sources.

WARNINGS ON USAGE

Only the OGIP-recognized format for RPSF. Details on these formats can be found in:

RPSFs: OGIP Calibration Memo CAL/GEN/92-020

PARAMETERS

infile [character string]: An input filename (in OGIP-standard format) containing a 1-dimensional radial profile of a source, or 'NONE'. If a filename is to be entered, then a specific extension of the input file containing the observational dataset to be operated on can be specified by including the integer extension number in square ("["extn#"]") brackets after the filename. If such a specification is not used, then the entire file will be searched for extensions likely to contain an RPSF dataset. In such cases, if the input file is then found to consist of more than one acceptable dataset, the task will warn the user and stop. If a single acceptable extension is found, then by default the following information required to generate the theoretical profile will be read from it:
the level of the background (can be overridden using the bkgd: parameter to this task)
the pixel size of the original image used to construct the: observational dataset
The total number of SOURCE counts required to lay under the predicted: RPSF curve. This value is recalculated if the bkgd value is changed.
detfil [character string]: An input file containing an off-axis histogram to be used for weighting the theoretical radial profile, or 'NONE'.Such a histogram can be written to a file if the PHA dataset is converted to an OGIP format using the task ftools/caltools/stw2pha
outfile [character string]: The name of the output file to be created (in OGIP standard format) containing an extension with the predicted radial profile model. If an observational dataset is entered (via the infile parameter), then this dataset will be copied into a seperate extension of the output file.
(chatter) [integer (hidden)]: The value of the chatter flag, useful for reassurance & diagostics purposes. The default value is chatter=9, with chatter <= 5 being very quite and chatter >= 20 very verbose.
bkgd [character string (real value parsed)]: Background level, in counts per pixel (assumed to be uniform over the extent of the profile),which will be scaled and added appropriately to the theoretical profile generated. In cases where an observational dataset has been specified (via the infile parameter), the bkgd parameter enables users to 'override' the background level stored in this file;by entering a new background value or by using the special value "CALC" which results in a background value being calculated. NOTE: If a new bkgd value is used then the sum of the counts used to lay under the predicted RPSF is recalculated. If this is not desired, then the special (default) value of "%" will result in using the background from the dataset specified by INFILE. In cases where INFILE=NONE, a numerical value of bkgd must be specified (but this value can be 0.0). If INFILE=NONE, the user must specify the angular size of a pixel (via the pixsize parameter), and the total number of source counts (via the sumtcts parameter) to which the RPSF is to be normalised.
bkgd_rad [real]: Only prompted for if bkgd="CALC". This is the inner radius for background calculation. NOTE: For ROSAT HRI data an inner radius less than 1/2 arcmin is not recommended as the background estimate could be contaminated by the PSF.
sumtcts [real]: The total number of SOURCE counts required to lay under the predicted RPSF curve (when this curve is integrated out to infinite radius, and over all azimuthal angles). This parameter is only required when no observational dataset is entered (ie when INFILE=NONE).
pix_size [real]: The angular size of the side of each square pixel (in arcmins). This parameter is only required when infile=NONE and the value of the background parameter is not equal to zero.
(rad_min) [integer (hidden)]: Inner radius for the predicted model RPSF dataset in arcmin. The default value is 0.0 and appropriate for most applications.
(rad_max) [integer (hidden)]: Outer radius for the predicted model RPSF dataset in arcmin. The default value is 10.0 and appropriate for most applications.
(n_rad) [integer (hidden)]: The number of radial bins to be used in generating the RPSF dataset. The default value is 300. For most applications it is suggested that this be a large number (at least 100) in order to obtain sufficient resolution to see the structure of the theoretical RPSF of the HRI. The number of bins does NOT have to be the same as the number of bins in any observational dataset entered via infile.
off_ang [real]: The off-axis angle (in arcmin) for which the predicted PRSF dataset is to be generated. This parameter is only required (and prompted for) if an off-axis dataset has NOT been entered via the detfil parameter. The current parameterization of the HRI profile is only valid out to approximately 28 arcmins from the optical axis, thus angles outside this range will be ignored.
(clobber) [boolean (hidden)]: 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. Default value is no.

EXAMPLE:




% hrirpsf
Please enter Radial Profile File[] NONE
Please enter Off Axis histogram filename[] NONE
Please enter Output filename[] hrirpsf.out
Please enter background count rate (ct/pixel or calc)[%] 0.0
Enter Sum of source counts under curve[] 1000
Please enter off_axis angle (arcmin)[] 0.2
 ** HRIRPSF 2.1.1
 ** HRIRPSF 2.1.1 completed successfully

BUGS

None known

PRIMARY AUTHOR

Rehana Yusaf

HEASARC

NASA/GSFC

http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp