.help calcrpsf Jan94 ftools.caltools
.ih
NAME
calcrpsf -- multi-task wrapper for Radial PSF tools
.ih
USAGE
calcrpsf 
.ih
DESCRIPTION

  This task is a multi-task 'wrapper' (essentially a FORTRAN script) to
run several ftools associated with Radial (1-dimensional) Point Spread 
Functions (RPSFs). In the current build, the following tasks are supported:
.ls st2rpsf
 Reads i/p data from a FITS file produced by stwfits (within the  
 stsdas/fitsio sub-package) assumed to contain a 1-dimensional radial profile 
 of a image, and writes an o/p RPSF dataset in OGIP-standard format.
.le
.ls rbnrpsf
 Rebins an RPSF dataset such that a user-defined number of 'source' counts 
 are contained within each bin, and writes a new file containing the results.
.le
.ls one of the following tasks to generate a theoretical RPSF dataset:
.ls pcrpsf
 for the ROSAT PSPC (with a number of user-defined options available).
.le
.ls hrirpsf
 for the ROSAT HRI 
.le
.le
.ls rpsfqdp
 Reads an observed RPSF dataset and writes the data to an ASCII file along 
 with QDP commands to enable QDP/PLT to be used directly on the o/p file.
 In additional, a theoretical/predicted RPSF dataset can be read and 
 written such that QDP/PLT will overlay it on the same curve.
.le 

 One, some or all of these tasks can be spawned automatically from within 
calcrpsf, as dictated by the input parameters (see below).
More detailed help on the individual tasks can of course by obtained by 
using the command "fhelp {task}".

  As Users Guide for this task (CAL/SW/93-011), which contains a more
detailed description of the task, protential problems, as well as examples
is available via the OGIP anonymous ftp acoount on legacy.gsfc.nasa.gov (in
Postscript) as caldb/docs /memos/cal_sw_93_011.ps. 


.ih
SUPPORTED FITS FILE FORMATS

   With the exception of the format conversion tasks st2rpsf & rpsfqdp, all
tasks read & write FITS files which adhere to the format given in OGIP
Calibration memo CAL/GEN/92-020. This document is available via the OGIP
anonymous ftp acoount on legacy.gsfc.nasa.gov (in Postscript) as caldb/docs
/memos/cal_gen_92_020.ps.


.ih
WARNINGS ON USAGE

The following temporary files can be generated in the local directory by 
calcrpsf during its execution. Which files are actually created by a given 
calcrpsf run obviously depends on which combination of tasksare spawned:
.ls (A) st2rpsf.tmp (by st2rpsf)
.le
.ls (B) rbnrpsf.tmp (by rbnrpsf)
.le
.ls (C) rpsfpred.tmp (by any of the RPSF generators)
.le

All these files should be automatically removed on successful execution. 
However under certain circumstances (eg if calcrpsf crashes) this might not 
be the case, and the files can/should be removed manually.

  Since this task spawns other ftools, it is crucial that users have their 
account properly set up. Specifically, users must have the path to their 
local copy of the ftools executables, and the environment variables 
pointing to the local system & user copies of the parameter files 
defined within the set-up files executed by such spawned jobs. For example,
users running the c-shell on unix/ultrix platforms must have the above 
defined within their .cshrc file (NOT their .login file).  Users who use 
the ftools initialization procedures recommended by a given ftools release
should experience no difficulties. Those that do not are on their own.
 
.ih
PARAMETERS

.ls infil [character string]
The name of the input file. The file required obviously depends upon which
tasks are to be spawned as detailed below. Users who simply want to generate 
a theoretical RPSF dataset for a given mission should specify infil=NONE. 
.le
.ls outfil [character string]
The name of the output file. The task which produces the output file 
obviously depends upon which is the last task to be spawned (as detailed 
below).
.le
.ls qst2rpsf [boolean]
Logical flag indicating whether the task st2rpsf is to be spawned. 
If yes, then the value of the infil parameter above should be the name of 
the FITS file produced by stwfits. If no other tasks are to be spawned from 
within calcrpsf, then the value of the outfil parameter should be the name 
of the desired o/p file. (If other tasks are spawned, then intermediate 
files will be produced & removed whilst calcrpsf is executing). This 
parameter is not required if infil=NONE.
.le
.ls qrbnrpsf [boolean]
Logical flag indicating whether the task rbnrpsf is to be spawned. 
If yes, but st2rpsf has NOT been run, then the value of the infil parameter 
above should be the name of the FITS file (in OGIP-standard format) to be 
rebinned. If no other tasks are to be spawned after rbnrpsf from within 
calcrpsf, then the value of the outfil parameter should be the name of the 
desired o/p file. (If other tasks are spawned, then intermediate files 
will be produced & removed whilst calcrpsf is executing). This parameter is 
not required if infil=NONE.
.le
.ls qpred [character string (pseudo-boolean)]
This string indicates whether one of the available tasks to generate a 
theoretical RPSF dataset is to be spawned. Its allowed values are the 
same as for a boolean (eg 'yes', 'no', 'true', 'false' etc etc), but 
with the addition that the special value '?' will list the instruments 
for which such a theoretical RPSF generator is available.
If a theoretical RPSF dataset is requested, but NEITHER st2rpsf OR rbnrpsf
have been run, then the value of  the infil parameter above should be
the name of the FITS file to which the  theoretical RPSF dataset is to be
appended. If infil=NONE, then the  theoretical RPSF dataset will be written
to a new FITS file. If rpsfqdp is  NOT to be spawned afterwards from within
calcrpsf, then the value of the  outfil parameter should be the name of the
desired o/p file. (If rpsfqdp is  spawned, then an intermediate file will
be produced & removed whilst  calcrpsf is executing). 
.le
.ls telescop  [character string]
The name of the mission on which the instrument for which the theoretical 
RPSF dataset is required. This parameter is only required by calcrpsf 
if infil=NONE, and qpred=yes.
.le
.ls instrume [character string]
The name of the instrume for which the theoretical 
RPSF dataset is required. This parameter is only required by calcrpsf 
if infil=NONE, and qpred=yes.
.le
.ls qrpsfqdp [boolean]
Logical flag indicating whether the task rpsfqdp is to be spawned. 
If yes, but NONE of the other tasks are to be run, then the value of the 
infil parameter above should be the name of the FITS file (in OGIP-standard 
format) to be converted to an ASCII QDP file. The value of the outfil 
parameter should be the name of the desired o/p file. 
.le
.ls (chatter = 9) [integer]
Integer flag to indicate how chatty the task is at execution. A value of 9 
is the default, with lower/higher values producing quieter/verbose output 
respectively.
.le
.ls (schatter = 5) [integer]
Integer flag to indicate how chatty the spawned tasks will be during their 
execution. A value of 5 is the default, with lower/higher values producing 
quieter/verbose output respectively.
.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

.ih
BUGS
None known 

.ih
SEE ALSO
.br
.nj
CAL/SW/93-011 (CALCRPSF Users Guide)
.br
.nj
CAL/GEN/92-020 (RPSF File format definitions)
.ju

.ih
LOG OF SIGNIFICANT CHANGES

.ls v1.2.0 (1994 Feb)
    Public release version
.le
.ls v1.0.0 (1994 Jan)
    Beta-test version
.le

.ih
PRIMARY AUTHOR

.nj
Ian M George
.br
.nj
HEASARC
.br
.nj
NASA/GFSC
.br
.nj
ftoolshelp@athena.gsfc.nasa.gov
.br
.nj
(301) 286-6094
.ju




.endhelp
