Source Files

Release Notes

ST2RPSF (Feb95)              ftools.caltools             ST2RPSF (Feb95)



NAME
    st2rpsf -- converts radial PSF dataset from stwfits to OGIP format
    
    
USAGE
    st2rpsf infil outfil bkgd
    
    
DESCRIPTION
    
      st2rpsf  reads i/p data from a FITS file produced by the IRAF task
    stwfits (within the stsdas/fitsio sub-package) assumed to contain  a
    1-dimensional  radial  profile  of  a  image, and writes an o/p FITS
    data file in OGIP standard format for radial profiles. The  data  is
    written  in the form of a BINTABLE in the first extension of the o/p
    file (with EXTNAME = OBS RPSF).
    
    Notes on which which IRAF tasks should be used to generate a  radial
    profile  dataset  prior  to  export  via  stwfits  (with  particular 
    emphasis  on  ROSAT  data)  are  given  in  OGIP  Calibration   Memo 
    CAL/ROS/93-014  available  via  the  OGIP  anonymous  ftp account on
    legacy.gsfc.nasa.gov as caldb/docs/memos/cal_gen_93_004.ps.  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        as       
    caldb/docs/memos/cal_gen_92_020.ps.
    
    
    
    
WARNINGS ON USAGE
    
      The task was designed with the analysis of X-ray  radial  profiles
    in   mind,  though  it  may  be  applicable  to  datasets  in  other 
    wavebands. It is anticipated that most users of  st2rpsf  will  have
    created  the  FITS i/p file with stwfits after having run the imcnts
    task  (within  the  xray/xspatial  sub-package)  to  construct   the 
    initial  radial  profile  dataset.  Thus the anticipated sequence of
    events is that the dataset is first written to an STSDAS table  file
    by  imcnts,  the  STSDAS  table  is  converted  to a  FITS format by
    stwfits, then converted  to  an  OGIP  standard  format  for  radial
    profiles by st2rpsf.
    
    However,  it  should  be  noted  that  the FITS extension created by
    stwfits containing  the  dataset  MUST  contain  an  annular  source
    region  descriptor  expressed  in  either  arcseconds or arcminutes.
    More specifically, an extension containing (say)  a  30  bin  radial
    profile  between  0  &  10  arcminutes  from a source at coordinates
    (123,456) requires the presence  of  the  FITS  keyword  SOU_A,  the
    value of which must adhere to either of the following formats:
    
    SOU_A   = 'ANNULUS 123. 456. 0." 600." n=30      
    or
    
    SOU_A   = 'ANNULUS 123. 456. 0.' 10.' n=30      
     This  enables  physical  units to be assigned to the radial bins as
    required by OGIP standards. Note that the coordinates of the  source
    are  not  used  by  st2rpsf  and  hence  can  be  expressed  in  any 
    coordinate scheme (eg image pixels, RA & dec etc).
    
    The above mandatory information required  within  the  i/p  file  to
    st2rpsf  can  be obtained in a straightforward way by specifying the
    source region descriptor (parameter) for imcnts  with  the  inner  &
    outer  radii  specified  in either arcseconds or arcminutes. Thus in
    the above examples, the region parameter to imcnts should be in  the
    form:
    
    region = "a 123 456 0" 600" n=30"
    or
    
    region = "a 123 456 0' 10' n=30"
    where  the  coordinates (123,456) are in either image pixels or RA &
    dec.
    
    Given these inputs, the default values for  the  stwfits  parameters
    can be used.
    
    
    
PARAMETERS
    
    infil [character string]
         The   input  filename  (produced  by  stwfits)  containing  the 
        1-dimensional  radial profile of a source. By default  the  task
        will   assume   the  dataset   is  contained  within  the  first 
        extension on the i/p file. This will  always be the case  unless
        the  o/p  file  from stwfits has been operated on  by other FITS
        manipulation tools (for  example  if  the  extension  containing
         the  radial profile has been appended to another FITS file). In
        such cases  the specific extension of the input file  containing
        the  radial profile  dataset to be converted can be specified by
        including the integer extension  number in square  ("["extn#"]")
        brackets after the filename.
    
    outfil [character string]
         The  name  of  the  output file to be created (in OGIP standard
        format).
    
    telescope [character string]
         The OGIP-standard string for the mission/satellite  from  which
        the  data  was  collected. (This parameter must unfortunately be
        entered since the  o/p  from   stwfits  does  not  contain  this
        information,  but  the OGIP-standard for RPSF  datasets requires
        the information be present within the o/p FITS file).
    
    instrume [character string]
         The  OGIP-standard  string  for  the  instrument/detector  from 
        which   the   data   was    collected.   (This   parameter  must 
        unfortunately be entered since the o/p from   stwfits  does  not
        contain   this  information,  but  the  OGIP-standard  for  RPSF 
         datasets requires the information be  present  within  the  o/p
        FITS file).
    
    chanmin [integer]
         This  parameter  is  currently only required for the ROSAT PSPC
        and gives  the lowest  PHA/PI  channel  used  to  construct  the
        radial  profile.  (This  parameter must unfortunately be entered
        since the o/p from stwfits does not  contain  this  information,
        but   the   OGIP-standard   for   RPSF  datasets  requires   the 
        information be present within the o/p FITS file in  cases  where
        the  RPSF is a function of energy).
    
    chanmax [integer]
         This  parameter  is  currently only required for the ROSAT PSPC
        and gives  the highest PHA/PI  channel  used  to  construct  the
        radial  profile.  (This  parameter must unfortunately be entered
        since the o/p from stwfits does not  contain  this  information,
        but   the   OGIP-standard   for   RPSF  datasets  requires   the 
        information be present within the o/p FITS file in  cases  where
        the  RPSF is a function of energy).
    
    bkgd [character string (real value parsed)]
         The  background  count  rate  in  units  of  ct/pixel (over the
        channel  range   chanmin-chanmax)  associated  with  the  radial 
        profile.   This  information  is   required  to  be  present  in 
        OGIP-standard RPSF datasets, but can be zero.
        
         If the special value "CALC" is  used  then  the  background  is
        calculated   using a user defined inner radius (bkgd_rad), it is
        assumed that from  this inner radius to the outer  radius  there
        is  background  contamination.    NOTE  : The theoretical sum of
        counts  ,sumtcts  (corrected  for  any  excluded   regions)   is 
        calculated using the background :
        
                 sumtcts = sumcts - (bkgd * sumpix)
        
         where  sumcts  is  the  actual sum of counts, and sumpix is the
        sum of the  pixels, calculated  using  the  area  of  a  circle.
        sumtcts  is later used to  normalise the theoretical PSF. If the
        background is too large then sumtcts  can be negative,  that  is
        the  background is dominating the source, if a  background value
        has been entered then try a smaller value.  If  the   user  asks
        the  program  to calculate an appropriate background value, then
         in cases where the source is weak or there  are  many  excluded
        regions,  the   background is calculated using the above formula
        such that sumtcts is set  to 1.
    
    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. For ROSAT HRI data
        an inner radius less than 1/2 arcmin is  not recommended.
    
    chatter [character string]
         The value  of  the  chatter  flag,  useful  for  reassurance  &
        diagostics   purposes.  The  default  value  is chatter=10, with
        chatter <= 5 being very  quite and chatter >= 20 very verbose.
    
    (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
    
    
SEE ALSO
    
    imcnts (xray/xspatial) 
    
    stwfits (stsdas/fitsio) 
    
    rbnrpsf (ftools/caltools) 
    
    pcrpsf (ftools/rosat)
    
    rpsfqdp (ftools/caltools)
    
    calcrpsf (ftools/caltools)
    
    
    
PRIMARY AUTHOR
    
    Rehana Yusaf
    HEASARC
    NASA/GFSC
    http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp
    (301) 286-6115