grppha2 HEADAS help file

NAME

grppha2 -- Manipulates OGIP standard TYPEII PHA FITS file. Both input and output files are of TYPEII PHA.

USAGE

         grppha2 infile outfile

or

         grppha2 infile outfile respfile=resp ancrfile=ancr

or

         grppha2 infile.pha outfile.pha respfile=@resp ancrfile=@ancr

DESCRIPTION

GRPPHA2 is a tool to define or redefine the grouping (binning) & quality flags, and the fractional systematic errors associated with channels in a FITS PHA file. A new typeII FITS PHA file is written which includes the latest settings. 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 (i.e., 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 GRPPHA2 commands and downstream software (eg XSPEC). The commands are case insensitive and are provided either on the command line, or in an ascii file. In the former case, the commands need to be separated by a comma, while in the latter case, the file name must be preceeded by "@" sign. See examples below. A maximum of 50 commands can be given in a file. NOTE: at the prompts for the spectra numbers and the command the user can obtain help by typing "help" or "?".

Option provided for user to choose respfile and ancrfile column for output file as hidden parameter. Otherwise specifically mentioned in the command line, those columns will be used as in input file.

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) quit or q   - to quit/exit the task
         6) exit or x   - to quit/exit the task
         7) help or ?   - interactive help

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:

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 pre-existing grouping will also be ignored and the user informed.

                     e.g.: group 10 20 2

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.

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 the software (QUALITY=2).

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

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:

BAD MINCHAN MAXCHAN

Channels between MINCHAN and MAXCHAN (inclusive) are set bad (Quality = 5).

                             e.g.: bad  5 20

will set the quality flag such that channels 5 through 20 are defined to be bad.

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 50 lines (sets of channel ranges, one per line) with the syntax MINCHAN MAXCHAN where these have the same meanings as above.

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:

GOOD MINCHAN MAXCHAN

Channels between MINCHAN and MAXCHAN (inclusive) are set good should they not be so already.

                     e.g.: good  6 18

will set the quality flag such that channels 6 through 18 are defined to be good.

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 50 lines (sets of channel ranges, one per line) with the syntax MINCHAN MAXCHAN where these have the same meanings as above.

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:

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

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 50 lines (sets of channel ranges, one per line) with the syntax MINCHAN MAXCHAN ERR where these have the same meanings as above.

5) QUIT or Q

Quits from the task without performing any command.. Same as Exit

6) EXIT or X

Exits the task without performing any command Same as Quit

7) HELP or ?

Interactive help, lists available commands. 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 and an overlap occurs with a previous setting, the data is rebinned after the overlap if applicable. Note: The "group min" command does not check for any overlaps.

PARAMETERS

infile [character]: The input filename containing the TYPEII 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) containing TYPEII PHA data.
spectra_num [character]: The range of spectra (rows) to be input. The default of "-" means all rows. The first ten rows could be specified as "1-10" or just "-10". To input the first ten rows and all rows from 100 through the last (inclusive), use "1-10,100-". An input of "1,3,7,23" will do only those four rows."
command [character]: The command string at the prompt. If string starts with "@" then it reads the ascii file following the @ sign. "help" displays help on available commands. "help group" displays help on group command.
respfile [character][hidden]: The root name of the response file column to be written. This is a hidden parameter and need to be provided at the command line. If this parameter is provided by the user as respfile=root, then the respfile column of the output file contains filenames with "root_rowid[i].rmf" Another way to use response file is if user uses respfile=@resp. In this case, the response file names for output file are read from the ascii file "resp".
ancrfile [character][hidden]: The root name of the ancr file column to be written. This is a hidden parameter and need to be provided at the command line. If this parameter is provided by the user as ancrfile=root, then the ancrfile column of the output file contains filenames with "root_rowid[i].arf" Another way to use ancronse file is if user uses ancrfile=@ancr. In this case, the ancr file names for output file are read from the ascii file "ancr".
(chatter = 5) [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

To manipulate the PHA file "infile.pha", and write to "outfile.pha" with the grouping commands,:

               grppha2 infile.pha outfile.pha
     
               grppha2 infile.pha outfile.pha respfile=root1 ancrfile=root2
     
               grppha2 infile.pha outfile.pha respfile=@resp ancrfile=@ancr

BUGS

None known

LOG OF SIGNIFICANT CHANGES

         v1.0.0 (1999 May)
                 Initial public release
         v2.0.0 (1999 June)
                 Provided option to use respfile and ancrfile names in the
                 command line.
         v3.0.0 (2002 Oct)
                 fixed bug

PRIMARY AUTHOR

Banashree M Seifert

MODIFIED BY

Chunhui Pan