.help hrirpsf Feb95 ftools.rosat
.ih
NAME
hrirpsf - calculates a theoretical radial PSF for the ROSAT HRI
.ih
USAGE
hrirpsf infile detfil outfile (chatter) bkgd bkgd_rad sumtcts pix_size
        (rad_min) (rad_max) (n_rad) off_ang (clobber)
.ih
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:
.ls 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).
.le
.ls 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. 
.le
.ls 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.
.le

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.

.ih
WARNINGS ON USAGE

  Only the OGIP-recognized format for RPSF.
Details on these formats can be found in:
.ls RPSFs:  OGIP Calibration Memo CAL/GEN/92-020
.le


.ih
PARAMETERS
.ls 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: 
.le
.ls the level of the background (can be overridden using the bkgd 
 parameter to this task)
.le
.ls the pixel size of the original image used to construct the 
 observational dataset
.le
.ls The total number of SOURCE counts required to lay under the predicted
 RPSF curve. This value is recalculated if the bkgd value is changed.
.le
.ls 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
.le
.ls 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.
.le
.ls (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.
.le
.ls 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.
.le
.ls 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.
.le
.ls 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).
.le
.ls 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.
.le
.ls (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.
.le
.ls (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.
.le
.ls (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. 
.le
.ls 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.
.le
.ls (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.
.le

.fi

.ih
EXAMPLE:
.nf
% 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
.fi

.ih
BUGS 
None known 
.ih
SEE ALSO

.ls st2rpsf (ftools/caltools) 
.le
.ls rbnrpsf (ftools/caltools)
.le
.ls rpsfqdp (ftools/caltools) 
.le
.ls calcrpsf (ftools/caltools)
.le
.ls stw2pha (ftools/caltools)
.le

.ih
PRIMARY AUTHOR
 
.nj
Rehana Yusaf
.br
.nj
HEASARC
.br
.nj
NASA/GSFC
.br
.nj
http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp
.br
.nj

.ju

.endhelp

