pcrpsf HEADAS help file

NAME

pcrpsf - calculates a theoretical radial PSF for the ROSAT PSPC

USAGE

pcrpsf infile phafile detfil rmffile outfile bkgd bkgd_rad sumtcts pix_size en_min en_max off_ang

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 heasarc.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:

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).

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:

channels defined by the observational dataset entered via the: infile parameter (if infile is entered), or
energies specified by the parameters en_min & en_max (if no: observational dataset is specified, ie infile=NONE)

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.

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.
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.

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).

WARNINGS ON USAGE

Only the OGIP-recognized formats for RPSF, PHA & RMF datasets are supported. Details on these formats can be found in:

RPSFs: OGIP Calibration Memo CAL/GEN/92-020
PHAs: Arnaud etal 1992 (Legacy, 2, 65) and its appendix provided in: OGIP Memo OGIP/92-007a.
RMFs: George etal 1992 (Legacy, 2, 51) and its appendix provided in: OGIP Calibration Memo OGIP/92-002a.

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, 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:

the range of channels over which the theoretical curve is to be: generated
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.

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.

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.

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

rmffile [character string]

The input filename containing EBOUNDS extension required to perform the translation between detector channel and nominal incident energy.

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 = 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.

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.

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.

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.

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 PSPC. The number of bins does NOT have to be the same as the number of bins in any observational dataset entered via infile.

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.

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.

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.

(binsize_min = 1) [real]

The binning size (in arcmin).

(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

LOG OF SIGNIFICANT CHANGES

v2.0.7 (1994 APRIL): Rename task from PSPCRPSF
v1.0.5 (1994 JAN): Additional functionality - The option of not entering an input dataset and only generating the theoretical PSF is given.
v1.0.0 (1993 JAN): Beta test version

PRIMARY AUTHOR

Rehana Yusaf

HEASARC

NASA/GSFC

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

(301) 286-6115