GRPPHA (July94)              ftools.heasarc              GRPPHA (July94)

NAME
    grppha -- Manipulates OGIP standard PHA FITS file
    
    
USAGE
    grppha infile outfile
    
    
DESCRIPTION
    
       GRPPHA is an  interactive  command  driven  task  to  define  (or
    redefine)  and/or  display  the  grouping (binning) & quality flags,
    and the fractional systematic errors associated with channels  in  a
    FITS  PHA file. A new FITS PHA file can be written at any time which
    includes the latest settings of the above, along with a copy of  any
    other  extensions  in  the  original file.  The various commands and
    their syntax are described in the command summary below.
    
       It should be noted that none of  the  commands  available  within
    this  task  change  the  actual  PHA dataset itself (ie the observed
    counts vs channel histogram)  in  any  way.  Instead  the  necessary
    grouping,  quality  &  systematic error information for each channel
    is written alongside the PHA dataset to be picked up  by  subsequent
    GRPPHA commands and downstream software (eg XSPEC).
    
       On  entry, the task displays the values of the keywords mandatory
    for FITS PHA extension conforming to an OGIP  standard  format.  The
    user  is  then  repeatedly prompted for commands until they exit (or
    quit) the task.
    
       This grppha help file is based on the OGIP Calibration Memo 
    CAL/SW/93-010 available on line at 

    http://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/
    cal_sw_93_010/cal_sw_93_010.html

    and in the OGIP anonymous FTP account on
               legacy.gsfc.nasa.gov (Internet: 128.183.8.233)
    as caldb/docs/memos/cal_sw_93_010.tex.
    
    
    
COMMAND SUMMARY
    
    There are 7 "families" of command strings currently implemented:
    
    1) group       - to group (or rebin) channels
    2) bad         - to set channels to bad quality (ignored by XSPEC
    etc)
    3) good        - to (re)set channels to good quality
    4) systematics - to set the fractional systematic error of the data
    5) show        - to display the current settings to the terminal
    6) reset       - to remove any current settings
    7) chkey       - to change keyword value
    
    The following commands are also available:
    8) write       - to write a new PHA file with the current settings
    9) exit        - to exit the task (writing a new file)
    10)quit        - to quit the task
    11)help        - interactive help
    
    Several commands can be  specified on the command line by separating
    them with an ampersand '&'
    
    The  various capabilities, limitations & syntax of each of the above
    are as follows:
    
    1) GROUP (or group)
         Sets the grouping flags  such  that  the  PHA  dataset  can  be
         rebinned.  It  is  stressed  that  the  group  command does NOT
         change the observed counts vs PHA channel dataset in  any  way.
         Rather  this command fills the GROUPING column with appropriate
         flags to delineate which channels start each new  'bin'  (value
         = +1), and which are part of a continuing 'bin' (-1).
         
         There are 3 methods by which the grouping can be set:
         
         GRPPHA> GROUP MINCHAN MAXCHAN NCHAN
              The  data  is  grouped from MINCHAN to MAXCHAN (inclusive)
              with NCHAN bins in each group. Any 'spare'  channels  will
              be  left  ungrouped  and  the  user informed. Any grouping
              requested  which  partially  overlaps  a  a   pre-existing 
              grouping  will  also  be ignored and the user informed.  A
              maximum of 6 sets of groupings is allowed on  the  command
              line.
              
                 eg: group 10 20 2 21 30 10
                 will  set  the  grouping flag such that from channel 10
                 to channel 19 the data can be binned up by a factor  2,
                 channel  20  is "spare" and left unbinned, and channels
                 21 to 30 can form a single bin.
                 
         GRPPHA> GROUP GRP_FILE.DAT
              The grouping information is read  (free-format)  from  the
              data  file  "GRP_FILE.DAT".  This  file is in ASCII format
              and can consist of up to 100  lines  (sets  of  groupings,
              one  per  line)  with  the  syntax  MINCHAN MAXCHAN NCHAN,
              where these have the same meanings as  above.   The  rules
              regarding spare and overlapping groupings are as above
              
         GRPPHA> GROUP MIN RCNTS
              The  grouping  is set such that each new grouping contains
              a minimum of RCNTS counts in each bin. Channels  that  are
              defined  as  BAD  are  not included. Any spare channels at
              the  end  of  the  data  are  defined  BAD   by   software 
              (QUALITY=2).
    
    2) BAD (or bad)
         Sets  the quality flags such that the specified channels can be
         ignored by certain  subsequent  commands  (such  as  GROUP  MIN
         RCNTS  above)  and  downstream software (eg XSPEC). The quality
         flags of unspecified channels are unchanged.
         
         There are 2 methods whereby channels can be set bad:
         
         GRPPHA> BAD MINCHAN-MAXCHAN
              Channels between MINCHAN and MAXCHAN (inclusive)  are  set
              bad  (Quality  =  5).  Note the hyphen: should this not be
              present, the task will set MINCHAN and MAXCHAN  (only)  to
              bad,  leaving  all channels in between with their previous
              quality flags.  A  maximum  of  6  sets  of  channels  are
              allowed on the command line.
              
                 eg: bad 1 5-20 29 100
                 will  set  the  quality  flag  such  that channels 1, 5
                 through 20, 29 and 100 are defined to be bad.
         
         GRPPHA> BAD BADFILE.DAT
              The quality information is  read  (free-format)  from  the
              data  file "BADFILE.DAT". This file is in ASCII format and
              can consist of up to 100 lines (sets  of  channel  ranges,
              one  per line) with the syntax MINCHAN MAXCHAN where these
              have  the  same  meanings  as  above.   NOTE:  Unlike  the 
              command  line, hyphens are illegal syntax in the file, and
              single channels which are to be set bad must be  specified
              setting MAXCHAN to MINCHAN explicitly.
              
    3) GOOD (or good)
         Sets  the  quality  flags  such that the specified channels are
         considered  good  (Quality  =  0).   The   quality   flags   of 
         unspecified channels are unchanged.
         
         There are 2 methods whereby channels can be set good:
         
         GRPPHA> GOOD MINCHAN-MAXCHAN
              Channels  between  MINCHAN and MAXCHAN (inclusive) are set
              good should they not be so already. As in the case of  the
              BAD  command, note the use of the hyphen - should this not
              be present, the task will set MINCHAN and  MAXCHAN  (only)
              to  good,  leaving  all  channels  in  between  with their
              previous quality flags.  A maximum of 6 sets  of  channels
              are allowed on the command line.
              
                 eg: good 2 6-18 99
                 will  set  the  quality  flag  such  that channels 2, 6
                 through 18 and 99 are defined to be good.
                 
         GRPPHA> GOOD GOODFILE.DAT
              The quality information is  read  (free-format)  from  the
              data  file  "GOODFILE.DAT".  This  file is in ASCII format
              and can consist of  up  to  100  lines  (sets  of  channel
              ranges,  one  per  line)  with  the syntax MINCHAN MAXCHAN
              where these  have  the  same  meanings  as  above.   NOTE:
              Unlike  the  command  line,  hyphens are illegal syntax in
              the file, and single channels which are  to  be  set  good
              must be specified setting MAXCHAN to MINCHAN explicitly.
              
    4) SYSTEMATICS (or systematics)
         Sets  the  fractional  systematic  error  for  each PHA channel
         which should be combined  with  the  corresponding  statistical
         error  on  the  data  to  define  the true (total) error on the
         data. It is stressed  that  this  command  obviously  does  NOT
         change  the  observed  (statistical)  error associated with the
         PHA data. Rather SYS_ERR column is filled with the  appropriate
         values,  and  the  command is therefore reversible. There are 2
         methods whereby the systematic errors can be set:
         
         GRPPHA> SYSTEMATICS MINCHAN-MAXCHAN ERR
              Channels between  MINCHAN  and  MAXCHAN  (inclusive)  will
              have  a  fractional systematic error of ERR defined (ERR =
              0.03 corresponds to  a  systematic  error  of  3%  of  the
              observed  PHA  count rate for that channel).  A maximum of
              6 errors are permitted on the command line.
              
         GRPPHA> SYSTEMATICS SYSFILE.DAT
              The  information  regarding  the   fractional   systematic 
              errors   is   read   (free-format)   from  the  data  file 
              "SYSFILE.DAT". This  file  is  in  ASCII  format  and  can
              consist  of  up  to 100 lines (sets of channel ranges, one
              per line) with the syntax MINCHAN MAXCHAN ERR where  these
              have the same meanings as above.
              
    5) SHOW (or show)
         Displays  the  current  settings  to  the  screen  in a concise
         format.
         
         GRPPHA> SHOW GROUPING
              Displays the current channel GROUPING cards to the screen.
              
         GRPPHA> SHOW QUALITY
              Displays current QUALITY flags to the screen.
              
         GRPPHA> SHOW SYSTEMATICS
              Displays  current  fractional  SYSTEMATIC  errors  to  the 
              screen.
              
         GRPPHA> SHOW ALL
              Displays  the  current  channel  GROUPING  cards,  QUALITY 
              flags and fractional SYSTEMATIC errors to the screen.
              
         GRPPHA> SHOW KEYWORDS
              Displays mandatory PHA keywords, and their current values.
              
         GRPPHA> SHOW INFILE
              Displays input filename.
              
         GRPPHA> SHOW CHKEYS
              Displays names of keywords  that  can  have  their  values
              changed.
              
              In  addition any of the CHKEY keywords can be displayed in
              full. An example is SHOW RESPFILE.
              
              
    6) RESET (or reset)
         Resets the current settings to 'null',  NOT  to  those  in  the
         original input file.
         
         GRPPHA> RESET GROUPING
              Reset  all  the  channel  GROUPING  flags to 1, that is to
              unbinned.  NOTE: The grouping is not reset to that of  the
              original file.
              
         GRPPHA> RESET QUALITY
              Reset  all  the  channel QUALITY flags to good (Qual = 0),
              regardless of the original setting.
              
         GRPPHA> RESET SYSTEMATICS
              Reset the fractional SYSTEMATIC errors to zero.
              
         GRPPHA> RESET ALL
              Reset all the channel GROUPING  card,  QUALITY  flags  and
              fractional SYSTEMATIC errors.
              
    7) CHKEY (or chkey)
         This  command  allows  a keyword value to be changed. Users are
         permitted  to  change  the  values  of  a  subsection  of   the 
         mandatory keywords.
         
         GRPPHA>CHKEY KEYWORD NEWVALUE
              
              The  value  of  KEYWORD is changed to NEWVALUE. NOTE : The
              maximum allowed length for a  number  is  20,  and  for  a
              character  string  (for  filenames) is 120. An example, is
              CHKEY AREASCAL 1.03.
              
    8) WRITE
         Writes an output file.
         
         GRPPHA> WRITE ABCD.PHA
              Writes a new PHA file called "ABCD.PHA" with  the  current
              settings,  and  including  copies  of any other extensions
              present within the original input PHA file.  This  command
              does  not  stop  the  task,  thus  settings can be altered
              further and subsequently written to another file.
              
         GRPPHA> WRITE !ABCD.PHA
              Writes a new PHA file called "ABCD.PHA" with  the  current
              setting,  the  ! indicates that if ABCD.PHA already exists
              it is OVERWRITTEN.
              
    9) EXIT
         Exits the task.
         
         GRPPHA> EXIT
              Exit the task, first writing a new PHA file with the  name
              as  specified  by  the  input  parameter  outfile (default
              "GRPPHA.OUT")  with  the  final  settings,  and  including 
              copies   of   any  other  extensions  present  within  the 
              original input PHA file.
              
         GRPPHA> EXIT !ABCD.PHA
              Exit the task,  first  writing  a  new  PHA  file,  the  !
              indicates   that   if   ABCD.PHA  already  exists,  it  is 
              OVERWRITTEN. This filename overrides the  input  parameter
              outfile.
              
    10) QUIT
         Quits from the task
         
         GRPPHA> QUIT
              Exit the task without writing a new PHA file.
              
    11) HELP
         Interactive  help,  lists available commands. "?" or "commands"
         will  also  give  this  help.  For  interactive  help   for   a 
         particular  command,  "HELP  COMMAND"  will give a description,
         and  the  syntax,  for  example  "HELP  GROUP"  describes   the 
         grouping facility.
         

WARNINGS ON USAGE
    
       When  the grouping command, "group MINCHAN MAXCHAN NCHAN" is used
    if an overlap occurs with a previous setting, the data  is  rebinned
    after  the overlap if applicable. If the user wants to overwrite the
    original setting the reset  command  should  be  used.  Note  :  The
    "group min" command does not check for any overlaps.
    
       When  using  files with the bad and good commands, filenames with
    hyphens are not permitted.
    
       The CHKEY command has been updated  to  allow  a  maximum  string
    length  of 120. In order to do this a fitsio continuation convention
    is used.  NOTE: This may cause problems if downstream  software  has
    not been appropriately modified.
    
    
    
PARAMETERS
    
    infile [character]
         The  input  filename  containing the PHA data in OGIP standard,
        as a BINARY  table FITS extension
    
    outfile [character]
         The name of the output file to be  created  (in  OGIP  standard
        format). The  default output file is GRPPHA.OUT
    
    comm [character]
         The command string at the first prompt.
    
    tempc [character]
         The command string starting from the second prompt.
    
    chatter [integer]
         The  value  of  the  chatter  flag,  useful  for  reassurance &
        diagnostics  purposes. The  default  value  is  chatter=5,  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.
    
    
EXAMPLES
    
    1)  To  manipulate  the  PHA  file  "my_file.pha"  ,  and  write  to 
    "my_file.grp" with the changes if any, and default chattiness :
              he> grppha my_file.pha myfile.grp
         Now the PHA extension mandatory keywords, and  values  will  be
         displayed  on  the  screen.  The  GRPPHA prompt will appear. An
         example command is "group MINCHAN MAXCHAN  NCHAN  ",  the  data
         would   be   rebinned   from  MINCHAN  to  MAXCHAN  with  NCHAN 
         specifying the number of bins to be grouped :
              grppha> group 1 400 10
         This command will group 1 to 400 with 10 bins  in  each  group.
         To show the current grouping :
              grppha> show grouping
         EXIT  can  be  used to write a new file with the rebinned data.
         Note :  in  addition  to  the  SPECTRUM  extension,  all  other
         extensions in the input file are copied :
              grppha> exit
    
    
    2)  To  use "test.pha" as input PHA file, and use the default output
    file, with default chattiness (quiet) :
              he> grppha test.pha
         To add a systematic error to channels 40 to 56 :
              grppha> systematics 40-56 0.03
         A 3% systematic error is added. Now to set bad  channels,  that
         is these channels will be ignored in XSPEC :
              grppha> bad 11 20-40
         This  command sets channel 11 to bad, and channels 20 to 40 bad
         inclusively. In order to see the current  grouping,  systematic
         errors, and quality settings :
              grppha> show all
         To exit the program without writing to a file :
              grppha> quit
    
    3)  To  use  "bbxrt.pha"  as  input  file, and "bbxrt.grp",as output
    filename, with verbose chattiness :
              he> grppha bbxrt.pha bbxrt.grp 20
         To group the data with at least 30 raw counts in each bin :
              grppha> group min 30
         The current changes can be written to a file,  without  exiting
         grppha :
              grppha> write bbxrt30.grp
         The  reset command can be used to set all the data as unbinned.
         After this the data can be rebinned afresh. To reset :
              grppha> reset grouping
         To set bad channels by defining them in a file :
              grppha> bad badfile.dat
         To exit, and write a new PHA file :
              grppha> exit
    
    
    
BUGS
    None known
    
    
SEE ALSO
     Chanpha (xspec)  Legacy No.2  cal/sw/93-010
    
    
    
LOG OF SIGNIFICANT CHANGES
    
    
    v1.0.9 (1994 Jan)
           GRPPHA can be  run  in  non-interactive  mode  by  separating
        commands  with  an  ampersand "&". It is now spawned by Xselect.
         image
    
    v1.0.0 (1993 March)
            Initial public release
    
    
    
PRIMARY AUTHOR
    
    Rehana Yusaf
    HEASARC
    NASA/GSFC
    http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp
    (301) 286-6115