.help pcrpsf Feb95 ftools.rosat
.ih
NAME
pcrpsf - calculates a theoretical radial PSF for the ROSAT PSPC
.ih
USAGE
pcrpsf infile phafile detfil rmffile outfile bkgd bkgd_rad sumtcts pix_size
       en_min en_max off_ang
.ih
DESCRIPTION
  
  pcrpsf generates a theoretical radial (1-dimensional) point spread 
function dataset for the ROSAT PSPC, 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 
available via the OGIP anonymous ftp account on legacy.gsfc.nasa.gov 
(in Postscript) as caldb/docs/memos/cal_gen_92_020.ps.  

  A number of options are available, controlled via user-defined parameters,
with the intention of serving the needs of users interested in generating 
predicted profiles for direct comparision with observational datasets, and 
users who simply require a theoretical profile. In addition to 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 
to enable a direct comparison between the observed and theoretical 
profiles (see below).
.le
.ls The PSF of the ROSAT PSPC is a strong function of energy. Users may 
therefore enter a PHA file (via the parameter phafile) to be used to weight 
the calculated theoretical profile with the number of counts observed in 
each PHA channel over the range of:
.ls channels defined by the observational dataset entered via the 
infile parameter (if infile is entered), or
.le
.ls energies specified by the parameters en_min & en_max (if no 
observational dataset is specified, ie infile=NONE)
.le
If a PHA file is not entered, then a uniform weighting will be assumed
across the above range of channels/energies. If a PHA file is entered 
(using phafile) and/or an observational dataset is entered (using infile), 
then the EBOUNDS extension (usually found within an RMF) is required to 
perform the detector channel -> incident energy conversion and must be 
entered via the rmffile parameter.
.ls The PSF of the ROSAT PSPC is also a strong function of off-axis angle,
hence the angle is required in order to calculate the correct theoretical 
curve. A 'nodding' of the spacecraft was performed for most (if not all) 
'pointed' PSPC observations, and an off-axis histogram stored within the 
'DETECTOR' extension of PHA files conforming to OGIP standards for the 
PSPC. Such a histogram can be specified using the detfil parameter within 
pcrpsf. 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 strength 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 an observational 
dataset has been entered via the parameter infile, then the specification 
of this parameter will override the value stored within the dataset. In
addition, if an observational dataset is entered then users may ask for 
a bkgd value to be calculated.
.le

The algorithm currently in use is valid over the energy range 0.07-3.0 keV
and all off-axis angles, and was supplied by Gunther Hasinger of MPE. A 
more detailed description can be found in OGIP Calibration Memo
CAL/ROS/93-015 (Hasinger etal 1994 Legacy 4, in press).

.ih
WARNINGS ON USAGE

  Only the OGIP-recognized formats for RPSF, PHA & RMF datasets are supported.
Details on these formats can be found in:
.ls RPSFs:  OGIP Calibration Memo CAL/GEN/92-020
.le
.ls PHAs:   Arnaud etal 1992 (Legacy, 2, 65) and its appendix provided in 
OGIP Memo OGIP/92-007a.
.le
.ls RMFs:   George etal 1992 (Legacy, 2, 51) and its appendix provided in 
OGIP Calibration Memo OGIP/92-002a.
.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, then 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: 
.ls the range of channels over which the theoretical curve is to be 
 generated
.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
 If the value 'NONE' is specified, then the user will be prompted for a 
 range of energies over which the theoretical profile is to be calculated.
.le
.ls phafile [character string]
 An input filename containing a PHA histogram to be used for weighting the 
 theoretical radial profile, or 'NONE' (for uniform weighting). A specific 
 extension of a given input file containing the PHA dataset 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 a PHA dataset. In 
 such cases, if the input file is then found to consist of more than one PHA
 dataset, then the task will warn the user and stop.
.le
.ls detfil [character string]
 An input file containing an off-axis histogram to be used for weighting the 
 theoretical radial profile, or 'NONE', or "%". The default value is "%" 
 indicating that the off-axis histogram dataset will be read from an 
 extension of the PHA file. Such a histogram can be written to the file if 
 the PHA dataset is converted to an OGIP format using the task 
 ftools/caltools/stw2pha
.le
.ls rmffile [character string]
 The input filename containing EBOUNDS extension required to perform the 
 translation between detector channel and nominal incident energy.
.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 = 9) [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 infil 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 the background from the observational dataset being used.
 Obviously in cases where infill=NONE a numerical value of bkgd must be
 specified (but which can be 0.0). Also in such cases,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 PSPC an inner radius less than 2 arcmins
 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). NOTE : This value should be
 corrected for any excluded regions.
.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 PSPC. 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 en_min [real]
 The lower bound on the energy range (in keV) over which the predicted PRSF 
 dataset is to be generated. This parameter is only required (and prompted 
 for) if an observational dataset has NOT been entered via the infile 
 parameter. The current parameterization of the PSPC profile is only valid 
 over the range 0.07-3.0 keV, thus all requested energies outside this 
 range will be ignored.
.le
.ls en_max [real]
 The upper bound on the energy range (in keV) over which the predicted PRSF 
 dataset is to be generated. This parameter is only required (and prompted 
 for) if an observational dataset has NOT been entered via the infile 
 parameter. The current parameterization of the PSPC profile is only valid 
 over the range 0.07-3.0 keV, thus all requested energies outside this 
 range will be ignored.
.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 PSPC profile is only valid out to 60 arcmins from 
 the optical axis, thus angles outside this range will be ignored.
.le
.ls (binsize_min = 1) [real]
 The binning size (in arcmin).
.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


.fi
.ih
BUGS 
None known 
.ih
SEE ALSO
.br
.nj
 The ftools/caltools task st2rpsf 
.br
.nj
 The ftools/caltools task rbnrpsf 
.br
.nj
 The ftools/caltools task rpsfqdp 
.br
.nj
 The ftools/caltools task calcrpsf 
.br
.nj
 The ftools/caltools task stw2pha 
.br
.nj
 OGIP Calibration Memo CAL/ROS/92-001  (Hasinger etal 1992 Legacy 2 77)
.br
.nj
 OGIP Calibration Memo CAL/ROS/92-001a (Hasinger etal 1993 Legacy 3 46)
.br
.nj
 OGIP Calibration Memo CAL/ROS/93-015  (Hasinger etal 1993 Legacy 4 in press)
.ju

.ih
LOG OF SIGNIFICANT CHANGES

.ls v2.0.7 (1994 APRIL)
 Rename task from PSPCRPSF
.le
.ls v1.0.5 (1994 JAN)
 Additional functionality - The option of not entering an input dataset
 and only generating the theoretical PSF is given.
.le
.ls v1.0.0 (1993 JAN)
 Beta test version
.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
(301) 286-6115
.ju

.endhelp


